Skip to content

Developer Guide

This guide is for engineers working on Adapta. It assumes you can read Python and have shipped backend services, but it does not assume you've worked with ML infrastructure before.

Start here

If you're new to the codebase, read these in order:

  1. Learning the system — the from-first-principles tour. If terms like embedding, vector store, LoRA adapter, GGUF, quantization, or eval gate are fuzzy, read this first. It maps every AI-specific concept onto something you already know from standard backend work (indexes, caches, job queues, migrations, CI).
  2. Architecture — the components, the two data planes, the data model, and how a request actually flows through the system.
  3. Workflow & the three contracts — how we make changes: contract-driven development (Extended SDD), the make targets, and the dev container. Read this before your first PR.
  4. Code reference — auto-generated API docs for the key modules, pulled straight from the source docstrings.

The non-negotiables

These are hard constraints. They're enforced in CI; violating them fails the build. The full rationale is in each linked doc, but in short:

  • Never let an exception reach a client as a raw string. Raise a typed DomainError; the boundary handler serializes it safely. make check-leaks fails the build if detail=str(e) reappears.
  • Change the contract before the code. API → specs/openapi.yaml; DB → Alembic migration; model/training → the dataset schema + eval gate. See Workflow.
  • Generated artifacts are never hand-edited (adapta/models/generated/, Alembic autogenerated migrations). Regenerate them.
  • Dependencies live in pyproject.toml only and are baked into the image at build time. Never pip install by hand.
  • Don't rewrite the inference engine or the training loop internals. They're wrapped and called, not rewritten.

How the docs themselves stay correct

Same discipline as the code. The API reference renders from the OpenAPI spec; the code reference renders from docstrings; mkdocs build --strict in CI fails on a broken internal link. When you change behavior, update the doc in the same change — and prefer linking to a single source over restating it.