joelmaison/afriball-rag

RAG system for African basketball Q&A — FastAPI backend, Qdrant vector DB, Docker, CI/CD. Benchmarks 5 retriever/generator combinations (GPT-4o-mini, FLAN-T5, Azure/local embeddings). # Basketball in Africa — RAG System A Retrieval-Augmented Generation service that answers questions about basketball in Africa (the Basketball Africa League, FIBA Africa, and African players in the NBA), benchmarked across five retriever/generator combinations and served through a FastAPI backend backed by a Qdrant vector database. **Author:** Joel Maison (github.com) · **Live demo:** Streamlit app --- ## Architecture ``` ┌─────────────────────┐ HTTP request ───▶ │ FastAPI (src/api.py)│ └──────────┬──────────┘ │ ┌──────────────┴──────────────┐ ▼ ▼ ┌───────────────────────┐ ┌───────────────────────┐ │ Retriever │ │ Generator │ │ • Qdrant (vector DB) │ │ • GPT-4o-mini (API) │ │ • Sentence-BERT (local)│ │ • FLAN-T5-base (local) │ │ • Azure embeddings │ └───────────────────────┘ └───────────┬────────────┘ ▼ ┌───────────────────────┐ │ Qdrant vector store │ │ (Docker / in-memory) │ └───────────────────────┘ ``` The retriever fetches the top-k relevant documents from a 53-document corpus on African basketball, the generator answers the question conditioned on that context, and the whole pipeline is swappable per request (`retriever` / `generator` fields in the API call) so different architectures can be benchmarked live. --- ## Quickstart ### Run with Docker (recommended — spins up Qdrant + the API together) ```bash cp .env.example .env # add your LLM API key docker compose up --build ``` The API is now live at `localhost`, backed by a real Qdrant instance. ```bash curl -X POST localhost \ -H "Content-Type: application/json" \ -d '{"question": "What is the Basketball Africa League?", "retriever": "qdrant", "generator": "gpt4omini"}' ``` ### Run locally without Docker ```bash make install export RAG_API_KEY="your-api-key" # any OpenAI-compatible endpoint make run-api # localhost …