Publish expanded LumynaX product platform package

MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md LICENSE requirements.txt SMOKE_TESTS.md PYPI_RELEASE.md quickstart.py product_manifest.json product_blueprint.md architecture.md gateway_contract.md
+recursive-include marama_route *.py py.typed
+recursive-include marama_route/configs *
+recursive-include marama_route/examples *
+recursive-include marama_route/integrations *
+recursive-include marama_route/schemas *

PYPI_RELEASE.md

@@ -0,0 +1,30 @@
+# PyPI Release: LumynaX MaramaRoute
+
+Package: `lumynax-marama-route`
+Version: `0.4.0`
+
+## Local Build
+
+```bash
+python -m build
+python -m twine check dist/*
+python quickstart.py
+marama-route serve --smoke
+```
+
+## Publish
+
+```bash
+python -m twine upload dist/*
+```
+
+Required local credentials: `TWINE_USERNAME=__token__` and `TWINE_PASSWORD=<pypi-token>`.
+The GitHub workflow can publish with PyPI trusted publishing when the PyPI project
+is configured to trust `Aimaghsoodi/TinyLuminaX`.
+
+## Runtime Surface
+
+- CLI: `marama-route`
+- Local UI/API: `marama-route serve --port 8787 --open`
+- OpenAI-compatible API: `GET /v1/models`, `POST /v1/route`, `POST /v1/chat/completions`
+- Default mode: route-only, with live OpenAI-compatible backend proxying configured in `configs/gateway.local.json`

README.md

@@ -21,10 +21,17 @@ language:
 # LumynaX MaramaRoute
 <!-- abteex-marama-route-card:v3 -->
 
-Standalone release package for `AbteeXAILab/marama-route`, bundled with 82 registry entries.
+Standalone release package for PyPI package `lumynax-marama-route` and Hugging Face repo `AbteeXAILab/marama-route`, bundled with 82 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
@@ -35,6 +42,9 @@ 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
@@ -77,6 +87,16 @@ Every request is evaluated through ordered gates:
 
 ## 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
@@ -151,6 +171,16 @@ 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

configs/gateway.local.json

@@ -1,13 +1,13 @@
-{
-  "mode": "route_only",
-  "prompt_retention": "not_stored_by_default",
-  "default_timeout_seconds": 120,
-  "backends": {
-    "example-local-openai-compatible": {
-      "type": "openai_compatible",
-      "base_url": "http://127.0.0.1:8000/v1",
-      "api_key_env": "",
-      "model": "local-model-id"
-    }
-  }
-}
+{
+  "mode": "route_only",
+  "prompt_retention": "not_stored_by_default",
+  "default_timeout_seconds": 120,
+  "backends": {
+    "example-local-openai-compatible": {
+      "type": "openai_compatible",
+      "base_url": "http://127.0.0.1:8000/v1",
+      "api_key_env": "",
+      "model": "local-model-id"
+    }
+  }
+}

configs/lumynax_model_registry.json

@@ -2,7 +2,7 @@
   "registry_id": "lumynax-marama-route-registry-v0",
   "publisher": "AbteeX AI Labs",
   "source_report": "docs/releases/hf-model-card-v4-refresh-2026-05-11.json",
