Backend API for Reporium — the AI-native GitHub knowledge graph. Handles all data reads and writes, semantic search, 8-dimension dynamic taxonomy, portfolio intelligence, and a queryable MCP interface for Claude.

Public reads. Protected writes (X-Ingest-Key). Admin operations (X-Admin-Key).

docker-compose up

API: http://localhost:8000 Docs: http://localhost:8000/docs

cp .env.example .env
# Edit .env with your values

pip install -r requirements.txt

# Run migrations
alembic upgrade head

# Start server
uvicorn app.main:app --reload

Secrets are resolved from GCP Secret Manager in production (no .env needed on Cloud Run).

GET /graph/edges serves from the published graph snapshot artifact before attempting live database queries so the graph UI remains available during primary DB incidents.

Both headers are optional when the env var is unset (dev-safe passthrough). In production, set both in Cloud Run environment variables or GCP Secret Manager.

Taxonomy is fully data-driven — no hardcoded lists. Values are generated freely by Claude during enrichment and grow automatically as new repos are added.

Zero-re-enrichment expansion: Adding a new taxonomy value costs one local embedding call (~$0.00001) and one SQL similarity query. Existing repos are matched automatically via pgvector — no Claude re-enrichment of any repo required.

• Embeddings: all-MiniLM-L6-v2 (384-dim), stored in repo_embeddings.embedding_vec
• Index: HNSW (vector_cosine_ops) for fast approximate nearest-neighbor
• Cosine similarity scores are returned in search results and repo detail responses
• Taxonomy assignment uses the same embeddings: 1 - (taxonomy_value.embedding_vec <=> repo.embedding_vec) >= 0.65

reporium-ingestion
  └─ publishes repo.ingested → GCP Pub/Sub topic: repo-ingested
                                    │
                              push subscription
                                    │
                                    ▼
reporium-api  POST /ingest/events/repo-ingested
  ├─ embed new taxonomy_values (sentence-transformers)
  ├─ assign taxonomy via cosine similarity
  └─ invalidate portfolio intelligence cache

Reporium exposes an MCP (Model Context Protocol) server via the separate reporium-mcp repo, giving Claude Code direct query access to the knowledge graph.

# Add to Claude Code
claude mcp add reporium -- python /path/to/reporium-mcp/mcp_server.py

10 tools available: search_repos, search_repos_semantic, get_repo, find_similar_repos, list_taxonomy_dimensions, list_taxonomy_values, get_repos_by_taxonomy, ask_portfolio, get_portfolio_gaps, get_ai_trends.

1. Create Cloud SQL PostgreSQL instance with pgvector extension enabled
2. Set DATABASE_URL=postgresql+asyncpg://[user]:[pass]@/[db]?host=/cloudsql/[connection-name]
3. Set ADMIN_API_KEY and INGEST_API_KEY in Cloud Run environment variables (or Secret Manager)
4. Build and push Docker image to Artifact Registry
5. Deploy to Cloud Run with the Cloud SQL connection
6. Run alembic upgrade head via Cloud Run Jobs or shell

pip install pytest pytest-asyncio httpx
pytest tests/