70 lines
3.7 KiB
Markdown
70 lines
3.7 KiB
Markdown
# Election Analytics Chatbot - Backend Guide
|
|
|
|
## Overview
|
|
The backend is a Python-based FastAPI application that leverages **LangGraph** to provide a stateful, hierarchical multi-agent workflow for election data analysis. It handles complex queries using an Orchestrator-Workers pattern, decomposing tasks and delegating them to specialized subgraphs (Data Analyst, Researcher) with built-in reflection and error recovery.
|
|
|
|
## 1. Architecture Overview
|
|
- **Framework**: LangGraph for hierarchical workflow orchestration and state management.
|
|
- **API**: FastAPI for providing REST and streaming (SSE) endpoints.
|
|
- **State Management**: Persistent state using LangGraph's `StateGraph` with a PostgreSQL checkpointer. Maintains global state (`AgentState`) and isolated worker states (`WorkerState`).
|
|
- **Virtual File System (VFS)**: An in-memory abstraction passed between nodes to manage intermediate artifacts (scripts, CSVs, charts) without bloating the context window.
|
|
- **Database**: PostgreSQL.
|
|
- Application data: Uses `users` table for local and OIDC users (String IDs).
|
|
- History: Persists chat history and artifacts.
|
|
- Election Data: Structured datasets for analysis.
|
|
|
|
## 2. Core Components
|
|
|
|
### 2.1. State Management (`src/ea_chatbot/graph/state.py` & `workers/*/state.py`)
|
|
- **Global State**: Tracks the conversation context, the high-level task `checklist`, execution progress (`current_step`), and the VFS.
|
|
- **Worker State**: Isolated snapshot for specialized subgraphs, tracking internal retry loops (`iterations`), worker-specific prompts, and raw results.
|
|
|
|
### 2.2. The Orchestrator
|
|
Located in `src/ea_chatbot/graph/nodes/`:
|
|
|
|
- **`query_analyzer`**: Analyzes the user query to determine the intent and required data. If ambiguous, routes to `clarification`.
|
|
- **`planner`**: Decomposes the user request into a strategic `checklist` of sub-tasks assigned to specific workers.
|
|
- **`delegate`**: The traffic controller. Routes the current task to the appropriate worker and enforces a strict retry budget to prevent infinite loops.
|
|
- **`reflector`**: The quality control node. Evaluates a worker's summary against the sub-task requirements. Can trigger a retry if unsatisfied.
|
|
- **`synthesizer`**: Aggregates all worker results into a final, cohesive response for the user.
|
|
- **`clarification`**: Asks the user for more information if the query is critically ambiguous.
|
|
|
|
### 2.3. Specialized Workers (Sub-Graphs)
|
|
Located in `src/ea_chatbot/graph/workers/`:
|
|
|
|
- **`data_analyst`**: Generates Python/SQL code, executes it securely, and captures dataframes/plots. Contains an internal retry loop (`coder` -> `executor` -> error check -> `coder`).
|
|
- **`researcher`**: Performs web searches for general election information and synthesizes factual findings.
|
|
|
|
### 2.4. The Workflow
|
|
The global graph connects the Orchestrator nodes, wrapping the Worker subgraphs as self-contained nodes with mapped inputs and outputs.
|
|
|
|
## 3. Key Modules
|
|
|
|
- **`src/ea_chatbot/api/`**: Contains FastAPI routers for authentication, conversation management, and the agent streaming endpoint.
|
|
- **`src/ea_chatbot/graph/`**: Core LangGraph logic, including state definitions, node implementations, and the workflow graph.
|
|
- **`src/ea_chatbot/history/`**: Manages persistent chat history and message mapping between application models and LangGraph state.
|
|
- **`src/ea_chatbot/utils/`**: Utility functions for database inspection, LLM factory, and logging.
|
|
|
|
## 4. Development & Execution
|
|
|
|
### Entry Point
|
|
The main entry point for the API is `src/ea_chatbot/api/main.py`.
|
|
|
|
### Running the API
|
|
```bash
|
|
cd backend
|
|
uv run python -m ea_chatbot.api.main
|
|
```
|
|
|
|
### Database Migrations
|
|
Handled by Alembic.
|
|
```bash
|
|
uv run alembic upgrade head
|
|
```
|
|
|
|
### Testing
|
|
Tests are located in the `tests/` directory and use `pytest`.
|
|
```bash
|
|
uv run pytest
|
|
```
|