lumynax-marama-route 0.4.2

LumynaX MaramaRoute: sovereign OpenAI-compatible model router for LumynaX releases.

🇳🇿 LumynaX MaramaRoute

Sovereign OpenAI-compatible model router for Aotearoa New Zealand. One install. One command. 98 curated LumynaX models. Jurisdiction- and sovereignty-aware routing built in.

Ko te mārama te tūāpapa. Clarity is the foundation.

---

What is MaramaRoute?

MaramaRoute is the Ollama-class CLI and OpenAI-compatible gateway for the LumynaX sovereign model family. Think Ollama for running models, OpenRouter for routing — but purpose-built for Aotearoa New Zealand with jurisdiction, sovereignty tier, and residency enforced at the routing layer, not bolted on after.

	Ollama	OpenRouter	MaramaRoute
OpenAI-compatible API	❌ partial	✅	✅
Local-first execution	✅	❌ remote-only	✅
Routes across many providers	❌ single backend	✅	✅
NZ jurisdiction enforcement	❌	❌	✅ first-class
Sovereignty tier policy gate	❌	❌	✅
Te reo Māori support tagging	❌	❌	✅
Curated model registry	small	huge unfiltered	98 LumynaX models, every one auditable
Self-hostable for free	✅	❌ paid	✅ Apache-2.0

If you've ever wanted ollama run ergonomics with per-request sovereignty controls and a curated NZ-aligned model catalog, this is that.

---

Install

pip install lumynax-marama-route

That's it. Six command aliases get installed — pick whichever you like to type:

MaramaRoute --help        # CamelCase
LumynaXRoute --help       # brand alias
marama-route --help       # hyphenated
maramaroute --help        # lowercase
lumynax-route --help      # brand hyphenated
lumynaxroute --help       # brand lowercase

Also available via npm (npm install -g lumynax-marama-route) for Node-first teams — the npm package wraps the same Python wheel.

---

30-second Quickstart

# 1. Install
pip install lumynax-marama-route

# 2. Verify the wiring (offline smoke — does not bind a port)
MaramaRoute serve --smoke

# 3. Start the OpenAI-compatible gateway + browser console
MaramaRoute serve --port 8787 --open

You now have an OpenAI-compatible endpoint at http://127.0.0.1:8787/v1. Point any OpenAI SDK at it:

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8787/v1", api_key="local")

# MaramaRoute picks the right model for the job — no hardcoding
response = client.chat.completions.create(
    model="auto",   # MaramaRoute selects from 98 LumynaX models
    messages=[{"role": "user", "content": "Write a Python function to compute Fibonacci."}],
    extra_body={"marama_route": {"task_type": "code", "jurisdiction": "NZ"}},
)
print(response.choices[0].message.content)

---

The model catalog (98 sovereign models, curated)

Distribution across the LumynaX family:

Families: qwen (29) · deepseek (6) · lumynax (6) · phi (6) · mistral (5) · olmo (5) · granite (4) · smollm (4)

Runtimes: llama_cpp · transformers · llama_cpp_multimodal · transformers_multimodal · python_embedding

Browse interactively:

MaramaRoute catalog --task code --limit 10
MaramaRoute catalog --task reasoning --requires-tools --jurisdiction NZ
MaramaRoute models | jq '.data[].id'

Every model in the registry carries:

• sovereignty_tier — 1 (remote frontier) through 5 (NZ-resident only)
• residency — list of allowed jurisdictions
• license_id — the upstream license, verifiable in the model card
• runtime — exactly which backend (llama.cpp, transformers, etc.) runs the weights
• primary_artifact — the actual file shipped on Hugging Face

Full registry: AbteeXAILab/marama-route · 98 LumynaX model repos under AbteeXAILab on Hugging Face.

---

What the router actually does

Every routing decision passes through ordered gates. Models that fail any gate are rejected with a documented reason.

