AI-Powered Multi-Dimensional NPS Analysis and Insight Generation Platform

• Overview
• Key Features
• System Architecture
• Installation
• Usage
• Configuration
• API Documentation
• Troubleshooting
• Contributing
• License

The NPS Analytics RAG System is an AI-powered analysis platform with a Perplexity.ai-style real-time streaming interface for comprehensive Net Promoter Score (NPS) analysis. It leverages a multi-agent architecture to process natural language queries and generate actionable insights from multi-dimensional customer experience data.

• 🤖 4 Specialized AI Agents (SQL, Explanation, Visualization, Validation)
• ⚡ Real-time Streaming analysis results
• 🔍 Natural Language Query processing
• 📊 Interactive Visualizations with Plotly
• ✅ Automatic Validation and confidence scoring

Natural language queries are seamlessly translated to SQL and executed:

✅ "Show me NPS scores for the US market"
✅ "What's the product-wise NPS breakdown?"
✅ "Compare R-NPS competitive scores year-over-year"
✅ "Show customer journey NPS for TV products in 2024"

• Year-over-Year Gap Analysis: Track performance trends across time periods
• Competitive Gap Analysis: Benchmark against competitors
• Improvement Analysis: Identify trends and improvement opportunities
• Segmentation Analysis: Deep dive by customer demographics, products, and channels

🔍 SQL Agent      ████████████ 100%  ✅ Complete (2.1s)
🤖 Explanation    ████████████  85%  🔄 Analyzing gaps...
📈 Chart          ████░░░░░░░░  30%  🎨 Generating chart...
✅ Validation     ░░░░░░░░░░░░   0%  ⏳ Waiting

graph TD
    A[User Query] --> B[SQL Agent]
    B --> C[Explanation Agent]
    C --> D[Chart Agent]
    D --> E[Validation Agent]
    E --> F[Results Display]

    G[LangGraph Orchestrator] --> B
    G --> C
    G --> D
    G --> E

    H[Streamlit UI] --> A
    F --> H

Each agent extends the BaseAgent class which provides:

• Standardized execution lifecycle with timing and error handling
• Streaming update capabilities via StreamingUpdate class
• Common result structure (AgentResult) with confidence scoring
• Async execution pattern with AgentStatus enum
• Built-in timeout management and error recovery

• Python 3.8 or higher
• OpenAI API key
• 4GB RAM minimum
• 2GB disk space

git clone <repository-url>
cd nps-analytics-system

# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (Linux/Mac)
source venv/bin/activate

pip install -r requirements.txt

Create a .env file in the project root:

# Required
OPENAI_API_KEY=your_openai_api_key_here

# Optional
ANTHROPIC_API_KEY=your_anthropic_api_key_here
DATABASE_PATH=./data/database.sqlite
CSV_FILE_PATH=./data/nps_scorecard.csv
STREAMLIT_PORT=8501
DEBUG_MODE=false

# Prepare your CSV file in data/ folder
# Then initialize database
python data_manager.py

streamlit run streamlit_app.py

Access the application at http://localhost:8501

Type natural language questions:

"What's the NPS for the US market?"
"Compare TV segment NPS across brands"
"Show 2024 customer journey NPS trends"

Choose from 6 categories:

• Geographic Analysis: Regional market analysis
• Product Analysis: Product category breakdown
• Competitive Analysis: Brand comparison and gaps
• Trend Analysis: Time series analysis
• Customer Journey: CEJ stage analysis
• Segmentation: Demographics and channel analysis

Reuse or modify previous queries for quick analysis

• Agent-by-agent execution status with progress bars
• Streaming intermediate results for immediate feedback

1. 📊 Data: SQL query results and raw data tables
2. 💡 Insights: AI-generated analysis and key findings
3. 📈 Charts: Interactive Plotly visualizations
4. ✅ Validation: Confidence scores and data quality metrics

# API Keys (Required)
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=optional_key_here

# Database Configuration
DATABASE_PATH=./data/database.sqlite
CSV_FILE_PATH=./data/nps_scorecard.csv

# Server Configuration
STREAMLIT_PORT=8501
WEBSOCKET_PORT=8502

