lumynax-marama-route 0.4.0

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

---

license: apache-2.0 library_name: custom tags:

• abteex-ai-labs
• lumynax
• marama-route
• model-router
• sovereign-ai
• governance
• new-zealand
• aotearoa
• openrouter-alternative
• openai-compatible
• local-first language:
• en
• mi

---

LumynaX MaramaRoute

Standalone release package for PyPI package lumynax-marama-route and Hugging Face repo AbteeXAILab/marama-route, bundled with 98 registry entries.

Install

pip install lumynax-marama-route
marama-route serve --smoke

HF mirror install:

hf download AbteeXAILab/marama-route --local-dir marama-route --repo-type model
cd marama-route
pip install -e .
python quickstart.py

Included Runtime Commands

marama-route serve --smoke
marama-route opencode-config --registry configs/lumynax_model_registry.json
marama-route ui --port 8787 --open
python -m marama_route.cli route --registry configs/lumynax_model_registry.json --request examples/request.code-restricted.json
python -m marama_route.cli models --registry configs/lumynax_model_registry.json
python -m marama_route.cli chat-dry-run --registry configs/lumynax_model_registry.json --request examples/request.openai-chat-code.json
python -m marama_route.cli catalog --registry configs/lumynax_model_registry.json --task code --limit 5
python -m marama_route.cli matrix --registry configs/lumynax_model_registry.json
python -m marama_route.cli opencode-config --registry configs/lumynax_model_registry.json
python -m marama_route.cli ui --smoke
python -m marama_route.cli serve --smoke
python -m marama_route.cli ui --port 8787 --open
python -m marama_route.cli serve --port 8787 --open

LumynaX MaramaRoute

LumynaX MaramaRoute is the proposed sovereign model router for LumynaX releases. It is similar in spirit to OpenRouter, but it is not a general marketplace router. It is a LumynaX-first routing layer that selects models based on sovereignty, residency, license, runtime, modality, task fit, context length, and operational risk.

Product Position

MaramaRoute gives AbteeX AI Labs a single routing surface for the LumynaX model family:

• Local GGUF models.
• MoE and frontier-style LumynaX packages.
• Multimodal LumynaX packages.
• Embedding and retrieval models.
• Reasoning and coding variants.
• Future tenant-specific sovereign models.

Routing Contract

Every request is evaluated through ordered gates:

Gate	Purpose
Capability	Modalities, context length, tool use, JSON mode, task fit.
Sovereignty	Jurisdiction, residency, data sensitivity, local runtime requirement.
License	Optional license allowlist and model-card provenance.
Runtime	llama.cpp, Transformers, embedding, multimodal, or hosted adapter.
Score	Quality, cost, active parameters, task tags, and fallback strength.
Audit	Decision, rejected models, selected model, and fallbacks are recorded.

Quickstart

Install the standalone package:

pip install lumynax-marama-route
marama-route serve --smoke
marama-route serve --port 8787 --open

The same package is mirrored on Hugging Face at AbteeXAILab/marama-route and can be installed from a downloaded snapshot with pip install -e ..

Build or refresh the registry from the latest HF card report:

py -3 scripts/build_lumynax_marama_route_registry.py

Route a request:

py -3 -m tinyluminax.products.marama_route.cli route \
  --registry products/lumynax-marama-route/configs/lumynax_model_registry.json \
  --request products/lumynax-marama-route/examples/request.code-restricted.json

Expected result: a LumynaX coder or Qwen-family GGUF package with New Zealand residency constraints satisfied.

Emit an OpenAI-compatible model list:

py -3 -m tinyluminax.products.marama_route.cli models \
  --registry products/lumynax-marama-route/configs/lumynax_model_registry.json

Dry-run an OpenAI-compatible chat request:

py -3 -m tinyluminax.products.marama_route.cli chat-dry-run \
  --registry products/lumynax-marama-route/configs/lumynax_model_registry.json \
  --request products/lumynax-marama-route/examples/request.openai-chat-code.json

