Election Analytics Chatbot

A stateful, graph-based chatbot for election data analysis, built with LangGraph, FastAPI, and React.

🚀 Features

• Intelligent Query Analysis: Automatically determines if a query needs data analysis, web research, or clarification.
• Automated Data Analysis: Generates and executes Python code to analyze election datasets and produce visualizations.
• Web Research: Integrates web search capabilities for general election-related questions.
• Stateful Conversations: Maintains context across multiple turns using LangGraph's persistent checkpointing.
• Real-time Streaming: Streams reasoning steps, code execution outputs, and plots to the UI.
• Secure Authentication: Traditional login and OIDC/SSO support with HttpOnly cookies.
• History Management: Persistent storage and management of chat history and generated artifacts.

🏗️ Project Structure

• backend/: Python FastAPI application using LangGraph.
• frontend/: React SPA built with TypeScript, Vite, and Tailwind CSS.

🛠️ Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL
• Docker (optional, for Postgres/PgAdmin)
• API Keys: OpenAI/Google Gemini, Google Search (if using research tools).

📥 Getting Started

Backend Setup

1. Navigate to the backend directory:

   cd backend
   

2. Install dependencies:

   uv sync
   

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration and API keys
   

4. Run database migrations:

   uv run alembic upgrade head
   

5. Start the server:

   uv run python -m ea_chatbot.api.main
   

Frontend Setup

1. Navigate to the frontend directory:

   cd frontend
   

2. Install dependencies:

   npm install
   

3. Start the development server:

   npm run dev
   

📖 Documentation

• Top-level GEMINI.md: General project overview.
• Backend Guide: Detailed backend architecture and implementation details.
• Frontend Guide: Frontend development guide and technology stack.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.