ski-sdk 0.1.0__py3-none-any.whl

ski_sdk/__init__.py

@@ -0,0 +1,47 @@
+"""ski-sdk — typed Python client for the SKI Framework SKI Model.
+
+> Early alpha: wraps an alpha HTTP API; pin your versions.
+"""
+
+from __future__ import annotations
+
+from .client import AsyncSKIClient, SKIClient
+from .errors import (
+    SKIAuthError,
+    SKIError,
+    SKIResponseError,
+    SKIServiceUnavailable,
+    SKITransportError,
+    SKIValidationError,
+)
+from .models import (
+    HealthStatus,
+    LLMTranscript,
+    MeasurementRecord,
+    V3Verdict,
+    V3VerdictEnvelope,
+    VerifierStatus,
+)
+from .verify import VerificationReport, verify_transcript
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncSKIClient",
+    "HealthStatus",
+    "LLMTranscript",
+    "MeasurementRecord",
+    "SKIAuthError",
+    "SKIClient",
+    "SKIError",
+    "SKIResponseError",
+    "SKIServiceUnavailable",
+    "SKITransportError",
+    "SKIValidationError",
+    "V3Verdict",
+    "V3VerdictEnvelope",
+    "VerificationReport",
+    "VerifierStatus",
+    "__version__",
+    "verify_transcript",
+]

ski_sdk/client.py

