Insurance Prior Auth Chat Agent

A conversational AI agent that helps call center agents navigate insurance verification processes using RAG (Retrieval-Augmented Generation) on uploaded insurance documents.

Features

• Conversational Interface: User-friendly chat interface for lay users
• Threaded Conversations: Support for multiple conversation threads
• Conversation Memory: Maintains context throughout conversations
• Plan Context Awareness: Always tracks which insurance plan is being discussed
• RAG on Documents: Performs retrieval-augmented generation on uploaded insurance documents
• Intelligent Chunking: Document chunking that preserves policy/plan context

Tech Stack

• Backend: FastAPI (Python)
• Frontend: Next.js (React)
• LLM: OpenAI (GPT-4, embeddings)
• Vector Database: Chroma (can be swapped for Pinecone, Qdrant, etc.)
• Document Processing: LangChain, PyPDF2, python-docx

Project Structure

.
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── api/           # API routes
│   │   ├── core/          # Core configuration
│   │   ├── models/        # Database models
│   │   ├── services/      # Business logic
│   │   │   ├── rag.py    # RAG service
│   │   │   ├── document_processor.py  # Document chunking
│   │   │   └── conversation_manager.py  # Thread & memory management
│   │   └── main.py        # FastAPI app entry point
│   ├── requirements.txt
│   └── .env.example
├── frontend/               # Next.js frontend
│   ├── app/               # Next.js app directory
│   ├── components/        # React components
│   ├── lib/               # Utilities
│   └── package.json
└── README.md

Quick Start

Having trouble getting started? Check out the detailed SETUP.md guide or use the automated startup scripts:

# Check your setup first
./check-setup.sh

# Start backend (in one terminal)
./start-backend.sh

# Start frontend (in another terminal)
./start-frontend.sh

Note: If the scripts aren't executable, run chmod +x *.sh first.

Setup

Backend Setup

1. Navigate to backend directory:

cd backend

2. Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Copy .env.example to .env and fill in your OpenAI API key:

cp .env.example .env

5. Initialize database:

python -c "from app.core.database import Base, engine; Base.metadata.create_all(bind=engine)"

6. Run the backend:

uvicorn app.main:app --reload

Frontend Setup

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Create .env.local (optional):

NEXT_PUBLIC_API_URL=http://localhost:8000

4. Run the frontend:

npm run dev

Environment Variables

Backend (.env)

• OPENAI_API_KEY: Your OpenAI API key
• DATABASE_URL: Database connection string (for conversation storage)
• VECTOR_DB_PATH: Path for Chroma vector database
• MAX_CHUNK_SIZE: Maximum chunk size for document processing
• CHUNK_OVERLAP: Overlap between chunks

Key Design Decisions

Plan Context Tracking

• Each conversation thread is associated with a specific insurance plan
• Plan context is maintained throughout the conversation
• Document chunks are tagged with plan identifiers
• RAG retrieval filters by plan context

Document Chunking Strategy

• Semantic chunking that preserves policy/plan context
• Chunks include metadata: plan_id, section, page numbers
• Overlapping chunks to maintain context boundaries
• Special handling for tables and structured data

Conversation Memory

• Short-term: Last N messages in conversation
• Long-term: Summarized conversation history
• Plan context: Always included in system prompts

API Endpoints

• POST /api/conversations - Create new conversation thread
• GET /api/conversations/{thread_id} - Get conversation history
• POST /api/conversations/{thread_id}/messages - Send message
• POST /api/documents/upload - Upload insurance documents
• GET /api/documents - List uploaded documents
• DELETE /api/documents/{doc_id} - Delete document
• POST /api/chat/message - Send chat message and get AI response

Development

See individual README files in backend/ and frontend/ directories for more details.