69ec2f667d
- New /settings/tools page: max_risk selector (low/medium/high) + per-tool override dropdowns (Default / Force include / Force exclude) for all 58 tools grouped by category with color-coded risk badges; JS updates Auto status live - get_tools_for_role() + get_openai_tools_for_role() now accept max_risk, whitelist, blacklist; _apply_risk_policy() handles the filtering logic - get_risk_policy() helper in auth_utils reads from tool_policy.json - Risk policy wired through orchestrator.py, openai_orchestrator.py, orchestrator_engine.py, nextcloud_talk.py, homeassistant.py - Tools nav link added to settings.html and notifications.html - CLAUDE.md and ARCH__SYSTEM.md updated: tool count 50→58, risk system docs, tool access control three-layer model documented Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
133 lines
9.4 KiB
Markdown
133 lines
9.4 KiB
Markdown
# Architecture: System Overview
|
||
|
||
> How the pieces fit together.
|
||
> Last updated: 2026-05-06
|
||
|
||
---
|
||
|
||
## Architecture Diagram
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ INPUT CHANNELS │
|
||
│ │
|
||
│ Web UI ──────────────────────────────────────────┐ │
|
||
│ Nextcloud Talk ──── POST /webhook/nextcloud/{u} ─┤ │
|
||
│ Google Chat ─────── POST /channels/google-chat/{u}┤ │
|
||
│ Cron / Scheduler ─────────────────────────────────┤ │
|
||
│ Webhooks (future) ─────────────────────────────────┘ │
|
||
└─────────────────────────────┬───────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ CORTEX DISPATCHER (FastAPI — cortex/) │
|
||
│ │
|
||
│ auth_middleware.py → validates JWT session cookie │
|
||
│ persona.py → resolves user + persona context │
|
||
│ context_loader.py → assembles system prompt (tier 1-4)│
|
||
│ │
|
||
│ POST /chat → direct LLM, streaming SSE │
|
||
│ POST /orchestrate → Gemini tool loop → Claude │
|
||
│ GET /orchestrate/{id} → poll job result │
|
||
└────────────┬───────────────────┬────────────────────────┘
|
||
↓ ↓
|
||
┌─────────────────┐ ┌──────────────────────────────────┐
|
||
│ LLM BACKENDS │ │ PERSONA DATA │
|
||
│ │ │ home/{user}/persona/{name}/ │
|
||
│ Claude CLI │ │ │
|
||
│ Gemini CLI │ │ IDENTITY.md SOUL.md │
|
||
│ Gemini API │ │ PROTOCOLS.md MEMORY_*.md │
|
||
│ Local (httpx) │ │ USER.md REMINDERS.md │
|
||
│ │ │ TASKS.json CRONS.json │
|
||
└─────────────────┘ │ sessions/ SCRATCH.md │
|
||
└──────────────────────────────────┘
|
||
```
|
||
|
||
Details: [`ARCH__BACKENDS.md`](ARCH__BACKENDS.md) | [`ARCH__PERSONA.md`](ARCH__PERSONA.md) | [`ARCH__CHANNELS.md`](ARCH__CHANNELS.md)
|
||
|
||
---
|
||
|
||
## Service Layout (`cortex/`)
|
||
|
||
| File | Purpose |
|
||
|---|---|
|
||
| `main.py` | App entry point, router registration |
|
||
| `config.py` | All settings (pydantic-settings, reads `.env`) |
|
||
| `persona.py` | User + persona path resolution, ContextVars |
|
||
| `context_loader.py` | Builds system prompt from persona files (tiers 1–4) |
|
||
| `llm_client.py` | All LLM backends — Claude, Gemini CLI, Local |
|
||
| `orchestrator_engine.py` | Gemini API ReAct tool loop → Claude handoff |
|
||
| `openai_orchestrator.py` | OpenAI-compatible ReAct tool loop (local models via Open WebUI/OpenRouter) |
|
||
| `model_registry.py` | Per-user model registry V2 — providers, hosts, models, role assignments |
|
||
| `session_store.py` | In-memory + file session persistence (`session_data/{id}.json`) |
|
||
| `session_logger.py` | Writes session turns to `sessions/YYYY-MM-DD.md` |
|
||
| `memory_distiller.py` | Short/mid/long distill jobs |
|
||
| `scheduler.py` | APScheduler — distill jobs + user crons |
|
||
| `cron_runner.py` | Cron job storage, schedule parsing, execution |
|
||
| `notification.py` | Outbound channel messages (distill alerts, cron proactive) |
|
||
| `auth_utils.py` | bcrypt passwords, JWT, invite tokens, channel config |
|
||
| `auth_middleware.py` | JWT cookie validation on all routes |
|
||
| `tool_audit.py` | JSONL audit log for every orchestrator tool invocation |
|
||
| `usage_tracker.py` | Per-user token usage tracking (daily buckets → `usage.json`) |
|
||
| `event_bus.py` | Internal SSE pub/sub (NC Talk → browser mirror) |
|
||
| `email_utils.py` | SMTP invite emails |
|
||
| `persona_template.py` | Bootstrap a new persona directory from templates |
|
||
| `routers/` | One file per endpoint group — `chat`, `orchestrator`, `auth`, `files`, `ui`, `settings`, `tools_settings`, `local_llm`, `distill`, `audit`, `usage`, `push`, `help`, `onboarding`, `auth_google`, `nextcloud_talk`, `google_chat`, `homeassistant` |
|
||
| `tools/` | 58 orchestrator tools in 15 domain modules — `web`, `files` (project + system scope), `tasks`, `scratch`, `reminders`, `cron`, `system`, `notify`, `ae_knowledge`, `ae_tasks`, `agent_notes`, `agents`, `homeassistant`. Registry and access control in `tools/__init__.py`. |
|
||
| `static/` | Web UI — `index.html`, `app.js`, `style.css`, `login.html`, `setup.html`, `HELP.md`, `local_llm.html`, `settings.html`, `notifications.html`, `tools_settings.html` |
|
||
| `tests/` | pytest suite |
|
||
|
||
---
|
||
|
||
## Key Design Decisions
|
||
|
||
**Two-brain pattern (Gemini orchestrator)** — Gemini API handles tool use (function calling, planning, web search). Claude CLI handles all user-facing responses. Direct chat bypasses the orchestrator entirely.
|
||
|
||
**Single-model pattern (local orchestrator)** — When the `orchestrator` role resolves to a `local_openai` model, `openai_orchestrator.py` runs the full ReAct loop and produces the final response itself. No Claude handoff — the local model does both reasoning and response.
|
||
|
||
**Subprocess backends** — Claude and Gemini run as CLI subprocesses (`claude --print`, `gemini -p`). This keeps auth transparent (Claude Code manages tokens) and avoids API costs on the Pro subscription path.
|
||
|
||
**Local backend via httpx** — Open WebUI's OpenAI-compatible API (`/api/chat/completions`). No CLI wrapper. Per-user host + model config in `local_llm.json`.
|
||
|
||
**ContextVars for async isolation** — `persona.py` uses Python `contextvars.ContextVar` so concurrent requests each see their own user/persona without thread-local hacks.
|
||
|
||
**Per-user filesystem layout** — `home/{user}/persona/{name}/` mirrors Linux home directories. Each persona is a directory of markdown files and JSON. No database. Easy to inspect, edit, and back up.
|
||
|
||
**No single point of coupling** — tools live in `cortex/tools/`, separate from `ae_*` MCP tools. Channels live in `cortex/routers/`, each self-contained. Adding a channel or tool doesn't touch other subsystems.
|
||
|
||
**Tool access control (three layers):**
|
||
1. **Role gate** (`TOOL_ROLES` in `tools/__init__.py`) — admin-only tools require `admin` role in `auth.json`.
|
||
2. **Risk policy** (`home/{user}/tool_policy.json`) — `max_risk` auto-includes all tools at or below a level (low/medium/high); `whitelist`/`blacklist` override individual tools. Configurable at `/settings/tools`.
|
||
3. **Model-level tool list** — per-role `tools` field in `local_llm.json`; can only restrict further, never elevate.
|
||
|
||
All 58 tools carry a `TOOL_RISK` rating (36 low / 12 medium / 10 high) used for auto-filtering. `CONFIRM_REQUIRED` is a separate static set of tools that trigger a user confirmation prompt before executing, independent of risk level.
|
||
|
||
**Agent private notes** — `AGENT_NOTES.md` per persona, writable only by the orchestrator via `agent_notes_*` tools. Never loaded into user-facing context. Three rolling backups (`bak1`–`bak3`) are visible read-only in the Files panel. Declared in `tools/agent_notes.py`; usage guidance in `PROTOCOLS.md`.
|
||
|
||
**No black boxes** — Every component, flow, and design decision is documented. Documentation is updated before implementation of significant changes and verified after. HELP.md is the user-facing contract; ARCH__*.md files are the developer contract; PROTOCOLS.md is the agent contract. If any of these drift from reality, that is a bug.
|
||
|
||
---
|
||
|
||
## Onboarding Flow
|
||
|
||
New users are invited via a one-time token and complete a three-step setup before reaching the chat:
|
||
|
||
```
|
||
1. /setup/{token} → Set password (POST creates session cookie, consumes token)
|
||
2. /setup/persona → Create persona (slug, display name, emoji, description)
|
||
3. /setup/model → Connect a model — OpenRouter recommended
|
||
(skip link goes straight to /{user}/{persona})
|
||
```
|
||
|
||
Step 3 is the planned addition (see `TODO__Agents.md § Guided onboarding`). Before it exists,
|
||
users land in the chat with no model configured and must navigate Settings → Model Registry
|
||
manually — which is confusing for non-technical users.
|
||
|
||
**After Step 3:**
|
||
- `save_host()` adds OpenRouter (`https://openrouter.ai/api/v1`, type `openai`)
|
||
- `save_model()` creates a model entry for the chosen model
|
||
- `set_role(chat, primary, model_id)` assigns it as the chat role primary
|
||
- Redirect to `/{user}/{persona}`
|
||
|
||
**Existing users with no model configured** — a dismissable banner is shown in the chat on
|
||
load, linking to `/setup/model` (the Step 3 form works standalone, without step labels).
|