# Feature Flags
ENABLE_STREAMING=true
DEBUG_MODE=false
LOG_LEVEL=INFO

# Performance Tuning
MAX_CONCURRENT_AGENTS=4
AGENT_TIMEOUT=30
STREAM_BUFFER_SIZE=1024
MAX_CHART_POINTS=1000

# Model Configuration
DEFAULT_LLM_MODEL=gpt-4o
TEMPERATURE=0.1

# UI Configuration
CHART_THEME=plotly_white

CREATE TABLE nps_scorecard (
    id INTEGER PRIMARY KEY,
    year INTEGER,
    quarter TEXT,
    market VARCHAR(50),           -- Geographic market (US, Korea, Global)
    company VARCHAR(50),          -- Company/Brand name
    product_category VARCHAR(50), -- TV, Refrigerator, Washing Machine, etc.
    product_type VARCHAR(100),    -- Front Loader, OLED, etc.
    price_segment VARCHAR(20),    -- Premium, Mid-range, Budget
    cej_stage VARCHAR(50),        -- Customer journey stage
    channel VARCHAR(50),          -- Brand store, Online, etc.
    customer_age_group VARCHAR(20), -- Age demographics
    customer_gender VARCHAR(10),   -- Gender demographics
    nps_score DECIMAL(5,2),       -- NPS score
    r_nps_score DECIMAL(5,2),     -- Relationship NPS score
    sample_size INTEGER           -- Sample size
);

from orchestrator import StreamingOrchestrator

# Initialize orchestrator
orchestrator = StreamingOrchestrator()

# Execute with streaming
async for update in orchestrator.execute_workflow_stream(query):
    print(f"Agent: {update.agent_name}, Status: {update.status}")

# Execute without streaming
result = await orchestrator.execute_workflow(query)

from agents.sql_agent import SqlAgent
from agents.explanation_agent import ExplanationAgent

# SQL Agent
sql_agent = SqlAgent()
sql_result = await sql_agent.execute("Show US market NPS")

# Explanation Agent
explanation_agent = ExplanationAgent()
explanation_result = await explanation_agent.execute(sql_result)

from agents.base_agent import BaseAgent, AgentResult

class CustomAgent(BaseAgent):
    async def _execute_impl(self, query: str) -> AgentResult:
        # Emit progress updates
        await self.emit_progress("Processing...", 0.5)

        # Your logic here
        result = process_query(query)

        return AgentResult(
            agent_name=self.name,
            data=result,
            confidence_score=0.95,
            execution_time=time.time() - start_time
        )

❌ Error: OPENAI_API_KEY not set
✅ Solution: Configure API key in .env file

❌ Error: CSV file not found
✅ Solution: Place your CSV file in data/ folder or use sample data

# Use different port
streamlit run streamlit_app.py --server.port 8502

# Reduce resource usage in .env
MAX_CONCURRENT_AGENTS=2
STREAM_BUFFER_SIZE=512
MAX_CHART_POINTS=500

DEBUG_MODE=true
LOG_LEVEL=DEBUG

Check logs in logs/ directory for detailed error information.

# Limit concurrent agents
MAX_CONCURRENT_AGENTS=2

# Adjust streaming buffer
STREAM_BUFFER_SIZE=1024

# Limit chart data points
MAX_CHART_POINTS=500

# Install development dependencies
pip install -r requirements-dev.txt

# Code quality checks
black .
flake8 .
mypy .

# Unit tests
python -m pytest tests/

# Integration tests
python -m pytest tests/integration/

# Coverage report
pytest --cov=agents --cov-report=html

• Follow PEP 8 style guidelines
• Add docstrings to all public methods
• Write unit tests for new features
• Update documentation for API changes

This project is licensed under the MIT License - see the LICENSE file for details.

• Issue Reporting: GitHub Issues
• Feature Requests: GitHub Discussions
• Documentation: Project Wiki

• Built with LangChain and LangGraph
• UI powered by Streamlit
• Visualizations using Plotly
• AI models from OpenAI

NPS Analytics RAG System v1.0 🚀 Next-generation AI-powered customer experience analytics