-  "model_count": 98,
+  "model_count": 82,
   "models": [
     {
       "model_id": "lumynax-coder-qwen25-05b-instruct-gguf",
@@ -3246,624 +3246,6 @@
         "public_status": "public and non-gated",
         "validation_status": "scaffold_verified"
       }
-    },
-    {
-      "model_id": "lumynax-frontier-coder-qwen3-480b-a35b-gguf",
-      "repo_id": "AbteeXAILab/lumynax-frontier-coder-qwen3-480b-a35b-gguf",
-      "title": "LumynaX Frontier Coder Qwen3 480B A35B GGUF",
-      "family": "coder",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 262144,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "apache-2.0",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "Q4_K_M/Qwen3-Coder-480B-A35B-Instruct-Q4_K_M-00001-of-00006.gguf",
-      "active_params_b": 35,
-      "total_params_b": 480,
-      "quality_rank": 1,
-      "cost_rank": 3,
-      "sovereignty_tier": 2,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "coder",
-        "frontier",
-        "moe",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "Qwen/Qwen3-Coder-480B-A35B-Instruct",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-frontier-coder-deepseek-v25-1210-gguf",
-      "repo_id": "AbteeXAILab/lumynax-frontier-coder-deepseek-v25-1210-gguf",
-      "title": "LumynaX Frontier Coder DeepSeek V2.5-1210 GGUF",
-      "family": "coder",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 163840,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "other",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "DeepSeek-V2.5-1210-Q4_K_M/DeepSeek-V2.5-1210-Q4_K_M-00001-of-00004.gguf",
-      "active_params_b": 21,
-      "total_params_b": 236,
-      "quality_rank": 1,
-      "cost_rank": 3,
-      "sovereignty_tier": 2,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "coder",
-        "frontier",
-        "moe",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "deepseek-ai/DeepSeek-V2.5-1210",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-coder-codellama-70b-instruct-gguf",
-      "repo_id": "AbteeXAILab/lumynax-coder-codellama-70b-instruct-gguf",
-      "title": "LumynaX Coder CodeLlama 70B Instruct GGUF",
-      "family": "codellama",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 16384,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "other",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "codellama-70b-instruct.Q4_K_M.gguf",
-      "active_params_b": null,
-      "total_params_b": 70,
-      "quality_rank": 2,
-      "cost_rank": 3,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "coder",
-        "frontier",
-        "moe",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "codellama/CodeLlama-70b-Instruct-hf",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-coder-deepseek-coder-33b-gguf",
-      "repo_id": "AbteeXAILab/lumynax-coder-deepseek-coder-33b-gguf",
-      "title": "LumynaX Coder DeepSeek-Coder 33B GGUF",
-      "family": "deepseek",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 16384,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "other",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "deepseek-coder-33b-instruct.Q4_K_M.gguf",
-      "active_params_b": null,
-      "total_params_b": 33,
-      "quality_rank": 2,
-      "cost_rank": 3,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "coder",
-        "frontier",
-        "moe",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "deepseek-ai/deepseek-coder-33b-instruct",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-coder-qwen25-coder-32b-gguf",
-      "repo_id": "AbteeXAILab/lumynax-coder-qwen25-coder-32b-gguf",
-      "title": "LumynaX Coder Qwen2.5-Coder 32B Instruct GGUF",
-      "family": "qwen25",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 131072,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "apache-2.0",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf",
-      "active_params_b": null,
-      "total_params_b": 32,
-      "quality_rank": 2,
-      "cost_rank": 3,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "coder",
-        "frontier",
-        "moe",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "Qwen/Qwen2.5-Coder-32B-Instruct",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-coder-starcoder2-15b-gguf",
-      "repo_id": "AbteeXAILab/lumynax-coder-starcoder2-15b-gguf",
-      "title": "LumynaX Coder StarCoder2 15B Instruct GGUF",
-      "family": "starcoder2",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 16384,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "apache-2.0",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "starcoder2-15b-instruct-v0.1-Q4_K_M.gguf",
-      "active_params_b": null,
-      "total_params_b": 15,
-      "quality_rank": 2,
-      "cost_rank": 3,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "coder",
-        "coding",
-        "moe",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "bigcode/starcoder2-15b-instruct-v0.1",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-coder-yi-coder-9b-gguf",
-      "repo_id": "AbteeXAILab/lumynax-coder-yi-coder-9b-gguf",
-      "title": "LumynaX Coder Yi-Coder 9B Chat GGUF",
-      "family": "yi",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 131072,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "other",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "Yi-Coder-9B-Chat-Q4_K_M.gguf",
-      "active_params_b": null,
-      "total_params_b": 9,
-      "quality_rank": 2,
-      "cost_rank": 3,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "coder",
-        "coding",
-        "moe",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "01-ai/Yi-Coder-9B-Chat",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-coder-codeqwen15-7b-chat-gguf",
-      "repo_id": "AbteeXAILab/lumynax-coder-codeqwen15-7b-chat-gguf",
-      "title": "LumynaX Coder CodeQwen1.5 7B Chat GGUF",
-      "family": "codeqwen15",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 65536,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "apache-2.0",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "codeqwen-1_5-7b-chat-q4_k_m.gguf",
-      "active_params_b": null,
-      "total_params_b": 7,
-      "quality_rank": 2,
-      "cost_rank": 3,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "coder",
-        "coding",
-        "moe",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "Qwen/CodeQwen1.5-7B-Chat",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-reasoning-deepseek-prover-v2-671b-gguf",
-      "repo_id": "AbteeXAILab/lumynax-reasoning-deepseek-prover-v2-671b-gguf",
-      "title": "LumynaX Reasoning DeepSeek-Prover V2 671B GGUF",
-      "family": "deepseek",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 163840,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "other",
-      "quantization": "Q4_K_M GGUF (sharded)",
-      "primary_artifact": "Q4_K_M/DeepSeek-Prover-V2-671B-Q4_K_M-00001-of-00009.gguf",
-      "active_params_b": 37,
-      "total_params_b": 671,
-      "quality_rank": 1,
-      "cost_rank": 5,
-      "sovereignty_tier": 2,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "reasoning",
-        "math",
-        "proof",
-        "deepseek",
-        "moe",
-        "gguf",
-        "frontier"
-      ],
-      "metadata": {
-        "upstream_repo": "deepseek-ai/DeepSeek-Prover-V2-671B",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-reasoning-deepseek-r1-distill-llama-70b-gguf",
-      "repo_id": "AbteeXAILab/lumynax-reasoning-deepseek-r1-distill-llama-70b-gguf",
-      "title": "LumynaX Reasoning DeepSeek-R1 Distill Llama 70B GGUF",
-      "family": "deepseek",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 131072,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "llama3.3",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "DeepSeek-R1-Distill-Llama-70B-Q4_K_M.gguf",
-      "active_params_b": null,
-      "total_params_b": 70,
-      "quality_rank": 1,
-      "cost_rank": 4,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "reasoning",
-        "r1-distill",
-        "deepseek",
-        "llama",
-        "gguf",
-        "chain-of-thought"
-      ],
-      "metadata": {
-        "upstream_repo": "deepseek-ai/DeepSeek-R1-Distill-Llama-70B",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-longctx-prolong-512k-instruct",
-      "repo_id": "AbteeXAILab/lumynax-longctx-prolong-512k-instruct",
-      "title": "LumynaX Long-Context ProLong-512K Instruct",
-      "family": "llama",
-      "runtime": "transformers",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 524288,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ",
-        "AU",
-        "global"
-      ],
-      "license_id": "llama3",
-      "quantization": "bf16 safetensors (sharded)",
-      "primary_artifact": "model.safetensors.index.json",
-      "active_params_b": null,
-      "total_params_b": 8,
-      "quality_rank": 2,
-      "cost_rank": 3,
-      "sovereignty_tier": 3,
-      "supports_tools": false,
-      "supports_json": true,
-      "tags": [
-        "long-context",
-        "512k",
-        "prolong",
-        "reasoning"
-      ],
-      "metadata": {
-        "upstream_repo": "princeton-nlp/Llama-3-8B-ProLong-512k-Instruct",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-frontier-phi-35-moe-instruct-gguf",
-      "repo_id": "AbteeXAILab/lumynax-frontier-phi-35-moe-instruct-gguf",
-      "title": "LumynaX Frontier Phi-3.5 MoE Instruct GGUF",
-      "family": "phi",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 131072,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "mit",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "Phi-3.5-MoE-instruct-Q4_K_M.gguf",
-      "active_params_b": 6.6,
-      "total_params_b": 42,
-      "quality_rank": 1,
-      "cost_rank": 2,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "frontier",
-        "moe",
-        "phi",
-        "microsoft",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "microsoft/Phi-3.5-MoE-instruct",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-longctx-yi-9b-200k",
-      "repo_id": "AbteeXAILab/lumynax-longctx-yi-9b-200k",
-      "title": "LumynaX Long-Context Yi-9B 200K",
-      "family": "yi",
-      "runtime": "transformers",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 204800,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ",
-        "AU",
-        "global"
-      ],
-      "license_id": "apache-2.0",
-      "quantization": "bf16 safetensors (sharded)",
-      "primary_artifact": "model.safetensors.index.json",
-      "active_params_b": null,
-      "total_params_b": 9,
-      "quality_rank": 2,
-      "cost_rank": 3,
-      "sovereignty_tier": 3,
-      "supports_tools": false,
-      "supports_json": true,
-      "tags": [
-        "long-context",
-        "200k",
-        "yi"
-      ],
-      "metadata": {
-        "upstream_repo": "01-ai/Yi-9B-200K",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-longctx-glm4-9b-chat-1m-gguf",
-      "repo_id": "AbteeXAILab/lumynax-longctx-glm4-9b-chat-1m-gguf",
-      "title": "LumynaX Long-Context GLM-4-9B-Chat-1M GGUF",
-      "family": "glm",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 1048576,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "apache-2.0",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "glm-4-9b-chat-1m-Q4_K_M.gguf",
-      "active_params_b": null,
-      "total_params_b": 9,
-      "quality_rank": 2,
-      "cost_rank": 2,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "long-context",
-        "1m",
-        "glm",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "THUDM/glm-4-9b-chat-1m",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-longctx-qwen25-7b-1m-gguf",
-      "repo_id": "AbteeXAILab/lumynax-longctx-qwen25-7b-1m-gguf",
-      "title": "LumynaX Long-Context Qwen2.5 7B Instruct 1M GGUF",
-      "family": "qwen",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 1048576,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "apache-2.0",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "Qwen2.5-7B-Instruct-1M-Q4_K_M.gguf",
-      "active_params_b": null,
-      "total_params_b": 7,
-      "quality_rank": 2,
-      "cost_rank": 2,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "long-context",
-        "1m",
-        "qwen",
-        "gguf"
-      ],
-      "metadata": {
-        "upstream_repo": "Qwen/Qwen2.5-7B-Instruct-1M",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
-    },
-    {
-      "model_id": "lumynax-moe-olmoe-1b-7b-0924-instruct-gguf",
-      "repo_id": "AbteeXAILab/lumynax-moe-olmoe-1b-7b-0924-instruct-gguf",
-      "title": "LumynaX MoE OLMoE 1B/7B 0924 Instruct GGUF",
-      "family": "olmo",
-      "runtime": "llama_cpp",
-      "modalities": [
-        "text"
-      ],
-      "context_tokens": 4096,
-      "jurisdiction": "NZ",
-      "residency": [
-        "NZ"
-      ],
-      "license_id": "apache-2.0",
-      "quantization": "Q4_K_M GGUF",
-      "primary_artifact": "OLMoE-1B-7B-0924-Instruct-Q4_K_M.gguf",
-      "active_params_b": 1,
-      "total_params_b": 7,
-      "quality_rank": 2,
-      "cost_rank": 1,
-      "sovereignty_tier": 3,
-      "supports_tools": true,
-      "supports_json": true,
-      "tags": [
-        "moe",
-        "olmoe",
-        "fully-open",
-        "gguf",
-        "allenai"
-      ],
-      "metadata": {
-        "upstream_repo": "allenai/OLMoE-1B-7B-0924-Instruct",
-        "release_version": "v0.1.0",
-        "package_state": "weights_mirrored",
-        "public_status": "public and non-gated",
-        "validation_status": "scaffold_verified"
-      }
     }
   ]
 }

marama_route/__init__.py

@@ -1,40 +1,40 @@
-from __future__ import annotations
-
-from .gateway import (
-    build_chat_route_response,
-    build_models_response,
-    route_chat_payload,
-    routing_request_from_chat_payload,
-)
-from .platform import (
-    build_opencode_provider_config,
-    build_registry_analytics,
-    catalog_models,
-    compare_models,
-    route_scenario_matrix,
-)
-from .registry import ModelEndpoint, RoutingRequest, load_model_registry
-from .router import RouteDecision, SovereignModelRouter
-from .server import handle_gateway_request, load_gateway_config, smoke_gateway
-from .ui import smoke_ui as smoke_ui
-
-__all__ = [
-    "ModelEndpoint",
-    "RouteDecision",
-    "RoutingRequest",
-    "SovereignModelRouter",
-    "build_chat_route_response",
-    "build_models_response",
-    "build_opencode_provider_config",
-    "build_registry_analytics",
-    "catalog_models",
-    "compare_models",
-    "handle_gateway_request",
-    "load_gateway_config",
-    "load_model_registry",
-    "route_chat_payload",
-    "route_scenario_matrix",
-    "routing_request_from_chat_payload",
-    "smoke_gateway",
-    "smoke_ui",
-]
+from __future__ import annotations
+
+from .gateway import (
+    build_chat_route_response,
+    build_models_response,
+    route_chat_payload,
+    routing_request_from_chat_payload,
+)
+from .platform import (
+    build_opencode_provider_config,
+    build_registry_analytics,
+    catalog_models,
+    compare_models,
+    route_scenario_matrix,
+)
+from .registry import ModelEndpoint, RoutingRequest, load_model_registry
+from .router import RouteDecision, SovereignModelRouter
+from .server import handle_gateway_request, load_gateway_config, smoke_gateway
+from .ui import smoke_ui as smoke_ui
+
+__all__ = [
+    "ModelEndpoint",
+    "RouteDecision",
+    "RoutingRequest",
+    "SovereignModelRouter",
+    "build_chat_route_response",
+    "build_models_response",
+    "build_opencode_provider_config",
+    "build_registry_analytics",
+    "catalog_models",
+    "compare_models",
+    "handle_gateway_request",
+    "load_gateway_config",
+    "load_model_registry",
+    "route_chat_payload",
+    "route_scenario_matrix",
+    "routing_request_from_chat_payload",
+    "smoke_gateway",
+    "smoke_ui",
+]

