Publish expanded LumynaX product platform package

MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md LICENSE requirements.txt SMOKE_TESTS.md PYPI_RELEASE.md quickstart.py product_manifest.json product_blueprint.md architecture.md
+recursive-include sovereigncode *.py py.typed
+recursive-include sovereigncode/configs *
+recursive-include sovereigncode/examples *
+recursive-include sovereigncode/integrations *
+recursive-include sovereigncode/policy-packs *
+recursive-include sovereigncode/schemas *
+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: AbteeX SovereignCode
+
+Package: `abteex-sovereigncode`
+Version: `0.4.0`
+
+## Local Build
+
+```bash
+python -m build
+python -m twine check dist/*
+python quickstart.py
+sovereigncode 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: `sovereigncode`
+- Local UI/API: `sovereigncode serve --port 8788 --open`
+- Policy API: `POST /v1/evaluate`, `POST /v1/plan-turn`, `POST /v1/tool-check`
+- Audit: `GET /v1/audit` and `sovereigncode audit --limit 25`

README.md

@@ -21,10 +21,17 @@ language:
 # AbteeX SovereignCode
 <!-- abteex-sovereigncode-card:v3 -->
 
-Standalone release package for `AbteeXAILab/sovereigncode`.
+Standalone release package for PyPI package `abteex-sovereigncode` and Hugging Face repo `AbteeXAILab/sovereigncode`.
 
 ## Install
 
+```bash
+pip install abteex-sovereigncode
+sovereigncode serve --smoke
+```
+
+HF mirror install:
+
 ```bash
 hf download AbteeXAILab/sovereigncode --local-dir sovereigncode --repo-type model
 cd sovereigncode
@@ -35,6 +42,10 @@ python quickstart.py
 ## Included Runtime Commands
 
 ```bash
+sovereigncode serve --smoke
+sovereigncode audit --limit 5
+sovereigncode opencode-config
+sovereigncode ui --port 8788 --open
 python -m sovereigncode.cli evaluate --capsule examples/capsule.restricted-nz-code.json --request examples/request.allowed-local-edit.json
 python -m sovereigncode.cli plan-turn --capsule examples/capsule.restricted-nz-code.json --request examples/request.allowed-local-edit.json --route-request examples/request.code-restricted.json --registry configs/lumynax_model_registry.json
 python -m sovereigncode.cli policy-matrix --capsule examples/capsule.restricted-nz-code.json --request examples/request.allowed-local-edit.json
@@ -83,6 +94,16 @@ The initial product scaffold includes:
 
 ## Quickstart
 
+Install the standalone package:
+
+```bash
+pip install abteex-sovereigncode
+sovereigncode serve --smoke
+sovereigncode serve --port 8788 --open
+```
+
+The same package is mirrored on Hugging Face at `AbteeXAILab/sovereigncode` and can be installed from a downloaded snapshot with `pip install -e .`.
+
 From the repo root:
 
 ```bash
@@ -162,6 +183,16 @@ py -3 -m tinyluminax.products.sovereigncode.cli audit --limit 10
 
 The service exposes `GET /health`, `GET /v1/audit`, `POST /v1/evaluate`, `POST /v1/plan-turn`, `POST /v1/tool-check`, `POST /v1/policy-matrix`, and the existing browser `/api/*` routes. It writes JSONL audit records to `.sovereigncode/audit.jsonl` by default.
 
+## 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 sovereigncode
+py -3 scripts/publish_products_to_pypi.py --product sovereigncode --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/service.local.json

@@ -1,14 +1,14 @@
-{
-  "ledger_path": ".sovereigncode/audit.jsonl",
-  "default_region": "NZ",
-  "fail_closed": true,
-  "require_human_review_for": [
-    "write_files",
-    "execute_shell",
-    "network_export",
-    "commit",
-    "publish",
-    "train_model"
-  ],
-  "marama_route_base_url": "http://127.0.0.1:8787/v1"
-}
+{
+  "ledger_path": ".sovereigncode/audit.jsonl",
+  "default_region": "NZ",
+  "fail_closed": true,
+  "require_human_review_for": [
+    "write_files",
+    "execute_shell",
+    "network_export",
+    "commit",
+    "publish",
+    "train_model"
+  ],
+  "marama_route_base_url": "http://127.0.0.1:8787/v1"
+}

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/configs/service.local.json

