nitelos 0.1.0__py3-none-any.whl

nitelos/__init__.py

@@ -0,0 +1,124 @@
+"""Nitelos: verify the outcome, not the attempt.
+
+Importing this package has no side effects: no logging handlers, no network,
+no optional model or evaluation dependencies.
+"""
+
+__version__ = "0.1.0"
+
+from nitelos.backends import DeterministicBackend
+from nitelos.errors import (
+    AbstentionReason,
+    BackendErrorCode,
+    ConfigurationError,
+    DecisionCode,
+    EvidenceValidationError,
+    InputErrorCode,
+    Issue,
+    LimitationCode,
+    RequestValidationError,
+)
+from nitelos.evidence import (
+    ArtifactStore,
+    PreparedEvidence,
+    PreparedImage,
+    prepare_evidence,
+    validate_evidence_ref,
+)
+from nitelos.policy import TrustBinding, VerificationPolicy
+from nitelos.schemas import (
+    ActionEvidence,
+    AssertionCriterion,
+    BackendDescriptor,
+    BackendFinding,
+    Basis,
+    Channel,
+    ColorConversion,
+    CriterionEvaluation,
+    CriterionResult,
+    CriterionState,
+    Decision,
+    Diagnostics,
+    ErrorInfo,
+    Evidence,
+    EvidenceRef,
+    ExecutionStatus,
+    Grounding,
+    Measurements,
+    MediaType,
+    ObservationEvidence,
+    Operator,
+    Phase,
+    PreprocessingRecord,
+    ReportedStatus,
+    Scope,
+    Score,
+    ScoreKind,
+    ScreenshotEvidence,
+    VerificationRequest,
+    VerificationResult,
+    VisualCriterion,
+    canonical_json,
+    parse_request,
+)
+from nitelos.trace import Trace, parse_trace
+from nitelos.verifier import Verifier
+
+__all__ = [
+    "AbstentionReason",
+    "ActionEvidence",
+    "ArtifactStore",
+    "AssertionCriterion",
+    "Backend",
+    "BackendCapabilities",
+    "BackendDescriptor",
+    "BackendErrorCode",
+    "BackendFinding",
+    "Basis",
+    "Channel",
+    "ColorConversion",
+    "ConfigurationError",
+    "CriterionEvaluation",
+    "CriterionResult",
+    "CriterionState",
+    "Decision",
+    "DecisionCode",
+    "DeterministicBackend",
+    "Diagnostics",
+    "ErrorInfo",
+    "Evidence",
+    "EvidenceRef",
+    "EvidenceValidationError",
+    "ExecutionStatus",
+    "Grounding",
+    "InputErrorCode",
+    "Issue",
+    "LimitationCode",
+    "Measurements",
+    "MediaType",
+    "ObservationEvidence",
+    "Operator",
+    "Phase",
+    "PreparedEvidence",
+    "PreparedImage",
+    "PreprocessingRecord",
+    "ReportedStatus",
+    "RequestValidationError",
+    "Scope",
+    "Score",
+    "ScoreKind",
+    "ScreenshotEvidence",
+    "Trace",
+    "TrustBinding",
+    "VerificationPolicy",
+    "VerificationRequest",
+    "VerificationResult",
+    "Verifier",
+    "VisualCriterion",
+    "__version__",
+    "canonical_json",
+    "parse_request",
+    "parse_trace",
+    "prepare_evidence",
+    "validate_evidence_ref",
+]

nitelos/_json.py

