# 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:
   ```bash
   cd backend
   ```
2. Install dependencies:
   ```bash
   uv sync
   ```
3. Set up environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your configuration and API keys
   ```
4. Run database migrations:
   ```bash
   uv run alembic upgrade head
   ```
5. Start the server:
   ```bash
   uv run python -m ea_chatbot.api.main
   ```

### Frontend Setup

1. Navigate to the frontend directory:
   ```bash
   cd frontend
   ```
2. Install dependencies:
   ```bash
   npm install
   ```
3. Start the development server:
   ```bash
   npm run dev
   ```

## 📖 Documentation

- **[Top-level GEMINI.md](./GEMINI.md)**: General project overview.
- **[Backend Guide](./backend/GEMINI.md)**: Detailed backend architecture and implementation details.
- **[Frontend Guide](./frontend/GEMINI.md)**: Frontend development guide and technology stack.

## 📜 License

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