agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/api.py

@@ -0,0 +1,368 @@
+"""Small Python API and authenticated loopback HTTP transport for the SDK.
+
+No experiment archives, remote imports, arbitrary commands or client-supplied
+backend URLs are accepted. Operators configure dependencies in Python.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hmac
+import inspect
+import json
+import os
+import threading
+from collections.abc import Callable, Mapping
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from agentinputlab import ContextBlock, ExecutionBudget, FrozenAgentState, Message
+from agentinputlab.benchmarks import BenchmarkRegistry
+from agentinputlab.contracts import InterventionContext
+from agentinputlab.contracts.errors import (
+    AgentInputLabError,
+    AlgorithmOutputError,
+    AlgorithmUnavailableError,
+    BudgetExceededError,
+    CapabilityError,
+    RegistryError,
+    ValidationError,
+)
+from agentinputlab.contracts.serialization import to_jsonable
+from agentinputlab.registry import AlgorithmRegistry
+from agentinputlab.runner import CompositeInterventionRunner, InterventionRunner
+from agentinputlab.selectors import NoOpIntervention
+
+
+def create_intervention(release_id: str, **parameters: Any) -> Any:
+    """Instantiate a registered profile; optional runtime assets remain explicit.
+
+    Parameters use the adapter's original Python signature. This does not turn
+    composite agents into input-patch methods or assert benchmark eligibility.
+    """
+    if release_id == "baseline.no_op":
+        return NoOpIntervention(**parameters)
+    factory = AlgorithmRegistry.default().resolve_entrypoint(release_id)
+    signature = inspect.signature(factory)
+    if "release_id" in signature.parameters:
+        parameters["release_id"] = release_id
+    signature.bind(**parameters)
+    result = factory(**parameters)
+    actual = getattr(result, "release_id", release_id)
+    if actual != release_id:
+        raise ValidationError(
+            f"registered profile {release_id} constructed a different release: {actual}"
+        )
+    return result
+
+
+def run_intervention(
+    intervention: Any, state: FrozenAgentState, context: InterventionContext | None = None
+) -> dict[str, Any]:
+    """Run one patch intervention, preserving the native trace, budget and errors.
+
+    A successful patch is NOT a benchmark score. Continue the patched state in
+    the benchmark's native runtime and official scorer to obtain an endpoint.
+    """
+    record = InterventionRunner().run(intervention, state, context or InterventionContext())
+    return {
+        "record": to_jsonable(record),
+        "state": to_jsonable(record.patch.apply(state)),
+        "scored": False,
+        "benchmark_score": None,
+    }
+
+
+def run_composite_intervention(
+    intervention: Any, state: FrozenAgentState, context: InterventionContext | None = None
+) -> dict[str, Any]:
+    """Run an answer-producing architecture with observed calls and cost.
+
+    The result is not a state patch or a benchmark score. The independent
+    benchmark provider/scorer still evaluates the returned final answer.
+    """
+    record = CompositeInterventionRunner().run(
+        intervention, state, context or InterventionContext()
+    )
+    return {
+        "record": to_jsonable(record),
+        "final_answer": record.result.final_answer,
+        "evidence": to_jsonable(record.result.evidence),
+        "scored": False,
+        "benchmark_score": None,
+    }
+
+
+def catalog() -> dict[str, Any]:
+    registry = AlgorithmRegistry.default()
+    return {
+        "methods": [m.to_dict() for m in registry.list_methods()],
+        "benchmarks": [to_jsonable(b) for b in BenchmarkRegistry.default().list()],
+        "note": "Inventory is not a claim that every method/dataset/model combination is supported or tested.",
+    }
+
+
+def _state(value: Any) -> FrozenAgentState:
+    if not isinstance(value, dict):
+        raise ValidationError("state must be an object")
+    allowed = {
+        "query",
+        "task_id",
+        "instruction",
+        "context",
+        "messages",
+        "tool_names",
+        "metadata",
+        "budget",
+    }
+    if value.keys() - allowed:
+        raise ValidationError("unknown state fields")
+    for key in ("query", "task_id", "instruction"):
+        if key in value and not isinstance(value[key], str):
+            raise ValidationError(f"{key} must be a string")
+    for key in ("context", "messages", "tool_names"):
+        if key in value and not isinstance(value[key], list):
+            raise ValidationError(f"{key} must be an array")
+    for key in ("metadata", "budget"):
+        if key in value and not isinstance(value[key], dict):
+            raise ValidationError(f"{key} must be an object")
+    try:
+        return FrozenAgentState(
+            **{
+                **value,
+                "context": tuple(ContextBlock(**x) for x in value.get("context", [])),
+                "messages": tuple(Message(**x) for x in value.get("messages", [])),
+                "budget": ExecutionBudget(**value.get("budget", {})),
+            }
+        )
+    except (TypeError, AttributeError) as exc:
+        raise ValidationError("invalid nested state fields") from exc
+
+
+class ToolkitService:
+    """Operator-owned factories and contexts; clients cannot inject Python code.
+
+    All Python profiles remain available through create_intervention. HTTP only
+    exposes explicitly configured patch profiles. Construct a fresh context per
+    request; do not share a mutable budget ledger between calls.
+    """
+
+    def __init__(
+        self,
+        factories: Mapping[str, Callable[[], Any]] | None = None,
+        context_factory: Callable[[int], InterventionContext] | None = None,
+    ):
+        self.factories = dict(
+            factories
+            if factories is not None
+            else {
+                "baseline.no_op": NoOpIntervention,
+                "plan.plan_and_solve.ps_prompt": lambda: create_intervention(
+                    "plan.plan_and_solve.ps_prompt"
+                ),
+            }
+        )
+        self.context_factory = context_factory or (lambda seed: InterventionContext(seed=seed))
+
+    def execute(self, body: Any) -> dict[str, Any]:
+        if not isinstance(body, dict) or body.keys() - {"release_id", "state", "seed"}:
+            raise ValidationError("expected release_id, state and optional seed")
+        rid = body.get("release_id")
+        if not isinstance(rid, str):
+            raise ValidationError("release_id must be a string")
+        if rid not in self.factories:
+            raise AlgorithmUnavailableError("profile is not configured on this server")
+        seed = body.get("seed", 0)
+        if isinstance(seed, bool) or not isinstance(seed, int) or seed < 0:
+            raise ValidationError("seed must be a non-negative integer")
+        state = _state(body.get("state"))
+        return run_intervention(self.factories[rid](), state, self.context_factory(seed))
+
+
+def make_server(service: ToolkitService, *, token: str, port: int = 8765) -> ThreadingHTTPServer:
+    """Authenticated loopback-only development service, not a public web host.
+
+    Bounded request bodies and one active execution. Put a production ASGI
+    deployment with TLS, quotas and job persistence in front for shared use.
+    Client timeouts do not cancel running model calls; there is no auto retry.
+    """
+    if not isinstance(token, str) or len(token) < 24 or not token.isascii():
+        raise ValueError("API token must be at least 24 ASCII characters")
+    lock = threading.Lock()
+
+    class Handler(BaseHTTPRequestHandler):
+        def setup(self):
+            super().setup()
+            self.connection.settimeout(30)
+
+        def log_message(self, *_args):
+            pass  # Never log bearer tokens, user prompts or upstream errors.
+
+        def send_json(self, status: int, value: Any):
+            data = json.dumps(value, allow_nan=False).encode()
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(data)))
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.end_headers()
+            self.wfile.write(data)
+
+        def authorized(self):
+            given = self.headers.get("Authorization", "").encode()
+            if not hmac.compare_digest(given, ("Bearer " + token).encode()):
+                self.send_json(
+                    401,
+                    {"error": {"code": "unauthorized", "message": "A valid API token is required"}},
+                )
+                return False
+            return True
+
+        def do_GET(self):
+            if not self.authorized():
+                return
+            if self.path == "/v1/catalog":
+                self.send_json(
+                    200, {"data": {**catalog(), "configured_releases": sorted(service.factories)}}
+                )
+            elif self.path == "/v1/health":
+                self.send_json(200, {"data": {"status": "ok", "protocol": "agentinputlab.v1"}})
+            else:
+                self.send_json(404, {"error": {"code": "not_found", "message": "Unknown resource"}})
+
+        def do_POST(self):
+            if not self.authorized():
+                return
+            if self.path != "/v1/interventions":
+                self.send_json(404, {"error": {"code": "not_found", "message": "Unknown resource"}})
+                return
+            if self.headers.get("Transfer-Encoding"):
+                self.send_json(
+                    400,
+                    {
+                        "error": {
+                            "code": "invalid_body",
+                            "message": "Chunked bodies are unsupported",
+                        }
+                    },
+                )
+                return
+            try:
+                length = int(self.headers.get("Content-Length", "-1"))
+            except ValueError:
+                length = -1
+            if length < 0 or length > 1024 * 1024:
+                self.send_json(
+                    413 if length > 0 else 411,
+                    {
+                        "error": {
+                            "code": "body_size",
+                            "message": "A body of at most 1 MiB is required",
+                        }
+                    },
+                )
+                return
+            if self.headers.get_content_type() != "application/json":
+                self.send_json(
+                    415, {"error": {"code": "content_type", "message": "Use application/json"}}
+                )
+                return
+            if not lock.acquire(blocking=False):
+                self.send_json(
+                    429,
+                    {
+                        "error": {
+                            "code": "busy",
+                            "message": "An execution is already active; no attempt started",
+                        }
+                    },
+                )
+                return
+            try:
+                body = json.loads(
+                    self.rfile.read(length),
+                    parse_constant=lambda _: (_ for _ in ()).throw(ValueError()),
+                )
+                result = service.execute(body)
+                self.send_json(200, {"data": result})
+            except (json.JSONDecodeError, UnicodeDecodeError, ValueError) as exc:
+                # Output errors inherit ValueError through ValidationError.
+                code = (
+                    "algorithm_output"
+                    if isinstance(exc, AlgorithmOutputError)
+                    else "invalid_request"
+                )
+                self.send_json(
+                    422 if code == "algorithm_output" else 400,
+                    {
+                        "error": {
+                            "code": code,
+                            "message": "Invalid output"
+                            if code == "algorithm_output"
+                            else "Invalid request schema",
+                        }
+                    },
+                )
+            except (AlgorithmUnavailableError, CapabilityError, RegistryError):
+                self.send_json(
+                    422,
+                    {
+                        "error": {
+                            "code": "unavailable",
+                            "message": "Required profile dependencies are not configured",
+                        }
+                    },
+                )
+            except BudgetExceededError:
+                self.send_json(
+                    422,
+                    {
+                        "error": {
+                            "code": "budget_exhausted",
+                            "message": "Execution budget exhausted",
+                        }
+                    },
+                )
+            except AgentInputLabError:
+                self.send_json(
+                    422,
+                    {
+                        "error": {
+                            "code": "execution_failed",
+                            "message": "Execution rejected; no score was fabricated",
+                        }
+                    },
+                )
+            except Exception:
+                self.send_json(
+                    500,
+                    {
+                        "error": {
+                            "code": "internal_error",
+                            "message": "Execution failed; inspect the operator environment",
+                        }
+                    },
+                )
+            finally:
+                lock.release()
+
+    return ThreadingHTTPServer(("127.0.0.1", port), Handler)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Authenticated loopback AgentInputLab SDK service")
+    parser.add_argument("--port", type=int, default=8765)
+    args = parser.parse_args()
+    server = make_server(
+        ToolkitService(), token=os.environ.get("AGENTINPUTLAB_API_TOKEN", ""), port=args.port
+    )
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()

agentinputlab/artifacts/__init__.py

@@ -0,0 +1,15 @@
+"""Artifact schemas and checksum-verified local storage."""
+
+from .json_file import load_pinned_json_mapping
+from .manifest import AcquisitionPolicy, ArtifactKind, ArtifactManifest, UpstreamLock
+from .store import ArtifactStore, sha256_file
+
+__all__ = [
+    "AcquisitionPolicy",
+    "ArtifactKind",
+    "ArtifactManifest",
+    "ArtifactStore",
+    "UpstreamLock",
+    "load_pinned_json_mapping",
+    "sha256_file",
+]

agentinputlab/artifacts/json_file.py

@@ -0,0 +1,104 @@
+"""Bounded checksum-pinned JSON loading without pickle or executable imports."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import stat
+from pathlib import Path
+from typing import Any
+
+from agentinputlab.contracts.errors import ArtifactError
+
+
+def _unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON object keys")
+        result[key] = value
+    return result
+
+
+def _finite_json(_value):
+    raise ValueError("non-finite JSON numbers")
+
+
+def _finite_float(value):
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError("non-finite JSON numbers")
+    return number
+
+
+def load_pinned_json_mapping(
+    path: str | Path,
+    *,
+    expected_sha256: str,
+    max_bytes: int = 4 * 1024 * 1024,
+) -> dict[str, Any]:
+    """Read one regular UTF-8 JSON object under a caller-trusted byte checksum.
+
+    The checksum must come from a trusted receipt, not be computed from an
+    untrusted file immediately before loading. It proves byte identity, not
+    authorship, source-license permission, or the truth of recorded results.
+    """
+
+    if (
+        not isinstance(expected_sha256, str)
+        or len(expected_sha256) != 64
+        or any(c not in "0123456789abcdef" for c in expected_sha256.lower())
+    ):
+        raise ArtifactError("expected_sha256 must be a SHA-256 hex digest")
+    if type(max_bytes) is not int or max_bytes < 1:
+        raise ArtifactError("artifact JSON max_bytes must be a positive integer")
+    source = Path(path).expanduser()
+    read_failed = False
+    try:
+        before = source.lstat()
+        if not stat.S_ISREG(before.st_mode) or before.st_size > max_bytes:
+            raise ArtifactError("artifact JSON must be a bounded regular file, not a symlink")
+        descriptor = os.open(
+            source, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+        )
+        with os.fdopen(descriptor, "rb") as handle:
+            opened = os.fstat(handle.fileno())
+            if not stat.S_ISREG(opened.st_mode) or (before.st_dev, before.st_ino) != (
+                opened.st_dev,
+                opened.st_ino,
+            ):
+                raise ArtifactError("artifact JSON file changed while opening")
+            raw = handle.read(max_bytes + 1)
+            after = os.fstat(handle.fileno())
+            if (opened.st_size, opened.st_mtime_ns, opened.st_ctime_ns) != (
+                after.st_size,
+                after.st_mtime_ns,
+                after.st_ctime_ns,
+            ):
+                raise ArtifactError("artifact JSON file changed while reading")
+    except OSError:
+        read_failed = True
+    if read_failed:
+        raise ArtifactError("artifact JSON file is unavailable")
+    if len(raw) > max_bytes:
+        raise ArtifactError("artifact JSON exceeds max_bytes")
+    if hashlib.sha256(raw).hexdigest() != expected_sha256.lower():
+        raise ArtifactError("artifact JSON checksum mismatch")
+    invalid_json = False
+    value = None
+    try:
+        value = json.loads(
+            raw.decode("utf-8"),
+            object_pairs_hook=_unique_object,
+            parse_constant=_finite_json,
+            parse_float=_finite_float,
+        )
+    except (UnicodeError, ValueError, RecursionError):
+        invalid_json = True
+    if invalid_json or not isinstance(value, dict):
+        raise ArtifactError(
+            "artifact must contain a valid UTF-8 JSON object with unique keys and finite values"
+        )
+    return value