@@ -0,0 +1,242 @@
+"""Bounded strict JSON parsing (private module).
+
+Parses exactly the RFC 8259 grammar (objects, arrays, strings, numbers,
+true/false/null) with these ingestion rules from document 03:
+
+- duplicate object keys are rejected and reported at the duplicated key's path;
+- NaN/Infinity tokens are syntax errors and numbers that overflow to a
+  non-finite float are rejected;
+- nesting deeper than the caller's bound is rejected (containers count one
+  level each; the root value is level 1);
+- integer literals beyond Python's conversion limit are rejected as too large.
+
+Error messages carry no input values, only a JSON-style path (``$`` root,
+``.key`` members, ``[i]`` items).
+"""
+
+from __future__ import annotations
+
+import math
+from enum import StrEnum
+
+_DIGITS = "0123456789"
+_ESCAPES = {'"': '"', "\\": "\\", "/": "/", "b": "\b", "f": "\f", "n": "\n", "r": "\r", "t": "\t"}
+_WHITESPACE = " \t\n\r"
+
+
+class JsonErrorKind(StrEnum):
+    SYNTAX = "SYNTAX"
+    DUPLICATE_KEY = "DUPLICATE_KEY"
+    NON_FINITE = "NON_FINITE"
+    TOO_DEEP = "TOO_DEEP"
+    TOO_LARGE = "TOO_LARGE"
+
+
+class JsonError(ValueError):
+    """Strict-JSON violation with a kind, a JSON-style path and a value-free message."""
+
+    def __init__(self, kind: JsonErrorKind, path: str, message: str) -> None:
+        super().__init__(f"{kind} at {path}: {message}")
+        self.kind = kind
+        self.path = path
+
+
+class _Parser:
+    def __init__(self, text: str, max_depth: int) -> None:
+        self._text = text
+        self._n = len(text)
+        self._i = 0
+        self._max_depth = max_depth
+
+    def parse_document(self) -> object:
+        value = self._value(1, "$")
+        self._skip_ws()
+        if self._i != self._n:
+            raise JsonError(JsonErrorKind.SYNTAX, "$", "unexpected trailing characters")
+        return value
+
+    def _skip_ws(self) -> None:
+        while self._i < self._n and self._text[self._i] in _WHITESPACE:
+            self._i += 1
+
+    def _value(self, depth: int, path: str) -> object:
+        if depth > self._max_depth:
+            raise JsonError(JsonErrorKind.TOO_DEEP, path, "nesting exceeds the allowed depth")
+        self._skip_ws()
+        if self._i >= self._n:
+            raise JsonError(JsonErrorKind.SYNTAX, path, "unexpected end of input")
+        ch = self._text[self._i]
+        if ch == "{":
+            return self._object(depth, path)
+        if ch == "[":
+            return self._array(depth, path)
+        if ch == '"':
+            return self._string(path)
+        if ch == "t":
+            return self._literal("true", True, path)
+        if ch == "f":
+            return self._literal("false", False, path)
+        if ch == "n":
+            return self._literal("null", None, path)
+        if ch == "-" or ch in _DIGITS:
+            return self._number(path)
+        raise JsonError(JsonErrorKind.SYNTAX, path, "unexpected character")
+
+    def _object(self, depth: int, path: str) -> dict[str, object]:
+        self._i += 1  # '{'
+        obj: dict[str, object] = {}
+        self._skip_ws()
+        if self._i < self._n and self._text[self._i] == "}":
+            self._i += 1
+            return obj
+        while True:
+            self._skip_ws()
+            if self._i >= self._n or self._text[self._i] != '"':
+                raise JsonError(JsonErrorKind.SYNTAX, path, "expected an object key")
+            key = self._string(path)
+            key_path = f"{path}.{key}"
+            if key in obj:
+                raise JsonError(JsonErrorKind.DUPLICATE_KEY, key_path, "duplicate object key")
+            self._skip_ws()
+            if self._i >= self._n or self._text[self._i] != ":":
+                raise JsonError(JsonErrorKind.SYNTAX, key_path, "expected ':' after object key")
+            self._i += 1
+            obj[key] = self._value(depth + 1, key_path)
+            self._skip_ws()
+            if self._i >= self._n:
+                raise JsonError(JsonErrorKind.SYNTAX, path, "unterminated object")
+            ch = self._text[self._i]
+            if ch == ",":
+                self._i += 1
+                continue
+            if ch == "}":
+                self._i += 1
+                return obj
+            raise JsonError(JsonErrorKind.SYNTAX, path, "expected ',' or '}' in object")
+
+    def _array(self, depth: int, path: str) -> list[object]:
+        self._i += 1  # '['
+        items: list[object] = []
+        self._skip_ws()
+        if self._i < self._n and self._text[self._i] == "]":
+            self._i += 1
+            return items
+        while True:
+            items.append(self._value(depth + 1, f"{path}[{len(items)}]"))
+            self._skip_ws()
+            if self._i >= self._n:
+                raise JsonError(JsonErrorKind.SYNTAX, path, "unterminated array")
+            ch = self._text[self._i]
+            if ch == ",":
+                self._i += 1
+                continue
+            if ch == "]":
+                self._i += 1
+                return items
+            raise JsonError(JsonErrorKind.SYNTAX, path, "expected ',' or ']' in array")
+
+    def _literal(self, word: str, value: object, path: str) -> object:
+        if self._text[self._i : self._i + len(word)] != word:
+            raise JsonError(JsonErrorKind.SYNTAX, path, "unexpected character")
+        self._i += len(word)
+        return value
+
+    def _string(self, path: str) -> str:
+        self._i += 1  # '"'
+        chunks: list[str] = []
+        while True:
+            if self._i >= self._n:
+                raise JsonError(JsonErrorKind.SYNTAX, path, "unterminated string")
+            ch = self._text[self._i]
+            if ch == '"':
+                self._i += 1
+                return "".join(chunks)
+            if ch == "\\":
+                chunks.append(self._escape(path))
+            elif ch < " ":
+                raise JsonError(JsonErrorKind.SYNTAX, path, "control character in string")
+            else:
+                chunks.append(ch)
+                self._i += 1
+
+    def _escape(self, path: str) -> str:
+        self._i += 1  # '\'
+        if self._i >= self._n:
+            raise JsonError(JsonErrorKind.SYNTAX, path, "unterminated escape")
+        esc = self._text[self._i]
+        if esc in _ESCAPES:
+            self._i += 1
+            return _ESCAPES[esc]
+        if esc != "u":
+            raise JsonError(JsonErrorKind.SYNTAX, path, "invalid escape")
+        code = self._hex4(path)
+        if 0xD800 <= code <= 0xDBFF:
+            if self._text[self._i : self._i + 2] != "\\u":
+                raise JsonError(JsonErrorKind.SYNTAX, path, "unpaired surrogate")
+            self._i += 1  # land on the 'u' of the low escape for _hex4
+            low = self._hex4(path)
+            if not 0xDC00 <= low <= 0xDFFF:
+                raise JsonError(JsonErrorKind.SYNTAX, path, "unpaired surrogate")
+            return chr(0x10000 + ((code - 0xD800) << 10) + (low - 0xDC00))
+        if 0xDC00 <= code <= 0xDFFF:
+            raise JsonError(JsonErrorKind.SYNTAX, path, "unpaired surrogate")
+        return chr(code)
+
+    def _hex4(self, path: str) -> int:
+        # self._i points at the 'u' of a \u escape
+        digits = self._text[self._i + 1 : self._i + 5]
+        if len(digits) != 4:
+            raise JsonError(JsonErrorKind.SYNTAX, path, "incomplete unicode escape")
+        try:
+            code = int(digits, 16)
+        except ValueError:
+            raise JsonError(JsonErrorKind.SYNTAX, path, "invalid unicode escape") from None
+        self._i += 5  # 'u' plus the four hex digits
+        return code
+
+    def _number(self, path: str) -> int | float:
+        start = self._i
+        if self._text[self._i] == "-":
+            self._i += 1
+        if self._i >= self._n:
+            raise JsonError(JsonErrorKind.SYNTAX, path, "invalid number")
+        ch = self._text[self._i]
+        if ch == "0":
+            self._i += 1
+        elif ch in _DIGITS:
+            while self._i < self._n and self._text[self._i] in _DIGITS:
+                self._i += 1
+        else:
+            raise JsonError(JsonErrorKind.SYNTAX, path, "invalid number")
+        is_float = False
+        if self._i < self._n and self._text[self._i] == ".":
+            is_float = True
+            self._i += 1
+            if self._i >= self._n or self._text[self._i] not in _DIGITS:
+                raise JsonError(JsonErrorKind.SYNTAX, path, "invalid number")
+            while self._i < self._n and self._text[self._i] in _DIGITS:
+                self._i += 1
+        if self._i < self._n and self._text[self._i] in "eE":
+            is_float = True
+            self._i += 1
+            if self._i < self._n and self._text[self._i] in "+-":
+                self._i += 1
+            if self._i >= self._n or self._text[self._i] not in _DIGITS:
+                raise JsonError(JsonErrorKind.SYNTAX, path, "invalid number")
+            while self._i < self._n and self._text[self._i] in _DIGITS:
+                self._i += 1
+        text = self._text[start : self._i]
+        if is_float:
+            value = float(text)
+            if not math.isfinite(value):
+                raise JsonError(JsonErrorKind.NON_FINITE, path, "number is not finite")
+            return value
+        try:
+            return int(text)
+        except ValueError:
+            raise JsonError(JsonErrorKind.TOO_LARGE, path, "integer literal is too large") from None
+
+
+def parse_json(text: str, *, max_depth: int) -> object:
+    """Parse ``text`` as strict JSON with the documented ingestion rules."""
+    return _Parser(text, max_depth).parse_document()

