Spaces:
Runtime error
Runtime error
| 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 Qdrant | |
| - Maintain lightweight repository and session metadata in SQLite | |
| - 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 is configured for higher-quality experimentation: | |
| - `LLM_PROVIDER=bedrock` | |
| - `EMBEDDING_PROVIDER=bedrock` | |
| - Claude on Amazon Bedrock for answer generation | |
| - Cohere Embed on Amazon Bedrock for semantic retrieval | |
| Production is configured for lower-cost hosting: | |
| - `LLM_PROVIDER=groq` | |
| - `EMBEDDING_PROVIDER=local` | |
| - Groq-hosted Llama for answer generation | |
| - Local sentence-transformer embeddings for retrieval | |
| - Qdrant Cloud for vector storage | |
| ## Qdrant Keepalive | |
| The backend starts a lightweight Qdrant keepalive scheduler when `QDRANT_URL` is configured. It calls the configured collection every 12 hours by default so a free-tier Qdrant cluster does not become inactive while the backend process is running. | |
| Configuration: | |
| - `QDRANT_URL` | |
| - `QDRANT_API_KEY` | |
| - `QDRANT_COLLECTION=repo_qa_chunks` | |
| - `QDRANT_KEEPALIVE_ENABLED=true` | |
| - `QDRANT_KEEPALIVE_INTERVAL_SECONDS=43200` | |
| The main repository also includes a GitHub Actions keepalive workflow for cases where the backend host is asleep. | |
| ## Metrics | |
| Metrics will be added after the next benchmark rerun. The evaluation harness is set up to report retrieval hit rate, top-1 hit rate, mean reciprocal rank, source recall, grounded answer rate, checklist pass rate, and optional RAGAS judge metrics. | |