E-Commerce Sales Analytics Chatbot & Pinnable Dashboard

An intelligent E-Commerce Sales Analytics Chatbot and Chart Builder with a Pinnable Dashboard built on the Brazilian E-Commerce Public Dataset by Olist (~100k real orders across 8 relational tables).

Features

• MCP Tool Architecture: Exposes analytics tools over Olist SQL dataset via the official Python mcp SDK (FastMCP).

• Dual LLM & Rule Fallback Agent (ILLMAgent): Switch seamlessly between LLM-backed native tool calling and keyword-based rule fallback using AGENT_MODE=llm|fallback.

• Chart Selector Engine: Recommends appropriate Chart.js charts (Line, Horizontal Bar, Donut, Dual-Axis, Scatter, Stacked Bar) with 1-sentence data insights and justifications.

• Pinnable Dashboard: Persistent dashboard pin board with refresh change/diff detection.

• Sample & Multi-Tool Queries: Full coverage of single-tool queries, joint multi-tool queries, and guardrail handling (out-of-bounds queries, empty results, tool timeouts).

Related MCP server: Sales MCP Server

Quick Start (Docker Compose)

1. Clone repository and set API key:

   cp .env.example .env
   # Add your GROQ_API_KEY (or OPENAI_API_KEY) in .env
   # Example: GROQ_API_KEY=gsk_...

2. Run with Docker Compose:

   docker compose up --build

3. Access Application: Open browser at http://localhost:8000.

Development Setup (uv)

1. Install dependencies:

   uv sync

2. Run database loader (automatic on startup or manual):

   uv run python -m src.database.loader

3. Start local server:

   uv run uvicorn src.main:app --reload --port 8000

4. Run tests:

   uv run pytest

Design Decisions

Chart Type Selection Logic

• Single metric over time: Line chart (line)

• Two metrics over same time axis: Dual-axis line chart (line with 2 y-axes)

• Ranked list (Top N): Horizontal bar chart (bar, indexAxis: 'y')

• Category comparison: Vertical bar chart (bar)

• Part-to-whole share: Donut chart (doughnut)

• Correlation: Scatter plot (scatter)

• Rating score distribution: Stacked horizontal bar chart

Refresh Diff Detection Engine

When a pinned chart is refreshed, the backend re-executes the original tool call against current dataset state, compares metrics against stored baseline values, and alerts if metric shifts exceed 5%.

Fallback Agent Behavior

When AGENT_MODE=fallback or LLM key is absent/timing out, RuleBasedFallbackAgent extracts date ranges, entity filters, and ranking keywords directly, queries MCP tools, and constructs Chart.js configs deterministically.