agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/runner/engine.py

@@ -0,0 +1,285 @@
+"""Minimal intervention runner preserving paired state and typed failures."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from agentinputlab.contracts.enums import PatchOp, StrEnum
+from agentinputlab.contracts.errors import (
+    AlgorithmOutputError,
+    BudgetExceededError,
+    IntentViolationError,
+    ValidationError,
+)
+from agentinputlab.contracts.intent import IntentCheck, check_intent_contract
+from agentinputlab.contracts.lifecycle import CompositeResult, Intervention, InterventionContext
+from agentinputlab.contracts.patch import InputPatch
+from agentinputlab.contracts.state import FrozenAgentState
+from agentinputlab.observability import (
+    BudgetLedger,
+    EventKind,
+    ObservedRunStatus,
+    PricingCatalog,
+    ResourceUsage,
+    RunMonitor,
+    instrument_context,
+)
+
+from .runtime_guard import runtime_dependency_nodes
+
+
+class RunStatus(StrEnum):
+    SUCCESS = "success"
+    NO_OP = "no_op"
+    FALLBACK = "fallback"
+    BUDGET_EXHAUSTED = "budget_exhausted"
+
+
+@dataclass(frozen=True, slots=True)
+class RunRecord:
+    release_id: str
+    input_state_hash: str
+    output_state_hash: str
+    patch: InputPatch
+    status: RunStatus
+    monitor_run_id: str = ""
+    duration_ms: float | None = None
+    usage: ResourceUsage = field(default_factory=ResourceUsage)
+    intent_check: IntentCheck | None = None
+
+
+class InterventionRunner:
+    """Run a profile without swallowing unavailable/error conditions."""
+
+    def __init__(self, *, monitor: RunMonitor | None = None) -> None:
+        self.monitor = monitor or RunMonitor()
+
+    def run(
+        self,
+        intervention: Intervention,
+        state: FrozenAgentState,
+        context: InterventionContext,
+    ) -> RunRecord:
+        _reject_hidden_runtime_dependencies(intervention)
+        monitor = context.monitor or self.monitor
+        if not isinstance(monitor, RunMonitor):
+            raise TypeError("context.monitor must be a RunMonitor")
+        intent_check: IntentCheck | None = None
+        with monitor.run_scope(
+            release_id=intervention.release_id,
+            state_hash=state.state_hash,
+            tags={"method_id": intervention.method_id, "family": intervention.family.value},
+        ) as run_id:
+            pricing = context.pricing_catalog
+            if pricing is not None and not isinstance(pricing, PricingCatalog):
+                raise TypeError("context.pricing_catalog must be a PricingCatalog")
+            runtime_context = instrument_context(
+                context,
+                state,
+                monitor,
+                run_id=run_id,
+                pricing=pricing,
+            )
+            ledger = runtime_context.budget_ledger
+            if not isinstance(ledger, BudgetLedger):  # pragma: no cover - helper invariant
+                raise TypeError("instrumented context did not produce a BudgetLedger")
+            monitor.emit(EventKind.STAGE_STARTED, component="intervention")
+            try:
+                patch = intervention.propose(state, runtime_context)
+                if not isinstance(patch, InputPatch):
+                    raise AlgorithmOutputError(
+                        f"intervention must return an InputPatch; got {type(patch).__name__}"
+                    )
+                if patch.method_id != intervention.method_id:
+                    raise AlgorithmOutputError("intervention returned a patch for another method")
+                if patch.release_id != intervention.release_id:
+                    raise AlgorithmOutputError("intervention returned a patch for another release")
+                self._reconcile_trace_usage(patch, ledger, monitor)
+                output = patch.apply(state)
+                if runtime_context.intent_contract is not None:
+                    intent_check = check_intent_contract(
+                        runtime_context.intent_contract,
+                        state,
+                        patch,
+                        output,
+                    )
+                    monitor.emit(
+                        EventKind.INTENT_CHECKED,
+                        component="intent_gate",
+                        payload={
+                            "preserved": intent_check.preserved,
+                            "missing_entities": intent_check.missing_entities,
+                            "missing_constraints": intent_check.missing_constraints,
+                            "introduced_assumptions": intent_check.introduced_assumptions,
+                        },
+                    )
+                    if runtime_context.strict_intent and not intent_check.preserved:
+                        raise IntentViolationError("observable intent contract was not preserved")
+                ledger.require_within_budget()
+            except BudgetExceededError as exc:
+                monitor.record_failure(
+                    exc,
+                    category="budget_exhausted",
+                    stage="intervention",
+                )
+                monitor.finish_run(ObservedRunStatus.BUDGET_EXHAUSTED, run_id=run_id)
+                raise
+            except IntentViolationError as exc:
+                monitor.record_failure(
+                    exc,
+                    category="intent_drift",
+                    stage="intent_gate",
+                )
+                monitor.finish_run(ObservedRunStatus.INTENT_REJECTED, run_id=run_id)
+                raise
+
+            is_noop = all(operation.op is PatchOp.NO_OP for operation in patch.operations)
+            if patch.metadata.get("fallback"):
+                status = RunStatus.FALLBACK
+            elif patch.metadata.get("budget_exhausted"):
+                status = RunStatus.BUDGET_EXHAUSTED
+            elif is_noop:
+                status = RunStatus.NO_OP
+            else:
+                status = RunStatus.SUCCESS
+            monitor.emit(
+                EventKind.STAGE_FINISHED,
+                component="intervention",
+                payload={"status": status.value, "patch_hash": patch.patch_hash},
+            )
+            observed_status = ObservedRunStatus.SUCCEEDED
+            if status is RunStatus.BUDGET_EXHAUSTED:
+                error = BudgetExceededError("intervention reported budget exhaustion")
+                monitor.record_failure(
+                    error,
+                    category="budget_exhausted",
+                    stage="intervention",
+                )
+                observed_status = ObservedRunStatus.BUDGET_EXHAUSTED
+            snapshot = monitor.finish_run(
+                observed_status,
+                run_id=run_id,
+                payload={"outcome": status.value},
+            )
+            return RunRecord(
+                release_id=intervention.release_id,
+                input_state_hash=state.state_hash,
+                output_state_hash=output.state_hash,
+                patch=patch,
+                status=status,
+                monitor_run_id=run_id,
+                duration_ms=snapshot.duration_ms,
+                usage=snapshot.usage,
+                intent_check=intent_check,
+            )
+
+    @staticmethod
+    def _reconcile_trace_usage(
+        patch: InputPatch | CompositeResult,
+        ledger: BudgetLedger,
+        monitor: RunMonitor,
+    ) -> None:
+        """Charge counters emitted by uninstrumented upstream workers once."""
+
+        counters = patch.trace.counters
+        current = ledger.usage
+        declared = ResourceUsage(
+            model_calls=_trace_integer_counter(counters, "model_calls"),
+            retrieval_calls=_trace_integer_counter(counters, "retrieval_calls"),
+            tool_calls=_trace_integer_counter(counters, "tool_calls"),
+            embedding_calls=_trace_integer_counter(counters, "embedding_calls"),
+            unpriced_model_calls=_trace_integer_counter(counters, "unpriced_model_calls"),
+            input_tokens=_trace_integer_counter(counters, "input_tokens"),
+            output_tokens=_trace_integer_counter(counters, "output_tokens"),
+            cpu_seconds=_trace_float_counter(counters, "cpu_seconds"),
+            accelerator_seconds=_trace_float_counter(counters, "accelerator_seconds"),
+            cost_usd=_trace_float_counter(counters, "cost_usd"),
+            compute_cost_usd=_trace_float_counter(counters, "compute_cost_usd"),
+        )
+        delta = ResourceUsage(
+            model_calls=max(0, declared.model_calls - current.model_calls),
+            retrieval_calls=max(0, declared.retrieval_calls - current.retrieval_calls),
+            tool_calls=max(0, declared.tool_calls - current.tool_calls),
+            embedding_calls=max(0, declared.embedding_calls - current.embedding_calls),
+            unpriced_model_calls=max(
+                0,
+                declared.unpriced_model_calls - current.unpriced_model_calls,
+            ),
+            input_tokens=max(0, declared.input_tokens - current.input_tokens),
+            output_tokens=max(0, declared.output_tokens - current.output_tokens),
+            cpu_seconds=max(0.0, declared.cpu_seconds - current.cpu_seconds),
+            accelerator_seconds=max(
+                0.0,
+                declared.accelerator_seconds - current.accelerator_seconds,
+            ),
+            cost_usd=max(0.0, declared.cost_usd - current.cost_usd),
+            compute_cost_usd=max(
+                0.0,
+                declared.compute_cost_usd - current.compute_cost_usd,
+            ),
+        )
+        if delta != ResourceUsage():
+            try:
+                ledger.charge_actual(delta)
+            except BudgetExceededError:
+                monitor.record_usage(delta, component="upstream_trace")
+                monitor.emit(EventKind.BUDGET_EXCEEDED, component="upstream_trace")
+                raise
+            monitor.record_usage(delta, component="upstream_trace")
+
+
+def _trace_integer_counter(counters: Mapping[str, object], name: str) -> int:
+    value = counters.get(name, 0)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise ValidationError(
+            f"trace counter {name!r} must be a non-negative integer; got {value!r}"
+        )
+    return value
+
+
+def _trace_float_counter(counters: Mapping[str, object], name: str) -> float:
+    value = counters.get(name, 0.0)
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or value < 0
+        or not math.isfinite(value)
+    ):
+        raise ValidationError(
+            f"trace counter {name!r} must be finite and non-negative; got {value!r}"
+        )
+    return float(value)
+
+
+def _reject_hidden_runtime_dependencies(intervention: Intervention) -> None:
+    """Keep executable dependencies on the context, independent of field names.
+
+    Upstream adapters may call an LLM field ``generator`` or nest a backend in a
+    small configuration holder.  Looking only for attributes literally named
+    ``backend`` would let those calls bypass monitoring, budgets, and balance
+    fingerprints.  This bounded walk inspects the intervention's declared
+    state and data containers, but never descends into arbitrary dependency
+    implementations.
+    """
+
+    hidden = _hidden_runtime_dependency_paths(intervention)
+    if hidden:
+        names = ", ".join(hidden)
+        raise ValidationError(
+            "runtime dependencies must be injected through InterventionContext "
+            f"for monitoring and balance audit; hidden on intervention: {names}"
+        )
+
+
+def _hidden_runtime_dependency_paths(intervention: Intervention) -> list[str]:
+    return sorted(
+        {
+            node.path
+            for node in runtime_dependency_nodes(
+                intervention,
+                root_path="intervention",
+            )
+        }
+    )

agentinputlab/runner/runtime_guard.py

@@ -0,0 +1,268 @@
+"""Bounded object-graph inspection for executable runtime dependencies."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, fields, is_dataclass
+from functools import partial
+from types import BuiltinFunctionType, FunctionType, MethodType, ModuleType
+from typing import Any
+
+from agentinputlab.backends.llm import LLMBackend
+from agentinputlab.backends.retrieval import Retriever
+from agentinputlab.backends.vector import DenseEmbedder, VectorSearcher
+from agentinputlab.connectors.tools import ToolConnector
+from agentinputlab.contracts.errors import ValidationError
+
+RUNTIME_DEPENDENCY_TYPES = (
+    LLMBackend,
+    DenseEmbedder,
+    Retriever,
+    VectorSearcher,
+    ToolConnector,
+)
+
+_EXTERNAL_EXECUTOR_METHODS = ("call", "invoke", "reformulate", "run")
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectGraphNode:
+    path: str
+    value: object
+
+
+def inspect_object_graph(
+    root: object,
+    *,
+    root_path: str,
+    terminal_types: tuple[type[Any], ...] = (),
+    traverse_runtime_delegates: bool = False,
+    max_depth: int = 8,
+    max_nodes: int = 4096,
+) -> tuple[ObjectGraphNode, ...]:
+    """Return a cycle-safe snapshot of declared object state and callable captures.
+
+    Mapping keys, bound-method owners, function defaults/closures/referenced
+    globals, partial arguments, dataclass fields, ``__dict__``, and ``__slots__``
+    are included.  The walk never executes user callables.  Hitting a bound is
+    an error rather than a silent partial audit.
+    """
+
+    nodes: list[ObjectGraphNode] = []
+    visited: set[int] = set()
+
+    def walk_function_captures(
+        function: FunctionType,
+        path: str,
+        *,
+        depth: int,
+        include_globals: bool,
+    ) -> None:
+        walk(function.__defaults__, f"{path}.__defaults__", depth=depth + 1)
+        walk(function.__kwdefaults__, f"{path}.__kwdefaults__", depth=depth + 1)
+        for index, cell in enumerate(function.__closure__ or ()):
+            try:
+                captured = cell.cell_contents
+            except ValueError:  # empty closure cell
+                continue
+            walk(captured, f"{path}.__closure__[{index}]", depth=depth + 1)
+        if include_globals:
+            for name in function.__code__.co_names:
+                if name in function.__globals__:
+                    walk(
+                        function.__globals__[name],
+                        f"{path}.__globals__[{name}]",
+                        depth=depth + 1,
+                    )
+
+    def walk(value: object, path: str, *, depth: int) -> None:
+        if value is None or isinstance(value, (str, bytes, int, float, bool, type, ModuleType)):
+            return
+        if depth > max_depth:
+            raise ValidationError(
+                f"runtime-dependency inspection exceeded depth {max_depth} at {path}"
+            )
+
+        identity = id(value)
+        if identity in visited:
+            return
+        visited.add(identity)
+        nodes.append(ObjectGraphNode(path, value))
+        if len(nodes) > max_nodes:
+            raise ValidationError(f"runtime-dependency inspection exceeded {max_nodes} objects")
+        if terminal_types and isinstance(value, terminal_types):
+            return
+        # An executable dependency is normally an auditable boundary: callers
+        # bind its public fingerprint and execution instance, while its private
+        # model graph (for example a SentenceTransformer/PyTorch module tree)
+        # is not part of hidden-dependency discovery.  Balance checks may opt
+        # into following only direct runtime delegates and ledgers so a proxy
+        # cannot conceal a shared executable object without opening the full
+        # model graph.
+        if is_runtime_dependency(value):
+            if traverse_runtime_delegates:
+                for name, item in _instance_state_items(value):
+                    if is_runtime_dependency(item) or (
+                        terminal_types and isinstance(item, terminal_types)
+                    ):
+                        walk(item, f"{path}.{name}", depth=depth + 1)
+            return
+
+        if isinstance(value, Mapping):
+            for index, (key, item) in enumerate(value.items()):
+                walk(key, f"{path}.key[{index}]", depth=depth + 1)
+                walk(item, f"{path}.value[{index}]", depth=depth + 1)
+            return
+        if isinstance(value, (tuple, list, set, frozenset)):
+            for index, item in enumerate(value):
+                walk(item, f"{path}[{index}]", depth=depth + 1)
+            return
+        if isinstance(value, partial):
+            walk(value.func, f"{path}.func", depth=depth + 1)
+            walk(value.args, f"{path}.args", depth=depth + 1)
+            walk(value.keywords, f"{path}.keywords", depth=depth + 1)
+            return
+        if isinstance(value, MethodType):
+            walk(value.__self__, f"{path}.__self__", depth=depth + 1)
+            walk(value.__func__, f"{path}.__func__", depth=depth + 1)
+            return
+        if isinstance(value, FunctionType):
+            walk_function_captures(value, path, depth=depth, include_globals=True)
+            return
+        if isinstance(value, BuiltinFunctionType):
+            owner = getattr(value, "__self__", None)
+            if owner is not None:
+                walk(owner, f"{path}.__self__", depth=depth + 1)
+            return
+        if is_dataclass(value) and not isinstance(value, type):
+            for declared in fields(value):
+                walk(
+                    getattr(value, declared.name),
+                    f"{path}.{declared.name}",
+                    depth=depth + 1,
+                )
+        else:
+            attributes = getattr(value, "__dict__", {})
+            if isinstance(attributes, Mapping):
+                for name, item in attributes.items():
+                    walk(item, f"{path}.{name}", depth=depth + 1)
+        for owner in type(value).__mro__:
+            declared_slots = owner.__dict__.get("__slots__", ())
+            if isinstance(declared_slots, str):
+                declared_slots = (declared_slots,)
+            for name in declared_slots:
+                if name in {"__dict__", "__weakref__"} or not hasattr(value, name):
+                    continue
+                walk(getattr(value, name), f"{path}.{name}", depth=depth + 1)
+        ignored_class_names = {
+            "__annotations__",
+            "__dict__",
+            "__doc__",
+            "__module__",
+            "__slots__",
+            "__weakref__",
+        }
+        for owner in type(value).__mro__:
+            for name, declared in owner.__dict__.items():
+                if name in ignored_class_names or (name.startswith("__") and name.endswith("__")):
+                    continue
+                function: FunctionType | None = None
+                if isinstance(declared, (classmethod, staticmethod)):
+                    unwrapped = declared.__func__
+                    if isinstance(unwrapped, FunctionType):
+                        function = unwrapped
+                elif isinstance(declared, FunctionType):
+                    function = declared
+                if function is not None:
+                    walk_function_captures(
+                        function,
+                        f"{path}.__class__.{name}",
+                        depth=depth + 1,
+                        include_globals=False,
+                    )
+                    continue
+                if isinstance(declared, property):
+                    for accessor_name, accessor in (
+                        ("fget", declared.fget),
+                        ("fset", declared.fset),
+                        ("fdel", declared.fdel),
+                    ):
+                        if isinstance(accessor, FunctionType):
+                            walk_function_captures(
+                                accessor,
+                                f"{path}.__class__.{name}.{accessor_name}",
+                                depth=depth + 1,
+                                include_globals=False,
+                            )
+                    continue
+                if hasattr(declared, "__get__"):
+                    continue
+                walk(declared, f"{path}.__class__.{name}", depth=depth + 1)
+
+    walk(root, root_path, depth=0)
+    return tuple(nodes)
+
+
+def _instance_state_items(value: object) -> tuple[tuple[str, object], ...]:
+    """Return direct instance state once, without executing descriptors."""
+
+    items: dict[str, object] = {}
+    if is_dataclass(value) and not isinstance(value, type):
+        for declared in fields(value):
+            items[declared.name] = getattr(value, declared.name)
+    attributes = getattr(value, "__dict__", {})
+    if isinstance(attributes, Mapping):
+        items.update((str(name), item) for name, item in attributes.items())
+    for owner in type(value).__mro__:
+        declared_slots = owner.__dict__.get("__slots__", ())
+        if isinstance(declared_slots, str):
+            declared_slots = (declared_slots,)
+        for name in declared_slots:
+            if name in {"__dict__", "__weakref__"} or name in items:
+                continue
+            if hasattr(value, name):
+                items[name] = getattr(value, name)
+    return tuple(items.items())
+
+
+def runtime_dependency_nodes(
+    root: object,
+    *,
+    root_path: str,
+    terminal_types: tuple[type[Any], ...] = (),
+) -> tuple[ObjectGraphNode, ...]:
+    return tuple(
+        node
+        for node in inspect_object_graph(
+            root,
+            root_path=root_path,
+            terminal_types=terminal_types,
+        )
+        if is_runtime_dependency(node.value)
+    )
+
+
+def is_runtime_dependency(value: object) -> bool:
+    """Return whether ``value`` can perform an in-scope external execution.
+
+    The core backend protocols are nominally identifiable.  Pinned upstream
+    bridges intentionally use small structural seams instead (``call``,
+    ``run``, or ``reformulate`` plus a stable fingerprint), so they must also
+    be treated as executable dependencies regardless of their field name.
+    """
+
+    if isinstance(value, RUNTIME_DEPENDENCY_TYPES):
+        return True
+    fingerprint = getattr(value, "fingerprint", None)
+    return callable(fingerprint) and any(
+        callable(getattr(value, method, None)) for method in _EXTERNAL_EXECUTOR_METHODS
+    )
+
+
+__all__ = [
+    "RUNTIME_DEPENDENCY_TYPES",
+    "ObjectGraphNode",
+    "inspect_object_graph",
+    "is_runtime_dependency",
+    "runtime_dependency_nodes",
+]

