Structured Answers
Responses can include insights, assumptions, limitations, chart metadata, tables, trace summaries, and a run identifier.
Local Demo
AI Analytics Agent
A local AI-powered analytics backend that answers natural-language questions about synthetic web analytics data using a controlled semantic layer, approved tools, and structured response generation.
Overview
A controlled analytics assistant for demo data
The AI Analytics Agent is built around a semantic layer and approved tool registry. Instead of allowing unrestricted text-to-SQL behavior, it maps natural-language questions to validated analytical workflows and returns structured responses for portfolio-ready analytics demos.
Local First
The backend runs separately during development and is reached only through a server-side Next.js proxy route.
Constrained by Design
The AI model does not receive unrestricted database access or permission to invent metrics outside the semantic layer.
How it works
Browser requests stay behind a portfolio proxy
The frontend never calls the FastAPI backend directly. The browser calls a Next.js route, and that server-side route adds any configured API key before forwarding the request.
01
The portfolio sends analytics questions to a server-side Next.js API route.
02
The proxy forwards validated requests to the local FastAPI backend.
03
A LangGraph workflow routes the question through approved analytical tools.
04
The semantic layer validates supported metrics, dimensions, thresholds, and tool mappings.
05
The data adapter reads from demo CSV data or PostgreSQL analytics views.
06
The API returns structured answers with insights, assumptions, limitations, chart metadata, tables, and trace summaries.
Safety model
Why it is not unrestricted text-to-SQL
Unlike a generic text-to-SQL chatbot, this agent uses a controlled semantic layer and approved tools to answer analytics questions safely. Natural-language questions are routed to validated analytical workflows instead of allowing unrestricted SQL generation.
SQL comes from allowlisted query files and stable analytics views. Metrics, dimensions, thresholds, guardrails, and tool mappings live in the semantic layer, reducing the risk of arbitrary SQL execution, raw schema leakage, hallucinated metric definitions, unsafe database access, and unsupported analytics questions.
Live local demo
Ask the agent about synthetic web analytics data
This demo expects the separate FastAPI backend to be running locally. The browser calls /api/ai-analytics-agent/query, and the server-side proxy forwards the question to /api/v1/agent/query.
Ask a question about the demo web analytics data. The browser sends the request to this Next.js app, and the server-side proxy forwards it to the local FastAPI agent.
MVP scope
- Settings and environment configuration
- Semantic layer loading
- Demo data support
- Allowlisted query files and analytics view SQL
- Controlled tool execution
- LangGraph-backed agent workflow
- Optional OpenAI-backed question routing and final answer drafting
- Deterministic fallback behavior
- Local trace persistence and optional LangSmith tracing
- Chart generation, API routes, and tests
Future improvements
- Production deployment with restricted public demo mode
- Chart rendering in the portfolio frontend
- More chart types beyond the current line-chart path
- Deeper test coverage
- Safer automated PostgreSQL adapter tests with mocks or fakes
- Expanded supported analytics questions
- Improved unsupported-question responses
- Better trace visualization
- Multiple datasets or demo scenarios