agentinputlab/artifacts/manifest.py

@@ -0,0 +1,98 @@
+"""Artifact and upstream-source identity schemas."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentinputlab.contracts.enums import StrEnum
+from agentinputlab.contracts.errors import ValidationError
+from agentinputlab.contracts.serialization import freeze_mapping
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_GIT_SHA = re.compile(r"^[0-9a-f]{40}$")
+_SAFE_SEGMENT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+class ArtifactKind(StrEnum):
+    DATASET = "dataset"
+    MODEL = "model"
+    INDEX = "index"
+    CACHE = "cache"
+    FEATURE = "feature"
+    PROMPT = "prompt"
+    TRACE = "trace"
+    RECIPE_OUTPUT = "recipe_output"
+
+
+class AcquisitionPolicy(StrEnum):
+    BUNDLED = "bundled"
+    DOWNLOAD = "download"
+    USER_PROVIDED = "user_provided"
+    GATED = "gated"
+    EXTERNAL_MOUNT = "external_mount"
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamLock:
+    repository: str
+    commit: str
+    license_id: str
+    vendoring_allowed: bool
+    subpath: str = ""
+    branch: str = ""
+
+    def __post_init__(self) -> None:
+        if self.commit and not _GIT_SHA.fullmatch(self.commit):
+            raise ValidationError("upstream git commit must be a full 40-character SHA")
+        if self.license_id == "NOASSERTION" and self.vendoring_allowed:
+            raise ValidationError("NOASSERTION source cannot be marked vendoring_allowed")
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactManifest:
+    artifact_id: str
+    kind: ArtifactKind
+    revision: str
+    sha256: str
+    acquisition: AcquisitionPolicy
+    license_id: str
+    source_uri: str = ""
+    size_bytes: int | None = None
+    lineage: Mapping[str, str] = field(default_factory=dict)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not _SAFE_SEGMENT.fullmatch(self.artifact_id) or ".." in self.artifact_id:
+            raise ValidationError("artifact_id must be a flat safe identifier")
+        if not _SAFE_SEGMENT.fullmatch(self.revision) or ".." in self.revision:
+            raise ValidationError("artifact revision must be a flat safe identifier")
+        if self.sha256 and not _SHA256.fullmatch(self.sha256):
+            raise ValidationError("artifact sha256 must contain 64 lowercase hex characters")
+        if self.acquisition is AcquisitionPolicy.DOWNLOAD:
+            if not self.sha256:
+                raise ValidationError("download artifacts require a pinned sha256")
+            if not self.source_uri:
+                raise ValidationError("download artifacts require a source_uri")
+        if self.size_bytes is not None and self.size_bytes < 0:
+            raise ValidationError("artifact size must be non-negative")
+        lineage = dict(self.lineage)
+        if any(
+            not isinstance(key, str)
+            or not key.strip()
+            or not isinstance(value, str)
+            or not value.strip()
+            for key, value in lineage.items()
+        ):
+            raise ValidationError("artifact lineage requires non-empty string keys and values")
+        try:
+            frozen_lineage = freeze_mapping(lineage)
+            frozen_metadata = freeze_mapping(self.metadata)
+        except TypeError as exc:
+            raise ValidationError(
+                f"artifact metadata must be canonically serializable: {exc}"
+            ) from exc
+        object.__setattr__(self, "lineage", frozen_lineage)
+        object.__setattr__(self, "metadata", frozen_metadata)