@@ -0,0 +1,242 @@
+"""Synchronous and asynchronous HTTP clients for the SKI Model.
+
+Thin wrappers over httpx that send the API key as the ``x-api-key`` header,
+verify TLS by default, parse responses into typed models, and map HTTP status
+codes onto the SDK error hierarchy. Idempotent GETs are retried with backoff;
+non-idempotent POSTs are not.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from .errors import (
+    SKIAuthError,
+    SKIResponseError,
+    SKIServiceUnavailable,
+    SKITransportError,
+    SKIValidationError,
+)
+from .models import HealthStatus, MeasurementRecord, V3VerdictEnvelope
+
+_DEFAULT_TIMEOUT = 30.0
+
+
+def _detail(resp: httpx.Response) -> Optional[str]:
+    try:
+        body = resp.json()
+        return body.get("detail") if isinstance(body, dict) else None
+    except Exception:
+        return None
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    if resp.status_code < 400:
+        return
+    detail = _detail(resp)
+    if resp.status_code == 401:
+        raise SKIAuthError(401, detail)
+    if resp.status_code == 503:
+        raise SKIServiceUnavailable(503, detail)
+    if 400 <= resp.status_code < 500:
+        raise SKIValidationError(resp.status_code, detail)
+    raise SKIResponseError(resp.status_code, detail)
+
+
+def _headers(api_key: Optional[str]) -> Dict[str, str]:
+    return {"x-api-key": api_key} if api_key else {}
+
+
+class _Base:
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: Optional[str] = None,
+        *,
+        verify_tls: Union[bool, str] = True,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/")
+        self._api_key = api_key
+        self._max_retries = max_retries
+
+    def __repr__(self) -> str:  # never leak the API key
+        return (
+            f"{type(self).__name__}(endpoint={self._endpoint!r}, api_key={'***' if self._api_key else None})"
+        )
+
+
+class SKIClient(_Base):
+    """Synchronous SKI Model client."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: Optional[str] = None,
+        *,
+        verify_tls: Union[bool, str] = True,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        super().__init__(endpoint, api_key, verify_tls=verify_tls, timeout=timeout, max_retries=max_retries)
+        self._client = httpx.Client(
+            base_url=self._endpoint,
+            verify=verify_tls,
+            timeout=timeout,
+            headers=_headers(api_key),
+            transport=transport,
+        )
+
+    def __enter__(self) -> SKIClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                resp = self._client.get(path, params=params)
+            except httpx.RequestError as exc:
+                if attempt >= self._max_retries:
+                    raise SKITransportError(str(exc)) from exc
+            else:
+                if resp.status_code < 500 or attempt >= self._max_retries:
+                    _raise_for_status(resp)
+                    return resp
+            time.sleep(0.25 * (2**attempt))
+            attempt += 1
+
+    def _post(self, path: str, json_body: Dict[str, Any]) -> httpx.Response:
+        try:
+            resp = self._client.post(path, json=json_body)
+        except httpx.RequestError as exc:
+            raise SKITransportError(str(exc)) from exc
+        _raise_for_status(resp)
+        return resp
+
+    def evaluate(
+        self,
+        *,
+        measurement_id: str,
+        timestamp: str,
+        subject: str,
+        measurement: Dict[str, Any],
+        jurisdiction: Optional[str] = None,
+    ) -> V3VerdictEnvelope:
+        body = MeasurementRecord(
+            measurement_id=measurement_id,
+            timestamp=timestamp,
+            subject=subject,
+            measurement=measurement,
+            jurisdiction=jurisdiction,
+        ).model_dump()
+        return V3VerdictEnvelope.model_validate(self._post("/api/evaluate", body).json())
+
+    def health(self) -> HealthStatus:
+        return HealthStatus.model_validate(self._get("/api/health").json())
+
+    def list_verdicts(self, *, limit: int = 100, offset: int = 0) -> Dict[str, Any]:
+        return dict(self._get("/api/verdicts", params={"limit": limit, "offset": offset}).json())
+
+    def load_kg(self, signed_kg: Dict[str, Any]) -> Dict[str, Any]:
+        return dict(self._post("/api/kg/load", signed_kg).json())
+
+
+class AsyncSKIClient(_Base):
+    """Asynchronous SKI Model client (mirrors :class:`SKIClient`)."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: Optional[str] = None,
+        *,
+        verify_tls: Union[bool, str] = True,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        super().__init__(endpoint, api_key, verify_tls=verify_tls, timeout=timeout, max_retries=max_retries)
+        self._client = httpx.AsyncClient(
+            base_url=self._endpoint,
+            verify=verify_tls,
+            timeout=timeout,
+            headers=_headers(api_key),
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> AsyncSKIClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                resp = await self._client.get(path, params=params)
+            except httpx.RequestError as exc:
+                if attempt >= self._max_retries:
+                    raise SKITransportError(str(exc)) from exc
+            else:
+                if resp.status_code < 500 or attempt >= self._max_retries:
+                    _raise_for_status(resp)
+                    return resp
+            await asyncio.sleep(0.25 * (2**attempt))
+            attempt += 1
+
+    async def _post(self, path: str, json_body: Dict[str, Any]) -> httpx.Response:
+        try:
+            resp = await self._client.post(path, json=json_body)
+        except httpx.RequestError as exc:
+            raise SKITransportError(str(exc)) from exc
+        _raise_for_status(resp)
+        return resp
+
+    async def evaluate(
+        self,
+        *,
+        measurement_id: str,
+        timestamp: str,
+        subject: str,
+        measurement: Dict[str, Any],
+        jurisdiction: Optional[str] = None,
+    ) -> V3VerdictEnvelope:
+        body = MeasurementRecord(
+            measurement_id=measurement_id,
+            timestamp=timestamp,
+            subject=subject,
+            measurement=measurement,
+            jurisdiction=jurisdiction,
+        ).model_dump()
+        resp = await self._post("/api/evaluate", body)
+        return V3VerdictEnvelope.model_validate(resp.json())
+
+    async def health(self) -> HealthStatus:
+        resp = await self._get("/api/health")
+        return HealthStatus.model_validate(resp.json())
+
+    async def list_verdicts(self, *, limit: int = 100, offset: int = 0) -> Dict[str, Any]:
+        resp = await self._get("/api/verdicts", params={"limit": limit, "offset": offset})
+        return dict(resp.json())
+
+    async def load_kg(self, signed_kg: Dict[str, Any]) -> Dict[str, Any]:
+        resp = await self._post("/api/kg/load", signed_kg)
+        return dict(resp.json())
+
+
+__all__ = ["AsyncSKIClient", "SKIClient"]

ski_sdk/errors.py

@@ -0,0 +1,48 @@
+"""Typed error hierarchy for the SKI SDK.
+
+Callers branch on the exception type rather than parsing strings. The API
+key is never included in any message or repr.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class SKIError(Exception):
+    """Base class for all SKI SDK errors."""
+
+
+class SKITransportError(SKIError):
+    """Network/TLS failure reaching the SKI Model (no HTTP response)."""
+
+
+class SKIResponseError(SKIError):
+    """The SKI Model returned an HTTP error status."""
+
+    def __init__(self, status_code: int, detail: Optional[str] = None) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"SKI Model returned HTTP {status_code}" + (f": {detail}" if detail else ""))
+
+
+class SKIAuthError(SKIResponseError):
+    """401 — missing or invalid API key."""
+
+
+class SKIServiceUnavailable(SKIResponseError):
+    """503 — service not ready (e.g. no Knowledge Graph loaded)."""
+
+
+class SKIValidationError(SKIResponseError):
+    """4xx — the request payload was rejected by the SKI Model."""
+
+
+__all__ = [
+    "SKIAuthError",
+    "SKIError",
+    "SKIResponseError",
+    "SKIServiceUnavailable",
+    "SKITransportError",
+    "SKIValidationError",
+]

