Files

Yunxiao Xu b4f79ee052 docs: update project documentation and verification strategies

- 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

2026-02-20 17:14:16 -08:00

2.7 KiB

Raw Blame History

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

cd backend
uv run python -m ea_chatbot.api.main

Database Migrations

Handled by Alembic.

uv run alembic upgrade head

Testing

Tests are located in the tests/ directory and use pytest.

uv run pytest

2.7 KiB Raw Blame History