agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/artifacts/store.py

@@ -0,0 +1,157 @@
+"""Checksum-verified local artifact store with atomic writes."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from agentinputlab.contracts.errors import ArtifactError
+
+from .manifest import ArtifactManifest
+
+
+def sha256_file(path: str | Path, *, chunk_size: int = 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        while chunk := handle.read(chunk_size):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+@dataclass(slots=True)
+class ArtifactStore:
+    root: Path
+
+    def __init__(self, root: str | Path) -> None:
+        self.root = Path(root).expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def path_for(self, manifest: ArtifactManifest) -> Path:
+        candidate = (self.root / manifest.artifact_id / manifest.revision / "payload").resolve()
+        if self.root not in candidate.parents:
+            raise ArtifactError("artifact path escaped store root")
+        return candidate
+
+    def verify(self, manifest: ArtifactManifest) -> Path:
+        path = self.path_for(manifest)
+        if not path.is_file():
+            raise ArtifactError(f"artifact missing: {manifest.artifact_id}@{manifest.revision}")
+        if manifest.size_bytes is not None and path.stat().st_size != manifest.size_bytes:
+            raise ArtifactError(f"artifact size mismatch: {manifest.artifact_id}")
+        if manifest.sha256 and sha256_file(path) != manifest.sha256:
+            raise ArtifactError(f"artifact checksum mismatch: {manifest.artifact_id}")
+        return path
+
+    def put_bytes(self, manifest: ArtifactManifest, content: bytes) -> Path:
+        digest = hashlib.sha256(content).hexdigest()
+        if manifest.sha256 and digest != manifest.sha256:
+            raise ArtifactError(
+                f"refusing materialization: checksum mismatch for {manifest.artifact_id}"
+            )
+        if manifest.size_bytes is not None and len(content) != manifest.size_bytes:
+            raise ArtifactError(
+                f"refusing materialization: size mismatch for {manifest.artifact_id}"
+            )
+        destination = self.path_for(manifest)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        if destination.exists():
+            if destination.is_file() and destination.read_bytes() == content:
+                return self.verify(manifest)
+            raise ArtifactError(
+                "refusing to overwrite an existing artifact revision with different content: "
+                f"{manifest.artifact_id}@{manifest.revision}"
+            )
+        descriptor, temporary_name = tempfile.mkstemp(
+            prefix=".partial-",
+            dir=destination.parent,
+        )
+        try:
+            with os.fdopen(descriptor, "wb") as handle:
+                handle.write(content)
+                handle.flush()
+                os.fsync(handle.fileno())
+            try:
+                # Linking a fully flushed temporary file is atomic and, unlike
+                # os.replace(), cannot overwrite a concurrently materialized
+                # artifact revision.
+                os.link(temporary_name, destination)
+            except FileExistsError:
+                if not destination.is_file() or destination.read_bytes() != content:
+                    raise ArtifactError(
+                        "refusing concurrent overwrite of artifact revision: "
+                        f"{manifest.artifact_id}@{manifest.revision}"
+                    ) from None
+        finally:
+            if os.path.exists(temporary_name):
+                os.unlink(temporary_name)
+        return self.verify(manifest)
+
+    def import_file(self, manifest: ArtifactManifest, source: str | Path) -> Path:
+        source_path = Path(source).resolve()
+        if not source_path.is_file():
+            raise ArtifactError(f"source artifact is not a regular file: {source_path}")
+        with source_path.open("rb") as handle:
+            return self.put_stream(manifest, iter(lambda: handle.read(1024 * 1024), b""))
+
+    def put_stream(
+        self,
+        manifest: ArtifactManifest,
+        chunks: Iterable[bytes],
+        *,
+        max_bytes: int | None = None,
+    ) -> Path:
+        """Hash bounded chunks to a temporary file and publish create-only.
+
+        A network interruption, size violation, or bad checksum never leaves a
+        usable payload. Concurrent downloads cannot replace an existing revision.
+        Neither the incoming payload nor an existing payload is buffered in RAM.
+        """
+        if max_bytes is not None and max_bytes < 0:
+            raise ArtifactError("stream size limit must be non-negative")
+        destination = self.path_for(manifest)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary_name = tempfile.mkstemp(prefix=".partial-", dir=destination.parent)
+        digest = hashlib.sha256()
+        size = 0
+        try:
+            with os.fdopen(descriptor, "wb") as handle:
+                for chunk in chunks:
+                    if not isinstance(chunk, bytes):
+                        raise ArtifactError("artifact stream must yield bytes")
+                    size += len(chunk)
+                    if (max_bytes is not None and size > max_bytes) or (
+                        manifest.size_bytes is not None and size > manifest.size_bytes
+                    ):
+                        raise ArtifactError("artifact stream exceeds size limit")
+                    digest.update(chunk)
+                    handle.write(chunk)
+                if manifest.size_bytes is not None and size != manifest.size_bytes:
+                    raise ArtifactError(
+                        f"refusing materialization: size mismatch for {manifest.artifact_id}"
+                    )
+                if manifest.sha256 and digest.hexdigest() != manifest.sha256:
+                    raise ArtifactError(
+                        f"refusing materialization: checksum mismatch for {manifest.artifact_id}"
+                    )
+                handle.flush()
+                os.fsync(handle.fileno())
+            try:
+                os.link(temporary_name, destination)
+            except FileExistsError:
+                if (
+                    not destination.is_file()
+                    or destination.stat().st_size != size
+                    or sha256_file(destination) != digest.hexdigest()
+                ):
+                    raise ArtifactError(
+                        "refusing concurrent overwrite of artifact revision: "
+                        f"{manifest.artifact_id}@{manifest.revision}"
+                    ) from None
+        finally:
+            if os.path.exists(temporary_name):
+                os.unlink(temporary_name)
+        return destination

agentinputlab/backends/__init__.py

@@ -0,0 +1,98 @@
+"""Backend contracts for LLMs, retrieval, embedding, and user simulators."""
+
+from .embedding import (
+    CallableEmbeddingBackend,
+    DeterministicHashEmbeddingBackend,
+    EmbeddingBackend,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    EmbeddingUsage,
+    ReplayEmbeddingBackend,
+)
+from .llm import (
+    FINAL_CONTENT_STOP_POLICY_ID,
+    CallableBackend,
+    DecompCompletionBackend,
+    FinalContentStopBackend,
+    GenerationRequest,
+    GenerationResponse,
+    LLMBackend,
+    ModelCapability,
+    OpenAICompatibleBackend,
+    ReplayBackend,
+    TransformersBackend,
+    Usage,
+    require_capabilities,
+)
+from .retrieval import (
+    DENSE_RETRIEVER_PROFILE_IDS,
+    RETRIEVER_PROFILES,
+    BatchTextEncoder,
+    DenseIndexSummary,
+    Document,
+    EmbeddingBackendEncoder,
+    FunctionRetriever,
+    InMemoryBM25Retriever,
+    RetrievalResult,
+    Retriever,
+    RetrieverProfile,
+    SentenceTransformerDenseRetriever,
+    SQLiteFTS5Retriever,
+    build_retriever,
+    retriever_profile,
+)
+from .user import (
+    CallableUserResponder,
+    ReplayTurn,
+    ReplayUserResponder,
+    UserRequest,
+    UserResponder,
+    UserResponse,
+)
+from .vector import DenseEmbedder, VectorSearcher
+
+__all__ = [
+    "DENSE_RETRIEVER_PROFILE_IDS",
+    "FINAL_CONTENT_STOP_POLICY_ID",
+    "RETRIEVER_PROFILES",
+    "BatchTextEncoder",
+    "CallableBackend",
+    "CallableEmbeddingBackend",
+    "CallableUserResponder",
+    "DecompCompletionBackend",
+    "DenseEmbedder",
+    "DenseIndexSummary",
+    "DeterministicHashEmbeddingBackend",
+    "Document",
+    "EmbeddingBackend",
+    "EmbeddingBackendEncoder",
+    "EmbeddingRequest",
+    "EmbeddingResponse",
+    "EmbeddingUsage",
+    "FinalContentStopBackend",
+    "FunctionRetriever",
+    "GenerationRequest",
+    "GenerationResponse",
+    "InMemoryBM25Retriever",
+    "LLMBackend",
+    "ModelCapability",
+    "OpenAICompatibleBackend",
+    "ReplayBackend",
+    "ReplayEmbeddingBackend",
+    "ReplayTurn",
+    "ReplayUserResponder",
+    "RetrievalResult",
+    "Retriever",
+    "RetrieverProfile",
+    "SQLiteFTS5Retriever",
+    "SentenceTransformerDenseRetriever",
+    "TransformersBackend",
+    "Usage",
+    "UserRequest",
+    "UserResponder",
+    "UserResponse",
+    "VectorSearcher",
+    "build_retriever",
+    "require_capabilities",
+    "retriever_profile",
+]

agentinputlab/backends/embedding/__init__.py

@@ -0,0 +1,25 @@
+"""Standard embedding seams and dependency-free fixture implementations."""
+
+from .base import (
+    EmbeddingBackend,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    EmbeddingUsage,
+    normalize_vector,
+    validate_embedding_response,
+)
+from .callable import CallableEmbeddingBackend, EmbeddingClient
+from .replay import DeterministicHashEmbeddingBackend, ReplayEmbeddingBackend
+
+__all__ = [
+    "CallableEmbeddingBackend",
+    "DeterministicHashEmbeddingBackend",
+    "EmbeddingBackend",
+    "EmbeddingClient",
+    "EmbeddingRequest",
+    "EmbeddingResponse",
+    "EmbeddingUsage",
+    "ReplayEmbeddingBackend",
+    "normalize_vector",
+    "validate_embedding_response",
+]

agentinputlab/backends/embedding/base.py

@@ -0,0 +1,145 @@
+"""Backend-neutral embedding request, response, and validation contracts."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from agentinputlab.contracts.errors import ValidationError
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping
+
+
+def _is_finite_nonnegative_number(value: Any) -> bool:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return False
+    try:
+        return math.isfinite(value) and value >= 0
+    except (OverflowError, TypeError, ValueError):
+        return False
+
+
+@dataclass(frozen=True, slots=True)
+class EmbeddingRequest:
+    texts: tuple[str, ...]
+    normalize: bool = False
+    dimensions: int | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "texts", tuple(self.texts))
+        object.__setattr__(self, "metadata", freeze_mapping(self.metadata))
+        if not all(isinstance(text, str) for text in self.texts):
+            raise ValidationError("embedding request texts must all be strings")
+        if self.dimensions is not None and self.dimensions < 1:
+            raise ValidationError("embedding request dimensions must be positive")
+
+    @property
+    def request_hash(self) -> str:
+        return content_hash(self)
+
+
+@dataclass(frozen=True, slots=True)
+class EmbeddingUsage:
+    input_count: int = 0
+    input_tokens: int | None = None
+    cost_usd: float | None = None
+
+    def __post_init__(self) -> None:
+        if isinstance(self.input_count, bool) or not isinstance(self.input_count, int):
+            raise ValidationError("embedding usage input_count must be a non-negative integer")
+        if self.input_count < 0:
+            raise ValidationError("embedding usage input_count must be a non-negative integer")
+        if self.input_tokens is not None and (
+            isinstance(self.input_tokens, bool)
+            or not isinstance(self.input_tokens, int)
+            or self.input_tokens < 0
+        ):
+            raise ValidationError(
+                "embedding usage input_tokens must be a non-negative integer or None"
+            )
+        if self.cost_usd is not None and not _is_finite_nonnegative_number(self.cost_usd):
+            raise ValidationError(
+                "embedding usage cost_usd must be finite and non-negative or None"
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class EmbeddingResponse:
+    vectors: tuple[tuple[float, ...], ...]
+    model: str = ""
+    usage: EmbeddingUsage = field(default_factory=EmbeddingUsage)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        vectors = tuple(tuple(float(value) for value in vector) for vector in self.vectors)
+        object.__setattr__(self, "vectors", vectors)
+        object.__setattr__(self, "metadata", freeze_mapping(self.metadata))
+        dimensions = {len(vector) for vector in vectors}
+        if len(dimensions) > 1:
+            raise ValidationError("embedding response vectors have inconsistent dimensions")
+        if vectors and dimensions == {0}:
+            raise ValidationError("embedding response vectors must not be empty")
+        if any(not math.isfinite(value) for vector in vectors for value in vector):
+            raise ValidationError("embedding response contains a non-finite value")
+
+    @property
+    def dimensions(self) -> int | None:
+        return len(self.vectors[0]) if self.vectors else None
+
+
+@runtime_checkable
+class EmbeddingBackend(Protocol):
+    model_id: str
+
+    def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        """Embed a batch without changing input order."""
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        """Return stable, secret-free identity fields."""
+
+
+def normalize_vector(vector: tuple[float, ...]) -> tuple[float, ...]:
+    norm = math.sqrt(sum(value * value for value in vector))
+    if norm == 0:
+        return vector
+    return tuple(value / norm for value in vector)
+
+
+def validate_embedding_response(
+    request: EmbeddingRequest,
+    response: EmbeddingResponse,
+    *,
+    backend_dimensions: int | None = None,
+) -> EmbeddingResponse:
+    if len(response.vectors) != len(request.texts):
+        raise ValidationError(
+            "embedding response count does not match request: "
+            f"{len(response.vectors)} != {len(request.texts)}"
+        )
+    required_dimensions = request.dimensions or backend_dimensions
+    if required_dimensions is not None and any(
+        len(vector) != required_dimensions for vector in response.vectors
+    ):
+        raise ValidationError(
+            f"embedding response dimension does not match required {required_dimensions}"
+        )
+    if request.normalize:
+        return EmbeddingResponse(
+            vectors=tuple(normalize_vector(vector) for vector in response.vectors),
+            model=response.model,
+            usage=response.usage,
+            metadata=response.metadata,
+        )
+    return response
+
+
+__all__ = [
+    "EmbeddingBackend",
+    "EmbeddingRequest",
+    "EmbeddingResponse",
+    "EmbeddingUsage",
+    "normalize_vector",
+    "validate_embedding_response",
+]

agentinputlab/backends/embedding/callable.py

@@ -0,0 +1,75 @@
+"""Embedding backend using an explicitly injected callable client."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentinputlab.contracts.errors import ValidationError
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping
+
+from .base import (
+    EmbeddingBackend,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    EmbeddingUsage,
+    validate_embedding_response,
+)
+
+EmbeddingClient = Callable[
+    [EmbeddingRequest],
+    EmbeddingResponse | Iterable[Iterable[float]],
+]
+
+
+@dataclass(slots=True)
+class CallableEmbeddingBackend(EmbeddingBackend):
+    """Adapt a local function, SDK client, RPC bridge, or test double.
+
+    The callable itself is never fingerprinted through ``repr``.  Callers must
+    supply stable identity fields for any behavior that affects an experiment.
+    """
+
+    client: EmbeddingClient
+    model_id: str
+    revision: str = "unversioned"
+    dimensions: int | None = None
+    identity: Mapping[str, Any] = field(default_factory=dict)
+    network: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.revision or self.revision == "unversioned":
+            raise ValidationError("callable embedding requires an explicit stable revision")
+        if not self.identity:
+            raise ValidationError("callable embedding requires explicit identity fields")
+        self.identity = freeze_mapping(self.identity)
+
+    def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        raw = self.client(request)
+        if isinstance(raw, EmbeddingResponse):
+            response = raw
+        else:
+            response = EmbeddingResponse(
+                vectors=tuple(tuple(float(value) for value in vector) for vector in raw),
+                model=self.model_id,
+                usage=EmbeddingUsage(input_count=len(request.texts)),
+            )
+        return validate_embedding_response(
+            request,
+            response,
+            backend_dimensions=self.dimensions,
+        )
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        return {
+            "backend": "agentinputlab.callable_embedding.v1",
+            "model_id": self.model_id,
+            "revision": self.revision,
+            "dimensions": self.dimensions,
+            "identity_hash": content_hash(self.identity),
+            "network": self.network,
+        }
+
+
+__all__ = ["CallableEmbeddingBackend", "EmbeddingClient"]

agentinputlab/backends/embedding/replay.py

@@ -0,0 +1,129 @@
+"""Offline replay and deterministic fixture embedding backends."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentinputlab.contracts.errors import ValidationError
+from agentinputlab.contracts.serialization import content_hash
+
+from .base import (
+    EmbeddingBackend,
+    EmbeddingRequest,
+    EmbeddingResponse,
+    EmbeddingUsage,
+    validate_embedding_response,
+)
+
+
+@dataclass(slots=True)
+class ReplayEmbeddingBackend(EmbeddingBackend):
+    """Replay exact text-to-vector fixtures; missing texts fail closed."""
+
+    vectors: Mapping[str, Sequence[float]]
+    model_id: str = "replay-embedding"
+    revision: str = "fixture-v1"
+    _vectors: Mapping[str, tuple[float, ...]] = field(init=False, repr=False)
+    _dimensions: int | None = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        converted = {
+            text: tuple(float(value) for value in vector) for text, vector in self.vectors.items()
+        }
+        EmbeddingResponse(vectors=tuple(converted.values()), model=self.model_id)
+        dimensions = {len(vector) for vector in converted.values()}
+        if len(dimensions) > 1:
+            raise ValidationError("replay embedding fixtures have inconsistent dimensions")
+        self._vectors = converted
+        self._dimensions = next(iter(dimensions), None)
+
+    def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        missing = [text for text in request.texts if text not in self._vectors]
+        if missing:
+            raise ValidationError(
+                f"replay embedding fixture is missing {len(missing)} requested text(s)"
+            )
+        response = EmbeddingResponse(
+            vectors=tuple(self._vectors[text] for text in request.texts),
+            model=self.model_id,
+            usage=EmbeddingUsage(input_count=len(request.texts)),
+            metadata={"replay": True},
+        )
+        return validate_embedding_response(
+            request,
+            response,
+            backend_dimensions=self._dimensions,
+        )
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        fixtures = [(text, self._vectors[text]) for text in sorted(self._vectors)]
+        return {
+            "backend": "agentinputlab.replay_embedding.v1",
+            "model_id": self.model_id,
+            "revision": self.revision,
+            "dimensions": self._dimensions,
+            "fixture_count": len(fixtures),
+            "fixture_hash": content_hash(fixtures),
+            "network": False,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class DeterministicHashEmbeddingBackend(EmbeddingBackend):
+    """Small dependency-free embedding backend for tests only."""
+
+    model_id: str = "fixture-hash-embedding"
+    dimensions: int = 32
+    salt: str = "agentinputlab-v1"
+
+    def __post_init__(self) -> None:
+        if self.dimensions < 1:
+            raise ValidationError("hash embedding dimensions must be positive")
+
+    def _vector(self, text: str) -> tuple[float, ...]:
+        values: list[float] = []
+        counter = 0
+        while len(values) < self.dimensions:
+            payload = f"{self.salt}\0{counter}\0{text}".encode()
+            digest = hashlib.sha256(payload).digest()
+            for offset in range(0, len(digest), 4):
+                integer = int.from_bytes(digest[offset : offset + 4], "big")
+                values.append((integer / 0xFFFFFFFF) * 2.0 - 1.0)
+                if len(values) == self.dimensions:
+                    break
+            counter += 1
+        return tuple(values)
+
+    def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        if request.dimensions is not None and request.dimensions != self.dimensions:
+            raise ValidationError(
+                f"hash embedding dimension is fixed at {self.dimensions}, "
+                f"requested {request.dimensions}"
+            )
+        response = EmbeddingResponse(
+            vectors=tuple(self._vector(text) for text in request.texts),
+            model=self.model_id,
+            usage=EmbeddingUsage(input_count=len(request.texts)),
+            metadata={"fixture_only": True},
+        )
+        return validate_embedding_response(
+            request,
+            response,
+            backend_dimensions=self.dimensions,
+        )
+
+    def fingerprint(self) -> Mapping[str, Any]:
+        return {
+            "backend": "agentinputlab.hash_embedding.v1",
+            "model_id": self.model_id,
+            "dimensions": self.dimensions,
+            "salt_hash": content_hash(self.salt),
+            "fixture_only": True,
+            "network": False,
+        }
+
+
+__all__ = ["DeterministicHashEmbeddingBackend", "ReplayEmbeddingBackend"]

agentinputlab/backends/llm/__init__.py

@@ -0,0 +1,31 @@
+"""Language-model backend implementations."""
+
+from .base import (
+    GenerationRequest,
+    GenerationResponse,
+    LLMBackend,
+    ModelCapability,
+    Usage,
+    require_capabilities,
+)
+from .callable import CallableBackend, ReplayBackend
+from .decomp_completion import DecompCompletionBackend
+from .final_content_stop import FINAL_CONTENT_STOP_POLICY_ID, FinalContentStopBackend
+from .openai_compatible import OpenAICompatibleBackend
+from .transformers import TransformersBackend
+
+__all__ = [
+    "FINAL_CONTENT_STOP_POLICY_ID",
+    "CallableBackend",
+    "DecompCompletionBackend",
+    "FinalContentStopBackend",
+    "GenerationRequest",
+    "GenerationResponse",
+    "LLMBackend",
+    "ModelCapability",
+    "OpenAICompatibleBackend",
+    "ReplayBackend",
+    "TransformersBackend",
+    "Usage",
+    "require_capabilities",
+]