# AI Architecture

> The two AI surfaces, the locked execution-ownership decision, and deployment status.

_Verified against the codebase on 2026-07-23._

---

## 🔒 Locked architecture decision — Execution ownership

**Numu is the authoritative business-action executor. Make.com is the orchestration + AI reasoning layer only.**

- After an agent proposal is approved, **Numu executes** the action through the canonical `Startup/InvestorLabelActionService` (via `AgentActionExecutor`).
- **Make.com** triggers runs and performs AI orchestration/reasoning; it does **not** execute business actions against Numu data.
- **Older documents that describe Make as the executor are deprecated** (e.g. `AI_AGENTS_ACTIONS_APPROVALS_WALKTHROUGH.md` and parts of `MANAGED_AGENTS_IMPLEMENTATION_PLAN.md`). See [`../06-history/decisions-log.md`](../06-history/decisions-log.md) and [`../06-history/deprecated.md`](../06-history/deprecated.md).

## Two distinct AI surfaces (do not conflate)

### A. MCP Connector — live, interactive
- `app/Services/Ai/*`, `app/Services/Ai/Mcp/McpToolRegistry.php`, `AiMcpController`.
- Claude.ai connects as an MCP client (OAuth 2.1 or legacy Sanctum), calling tools directly.
- **Writes apply immediately — there is no suggestion/approval queue here.** (The old `change_request.submit` workflow was removed.)
- Includes the **Enrichment engine** (`app/Services/Ai/Enrichment/*`): provider fetch → normalize → source resolution → confidence (≥ 0.80) → write → audit → rollback. Providers: Proxycurl, Hunter, WebFetch, Gravatar. Guards: budget ceiling, SSRF `UrlGuard`, `ImageValidator`.

### B. Managed Agent Runtime — propose-only
- `app/Services/Agents/*`.
- An agent run produces a **proposal only** (`executed:false`); it never decides, executes, or mutates state.
- Pipeline: `RuntimeRunner` (preconditions → immutable knowledge package → context/prompt → model provider → structured-output validation) → `AgentDecisionService` (policy → approval → execution). Full detail in [`../03-ai-agents/decisions.md`](../03-ai-agents/decisions.md).

## Feature gating
`config/ai.php` (`NUMU_AI_ENABLED`) is the master flag. When false, `/api/v1/ai/*` returns **404** and the admin AI console is hidden. Also holds PII-redaction rules, a per-token circuit breaker (`ai.cb` middleware → HTTP 423), a CORS allow-list (default `https://claude.ai`), enrichment config, and MCP file-size caps.

## Deployment status (must not be assumed)
- **MCP:** implemented as a native-PHP MCP host; controlled by `ai.enabled`; **production availability requires confirmation.**
- **Managed Agents:** runtime exists; live agents are `intake_triage` and `prescreen` — **implemented, but deployment status requires confirmation.** Planned agents (AUTO-027…031) are **not implemented** — see [`../03-ai-agents/agents.md`](../03-ai-agents/agents.md).