---
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.