Modules overview¶

The Apogee Framework is composed. The CLI binary (apogee) is the integration layer; the actual building blocks live in 28 independent Python packages, each with its own version, tests, and documentation. Two cohorts:

Foundational (4) — clean architecture, auth (+ runtime middleware) and the React SPA generator.
AI-native (24) — providers, RAG, agents, communication protocols, plus prompt, eval, observability, sandbox, memory, voice, workflow, serving, data, browser, guardrails, tools, UI, ops, cost, billing, connectors, training, templates and search.

Foundational layer¶

Package	What it provides
`apogee-core`	Domain primitives (Entity, ValueObject, DTO), `ApiResponse`, Alembic runner, settings, logging
`apogee-auth`	RBAC, MFA (TOTP/WebAuthn/SMS), audit log, session/credential management
`apogee-auth-runtime`	Runtime middleware that wires `apogee-auth` into FastAPI/Starlette apps
`apogee-frontend`	React SPA generator: shadcn/ui, MUI, Bootstrap, Chakra, PrimeReact + Vite/Next, AI widgets

AI-native layer¶

Package	What it provides
`apogee-ai-providers`	Unified LLM client: OpenRouter, OpenAI, Anthropic, Bedrock, Gemini, Azure, vLLM, Ollama
`apogee-ai-rag`	28 RAG variants and 60+ integrations: vector DBs, embedders, rerankers, chunkers
`apogee-ai`	Agent orchestration: tool-use loop, planner/executor, MCP server/client, multi-agent graphs
`apogee-ai-comunication`	Channel adapters (email/SMS/WhatsApp/Slack/Teams) with the same `Channel` abstraction
`apogee-ai-prompt`	Prompt registry, versioning, A/B comparison, golden-set replay
`apogee-ai-eval`	Offline + online evaluation harness with G-Eval, faithfulness, bias and judge-LLM scorers
`apogee-ai-observability`	OpenTelemetry tracing, span enrichment for LLM calls, token/cost dashboards
`apogee-ai-sandbox`	Code/agent sandbox (firejail, docker, e2b, codeact) with policy gates
`apogee-ai-memory`	Short-term, episodic, semantic and procedural memory with summarisation and pinning
`apogee-ai-voice`	STT, TTS, VAD, barge-in, hot-word adapters (Deepgram, ElevenLabs, OpenAI Realtime, Whisper)
`apogee-ai-workflow`	Long-running, durable agent workflows on Temporal/Restate/Inngest with HIL pauses
`apogee-ai-serving`	Tier-aware router (CHEAP/BALANCED/EXPENSIVE), shadow traffic, canaries, batch inference
`apogee-ai-data`	DVC-style content-addressed dataset/vector versioning, synthetic data, labelling, feature store
`apogee-ai-browser`	Headless browser automation (Playwright + agent), web actions catalogue, captcha handlers
`apogee-ai-guardrails`	Input/output filters: PII, prompt injection, jailbreak; adapters for GuardrailsAI, Lakera, ProtectAI, NeMo
`apogee-ai-tools`	Curated tool registry: search, code-exec, SQL, HTTP, filesystem, calendar, email
`apogee-ai-ui`	npm `@apogee/ai-ui-react`: ChatUI, VoiceUI, AgentInspector, GenerativeUI, AgUiRenderer, TraceUI, HilUI
`apogee-ai-ops`	Production runbooks: rollouts, rollbacks, drift detection, retraining triggers
`apogee-ai-cost`	Cost-aware router that picks the cheapest model meeting a quality bar; budget caps
`apogee-ai-billing`	Tenant usage metering, plan management, RLS-isolated invoicing, Stripe/Paddle adapters
`apogee-ai-connectors`	SaaS integrations (Salesforce, HubSpot, Pipedrive, Zendesk, Intercom, Freshdesk) over `RestIntegrationBase`
`apogee-ai-training`	Fine-tuning recipes (LoRA/QLoRA), distillation, RLHF/DPO entrypoints
`apogee-ai-templates`	End-to-end project templates: copilots, agents, RAG-only, voice-bot, classifier
`apogee-ai-search`	Hybrid retrieval (BM25 + dense + reranker) over the apogee-core index abstractions

Each package documentation site is independent. Version selectors are independent — apogee-ai-rag 0.3.x may be released alongside apogee-core 0.7.x.

How modules fit a generated project¶

flowchart TB
  subgraph generated["Generated project (e.g. shop-api)"]
    domain
    application
    infrastructure
    presentation
  end

  subgraph foundational["Foundational layer (4)"]
    apogee_core[apogee-core]
    apogee_auth[apogee-auth]
    apogee_auth_runtime[apogee-auth-runtime]
    apogee_frontend[apogee-frontend]
  end

  apogee_core --> domain
  apogee_core --> application
  apogee_core --> infrastructure
  apogee_auth --> infrastructure
  apogee_auth_runtime --> infrastructure

  subgraph ai_native["AI-native layer (24)"]
    apogee_ai_providers[apogee-ai-providers]
    apogee_ai_rag[apogee-ai-rag]
    apogee_ai[apogee-ai]
    apogee_ai_comunication[apogee-ai-comunication]
    apogee_ai_prompt[apogee-ai-prompt]
    apogee_ai_eval[apogee-ai-eval]
    apogee_ai_obs[apogee-ai-observability]
    apogee_ai_guardrails[apogee-ai-guardrails]
    apogee_ai_serving[apogee-ai-serving]
    apogee_ai_workflow[apogee-ai-workflow]
    apogee_ai_memory[apogee-ai-memory]
    apogee_ai_data[apogee-ai-data]
    apogee_ai_cost[apogee-ai-cost]
    apogee_ai_billing[apogee-ai-billing]
  end
  ai_native --> infrastructure
  ai_native --> application

  apogee_frontend -.spawns.-> frontend_project((web SPA + AI widgets))

Install snippets¶

Pick the dependencies your project actually uses; every package is opt-in:

TOML

# pyproject.toml of a generated project
[project]
dependencies = [
  "apogee-core>=0.7",
  "apogee-auth>=0.4",
  "apogee-ai-providers>=0.5",
  "apogee-ai-rag[qdrant,openai]>=0.3",
  "apogee-ai>=0.4",
  "apogee-ai-prompt>=0.2",
  "apogee-ai-eval>=0.2",
  "apogee-ai-observability>=0.2",
  "apogee-ai-guardrails[lakera]>=0.2",
  "apogee-ai-serving>=0.2",
  "apogee-ai-cost>=0.2",
]

The CLI auto-detects which packages are installed and only registers the matching make:*/add:* subcommands.

End-to-end example¶

The globaltrust-bank example project uses every module: a fictional international bank with multi-currency, multi-language support, RAG-based compliance assistant, RBAC, voice agent, workflow with HIL escalation, and a shadcn/ui frontend wired with the @apogee/ai-ui-react widget catalogue.