ski-schemas 0.1.0__tar.gz

ski_schemas-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: ski-schemas
+Version: 0.1.0
+Summary: SKI Framework wire models: verdict envelope, signed LLM transcript, measurement record. One definition, no drift (RFC 0003).
+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: pydantic<3,>=2.5
+
+# ski-schemas
+
+> Install from PyPI: `pip install ski-schemas`
+
+The [SKI Framework](https://github.com/kpifinity/ski-framework) wire
+models — the v3 verdict envelope, the signed LLM transcript, and the
+measurement record — extracted into one dependency-light package per
+RFC 0003. The server, the `ski-sdk` client, and the conformance suite
+all import these models, so the wire contract has exactly one
+definition.
+
+```python
+from ski_schemas import V3VerdictEnvelope
+
+envelope = V3VerdictEnvelope.model_validate_json(raw)
+print(envelope.verdict, envelope.model_provenance.kg_version_hash)
+```
+
+Versioned independently of the framework (it carries a wire contract,
+not a runtime). Dependencies: `pydantic` only.

ski_schemas-0.1.0/README.md

@@ -0,0 +1,20 @@
+# ski-schemas
+
+> Install from PyPI: `pip install ski-schemas`
+
+The [SKI Framework](https://github.com/kpifinity/ski-framework) wire
+models — the v3 verdict envelope, the signed LLM transcript, and the
+measurement record — extracted into one dependency-light package per
+RFC 0003. The server, the `ski-sdk` client, and the conformance suite
+all import these models, so the wire contract has exactly one
+definition.
+
+```python
+from ski_schemas import V3VerdictEnvelope
+
+envelope = V3VerdictEnvelope.model_validate_json(raw)
+print(envelope.verdict, envelope.model_provenance.kg_version_hash)
+```
+
+Versioned independently of the framework (it carries a wire contract,
+not a runtime). Dependencies: `pydantic` only.

ski_schemas-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ski-schemas"
+version = "0.1.0"
+description = "SKI Framework wire models: verdict envelope, signed LLM transcript, measurement record. One definition, no drift (RFC 0003)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [{name = "KpiFinity Inc."}]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = ["pydantic>=2.5,<3"]
+
+[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_schemas = ["py.typed"]

ski_schemas-0.1.0/setup.cfg

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

ski_schemas-0.1.0/src/ski_schemas/__init__.py

@@ -0,0 +1,37 @@
+"""ski-schemas — the SKI Framework wire models, defined once (RFC 0003 PR 1).
+
+The verdict envelope, the signed LLM transcript, and the measurement
+record are normative (spec v3.0 §4, §6). This dependency-light package
+is the single source of truth the server, the ski-sdk client, and the
+conformance suite all import — one definition, no drift.
+"""
+
+from .envelope import (
+    FormalizableAssertion,
+    KGCitation,
+    KGCitationRole,
+    ModelProvenance,
+    V3Verdict,
+    V3VerdictEnvelope,
+    VerifierResult,
+    VerifierStatus,
+)
+from .measurement import MeasurementRecord
+from .transcript import LLMTranscript, hash_pair, signing_message
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FormalizableAssertion",
+    "KGCitation",
+    "KGCitationRole",
+    "LLMTranscript",
+    "MeasurementRecord",
+    "ModelProvenance",
+    "V3Verdict",
+    "V3VerdictEnvelope",
+    "VerifierResult",
+    "VerifierStatus",
+    "hash_pair",
+    "signing_message",
+]

ski_schemas-0.1.0/src/ski_schemas/envelope.py

@@ -0,0 +1,159 @@
+"""Pydantic models for the v3 verdict envelope per spec v3.0 §4.
+
+* §4.1 — the five-verdict taxonomy (preserved from v2.1).
+* §4.2 — required + optional envelope fields.
+* §4.3 — KG citations with node_id / version / role.
+* §4.4 — formalizable assertions the symbolic verifier can check.
+* §4.5 — verifier result with status enum.
+* §4.6 — model provenance (six required hash + id fields).
+
+These models are the contract every v3 verdict honours. They MUST
+round-trip through JSON without loss; the runtime's envelope tests
+enforce this. This module is the single source of truth shared by the
+server, the SDK, and the conformance suite (RFC 0003 PR 1).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ---- Verdict taxonomy (§4.1) ----
+
+
+class V3Verdict(str, Enum):
+    """The five-verdict taxonomy, preserved from v2.1."""
+
+    CLEAR = "CLEAR"
+    FLAG = "FLAG"
+    NULL_UNMAPPED = "NULL_UNMAPPED"
+    NULL_STALE = "NULL_STALE"
+    DISCRETIONARY = "DISCRETIONARY"
+
+
+# ---- Verifier status (§4.5) ----
+
+
+class VerifierStatus(str, Enum):
+    """Status returned by the Symbolic Verifier (spec §5.3)."""
+
+    AGREED = "AGREED"
+    LLM_CONTRADICTION = "LLM_CONTRADICTION"
+    NEURO_SYMBOLIC_DIVERGENCE = "NEURO_SYMBOLIC_DIVERGENCE"
+    UNVERIFIABLE = "UNVERIFIABLE"
+
+
+# ---- KG citation (§4.3) ----
+
+
+class KGCitationRole(str, Enum):
+    """The role a cited KG node played in the verdict."""
+
+    OBLIGATION = "obligation"
+    DEFINITION_RESOLVED = "definition_resolved"
+    EXEMPTION_CONSIDERED = "exemption_considered"
+    PRECEDENT_REFERENCED = "precedent_referenced"
+    JURISDICTION_MATCHED = "jurisdiction_matched"
+
+
+class KGCitation(BaseModel):
+    """A single KG node the LLM cited as informing the verdict."""
+
+    model_config = ConfigDict(use_enum_values=True, extra="forbid")
+
+    node_id: str
+    version: str
+    role: KGCitationRole
+
+
+# ---- Formalizable assertion (§4.4) ----
+
+
+class FormalizableAssertion(BaseModel):
+    """A structured assertion the symbolic verifier can mechanically check."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    predicate: str = Field(..., description="Predicate type, e.g. 'must_not_exceed'.")
+    metric: str = Field(..., description="Dotted-path into the measurement object.")
+    value: Union[float, int, str, List[Any], None] = None
+    observed: Union[float, int, str, List[Any], None] = None
+    satisfied: bool
+    obligation_id: str = Field(..., description="The KG obligation this assertion checks.")
+    window_seconds: Optional[int] = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Time-window length in seconds for stateful predicates "
+            "(e.g. 86400 for a 24h rolling average). None for stateless "
+            "predicates."
+        ),
+    )
+
+
+# ---- Verifier result (§4.5) ----
+
+
+class VerifierResult(BaseModel):
+    """The symbolic verifier's per-assertion result."""
+
+    model_config = ConfigDict(use_enum_values=True, extra="forbid")
+
+    status: VerifierStatus
+    checked_assertions: int = Field(default=0, ge=0)
+    divergences: List[str] = Field(default_factory=list)
+
+
+# ---- Model provenance (§4.6) ----
+
+
+class ModelProvenance(BaseModel):
+    """Inference provenance metadata required for v3 replay.
+
+    All hash values MUST be lowercase hex prefixed with ``sha256:`` per
+    spec §4.6. The Pydantic layer enforces the prefix.
+    """
+
+    # model_weight_hash collides with Pydantic's reserved model_
+    # namespace; opt out explicitly. The field name is normative per
+    # spec §4.6 and cannot be renamed.
+    model_config = ConfigDict(extra="forbid", protected_namespaces=())
+
+    model_weight_hash: str = Field(..., pattern=r"^sha256:[0-9a-f]+$")
+    kg_version_hash: str = Field(..., pattern=r"^sha256:[0-9a-f]+$")
+    prompt_template_id: str = Field(..., description="Stable id, e.g. 'ski.v3.evaluate.1'.")
+    prompt_template_hash: str = Field(..., pattern=r"^sha256:[0-9a-f]+$")
+    decoder_seed: int = Field(..., ge=0)
+    structured_grammar_hash: str = Field(..., pattern=r"^sha256:[0-9a-f]+$")
+
+
+# ---- Verdict envelope (§4.2) ----
+
+
+class V3VerdictEnvelope(BaseModel):
+    """The complete v3 verdict envelope.
+
+    Every required field is enforced at the Pydantic layer. The
+    envelope MUST round-trip through JSON without loss; that property
+    is what makes the audit ledger's hash chain meaningful.
+    """
+
+    # model_provenance collides with Pydantic's reserved model_
+    # namespace; opt out explicitly. The field name is normative per
+    # spec §4.2 and cannot be renamed.
+    model_config = ConfigDict(use_enum_values=True, extra="forbid", protected_namespaces=())
+
+    verdict: V3Verdict
+    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 = Field(..., description="Pointer to the LLM transcript in the ledger.")
+
+    # Optional fields per spec §4.2 + §5.4 + §5.6.
+    human_attestation: Optional[Dict[str, Any]] = None
+    notes: List[str] = Field(default_factory=list)
+    verdict_path: Optional[str] = Field(default=None, description="Per §5.6: 'fast' or None.")

