arkaos 4.1.0 → 4.2.0

package/core/runtime/llm_provider.py

@@ -32,7 +32,9 @@ from core.runtime.pricing import estimate_cost_usd
 
 
 _DEFAULT_CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
-_FALLBACK_ORDER: tuple[str, ...] = ("subagent", "ollama", "anthropic-direct", "stub")
+_FALLBACK_ORDER: tuple[str, ...] = (
+    "subagent", "ollama", "openrouter", "anthropic-direct", "stub"
+)
 
 
 # ─── Public dataclass ─────────────────────────────────────────────────
@@ -330,9 +332,16 @@ def _import_ollama_provider() -> type:
     return OllamaProvider
 
 
+def _import_openrouter_provider() -> type:
+    """Lazy import to keep the OpenRouter provider optional at runtime."""
+    from core.runtime.openrouter_provider import OpenRouterProvider
+    return OpenRouterProvider
+
+
 _PROVIDERS: dict[str, type] = {
     "subagent": SubagentProvider,
     "ollama": _import_ollama_provider(),
+    "openrouter": _import_openrouter_provider(),
     "anthropic-direct": AnthropicDirectProvider,
     "stub": StubProvider,
 }

package/core/runtime/model_router.py

@@ -0,0 +1,204 @@
+"""Model Fabric router — resolve a work role to (provider, model, effort).
+
+The user owns ``~/.arkaos/models.yaml``; the packaged default ships at
+``config/models.yaml``. Roles govern everything ArkaOS dispatches
+(subagents, Quality Gate, Forge, fusion, cognition, daemons) — the
+interactive runtime keeps its own main-loop model.
+
+Constitution ``model-routing`` (Excellence Reform 2026-07-05): quality-
+critical roles (design, review, architecture, strategy, quality_gate)
+default to the best model available at maximum effort; only genuinely
+mechanical work economises. The built-in fallback used when no YAML can
+be read encodes the same posture — a missing file never silently
+downgrades a quality role.
+
+Public API::
+
+    resolve("review")          -> ResolvedModel(provider, model, effort)
+    load_config()              -> ModelsConfig
+    ensure_user_config()       -> Path (creates ~/.arkaos/models.yaml)
+    set_role("review", "anthropic/best", effort="max")
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+USER_CONFIG_PATH = Path.home() / ".arkaos" / "models.yaml"
+
+QUALITY_ROLES = frozenset({
+    "design", "review", "architecture", "strategy", "quality_gate",
+})
+KNOWN_EFFORTS = ("low", "medium", "high", "max")
+
+_ALIAS_NAMES = frozenset({"best", "default", "fast"})
+
+
+class RoleChoice(BaseModel):
+    """One role entry as written in models.yaml."""
+
+    provider: str = "runtime"
+    model: str = "best"
+    effort: str = "high"
+
+    @field_validator("effort")
+    @classmethod
+    def _known_effort(cls, value: str) -> str:
+        if value not in KNOWN_EFFORTS:
+            raise ValueError(
+                f"effort must be one of {KNOWN_EFFORTS}, got {value!r}"
+            )
+        return value
+
+
+class FusionConfig(BaseModel):
+    """Judge + panel for the fusion engine (PR-D consumes this)."""
+
+    judge: RoleChoice = Field(default_factory=lambda: RoleChoice(effort="max"))
+    panel: list[RoleChoice] = Field(default_factory=list)
+
+
+class ModelsConfig(BaseModel):
+    """Validated shape of models.yaml."""
+
+    version: int = 1
+    providers: dict[str, dict] = Field(default_factory=dict)
+    aliases: dict[str, dict[str, str]] = Field(default_factory=dict)
+    roles: dict[str, RoleChoice] = Field(default_factory=dict)
+    fusion: FusionConfig = Field(default_factory=FusionConfig)
+
+
+class ResolvedModel(BaseModel):
+    """A role after alias resolution — what a dispatcher actually uses."""
+
+    role: str
+    provider: str
+    model: str
+    effort: str
+    source: str  # "user" | "packaged" | "builtin"
+
+
+def _packaged_config_path() -> Path:
+    return Path(__file__).resolve().parents[2] / "config" / "models.yaml"
+
+
+def _builtin_config() -> ModelsConfig:
+    """Quality-first posture used when no YAML is readable at all."""
+    roles = {
+        role: RoleChoice(model="best", effort="max") for role in QUALITY_ROLES
+    }
+    roles["execution"] = RoleChoice(model="default", effort="high")
+    roles["mechanical"] = RoleChoice(model="fast", effort="low")
+    return ModelsConfig(
+        providers={"runtime": {"type": "subagent"}},
+        aliases={"runtime": {"best": "opus", "default": "sonnet", "fast": "haiku"}},
+        roles=roles,
+    )
+
+
+def _read_yaml(path: Path) -> ModelsConfig | None:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    try:
+        return ModelsConfig.model_validate(data)
+    except ValueError:
+        return None
+
+
+def load_config(user_path: Path | None = None) -> tuple[ModelsConfig, str]:
+    """Load config with provenance: user file, packaged default, builtin."""
+    path = user_path or USER_CONFIG_PATH
+    config = _read_yaml(path) if path.is_file() else None
+    if config is not None:
+        return config, "user"
+    packaged = _packaged_config_path()
+    config = _read_yaml(packaged) if packaged.is_file() else None
+    if config is not None:
+        return config, "packaged"
+    return _builtin_config(), "builtin"
+
+
+def _resolve_alias(config: ModelsConfig, provider: str, model: str) -> str:
+    if model not in _ALIAS_NAMES:
+        return model
+    return config.aliases.get(provider, {}).get(model, "") or model
+
+
+def resolve(role: str, user_path: Path | None = None) -> ResolvedModel:
+    """Resolve a role name to a concrete (provider, model, effort).
+
+    Unknown roles resolve conservatively: quality posture, not economy —
+    a typo must never silently land on the cheap tier
+    (``excellence-mandate``).
+    """
+    config, source = load_config(user_path)
+    choice = config.roles.get(role)
+    if choice is None:
+        fallback = "execution" if role not in QUALITY_ROLES else role
+        choice = config.roles.get(fallback, RoleChoice(model="best", effort="max"))
+    return ResolvedModel(
+        role=role,
+        provider=choice.provider,
+        model=_resolve_alias(config, choice.provider, choice.model),
+        effort=choice.effort,
+        source=source,
+    )
+
+
+def resolve_all(user_path: Path | None = None) -> list[ResolvedModel]:
+    """Resolve every configured role — the CLI table."""
+    config, _ = load_config(user_path)
+    return [resolve(role, user_path) for role in sorted(config.roles)]
+
+
+def ensure_user_config(user_path: Path | None = None) -> Path:
+    """Create ~/.arkaos/models.yaml from the packaged default if absent."""
+    path = user_path or USER_CONFIG_PATH
+    if path.is_file():
+        return path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    packaged = _packaged_config_path()
+    if packaged.is_file():
+        shutil.copy(packaged, path)
+    else:
+        path.write_text(
+            yaml.safe_dump(_builtin_config().model_dump(), sort_keys=False),
+            encoding="utf-8",
+        )
+    return path
+
+
+def set_role(
+    role: str,
+    target: str,
+    effort: str | None = None,
+    user_path: Path | None = None,
+) -> ResolvedModel:
+    """Point a role at ``provider/model`` (e.g. ``anthropic/best``).
+
+    Writes the user file (creating it first when needed) and returns the
+    new resolution. Raises ValueError on a malformed target or effort.
+    """
+    if "/" not in target:
+        raise ValueError(
+            f"target must be provider/model (e.g. runtime/best), got {target!r}"
+        )
+    provider, model = target.split("/", 1)
+    path = ensure_user_config(user_path)
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    entry = {"provider": provider, "model": model}
+    entry["effort"] = effort or data.get("roles", {}).get(role, {}).get(
+        "effort", "max" if role in QUALITY_ROLES else "high"
+    )
+    RoleChoice.model_validate(entry)  # fail before writing anything
+    data.setdefault("roles", {})[role] = entry
+    path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+    return resolve(role, path)

package/core/runtime/model_router_cli.py

@@ -0,0 +1,82 @@
+"""CLI for the Model Fabric router — `npx arkaos models` delegates here.
+
+Usage::
+
+    python -m core.runtime.model_router_cli               # table of roles
+    python -m core.runtime.model_router_cli --json        # machine-readable
+    python -m core.runtime.model_router_cli init          # create user file
+    python -m core.runtime.model_router_cli set review anthropic/best --effort max
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from core.runtime.model_router import (
+    USER_CONFIG_PATH,
+    ensure_user_config,
+    load_config,
+    resolve_all,
+    set_role,
+)
+
+
+def _print_table() -> None:
+    resolved = resolve_all()
+    _, source = load_config()
+    print()
+    print("  ArkaOS Model Fabric — role routing")
+    print(f"  config: {USER_CONFIG_PATH if source == 'user' else source}")
+    print()
+    header = f"  {'ROLE':<14} {'PROVIDER':<12} {'MODEL':<34} EFFORT"
+    print(header)
+    print("  " + "─" * (len(header) - 2))
+    for item in resolved:
+        model = item.model or "(unset — configure alias)"
+        print(f"  {item.role:<14} {item.provider:<12} {model:<34} {item.effort}")
+    print()
+    print("  Change: npx arkaos models set <role> <provider>/<model> [--effort max]")
+    print()
+
+
+def _print_json() -> None:
+    payload = [item.model_dump() for item in resolve_all()]
+    print(json.dumps(payload, indent=2))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="arkaos models")
+    parser.add_argument("action", nargs="?", default="list",
+                        choices=["list", "init", "set"])
+    parser.add_argument("role", nargs="?")
+    parser.add_argument("target", nargs="?")
+    parser.add_argument("--effort", choices=["low", "medium", "high", "max"])
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    if args.action == "init":
+        path = ensure_user_config()
+        print(f"  ✓ Model Fabric config: {path}")
+        return 0
+    if args.action == "set":
+        if not args.role or not args.target:
+            parser.error("set requires: <role> <provider>/<model>")
+        try:
+            item = set_role(args.role, args.target, effort=args.effort)
+        except ValueError as exc:
+            print(f"  ✗ {exc}", file=sys.stderr)
+            return 1
+        print(f"  ✓ {item.role} -> {item.provider}/{item.model} "
+              f"(effort {item.effort})")
+        return 0
+    if args.as_json:
+        _print_json()
+    else:
+        _print_table()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/runtime/openrouter_provider.py