marama_route/_ui_server.py

@@ -1,121 +1,121 @@
-from __future__ import annotations
-
-import json
-import socket
-import webbrowser
-from collections.abc import Callable
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from typing import Any
-from urllib.parse import urlparse
-
-ApiHandler = Callable[[str, str, dict[str, Any] | None], tuple[int, dict[str, Any]]]
-
-
-def find_available_port(host: str, preferred_port: int, *, attempts: int = 50) -> int:
-    start = preferred_port if preferred_port > 0 else 0
-    if start == 0:
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
-            probe.bind((host, 0))
-            return int(probe.getsockname()[1])
-
-    for port in range(start, start + attempts):
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
-            probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-            try:
-                probe.bind((host, port))
-            except OSError:
-                continue
-            return port
-    raise OSError(f"No available port found from {preferred_port} to {preferred_port + attempts - 1}")
-
-
-def serve_dashboard(
-    *,
-    product_name: str,
-    html: str,
-    api_handler: ApiHandler,
-    host: str,
-    port: int,
-    open_browser: bool = False,
-    api_path_prefixes: tuple[str, ...] = ("/api/",),
-    api_exact_paths: tuple[str, ...] = (),
-) -> int:
-    actual_port = find_available_port(host, port)
-    exact_paths = set(api_exact_paths)
-
-    def is_api_path(path: str) -> bool:
-        return path in exact_paths or any(path.startswith(prefix) for prefix in api_path_prefixes)
-
-    class Handler(BaseHTTPRequestHandler):
-        server_version = "AbteeXProductUI/0.1"
-
-        def do_GET(self) -> None:  # noqa: N802 - stdlib handler method name
-            path = urlparse(self.path).path
-            if path == "/":
-                self._send_text(200, html, "text/html; charset=utf-8")
-                return
-            if is_api_path(path):
-                self._send_api("GET", path, None)
-                return
-            self._send_json(404, {"ok": False, "error": "not_found"})
-
-        def do_POST(self) -> None:  # noqa: N802 - stdlib handler method name
-            path = urlparse(self.path).path
-            if not is_api_path(path):
-                self._send_json(404, {"ok": False, "error": "not_found"})
-                return
-            try:
-                length = int(self.headers.get("Content-Length", "0"))
-                raw = self.rfile.read(length).decode("utf-8") if length else "{}"
-                payload = json.loads(raw)
-                if not isinstance(payload, dict):
-                    raise ValueError("JSON body must be an object")
-                self._send_api("POST", path, payload)
-            except Exception as exc:  # defensive API boundary
-                self._send_json(400, {"ok": False, "error": str(exc)})
-
-        def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
-            return
-
-        def _send_api(
-            self,
-            method: str,
-            path: str,
-            payload: dict[str, Any] | None,
-        ) -> None:
-            try:
-                status, response = api_handler(method, path, payload)
-            except Exception as exc:  # defensive API boundary
-                status, response = 500, {"ok": False, "error": str(exc)}
-            self._send_json(status, response)
-
-        def _send_json(self, status: int, payload: dict[str, Any]) -> None:
-            body = json.dumps(payload, indent=2, sort_keys=True).encode("utf-8")
-            self.send_response(status)
-            self.send_header("Content-Type", "application/json; charset=utf-8")
-            self.send_header("Content-Length", str(len(body)))
-            self.send_header("Cache-Control", "no-store")
-            self.end_headers()
-            self.wfile.write(body)
-
-        def _send_text(self, status: int, body: str, content_type: str) -> None:
-            encoded = body.encode("utf-8")
-            self.send_response(status)
-            self.send_header("Content-Type", content_type)
-            self.send_header("Content-Length", str(len(encoded)))
-            self.send_header("Cache-Control", "no-store")
-            self.end_headers()
-            self.wfile.write(encoded)
-
-    server = ThreadingHTTPServer((host, actual_port), Handler)
-    url = f"http://{host}:{actual_port}/"
-    print(f"{product_name} UI listening on {url}")
-    if open_browser:
-        webbrowser.open(url)
-    try:
-        server.serve_forever()
-    except KeyboardInterrupt:
-        print(f"{product_name} UI stopped")
-    finally:
-        server.server_close()
-    return 0
+from __future__ import annotations
+
+import json
+import socket
+import webbrowser
+from collections.abc import Callable
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+from urllib.parse import urlparse
+
+ApiHandler = Callable[[str, str, dict[str, Any] | None], tuple[int, dict[str, Any]]]
+
+
+def find_available_port(host: str, preferred_port: int, *, attempts: int = 50) -> int:
+    start = preferred_port if preferred_port > 0 else 0
+    if start == 0:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            probe.bind((host, 0))
+            return int(probe.getsockname()[1])
+
+    for port in range(start, start + attempts):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                probe.bind((host, port))
+            except OSError:
+                continue
+            return port
+    raise OSError(f"No available port found from {preferred_port} to {preferred_port + attempts - 1}")
+
+
+def serve_dashboard(
+    *,
+    product_name: str,
+    html: str,
+    api_handler: ApiHandler,
+    host: str,
+    port: int,
+    open_browser: bool = False,
+    api_path_prefixes: tuple[str, ...] = ("/api/",),
+    api_exact_paths: tuple[str, ...] = (),
+) -> int:
+    actual_port = find_available_port(host, port)
+    exact_paths = set(api_exact_paths)
+
+    def is_api_path(path: str) -> bool:
+        return path in exact_paths or any(path.startswith(prefix) for prefix in api_path_prefixes)
+
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "AbteeXProductUI/0.1"
+
+        def do_GET(self) -> None:  # noqa: N802 - stdlib handler method name
+            path = urlparse(self.path).path
+            if path == "/":
+                self._send_text(200, html, "text/html; charset=utf-8")
+                return
+            if is_api_path(path):
+                self._send_api("GET", path, None)
+                return
+            self._send_json(404, {"ok": False, "error": "not_found"})
+
+        def do_POST(self) -> None:  # noqa: N802 - stdlib handler method name
+            path = urlparse(self.path).path
+            if not is_api_path(path):
+                self._send_json(404, {"ok": False, "error": "not_found"})
+                return
+            try:
+                length = int(self.headers.get("Content-Length", "0"))
+                raw = self.rfile.read(length).decode("utf-8") if length else "{}"
+                payload = json.loads(raw)
+                if not isinstance(payload, dict):
+                    raise ValueError("JSON body must be an object")
+                self._send_api("POST", path, payload)
+            except Exception as exc:  # defensive API boundary
+                self._send_json(400, {"ok": False, "error": str(exc)})
+
+        def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+            return
+
+        def _send_api(
+            self,
+            method: str,
+            path: str,
+            payload: dict[str, Any] | None,
+        ) -> None:
+            try:
+                status, response = api_handler(method, path, payload)
+            except Exception as exc:  # defensive API boundary
+                status, response = 500, {"ok": False, "error": str(exc)}
+            self._send_json(status, response)
+
+        def _send_json(self, status: int, payload: dict[str, Any]) -> None:
+            body = json.dumps(payload, indent=2, sort_keys=True).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _send_text(self, status: int, body: str, content_type: str) -> None:
+            encoded = body.encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(encoded)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(encoded)
+
+    server = ThreadingHTTPServer((host, actual_port), Handler)
+    url = f"http://{host}:{actual_port}/"
+    print(f"{product_name} UI listening on {url}")
+    if open_browser:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print(f"{product_name} UI stopped")
+    finally:
+        server.server_close()
+    return 0

marama_route/cli.py

