How s84v/ai-sql-analyst works
OlistIQ lets a user ask natural-language questions about the Olist dataset and receive a streamed, evidence-based answer. The main workflow runs from the React interface through the HTTP event stream to a LangGraph agent, which inspects schema and executes read-only SQL before generating an answer rendered as Markdown. A separate ingestion path loads Olist CSVs into PostgreSQL. The graph reflects shown imports and documented protocol boundaries; backend API wiring is supported by the source index, while unsampled implementation details are not inferred.
Main entry points: api.py HTTP API · App.tsx Question UI · tools.py Agent tools · api.ts SSE client
Components 17
User interface
- Question UI
frontend/src/App.tsx - SSE client
frontend/src/api.ts - Answer reveal
frontend/src/AnswerReveal.tsx - Markdown renderer
frontend/src/MarkdownAnswer.tsx
Query transport
- HTTP API
backend/src/ai_sql_analyst/api.py - Event translator
backend/src/ai_sql_analyst/streaming.py
Analysis agent
- Tool-calling agent
backend/src/ai_sql_analyst/agent.py - DeepSeek model
backend/src/ai_sql_analyst/model.py - Agent tools
backend/src/ai_sql_analyst/tools.py
Data and SQL
- Schema introspection
backend/src/ai_sql_analyst/schema.py - Read-only SQL
backend/src/ai_sql_analyst/query.py - DB connection
backend/src/ai_sql_analyst/db.py - PostgreSQL
backend/sql/schema.sql - CSV ingestion
backend/src/ai_sql_analyst/ingest.py
Other components
- Analyst
- Olist CSV files
data/raw - DeepSeek API
Connections 18
- Analyst → Question UI: asks question
frontend/src/App.tsx - Question UI → SSE client: streams question
frontend/src/App.tsx - SSE client → HTTP API: POSTs query
frontend/src/api.ts - HTTP API → SSE client: streams events
frontend/src/api.ts - Question UI → Answer reveal: shows answer
frontend/src/App.tsx - Answer reveal → Markdown renderer: renders markdown
frontend/src/AnswerReveal.tsx - HTTP API → DeepSeek model: builds model
backend/src/ai_sql_analyst/api.py - HTTP API → Tool-calling agent: runs agent
backend/src/ai_sql_analyst/api.py - HTTP API → Event translator: translates events
backend/src/ai_sql_analyst/api.py - DeepSeek model → DeepSeek API: calls provider
- Tool-calling agent → Agent tools: dispatches tools
backend/src/ai_sql_analyst/agent.py - Agent tools → Schema introspection: gets schema
backend/src/ai_sql_analyst/tools.py - Agent tools → Read-only SQL: runs SQL
backend/src/ai_sql_analyst/tools.py - Schema introspection → DB connection: connects via
backend/src/ai_sql_analyst/schema.py - Read-only SQL → DB connection: connects via
backend/src/ai_sql_analyst/query.py - DB connection → PostgreSQL: opens connection
backend/src/ai_sql_analyst/db.py - CSV ingestion → Olist CSV files: reads CSVs
backend/src/ai_sql_analyst/ingest.py - CSV ingestion → PostgreSQL: loads tables
backend/src/ai_sql_analyst/ingest.py