ski_sdk/models.py

@@ -0,0 +1,145 @@
+"""Wire-contract models, mirrored from the SKI Model v3 envelope (spec §4-§6).
+
+These intentionally duplicate the server's Pydantic models so the SDK has no
+dependency on the reference implementation. A contract-drift test
+(`tests/test_contract_drift.py`) asserts the field sets stay in lock-step with
+the server's `V3VerdictEnvelope` / `MeasurementRecord` / `LLMTranscript`.
+
+Response models use ``extra="ignore"`` so a forward-compatible server that adds
+a field does not break older SDKs at runtime; the drift test is what flags the
+divergence in CI.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+_RESPONSE = ConfigDict(use_enum_values=True, extra="ignore", protected_namespaces=())
+
+
+class V3Verdict(str, Enum):
+    CLEAR = "CLEAR"
+    FLAG = "FLAG"
+    DISCRETIONARY = "DISCRETIONARY"
+    NULL_UNMAPPED = "NULL_UNMAPPED"
+    NULL_STALE = "NULL_STALE"
+
+
+class VerifierStatus(str, Enum):
+    AGREED = "AGREED"
+    LLM_CONTRADICTION = "LLM_CONTRADICTION"
+    NEURO_SYMBOLIC_DIVERGENCE = "NEURO_SYMBOLIC_DIVERGENCE"
+    UNVERIFIABLE = "UNVERIFIABLE"
+
+
+class KGCitationRole(str, Enum):
+    OBLIGATION = "obligation"
+    DEFINITION = "definition"
+    PRECEDENT = "precedent"
+
+
+class KGCitation(BaseModel):
+    model_config = _RESPONSE
+    node_id: str
+    version: str
+    role: str
+
+
+class FormalizableAssertion(BaseModel):
+    model_config = _RESPONSE
+    predicate: str
+    metric: str
+    value: Union[float, int, str, List[Any], None] = None
+    observed: Union[float, int, str, List[Any], None] = None
+    satisfied: bool
+    obligation_id: str
+    window_seconds: Optional[int] = None
+
+
+class VerifierResult(BaseModel):
+    model_config = _RESPONSE
+    status: str
+    checked_assertions: int = 0
+    divergences: List[str] = Field(default_factory=list)
+
+
+class ModelProvenance(BaseModel):
+    model_config = _RESPONSE
+    model_weight_hash: str
+    kg_version_hash: str
+    prompt_template_id: str
+    prompt_template_hash: str
+    decoder_seed: int
+    structured_grammar_hash: str
+
+
+class V3VerdictEnvelope(BaseModel):
+    model_config = _RESPONSE
+    verdict: str
+    reasoning: str
+    kg_citations: List[KGCitation] = Field(default_factory=list)
+    formalizable_assertions: List[FormalizableAssertion] = Field(default_factory=list)
+    verifier_result: VerifierResult
+    model_provenance: ModelProvenance
+    transcript_ref: str
+    human_attestation: Optional[Dict[str, Any]] = None
+    notes: List[str] = Field(default_factory=list)
+    verdict_path: Optional[str] = None
+
+
+class MeasurementRecord(BaseModel):
+    """Request body for ``POST /api/evaluate``."""
+
+    model_config = ConfigDict(extra="forbid")
+    measurement_id: str
+    timestamp: str
+    subject: str
+    measurement: Dict[str, Any] = Field(default_factory=dict)
+    jurisdiction: Optional[str] = None
+
+
+class LLMTranscript(BaseModel):
+    """The signed transcript an auditor verifies (spec §6.2)."""
+
+    model_config = ConfigDict(extra="ignore")
+    transcript_id: str
+    request_canonical: str
+    request_hash: str
+    response_canonical: Dict[str, Any]
+    response_hash: str
+    signature_hex: str
+    signing_key_id: str
+    backend_name: str
+    backend_metadata: Dict[str, Any] = Field(default_factory=dict)
+    started_at: datetime
+    completed_at: datetime
+
+
+class HealthStatus(BaseModel):
+    model_config = _RESPONSE
+    status: str
+    kg_loaded: bool
+    kg_signature_verified: bool
+    canary_status: str
+    verdicts_produced: int
+    timestamp: str
+    runtime_version: str
+
+
+__all__ = [
+    "FormalizableAssertion",
+    "HealthStatus",
+    "KGCitation",
+    "KGCitationRole",
+    "LLMTranscript",
+    "MeasurementRecord",
+    "ModelProvenance",
+    "V3Verdict",
+    "V3VerdictEnvelope",
+    "VerifierResult",
+    "VerifierStatus",
+]

ski_sdk/verify.py

@@ -0,0 +1,80 @@
+"""Verify the signed provenance of a verdict's LLM transcript (spec §6.2).
+
+Re-implements the framework's canonicalisation and Ed25519 verification so the
+SDK depends only on `cryptography` — not on the reference implementation. The
+runtime signs ``request_hash || "|" || response_hash``; an auditor recomputes
+those hashes from the canonical request/response, then verifies the signature
+against the runtime's public key.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Union
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+from .models import LLMTranscript
+
+
+def _sha256_prefixed(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _canonical_response(response: Mapping[str, Any]) -> bytes:
+    return json.dumps(dict(response), sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+
+
+@dataclass(frozen=True)
+class VerificationReport:
+    """Result of verifying a transcript."""
+
+    signature_valid: bool
+    hashes_match: bool
+    ok: bool
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+def verify_transcript(
+    transcript: Union[LLMTranscript, Dict[str, Any]],
+    public_key_pem: Union[str, bytes],
+    *,
+    strict: bool = True,
+) -> VerificationReport:
+    """Verify a transcript's Ed25519 signature (and, in strict mode, its hashes).
+
+    ``strict=True`` (default) also recomputes ``request_hash``/``response_hash``
+    from the canonical request/response and confirms they match the recorded
+    values — catching a response that was altered after signing.
+    """
+    t = transcript if isinstance(transcript, LLMTranscript) else LLMTranscript.model_validate(transcript)
+
+    recomputed_req = _sha256_prefixed(t.request_canonical.encode("utf-8"))
+    recomputed_resp = _sha256_prefixed(_canonical_response(t.response_canonical))
+    hashes_match = recomputed_req == t.request_hash and recomputed_resp == t.response_hash
+
+    pem = public_key_pem.encode("ascii") if isinstance(public_key_pem, str) else public_key_pem
+    key = load_pem_public_key(pem)
+    if not isinstance(key, Ed25519PublicKey):
+        raise ValueError("public_key_pem is not an Ed25519 public key.")
+
+    message = f"{t.request_hash}|{t.response_hash}".encode("ascii")
+    try:
+        key.verify(bytes.fromhex(t.signature_hex), message)
+        signature_valid = True
+    except (InvalidSignature, ValueError):
+        signature_valid = False
+
+    ok = signature_valid and (hashes_match or not strict)
+    return VerificationReport(signature_valid=signature_valid, hashes_match=hashes_match, ok=ok)
+
+
+__all__ = ["VerificationReport", "verify_transcript"]

ski_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: ski-sdk
+Version: 0.1.0
+Summary: Typed Python client for the SKI Framework SKI Model, with one-call provenance verification.
+Author: KpiFinity Inc.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/kpifinity/ski-framework
+Project-URL: Documentation, https://kpifinity.github.io/ski-framework/
+Project-URL: Issues, https://github.com/kpifinity/ski-framework/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pydantic<3,>=2.13.4
+Requires-Dist: cryptography<48,>=46
+
+# ski-sdk
+
+> Install from PyPI: `pip install ski-sdk` (publishing starts with the first release after June 2026).
+
+Typed Python client for the [SKI Framework](https://github.com/kpifinity/ski-framework)
+SKI Model, with one-call verification of a verdict's signed provenance.
+
+> **Status: early alpha.** This wraps an alpha HTTP API; pin your versions. The
+> SDK is versioned independently of the framework — see the compatibility note
+> in the docs.
+
+```python
+from ski_sdk import SKIClient
+
+client = SKIClient(endpoint="https://ski.internal:8000", api_key="…")
+env = client.evaluate(
+    measurement_id="m-001",
+    timestamp="2026-06-05T12:00:00Z",
+    subject="stack-7",
+    measurement={"so2_ppm": 150},
+)
+print(env.verdict, [c.node_id for c in env.kg_citations])  # FLAG ['energy.so2.lte_100ppm']
+```
+
+Verify a verdict's signed transcript (tamper-evident provenance):
+
+```python
+from ski_sdk import verify_transcript
+
+report = verify_transcript(transcript, public_key_pem)
+assert report.ok  # signature valid AND recorded hashes match the canonical pair
+```

ski_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ski_sdk/__init__.py,sha256=UmYrKdo5ELLyPnkq11blKR2DkXGevUeklgjOPoPaBOo,984
+ski_sdk/client.py,sha256=huuDLjDuV1sOI8bTT40R9K8qWdst293MeG7fm8k9fmA,7824
+ski_sdk/errors.py,sha256=B9nveH9_srhwPRellx9HoQQ0AW3mGUWVu5g-B3U6WOU,1235
+ski_sdk/models.py,sha256=K6_mkv8Gp8yXgbr2rbpy6bt0rVLyvkeSh6C-gGa4rc8,3891
+ski_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ski_sdk/verify.py,sha256=dERYk5-u-KgIpZdcRYYD9MYGeTIviYtwv8HxIEuORRQ,2878
+ski_sdk-0.1.0.dist-info/METADATA,sha256=Kab6MIiLjowBqZJBYnHOKuTmHJUiEK3Ahf47SdNRJ9Q,1840
+ski_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ski_sdk-0.1.0.dist-info/top_level.txt,sha256=wXpUfrUOWsOSAPCLcuQ7fo6mKx1cjurpveP9keBPfKQ,8
+ski_sdk-0.1.0.dist-info/RECORD,,

ski_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ski_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ski_sdk