Concepts
========

Agency runs AI agents as **persistent, auditable backend processes** — not one-off chat scripts.
Tagline: *intelligence as a process, not a script*.

Django + PostgreSQL hold application state; LangGraph/LangChain drive each invoke.
Code and the Framework pages are the source of truth for signatures and behaviour.

Repos
------

Product, host, and umbrella roles: :doc:`architecture`.

Domain lifecycle
----------------

::

    Provider → Model → Agent (+ Tools) → Mission
         → Execution → Thread → Run(s) → Checkpoint
                              ↘ Interruption (HITL) → resume → new Run

* **Provider** — inference backend (``kind``: ollama, openai, fal, or
  openai-compatible). URL plus the *name* of the API-key env var; the secret
  stays in Compose ``.env``. Boot seeds Ollama, OpenAI (``gpt-4o-mini`` /
  ``gpt-4o``), and FAL. Uncustomized Veronica uses Ollama when it is chat-ready,
  otherwise ``gpt-4o-mini``.
* **Model** — LLM row under a Provider (``Agent.model`` FK). Temperature and
  Ollama ``num_ctx`` live in ``metadata``.
* **Execution** — business intent.
* **Thread** — persistent timeline / LangGraph ``thread_id``.
* **Run** — one technical attempt; interrupted Runs stay interrupted; resume creates a **new** Run.
* **Interruption** — durable HITL; workers are not held open waiting.
* **Celery Task** ≠ Execution/Run — transport only.

Narratives: :doc:`development/processes/execution`, :doc:`development/processes/agent`,
:doc:`development/processes/celery`. Tutorials: :doc:`tutorials/index`.

Realtime
--------

DB commit → signals → Channels projection.

* **Messenger** — conversation · **Monitor** — run telemetry · **Catalog** — explorer CRUD

Details: :doc:`development/processes/realtime`, contract :doc:`framework/connections`.

Knowledge
---------

* **RAG** (``agency.corpus``) — Tenant → Workspace → Document → Chunk → vector store
* **miner** — Scrap → Block (ingest; not the RAG index)

UI
--

Schema-driven **Agency desktop**. Backend owns domain + producers; **agency-ui**
owns rendering (:doc:`development/ui/index`). **Mission Control** is the desktop
app for Agents, Missions, and Executions — not the whole SPA
(:doc:`development/ui/mission-control`). Operator chrome also includes the
**Media** player (images / YouTube) and **Map** (dark chart + satellite pane); kiosks
are ``agency.display``, not those windows.

Principles (short)
------------------

1. Database is the source of truth; WebSockets are projections.
2. Execution ≠ Run; resume = new Run on the same Thread.
3. HITL is explicit and auditable.
4. Keep agency-django free of host-only logic.

Longer product vision (Spanish, workspace): ``agency-workspace/CONTEXT.md``.
Doc surface map: workspace ``README.md`` (*Documentation architecture*).
Single-file HTML: ``./dev doc`` → ``/static/documentation-single/``.