ski_schemas-0.1.0/src/ski_schemas/measurement.py

@@ -0,0 +1,37 @@
+"""Measurement record — the input shape of ``POST /api/evaluate`` (RFC 0003)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+
+class MeasurementRecord(BaseModel):
+    """Measurement input for /api/evaluate.
+
+    The v3 evaluator consumes the full measurement; the LLM scopes the KG
+    snapshot to the measurement's jurisdiction and effective date. PR 10b
+    passes the full KG as the snapshot. Jurisdiction-scoped snapshots are a
+    follow-up.
+    """
+
+    measurement_id: str = Field(..., description="Stable id for replay correlation.")
+    timestamp: str = Field(..., description="ISO-8601 UTC.")
+    subject: str = Field(..., description="Subject token (e.g. data source identifier).")
+    measurement: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Structured measurement values keyed by metric name.",
+    )
+    jurisdiction: Optional[str] = Field(
+        default=None,
+        description=(
+            "Tenant-declared jurisdiction (e.g. 'us-ca', 'eu', 'global'). When set, "
+            "the KG is scoped to obligations whose jurisdiction matches or is "
+            "universal ('global', '*'). None means 'no restriction' — all rules "
+            "effective at the measurement's timestamp are sent to the LLM."
+        ),
+    )
+
+
+__all__ = ["MeasurementRecord"]

ski_schemas-0.1.0/src/ski_schemas/transcript.py

@@ -0,0 +1,104 @@
+"""Provider-neutral LLM transcript record (spec v3.0 §6).
+
+An :class:`LLMTranscript` captures the canonical input/output pair of a
+single LLM evaluation call so the verdict can be independently replayed by
+an auditor. The transcript is **provider-neutral by design**: no
+Anthropic Messages blob, no OpenAI ChatCompletion shape, no Ollama
+response envelope leaks into the audit trail. Each backend is responsible
+for normalising its own request / response into the canonical strings the
+transcript records.
+
+Fields (spec §6.2):
+
+  * ``request_canonical`` — the prompt as actually sent to the LLM,
+    UTF-8 text. For chat-style APIs this is the formatted single string
+    the backend constructed; for raw-completion APIs it is the prompt
+    itself.
+  * ``request_hash`` — sha256 of ``request_canonical``.
+  * ``response_canonical`` — the structured-output dict matching
+    the framework's ``RESPONSE_GRAMMAR``. Vendor-specific
+    fields MUST be filtered out before canonicalisation.
+  * ``response_hash`` — sha256 of the canonical JSON serialisation of
+    ``response_canonical`` (sort_keys, compact separators).
+  * ``signature_hex`` — ed25519 signature over
+    ``request_hash || "|" || response_hash`` produced by the runtime's
+    the runtime's ``TranscriptSigner``.
+  * ``signing_key_id`` — sha256 of the public-key bytes; auditors look
+    up the corresponding public key to verify.
+  * ``backend_name`` — opaque observability tag (e.g. ``"fake-llm"``,
+    ``"ollama-v3:qwen2.5-7b"``). Not part of the audit contract.
+  * ``backend_metadata`` — opaque per-backend dict. Use freely for
+    observability; NEVER for contract.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime
+from typing import Any, Dict, Tuple
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def canonical_request(request_text: str) -> bytes:
+    """Canonical request bytes — UTF-8 encoding of the request string."""
+    return request_text.encode("utf-8")
+
+
+def canonical_response(response: Dict[str, Any]) -> bytes:
+    """Canonical response bytes — sorted-keys compact JSON, UTF-8.
+
+    Vendor-specific fields are NOT filtered here — callers MUST construct
+    ``response`` from the structured-output portion of the LLM reply only.
+    The the framework's ``RESPONSE_GRAMMAR`` is the contract.
+    """
+    return json.dumps(response, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def hash_pair(*, request_text: str, response: Dict[str, Any]) -> Tuple[str, str]:
+    """Compute ``(request_hash, response_hash)`` as sha256-prefixed hex."""
+    req_hash = "sha256:" + hashlib.sha256(canonical_request(request_text)).hexdigest()
+    resp_hash = "sha256:" + hashlib.sha256(canonical_response(response)).hexdigest()
+    return req_hash, resp_hash
+
+
+def signing_message(*, request_hash: str, response_hash: str) -> bytes:
+    """Bytes to be signed — concatenation of the two hashes with a separator."""
+    return f"{request_hash}|{response_hash}".encode("ascii")
+
+
+class LLMTranscript(BaseModel):
+    """A signed transcript of one LLM evaluation call.
+
+    Round-trips through JSON; auditors deserialise from the ledger and call
+    :func:`ski_model.v3.signing.verify_signature` to prove integrity.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    transcript_id: str = Field(..., description="Globally unique id for this transcript.")
+    request_canonical: str = Field(..., description="The prompt as actually sent.")
+    request_hash: str = Field(..., pattern=r"^sha256:[0-9a-f]+$")
+    response_canonical: Dict[str, Any] = Field(
+        ..., description="Structured output matching RESPONSE_GRAMMAR."
+    )
+    response_hash: str = Field(..., pattern=r"^sha256:[0-9a-f]+$")
+    signature_hex: str = Field(..., description="Ed25519 signature, hex-encoded.")
+    signing_key_id: str = Field(..., pattern=r"^sha256:[0-9a-f]+$")
+    backend_name: str = Field(..., description="Observability tag for the LLM backend; not contract.")
+    backend_metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Opaque backend-specific metadata. Never contract.",
+    )
+    started_at: datetime
+    completed_at: datetime
+
+
+__all__ = [
+    "LLMTranscript",
+    "canonical_request",
+    "canonical_response",
+    "hash_pair",
+    "signing_message",
+]

ski_schemas-0.1.0/src/ski_schemas.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: ski-schemas
+Version: 0.1.0
+Summary: SKI Framework wire models: verdict envelope, signed LLM transcript, measurement record. One definition, no drift (RFC 0003).
+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: pydantic<3,>=2.5
+
+# ski-schemas
+
+> Install from PyPI: `pip install ski-schemas`
+
+The [SKI Framework](https://github.com/kpifinity/ski-framework) wire
+models — the v3 verdict envelope, the signed LLM transcript, and the
+measurement record — extracted into one dependency-light package per
+RFC 0003. The server, the `ski-sdk` client, and the conformance suite
+all import these models, so the wire contract has exactly one
+definition.
+
+```python
+from ski_schemas import V3VerdictEnvelope
+
+envelope = V3VerdictEnvelope.model_validate_json(raw)
+print(envelope.verdict, envelope.model_provenance.kg_version_hash)
+```
+
+Versioned independently of the framework (it carries a wire contract,
+not a runtime). Dependencies: `pydantic` only.

ski_schemas-0.1.0/src/ski_schemas.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/ski_schemas/__init__.py
+src/ski_schemas/envelope.py
+src/ski_schemas/measurement.py
+src/ski_schemas/py.typed
+src/ski_schemas/transcript.py
+src/ski_schemas.egg-info/PKG-INFO
+src/ski_schemas.egg-info/SOURCES.txt
+src/ski_schemas.egg-info/dependency_links.txt
+src/ski_schemas.egg-info/requires.txt
+src/ski_schemas.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+pydantic<3,>=2.5

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

@@ -0,0 +1 @@
+ski_schemas