Conversational Q&A System

Hybrid RAG system that answers questions using both persistent documents (PDFs) and a session-specific object list.

Architecture

• frontend/ React UI for login, object list input, and Q&A
• backend/ FastAPI API for auth + session + agent coordination
• agent/ FastAPI AI service with vector retrieval + hybrid reasoning (agentic mode + verification)

Quickstart (local)

1) Prepare documents

Copy PDFs into agent/data/documents/ or keep them in repo root.

Included example PDFs:

• AICI Challenge_ Conversational Q&A System.pdf
• 240213 Permitted Development Rights.pdf

2) Start the agent

cd agent
python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8001

The agent builds a FAISS index on first start and stores it in agent/data/index/. It also extracts PDF images into agent/data/documents/_images/ for future use.

3) Start the backend

cd backend
python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

4) Start the frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173.

Docker

docker compose up --build

Backend: http://localhost:8000
Agent: http://localhost:8001

Environment

Optional env vars:

• OPENAI_API_KEY for LLM synthesis and verification
• OPENAI_MODEL (default gpt-4o-mini)
• EMBEDDING_MODEL (default all-mpnet-base-v2)
• CHUNK_SIZE (default 900)
• CHUNK_OVERLAP (default 180)

API Overview

Auth

• POST /auth/register → {email,password} → JWT token
• POST /auth/login → {email,password} → JWT token

Session objects

• GET /session/objects → list
• PUT /session/objects → {objects:[...]} update list

Q&A

• POST /qa → {question, objects?, mode?} → hybrid answer
• WS /ws/qa → send {question, objects?, mode?} → receive answer
  • mode: agentic (default) or standard

Notes

• If OPENAI_API_KEY is set, the agent uses the model for synthesis and verification.
• If not, the agent returns a deterministic summary + heuristic verification.