b4f79ee052
- Update GEMINI.md with verification steps and remove ignored docs reference - Update README.md to remove reference to local langchain-docs - Update backend/GEMINI.md with correct database schema (users table) and architecture details - Update frontend/GEMINI.md with latest project structure
64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# Election Analytics Chatbot - Backend Guide
|
|
|
|
## Overview
|
|
The backend is a Python-based FastAPI application that leverages **LangGraph** to provide a stateful, agentic workflow for election data analysis. It handles complex queries by decomposing them into tasks such as data analysis, web research, or user clarification.
|
|
|
|
## 1. Architecture Overview
|
|
- **Framework**: LangGraph for 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.
|
|
- **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. The Graph State (`src/ea_chatbot/graph/state.py`)
|
|
The state tracks the conversation context, plan, generated code, execution results, and artifacts.
|
|
|
|
### 2.2. Nodes (The Actors)
|
|
Located in `src/ea_chatbot/graph/nodes/`:
|
|
|
|
- **`query_analyzer`**: Analyzes the user query to determine the intent and required data.
|
|
- **`planner`**: Creates a step-by-step plan for data analysis.
|
|
- **`coder`**: Generates Python code based on the plan and dataset metadata.
|
|
- **`executor`**: Safely executes the generated code and captures outputs (dataframes, plots).
|
|
- **`error_corrector`**: Fixes code if execution fails.
|
|
- **`researcher`**: Performs web searches for general election information.
|
|
- **`summarizer`**: Generates a natural language response based on the analysis results.
|
|
- **`clarification`**: Asks the user for more information if the query is ambiguous.
|
|
|
|
### 2.3. The Workflow (Graph)
|
|
The graph connects these nodes with conditional edges, allowing for iterative refinement and error correction.
|
|
|
|
## 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
|
|
```
|