nitelos/backends/__init__.py

@@ -0,0 +1,33 @@
+"""Nitelos backends.
+
+The deterministic assertion evaluator is core and dependency-free; the
+optional local model adapter will live in ``nitelos.backends.smolvlm``
+(NIT-008) and is never imported from here. ``base`` defines the Backend
+protocol, capabilities and the reusable finding validator (NIT-007).
+"""
+
+from nitelos.backends.base import (
+    Backend,
+    BackendCapabilities,
+    BackendOutputError,
+    InferenceContext,
+    PreparedVisualCriterion,
+    validate_backend_finding,
+)
+from nitelos.backends.deterministic import DeterministicBackend, evaluate_assertion, evaluate_reference
+from nitelos.schemas import BackendDescriptor, BackendFinding, Score
+
+__all__ = [
+    "Backend",
+    "BackendCapabilities",
+    "BackendDescriptor",
+    "BackendFinding",
+    "BackendOutputError",
+    "DeterministicBackend",
+    "InferenceContext",
+    "PreparedVisualCriterion",
+    "Score",
+    "evaluate_assertion",
+    "evaluate_reference",
+    "validate_backend_finding",
+]

nitelos/backends/base.py

@@ -0,0 +1,203 @@
+"""Backend protocol, capabilities and output validation (NIT-007).
+
+Authority: docs/planning/04-verification-backends.md ("Protocol and capability
+negotiation", prepared interface details), 03 (finding/reference/score rules),
+07 (backend output is untrusted; a custom backend is trusted executable code).
+Custom backends are injected as instances — no registry, import strings or
+entry-point discovery.
+
+Everything a backend receives is immutable and minimal: a
+``PreparedVisualCriterion`` (criterion id, description, decoded images in
+declared reference order — no file paths) and an ``InferenceContext``
+(objective, bounded action context, cooperative deadline — no metadata
+dictionary, trust bindings, labels or credentials). Backend output is
+untrusted: :func:`validate_backend_finding` enforces the doc-03 rules before
+anything reaches a result, and violations raise :class:`BackendOutputError`
+with a stable backend code and a value-free message. The helper is public so
+custom backend authors can run the same conformance check the engine does.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from nitelos.context import ActionContextItem
+from nitelos.errors import BackendErrorCode, EvidenceValidationError
+from nitelos.evidence import PreparedImage, validate_evidence_ref
+from nitelos.schemas import (
+    BackendFinding,
+    CriterionState,
+    Grounding,
+    ScoreKind,
+    ScreenshotEvidence,
+)
+
+__all__ = [
+    "Backend",
+    "BackendCapabilities",
+    "BackendOutputError",
+    "InferenceContext",
+    "PreparedVisualCriterion",
+    "validate_backend_finding",
+]
+
+
+class BackendOutputError(Exception):
+    """Invalid backend output; carries a stable backend code and a safe message.
+
+    Raised by :func:`validate_backend_finding` (and by the verifier around
+    ``infer``). The message never contains backend output or exception text.
+    """
+
+    def __init__(self, code: BackendErrorCode, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.safe_message = message
+
+
+@dataclass(frozen=True)
+class BackendCapabilities:
+    """Truthful limits of one backend (doc 04); maxima are ints, never null.
+
+    Non-image backends declare ``max_images_per_criterion = 0``;
+    unlimited/null maxima are not representable by design.
+    """
+
+    evidence_kinds: tuple[str, ...] = ()
+    criterion_kinds: tuple[str, ...] = ()
+    supports_text: bool = False
+    supports_images: bool = False
+    supports_structured_decisions: bool = False
+    supports_probabilities: bool = False
+    supports_calibrated_probabilities: bool = False
+    supports_native_abstention: bool = False
+    supports_evidence_references: bool = False
+    local_execution: bool = False
+    supports_native_batch: bool = False
+    max_images_per_criterion: int = 0
+    max_text_tokens: int = 0
+
+
+@dataclass(frozen=True)
+class PreparedVisualCriterion:
+    """What a visual backend infers on: id, description, decoded images."""
+
+    criterion_id: str
+    description: str
+    images: tuple[PreparedImage, ...]
+
+
+@dataclass(frozen=True)
+class InferenceContext:
+    """Model context: objective, bounded actions, cooperative deadline.
+
+    ``actions`` holds NIT-009's ActionContextItem records (last-eight action
+    name/status view); until that lands the verifier passes an empty tuple.
+    ``deadline`` is an absolute monotonic timestamp or None when no deadline
+    is configured; backends check it cooperatively between steps. There is no
+    metadata dictionary, and trust bindings or labels never appear here.
+    """
+
+    objective: str
+    actions: tuple[ActionContextItem, ...] = ()
+    deadline: float | None = None
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """The visual backend protocol; registration is instance injection."""
+
+    @property
+    def descriptor(self) -> Any: ...
+
+    @property
+    def capabilities(self) -> BackendCapabilities: ...
+
+    def infer(self, prepared: PreparedVisualCriterion, context: InferenceContext) -> BackendFinding:
+        """Return one finding for the prepared criterion (synchronous)."""
+
+    def close(self) -> None:
+        """Release resources; idempotent."""
+
+
+def validate_backend_finding(
+    finding: Any,
+    *,
+    criterion_id: str,
+    images: Mapping[str, PreparedImage],
+    already_emitted: frozenset[str] = frozenset(),
+) -> BackendFinding:
+    """Validate one backend finding against doc 03; returns it when valid.
+
+    ``images`` are the prepared images actually supplied to that inference,
+    keyed by evidence id — box bounds are checked against their real decoded
+    dimensions. Raises :class:`BackendOutputError` with INVALID_OUTPUT for a
+    missing/malformed finding, a foreign or duplicate criterion id or an
+    illegal state; INVALID_EVIDENCE_REFERENCE for invented references,
+    references outside the supplied images, decisive findings without at
+    least one supplied-image reference, pointers on screenshots,
+    out-of-bounds boxes and self-asserted ``assertion_checked`` grounding;
+    and UNSUPPORTED_CALIBRATION for a ``calibrated_probability`` score (a
+    capability flag alone cannot authorize it in v0.1).
+    """
+    if not isinstance(finding, BackendFinding):
+        raise BackendOutputError(BackendErrorCode.INVALID_OUTPUT, "backend returned no valid finding")
+    if finding.criterion_id != criterion_id or criterion_id in already_emitted:
+        raise BackendOutputError(BackendErrorCode.INVALID_OUTPUT, "finding cites a foreign criterion id")
+    if not isinstance(finding.state, CriterionState):
+        raise BackendOutputError(BackendErrorCode.INVALID_OUTPUT, "finding state is not a legal state")
+    if finding.score is not None and finding.score.kind == ScoreKind.CALIBRATED_PROBABILITY:
+        raise BackendOutputError(
+            BackendErrorCode.UNSUPPORTED_CALIBRATION, "calibrated probabilities are not supported in v0.1"
+        )
+    decisive = finding.state in (CriterionState.SUPPORTED, CriterionState.REFUTED)
+    if decisive and not finding.evidence_refs:
+        raise BackendOutputError(
+            BackendErrorCode.INVALID_EVIDENCE_REFERENCE,
+            "a decisive finding must reference at least one supplied image",
+        )
+    for reference in finding.evidence_refs:
+        if reference.evidence_id not in images:
+            raise BackendOutputError(
+                BackendErrorCode.INVALID_EVIDENCE_REFERENCE, "finding references unprepared evidence"
+            )
+        if reference.grounding == Grounding.ASSERTION_CHECKED:
+            raise BackendOutputError(
+                BackendErrorCode.INVALID_EVIDENCE_REFERENCE,
+                "backends cannot self-assert assertion_checked grounding",
+            )
+        try:
+            validate_evidence_ref(
+                reference,
+                {evidence_id: _as_screenshot(evidence_id) for evidence_id in images},
+                images,
+            )
+        except EvidenceValidationError:
+            raise BackendOutputError(
+                BackendErrorCode.INVALID_EVIDENCE_REFERENCE,
+                "finding reference violates pointer/box kind or bounds rules",
+            ) from None
+    return finding
+
+
+def _as_screenshot(evidence_id: str) -> ScreenshotEvidence:
+    """Minimal valid screenshot model for the shared EvidenceRef kind rules."""
+    return ScreenshotEvidence.model_validate(
+        {
+            "id": evidence_id,
+            "kind": "screenshot",
+            "sequence": 0,
+            "captured_at": "2024-06-01T10:00:00Z",
+            "checkpoint_id": "cp",
+            "source_id": "backend-validation",
+            "subject": {"form": "validation"},
+            "phase": "final",
+            "sha256": "0" * 64,
+            "artifact_id": f"art-{evidence_id}",
+            "media_type": "image/png",
+            "width": 4,
+            "height": 4,
+        }
+    )