# 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.