AgentContextOS

Production-grade, multi-tenant RAG platform — pluggable retrieval, enterprise governance, agent loops, and full observability behind one API. v1.0.0 GA.

Four API surfaces — REST, gRPC, MCP, and OpenAI-compatible — over one engine: hybrid retrieval (dense + sparse + graph) with reranking, hallucination guarding, signed per-query provenance, tenant isolation with ACL/PII enforcement, quotas, drift monitoring, eval gates, and billing. Every backend (vector store, embedder, LLM, …) is a swappable plugin behind an SPI, and rag.yaml is the portability contract — the same code runs on a laptop, a VM, and Kubernetes.

What's running once it's up

Component	Where	What you get
Gateway	http://localhost:8000	REST (/v1/query, /v1/retrieve, /v1/ingest/document, /v1/feedback, …), OpenAI-compatible (/v1/chat/completions, /v1/embeddings, /v1/models), gRPC, and MCP — plus /v1/status/* (health / metrics / logs) and Swagger UI at /docs
Admin console	http://localhost:3100	Operator GUI: live status, metrics, log tail, tenants, corpora, connectors
ragctl	your terminal	Control-plane CLI — 37 commands + 13 groups (config, eval, drift, pilots, billing, …); see the command reference

Prerequisites

• uv — manages Python 3.12+ and all server dependencies (required)
• Docker — only needed to run real backends locally (the demo needs none)
• Node 20 + pnpm — only for the admin console and the docs site

1. Try it in 5 minutes — demo mode

Zero credentials, zero infrastructure. The gateway starts against an in-memory noop wiring that still exercises the full real pipeline (understand → route → retrieve → rerank → pack):

git clone https://github.com/officialCodeWork/AgentContextOS.git
cd AgentContextOS && uv sync

# Terminal 1 — start the gateway
uv run uvicorn rag_gateway.app:app --port 8000

# Terminal 2 — check it's up
curl -s http://localhost:8000/healthz        # → {"status":"ok"}

Ingest a document, then query:

curl -s -X POST http://localhost:8000/v1/ingest/document \
  -F 'tenant_id=demo' -F 'corpus_id=docs' -F 'principal_id=me' \
  -F 'file=@README.md' | jq '{document_id, status, chunk_count}'

curl -s http://localhost:8000/v1/query \
  -H 'content-type: application/json' \
  -d '{"tenant_id":"demo","principal_id":"me","query":"what is AgentContextOS?","top_k":3}' \
  | jq '{chunks: (.chunks|length), citations: (.citations|length), timings}'

Or run the whole ingest-and-query loop in one process with the CLI:

uv run ragctl query "what is RAG?" --top-k 3

Heads-up: in demo mode the two terminals don't share the in-memory store, so cross-process queries come back empty — use ragctl query for a populated demo, or wire real backends (next section). Full walkthrough with expected outputs: curl quickstart.

2. Run with real backends

Start the backing services (Postgres + pgvector, Qdrant, Redis, Elasticsearch, MinIO):

make dev          # or: task dev
make dev-full     # + OTel collector, Jaeger, Prometheus, Grafana, Loki

Configure rag.yaml — change providers here, nothing else changes:

backends:
  vector_store:  { provider: qdrant }
  keyword_store: { provider: elasticsearch }
  embedder:      { provider: openai, model: text-embedding-3-large }
  llm:           { provider: anthropic, model: claude-sonnet-4-6 }
  cache:         { provider: redis }

Ready-made profiles for each deployment shape live in examples/configs/ — laptop.yaml, single-vm.yaml, k8s-onprem.yaml, saas.yaml, airgap.yaml. Validate any config with:

uv run ragctl config validate rag.yaml

Serve the configured app. The gateway builds its wiring from config via build_app_from_config:

# serve.py
from rag_config import load
from rag_gateway.wiring import build_app_from_config

app = build_app_from_config(load("rag.yaml"))

uv run uvicorn serve:app --host 0.0.0.0 --port 8000

For fully programmatic wiring — injecting backend instances directly instead of via config — see production wiring.

