snapdec 0.2.0__py3-none-any.whl

snapdec/_brand.py

@@ -0,0 +1,8 @@
+"""Single source of truth for the project name (rename gate §1.4).
+
+A rename must be a single commit: this constant + pyproject.toml.
+Do not hardcode the name anywhere else.
+"""
+
+__version__ = "0.2.0"
+NAME = "snapdec"  # final — rename gate cleared 2026-10-03, see docs/adr/0007

snapdec/backends/__init__.py

@@ -0,0 +1,5 @@
+from .base import Backend, Health
+from .mock import MockBackend
+from .remote_systemone import RemoteSystemOne
+
+__all__ = ["Backend", "Health", "MockBackend", "RemoteSystemOne"]

snapdec/backends/base.py

@@ -0,0 +1,31 @@
+"""Backend interface (§6).
+
+Backends are interchangeable behind one interface; anything that already
+speaks /v1/systemone (hosted Jev, kev.serve, laya-serve, OpenRouter) is
+just a manifest/URL away — no adapter code needed (remote_systemone).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from ..decisions.envelope import SystemOneRequest, SystemOneResponse
+
+
+@dataclass
+class Health:
+    status: str  # ready | warming | degraded | failed
+    device: str = ""
+    detail: str = ""
+
+
+@runtime_checkable
+class Backend(Protocol):
+    id: str
+
+    def load(self) -> None: ...
+    def system_one(self, req: SystemOneRequest) -> SystemOneResponse: ...
+    def health(self) -> Health: ...
+    def close(self) -> None: ...
+    def describe(self) -> dict[str, Any]: ...

snapdec/backends/keydetect.py

@@ -0,0 +1,67 @@
+"""Auto-detect the provider from a pasted API key (§9.1 'all auto').
+
+Only System One-compatible endpoints are usable by the remote backend.
+OpenRouter is the universal bridge (hosts Jev/Kev models); OpenAI/Groq/
+Anthropic keys do NOT speak /v1/systemone and are reported as such with
+a hint instead of being silently misrouted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ProviderGuess:
+    provider: str          # openrouter | typesafe | unsupported:<id> | unknown
+    url: str = ""
+    default_models: tuple[str, ...] = ()
+    note: str = ""
+
+
+_OPENROUTER = ProviderGuess(
+    "openrouter", "https://openrouter.ai/api/v1",
+    # free variants first — "paid or free judgement": try :free, fall back
+    ("jaredpalmer/kev-4b:free", "jaredpalmer/kev-4b", "typesafe/jev-latest"),
+    "OpenRouter — universal bridge, hosts Jev/Kev",
+)
+_TYPESAFE = ProviderGuess(
+    "typesafe", "https://api.typesafe.ai",
+    ("jev-latest",),
+    "TypeSafe Jev — native System One",
+)
+
+
+def detect_provider(key: str) -> ProviderGuess:
+    k = key.strip()
+    if k.startswith("sk-or-"):
+        return _OPENROUTER
+    if k.startswith("ts-") or k.startswith("tsk_"):
+        return _TYPESAFE
+    if k.startswith("sk-ant-"):
+        return ProviderGuess("unsupported:anthropic", note=(
+            "Anthropic key detected — Anthropic speaks /v1/messages, not "
+            "/v1/systemone. Create a free OpenRouter key (openrouter.ai/keys) "
+            "and paste that instead."))
+    if k.startswith("gsk_"):
+        return ProviderGuess("unsupported:groq", note=(
+            "Groq key detected — not System One compatible. "
+            "Use an OpenRouter key (openrouter.ai/keys)."))
+    if k.startswith("sk-proj-") or k.startswith("sk-"):
+        return ProviderGuess("unsupported:openai", note=(
+            "OpenAI key detected — not System One compatible. "
+            "Use an OpenRouter key (openrouter.ai/keys) or a TypeSafe key."))
+    return ProviderGuess("unknown")
+
+
+def provider_by_id(pid: str) -> ProviderGuess:
+    return {"openrouter": _OPENROUTER, "typesafe": _TYPESAFE}.get(pid, ProviderGuess(pid))
+
+
+def pick_model(guess: ProviderGuess, *, low_power: bool = False) -> str:
+    """Device-aware default: hosted models are small enough that the wire
+    cost dominates; low-power devices still prefer the cheapest first."""
+    models = guess.default_models
+    if not models:
+        return ""
+    return models[0]

snapdec/backends/mock.py