@@ -1,14 +1,14 @@
-{
-  "ledger_path": ".sovereigncode/audit.jsonl",
-  "default_region": "NZ",
-  "fail_closed": true,
-  "require_human_review_for": [
-    "write_files",
-    "execute_shell",
-    "network_export",
-    "commit",
-    "publish",
-    "train_model"
-  ],
-  "marama_route_base_url": "http://127.0.0.1:8787/v1"
-}
+{
+  "ledger_path": ".sovereigncode/audit.jsonl",
+  "default_region": "NZ",
+  "fail_closed": true,
+  "require_human_review_for": [
+    "write_files",
+    "execute_shell",
+    "network_export",
+    "commit",
+    "publish",
+    "train_model"
+  ],
+  "marama_route_base_url": "http://127.0.0.1:8787/v1"
+}

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,62 +1,77 @@
-{
-  "product_name": "AbteeX SovereignCode",
-  "slug": "abx-sovereigncode",
+{
+  "product_name": "AbteeX SovereignCode",
+  "slug": "abx-sovereigncode",
   "publisher": "AbteeX AI Labs",
   "family": "LumynaX sovereign products",
   "stage": "local_runtime",
-  "positioning": "OpenCode-style local coding agent with Data Capsule sovereignty controls",
-  "target_region": "NZ",
-  "target_users": [
-    "New Zealand developers",
-    "regulated SMEs",
-    "local government teams",
-    "health-adjacent operators",
-    "Iwi and community data stewards",
-    "privacy-conscious individual developers"
-  ],
-  "primary_modules": [
-    "data_capsule_policy",
-    "personal_detail_consent",
-    "tool_broker",
-    "lumynax_runtime_adapter",
-    "audit_ledger",
-    "human_review_gate",
-    "policy_matrix",
-    "tool_gate_check",
-    "capsule_summary",
-    "opencode_workspace_export",
-    "opencode_compatible_provider",
-    "policy_api_service",
-    "persistent_audit_ledger"
-  ],
-  "runtime_entrypoints": [
-    "python -m tinyluminax.products.sovereigncode.cli evaluate",
-    "python -m tinyluminax.products.sovereigncode.cli plan-turn",
-    "python -m tinyluminax.products.sovereigncode.cli policy-matrix",
-    "python -m tinyluminax.products.sovereigncode.cli tool-check",
-    "python -m tinyluminax.products.sovereigncode.cli opencode-config",
+  "package": {
+    "pypi_name": "abteex-sovereigncode",
+    "python_import": "sovereigncode",
+    "console_script": "sovereigncode",
+    "version": "0.4.0",
+    "release_artifacts": [
+      "wheel",
+      "sdist",
+      "huggingface_model_repo",
+      "github_source"
+    ]
+  },
+  "positioning": "OpenCode-style local coding agent with Data Capsule sovereignty controls",
+  "target_region": "NZ",
+  "target_users": [
+    "New Zealand developers",
+    "regulated SMEs",
+    "local government teams",
+    "health-adjacent operators",
+    "Iwi and community data stewards",
+    "privacy-conscious individual developers"
+  ],
+  "primary_modules": [
+    "data_capsule_policy",
+    "personal_detail_consent",
+    "tool_broker",
+    "lumynax_runtime_adapter",
+    "audit_ledger",
+    "human_review_gate",
+    "policy_matrix",
+    "tool_gate_check",
+    "capsule_summary",
+    "opencode_workspace_export",
+    "opencode_compatible_provider",
+    "policy_api_service",
+    "persistent_audit_ledger"
+  ],
+  "runtime_entrypoints": [
+    "python -m tinyluminax.products.sovereigncode.cli evaluate",
+    "python -m tinyluminax.products.sovereigncode.cli plan-turn",
+    "python -m tinyluminax.products.sovereigncode.cli policy-matrix",
+    "python -m tinyluminax.products.sovereigncode.cli tool-check",
+    "python -m tinyluminax.products.sovereigncode.cli opencode-config",
     "python -m tinyluminax.products.sovereigncode.cli ui",
     "python -m tinyluminax.products.sovereigncode.cli serve",
-    "python -m tinyluminax.products.sovereigncode.cli audit"
-  ],
-  "integration_surfaces": [
-    "OpenAI-compatible /v1/chat/completions via MaramaRoute",
-    "OpenAI-compatible /v1/models via MaramaRoute",
-    "SovereignCode GET /health and GET /v1/audit",
-    "SovereignCode POST /v1/evaluate",
-    "SovereignCode POST /v1/plan-turn",
-    "SovereignCode POST /v1/tool-check",
-    "OpenCode custom provider config",
-    "local CLI policy evaluator",
-    "governed coding-turn planner",
-    "policy matrix and tool gate checker",
-    "browser operator checklist",
-    "browser operator console"
+    "python -m tinyluminax.products.sovereigncode.cli audit",
+    "sovereigncode serve",
+    "sovereigncode serve --smoke",
+    "sovereigncode audit"
   ],
-  "brand_system": {
-    "paper": "#fffefa",
-    "ink": "#0a0a0b",
-    "accent": "#e08a2c",
-    "muted": "#726b62"
-  }
-}
+  "integration_surfaces": [
+    "OpenAI-compatible /v1/chat/completions via MaramaRoute",
+    "OpenAI-compatible /v1/models via MaramaRoute",
+    "SovereignCode GET /health and GET /v1/audit",
+    "SovereignCode POST /v1/evaluate",
+    "SovereignCode POST /v1/plan-turn",
+    "SovereignCode POST /v1/tool-check",
+    "OpenCode custom provider config",
+    "local CLI policy evaluator",
+    "governed coding-turn planner",
+    "policy matrix and tool gate checker",
+    "browser operator checklist",
+    "browser operator console"
+  ],
+  "brand_system": {
+    "paper": "#fffefa",
+    "ink": "#0a0a0b",
+    "accent": "#e08a2c",
+    "muted": "#726b62"
+  }
+}

pyproject.toml

@@ -4,19 +4,41 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "abteex-sovereigncode"
-version = "0.3.0"
-description = "AbteeX SovereignCode: local-first coding agent with Data Capsule sovereignty controls."
+version = "0.4.0"
+description = "AbteeX SovereignCode: local-first policy API, audit ledger, and coding-agent sovereignty controls."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
 authors = [{ name = "AbteeX AI Labs" }]
-keywords = ["lumynax", "sovereignty", "data-capsule", "coding-agent", "opencode", "new-zealand"]
+maintainers = [{ name = "AbteeX AI Labs" }]
+keywords = ["lumynax", "sovereignty", "data-capsule", "coding-agent", "opencode", "new-zealand", "policy-api", "audit-ledger"]
 dependencies = ["PyYAML>=6.0"]
+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 :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Systems Administration",
+  "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://abteex.com"
-Repository = "https://huggingface.co/AbteeXAILab/sovereigncode"
+Repository = "https://github.com/Aimaghsoodi/TinyLuminaX"
+"Hugging Face" = "https://huggingface.co/AbteeXAILab/sovereigncode"
 Lumynax = "https://lumynax.com"
+Issues = "https://github.com/Aimaghsoodi/TinyLuminaX/issues"
 
 [project.scripts]
 sovereigncode = "sovereigncode.cli:main"
@@ -26,6 +48,9 @@ where = ["."]
 include = ["sovereigncode*", "marama_route*"]
 namespaces = true
 
+[tool.setuptools]
+include-package-data = true
+
 [tool.setuptools.package-data]
-sovereigncode = ["configs/*", "examples/*", "integrations/*", "policy-packs/*", "schemas/*"]
-marama_route = ["configs/*", "examples/*", "integrations/*", "schemas/*"]
+sovereigncode = ["py.typed", "configs/*", "examples/*", "integrations/*", "policy-packs/*", "schemas/*"]
+marama_route = ["py.typed", "configs/*", "examples/*", "integrations/*", "schemas/*"]

sovereigncode/__init__.py

@@ -1,41 +1,41 @@
-from __future__ import annotations
-
-from .audit import AuditRecord, build_audit_record
-from .ledger import AuditLedger
-from .planner import SovereignCodingTurnPlan, ToolGrant, plan_coding_turn
-from .platform import (
-    build_capsule_summary,
-    build_opencode_workspace_config,
-    build_policy_matrix,
-    build_turn_brief,
-    check_tool_request,
-)
-from .policy import (
-    DataCapsule,
-    PolicyDecision,
-    SovereignRequest,
-    SovereigntyPolicyEngine,
-)
-from .server import handle_service_request, smoke_service
-from .ui import smoke_ui as smoke_ui
-
-__all__ = [
-    "AuditRecord",
-    "AuditLedger",
-    "DataCapsule",
-    "PolicyDecision",
-    "SovereignRequest",
-    "SovereignCodingTurnPlan",
-    "SovereigntyPolicyEngine",
-    "ToolGrant",
-    "build_audit_record",
-    "build_capsule_summary",
-    "build_opencode_workspace_config",
-    "build_policy_matrix",
-    "build_turn_brief",
-    "check_tool_request",
-    "handle_service_request",
-    "plan_coding_turn",
-    "smoke_service",
-    "smoke_ui",
-]
+from __future__ import annotations
+
+from .audit import AuditRecord, build_audit_record
+from .ledger import AuditLedger
+from .planner import SovereignCodingTurnPlan, ToolGrant, plan_coding_turn
+from .platform import (
+    build_capsule_summary,
+    build_opencode_workspace_config,
+    build_policy_matrix,
+    build_turn_brief,
+    check_tool_request,
+)
+from .policy import (
+    DataCapsule,
+    PolicyDecision,
+    SovereignRequest,
+    SovereigntyPolicyEngine,
+)
+from .server import handle_service_request, smoke_service
+from .ui import smoke_ui as smoke_ui
+
+__all__ = [
+    "AuditRecord",
+    "AuditLedger",
+    "DataCapsule",
+    "PolicyDecision",
+    "SovereignRequest",
+    "SovereignCodingTurnPlan",
+    "SovereigntyPolicyEngine",
+    "ToolGrant",
+    "build_audit_record",
+    "build_capsule_summary",
+    "build_opencode_workspace_config",
+    "build_policy_matrix",
+    "build_turn_brief",
+    "check_tool_request",
+    "handle_service_request",
+    "plan_coding_turn",
+    "smoke_service",
+    "smoke_ui",
+]

sovereigncode/_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

sovereigncode/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"
+    }
+  }
+}