Search the model catalog:

py -3 -m tinyluminax.products.marama_route.cli catalog \
  --registry products/lumynax-marama-route/configs/lumynax_model_registry.json \
  --task code \
  --limit 5

Run the built-in route scenario matrix:

py -3 -m tinyluminax.products.marama_route.cli matrix \
  --registry products/lumynax-marama-route/configs/lumynax_model_registry.json

Emit an OpenCode-compatible provider config:

py -3 -m tinyluminax.products.marama_route.cli opencode-config \
  --registry products/lumynax-marama-route/configs/lumynax_model_registry.json

Run the browser router console:

py -3 -m tinyluminax.products.marama_route.cli ui --port 8787 --open

Run the OpenAI-compatible local gateway and browser console:

py -3 -m tinyluminax.products.marama_route.cli serve --port 8787 --open

Smoke-check the gateway without opening a browser:

py -3 -m tinyluminax.products.marama_route.cli serve --smoke

The gateway exposes GET /health, GET /v1/models, POST /v1/route, and POST /v1/chat/completions. By default it runs in route_only mode and returns an OpenAI-shaped routed response without retaining prompts. Set products/lumynax-marama-route/configs/gateway.local.json to mode: live and map model ids to OpenAI-compatible backends to proxy real generation.

PyPI Release Readiness

The generated standalone package includes pyproject.toml, MANIFEST.in, SMOKE_TESTS.md, PYPI_RELEASE.md, package data, console script entry points, and wheel/sdist validation support. The release gate is:

py -3 scripts/build_product_release_packages.py
py -3 scripts/verify_product_installs.py --product marama-route
py -3 scripts/publish_products_to_pypi.py --product marama-route --dry-run

Smoke-check the UI routes without opening a browser:

py -3 -m tinyluminax.products.marama_route.cli ui --smoke

Product Modules

Module	Purpose
Registry Compiler	Converts HF release reports into a routing registry.
Sovereign Router	Filters and scores model endpoints for each request.
Gateway Adapter	OpenAI-compatible /v1/chat/completions and /v1/models request/response adapter.
Gateway Service	Runs the actual local /health, /v1/models, /v1/route, and /v1/chat/completions API with fail-closed backend configuration.
Catalog Console	Searches, compares, and ranks models by runtime, task fit, context, JSON/tool support, and residency.
Scenario Matrix	Routes code, personal, multimodal, and reasoning workloads through the same deterministic policy.
Provider Exporter	Emits OpenCode/OpenAI-compatible provider JSON for local or hosted MaramaRoute endpoints.
Policy Packs	Tenant-specific jurisdiction, license, and sensitivity rules.
Telemetry Ledger	Stores routing decisions without retaining sensitive prompts by default.

Real Product Surfaces

Surface	File
OpenAI/OpenRouter-style gateway contract	gateway_contract.md
OpenAI chat routing schema	schemas/openai_chat_route_request.schema.json
OpenCode provider example	integrations/opencode-provider.json
Gateway backend config	configs/gateway.local.json
Provider alias and route policy hints	configs/provider_aliases.yaml
OpenAI chat code request example	examples/request.openai-chat-code.json
Browser router console	python -m tinyluminax.products.marama_route.cli ui
Local gateway service	python -m tinyluminax.products.marama_route.cli serve
Catalog search	python -m tinyluminax.products.marama_route.cli catalog
Scenario matrix	python -m tinyluminax.products.marama_route.cli matrix
OpenCode provider export	python -m tinyluminax.products.marama_route.cli opencode-config
Product blueprint	product_blueprint.md

OpenRouter-Like Behaviour

MaramaRoute borrows the useful integration pattern from OpenRouter: one endpoint, many models, normalised response shape, and fallbacks. It differs in product intent:

OpenRouter-like	MaramaRoute-specific
OpenAI-compatible request/response shape	NZ-first residency and sovereignty gates
/v1/models style discovery	LumynaX release registry and provenance metadata
fallback models	fallback models constrained by data sensitivity
router metadata	audit-ready route decisions with prompt retention disabled by default
broad app compatibility	direct use by SovereignCode and other governed tools

