diff --git a/AI-Stack.md b/AI-Stack.md deleted file mode 100644 index 9ea82a3..0000000 --- a/AI-Stack.md +++ /dev/null @@ -1,104 +0,0 @@ -# AI Stack - -The AI layer is the reasoning core of Atlas OS: a durable decision spine, an autonomous-but-gated execution Brain, and a cost-tiered model router that always reaches for the cheapest capable model first. This page covers how those pieces fit together and where the rough edges still are. - -For where these services surface in the desktop, see [[Atlas-OS]]. For hosting and isolation, see [[Infrastructure]] and [[Security]]. - ---- - -## At a glance - -| Component | What it is | Where it lives | -|---|---|---| -| Kernel spine | `kernel.sqlite` — the durable record of decisions and events | Local SQLite spine | -| Atlas Brain | Reviewed-execution autonomous core | Reasoning layer over the spine | -| Policy gate | Human-approval checkpoint for sensitive actions | In front of every Brain action | -| LLM router | Cost-tiered model selector | `localhost:8888` | -| Headroom proxy | Context compression layer | In front of model calls | - -Surfaced in Atlas OS under the **AI** category: Atlas Chat (Open WebUI), AI Gateway, Mindmap, and Leeragent. - ---- - -## The spine — `kernel.sqlite` - -Everything the Brain does is anchored to a single durable record. `kernel.sqlite` holds roughly **458 decisions** and **3,415 events**, giving the system an auditable memory of what was decided, when, and what happened around it. - -The spine is the source of truth: decisions are recorded as first-class objects, and events accumulate as an append-style log around them. This is what lets autonomous execution stay reviewable — there is always a record to inspect rather than an opaque chain of model calls. - ---- - -## The Brain — reviewed execution - -**Atlas Brain** is the autonomous core, built on a *reviewed-execution* model. It can reason, plan, and act against the spine, but it is not unconditionally free to do so. - -A **policy gate** sits in front of every action. It **always requires human approval** for three classes of action: - -- **Money** — anything financial. -- **External communications** — anything that leaves the system to a third party. -- **Self-modification** — anything that changes Atlas itself. - -Actions outside those classes can proceed under reviewed execution; the three gated classes never auto-execute. This is a hard rule, not a tunable setting — the gate is the safety boundary that makes autonomy acceptable. - ---- - -## The router — cost-tiered model selection - -The LLM router at **`localhost:8888`** picks the cheapest model that can handle a task, and only escalates when it must. The ordering is deliberate: local models cost nothing and stay private, free cloud tiers cost nothing but leave the box, and paid Claude is the last resort. - -| Tier | Models | Cost profile | -|---|---|---| -| **1 — Local** | LLaMA 1B, hermes3, Qwen Coder, Qwen 7B | Zero cost, fully on-box | -| **2 — Free cloud** | Groq `llama-3.3-70b`, Cerebras, OpenRouter | Zero cost, off-box | -| **3 — Paid** | Claude | Used last, only when needed | - -The principle: never burn paid tokens on work a free or local model can do. Classification, routing, copy, and summaries stay local; harder reasoning escalates only as far as it has to. - ---- - -## Headroom — context compression - -The **Headroom proxy** sits in front of model calls and compresses context before it reaches the model. This keeps prompts within working limits and reduces the cost and latency of each call — which in turn makes the cheaper tiers viable for more tasks than they otherwise would be. - ---- - -## How a request flows - -```mermaid -%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%% -flowchart TD - REQ[Incoming task] --> BRAIN[Atlas Brain
reviewed execution] - BRAIN --> SPINE[(kernel.sqlite
decisions + events)] - BRAIN --> GATE{Policy gate} - - GATE -->|money / external-comms / self-modify| HUMAN[Human approval required] - GATE -->|everything else| HEADROOM[Headroom proxy
context compression] - - HUMAN -->|approved| HEADROOM - - HEADROOM --> ROUTER{LLM router
localhost:8888} - ROUTER -->|cheapest capable| LOCAL[Local models
LLaMA 1B / hermes3 / Qwen] - ROUTER -->|escalate| FREE[Free cloud
Groq / Cerebras / OpenRouter] - ROUTER -->|last resort| CLAUDE[Claude paid] - - LOCAL --> SPINE - FREE --> SPINE - CLAUDE --> SPINE -``` - -The Brain records its reasoning to the spine, passes through the policy gate, and — once cleared — compresses context via Headroom before the router selects a model from the cheapest capable tier. Results flow back into the spine. - ---- - -## Known gap — cross-device chat history - -Chat-history consolidation across devices is **not yet solved**. Conversation history is not currently unified into a single cross-device view, and reconciling it is a pending follow-up rather than a shipped feature. Treat per-device history as authoritative on its own device until this is addressed. - ---- - -## Related pages - -- [[Atlas-OS]] — the desktop where AI apps surface -- [[Infrastructure]] — hosting, Caddy, containers -- [[Security]] — EU-sovereign hosting, secrets, MFA -- [[Fleet-and-Mesh]] — NATS mesh and node-to-node messaging