Spaces:
Sleeping
Sleeping
| title: Code Compass API | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: docker | |
| app_port: 7860 | |
| # Code Compass Backend | |
| FastAPI backend for Code Compass, a personal full-stack RAG project that indexes public GitHub repositories and answers questions with grounded source citations. | |
| ## What This Demonstrates | |
| - End-to-end AI application design, not just a prompt wrapper | |
| - Backend API design with FastAPI, Pydantic validation, and session-scoped state | |
| - Code-aware retrieval using tree-sitter chunking, vector search, BM25, rank fusion, and reranking | |
| - Grounded answer generation with file-level citations | |
| - Deployment-aware tradeoffs for cost, model choice, and free-tier infrastructure | |
| - Evaluation workflow prepared for retrieval and answer-quality metrics | |
| ## Backend Responsibilities | |
| - Clone a public GitHub repository into temporary storage | |
| - Filter and chunk source files for retrieval | |
| - Generate embeddings and store chunks in Chroma DB | |
| - Maintain lightweight repository and session metadata in memory | |
| - Run indexing as a background task | |
| - Retrieve evidence with semantic search, lexical search, fusion, and reranking | |
| - Generate answers from the selected context and return citations to the UI | |
| - Delete cloned repository files after indexing | |
| ## Runtime Configuration | |
| ### Local Development (higher-quality experimentation) | |
| - `LLM_PROVIDER=bedrock` with Claude 3.5 Sonnet | |
| - `EMBEDDING_PROVIDER=bedrock` with Cohere Embed v3 | |
| - Recommended: `AWS_REGION=us-east-1`, `BEDROCK_LLM_MODEL=anthropic.claude-3-5-sonnet-20240620-v1:0`, `BEDROCK_EMBEDDING_MODEL=cohere.embed-v3:0` | |
| ### Production (lower-cost hosting) | |
| - `LLM_PROVIDER=groq` with Llama 3.1 70B | |
| - `EMBEDDING_PROVIDER=local` with sentence-transformers/all-MiniLM-L6-v2 | |
| - Required: `GROQ_API_KEY` | |
| ## Chroma Storage | |
| The backend uses Chroma DB for vector storage in both local development and production. By default it stores the collection under `./data/chroma`, and you can point it somewhere else with `CHROMA_PATH`. | |
| Configuration: | |
| - `CHROMA_PATH=./data/chroma` | |
| - `CHROMA_COLLECTION=repo_qa_chunks` | |
| - `CHROMA_UPSERT_BATCH_SIZE=64` | |
| ## Metrics | |
| The evaluation harness reports 4 core metrics: | |
| - **Retrieval hit rate @ top-5**: Fraction of queries with at least one relevant source in top 5 results | |
| - **Top-1 hit rate**: Fraction of queries where the first result is relevant | |
| - **Grounded answer rate**: Fraction of answers that cite actual source code | |
| - **Faithfulness (RAGAS)**: LLM-as-judge score for answer consistency with retrieved context | |
| - **Query latency P95**: 95th percentile response time in milliseconds | |