Gate	Rejects when
Modality match	Requested modalities aren't subset of model modalities
Context length	Model's context_tokens < requested min_context_tokens
Tool support	requires_tools=true but model lacks tool calling
JSON support	requires_json=true but model can't enforce JSON output
License allowlist	License ID isn't in caller's allowed list
Jurisdictional residency	requires_local=true and jurisdiction not in model residency
Sovereignty tier	High-sensitivity data routed to insufficient tier

Surviving candidates are then scored on:

• Jurisdiction fit (+8)
• Task-type tag match (+7, with +10 for coder specialization, +9 for reasoning)
• Sovereignty bonus for iwi / data sovereignty keywords (+3 × tier)
• Runtime preference (GGUF/llama.cpp gets +2.5)
• Quality rank vs cost rank tradeoff

The router returns the winner plus the full rejection log so you always know why each candidate didn't win.

---

All the ways to run it

Local OpenAI-compatible gateway

MaramaRoute serve --port 8787 --open     # browser console + /v1 endpoints

Endpoints exposed:

• GET /health
• GET /v1/models — OpenAI-shape {"object":"list","data":[…]}
• POST /v1/route — show me which model would handle this
• POST /v1/chat/completions — full OpenAI chat shape, route_only by default

Ask the router which model fits

MaramaRoute route --request examples/request.code-restricted.json

Inspect a single model

MaramaRoute catalog --search starcoder --limit 5
MaramaRoute compare --model lumynax-coder-starcoder2-15b-gguf --model lumynax-coder-qwen25-coder-32b-gguf

Run the built-in sovereignty scenario matrix

MaramaRoute matrix

Emit an OpenCode provider config (drop into ~/.opencode/providers/)

MaramaRoute opencode-config > ~/.opencode/providers/lumynax.json

Drive it from Python

from marama_route import (
    SovereignModelRouter,
    RoutingRequest,
    load_model_registry,
)
from pathlib import Path

models = load_model_registry(Path("./my_registry.json"))
router = SovereignModelRouter(models)

decision = router.route(
    RoutingRequest(
        prompt="Translate this paragraph to te reo Māori",
        task_type="general",
        jurisdiction="NZ",
        data_sensitivity="personal",   # routes only to sovereignty_tier >= 2
        requires_local=True,
    )
)

print(decision.selected_model.model_id)   # e.g. lumynax-translate-nllb-200-3b
print(decision.reasons)                    # human-readable rationale
print(decision.scores)                     # full scorecard

---

Why this exists

LumynaX is built by AbteeX AI Labs in Auckland, Aotearoa New Zealand. Three principles drive the design:

1. Sovereignty over convenience. Every routing decision can be justified to a Māori data-governance reviewer, a privacy officer, or an iwi advisory board. The registry, the routing log, and the policy gates exist for that conversation.

2. Local-first by default. Tier-3+ models run on machines the data owner controls. The router never silently escalates a sensitive request to a remote frontier model.

3. Open weights, open license, open evals. Apache-2.0 on this routing layer. Upstream model licenses surfaced honestly per entry. No vendor lock-in.

Ko te mārama te tūāpapa — clarity is the foundation. Every model card states its provenance. Every routing decision is auditable. Every sovereignty constraint is testable.

---

Companion products

• abteex-sovereigncode — Policy API and audit ledger for coding agents. Pairs with MaramaRoute when you need per-request policy enforcement and tamper-evident logs.
• LumynaX model family — 98 sovereign-tagged model repos on Hugging Face, all routable through MaramaRoute out of the box.
• TinyLuminaX — the heterogeneous MoE research line and training scaffolds.

---

Links

• PyPI: https://pypi.org/project/lumynax-marama-route/
• npm: https://www.npmjs.com/package/lumynax-marama-route
• Hugging Face: https://huggingface.co/AbteeXAILab/marama-route
• GitHub: https://github.com/Aimaghsoodi/lumynax-release
• Website: https://lumynax.com · https://abteex.com

---

License

Apache-2.0 — see LICENSE.

Upstream models retain their own licenses; check each model card before commercial deployment.

---

_{Made in Aotearoa New Zealand by AbteeX AI Labs. Ko te mārama te tūāpapa.}