@@ -1,233 +1,233 @@
-from __future__ import annotations
-
-import argparse
-import json
-from collections.abc import Sequence
-from pathlib import Path
-from typing import Any
-
-from .gateway import build_models_response, route_chat_payload
-from .platform import (
-    build_opencode_provider_config,
-    build_registry_analytics,
-    catalog_models,
-    compare_models,
-    route_scenario_matrix,
-)
-from .registry import RoutingRequest, load_model_registry
-from .router import SovereignModelRouter
-
-
-def _load_json_mapping(path: Path) -> dict[str, Any]:
-    payload = json.loads(path.read_text(encoding="utf-8-sig"))
-    if not isinstance(payload, dict):
-        raise ValueError(f"Expected mapping in {path}")
-    return payload
-
-
-def _route(args: argparse.Namespace) -> int:
-    models = load_model_registry(args.registry)
-    payload = _load_json_mapping(args.request)
-    decision = SovereignModelRouter(models).route(RoutingRequest.from_payload(payload))
-    print(json.dumps(decision.to_dict(), indent=2, sort_keys=True))
-    return 0 if decision.selected_model is not None else 2
-
-
-def _models(args: argparse.Namespace) -> int:
-    models = load_model_registry(args.registry)
-    print(json.dumps(build_models_response(models), indent=2, sort_keys=True))
-    return 0
-
-
-def _chat_dry_run(args: argparse.Namespace) -> int:
-    models = load_model_registry(args.registry)
-    payload = _load_json_mapping(args.request)
-    result = route_chat_payload(payload, models)
-    print(json.dumps(result, indent=2, sort_keys=True))
-    selected = result["route_decision"]["selected_model"]
-    return 0 if selected is not None else 2
-
-
-def _catalog(args: argparse.Namespace) -> int:
-    models = load_model_registry(args.registry)
-    result = catalog_models(
-        models,
-        {
-            "search": args.search,
-            "task_type": args.task,
-            "runtime": args.runtime,
-            "modality": args.modality,
-            "jurisdiction": args.jurisdiction,
-            "min_context_tokens": args.min_context_tokens,
-            "requires_json": args.requires_json,
-            "requires_tools": args.requires_tools,
-            "requires_local": args.requires_local,
-            "limit": args.limit,
-        },
-    )
-    print(json.dumps(result, indent=2, sort_keys=True))
-    return 0
-
-
-def _compare(args: argparse.Namespace) -> int:
-    models = load_model_registry(args.registry)
-    model_ids = [item.strip() for value in args.model for item in value.split(",") if item.strip()]
-    request = _load_json_mapping(args.request) if args.request else None
-    result = compare_models(models, model_ids, request)
-    print(json.dumps(result, indent=2, sort_keys=True))
-    return 0 if result["ok"] else 2
-
-
-def _matrix(args: argparse.Namespace) -> int:
-    models = load_model_registry(args.registry)
-    result = route_scenario_matrix(models)
-    print(json.dumps(result, indent=2, sort_keys=True))
-    return 0 if result["ok"] or args.allow_blocked_exit_zero else 2
-
-
-def _analytics(args: argparse.Namespace) -> int:
-    print(json.dumps(build_registry_analytics(load_model_registry(args.registry)), indent=2, sort_keys=True))
-    return 0
-
-
-def _opencode_config(args: argparse.Namespace) -> int:
-    models = load_model_registry(args.registry)
-    result = build_opencode_provider_config(models, base_url=args.base_url)
-    print(json.dumps(result, indent=2, sort_keys=True))
-    return 0
-
-
-def _ui(args: argparse.Namespace) -> int:
-    from .ui import run_ui
-
-    return run_ui(
-        registry_path=args.registry,
-        host=args.host,
-        port=args.port,
-        open_browser=args.open,
-        smoke=args.smoke,
-    )
-
-
-def _serve(args: argparse.Namespace) -> int:
-    from .server import serve_gateway
-
-    return serve_gateway(
-        registry_path=args.registry,
-        config_path=args.config,
-        host=args.host,
-        port=args.port,
-        open_browser=args.open,
-        smoke=args.smoke,
-    )
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="lumynax-marama-route",
-        description="Route requests across LumynaX sovereign model releases.",
-    )
-    subparsers = parser.add_subparsers(dest="command")
-    route = subparsers.add_parser("route", help="Select a LumynaX model for a request.")
-    route.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
-    route.add_argument("--request", type=Path, required=True, help="Routing request JSON.")
-    route.set_defaults(handler=_route)
-
-    models = subparsers.add_parser(
-        "models",
-        help="Emit an OpenAI-compatible /v1/models response.",
-    )
-    models.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
-    models.set_defaults(handler=_models)
-
-    chat = subparsers.add_parser(
-        "chat-dry-run",
-        help="Route an OpenAI-compatible chat request without invoking a backend.",
-    )
-    chat.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
-    chat.add_argument("--request", type=Path, required=True, help="OpenAI chat request JSON.")
-    chat.set_defaults(handler=_chat_dry_run)
-
-    catalog = subparsers.add_parser(
-        "catalog",
-        help="Search and filter the MaramaRoute model catalog.",
-    )
-    catalog.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
-    catalog.add_argument("--search", default="")
-    catalog.add_argument("--task", default="")
-    catalog.add_argument("--runtime", default="")
-    catalog.add_argument("--modality", default="")
-    catalog.add_argument("--jurisdiction", default="NZ")
-    catalog.add_argument("--min-context-tokens", type=int, default=0)
-    catalog.add_argument("--requires-json", action=argparse.BooleanOptionalAction, default=False)
-    catalog.add_argument("--requires-tools", action=argparse.BooleanOptionalAction, default=False)
-    catalog.add_argument("--requires-local", action=argparse.BooleanOptionalAction, default=False)
-    catalog.add_argument("--limit", type=int, default=25)
-    catalog.set_defaults(handler=_catalog)
-
-    compare = subparsers.add_parser(
-        "compare",
-        help="Compare routed fit for selected model ids.",
-    )
-    compare.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
-    compare.add_argument("--model", action="append", required=True, help="Model id, repeatable or comma-separated.")
-    compare.add_argument("--request", type=Path, default=None, help="Optional routing request JSON.")
-    compare.set_defaults(handler=_compare)
-
-    matrix = subparsers.add_parser(
-        "matrix",
-        help="Run the built-in sovereign routing scenario matrix.",
-    )
-    matrix.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
-    matrix.add_argument("--allow-blocked-exit-zero", action=argparse.BooleanOptionalAction, default=False)
-    matrix.set_defaults(handler=_matrix)
-
-    analytics = subparsers.add_parser("analytics", help="Summarise registry coverage.")
-    analytics.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
-    analytics.set_defaults(handler=_analytics)
-
-    opencode = subparsers.add_parser(
-        "opencode-config",
-        help="Emit an OpenCode-compatible MaramaRoute provider config.",
-    )
-    opencode.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
-    opencode.add_argument("--base-url", default="http://127.0.0.1:8787/v1")
-    opencode.set_defaults(handler=_opencode_config)
-
-    ui = subparsers.add_parser(
-        "ui",
-        help="Launch the local MaramaRoute browser platform.",
-    )
-    ui.add_argument("--registry", type=Path, default=None, help="MaramaRoute model registry JSON.")
-    ui.add_argument("--host", type=str, default="127.0.0.1")
-    ui.add_argument("--port", type=int, default=8787)
-    ui.add_argument("--open", action=argparse.BooleanOptionalAction, default=False)
-    ui.add_argument("--smoke", action=argparse.BooleanOptionalAction, default=False)
-    ui.set_defaults(handler=_ui)
-
-    serve = subparsers.add_parser(
-        "serve",
-        help="Run the local OpenAI-compatible MaramaRoute gateway and browser console.",
-    )
-    serve.add_argument("--registry", type=Path, default=None, help="MaramaRoute model registry JSON.")
-    serve.add_argument("--config", type=Path, default=None, help="Gateway backend config JSON.")
-    serve.add_argument("--host", type=str, default="127.0.0.1")
-    serve.add_argument("--port", type=int, default=8787)
-    serve.add_argument("--open", action=argparse.BooleanOptionalAction, default=False)
-    serve.add_argument("--smoke", action=argparse.BooleanOptionalAction, default=False)
-    serve.set_defaults(handler=_serve)
-    return parser
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    parser = build_parser()
-    args = parser.parse_args(argv)
-    handler = getattr(args, "handler", None)
-    if handler is None:
-        parser.print_help()
-        return 0
-    return int(handler(args))
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from .gateway import build_models_response, route_chat_payload
+from .platform import (
+    build_opencode_provider_config,
+    build_registry_analytics,
+    catalog_models,
+    compare_models,
+    route_scenario_matrix,
+)
+from .registry import RoutingRequest, load_model_registry
+from .router import SovereignModelRouter
+
+
+def _load_json_mapping(path: Path) -> dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8-sig"))
+    if not isinstance(payload, dict):
+        raise ValueError(f"Expected mapping in {path}")
+    return payload
+
+
+def _route(args: argparse.Namespace) -> int:
+    models = load_model_registry(args.registry)
+    payload = _load_json_mapping(args.request)
+    decision = SovereignModelRouter(models).route(RoutingRequest.from_payload(payload))
+    print(json.dumps(decision.to_dict(), indent=2, sort_keys=True))
+    return 0 if decision.selected_model is not None else 2
+
+
+def _models(args: argparse.Namespace) -> int:
+    models = load_model_registry(args.registry)
+    print(json.dumps(build_models_response(models), indent=2, sort_keys=True))
+    return 0
+
+
+def _chat_dry_run(args: argparse.Namespace) -> int:
+    models = load_model_registry(args.registry)
+    payload = _load_json_mapping(args.request)
+    result = route_chat_payload(payload, models)
+    print(json.dumps(result, indent=2, sort_keys=True))
+    selected = result["route_decision"]["selected_model"]
+    return 0 if selected is not None else 2
+
+
+def _catalog(args: argparse.Namespace) -> int:
+    models = load_model_registry(args.registry)
+    result = catalog_models(
+        models,
+        {
+            "search": args.search,
+            "task_type": args.task,
+            "runtime": args.runtime,
+            "modality": args.modality,
+            "jurisdiction": args.jurisdiction,
+            "min_context_tokens": args.min_context_tokens,
+            "requires_json": args.requires_json,
+            "requires_tools": args.requires_tools,
+            "requires_local": args.requires_local,
+            "limit": args.limit,
+        },
+    )
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0
+
+
+def _compare(args: argparse.Namespace) -> int:
+    models = load_model_registry(args.registry)
+    model_ids = [item.strip() for value in args.model for item in value.split(",") if item.strip()]
+    request = _load_json_mapping(args.request) if args.request else None
+    result = compare_models(models, model_ids, request)
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0 if result["ok"] else 2
+
+
+def _matrix(args: argparse.Namespace) -> int:
+    models = load_model_registry(args.registry)
+    result = route_scenario_matrix(models)
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0 if result["ok"] or args.allow_blocked_exit_zero else 2
+
+
+def _analytics(args: argparse.Namespace) -> int:
+    print(json.dumps(build_registry_analytics(load_model_registry(args.registry)), indent=2, sort_keys=True))
+    return 0
+
+
+def _opencode_config(args: argparse.Namespace) -> int:
+    models = load_model_registry(args.registry)
+    result = build_opencode_provider_config(models, base_url=args.base_url)
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0
+
+
+def _ui(args: argparse.Namespace) -> int:
+    from .ui import run_ui
+
+    return run_ui(
+        registry_path=args.registry,
+        host=args.host,
+        port=args.port,
+        open_browser=args.open,
+        smoke=args.smoke,
+    )
+
+
+def _serve(args: argparse.Namespace) -> int:
+    from .server import serve_gateway
+
+    return serve_gateway(
+        registry_path=args.registry,
+        config_path=args.config,
+        host=args.host,
+        port=args.port,
+        open_browser=args.open,
+        smoke=args.smoke,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="lumynax-marama-route",
+        description="Route requests across LumynaX sovereign model releases.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+    route = subparsers.add_parser("route", help="Select a LumynaX model for a request.")
+    route.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
+    route.add_argument("--request", type=Path, required=True, help="Routing request JSON.")
+    route.set_defaults(handler=_route)
+
+    models = subparsers.add_parser(
+        "models",
+        help="Emit an OpenAI-compatible /v1/models response.",
+    )
+    models.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
+    models.set_defaults(handler=_models)
+
+    chat = subparsers.add_parser(
+        "chat-dry-run",
+        help="Route an OpenAI-compatible chat request without invoking a backend.",
+    )
+    chat.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
+    chat.add_argument("--request", type=Path, required=True, help="OpenAI chat request JSON.")
+    chat.set_defaults(handler=_chat_dry_run)
+
+    catalog = subparsers.add_parser(
+        "catalog",
+        help="Search and filter the MaramaRoute model catalog.",
+    )
+    catalog.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
+    catalog.add_argument("--search", default="")
+    catalog.add_argument("--task", default="")
+    catalog.add_argument("--runtime", default="")
+    catalog.add_argument("--modality", default="")
+    catalog.add_argument("--jurisdiction", default="NZ")
+    catalog.add_argument("--min-context-tokens", type=int, default=0)
+    catalog.add_argument("--requires-json", action=argparse.BooleanOptionalAction, default=False)
+    catalog.add_argument("--requires-tools", action=argparse.BooleanOptionalAction, default=False)
+    catalog.add_argument("--requires-local", action=argparse.BooleanOptionalAction, default=False)
+    catalog.add_argument("--limit", type=int, default=25)
+    catalog.set_defaults(handler=_catalog)
+
+    compare = subparsers.add_parser(
+        "compare",
+        help="Compare routed fit for selected model ids.",
+    )
+    compare.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
+    compare.add_argument("--model", action="append", required=True, help="Model id, repeatable or comma-separated.")
+    compare.add_argument("--request", type=Path, default=None, help="Optional routing request JSON.")
+    compare.set_defaults(handler=_compare)
+
+    matrix = subparsers.add_parser(
+        "matrix",
+        help="Run the built-in sovereign routing scenario matrix.",
+    )
+    matrix.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
+    matrix.add_argument("--allow-blocked-exit-zero", action=argparse.BooleanOptionalAction, default=False)
+    matrix.set_defaults(handler=_matrix)
+
+    analytics = subparsers.add_parser("analytics", help="Summarise registry coverage.")
+    analytics.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
+    analytics.set_defaults(handler=_analytics)
+
+    opencode = subparsers.add_parser(
+        "opencode-config",
+        help="Emit an OpenCode-compatible MaramaRoute provider config.",
+    )
+    opencode.add_argument("--registry", type=Path, required=True, help="MaramaRoute model registry JSON.")
+    opencode.add_argument("--base-url", default="http://127.0.0.1:8787/v1")
+    opencode.set_defaults(handler=_opencode_config)
+
+    ui = subparsers.add_parser(
+        "ui",
+        help="Launch the local MaramaRoute browser platform.",
+    )
+    ui.add_argument("--registry", type=Path, default=None, help="MaramaRoute model registry JSON.")
+    ui.add_argument("--host", type=str, default="127.0.0.1")
+    ui.add_argument("--port", type=int, default=8787)
+    ui.add_argument("--open", action=argparse.BooleanOptionalAction, default=False)
+    ui.add_argument("--smoke", action=argparse.BooleanOptionalAction, default=False)
+    ui.set_defaults(handler=_ui)
+
+    serve = subparsers.add_parser(
+        "serve",
+        help="Run the local OpenAI-compatible MaramaRoute gateway and browser console.",
+    )
+    serve.add_argument("--registry", type=Path, default=None, help="MaramaRoute model registry JSON.")
+    serve.add_argument("--config", type=Path, default=None, help="Gateway backend config JSON.")
+    serve.add_argument("--host", type=str, default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8787)
+    serve.add_argument("--open", action=argparse.BooleanOptionalAction, default=False)
+    serve.add_argument("--smoke", action=argparse.BooleanOptionalAction, default=False)
+    serve.set_defaults(handler=_serve)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help()
+        return 0
+    return int(handler(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

marama_route/configs/gateway.local.json

@@ -1,13 +1,13 @@
-{
-  "mode": "route_only",
-  "prompt_retention": "not_stored_by_default",
-  "default_timeout_seconds": 120,
-  "backends": {
-    "example-local-openai-compatible": {
-      "type": "openai_compatible",
-      "base_url": "http://127.0.0.1:8000/v1",
-      "api_key_env": "",
-      "model": "local-model-id"
-    }
-  }
-}
+{
+  "mode": "route_only",
+  "prompt_retention": "not_stored_by_default",
+  "default_timeout_seconds": 120,
+  "backends": {
+    "example-local-openai-compatible": {
+      "type": "openai_compatible",
+      "base_url": "http://127.0.0.1:8000/v1",
+      "api_key_env": "",
+      "model": "local-model-id"
+    }
+  }
+}

marama_route/server.py

@@ -1,312 +1,312 @@
-from __future__ import annotations
-
-import json
-import os
-import tempfile
-import urllib.error
-import urllib.request
-from pathlib import Path
-from typing import Any
-
-try:  # repo package
-    from tinyluminax.products._ui_server import serve_dashboard
-except ModuleNotFoundError:  # standalone HF package
-    from ._ui_server import serve_dashboard
-
-from .gateway import route_chat_payload
-from .platform import build_models_api, route_or_chat_payload, route_receipt
-from .registry import load_model_registry
-from .ui import (
-    PRODUCT_NAME,
-    build_dashboard_state,
-    build_expanded_dashboard_html,
-    default_openai_chat_request_path,
-    default_registry_path,
-    handle_api_request,
-    load_json_mapping,
-)
-
-PACKAGE_ROOT = Path(__file__).resolve().parent
-PACKAGE_PARENT = PACKAGE_ROOT.parent
-
-DEFAULT_GATEWAY_CONFIG: dict[str, Any] = {
-    "mode": "route_only",
-    "prompt_retention": "not_stored_by_default",
-    "default_timeout_seconds": 120,
-    "backends": {},
-}
-
-
-def default_gateway_config_path() -> Path:
-    candidates = [
-        Path.cwd() / "products" / "lumynax-marama-route" / "configs" / "gateway.local.json",
-        Path.cwd() / "configs" / "gateway.local.json",
-        PACKAGE_ROOT / "configs" / "gateway.local.json",
-        PACKAGE_PARENT / "configs" / "gateway.local.json",
-    ]
-    for path in candidates:
-        if path.exists():
-            return path
-    return candidates[0]
-
-
-def default_route_request_path() -> Path:
-    candidates = [
-        Path.cwd() / "products" / "lumynax-marama-route" / "examples" / "request.code-restricted.json",
-        Path.cwd() / "examples" / "request.code-restricted.json",
-        PACKAGE_ROOT / "examples" / "request.code-restricted.json",
-        PACKAGE_PARENT / "examples" / "request.code-restricted.json",
-    ]
-    for path in candidates:
-        if path.exists():
-            return path
-    return candidates[0]
-
-
-def load_gateway_config(path: Path | None = None) -> dict[str, Any]:
-    config = dict(DEFAULT_GATEWAY_CONFIG)
-    config["backends"] = dict(DEFAULT_GATEWAY_CONFIG["backends"])
-    resolved = path or default_gateway_config_path()
-    if resolved.exists():
-        payload = json.loads(resolved.read_text(encoding="utf-8-sig"))
-        if not isinstance(payload, dict):
-            raise ValueError(f"Expected gateway config object in {resolved}")
-        config.update(payload)
-        config["backends"] = dict(payload.get("backends") or {})
-    config["config_path"] = str(resolved)
-    return config
-
-
-def handle_gateway_request(
-    method: str,
-    path: str,
-    payload: dict[str, Any] | None,
-    registry_path: Path,
-    config_path: Path | None = None,
-) -> tuple[int, dict[str, Any]]:
-    models = load_model_registry(registry_path)
-    config = load_gateway_config(config_path)
-
-    if path.startswith("/api/"):
-        return handle_api_request(method, path, payload, registry_path)
-    if method == "GET" and path in {"/health", "/v1/health"}:
-        return 200, {
-            "ok": True,
-            "product": PRODUCT_NAME,
-            "mode": config["mode"],
-            "model_count": len(models),
-            "configured_backends": len(config.get("backends") or {}),
-            "prompt_retention": config.get("prompt_retention", "not_stored_by_default"),
-        }
-    if method == "GET" and path == "/v1/models":
-        return 200, build_models_api(models)
-    if method == "POST" and path == "/v1/route" and payload is not None:
-        result = route_or_chat_payload(payload, models)
-        return (200 if result["ok"] else 422), result
-    if method == "POST" and path == "/v1/chat/completions" and payload is not None:
-        return chat_completion_gateway(payload, models, config)
-    return 404, {"ok": False, "error": "not_found"}
-
-
-def chat_completion_gateway(
-    payload: dict[str, Any],
-    models: tuple[Any, ...],
-    config: dict[str, Any],
-) -> tuple[int, dict[str, Any]]:
-    route_result = route_chat_payload(payload, models)
-    decision = route_result["route_decision"]
-    selected = decision.get("selected_model")
-    if not isinstance(selected, dict):
-        return 422, {"ok": False, "error": "no_eligible_model", **route_result}
-
-    receipt = route_receipt(payload, route_result)
-    dry_run = bool(
-        payload.get("dry_run")
-        or payload.get("marama_route_dry_run")
-        or config.get("mode", "route_only") == "route_only"
-    )
-    if dry_run:
-        response = dict(route_result["chat_completion_response"])
-        response["marama_route"] = dict(response["marama_route"])
-        response["marama_route"].update(
-            {
-                "backend_mode": "route_only",
-                "receipt": receipt,
-                "prompt_retention": config.get("prompt_retention", "not_stored_by_default"),
-            },
-        )
-        return 200, response
-
-    backend = _backend_for_model(selected["model_id"], config)
-    if backend is None:
-        return 424, {
-            "ok": False,
-            "error": "backend_not_configured",
-            "message": "Routing succeeded, but no live backend is configured for the selected model.",
-            "selected_model": selected["model_id"],
-            "required_config": {
-                "mode": "live",
-                "backends": {
-                    selected["model_id"]: {
-                        "type": "openai_compatible",
-                        "base_url": "http://127.0.0.1:8000/v1",
-                        "api_key_env": "OPTIONAL_ENV_NAME",
-                    },
-                },
-            },
-            "receipt": receipt,
-            **route_result,
-        }
-    return _proxy_openai_chat_completion(payload, selected, backend, config, route_result, receipt)
-
-
-def smoke_gateway(
-    *,
-    registry_path: Path | None = None,
-    config_path: Path | None = None,
-) -> dict[str, Any]:
-    resolved_registry = registry_path or default_registry_path()
-    resolved_config = config_path or _temporary_route_only_config()
-    route_payload = load_json_mapping(default_route_request_path())
-    chat_payload = load_json_mapping(default_openai_chat_request_path())
-    chat_payload["dry_run"] = True
-
-    health_status, health = handle_gateway_request("GET", "/health", None, resolved_registry, resolved_config)
-    models_status, models = handle_gateway_request("GET", "/v1/models", None, resolved_registry, resolved_config)
-    route_status, route = handle_gateway_request("POST", "/v1/route", route_payload, resolved_registry, resolved_config)
-    chat_status, chat = handle_gateway_request(
-        "POST",
-        "/v1/chat/completions",
-        chat_payload,
-        resolved_registry,
-        resolved_config,
-    )
-
-    if health_status != 200 or models_status != 200 or route_status != 200 or chat_status != 200:
-        raise RuntimeError("MaramaRoute gateway smoke failed")
-    if chat.get("object") != "chat.completion" or chat["marama_route"]["selected_model"] is None:
-        raise RuntimeError("MaramaRoute gateway did not return a routed chat response")
-    return {
-        "ok": True,
-        "product": PRODUCT_NAME,
-        "mode": health["mode"],
-        "model_count": health["model_count"],
-        "route_selected_model": route["route_decision"]["selected_model"]["model_id"],
-        "chat_selected_model": chat["marama_route"]["selected_model"]["model_id"],
-        "configured_backends": health["configured_backends"],
-    }
-
-
-def serve_gateway(
-    *,
-    registry_path: Path | None = None,
-    config_path: Path | None = None,
-    host: str = "127.0.0.1",
-    port: int = 8787,
-    open_browser: bool = False,
-    smoke: bool = False,
-) -> int:
-    resolved_registry = registry_path or default_registry_path()
-    if smoke:
-        print(json.dumps(smoke_gateway(registry_path=resolved_registry, config_path=config_path), indent=2, sort_keys=True))
-        return 0
-
-    html = build_expanded_dashboard_html(build_dashboard_state(resolved_registry))
-    return serve_dashboard(
-        product_name=f"{PRODUCT_NAME} Gateway",
-        html=html,
-        api_handler=lambda method, path, request_payload: handle_gateway_request(
-            method,
-            path,
-            request_payload,
-            resolved_registry,
-            config_path,
-        ),
-        host=host,
-        port=port,
-        open_browser=open_browser,
-        api_path_prefixes=("/api/", "/v1/"),
-        api_exact_paths=("/health",),
-    )
-
-
-def _backend_for_model(model_id: str, config: dict[str, Any]) -> dict[str, Any] | None:
-    backends = config.get("backends")
-    if not isinstance(backends, dict):
-        return None
-    backend = backends.get(model_id) or backends.get("*")
-    return dict(backend) if isinstance(backend, dict) else None
-
-
-def _proxy_openai_chat_completion(
-    payload: dict[str, Any],
-    selected: dict[str, Any],
-    backend: dict[str, Any],
-    config: dict[str, Any],
-    route_result: dict[str, Any],
-    receipt: dict[str, Any],
-) -> tuple[int, dict[str, Any]]:
-    if str(backend.get("type") or "openai_compatible") != "openai_compatible":
-        return 424, {"ok": False, "error": "unsupported_backend_type", "backend": backend}
-
-    base_url = str(backend.get("base_url") or "").rstrip("/")
-    if not base_url:
-        return 424, {"ok": False, "error": "backend_base_url_missing", "selected_model": selected["model_id"]}
-    endpoint = f"{base_url}/chat/completions"
-    upstream_payload = dict(payload)
-    upstream_payload["model"] = str(backend.get("model") or selected["model_id"])
-    for key in ("route", "routing", "dry_run", "marama_route_dry_run"):
-        upstream_payload.pop(key, None)
-
-    headers = {"Content-Type": "application/json"}
-    api_key_env = str(backend.get("api_key_env") or "")
-    if api_key_env and os.getenv(api_key_env):
-        headers["Authorization"] = f"Bearer {os.environ[api_key_env]}"
-    headers.update({str(key): str(value) for key, value in dict(backend.get("headers") or {}).items()})
-
-    timeout = float(backend.get("timeout_seconds") or config.get("default_timeout_seconds") or 120)
-    request = urllib.request.Request(
-        endpoint,
-        data=json.dumps(upstream_payload).encode("utf-8"),
-        headers=headers,
-        method="POST",
-    )
-    try:
-        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 - operator-configured local/remote backend
-            body = response.read().decode("utf-8")
-            payload_out = json.loads(body)
-            if not isinstance(payload_out, dict):
-                raise ValueError("upstream response was not a JSON object")
-            payload_out["marama_route"] = {
-                "dry_run": False,
-                "selected_model": selected,
-                "fallback_models": route_result["route_decision"]["fallback_models"],
-                "rejected_count": len(route_result["route_decision"]["rejected"]),
-                "receipt": receipt,
-                "backend_base_url": base_url,
-                "prompt_retention": config.get("prompt_retention", "not_stored_by_default"),
-            }
-            return int(response.status), payload_out
-    except urllib.error.HTTPError as exc:
-        return exc.code, {
-            "ok": False,
-            "error": "backend_http_error",
-            "status": exc.code,
-            "body": exc.read().decode("utf-8", errors="replace"),
-            "receipt": receipt,
-            **route_result,
-        }
-    except Exception as exc:
-        return 502, {
-            "ok": False,
-            "error": "backend_unavailable",
-            "message": str(exc),
-            "receipt": receipt,
-            **route_result,
-        }
-
-
-def _temporary_route_only_config() -> Path:
-    path = Path(tempfile.gettempdir()) / "marama-route-smoke.gateway.json"
-    path.write_text(json.dumps(DEFAULT_GATEWAY_CONFIG, indent=2, sort_keys=True), encoding="utf-8")
-    return path
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+try:  # repo package
+    from tinyluminax.products._ui_server import serve_dashboard
+except ModuleNotFoundError:  # standalone HF package
+    from ._ui_server import serve_dashboard
+
+from .gateway import route_chat_payload
+from .platform import build_models_api, route_or_chat_payload, route_receipt
+from .registry import load_model_registry
+from .ui import (
+    PRODUCT_NAME,
+    build_dashboard_state,
+    build_expanded_dashboard_html,
+    default_openai_chat_request_path,
+    default_registry_path,
+    handle_api_request,
+    load_json_mapping,
+)
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+PACKAGE_PARENT = PACKAGE_ROOT.parent
+
+DEFAULT_GATEWAY_CONFIG: dict[str, Any] = {
+    "mode": "route_only",
+    "prompt_retention": "not_stored_by_default",
+    "default_timeout_seconds": 120,
+    "backends": {},
+}
+
+
+def default_gateway_config_path() -> Path:
+    candidates = [
+        Path.cwd() / "products" / "lumynax-marama-route" / "configs" / "gateway.local.json",
+        Path.cwd() / "configs" / "gateway.local.json",
+        PACKAGE_ROOT / "configs" / "gateway.local.json",
+        PACKAGE_PARENT / "configs" / "gateway.local.json",
+    ]
+    for path in candidates:
+        if path.exists():
+            return path
+    return candidates[0]
+
+
+def default_route_request_path() -> Path:
+    candidates = [
+        Path.cwd() / "products" / "lumynax-marama-route" / "examples" / "request.code-restricted.json",
+        Path.cwd() / "examples" / "request.code-restricted.json",
+        PACKAGE_ROOT / "examples" / "request.code-restricted.json",
+        PACKAGE_PARENT / "examples" / "request.code-restricted.json",
+    ]
+    for path in candidates:
+        if path.exists():
+            return path
+    return candidates[0]
+
+
+def load_gateway_config(path: Path | None = None) -> dict[str, Any]:
+    config = dict(DEFAULT_GATEWAY_CONFIG)
+    config["backends"] = dict(DEFAULT_GATEWAY_CONFIG["backends"])
+    resolved = path or default_gateway_config_path()
+    if resolved.exists():
+        payload = json.loads(resolved.read_text(encoding="utf-8-sig"))
+        if not isinstance(payload, dict):
+            raise ValueError(f"Expected gateway config object in {resolved}")
+        config.update(payload)
+        config["backends"] = dict(payload.get("backends") or {})
+    config["config_path"] = str(resolved)
+    return config
+
+
+def handle_gateway_request(
+    method: str,
+    path: str,
+    payload: dict[str, Any] | None,
+    registry_path: Path,
+    config_path: Path | None = None,
+) -> tuple[int, dict[str, Any]]:
+    models = load_model_registry(registry_path)
+    config = load_gateway_config(config_path)
+
+    if path.startswith("/api/"):
+        return handle_api_request(method, path, payload, registry_path)
+    if method == "GET" and path in {"/health", "/v1/health"}:
+        return 200, {
+            "ok": True,
+            "product": PRODUCT_NAME,
+            "mode": config["mode"],
+            "model_count": len(models),
+            "configured_backends": len(config.get("backends") or {}),
+            "prompt_retention": config.get("prompt_retention", "not_stored_by_default"),
+        }
+    if method == "GET" and path == "/v1/models":
+        return 200, build_models_api(models)
+    if method == "POST" and path == "/v1/route" and payload is not None:
+        result = route_or_chat_payload(payload, models)
+        return (200 if result["ok"] else 422), result
+    if method == "POST" and path == "/v1/chat/completions" and payload is not None:
+        return chat_completion_gateway(payload, models, config)
+    return 404, {"ok": False, "error": "not_found"}
+
+
+def chat_completion_gateway(
+    payload: dict[str, Any],
+    models: tuple[Any, ...],
+    config: dict[str, Any],
+) -> tuple[int, dict[str, Any]]:
+    route_result = route_chat_payload(payload, models)
+    decision = route_result["route_decision"]
+    selected = decision.get("selected_model")
+    if not isinstance(selected, dict):
+        return 422, {"ok": False, "error": "no_eligible_model", **route_result}
+
+    receipt = route_receipt(payload, route_result)
+    dry_run = bool(
+        payload.get("dry_run")
+        or payload.get("marama_route_dry_run")
+        or config.get("mode", "route_only") == "route_only"
+    )
+    if dry_run:
+        response = dict(route_result["chat_completion_response"])
+        response["marama_route"] = dict(response["marama_route"])
+        response["marama_route"].update(
+            {
+                "backend_mode": "route_only",
+                "receipt": receipt,
+                "prompt_retention": config.get("prompt_retention", "not_stored_by_default"),
+            },
+        )
+        return 200, response
+
+    backend = _backend_for_model(selected["model_id"], config)
+    if backend is None:
+        return 424, {
+            "ok": False,
+            "error": "backend_not_configured",
+            "message": "Routing succeeded, but no live backend is configured for the selected model.",
+            "selected_model": selected["model_id"],
+            "required_config": {
+                "mode": "live",
+                "backends": {
+                    selected["model_id"]: {
+                        "type": "openai_compatible",
+                        "base_url": "http://127.0.0.1:8000/v1",
+                        "api_key_env": "OPTIONAL_ENV_NAME",
+                    },
+                },
+            },
+            "receipt": receipt,
+            **route_result,
+        }
+    return _proxy_openai_chat_completion(payload, selected, backend, config, route_result, receipt)
+
+
+def smoke_gateway(
+    *,
+    registry_path: Path | None = None,
+    config_path: Path | None = None,
+) -> dict[str, Any]:
+    resolved_registry = registry_path or default_registry_path()
+    resolved_config = config_path or _temporary_route_only_config()
+    route_payload = load_json_mapping(default_route_request_path())
+    chat_payload = load_json_mapping(default_openai_chat_request_path())
+    chat_payload["dry_run"] = True
+
+    health_status, health = handle_gateway_request("GET", "/health", None, resolved_registry, resolved_config)
+    models_status, models = handle_gateway_request("GET", "/v1/models", None, resolved_registry, resolved_config)
+    route_status, route = handle_gateway_request("POST", "/v1/route", route_payload, resolved_registry, resolved_config)
+    chat_status, chat = handle_gateway_request(
+        "POST",
+        "/v1/chat/completions",
+        chat_payload,
+        resolved_registry,
+        resolved_config,
+    )
+
+    if health_status != 200 or models_status != 200 or route_status != 200 or chat_status != 200:
+        raise RuntimeError("MaramaRoute gateway smoke failed")
+    if chat.get("object") != "chat.completion" or chat["marama_route"]["selected_model"] is None:
+        raise RuntimeError("MaramaRoute gateway did not return a routed chat response")
+    return {
+        "ok": True,
+        "product": PRODUCT_NAME,
+        "mode": health["mode"],
+        "model_count": health["model_count"],
+        "route_selected_model": route["route_decision"]["selected_model"]["model_id"],
+        "chat_selected_model": chat["marama_route"]["selected_model"]["model_id"],
+        "configured_backends": health["configured_backends"],
+    }
+
+
+def serve_gateway(
+    *,
+    registry_path: Path | None = None,
+    config_path: Path | None = None,
+    host: str = "127.0.0.1",
+    port: int = 8787,
+    open_browser: bool = False,
+    smoke: bool = False,
+) -> int:
+    resolved_registry = registry_path or default_registry_path()
+    if smoke:
+        print(json.dumps(smoke_gateway(registry_path=resolved_registry, config_path=config_path), indent=2, sort_keys=True))
+        return 0
+
+    html = build_expanded_dashboard_html(build_dashboard_state(resolved_registry))
+    return serve_dashboard(
+        product_name=f"{PRODUCT_NAME} Gateway",
+        html=html,
+        api_handler=lambda method, path, request_payload: handle_gateway_request(
+            method,
+            path,
+            request_payload,
+            resolved_registry,
+            config_path,
+        ),
+        host=host,
+        port=port,
+        open_browser=open_browser,
+        api_path_prefixes=("/api/", "/v1/"),
+        api_exact_paths=("/health",),
+    )
+
+
+def _backend_for_model(model_id: str, config: dict[str, Any]) -> dict[str, Any] | None:
+    backends = config.get("backends")
+    if not isinstance(backends, dict):
+        return None
+    backend = backends.get(model_id) or backends.get("*")
+    return dict(backend) if isinstance(backend, dict) else None
+
+
+def _proxy_openai_chat_completion(
+    payload: dict[str, Any],
+    selected: dict[str, Any],
+    backend: dict[str, Any],
+    config: dict[str, Any],
+    route_result: dict[str, Any],
+    receipt: dict[str, Any],
+) -> tuple[int, dict[str, Any]]:
+    if str(backend.get("type") or "openai_compatible") != "openai_compatible":
+        return 424, {"ok": False, "error": "unsupported_backend_type", "backend": backend}
+
+    base_url = str(backend.get("base_url") or "").rstrip("/")
+    if not base_url:
+        return 424, {"ok": False, "error": "backend_base_url_missing", "selected_model": selected["model_id"]}
+    endpoint = f"{base_url}/chat/completions"
+    upstream_payload = dict(payload)
+    upstream_payload["model"] = str(backend.get("model") or selected["model_id"])
+    for key in ("route", "routing", "dry_run", "marama_route_dry_run"):
+        upstream_payload.pop(key, None)
+
+    headers = {"Content-Type": "application/json"}
+    api_key_env = str(backend.get("api_key_env") or "")
+    if api_key_env and os.getenv(api_key_env):
+        headers["Authorization"] = f"Bearer {os.environ[api_key_env]}"
+    headers.update({str(key): str(value) for key, value in dict(backend.get("headers") or {}).items()})
+
+    timeout = float(backend.get("timeout_seconds") or config.get("default_timeout_seconds") or 120)
+    request = urllib.request.Request(
+        endpoint,
+        data=json.dumps(upstream_payload).encode("utf-8"),
+        headers=headers,
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 - operator-configured local/remote backend
+            body = response.read().decode("utf-8")
+            payload_out = json.loads(body)
+            if not isinstance(payload_out, dict):
+                raise ValueError("upstream response was not a JSON object")
+            payload_out["marama_route"] = {
+                "dry_run": False,
+                "selected_model": selected,
+                "fallback_models": route_result["route_decision"]["fallback_models"],
+                "rejected_count": len(route_result["route_decision"]["rejected"]),
+                "receipt": receipt,
+                "backend_base_url": base_url,
+                "prompt_retention": config.get("prompt_retention", "not_stored_by_default"),
+            }
+            return int(response.status), payload_out
+    except urllib.error.HTTPError as exc:
+        return exc.code, {
+            "ok": False,
+            "error": "backend_http_error",
+            "status": exc.code,
+            "body": exc.read().decode("utf-8", errors="replace"),
+            "receipt": receipt,
+            **route_result,
+        }
+    except Exception as exc:
+        return 502, {
+            "ok": False,
+            "error": "backend_unavailable",
+            "message": str(exc),
+            "receipt": receipt,
+            **route_result,
+        }
+
+
+def _temporary_route_only_config() -> Path:
+    path = Path(tempfile.gettempdir()) / "marama-route-smoke.gateway.json"
+    path.write_text(json.dumps(DEFAULT_GATEWAY_CONFIG, indent=2, sort_keys=True), encoding="utf-8")
+    return path

product_manifest.json

@@ -1,54 +1,68 @@
-{
-  "product_name": "LumynaX MaramaRoute",
-  "slug": "lumynax-marama-route",
+{
+  "product_name": "LumynaX MaramaRoute",
+  "slug": "lumynax-marama-route",
   "publisher": "AbteeX AI Labs",
   "family": "LumynaX sovereign products",
   "stage": "local_runtime",
-  "positioning": "Sovereign model router for LumynaX releases",
-  "target_region": "NZ",
-  "compatibility_goal": "OpenAI/OpenRouter-style model routing for LumynaX releases",
-  "primary_modules": [
-    "registry_compiler",
-    "sovereign_router",
-    "gateway_adapter",
-    "catalog_search",
-    "model_comparison",
-    "scenario_matrix",
-    "provider_config_export",
-    "policy_packs",
-    "telemetry_ledger",
-    "opencode_provider_config",
-    "openai_compatible_gateway_service",
-    "backend_proxy_config"
-  ],
-  "runtime_entrypoints": [
-    "python -m tinyluminax.products.marama_route.cli route",
-    "python -m tinyluminax.products.marama_route.cli models",
-    "python -m tinyluminax.products.marama_route.cli chat-dry-run",
-    "python -m tinyluminax.products.marama_route.cli catalog",
-    "python -m tinyluminax.products.marama_route.cli matrix",
-    "python -m tinyluminax.products.marama_route.cli opencode-config",
+  "package": {
+    "pypi_name": "lumynax-marama-route",
+    "python_import": "marama_route",
+    "console_script": "marama-route",
+    "version": "0.4.0",
+    "release_artifacts": [
+      "wheel",
+      "sdist",
+      "huggingface_model_repo",
+      "github_source"
+    ]
+  },
+  "positioning": "Sovereign model router for LumynaX releases",
+  "target_region": "NZ",
+  "compatibility_goal": "OpenAI/OpenRouter-style model routing for LumynaX releases",
+  "primary_modules": [
+    "registry_compiler",
+    "sovereign_router",
+    "gateway_adapter",
+    "catalog_search",
+    "model_comparison",
+    "scenario_matrix",
+    "provider_config_export",
+    "policy_packs",
+    "telemetry_ledger",
+    "opencode_provider_config",
+    "openai_compatible_gateway_service",
+    "backend_proxy_config"
+  ],
+  "runtime_entrypoints": [
+    "python -m tinyluminax.products.marama_route.cli route",
+    "python -m tinyluminax.products.marama_route.cli models",
+    "python -m tinyluminax.products.marama_route.cli chat-dry-run",
+    "python -m tinyluminax.products.marama_route.cli catalog",
+    "python -m tinyluminax.products.marama_route.cli matrix",
+    "python -m tinyluminax.products.marama_route.cli opencode-config",
     "python -m tinyluminax.products.marama_route.cli ui",
-    "python -m tinyluminax.products.marama_route.cli serve"
-  ],
-  "api_surfaces": [
-    "GET /health",
-    "GET /v1/health",
-    "GET /v1/models",
-    "POST /v1/route",
-    "POST /v1/chat/completions",
-    "POST /v1/embeddings",
-    "GET /api/health",
-    "POST /api/route",
-    "POST /api/catalog",
-    "POST /api/compare",
-    "POST /api/matrix",
-    "POST /api/opencode-config"
+    "python -m tinyluminax.products.marama_route.cli serve",
+    "marama-route serve",
+    "marama-route serve --smoke"
   ],
-  "brand_system": {
-    "paper": "#fffefa",
-    "ink": "#0a0a0b",
-    "accent": "#e08a2c",
-    "muted": "#726b62"
-  }
-}
+  "api_surfaces": [
+    "GET /health",
+    "GET /v1/health",
+    "GET /v1/models",
+    "POST /v1/route",
+    "POST /v1/chat/completions",
+    "POST /v1/embeddings",
+    "GET /api/health",
+    "POST /api/route",
+    "POST /api/catalog",
+    "POST /api/compare",
+    "POST /api/matrix",
+    "POST /api/opencode-config"
+  ],
+  "brand_system": {
+    "paper": "#fffefa",
+    "ink": "#0a0a0b",
+    "accent": "#e08a2c",
+    "muted": "#726b62"
+  }
+}

pyproject.toml

@@ -4,18 +4,40 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lumynax-marama-route"
-version = "0.3.0"
+version = "0.4.0"
 description = "LumynaX MaramaRoute: sovereign OpenAI-compatible model router for LumynaX releases."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
 authors = [{ name = "AbteeX AI Labs" }]
-keywords = ["lumynax", "marama-route", "model-router", "sovereignty", "openrouter-alternative", "openai-compatible"]
+maintainers = [{ name = "AbteeX AI Labs" }]
+keywords = ["lumynax", "marama-route", "model-router", "sovereignty", "openrouter-alternative", "openai-compatible", "new-zealand"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Environment :: Web Environment",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+release = ["build>=1.2", "twine>=5.1"]
+dev = ["build>=1.2", "ruff>=0.6", "twine>=5.1"]
 
 [project.urls]
 Homepage = "https://lumynax.com"
-Repository = "https://huggingface.co/AbteeXAILab/marama-route"
+Repository = "https://github.com/Aimaghsoodi/TinyLuminaX"
+"Hugging Face" = "https://huggingface.co/AbteeXAILab/marama-route"
 Abteex = "https://abteex.com"
+Issues = "https://github.com/Aimaghsoodi/TinyLuminaX/issues"
 
 [project.scripts]
 marama-route = "marama_route.cli:main"
@@ -25,5 +47,8 @@ where = ["."]
 include = ["marama_route*"]
 namespaces = true
 
+[tool.setuptools]
+include-package-data = true
+
 [tool.setuptools.package-data]
-marama_route = ["configs/*", "examples/*", "integrations/*", "schemas/*"]
+marama_route = ["py.typed", "configs/*", "examples/*", "integrations/*", "schemas/*"]