Adaptive Iterative Retrieval-Augmented Generation System

* UC IRVINE COMPSCI 256 COURSE PROJECT

An implementation of intent-aware and self-refining RAG System with FastAPI + React.

This is a complete Retrieval-Augmented Generation (RAG) template with:

• FastAPI backend: upload, ingestion (parse → chunk → embed → index), retrieval, chat.
• Local FAISS vector store.
• OpenAI-compatible LLM/Embeddings via API.
• React (Vite) frontend for uploading files and chatting.

1. Prerequisites

• Python 3.11+
• Node.js 18+

2. Setup

1) Backend

cd ...
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
cp env.example .env  # fill your keys

Run the server:

uvicorn backend.main:app --host 0.0.0.0 --port 8001 --reload

2) Frontend

cd .../frontend
npm install
npm run dev

Open http://localhost:5173

3. How to Use

1. Upload your files (PDF, DOCX, TXT, MD, HTML).
2. Click "Ingest" to parse, chunk, embed, and index to FAISS.
3. Ask questions in Chat. The model answers with retrieved context.

4. Configuration

Set in .env (see env.example):

• HOST, PORT
• ALLOWED_ORIGINS (frontend URL)
• LLM_PROVIDER=openai
• OPENAI_API_KEY (required)
• OPENAI_BASE_URL (default: https://api.openai.com/v1)
• OPENAI_CHAT_MODEL (default: gpt-4o-mini)
• OPENAI_EMBEDDING_MODEL (default: text-embedding-3-small)
• VECTOR_INDEX_DIR, CHUNK_SIZE, CHUNK_OVERLAP

LLM full setup (OpenAI-compatible)

1. Create .env from example and fill your key:

cp env.example .env

Edit .env:

OPENAI_API_KEY=sk-...
# Optional overrides
# OPENAI_BASE_URL=https://api.openai.com/v1
# OPENAI_CHAT_MODEL=gpt-4o-mini
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small

2. Start backend and verify diagnostics:

uvicorn backend.main:app --host 0.0.0.0 --port 8001 --reload

Open in browser:

http://localhost:8001/api/llm/check

You should see embedding_ok: true and chat_ok: true. If not, the JSON includes error messages for troubleshooting (e.g., invalid API key).

5. Notes

• Default provider is OpenAI. Swap models/URL for Azure/OpenAI-compatible endpoints.
• FAISS index stored at data/index.

6. Security

• This template is for local development. Add auth, rate limiting, and content validation before production.