Glossary

The project uses two evocative names — Praetor and Legion — because they're easier to talk about than "central orchestrator service" and "worker agent pool". Everything else is plain English.

A–Z

ADR — Architecture Decision Record. Short markdown files under docs/adr/ recording why we made a non-trivial technical choice. New application code in a new area requires an accepted ADR first (see CLAUDE.md).

Audit Log — Append-only table (audit_log in SQLite) recording every decision Praetor makes plus the inputs that produced it. Replayable. See ADR-0012.

CLA — Contributor License Agreement. Every contributor signs the CLA before their first PR is merged; this is enforced by the CLA Assistant Lite workflow.

Dashboard — Server-side HTMX UI embedded in Praetor. Shows the live audit log via SSE, the facts and episodes the brain has accumulated, an operator-editable system-prompt override, and active sessions. Opt-in via CAESAR_DASHBOARD__TOKEN. See ADR-0021.

Episode — A 1–2 sentence summary of one past chat, embedded for similarity recall. New chats automatically inject relevant past episodes into the system prompt. See ADR-0034.

Fact — A durable key/value record (e.g. dog_name = "Beans") extracted from past chats by the memory.extract worker and auto-injected into future chat system prompts. See ADR-0033.

HA Bridge — The module that talks to Home Assistant over REST + WS. Single, well-defined surface so the rest of CAESAR doesn't depend on HA internals. See ADR-0007.

Legion — The pool of worker agents. Each worker handles a slice of work (calculator, web search, calendar read, MQTT publish, …) and registers with Praetor over the message bus. Workers run in-process under Praetor or as separate processes on other hosts (see ADR-0027).

LLM Gateway — Provider-agnostic abstraction over Anthropic, OpenAI, and Ollama. Per-task routing lets the operator send chat to one provider and background memory work to another. See ADR-0011 and ADR-0026.

MADR — Markdown Architecture Decision Records. The format CAESAR ADRs follow (Context · Decision · Consequences). See ADR-0001.

Memory — Two layers. Episodic (SQLite audit_log + per-chat episode summaries) is always on; semantic (vector store fed by a background indexer) opts in via CAESAR_SEMANTIC__ENABLED. See ADR-0010.

Message Bus — Inter-process messaging fabric. NATS, per ADR-0009. Subjects are caesar.dispatch.<worker_id>, caesar.registry.*, and caesar.reply.<inbox>. Disabled by default; turn it on with CAESAR_BUS__ENABLED=true.

Plugin — A third-party Python package that ships a Legion worker via the caesar.plugins entry-point group. Operators install plugins with pip install; Praetor discovers them at startup, validates each manifest, and the result joins the in-process Legion pool. See ADR-0035 and BUILD-A-PLUGIN.md.

Policy Engine — Gatekeeper between agents and the real world. Declarative YAML allow-list — every HA service call and every Legion tool call passes through. Plugins do not bypass it. See ADR-0013 and ADR-0028.

Praetor — The central brain. A Python service (FastAPI + LangGraph) that owns conversation state, memory reads/writes, policy decisions, and orchestration of Legion workers. The only component that holds long-lived credentials. See ADR-0006.

ProactiveRunner — The entry point used by every trigger source (scheduler, HA-event driver, webhook dispatcher) to fire the brain graph unattended. Same call_llm → dispatch_tools loop as /v1/chat, plus a proactive=true safety preamble that biases toward summarise + notify over act on the house. See PROACTIVE-CAESAR.md.

Trigger — A source that fires the brain graph unattended. Discriminated union: ScheduleSource (cron; ADR-0030), HASource (HA event; ADR-0031), or WebhookSource (HTTP POST; ADR-0032). Lives in triggers.yaml.

Trunk-based development — Short-lived branches off main, squash-merged via PR. Release branches are created on demand for hotfixes. See ADR-0014.

Worker — Singular of Legion. A process that registers with Praetor over NATS and handles a declared set of capabilities (tool ids).