3. Open the admin console

pnpm install
NEXT_PUBLIC_GATEWAY_URL=http://localhost:8000 pnpm --filter @ragplatform/admin-ui dev
# → http://localhost:3100

Without a gateway URL it renders seed data (every page carries a "Demo data" badge), so you can preview the console standalone. Guide: admin-ui quickstart · live-data tour: operator console.

4. Deploy to production

Channel	Install	Notes
Container	docker run -p 8000:8000 ghcr.io/officialcodework/agentcontextos/rag-gateway:1.0.1	serves on :8000 out of the box (noop wiring); mount a rag.yaml + set RAG_CONFIG_PATH for real backends — config-driven serving; cosign-signed, SBOM-attested
Helm	helm install rag oci://ghcr.io/officialcodework/agentcontextos/charts/rag-platform	chart source in infra/helm/rag-platform/; put your full rag.yaml in values.yaml under config.ragYaml
PyPI	pip install rag-platform	meta-package pins all components to a reproducible server stack
Air-gapped	signed offline bundle + install.sh	air-gap install guide

One vX.Y.Z tag publishes every channel — signed (cosign keyless) with SBOMs. Details: packaging & distribution.

Talk to it from your stack

Surface	Guide
REST + curl	curl-quickstart
Python / TypeScript SDKs	sdk-quickstart
OpenAI-compatible (drop-in chat/completions)	openai-quickstart
MCP — Claude Desktop, Cursor, VS Code	mcp-quickstart
gRPC	grpcurl-quickstart
LangChain / LlamaIndex / Semantic Kernel adapters	integrations-quickstart
Webhooks (ingest / drift / feedback events)	webhooks-quickstart
Agent loop (POST /v1/agent)	agent-quickstart

Developing on the platform

./scripts/bootstrap.sh   # uv sync + pnpm install + pre-commit hooks (or: make bootstrap)

make lint                # ruff + mypy --strict
make test                # full test suite
make help                # all targets

Repository layout

AgentContextOS/
├── packages/              # 30 Python packages: rag-core (types, SPIs), rag-config,
│                          # rag-observability, rag-policy, rag-backends, per-stage
│                          # pipeline packages (parsers, chunker, embedders, …),
│                          # governance (guard, quota, pii, sso, …), and ragctl
├── apps/
│   ├── gateway/           # rag-gateway — REST + gRPC + MCP + OpenAI-compatible service
│   └── admin-ui/          # Next.js operator console
├── sdks/                  # Generated Python / TypeScript / Go / Java / .NET clients
├── website/               # Docusaurus documentation site (sources docs/ directly)
├── eval/                  # Golden-set eval harness + CI eval gate runner
├── tests/                 # Cross-package suites: contract, logs, policy, docs, eval
├── proto/                 # core.proto — canonical cross-language schema
├── dist/                  # Generated + committed + drift-gated: OpenAPI, JSON schemas
├── infra/                 # Helm chart, Terraform, OTel / Prometheus / Grafana configs
├── packaging/             # Docker image + air-gapped bundle build
├── marketplace/           # Cloud marketplace listing artifacts + pricing model
├── planning/              # The 8-phase execution plan the build followed
├── docs/                  # ADRs, architecture, guides, reference, runbooks, compliance
├── docker-compose.yml     # Local dev stack (core + observability profiles)
├── rag.yaml               # Platform config contract
├── Taskfile.yml           # Cross-platform task runner (Makefile wraps it on Unix)
└── TRACKER.md             # The 84-step build record (all complete)

Documentation

• docs/README.md — full documentation index (published as the docs site)
• High-Level Design — architecture, components, problem → capability map
• REST API reference — generated from the drift-gated OpenAPI contract
• v1.0.0 release notes — what shipped at GA
• Support & SLAs — support tiers, SLA targets, runbooks
• Problem catalog — the 22+ enterprise RAG failure modes this platform addresses
• Execution plan — the 8-phase build plan, now complete (TRACKER.md is the step-by-step record)