sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/assessment_contracts.py

@@ -0,0 +1,378 @@
+"""Domain-neutral read views for cases, evidence, and assessments.
+
+These views do not replace native capture, grading, or comparison records. A
+schema name identifies a payload contract; the domain backend must validate that
+contract before it creates a view. JSON validation here checks the envelope only.
+
+An evaluator context belongs inside the trusted grader. Its private builder is
+called after the backend verifies native records and reference access. Python
+objects, private functions, and hashes do not establish authentication or process
+isolation. Local records retain ``local_unverified`` authority.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import InitVar, dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, Mapping, Sequence
+
+if TYPE_CHECKING:
+    from .workflow_contracts import PayloadSchema
+
+
+ASSESSMENT_VIEW_SCHEMA = "sphynx.assessment-view.v1"
+STRUCTURED_ASSESSMENT_VIEW_SCHEMA = "sphynx.assessment-view.v2"
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z")
+_CONTEXT_TOKEN = object()
+_STRUCTURED_ASSESSMENT_TOKEN = object()
+_CUSTOM_KIND = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/@+\-]*\Z")
+_ASSESSMENT_AVAILABILITY = frozenset({
+    "available", "missing", "unavailable", "undefined", "error", "ineligible",
+    "pending", "invalid", "redacted", "truncated",
+})
+_EVIDENCE_AVAILABILITY = frozenset({
+    "available", "missing", "unavailable", "invalid", "redacted", "truncated",
+})
+
+
+class AssessmentContractError(ValueError):
+    """A shared view is malformed or has inconsistent availability."""
+
+
+def _text(value: Any, name: str) -> str:
+    if type(value) is not str or not value.strip() or "\x00" in value:
+        raise AssessmentContractError(f"{name} must be nonempty text without NUL bytes")
+    try:
+        value.encode("utf-8", errors="strict")
+    except UnicodeEncodeError:
+        raise AssessmentContractError(f"{name} must contain valid Unicode") from None
+    return value
+
+
+def _optional_text(value: Any, name: str) -> None:
+    if value is not None:
+        _text(value, name)
+
+
+def _freeze_json(value: Any, name: str, depth: int = 0) -> Any:
+    if depth > 32:
+        raise AssessmentContractError(f"{name} exceeds the JSON nesting limit")
+    if value is None or type(value) is bool or type(value) is int:
+        return value
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise AssessmentContractError(f"{name} must contain finite numbers")
+        return value
+    if type(value) is str:
+        # JSON strings may be empty; NUL is legal within a JSON payload.
+        try:
+            value.encode("utf-8", errors="strict")
+        except UnicodeEncodeError:
+            raise AssessmentContractError(f"{name} must contain valid Unicode") from None
+        return value
+    if isinstance(value, Mapping):
+        if any(type(key) is not str for key in value):
+            raise AssessmentContractError(f"{name} must use string object keys")
+        for key in value:
+            _freeze_json(key, name, depth + 1)
+        return MappingProxyType({
+            key: _freeze_json(child, name, depth + 1) for key, child in value.items()
+        })
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze_json(child, name, depth + 1) for child in value)
+    raise AssessmentContractError(f"{name} must contain only JSON values")
+
+
+def _mapping(value: Any, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise AssessmentContractError(f"{name} must be a JSON object")
+    return _freeze_json(value, name)
+
+
+def _thaw(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: _thaw(child) for key, child in value.items()}
+    if isinstance(value, tuple):
+        return [_thaw(child) for child in value]
+    return value
+
+
+def _texts(values: Sequence[str], name: str) -> tuple[str, ...]:
+    if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
+        raise AssessmentContractError(f"{name} must be a sequence of text values")
+    result = tuple(_text(value, name) for value in values)
+    if len(set(result)) != len(result):
+        raise AssessmentContractError(f"{name} must not contain duplicates")
+    return result
+
+
+@dataclass(frozen=True)
+class CaseView:
+    """Candidate-permitted case inputs, without grading references.
+
+    The backend allowlists the fields copied into ``inputs`` and ``metadata``.
+    The plain constructor validates the JSON envelope only. Use ``validated``
+    with a registered PayloadSchema to validate domain content. Neither path can
+    infer whether arbitrary caller-supplied data is protected. Grouping, split,
+    session, and scenario identities can use domain metadata.
+    """
+
+    case_id: str
+    schema_version: str
+    inputs: Mapping[str, Any]
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        _text(self.case_id, "case_id")
+        _text(self.schema_version, "schema_version")
+        object.__setattr__(self, "inputs", _mapping(self.inputs, "inputs"))
+        object.__setattr__(self, "metadata", _mapping(self.metadata, "metadata"))
+
+    @classmethod
+    def validated(cls, case_id: str, inputs: Mapping[str, Any], *,
+                  schema: PayloadSchema, metadata: Mapping[str, Any] | None = None) -> CaseView:
+        """Validate domain inputs and retain their exact schema identity.
+
+        Import the schema contract only at this explicit operation, after module
+        initialization. Native adapters that already validate their own typed
+        payloads can continue using the compatible envelope constructor.
+        """
+        from .workflow_contracts import PayloadSchema
+
+        if not isinstance(schema, PayloadSchema):
+            raise AssessmentContractError("validated cases require a PayloadSchema")
+        validated = schema.validate(inputs)
+        return cls(case_id=case_id, schema_version=schema.schema_id, inputs=validated,
+                   metadata=metadata if metadata is not None else {})
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"case_id": self.case_id, "schema_version": self.schema_version,
+                "inputs": _thaw(self.inputs), "metadata": _thaw(self.metadata)}
+
+
+@dataclass(frozen=True)
+class EvidenceView:
+    """A typed reference to native evidence, without loading its bytes.
+
+    ``source`` names the observer, not a trust decision. ``visibility`` retains
+    the backend's native access label; this read view does not grant access.
+    Metadata can bind episode order, state lineage, reviewers, measurement
+    boundaries, and environment identities under the named domain schema.
+    """
+
+    evidence_id: str
+    sha256: str | None
+    media_type: str
+    role: str
+    source: str
+    visibility: str
+    schema_version: str | None = None
+    case_id: str | None = None
+    step_id: str | None = None
+    availability: str = "available"
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name in ("evidence_id", "media_type", "role", "source", "visibility"):
+            _text(getattr(self, name), name)
+        for name in ("schema_version", "case_id", "step_id"):
+            _optional_text(getattr(self, name), name)
+        if type(self.availability) is not str or self.availability not in _EVIDENCE_AVAILABILITY:
+            raise AssessmentContractError("unsupported evidence availability")
+        if self.sha256 is not None and (type(self.sha256) is not str or not _DIGEST.fullmatch(self.sha256)):
+            raise AssessmentContractError("sha256 must use sha256: lowercase hex")
+        if self.availability == "available" and self.sha256 is None:
+            raise AssessmentContractError("available evidence requires its native byte digest")
+        object.__setattr__(self, "metadata", _mapping(self.metadata, "metadata"))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"evidence_id": self.evidence_id, "sha256": self.sha256,
+                "media_type": self.media_type, "role": self.role, "source": self.source,
+                "visibility": self.visibility, "schema_version": self.schema_version,
+                "case_id": self.case_id, "step_id": self.step_id,
+                "availability": self.availability, "metadata": _thaw(self.metadata)}
+
+
+@dataclass(frozen=True)
+class Assessment:
+    """One evaluator's assessment of a criterion against retained evidence.
+
+    Available scores can have any finite scale. Missing evidence is never a
+    measured zero. Native run/grading IDs identify the authoritative records;
+    this view does not create a new capture or saved grading identity. Use
+    ``structured`` for a schema-validated bespoke JSON payload. Its schema
+    identity remains explicit; reporting must use an explicitly selected
+    projection instead of coercing the payload to a number or string.
+    """
+
+    criterion_id: str
+    evaluator_id: str
+    case_id: str
+    kind: str
+    availability: str
+    value: Any = None
+    reason: str | None = None
+    evidence_ids: tuple[str, ...] = ()
+    run_id: str | None = None
+    grading_id: str | None = None
+    trial: int = 1
+    attempt: int = 1
+    payload_schema: Mapping[str, Any] | None = None
+    _schema_token: InitVar[object] = None
+
+    def __post_init__(self, _schema_token: object) -> None:
+        for name in ("criterion_id", "evaluator_id", "case_id"):
+            _text(getattr(self, name), name)
+        for name in ("reason", "run_id", "grading_id"):
+            _optional_text(getattr(self, name), name)
+        for name in ("trial", "attempt"):
+            if type(getattr(self, name)) is not int or getattr(self, name) < 1:
+                raise AssessmentContractError(f"{name} must be a positive integer")
+        if type(self.kind) is not str:
+            raise AssessmentContractError("assessment kind must be text")
+        builtin = self.kind in {"assertion", "score", "label"}
+        if not builtin:
+            if _schema_token is not _STRUCTURED_ASSESSMENT_TOKEN or self.payload_schema is None:
+                raise AssessmentContractError("custom assessment kinds require a validated payload schema")
+            if self.kind != "structured" and (not _CUSTOM_KIND.fullmatch(self.kind)
+                                               or ("." not in self.kind and ":" not in self.kind)):
+                raise AssessmentContractError("custom assessment kind must be structured or namespaced")
+            schema = _mapping(self.payload_schema, "payload_schema")
+            if set(schema) != {"schema_id", "version", "implementation_id"}:
+                raise AssessmentContractError("payload schema requires its exact identity and implementation")
+            for name in ("schema_id", "version", "implementation_id"):
+                _text(schema[name], "payload_schema." + name)
+            object.__setattr__(self, "payload_schema", schema)
+        elif self.payload_schema is not None or _schema_token is not None:
+            raise AssessmentContractError("builtin assessments do not accept a custom payload schema")
+        if type(self.availability) is not str or self.availability not in _ASSESSMENT_AVAILABILITY:
+            raise AssessmentContractError("unsupported assessment availability")
+        if self.availability != "available":
+            if self.value is not None or self.reason is None:
+                raise AssessmentContractError("an unavailable assessment requires a reason and no value")
+        elif self.kind == "assertion" and type(self.value) is not bool:
+            raise AssessmentContractError("an available assertion requires a boolean")
+        elif self.kind == "score":
+            if type(self.value) not in (int, float):
+                raise AssessmentContractError("an available score requires a finite number")
+            try:
+                finite = math.isfinite(self.value)
+            except OverflowError:
+                finite = False
+            if not finite:
+                raise AssessmentContractError("an available score requires a finite number")
+        elif self.kind == "label":
+            _text(self.value, "label value")
+        if not builtin:
+            object.__setattr__(self, "value", _freeze_json(self.value, "assessment payload"))
+        object.__setattr__(self, "evidence_ids", _texts(self.evidence_ids, "evidence_ids"))
+
+    @classmethod
+    def structured(cls, criterion_id: str, evaluator_id: str, case_id: str, value: Any, *,
+                   schema: PayloadSchema, kind: str = "structured", availability: str = "available",
+                   reason: str | None = None, evidence_ids: tuple[str, ...] = (),
+                   run_id: str | None = None, grading_id: str | None = None,
+                   trial: int = 1, attempt: int = 1) -> Assessment:
+        """Create a custom assessment after explicit domain-payload validation.
+
+        Missing or pending values retain the schema declaration but have no
+        payload to validate. Their reason remains required. The factory marker
+        records this construction path; it is not evidence authentication.
+        Projection callbacks remain backend/registry-owned and are not executed
+        by construction or serialization.
+        """
+        from .workflow_contracts import PayloadSchema
+
+        if not isinstance(schema, PayloadSchema):
+            raise AssessmentContractError("structured assessments require a PayloadSchema")
+        validated = schema.validate(value) if availability == "available" else value
+        return cls(
+            criterion_id=criterion_id, evaluator_id=evaluator_id, case_id=case_id,
+            kind=kind, availability=availability, value=validated, reason=reason,
+            evidence_ids=evidence_ids, run_id=run_id, grading_id=grading_id,
+            trial=trial, attempt=attempt,
+            payload_schema={"schema_id": schema.schema_id, "version": schema.version,
+                            "implementation_id": schema.implementation_id},
+            _schema_token=_STRUCTURED_ASSESSMENT_TOKEN,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        data = {"schema_version": ASSESSMENT_VIEW_SCHEMA,
+                "criterion_id": self.criterion_id, "evaluator_id": self.evaluator_id,
+                "case_id": self.case_id, "kind": self.kind,
+                "availability": self.availability, "value": _thaw(self.value), "reason": self.reason,
+                "evidence_ids": list(self.evidence_ids), "run_id": self.run_id,
+                "grading_id": self.grading_id, "trial": self.trial, "attempt": self.attempt}
+        if self.payload_schema is not None:
+            data["schema_version"] = STRUCTURED_ASSESSMENT_VIEW_SCHEMA
+            data["payload_schema"] = _thaw(self.payload_schema)
+        return data
+
+
+@dataclass(frozen=True, init=False)
+class EvaluatorContext:
+    """Grader-owned access to verified data and permitted references.
+
+    Do not pass this object to a candidate or include it in a public report.
+    ``candidate_case`` returns only the backend's candidate-permitted projection.
+    No general serializer is provided because references can be protected.
+    """
+
+    case: CaseView
+    outputs: Mapping[str, Any] = field(repr=False)
+    references: Mapping[str, Any] = field(repr=False)
+    evidence: tuple[EvidenceView, ...] = field(repr=False)
+    run_id: str
+    grading_id: str | None
+    trust_tier: str
+    verified_by: str
+    metadata: Mapping[str, Any] = field(repr=False)
+
+    def __init__(self, *, case: CaseView, outputs: Mapping[str, Any],
+                 references: Mapping[str, Any], evidence: Sequence[EvidenceView] = (),
+                 run_id: str, grading_id: str | None = None, trust_tier: str,
+                 verified_by: str, metadata: Mapping[str, Any] | None = None,
+                 _token: object = None) -> None:
+        if _token is not _CONTEXT_TOKEN:
+            raise AssessmentContractError("evaluator contexts must be built inside a verified backend")
+        if not isinstance(case, CaseView):
+            raise AssessmentContractError("case must be CaseView")
+        if isinstance(evidence, (str, bytes)) or not isinstance(evidence, Sequence):
+            raise AssessmentContractError("evidence must be a sequence of EvidenceView values")
+        evidence = tuple(evidence)
+        if any(not isinstance(item, EvidenceView) for item in evidence):
+            raise AssessmentContractError("evidence must contain EvidenceView values")
+        if len({item.evidence_id for item in evidence}) != len(evidence):
+            raise AssessmentContractError("evidence identities must be unique within a context")
+        if any(item.case_id is not None and item.case_id != case.case_id for item in evidence):
+            raise AssessmentContractError("evidence case binding differs from the context")
+        for name, value in (("run_id", run_id), ("trust_tier", trust_tier), ("verified_by", verified_by)):
+            _text(value, name)
+        _optional_text(grading_id, "grading_id")
+        values = {"case": case, "outputs": _mapping(outputs, "outputs"),
+                  "references": _mapping(references, "references"), "evidence": evidence,
+                  "run_id": run_id, "grading_id": grading_id, "trust_tier": trust_tier,
+                  "verified_by": verified_by,
+                  "metadata": _mapping(metadata if metadata is not None else {}, "metadata")}
+        for name, value in values.items():
+            object.__setattr__(self, name, value)
+
+    def candidate_case(self) -> CaseView:
+        return self.case
+
+
+def _verified_evaluator_context(*, case: CaseView, outputs: Mapping[str, Any],
+                                references: Mapping[str, Any], evidence: Sequence[EvidenceView] = (),
+                                run_id: str, grading_id: str | None = None,
+                                trust_tier: str, verified_by: str,
+                                metadata: Mapping[str, Any] | None = None) -> EvaluatorContext:
+    """Build after native verification and reference authorization, inside grading.
+
+    The caller owns those checks. This helper does not read storage, verify
+    hashes, authenticate a principal, or upgrade the native evidence's trust.
+    """
+    return EvaluatorContext(case=case, outputs=outputs, references=references,
+                            evidence=evidence, run_id=run_id, grading_id=grading_id,
+                            trust_tier=trust_tier, verified_by=verified_by,
+                            metadata=metadata, _token=_CONTEXT_TOKEN)

sphynx/assessment_selection.py

@@ -0,0 +1,57 @@
+"""Lazy exact-match selection of assessments already permitted by a backend."""
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+
+from .assessment_contracts import Assessment, _ASSESSMENT_AVAILABILITY
+from .workflow_contracts import WorkflowContractError, _text
+
+
+@dataclass(frozen=True)
+class AssessmentSelector:
+    """Optional envelope filters combined with AND.
+
+    Selection does not interpret values, execute projections, group trials, or
+    grant access. Custom schema-bound kinds retain their original payloads.
+    """
+
+    case_id: str | None = None
+    criterion_id: str | None = None
+    evaluator_id: str | None = None
+    kind: str | None = None
+    availability: str | None = None
+    trial: int | None = None
+    attempt: int | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("case_id", "criterion_id", "evaluator_id", "kind", "availability"):
+            value = getattr(self, name)
+            if value is not None:
+                _text(value, name)
+        if self.availability is not None and self.availability not in _ASSESSMENT_AVAILABILITY:
+            raise WorkflowContractError("unsupported assessment availability")
+        for name in ("trial", "attempt"):
+            value = getattr(self, name)
+            if value is not None and (type(value) is not int or value < 1):
+                raise WorkflowContractError(name + " must be a positive integer")
+
+    def matches(self, assessment: Assessment) -> bool:
+        if not isinstance(assessment, Assessment):
+            raise WorkflowContractError("assessment selection requires Assessment values")
+        return all(
+            getattr(self, name) is None or getattr(assessment, name) == getattr(self, name)
+            for name in ("case_id", "criterion_id", "evaluator_id", "kind", "availability", "trial", "attempt")
+        )
+
+    def select(self, assessments: Iterable[Assessment]) -> Iterator[Assessment]:
+        """Yield matching original views without materializing the input."""
+        for assessment in assessments:
+            if self.matches(assessment):
+                yield assessment
+
+    def to_dict(self) -> dict:
+        return {"schema_version": "sphynx.assessment-selector.v1", **{
+            name: getattr(self, name)
+            for name in ("case_id", "criterion_id", "evaluator_id", "kind", "availability", "trial", "attempt")
+        }}