wiki: AI-Stack

AI-Stack.-.md

@@ -0,0 +1,69 @@
+# AI Stack
+
+Atlas OS routes every AI task by cost and complexity. The rule: **never burn paid tokens on work a free or local model can handle.** Free tier first, escalate only when it can't cope.
+
+## Tier 0 — Zero-cost local (`localhost:8888/v1`, RTX A2000)
+
+An OpenAI-compatible router exposes local Ollama models. Used for all non-critical subagent work, copy, summaries, translations, and classification.
+
+| Alias | Backing | Use for |
+|-------|---------|---------|
+| `atlas-fast` | LLaMA 1B | Ultra-fast classification, routing, labels |
+| `atlas-free` | Hermes3 | Dutch copy, summaries, FAQ, product descriptions |
+| `atlas-code` | Qwen Coder | Code completion, simple fixes, boilerplate |
+| `atlas-qwen` | qwen2.5 | General Dutch content, emails |
+| `atlas-phi3` | qwen2.5:7b | Reasoning, analysis, comparisons |
+| `atlas-auto` | smart router | Auto-picks the best free local model |
+
+```python
+import openai
+client = openai.OpenAI(base_url="http://localhost:8888/v1", api_key="atlas")
+client.chat.completions.create(model="atlas-auto", messages=[{"role":"user","content":"..."}])
+```
+
+## Tier 1 — Free cloud APIs
+
+| Provider | Models | Best for |
+|----------|--------|----------|
+| Groq | llama-3.3-70b-versatile, mixtral-8x7b | Fast 70B reasoning, bulk tasks |
+| Cerebras | llama-3.1-70b | Fastest inference, free tier |
+| OpenRouter | 50+ free models incl. Gemini | Multi-model fallback |
+| Gemini (via OpenRouter) | gemini-2.5-pro / 3.5-flash | 1M context, vision, PDF |
+
+## Tier 2 — Paid Anthropic (only when free tiers can't cope)
+
+| Task | Model |
+|------|-------|
+| Simple classification, short copy | `claude-haiku-4-5` |
+| Code, multi-step reasoning, planning | `claude-sonnet-4-6` |
+| Deep research, architecture, complex builds | `claude-opus-4-8` |
+
+## Routing decision tree
+
+```
+copy / text / translation / summary / Dutch content
+    → atlas-free (local) or Groq llama-3.3-70b (free cloud)
+simple code / boilerplate / fix
+    → atlas-code (local) or Cerebras (free cloud)
+non-critical workflow subagent
+    → atlas-auto or Groq  (never Claude)
+multi-step code / planning / complex reasoning
+    → claude-sonnet-4-6
+deep architecture / research / competitive analysis
+    → claude-opus-4-8 or gemini-2.5-pro (free)
+1M context / vision / PDF
+    → Gemini via OpenRouter
+```
+
+## Always-on AI services
+
+| Service | What it does |
+|---------|-------------|
+| `atlas-brain` | Collects mail + CRM + bank every 15 min → synthesizes the daily brief |
+| `atlas-loop` | Background signal loop — publishes nudges to NATS |
+| `atlas-meridian` | Autonomous decision engine / battle responder |
+| `atlas-litellm` | Unified LLM proxy (OpenAI-compat API for all models above) |
+| NATS mesh | Real-time event bus across all devices on the tailnet |
+| Langfuse | Full LLM observability — every call traced with latency, cost, tokens |
+
+All model calls flow through the LiteLLM proxy so cost and latency are traced centrally in Langfuse, regardless of which tier served the request.