Metadata-Version: 2.4
Name: lumynax-marama-route
Version: 0.4.0
Summary: LumynaX MaramaRoute: sovereign OpenAI-compatible model router for LumynaX releases.
Author: AbteeX AI Labs
Maintainer: AbteeX AI Labs
License-Expression: Apache-2.0
Project-URL: Homepage, https://lumynax.com
Project-URL: Repository, https://github.com/Aimaghsoodi/TinyLuminaX
Project-URL: Hugging Face, https://huggingface.co/AbteeXAILab/marama-route
Project-URL: Abteex, https://abteex.com
Project-URL: Issues, https://github.com/Aimaghsoodi/TinyLuminaX/issues
Keywords: lumynax,marama-route,model-router,sovereignty,openrouter-alternative,openai-compatible,new-zealand
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5.1; extra == "release"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Dynamic: license-file

---
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
<!-- abteex-marama-route-card:v3 -->

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

## Install

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

HF mirror install:

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

## Included Runtime Commands

```bash
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:

```bash
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:

```bash
py -3 scripts/build_lumynax_marama_route_registry.py
```

Route a request:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

Run the OpenAI-compatible local gateway and browser console:

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

Smoke-check the gateway without opening a browser:

```bash
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:

```bash
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:

```bash
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

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