Skip to content

Adapta

A self-hosted platform for customizing and serving private language models. Upload documents and import your own LoRA adapter — then expose the result as an OpenAI-compatible API. Your data never leaves your servers.

Beta maturity

One maintainer, built with AI assistance. The lifecycle works end to end: cited hybrid RAG, bring-your-own-adapter (import, CPU eval gate, promote/rollback) and multi-tenant serving; the API contract gate passes 40 of 40 operations. It has not been independently audited, so review the auth and eval-gate code paths before using sensitive data. Not built yet and known limits: see Project status. Migrating from another stack: migration guide.

This documentation serves two purposes: it is the operational and developer reference for the platform, and it is a concrete learning resource for anyone building or studying AI infrastructure on a real, production-grade codebase.

Where to start

  • AI Infrastructure Guide

    Not sure what GGUF, LoRA, embeddings, or a vector store are? Start here. This section explains the full technology stack — every component, why it was chosen, and how it fits — written for engineers who know web development but are new to AI infrastructure.

    AI Infrastructure Guide

  • User Guide

    For the operator running the platform. How to create projects, give a model knowledge from your documents, change how it behaves through adapters, and hand an application a scoped API key.

    User Guide

  • Developer Guide

    For engineers working on the codebase. Architecture, the contract-driven workflow, the three CI gates, and the auto-generated code reference. Read Learning the system before your first change.

    Developer Guide

  • Reference

    The locked facts: product scope, the live API reference generated from the OpenAPI spec, the operations runbook, and the architecture-decision record.

    API Reference

What the platform does

A company deploys Adapta on its own server with Docker Compose. Inside that deployment, teams create Projects. Each project ends in a private model endpoint consumed with a scoped API key:

Knowledge (RAG) — upload documents → they are parsed, chunked, and embedded into a per-project vector store → each question is answered by hybrid retrieval (semantic vector search + BM25 keyword search, fused and re-scored by a cross-encoder reranker) → the model answers grounded in your documents, with citations pointing at the source passages. The model's weights never change. CPU-only.

Bring your own adapter (LoRA) — import a GGUF/PEFT adapter, gate it on CPU against the base on your eval set, then serve base model + adapter. Import, conversion and the gate run on CPU (E4.2–E4.4, live 2026-10-10); a rejected adapter is never served. In-product training was removed on 2026-10-10; no service needs a GPU. See the import guide.

Both together — a finetune project can also index documents. Its endpoint injects retrieved context and applies the adapter in one call: facts from retrieval with citations, tone and structure from the adapter.

The POST /v1/chat/completions endpoint is the only protocol customer applications call. If your code already calls OpenAI, it already calls Adapta.

New to RAG, LoRA, GGUF, or embeddings?

The AI Infrastructure Guide explains every concept in terms of engineering ideas you already know — databases, caches, job queues, and CI pipelines. No prior ML background required.

Learning paths

Your goal Recommended path
Understand the AI infrastructure AI Infrastructure Guide → Stack & decisions → Learning the system
Set up and use the platform User Guide → Operator console → Consuming the API
Contribute to the codebase Developer Guide → Architecture → Workflow
Understand a specific decision Stack & decisions — each component has an explicit "why not X?" section
Operate the platform in production Operations runbook

How this documentation stays correct

Docs rot. This system is built so the parts that drift hardest can't:

Part How it stays in sync
API reference Rendered from specs/openapi.yaml — the same file the server is tested against. Change the API, the docs change.
Code reference Auto-extracted from source docstrings (mkdocstrings). The reference is the code.
Internal links mkdocs build --strict runs in CI. A broken internal link fails the build.
Roadmap Canonical source at TODO.md in the repository — the roadmap page links to it directly rather than embedding it (the file links to source paths that only resolve in-repo).
Changelog CHANGELOG.md at the repository root — every shipped roadmap block, newest first; linked, not embedded, for the same reason.
Scope vs. tasks Reference docs describe what is. The Roadmap is the only place with open work. The two are never mixed.