agentinputlab/runner/worker.py

@@ -0,0 +1,80 @@
+"""Strict external-worker clients.
+
+The subprocess transport accepts an argv tuple and never invokes a shell.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from agentinputlab.contracts.errors import ExternalDependencyError
+from agentinputlab.contracts.serialization import to_jsonable
+from agentinputlab.contracts.worker import WorkerRequest, WorkerResponse
+from agentinputlab.integrations.external_workers.process import run_bounded_process
+
+
+@runtime_checkable
+class WorkerClient(Protocol):
+    def invoke(self, request: WorkerRequest) -> WorkerResponse: ...
+
+
+@dataclass(slots=True)
+class FunctionWorkerClient(WorkerClient):
+    fn: Callable[[WorkerRequest], WorkerResponse]
+
+    def invoke(self, request: WorkerRequest) -> WorkerResponse:
+        return self.fn(request)
+
+
+@dataclass(slots=True)
+class JsonLineWorkerClient(WorkerClient):
+    argv: tuple[str, ...]
+    timeout_seconds: float = 300.0
+    max_request_bytes: int = 8 * 1024 * 1024
+    max_response_bytes: int = 8 * 1024 * 1024
+    max_stderr_bytes: int = 1024 * 1024
+    cwd: str | None = None
+    env: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.argv = tuple(self.argv)
+        if not self.argv:
+            raise ValueError("worker argv must not be empty")
+        if min(self.max_request_bytes, self.max_response_bytes, self.max_stderr_bytes) < 1:
+            raise ValueError("worker byte limits must be positive")
+
+    def invoke(self, request: WorkerRequest) -> WorkerResponse:
+        payload = json.dumps(to_jsonable(request), sort_keys=True) + "\n"
+        completed = run_bounded_process(
+            self.argv,
+            input_text=payload,
+            timeout_seconds=self.timeout_seconds,
+            max_input_bytes=self.max_request_bytes,
+            max_stdout_bytes=self.max_response_bytes,
+            max_stderr_bytes=self.max_stderr_bytes,
+            cwd=self.cwd,
+            environment=self.env,
+            process_name="external worker",
+        )
+        if completed.returncode != 0:
+            stderr = completed.stderr[-2000:]
+            raise ExternalDependencyError(
+                f"external worker exited {completed.returncode}: {stderr}"
+            )
+        lines = [line for line in completed.stdout.splitlines() if line.strip()]
+        if len(lines) != 1:
+            raise ExternalDependencyError("external worker must emit exactly one JSON line")
+        try:
+            data = json.loads(lines[0])
+        except json.JSONDecodeError as exc:
+            raise ExternalDependencyError("external worker returned invalid JSON") from exc
+        try:
+            response = WorkerResponse(**data)
+        except (TypeError, ValueError) as exc:
+            raise ExternalDependencyError("external worker returned an invalid envelope") from exc
+        if response.request_id != request.request_id:
+            raise ExternalDependencyError("external worker response request_id mismatch")
+        return response