sovereigncode/configs/service.local.json

@@ -1,14 +1,14 @@
-{
-  "ledger_path": ".sovereigncode/audit.jsonl",
-  "default_region": "NZ",
-  "fail_closed": true,
-  "require_human_review_for": [
-    "write_files",
-    "execute_shell",
-    "network_export",
-    "commit",
-    "publish",
-    "train_model"
-  ],
-  "marama_route_base_url": "http://127.0.0.1:8787/v1"
-}
+{
+  "ledger_path": ".sovereigncode/audit.jsonl",
+  "default_region": "NZ",
+  "fail_closed": true,
+  "require_human_review_for": [
+    "write_files",
+    "execute_shell",
+    "network_export",
+    "commit",
+    "publish",
+    "train_model"
+  ],
+  "marama_route_base_url": "http://127.0.0.1:8787/v1"
+}

sovereigncode/ledger.py

@@ -1,64 +1,64 @@
-from __future__ import annotations
-
-import hashlib
-import json
-import threading
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any
-
-
-def default_ledger_path() -> Path:
-    return Path.cwd() / ".sovereigncode" / "audit.jsonl"
-
-
-@dataclass(slots=True)
-class AuditLedger:
-    path: Path
-    _lock: threading.Lock = field(init=False, repr=False)
-
-    def __post_init__(self) -> None:
-        self._lock = threading.Lock()
-
-    def append(self, event: str, payload: dict[str, Any]) -> dict[str, Any]:
-        with self._lock:
-            self.path.parent.mkdir(parents=True, exist_ok=True)
-            sequence = self._line_count() + 1
-            record = {
-                "ledger_sequence": sequence,
-                "ledger_timestamp": datetime.now(UTC).isoformat(),
-                "event": event,
-                "payload": payload,
-            }
-            record["ledger_id"] = self._digest(record)
-            with self.path.open("a", encoding="utf-8", newline="\n") as stream:
-                stream.write(json.dumps(record, sort_keys=True, separators=(",", ":")))
-                stream.write("\n")
-            return {**record, "ledger_path": str(self.path)}
-
-    def tail(self, limit: int = 50) -> list[dict[str, Any]]:
-        if not self.path.exists():
-            return []
-        lines = self.path.read_text(encoding="utf-8-sig").splitlines()
-        records: list[dict[str, Any]] = []
-        for line in lines[-max(1, limit) :]:
-            try:
-                payload = json.loads(line)
-            except json.JSONDecodeError:
-                continue
-            if isinstance(payload, dict):
-                payload["ledger_path"] = str(self.path)
-                records.append(payload)
-        return records
-
-    def _line_count(self) -> int:
-        if not self.path.exists():
-            return 0
-        with self.path.open("r", encoding="utf-8-sig") as stream:
-            return sum(1 for line in stream if line.strip())
-
-    @staticmethod
-    def _digest(record: dict[str, Any]) -> str:
-        raw = json.dumps(record, sort_keys=True, default=str).encode("utf-8")
-        return f"sc-ledger-{hashlib.sha256(raw).hexdigest()[:24]}"
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+
+def default_ledger_path() -> Path:
+    return Path.cwd() / ".sovereigncode" / "audit.jsonl"
+
+
+@dataclass(slots=True)
+class AuditLedger:
+    path: Path
+    _lock: threading.Lock = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._lock = threading.Lock()
+
+    def append(self, event: str, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            sequence = self._line_count() + 1
+            record = {
+                "ledger_sequence": sequence,
+                "ledger_timestamp": datetime.now(UTC).isoformat(),
+                "event": event,
+                "payload": payload,
+            }
+            record["ledger_id"] = self._digest(record)
+            with self.path.open("a", encoding="utf-8", newline="\n") as stream:
+                stream.write(json.dumps(record, sort_keys=True, separators=(",", ":")))
+                stream.write("\n")
+            return {**record, "ledger_path": str(self.path)}
+
+    def tail(self, limit: int = 50) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        lines = self.path.read_text(encoding="utf-8-sig").splitlines()
+        records: list[dict[str, Any]] = []
+        for line in lines[-max(1, limit) :]:
+            try:
+                payload = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(payload, dict):
+                payload["ledger_path"] = str(self.path)
+                records.append(payload)
+        return records
+
+    def _line_count(self) -> int:
+        if not self.path.exists():
+            return 0
+        with self.path.open("r", encoding="utf-8-sig") as stream:
+            return sum(1 for line in stream if line.strip())
+
+    @staticmethod
+    def _digest(record: dict[str, Any]) -> str:
+        raw = json.dumps(record, sort_keys=True, default=str).encode("utf-8")
+        return f"sc-ledger-{hashlib.sha256(raw).hexdigest()[:24]}"

sovereigncode/server.py

@@ -1,352 +1,352 @@
-from __future__ import annotations
-
-import json
-import os
-import tempfile
-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
-
-try:  # repo package
-    from tinyluminax.products.marama_route import RoutingRequest, load_model_registry
-except ModuleNotFoundError:  # standalone HF package
-    from marama_route import RoutingRequest, load_model_registry
-
-from .audit import build_audit_record
-from .ledger import AuditLedger, default_ledger_path
-from .planner import plan_coding_turn
-from .platform import (
-    build_capsule_summary,
-    build_policy_matrix,
-    build_turn_brief,
-    check_tool_request,
-)
-from .policy import DataCapsule, SovereignRequest, SovereigntyPolicyEngine
-from .ui import (
-    PRODUCT_NAME,
-    build_dashboard_html,
-    build_dashboard_state,
-    default_capsule_path,
-    default_registry_path,
-    default_request_path,
-    default_route_request_path,
-    handle_api_request,
-)
-
-
-def handle_service_request(
-    method: str,
-    path: str,
-    payload: dict[str, Any] | None,
-    *,
-    capsule_path: Path,
-    request_path: Path,
-    route_request_path: Path,
-    registry_path: Path,
-    ledger_path: Path,
-    state: dict[str, Any] | None = None,
-) -> tuple[int, dict[str, Any]]:
-    ledger = AuditLedger(ledger_path)
-    service_state = state or build_dashboard_state(capsule_path, request_path, route_request_path, registry_path)
-
-    if path.startswith("/api/"):
-        return handle_api_request(method, path, payload, registry_path, service_state)
-    if method == "GET" and path in {"/health", "/v1/health"}:
-        return 200, _health_payload(ledger, service_state)
-    if method == "GET" and path == "/v1/audit":
-        return 200, {"ok": True, "ledger_path": str(ledger.path), "records": ledger.tail()}
-    if method == "GET" and path == "/v1/capsule-summary":
-        return 200, {"ok": True, "summary": build_capsule_summary(service_state["capsule"])}
-    if method == "POST" and path == "/v1/evaluate":
-        result = evaluate_payload(payload or {}, service_state, ledger)
-        return (200 if result["decision"]["allowed"] else 422), result
-    if method == "POST" and path == "/v1/plan-turn":
-        result = plan_turn_payload(payload or {}, service_state, ledger)
-        return (200 if result["allowed"] else 422), result
-    if method == "POST" and path == "/v1/tool-check":
-        result = tool_check_payload(payload or {}, service_state, ledger)
-        return (200 if result["ok"] else 422), result
-    if method == "POST" and path == "/v1/policy-matrix":
-        return 200, policy_matrix_payload(payload or {}, service_state, ledger)
-    if method == "POST" and path == "/v1/capsule-summary":
-        capsule_payload = _mapping(payload, "capsule") or service_state["capsule"]
-        return 200, {"ok": True, "summary": build_capsule_summary(capsule_payload)}
-    return 404, {"ok": False, "error": "not_found"}
-
-
-def evaluate_payload(
-    payload: dict[str, Any],
-    state: dict[str, Any],
-    ledger: AuditLedger,
-) -> dict[str, Any]:
-    capsule = DataCapsule.from_payload(_mapping(payload, "capsule") or state["capsule"])
-    request = SovereignRequest.from_payload(_mapping(payload, "request") or state["request"])
-    decision = SovereigntyPolicyEngine().evaluate(capsule, request)
-    audit = build_audit_record(capsule, request, decision).to_dict()
-    ledger_record = ledger.append(
-        "policy_evaluate",
-        {
-            "capsule_id": capsule.capsule_id,
-            "request": request.to_dict(),
-            "decision": decision.to_dict(),
-            "audit_record": audit,
-        },
-    )
-    return {
-        "ok": decision.allowed,
-        "decision": decision.to_dict(),
-        "audit_record": audit,
-        "ledger_record": ledger_record,
-    }
-
-
-def plan_turn_payload(
-    payload: dict[str, Any],
-    state: dict[str, Any],
-    ledger: AuditLedger,
-) -> dict[str, Any]:
-    capsule = DataCapsule.from_payload(_mapping(payload, "capsule") or state["capsule"])
-    request = SovereignRequest.from_payload(_mapping(payload, "request") or state["request"])
-    route_request = RoutingRequest.from_payload(_mapping(payload, "route_request") or state["route_request"])
-    models = load_model_registry(Path(str(payload.get("registry_path") or state["registry_path"])))
-    plan = plan_coding_turn(capsule, request, route_request, models)
-    result = plan.to_dict()
-    result["turn_brief"] = build_turn_brief(result)
-    result["ledger_record"] = ledger.append(
-        "plan_turn",
-        {
-            "capsule_id": capsule.capsule_id,
-            "allowed": plan.allowed,
-            "policy_decision": result["policy_decision"],
-            "route_decision": result["route_decision"],
-            "audit_record": result["audit_record"],
-            "turn_brief": result["turn_brief"],
-        },
-    )
-    result["ok"] = plan.allowed
-    return result
-
-
-def tool_check_payload(
-    payload: dict[str, Any],
-    state: dict[str, Any],
-    ledger: AuditLedger,
-) -> dict[str, Any]:
-    tool_payload = _mapping(payload, "tool") or {
-        "tool_name": payload.get("tool_name", "workspace_reader"),
-        "action": payload.get("action", "read_context"),
-        "writes_files": bool(payload.get("writes_files", False)),
-        "exports_data": bool(payload.get("exports_data", False)),
-        "trains_model": bool(payload.get("trains_model", False)),
-        "human_approved": bool(payload.get("human_approved", False)),
-    }
-    result = check_tool_request(
-        _mapping(payload, "capsule") or state["capsule"],
-        _mapping(payload, "request") or state["request"],
-        tool_payload,
-    )
-    result["ledger_record"] = ledger.append(
-        "tool_check",
-        {
-            "tool": tool_payload,
-            "decision": result["decision"],
-            "audit_record": result["audit_record"],
-            "operator_gate": result["operator_gate"],
-        },
-    )
-    return result
-
-
-def policy_matrix_payload(
-    payload: dict[str, Any],
-    state: dict[str, Any],
-    ledger: AuditLedger,
-) -> dict[str, Any]:
-    scenarios = payload.get("scenarios") if isinstance(payload.get("scenarios"), list) else None
-    result = build_policy_matrix(
-        _mapping(payload, "capsule") or state["capsule"],
-        _mapping(payload, "request") or state["request"],
-        scenarios,
-    )
-    result["ledger_record"] = ledger.append(
-        "policy_matrix",
-        {
-            "capsule_id": result["capsule_id"],
-            "allowed_count": result["allowed_count"],
-            "blocked_count": result["blocked_count"],
-        },
-    )
-    return result
-
-
-def smoke_service(
-    *,
-    capsule_path: Path | None = None,
-    request_path: Path | None = None,
-    route_request_path: Path | None = None,
-    registry_path: Path | None = None,
-    ledger_path: Path | None = None,
-) -> dict[str, Any]:
-    resolved_capsule = capsule_path or default_capsule_path()
-    resolved_request = request_path or default_request_path()
-    resolved_route_request = route_request_path or default_route_request_path()
-    resolved_registry = registry_path or default_registry_path()
-    resolved_ledger = ledger_path or _temporary_ledger_path()
-    state = build_dashboard_state(resolved_capsule, resolved_request, resolved_route_request, resolved_registry)
-
-    health_status, health = handle_service_request(
-        "GET",
-        "/health",
-        None,
-        capsule_path=resolved_capsule,
-        request_path=resolved_request,
-        route_request_path=resolved_route_request,
-        registry_path=resolved_registry,
-        ledger_path=resolved_ledger,
-        state=state,
-    )
-    evaluate_status, evaluate = handle_service_request(
-        "POST",
-        "/v1/evaluate",
-        {},
-        capsule_path=resolved_capsule,
-        request_path=resolved_request,
-        route_request_path=resolved_route_request,
-        registry_path=resolved_registry,
-        ledger_path=resolved_ledger,
-        state=state,
-    )
-    plan_status, plan = handle_service_request(
-        "POST",
-        "/v1/plan-turn",
-        {},
-        capsule_path=resolved_capsule,
-        request_path=resolved_request,
-        route_request_path=resolved_route_request,
-        registry_path=resolved_registry,
-        ledger_path=resolved_ledger,
-        state=state,
-    )
-    tool_status, tool = handle_service_request(
-        "POST",
-        "/v1/tool-check",
-        {"tool_name": "workspace_reader", "action": "read_context"},
-        capsule_path=resolved_capsule,
-        request_path=resolved_request,
-        route_request_path=resolved_route_request,
-        registry_path=resolved_registry,
-        ledger_path=resolved_ledger,
-        state=state,
-    )
-    audit_status, audit = handle_service_request(
-        "GET",
-        "/v1/audit",
-        None,
-        capsule_path=resolved_capsule,
-        request_path=resolved_request,
-        route_request_path=resolved_route_request,
-        registry_path=resolved_registry,
-        ledger_path=resolved_ledger,
-        state=state,
-    )
-
-    if (health_status, evaluate_status, plan_status, tool_status, audit_status) != (200, 200, 200, 200, 200):
-        raise RuntimeError("SovereignCode service smoke failed")
-    if not evaluate["decision"]["allowed"] or not plan["allowed"] or not tool["ok"]:
-        raise RuntimeError("SovereignCode service smoke did not allow the governed local request")
-    return {
-        "ok": True,
-        "product": PRODUCT_NAME,
-        "capsule_id": state["capsule"]["capsule_id"],
-        "selected_model": plan["turn_brief"]["selected_model"],
-        "ledger_path": str(resolved_ledger),
-        "ledger_records": len(audit["records"]),
-        "tool_next_gate": tool["operator_gate"]["next_gate"],
-    }
-
-
-def serve_service(
-    *,
-    capsule_path: Path | None = None,
-    request_path: Path | None = None,
-    route_request_path: Path | None = None,
-    registry_path: Path | None = None,
-    ledger_path: Path | None = None,
-    host: str = "127.0.0.1",
-    port: int = 8788,
-    open_browser: bool = False,
-    smoke: bool = False,
-) -> int:
-    resolved_capsule = capsule_path or default_capsule_path()
-    resolved_request = request_path or default_request_path()
-    resolved_route_request = route_request_path or default_route_request_path()
-    resolved_registry = registry_path or default_registry_path()
-    resolved_ledger = ledger_path or default_ledger_path()
-    if smoke:
-        print(
-            json.dumps(
-                smoke_service(
-                    capsule_path=resolved_capsule,
-                    request_path=resolved_request,
-                    route_request_path=resolved_route_request,
-                    registry_path=resolved_registry,
-                    ledger_path=ledger_path,
-                ),
-                indent=2,
-                sort_keys=True,
-            ),
-        )
-        return 0
-
-    state = build_dashboard_state(resolved_capsule, resolved_request, resolved_route_request, resolved_registry)
-    html = build_dashboard_html(state)
-    return serve_dashboard(
-        product_name=f"{PRODUCT_NAME} Service",
-        html=html,
-        api_handler=lambda method, path, request_payload: handle_service_request(
-            method,
-            path,
-            request_payload,
-            capsule_path=resolved_capsule,
-            request_path=resolved_request,
-            route_request_path=resolved_route_request,
-            registry_path=resolved_registry,
-            ledger_path=resolved_ledger,
-            state=state,
-        ),
-        host=host,
-        port=port,
-        open_browser=open_browser,
-        api_path_prefixes=("/api/", "/v1/"),
-        api_exact_paths=("/health",),
-    )
-
-
-def _health_payload(ledger: AuditLedger, state: dict[str, Any]) -> dict[str, Any]:
-    return {
-        "ok": True,
-        "product": PRODUCT_NAME,
-        "capsule_id": state["capsule"]["capsule_id"],
-        "ledger_path": str(ledger.path),
-        "ledger_records": len(ledger.tail()),
-        "service": "policy_api_audit_ledger",
-    }
-
-
-def _mapping(payload: dict[str, Any] | None, key: str) -> dict[str, Any]:
-    if not isinstance(payload, dict):
-        return {}
-    value = payload.get(key)
-    return dict(value) if isinstance(value, dict) else {}
-
-
-def _temporary_ledger_path() -> Path:
-    handle, raw_path = tempfile.mkstemp(prefix="sovereigncode-smoke-", suffix=".audit.jsonl")
-    os.close(handle)
-    path = Path(raw_path)
-    path.unlink(missing_ok=True)
-    return path
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+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
+
+try:  # repo package
+    from tinyluminax.products.marama_route import RoutingRequest, load_model_registry
+except ModuleNotFoundError:  # standalone HF package
+    from marama_route import RoutingRequest, load_model_registry
+
+from .audit import build_audit_record
+from .ledger import AuditLedger, default_ledger_path
+from .planner import plan_coding_turn
+from .platform import (
+    build_capsule_summary,
+    build_policy_matrix,
+    build_turn_brief,
+    check_tool_request,
+)
+from .policy import DataCapsule, SovereignRequest, SovereigntyPolicyEngine
+from .ui import (
+    PRODUCT_NAME,
+    build_dashboard_html,
+    build_dashboard_state,
+    default_capsule_path,
+    default_registry_path,
+    default_request_path,
+    default_route_request_path,
+    handle_api_request,
+)
+
+
+def handle_service_request(
+    method: str,
+    path: str,
+    payload: dict[str, Any] | None,
+    *,
+    capsule_path: Path,
+    request_path: Path,
+    route_request_path: Path,
+    registry_path: Path,
+    ledger_path: Path,
+    state: dict[str, Any] | None = None,
+) -> tuple[int, dict[str, Any]]:
+    ledger = AuditLedger(ledger_path)
+    service_state = state or build_dashboard_state(capsule_path, request_path, route_request_path, registry_path)
+
+    if path.startswith("/api/"):
+        return handle_api_request(method, path, payload, registry_path, service_state)
+    if method == "GET" and path in {"/health", "/v1/health"}:
+        return 200, _health_payload(ledger, service_state)
+    if method == "GET" and path == "/v1/audit":
+        return 200, {"ok": True, "ledger_path": str(ledger.path), "records": ledger.tail()}
+    if method == "GET" and path == "/v1/capsule-summary":
+        return 200, {"ok": True, "summary": build_capsule_summary(service_state["capsule"])}
+    if method == "POST" and path == "/v1/evaluate":
+        result = evaluate_payload(payload or {}, service_state, ledger)
+        return (200 if result["decision"]["allowed"] else 422), result
+    if method == "POST" and path == "/v1/plan-turn":
+        result = plan_turn_payload(payload or {}, service_state, ledger)
+        return (200 if result["allowed"] else 422), result
+    if method == "POST" and path == "/v1/tool-check":
+        result = tool_check_payload(payload or {}, service_state, ledger)
+        return (200 if result["ok"] else 422), result
+    if method == "POST" and path == "/v1/policy-matrix":
+        return 200, policy_matrix_payload(payload or {}, service_state, ledger)
+    if method == "POST" and path == "/v1/capsule-summary":
+        capsule_payload = _mapping(payload, "capsule") or service_state["capsule"]
+        return 200, {"ok": True, "summary": build_capsule_summary(capsule_payload)}
+    return 404, {"ok": False, "error": "not_found"}
+
+
+def evaluate_payload(
+    payload: dict[str, Any],
+    state: dict[str, Any],
+    ledger: AuditLedger,
+) -> dict[str, Any]:
+    capsule = DataCapsule.from_payload(_mapping(payload, "capsule") or state["capsule"])
+    request = SovereignRequest.from_payload(_mapping(payload, "request") or state["request"])
+    decision = SovereigntyPolicyEngine().evaluate(capsule, request)
+    audit = build_audit_record(capsule, request, decision).to_dict()
+    ledger_record = ledger.append(
+        "policy_evaluate",
+        {
+            "capsule_id": capsule.capsule_id,
+            "request": request.to_dict(),
+            "decision": decision.to_dict(),
+            "audit_record": audit,
+        },
+    )
+    return {
+        "ok": decision.allowed,
+        "decision": decision.to_dict(),
+        "audit_record": audit,
+        "ledger_record": ledger_record,
+    }
+
+
+def plan_turn_payload(
+    payload: dict[str, Any],
+    state: dict[str, Any],
+    ledger: AuditLedger,
+) -> dict[str, Any]:
+    capsule = DataCapsule.from_payload(_mapping(payload, "capsule") or state["capsule"])
+    request = SovereignRequest.from_payload(_mapping(payload, "request") or state["request"])
+    route_request = RoutingRequest.from_payload(_mapping(payload, "route_request") or state["route_request"])
+    models = load_model_registry(Path(str(payload.get("registry_path") or state["registry_path"])))
+    plan = plan_coding_turn(capsule, request, route_request, models)
+    result = plan.to_dict()
+    result["turn_brief"] = build_turn_brief(result)
+    result["ledger_record"] = ledger.append(
+        "plan_turn",
+        {
+            "capsule_id": capsule.capsule_id,
+            "allowed": plan.allowed,
+            "policy_decision": result["policy_decision"],
+            "route_decision": result["route_decision"],
+            "audit_record": result["audit_record"],
+            "turn_brief": result["turn_brief"],
+        },
+    )
+    result["ok"] = plan.allowed
+    return result
+
+
+def tool_check_payload(
+    payload: dict[str, Any],
+    state: dict[str, Any],
+    ledger: AuditLedger,
+) -> dict[str, Any]:
+    tool_payload = _mapping(payload, "tool") or {
+        "tool_name": payload.get("tool_name", "workspace_reader"),
+        "action": payload.get("action", "read_context"),
+        "writes_files": bool(payload.get("writes_files", False)),
+        "exports_data": bool(payload.get("exports_data", False)),
+        "trains_model": bool(payload.get("trains_model", False)),
+        "human_approved": bool(payload.get("human_approved", False)),
+    }
+    result = check_tool_request(
+        _mapping(payload, "capsule") or state["capsule"],
+        _mapping(payload, "request") or state["request"],
+        tool_payload,
+    )
+    result["ledger_record"] = ledger.append(
+        "tool_check",
+        {
+            "tool": tool_payload,
+            "decision": result["decision"],
+            "audit_record": result["audit_record"],
+            "operator_gate": result["operator_gate"],
+        },
+    )
+    return result
+
+
+def policy_matrix_payload(
+    payload: dict[str, Any],
+    state: dict[str, Any],
+    ledger: AuditLedger,
+) -> dict[str, Any]:
+    scenarios = payload.get("scenarios") if isinstance(payload.get("scenarios"), list) else None
+    result = build_policy_matrix(
+        _mapping(payload, "capsule") or state["capsule"],
+        _mapping(payload, "request") or state["request"],
+        scenarios,
+    )
+    result["ledger_record"] = ledger.append(
+        "policy_matrix",
+        {
+            "capsule_id": result["capsule_id"],
+            "allowed_count": result["allowed_count"],
+            "blocked_count": result["blocked_count"],
+        },
+    )
+    return result
+
+
+def smoke_service(
+    *,
+    capsule_path: Path | None = None,
+    request_path: Path | None = None,
+    route_request_path: Path | None = None,
+    registry_path: Path | None = None,
+    ledger_path: Path | None = None,
+) -> dict[str, Any]:
+    resolved_capsule = capsule_path or default_capsule_path()
+    resolved_request = request_path or default_request_path()
+    resolved_route_request = route_request_path or default_route_request_path()
+    resolved_registry = registry_path or default_registry_path()
+    resolved_ledger = ledger_path or _temporary_ledger_path()
+    state = build_dashboard_state(resolved_capsule, resolved_request, resolved_route_request, resolved_registry)
+
+    health_status, health = handle_service_request(
+        "GET",
+        "/health",
+        None,
+        capsule_path=resolved_capsule,
+        request_path=resolved_request,
+        route_request_path=resolved_route_request,
+        registry_path=resolved_registry,
+        ledger_path=resolved_ledger,
+        state=state,
+    )
+    evaluate_status, evaluate = handle_service_request(
+        "POST",
+        "/v1/evaluate",
+        {},
+        capsule_path=resolved_capsule,
+        request_path=resolved_request,
+        route_request_path=resolved_route_request,
+        registry_path=resolved_registry,
+        ledger_path=resolved_ledger,
+        state=state,
+    )
+    plan_status, plan = handle_service_request(
+        "POST",
+        "/v1/plan-turn",
+        {},
+        capsule_path=resolved_capsule,
+        request_path=resolved_request,
+        route_request_path=resolved_route_request,
+        registry_path=resolved_registry,
+        ledger_path=resolved_ledger,
+        state=state,
+    )
+    tool_status, tool = handle_service_request(
+        "POST",
+        "/v1/tool-check",
+        {"tool_name": "workspace_reader", "action": "read_context"},
+        capsule_path=resolved_capsule,
+        request_path=resolved_request,
+        route_request_path=resolved_route_request,
+        registry_path=resolved_registry,
+        ledger_path=resolved_ledger,
+        state=state,
+    )
+    audit_status, audit = handle_service_request(
+        "GET",
+        "/v1/audit",
+        None,
+        capsule_path=resolved_capsule,
+        request_path=resolved_request,
+        route_request_path=resolved_route_request,
+        registry_path=resolved_registry,
+        ledger_path=resolved_ledger,
+        state=state,
+    )
+
+    if (health_status, evaluate_status, plan_status, tool_status, audit_status) != (200, 200, 200, 200, 200):
+        raise RuntimeError("SovereignCode service smoke failed")
+    if not evaluate["decision"]["allowed"] or not plan["allowed"] or not tool["ok"]:
+        raise RuntimeError("SovereignCode service smoke did not allow the governed local request")
+    return {
+        "ok": True,
+        "product": PRODUCT_NAME,
+        "capsule_id": state["capsule"]["capsule_id"],
+        "selected_model": plan["turn_brief"]["selected_model"],
+        "ledger_path": str(resolved_ledger),
+        "ledger_records": len(audit["records"]),
+        "tool_next_gate": tool["operator_gate"]["next_gate"],
+    }
+
+
+def serve_service(
+    *,
+    capsule_path: Path | None = None,
+    request_path: Path | None = None,
+    route_request_path: Path | None = None,
+    registry_path: Path | None = None,
+    ledger_path: Path | None = None,
+    host: str = "127.0.0.1",
+    port: int = 8788,
+    open_browser: bool = False,
+    smoke: bool = False,
+) -> int:
+    resolved_capsule = capsule_path or default_capsule_path()
+    resolved_request = request_path or default_request_path()
+    resolved_route_request = route_request_path or default_route_request_path()
+    resolved_registry = registry_path or default_registry_path()
+    resolved_ledger = ledger_path or default_ledger_path()
+    if smoke:
+        print(
+            json.dumps(
+                smoke_service(
+                    capsule_path=resolved_capsule,
+                    request_path=resolved_request,
+                    route_request_path=resolved_route_request,
+                    registry_path=resolved_registry,
+                    ledger_path=ledger_path,
+                ),
+                indent=2,
+                sort_keys=True,
+            ),
+        )
+        return 0
+
+    state = build_dashboard_state(resolved_capsule, resolved_request, resolved_route_request, resolved_registry)
+    html = build_dashboard_html(state)
+    return serve_dashboard(
+        product_name=f"{PRODUCT_NAME} Service",
+        html=html,
+        api_handler=lambda method, path, request_payload: handle_service_request(
+            method,
+            path,
+            request_payload,
+            capsule_path=resolved_capsule,
+            request_path=resolved_request,
+            route_request_path=resolved_route_request,
+            registry_path=resolved_registry,
+            ledger_path=resolved_ledger,
+            state=state,
+        ),
+        host=host,
+        port=port,
+        open_browser=open_browser,
+        api_path_prefixes=("/api/", "/v1/"),
+        api_exact_paths=("/health",),
+    )
+
+
+def _health_payload(ledger: AuditLedger, state: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "ok": True,
+        "product": PRODUCT_NAME,
+        "capsule_id": state["capsule"]["capsule_id"],
+        "ledger_path": str(ledger.path),
+        "ledger_records": len(ledger.tail()),
+        "service": "policy_api_audit_ledger",
+    }
+
+
+def _mapping(payload: dict[str, Any] | None, key: str) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        return {}
+    value = payload.get(key)
+    return dict(value) if isinstance(value, dict) else {}
+
+
+def _temporary_ledger_path() -> Path:
+    handle, raw_path = tempfile.mkstemp(prefix="sovereigncode-smoke-", suffix=".audit.jsonl")
+    os.close(handle)
+    path = Path(raw_path)
+    path.unlink(missing_ok=True)
+    return path