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