How sahilnegi4444/ai-analyst-agent works
1. High-level shape
- This repo is a two-part system: a FastAPI backend that serves an AI analyst API, and a React/Vite frontend that renders a conversational dashboard with charts.
- The backend is the real architecture center: it routes each user question through a LangGraph workflow that decides whether to use SQL, document retrieval, analytics calculations, or a hybrid path.
2. Primary request flow
- A user query enters through app/api/endpoints.py, which calls the backend workflow.
- Before invoking the agent, app/services/cache_service.py checks Redis using a normalized query key.
- On a cache miss, the request goes into app/agents/workflow.py, then to app/agents/router.py for intent classification, and finally to one or more tool nodes.
- The final response is returned to the API, cached, and sent back to the frontend.
3. Agent orchestration boundary
- app/agents/router.py is the intent classifier, powered by Groq LLMs in JSON mode.
- app/agents/workflow.py is the orchestration layer that chooses between SQL_QUERY, RAG_QUERY, HYBRID_QUERY, ANALYTICS_QUERY, or UNSUPPORTED_QUERY.
- This is the main control boundary of the backend: it separates natural-language understanding from actual data access and calculation.
4. Tool layer and execution safety
- The backend does not let the LLM directly touch storage; it must go through tools in app/tools/.
- sql_tool.py enforces read-only SQL and validates generated queries with a dry-run EXPLAIN, rolling back on failure.
- rag_tool.py performs semantic document retrieval over PostgreSQL pgvector.
- analytics_tool.py delegates numeric business calculations to the analytics service instead of letting the model do math.
5. Data sources and storage
- The system uses PostgreSQL as the main persistent store for structured data and vector search.
- SQLAlchemy models are defined in app/models/__init__.py, with session/engine wiring in app/database/__init__.py.
- Alembic is included for schema migration management.
- The repository also implies a document corpus under data/documents/, which is ingested into vectorized chunks for RAG.
6. Retrieval-augmented generation path
- Document search is backed by pgvector in PostgreSQL rather than a separate vector database.
- Embeddings are generated locally using Sentence Transformers via app/services/embedding.py, specifically the offline all-MiniLM-L6-v2 model.
- Retrieved passages are surfaced with source attribution and similarity confidence, which matters for how the frontend presents evidence.
7. Analytics path
- app/services/analytics_service.py handles deterministic business calculations such as growth rates, ratios, and distribution comparisons.
- This path is intentionally non-generative: the LLM may classify the request, but the actual math is done in Python/Pandas.
- That creates a separate execution boundary for precise analytical answers versus SQL results or document-grounded answers.
8. Caching and resilience
- app/services/cache_service.py provides Redis-backed query caching keyed by the normalized text of the question.
- The cache layer is fault-tolerant: if Redis is unavailable, it falls back to an in-memory thread-safe cache.
- Architecturally, this sits in front of the workflow so repeated queries can bypass both routing and generation.
9. Observability and traceability
- app/utils/logger.py writes execution traces to data/observability_runs.jsonl.
- Logged data includes the original query, intent classification, selected tools, generated SQL, status, and latency breakdown.
- This makes the system auditable and supports post-run analysis of agent behavior.
10. Frontend responsibilities
- The frontend in frontend/ is a Vite/React/TypeScript dashboard.
- App.tsx is the main UI entry point and likely handles query submission, response rendering, and chart selection.
- Based on the README, it also visualizes structured results using charting logic and exposes SQL/doc evidence in the UI.
11. Backend service composition
- app/schemas/ defines the request/response contracts used between API, workflow, and tools.
- app/repositories/ provides a repository abstraction over persistence, keeping database access separate from orchestration logic.
- app/config.py centralizes environment-driven configuration such as database, Redis, and Groq settings.
12. Offline and deployment concerns
- The repo is designed to run with containerization: Dockerfile and docker-compose.yml support multi-service deployment.
- The environment also assumes offline-friendly embedding behavior via HF_HUB_OFFLINE and TRANSFORMERS_OFFLINE.
- In practice, the external dependencies that materially shape the architecture are PostgreSQL, Redis, and Groq LLM endpoints.
13. Ingestion, validation, and lifecycle scripts
- scripts/ingest_all.py appears to populate tables and vector embeddings, making it the main data bootstrap path.
- scripts/verify_db.py, generate_documents.py, generate_dataset.py, and validate_dataset.py support data preparation and consistency checks.
- alembic/versions/ contains the initial schema migration, which indicates the database lifecycle is managed separately from runtime code.
14. Quality assurance and evaluation
- tests/test_agent.py covers routing, SQL safety, caching, and RAG behavior.
- app/evaluation/ contains a benchmark dataset and evaluator that produces data/evaluation_report.json.
- This suggests the repo treats agent quality as a first-class subsystem, not just application logic.
15. How to draw the architecture
- The most important boundaries to show are: frontend → API → cache → LangGraph workflow → tools → storage/services.
- Split the backend into three zones: orchestration (agents), execution (tools and services), and persistence (database, PostgreSQL, Redis, traces).
- Show the LLM as a control component for routing and generation, but keep actual SQL access, retrieval, and analytics in deterministic tool/service layers.
Main entry points: endpoints.py API Routes · workflow.py Workflow · config.py Config · cache_service.py Cache
Components 24
Frontend
React/Vite conversational dashboard
Backend
FastAPI app with agent orchestration and tools
- API Routes · Chat and analyst API endpoints
app/api/endpoints.py - App Entry · Backend application startup and wiring
app/main.py - Cache · Normalized query cache with fallback memory store
app/services/cache_service.py - Workflow · Agent orchestration and query path selection
app/agents/workflow.py - Router · Intent classification in JSON mode
app/agents/router.py - SQL Tool · Safe SQL execution with EXPLAIN validation
app/tools/sql_tool.py - RAG Tool · Document retrieval over pgvector
app/tools/rag_tool.py - Analytics Tool · Deterministic business calculations boundary
app/tools/analytics_tool.py - Embeddings · Offline sentence-transformer embeddings
app/services/embedding.py - Analytics Core · Numeric and distribution calculations
app/services/analytics_service.py - Config · Environment-driven settings for services
app/config.py - Contracts · Request and response schemas
app/schemas/chat.py
Data Layer
Persistence, ingestion, embeddings, and storage
Ops
Logging and evaluation
- Tracing · Execution traces and run history
app/utils/logger.py - Evaluation · Agent quality evaluation pipeline
app/evaluation/evaluator.py - Agent Tests · Focused coverage for routing, safety, cache, and RAG
tests/test_agent.py
Other components
- PostgreSQL · Structured storage and pgvector retrieval
- Redis · Primary cache backend
- Groq LLM · LLM provider for routing and generation
Connections 30
- Boot → UI Shell: mounts · Bootstraps the UI shell
- UI Shell → API Routes: queries · Submits user questions to the backend API
- App Entry → API Routes: serves · FastAPI application exposes the endpoints
- API Routes → Cache: check cache · Looks up normalized questions before agent execution
- Cache → API Routes: cache hit · Returns stored answer when available
- API Routes → Workflow: invoke · Hands cache misses to the agent workflow
- Workflow → Router: classify · Determines SQL, RAG, hybrid, analytics, or unsupported path
- Router → Groq LLM: uses · LLM-backed intent classification
- Workflow → SQL Tool: route · Executes structured-data questions
- Workflow → RAG Tool: route · Executes document-grounded questions
- Workflow → Analytics Tool: route · Executes deterministic calculations
- SQL Tool → Database: queries · Runs validated SQL through the database layer
- SQL Tool → Repos: abstracts · Uses repository boundaries for persistence access
- RAG Tool → Embeddings: embed · Creates vector representations for retrieval
- RAG Tool → PostgreSQL: vector search · Retrieves passages from pgvector storage
- Analytics Tool → Analytics Core: delegate · Pushes numeric business logic into deterministic code
- Analytics Core → PostgreSQL: reads data · Consumes stored structured data when needed
- Ingestion → Embeddings: build vectors · Generates embeddings during corpus bootstrap
- Ingestion → Database: load data · Populates persistent tables and indexes
- Database → Models: maps · Session and engine wiring target ORM models
- API Routes → Contracts: contracts · Uses shared request and response shapes
- Workflow → Tracing: trace · Logs intent, tools, latency, and status
- API Routes → Tracing: trace · Records request and response lifecycle
- Evaluation → Tracing: reports · Produces evaluation artifacts from run traces
- Agent Tests → Workflow: verifies · Covers routing and tool safety behavior
- API Routes → Cache: store answer · Caches successful responses for repeat queries
- Config → Cache: configures · Provides Redis and cache settings
- Config → Database: configures · Provides database settings
- Config → Workflow: configures · Provides model and runtime settings
- Config → Groq LLM: auth · Supplies LLM connection settings