@@ -0,0 +1,72 @@
+"""Deterministic mock backend — tests, demos, and `--backend mock`."""
+
+from __future__ import annotations
+
+import hashlib
+import random
+from typing import Any
+
+from ..decisions.envelope import (
+    Answer,
+    SystemOneRequest,
+    SystemOneResponse,
+)
+from .base import Health
+
+
+class MockBackend:
+    id = "mock"
+
+    def load(self) -> None:
+        pass
+
+    def _dist(self, seed_text: str, options: list[str]) -> dict[str, float]:
+        """Stable pseudo-distribution: same input → same numbers."""
+        rng = random.Random(int(hashlib.sha256(seed_text.encode("utf-8")).hexdigest()[:8], 16))
+        raw = [rng.random() + 0.35 for _ in options] or [1.0]
+        total = sum(raw)
+        probs = [r / total for r in raw]
+        # sharpen the top so `auto` is reachable with default thresholds
+        top = probs.index(max(probs))
+        probs[top] += 0.30
+        total = sum(probs)
+        return {o: p / total for o, p in zip(options, probs, strict=False)}
+
+    def system_one(self, req: SystemOneRequest) -> SystemOneResponse:
+        state = req.state if isinstance(req.state, str) else str(req.state)
+        answers: dict[str, Answer] = {}
+        for name, q in req.questions.items():
+            if q.type == "noul":
+                probs = self._dist(f"{state}|{name}", ["yes", "no"])
+                answers[name] = Answer(
+                    type="noul", noul=probs["yes"] > probs["no"], probabilities=probs,
+                    confidence=max(probs.values()),
+                )
+            elif q.type == "score":
+                levels = list(q.criteria) if isinstance(q.criteria, (list, dict)) else \
+                    [f"L{i}" for i in range(1, 6)]
+                probs = self._dist(f"{state}|{name}", levels)
+                best = max(probs, key=probs.get)
+                idx = levels.index(best)
+                answers[name] = Answer(
+                    type="score", score=idx + 1, nearest_level=best,
+                    probabilities=probs, confidence=probs[best],
+                )
+            else:  # choice
+                options = list(q.criteria) if q.criteria else ["a", "b"]
+                probs = self._dist(f"{state}|{name}", options)
+                best = max(probs, key=probs.get)
+                answers[name] = Answer(
+                    type="choice", choice=best, probabilities=probs,
+                    confidence=probs[best],
+                )
+        return SystemOneResponse(answers=answers, model="mock-1")
+
+    def health(self) -> Health:
+        return Health(status="ready", device="cpu", detail="deterministic mock")
+
+    def close(self) -> None:
+        pass
+
+    def describe(self) -> dict[str, Any]:
+        return {"name": self.id, "model": "mock-1", "remote": False, "ready": True}

snapdec/backends/remote_systemone.py

@@ -0,0 +1,79 @@
+"""Remote /v1/systemone backend (§6).
+
+Works unchanged with: hosted TypeSafe Jev, OpenRouter-hosted models,
+kev.serve, laya-serve, team servers, Telnyx/Opper/LLM Gateway.
+Fail-closed: any transport error raises; the daemon converts it into a
+`review` envelope — never into an exception toward the host agent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ..decisions.envelope import (
+    Answer,
+    SystemOneRequest,
+    SystemOneResponse,
+)
+from .base import Health
+
+
+class RemoteSystemOne:
+    id = "remote"
+
+    def __init__(self, base_url: str, model: str = "", api_key: str | None = None,
+                 timeout: float = 5.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.api_key = api_key
+        self.timeout = timeout
+
+    # ---------------------------------------------------------------- http
+    def _headers(self) -> dict[str, str]:
+        h = {"content-type": "application/json"}
+        if self.api_key:
+            h["authorization"] = f"Bearer {self.api_key}"
+            h["x-api-key"] = self.api_key  # kev.serve / laya-serve convention
+        return h
+
+    def load(self) -> None:
+        pass  # no local state; readiness checked via health()
+
+    def system_one(self, req: SystemOneRequest) -> SystemOneResponse:
+        payload = req.model_dump(exclude_none=True)
+        if self.model:
+            payload["model"] = self.model
+        r = httpx.post(
+            f"{self.base_url}/v1/systemone",
+            json=payload, headers=self._headers(), timeout=self.timeout,
+        )
+        r.raise_for_status()
+        data = r.json()
+        answers = {k: Answer(**v) for k, v in (data.get("answers") or {}).items()}
+        return SystemOneResponse(answers=answers, usage=data.get("usage"),
+                                 model=data.get("model"))
+
+    def health(self) -> Health:
+        try:
+            with httpx.Client(timeout=self.timeout) as c:
+                r = c.get(f"{self.base_url}/v1/models", headers=self._headers())
+                if r.status_code == 404:  # laya-serve exposes /models, not /v1/models
+                    r = c.get(f"{self.base_url}/models", headers=self._headers())
+                if r.status_code in (200, 401, 403):
+                    # 401/403 = server is up, key is wrong — still "reachable"
+                    status = "ready" if r.status_code == 200 else "degraded"
+                    return Health(status=status, device="remote",
+                                  detail=f"HTTP {r.status_code}")
+                return Health(status="degraded", device="remote",
+                              detail=f"HTTP {r.status_code}")
+        except httpx.HTTPError as e:
+            return Health(status="failed", device="remote", detail=str(e))
+
+    def close(self) -> None:
+        pass
+
+    def describe(self) -> dict[str, Any]:
+        return {"name": self.id, "url": self.base_url, "model": self.model,
+                "remote": True}

snapdec/cli/__init__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+__all__ = ["app"]

snapdec/cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+app()