GitHub - JoeCardoso13/brush-up-backend: FastAPI backend for brush-up-py deployed on Fly.io

Backend for Brush Up Python, Brush Up Ruby, and Brush Up JavaScript. A small AI-powered backend for tutors of Python, Ruby, and JavaScript built to showcase applied product and engineering work. You can read about its creation in my blog post.

The app answers programming questions by grounding model responses in a personal Zettelkasten-style knowledge base of interconnected markdown notes. This repository contains the backend API, retrieval pipeline, tutor prompt, and test suite.

What this does

• Serves a FastAPI chat API for the public brush-up frontend
• Builds one directed knowledge graph per language from markdown notes in notes/<language>/
• Retrieves the most relevant topic with a lightweight TF-IDF index
• Expands context with 1-hop graph neighbors before calling Anthropic
• Tracks per-user token usage in memory to limit abuse on the public demo

Architecture

Flow

1. A user asks a programming question from the frontend, scoped to a specific tutor (Python, Ruby, or JavaScript).
2. The backend scores the question against the note corpus with TF-IDF retrieval.
3. The top matching note becomes the primary topic.
4. The graph expands that topic with connected neighbor notes.
5. The backend builds a grounded system prompt from tutor_prompt.md plus the retrieved note context.
6. Anthropic generates the tutoring response.
7. The API returns the response, updated conversation history, and token usage metadata.

Main pieces

• src/api.py
  FastAPI app with /api/chat and /api/health, app startup lifecycle, CORS config, and API error handling.

• src/agent.py
  Retrieval-aware tutoring logic. Selects context, assembles the system prompt, calls Anthropic, and returns usage metadata.

• src/graph.py
  Builds a networkx.DiGraph from Obsidian-style [[wikilinks]], exposes 1-hop context gathering, and implements the TF-IDF search index.

• src/budget.py
  In-memory per-user input/output token budget tracking.

• src/main.py
  Simple CLI entrypoint for chatting with the tutor locally.

• notes/<language>/
  The teaching corpus: atomic markdown notes per language (Python, Ruby, JavaScript) with wikilinks between them.

• tutor_prompt.md
  The tutor's behavioral/system prompt.

Tech stack

• Python 3.11+
• FastAPI
• NetworkX
• Anthropic Python SDK
• pytest
• uv for environment and dependency management
• Fly.io for deployment

Local development

Prerequisites

• Python 3.11 or newer
• uv
• ANTHROPIC_API_KEY

Install dependencies

uv pip install -e ".[dev,web]"

If you only want the core package plus tests:

uv pip install -e ".[dev]"

Run the API

ANTHROPIC_API_KEY=your_key uvicorn api:app --app-dir src --reload --port 8080

Run the CLI

ANTHROPIC_API_KEY=your_key python src/main.py

Run tests

Environment variables

API

POST /api/chat

Request body:

{
  "user_id": "browser-generated-id",
  "tutor": "python",
  "question": "What is a list comprehension?",
  "conversation_history": []
}

Response body:

{
  "response": "A list comprehension is ...",
  "history": [
    { "role": "user", "content": "What is a list comprehension?" },
    { "role": "assistant", "content": "A list comprehension is ..." }
  ],
  "usage": {
    "input_tokens": 123,
    "output_tokens": 456,
    "retrieval": {
      "topic": "Comprehension",
      "score": 0.73,
      "neighbors": 4
    }
  }
}

Behavior notes:

• Returns 429 when a user exceeds the in-memory token budget
• Returns 503 when Anthropic reports temporary overload
• Returns 502 for other Anthropic API failures
• Does not persist conversation history server-side; the client sends it back on each request

GET /api/health

Returns service status plus the number of topics loaded into each tutor's graph, e.g. {"status": "ok", "tutors": {"python": 127, "ruby": 42, "javascript": 30}}.

Deployment

This repo includes:

• Dockerfile for containerized deployment
• fly.toml for Fly.io

The production container:

• installs the web dependencies
• copies src/, notes/, and tutor_prompt.md
• runs uvicorn on port 8080

Testing

The project includes unit, integration, and API-level tests covering the graph builder, retrieval, tutor flow, budget logic, and FastAPI endpoints.

License

MIT