Metadata-Version: 2.4
Name: lumynax-marama-route
Version: 0.4.1
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
- ollama-alternative
language:
- en
- mi
---
<!-- abteex-marama-route-card:v4 -->

# 🇳🇿 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.

[![PyPI](https://img.shields.io/pypi/v/lumynax-marama-route.svg?label=PyPI&color=e08a2c)](https://pypi.org/project/lumynax-marama-route/)
[![npm](https://img.shields.io/npm/v/lumynax-marama-route.svg?label=npm&color=cb3837)](https://www.npmjs.com/package/lumynax-marama-route)
[![Hugging Face](https://img.shields.io/badge/🤗-AbteeXAILab%2Fmarama--route-yellow)](https://huggingface.co/AbteeXAILab/marama-route)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

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

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

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

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

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

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

```bash
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`](https://huggingface.co/AbteeXAILab/marama-route) · 98 LumynaX model repos under [`AbteeXAILab`](https://huggingface.co/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

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

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

### Inspect a single model

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

```bash
MaramaRoute matrix
```

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

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

### Drive it from Python

```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`](https://pypi.org/project/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](https://huggingface.co/AbteeXAILab)** — 98 sovereign-tagged model repos on Hugging Face, all routable through MaramaRoute out of the box.
- **[TinyLuminaX](https://github.com/Aimaghsoodi/lumynax-release)** — 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](LICENSE).

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

---

<sub>Made in **Aotearoa New Zealand** by **[AbteeX AI Labs](https://abteex.com)**. *Ko te mārama te tūāpapa.*</sub>
