ski-sdk 0.1.0__tar.gz

ski_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,32 @@
+# 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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ski-sdk"
+version = "0.1.0"
+description = "Typed Python client for the SKI Framework SKI Model, with one-call provenance verification."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "KpiFinity Inc." }]
+dependencies = [
+    "httpx>=0.27,<0.29",
+    "pydantic>=2.13.4,<3",
+    "cryptography>=46,<48",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/kpifinity/ski-framework"
+Documentation = "https://kpifinity.github.io/ski-framework/"
+Issues = "https://github.com/kpifinity/ski-framework/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ski_sdk = ["py.typed"]

ski_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ski_sdk-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/ski_sdk.egg-info/PKG-INFO

@@ -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/src/ski_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/ski_sdk/__init__.py
+src/ski_sdk/client.py
+src/ski_sdk/errors.py
+src/ski_sdk/models.py
+src/ski_sdk/py.typed
+src/ski_sdk/verify.py
+src/ski_sdk.egg-info/PKG-INFO
+src/ski_sdk.egg-info/SOURCES.txt
+src/ski_sdk.egg-info/dependency_links.txt
+src/ski_sdk.egg-info/requires.txt
+src/ski_sdk.egg-info/top_level.txt
+tests/test_sdk_client.py
+tests/test_sdk_contract_drift.py
+tests/test_sdk_verify.py

ski_sdk-0.1.0/src/ski_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ski_sdk-0.1.0/src/ski_sdk.egg-info/requires.txt

@@ -0,0 +1,3 @@
+httpx<0.29,>=0.27
+pydantic<3,>=2.13.4
+cryptography<48,>=46

ski_sdk-0.1.0/src/ski_sdk.egg-info/top_level.txt

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

ski_sdk-0.1.0/tests/test_sdk_client.py

@@ -0,0 +1,73 @@
+"""SKIClient request/response handling and error mapping.
+
+Uses httpx's built-in MockTransport (injected via the client's ``transport``
+parameter) — no pytest-httpx dependency, and version-agnostic across httpx 0.27/0.28.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from ski_sdk import SKIAuthError, SKIClient, SKIServiceUnavailable
+
+BASE = "https://ski.test:8000"
+
+_ENVELOPE = {
+    "verdict": "FLAG",
+    "reasoning": "breach",
+    "kg_citations": [],
+    "formalizable_assertions": [],
+    "verifier_result": {"status": "AGREED", "checked_assertions": 1, "divergences": []},
+    "model_provenance": {
+        "model_weight_hash": "sha256:" + "f" * 64,
+        "kg_version_hash": "sha256:" + "a" * 64,
+        "prompt_template_id": "ski.v3.evaluate.1",
+        "prompt_template_hash": "sha256:" + "1" * 64,
+        "decoder_seed": 0,
+        "structured_grammar_hash": "sha256:" + "2" * 64,
+    },
+    "transcript_ref": "transcript:abc",
+    "notes": [],
+}
+
+
+def _client(handler, **kw) -> SKIClient:
+    return SKIClient(BASE, api_key=kw.pop("api_key", "s3cret"), transport=httpx.MockTransport(handler), **kw)
+
+
+def test_evaluate_parses_envelope_and_sends_api_key() -> None:
+    seen = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return httpx.Response(200, json=_ENVELOPE)
+
+    with _client(handler) as client:
+        env = client.evaluate(
+            measurement_id="m1",
+            timestamp="2026-06-05T12:00:00Z",
+            subject="emissions",
+            measurement={"so2_ppm": 150},
+        )
+    assert env.verdict == "FLAG"
+    assert env.verifier_result.status == "AGREED"
+    assert seen[0].headers["x-api-key"] == "s3cret"
+    assert seen[0].url.path == "/api/evaluate"
+
+
+def test_401_maps_to_auth_error() -> None:
+    with (
+        _client(
+            lambda r: httpx.Response(401, json={"detail": "Invalid or missing API key."}), api_key="bad"
+        ) as client,
+        pytest.raises(SKIAuthError),
+    ):
+        client.evaluate(measurement_id="m1", timestamp="t", subject="s", measurement={})
+
+
+def test_503_maps_to_service_unavailable() -> None:
+    with (
+        _client(lambda r: httpx.Response(503, json={"detail": "No KG loaded."}), max_retries=0) as client,
+        pytest.raises(SKIServiceUnavailable),
+    ):
+        client.health()

ski_sdk-0.1.0/tests/test_sdk_contract_drift.py

@@ -0,0 +1,41 @@
+"""Contract-drift guard: SDK models must match the server's field-for-field.
+
+Skips when the reference implementation is not importable (so the SDK package
+stays independently testable); runs in the repo CI where `ski_model` is on the
+path. If the server changes a model, this test fails and the SDK must follow.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+pytest.importorskip("ski_model.v3.envelope")
+
+from ski_model.v3 import envelope as srv
+from ski_model.v3 import transcript as srv_t
+from ski_sdk import models as sdk
+
+
+def _fields(model: object) -> set:
+    return set(model.model_fields)  # type: ignore[attr-defined]
+
+
+def test_envelope_and_nested_models_match() -> None:
+    pairs = [
+        (srv.V3VerdictEnvelope, sdk.V3VerdictEnvelope),
+        (srv.KGCitation, sdk.KGCitation),
+        (srv.FormalizableAssertion, sdk.FormalizableAssertion),
+        (srv.VerifierResult, sdk.VerifierResult),
+        (srv.ModelProvenance, sdk.ModelProvenance),
+        (srv_t.LLMTranscript, sdk.LLMTranscript),
+    ]
+    for server_model, sdk_model in pairs:
+        sf, df = _fields(server_model), _fields(sdk_model)
+        assert sf == df, f"{server_model.__name__} drift: only-server={sf - df} only-sdk={df - sf}"
+
+
+def test_measurement_record_matches() -> None:
+    srv_server = pytest.importorskip("ski_model.server")
+    sf = set(srv_server.MeasurementRecord.model_fields)
+    df = set(sdk.MeasurementRecord.model_fields)
+    assert sf == df, f"MeasurementRecord drift: only-server={sf - df} only-sdk={df - sf}"

ski_sdk-0.1.0/tests/test_sdk_verify.py

@@ -0,0 +1,71 @@
+"""verify_transcript: a valid transcript verifies; a tampered one does not."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from ski_sdk import verify_transcript
+
+
+def _h(b: bytes) -> str:
+    return "sha256:" + hashlib.sha256(b).hexdigest()
+
+
+def _build_signed_transcript(key: Ed25519PrivateKey) -> dict:
+    request_canonical = "PROMPT: evaluate so2_ppm=50 against energy.so2.lte_100ppm"
+    response_canonical = {"verdict": "CLEAR", "kg_citations": [{"node_id": "energy.so2.lte_100ppm"}]}
+    req_hash = _h(request_canonical.encode("utf-8"))
+    resp_hash = _h(
+        json.dumps(response_canonical, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+            "utf-8"
+        )
+    )
+    sig = key.sign(f"{req_hash}|{resp_hash}".encode("ascii")).hex()
+    return {
+        "transcript_id": "t-1",
+        "request_canonical": request_canonical,
+        "request_hash": req_hash,
+        "response_canonical": response_canonical,
+        "response_hash": resp_hash,
+        "signature_hex": sig,
+        "signing_key_id": "sha256:" + "0" * 64,
+        "backend_name": "fake-llm",
+        "backend_metadata": {},
+        "started_at": "2026-06-05T12:00:00Z",
+        "completed_at": "2026-06-05T12:00:01Z",
+    }
+
+
+def _pem(key: Ed25519PrivateKey) -> str:
+    return (
+        key.public_key()
+        .public_bytes(
+            encoding=serialization.Encoding.PEM, format=serialization.PublicFormat.SubjectPublicKeyInfo
+        )
+        .decode("ascii")
+    )
+
+
+def test_valid_transcript_verifies() -> None:
+    key = Ed25519PrivateKey.generate()
+    report = verify_transcript(_build_signed_transcript(key), _pem(key))
+    assert report.signature_valid and report.hashes_match and report.ok and bool(report)
+
+
+def test_tampered_response_fails() -> None:
+    key = Ed25519PrivateKey.generate()
+    t = _build_signed_transcript(key)
+    t["response_canonical"]["verdict"] = "FLAG"  # tamper after signing
+    report = verify_transcript(t, _pem(key))
+    assert not report.hashes_match
+    assert not report.ok
+
+
+def test_wrong_key_fails() -> None:
+    t = _build_signed_transcript(Ed25519PrivateKey.generate())
+    report = verify_transcript(t, _pem(Ed25519PrivateKey.generate()))
+    assert not report.signature_valid
+    assert not report.ok