Stage

This is a local runtime product surface. The deterministic router, CLI, OpenAI-compatible model listing, chat dry-run routing, catalog/search, model comparison, scenario matrix, provider config export, receipt generation, browser router console, and local OpenAI-compatible gateway are implemented now. Live model generation is available when operator-provided OpenAI-compatible backends are configured; tenant billing/quotas remain a later commercial layer.

LumynaX MaramaRoute Product Blueprint

One-Sentence Product

MaramaRoute is an OpenRouter-style model router for LumynaX releases that gives apps one OpenAI-compatible endpoint while enforcing residency, capability, license, sensitivity, and fallback rules.

Core User Jobs

User	Job	MaramaRoute Response
SovereignCode	Select a resident coding model for a governed workspace.	Code task route with NZ residency and JSON/tool gates.
Internal app	Call one endpoint instead of hard-coding model ids.	/v1/models, /v1/route, and /v1/chat/completions contract.
Operator	Know why a model was selected or rejected.	Route decision with scores, reasons, rejections, and request hash.
Model publisher	Add new LumynaX releases without changing every client.	Registry compiler and aliases.
Enterprise tenant	Restrict models by region, license, runtime, and sensitivity.	Future tenant policy packs and allowlists.

Router Product Pillars

1. One endpoint: OpenAI-compatible clients can point at MaramaRoute.
2. Sovereign default: New Zealand residency is the default route constraint.
3. Model provenance: every selectable model carries repo, artifact, license, runtime, modality, context, and validation metadata.
4. Deterministic audit: decisions are explainable and repeatable for the same registry and request.
5. Runtime independence: route selection is separate from the backend that runs llama.cpp, Transformers, embeddings, speech, or multimodal models.

Minimum Gateway Loop

client sends OpenAI chat request
  -> parse route hints
  -> infer task and modalities
  -> apply capability gates
  -> apply sovereignty and license gates
  -> score accepted models
  -> return selected model and fallbacks
  -> future: invoke runtime adapter
  -> return OpenAI-compatible response with route metadata

Model Alias Strategy

Alias	Intended Use	Route Bias
lumynax/auto	General application calls.	Best resident general model.
lumynax/code	Coding agents and repo work.	Coder tags, JSON support, tool support.
lumynax/reasoning	Planning, analysis, evaluation.	Reasoning tags and stronger quality rank.
lumynax/multimodal	Image plus text requests.	Multimodal runtime and policy-permitted residency.
lumynax/local	Sensitive tenant work.	Local GGUF or resident runtime only.

Runtime Adapters To Build Next

Adapter	Purpose	First Implementation
llama.cpp HTTP	Run GGUF models behind a local or tenant endpoint.	Forward OpenAI chat payload with selected model path.
Transformers	Run safetensors or multimodal packages.	Python worker with model cache and VRAM guard.
Embeddings	Serve retrieval models.	/v1/embeddings compatible response.
Speech	Serve Whisper/Kokoro-style packages.	Separate speech endpoints after text route is stable.
Hosted LumynaX	Private hosted runtime.	Tenant auth, quotas, and audit export.

Commercial Controls

Control	Why it matters
API keys	Required for OpenCode, IDEs, and internal apps.
Tenant quotas	Prevent runaway local or hosted compute spend.
Model allowlists	Keep restricted tenants away from unsuitable models.
Route metadata	Lets customers prove why a model was used.
Prompt retention flag	Supports privacy-sensitive deployments by default.
Registry signing	Prevents silent model substitution.

First Non-Negotiables

• Do not silently route restricted NZ data to a non-resident model.
• Do not pick a model that lacks required modality, JSON, or tool support.
• Do not hide rejection reasons from route metadata.
• Do not retain prompts by default for high-sensitivity routes.
• Do not let runtime adapters substitute models outside the route decision.