---
license: apache-2.0
tags:
  - router
  - mixture-of-experts
  - tool-calling
  - security
  - agent
  - ollama
---

# Opal Router — one endpoint, the best US model per task

The **Opal Router** is the capability half of the [Opal suite](https://huggingface.co/cognis-digital/Opal-8B-GGUF).
Different model architectures (Llama / gpt-oss / Phi / Gemma) **cannot be
weight-merged**. So instead of faking a single super-model, Opal combines them
**honestly, at the system level**: one OpenAI-compatible endpoint that classifies
each request and routes it to the US specialist best suited to it.

```
                    ┌──────────────── Opal Router (:11500, model="opal") ────────────────┐
  your request ───► │  classify →  code/sec ─► opal-8b        (Cognis merge)             │
                    │              reasoning ─► gpt-oss:20b    (OpenAI open MoE)          │
                    │              tool-call ─► llama3.1:8b    (Meta)                     │
                    │              general   ─► phi4           (Microsoft)               │
                    │              vision    ─► llava                                    │
                    └────────────────────────────────────────────────────────────────────┘
```

- **Honest framing:** this is orchestration, not one weight. We don't claim a
  single model does all of this — we route to the model that actually does.
- **Real MoE included:** hard-reasoning requests go to **gpt-oss:20b, OpenAI's
  genuine open Mixture-of-Experts**.
- **All US-origin backends**, all pullable from the Ollama registry.
- **Native tool-calling passthrough:** requests carrying a `tools=[…]` array are
  routed to the tool-calling specialist and the tool calls flow straight back.
- **Zero dependencies** (Python stdlib only). No training. Runs over local Ollama.

## Run
```bash
# 1. pull the backends (all US-origin)
ollama pull llama3.1:8b && ollama pull gpt-oss:20b && ollama pull phi4 && ollama pull llava
#    plus the Opal-8B weight (see the Opal-8B-GGUF repo) imported as `opal-8b`
# 2. start the router
python opal_router.py            # serves http://localhost:11500/v1
# 3. point any OpenAI client at it
curl http://localhost:11500/v1/chat/completions -H "Content-Type: application/json" \
  -d '{"model":"opal","messages":[{"role":"user","content":"Prove sqrt(2) is irrational"}]}'
#    -> classified as reasoning -> served by gpt-oss:20b
```

Env: `OLLAMA=http://localhost:11434`, `PORT=11500`. Routing table:
[`configs/routes.json`](configs/routes.json) (edit to change backends; a model
missing from `ollama list` falls back to `default`).

## Files
- `opal_router.py` — the stdlib router/server
- `configs/routes.json` — capability → model map + backend provenance

## License
Apache-2.0.