@@ -0,0 +1,172 @@
+"""OpenRouter provider — one API key, hundreds of models.
+
+Model Fabric PR-B. One of the backends behind the ``LLMProvider``
+Protocol in ``core/runtime/llm_provider.py``; callers go through
+``get_llm_provider()`` or pass an explicit model resolved by
+``core/runtime/model_router.py`` (e.g. role ``review`` →
+``openrouter/deepseek/deepseek-v4-pro``).
+
+OpenAI-compatible ``/api/v1/chat/completions`` via stdlib ``urllib`` —
+no extra dependencies, mirroring ``ollama_provider.py``. Key resolution:
+``OPENROUTER_API_KEY`` env, then ``~/.arkaos/keys.json``. Model from
+constructor, then ``OPENROUTER_MODEL`` env, then
+``models.yaml`` alias ``openrouter.default``.
+
+OpenRouter returns token usage (and native cached-token counts for
+providers that support caching) in the ``usage`` block; both are
+forwarded so cost telemetry stays accurate.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from core.runtime.llm_provider import LLMResponse, LLMUnavailable
+
+_API_BASE = "https://openrouter.ai/api/v1"
+_TIMEOUT_S = 180  # frontier models on long prompts; fusion panels wait
+_KEYS_PATH = Path.home() / ".arkaos" / "keys.json"
+
+# Attribution headers — OpenRouter ranks apps by these; harmless otherwise.
+_APP_HEADERS = {
+    "HTTP-Referer": "https://github.com/andreagroferreira/arka-os",
+    "X-Title": "ArkaOS",
+}
+
+
+def _read_key_from_keys_json() -> str:
+    try:
+        data = json.loads(_KEYS_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    value = data.get("OPENROUTER_API_KEY", "")
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _default_model_from_fabric() -> str:
+    """Resolve the `openrouter.default` alias from models.yaml, if set."""
+    try:
+        from core.runtime.model_router import load_config
+        config, _ = load_config()
+    except Exception:
+        return ""
+    return config.aliases.get("openrouter", {}).get("default", "")
+
+
+class OpenRouterProvider:
+    """Provider that hits the OpenRouter chat-completions API."""
+
+    ENV_KEY = "OPENROUTER_API_KEY"
+    ENV_MODEL = "OPENROUTER_MODEL"
+
+    def __init__(self, model: str | None = None, api_base: str | None = None) -> None:
+        self._model_override = model
+        self._api_base = (api_base or _API_BASE).rstrip("/")
+
+    def name(self) -> str:
+        return "openrouter"
+
+    def _resolve_key(self) -> str:
+        env_value = os.environ.get(self.ENV_KEY, "").strip()
+        return env_value or _read_key_from_keys_json()
+
+    def _resolve_model(self) -> str:
+        if self._model_override:
+            return self._model_override
+        env_value = os.environ.get(self.ENV_MODEL, "").strip()
+        return env_value or _default_model_from_fabric()
+
+    def is_available(self) -> bool:
+        """Static capability check: a key and a model are configured.
+
+        No network probe — OpenRouter is a paid remote API and this is
+        called on every provider-chain walk; a dead network surfaces as
+        ``LLMUnavailable`` at call time and the chain moves on.
+        """
+        return bool(self._resolve_key() and self._resolve_model())
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int = 2000,
+        system: str = "",
+    ) -> LLMResponse:
+        key = self._resolve_key()
+        if not key:
+            raise LLMUnavailable(
+                "OpenRouter key not configured (set OPENROUTER_API_KEY or "
+                "add it via `npx arkaos keys`)"
+            )
+        model = self._resolve_model()
+        if not model:
+            raise LLMUnavailable(
+                "OpenRouter model not configured (set OPENROUTER_MODEL, pass "
+                "model=, or set aliases.openrouter.default in models.yaml)"
+            )
+        data = self._post_chat(key, self._build_payload(model, prompt, system, max_tokens))
+        return self._to_response(data, model)
+
+    def _build_payload(
+        self, model: str, prompt: str, system: str, max_tokens: int
+    ) -> dict:
+        messages: list[dict] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        return {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "stream": False,
+            "usage": {"include": True},  # cost + cached tokens in response
+        }
+
+    def _post_chat(self, key: str, payload: dict) -> dict:
+        request = urllib.request.Request(
+            f"{self._api_base}/chat/completions",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {key}",
+                **_APP_HEADERS,
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=_TIMEOUT_S) as response:
+                raw = response.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:300]
+            raise LLMUnavailable(
+                f"OpenRouter HTTP {exc.code}: {detail}"
+            ) from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise LLMUnavailable(f"OpenRouter request failed: {exc}") from exc
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise LLMUnavailable(f"OpenRouter returned invalid JSON: {exc}") from exc
+
+    def _to_response(self, data: dict, model: str) -> LLMResponse:
+        if data.get("error"):
+            message = data["error"].get("message", "unknown error")
+            raise LLMUnavailable(f"OpenRouter error: {message}")
+        choices = data.get("choices") or []
+        text = ""
+        if choices:
+            text = ((choices[0].get("message") or {}).get("content") or "").strip()
+        usage = data.get("usage") or {}
+        cached = int(
+            (usage.get("prompt_tokens_details") or {}).get("cached_tokens", 0) or 0
+        )
+        return LLMResponse(
+            text=text,
+            tokens_in=int(usage.get("prompt_tokens", 0) or 0),
+            tokens_out=int(usage.get("completion_tokens", 0) or 0),
+            cached_tokens=cached,
+            model=str(data.get("model") or model),
+        )