chatbi-mvp

ChatBI MVP Architecture

Overview

Build a ChatBI system: user asks questions in natural language → system generates SQL → executes → displays interactive charts with AI insights.

Architecture: NL → S2SQL (semantic SQL / MQL) → Physical SQL. LLM generates S2SQL using business terms (bizName), a deterministic Translator converts to physical SQL. LLM never touches physical table/column names.

Tech stack assumed: React (frontend) + Python/FastAPI (backend). Architecture is language-agnostic.

Five Core Layers

User: "最近7天各分区播放量怎么样"
         │
         ▼
┌─ Layer 3: RAG ────────────────┐  Trie + Embedding recall
│  "播放量" → views (metric)     │  Identify schema elements
│  "分区"   → category (dim)     │  in user query
│  "最近7天" → DateConf{-7d}     │
└───────────────┬───────────────┘
                │
                ▼
┌─ Layer 1: NL → S2SQL → SQL ──┐  5-stage pipeline
│  MAPPING → PARSING →          │  LLM generates S2SQL (bizName)
│  CORRECTING → TRANSLATING     │  Translator → physical SQL
│  → EXECUTE                    │
└───────────────┬───────────────┘
                │
        ┌───────┴───────┐
        ▼               ▼
┌─ Layer 2 ───┐  ┌─ Layer 5 ──────────┐
│ Multi-turn   │  │ Attribution         │
│ Context save │  │ LLM summary + YoY   │
│ + LLM rewrite│  │ + drill-down recs   │
└──────────────┘  └─────────────────────┘
        │               │
        └───────┬───────┘
                ▼
┌─ Layer 4: Visualization ──────┐
│  Auto chart type → ECharts    │
│  User can toggle chart/table  │
│  Drill-down → re-query        │
└───────────────────────────────┘

File Index

This skill is split into focused files. Read in order, or jump to what you need.

Core Architecture (read first)

File	Contents	When to read
data-models.md	All shared POJOs: SemanticSchema, SchemaMapInfo, SemanticParseInfo, QueryResult	Always start here — these connect every layer
nl2sql-pipeline.md	Layer 1 in detail: 5-stage pipeline, prompt template, self-consistency, corrector chain, S2SQL→physical translator	Core of the system
wiring.md	How all layers connect: full request flow, plugin registration, DB tables	When you need to see the big picture