agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/integrations/full_architecture/__init__.py

@@ -0,0 +1 @@
+"""Full-agent architectures that cannot be represented as thin input patches."""

agentinputlab/integrations/full_architecture/hyde.py

@@ -0,0 +1,212 @@
+"""Execute caller-mounted HyDE source under a checksum-locked shape patch.
+
+The package contains no upstream source, native API client, model or index.
+Only the original algorithm and promptor modules are loaded from the mount.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from agentinputlab.artifacts import load_pinned_json_mapping
+from agentinputlab.backends.llm import GenerationRequest
+from agentinputlab.contracts import (
+    AlgorithmOutputError,
+    ArtifactError,
+    BudgetExceededError,
+    ExternalDependencyError,
+    Message,
+    ValidationError,
+)
+
+HYDE_UPSTREAM_REVISION="a2fd8734307612cb0225d71ffbf26e0d225986b8"
+HYDE_PATCH_PROTOCOL="agentinputlab.hyde.external-flatten-encoder.v1"
+HYDE_SOURCE_SHA256={
+    "src/hyde/hyde.py":"7a395213842b80052e2d47db45ddfff4ebf416d11197fdc9760997ecb2cf7041",
+    "src/hyde/promptor.py":"675a9ccc9336122095b401b6d05dc314fd6a3fbb067f78e4e660024892d78d34",
+}
+
+
+def _sources(source_root):
+    root=Path(source_root).expanduser().resolve()
+    result={}
+    for name,pin in HYDE_SOURCE_SHA256.items():
+        try:
+            path=root/name
+            if path.stat().st_size>65536:
+                raise ArtifactError("HyDE source exceeds the checked module size")
+            raw=path.read_bytes()
+        except OSError as exc:
+            raise ArtifactError(f"HyDE external source unavailable: {name}") from exc
+        if hashlib.sha256(raw).hexdigest()!=pin:
+            raise ArtifactError(f"HyDE external source SHA-256 differs: {name}")
+        result[name]=raw
+    return result
+
+
+def _patched_source(sources):
+    raw=sources["src/hyde/hyde.py"]
+    before=b"np.array(c_emb)"
+    after=b"np.asarray(c_emb).reshape(-1)"
+    if raw.count(before)!=1:
+        raise ArtifactError("HyDE reviewed encoder-shape patch site differs")
+    return raw.replace(before,after)
+
+
+def _manifest(sources):
+    return dict(schema_version=1,protocol=HYDE_PATCH_PROTOCOL,upstream_revision=HYDE_UPSTREAM_REVISION,
+        source_sha256=dict(HYDE_SOURCE_SHA256),
+        patch=dict(target="src/hyde/hyde.py:HyDE.encode",change="flatten_each_singleton_encoder_vector_before_mean",
+            patched_source_sha256=hashlib.sha256(_patched_source(sources)).hexdigest()),
+        native_client_module_imported=False,source_modified_on_disk=False,
+        source_review_acknowledged=True,source_redistributed_by_toolkit=False,
+        substitutions=["observed_serial_generation_draws","observed_dense_embedding","observed_corpus_vector_search"])
+
+
+def write_hyde_patch_manifest(source_root,output,*,accept_source_review=False):
+    """Create-only operator receipt. Source review is not a redistribution grant."""
+    if accept_source_review is not True:
+        raise ArtifactError("review the mounted HyDE source/terms and acknowledge source review explicitly")
+    value=_manifest(_sources(source_root))
+    path=Path(output).expanduser().resolve()
+    path.parent.mkdir(parents=True,exist_ok=True)
+    with path.open("x",encoding="utf-8") as f:
+        json.dump(value,f,indent=2,sort_keys=True,allow_nan=False)
+    return {"path":str(path),"sha256":hashlib.sha256(path.read_bytes()).hexdigest()}
+
+
+@dataclass(frozen=True,slots=True)
+class HyDEPatchedExecutionRequest:
+    """In-process callbacks are the runner's already-instrumented context objects.
+
+    This request is not an IPC recipe. Do not serialize or store its executable
+    dependencies on an intervention. Native bridge usage is charged there once.
+    """
+    query: str
+    config: Any
+    seed: int
+    budget: Any
+    backend: Any
+    embedder: Any
+    searcher: Any
+
+
+class HyDEPatchedSourceRuntime:
+    worker_id="agentinputlab.hyde.pinned-native-source.v1"
+
+    def __init__(self,*,source_root,patch_manifest,expected_manifest_sha256):
+        self.source_root=Path(source_root).expanduser().resolve()
+        self.patch_manifest=Path(patch_manifest).expanduser().resolve()
+        self.expected_manifest_sha256=expected_manifest_sha256
+
+    def _verified(self):
+        sources=_sources(self.source_root)
+        receipt=load_pinned_json_mapping(self.patch_manifest,expected_sha256=self.expected_manifest_sha256,max_bytes=65536)
+        if dict(receipt)!=_manifest(sources):
+            raise ArtifactError("HyDE patch manifest is not the exact reviewed patch/substitution set")
+        try:
+            import numpy
+        except ImportError as exc:
+            raise ExternalDependencyError("install agentinputlab[hyde-native] for the external source runtime") from exc
+        return sources,numpy
+
+    def fingerprint(self):
+        sources,np=self._verified()
+        return {"runtime_id":self.worker_id,"binding_mode":HYDE_PATCH_PROTOCOL,
+            "upstream_revision":HYDE_UPSTREAM_REVISION,"source_sha256":dict(HYDE_SOURCE_SHA256),
+            "patched_source_sha256":hashlib.sha256(_patched_source(sources)).hexdigest(),
+            "patch_manifest_sha256":self.expected_manifest_sha256,"numpy_version":np.__version__,
+            "native_generator_client_used":False,"source_redistributed":False,
+            "generation_transport":"observed_serial_draws_no_logprob_reordering_no_retry"}
+
+    def run(self,request):
+        from agentinputlab.algorithms.acquire.hyde import _validate_vectors
+        from agentinputlab.algorithms.acquire.hyde_external import HyDENativeConfig
+        if not isinstance(request,HyDEPatchedExecutionRequest) or not isinstance(request.config,HyDENativeConfig):
+            raise ValidationError("HyDE patched runtime requires its typed execution request/config")
+        sources,np=self._verified()
+        identity=self.fingerprint()
+        native_namespace={}
+        prompt_namespace={}
+        exec(compile(_patched_source(sources),"externally-mounted-hyde-patched","exec"),native_namespace)
+        exec(compile(sources["src/hyde/promptor.py"],"externally-mounted-hyde-promptor","exec"),prompt_namespace)
+        config=request.config
+        if (request.budget.max_model_calls<config.num_hypotheses or request.budget.max_retrieval_calls<1
+                or request.budget.max_output_tokens<config.num_hypotheses):
+            raise BudgetExceededError("HyDE cannot reserve all hypothesis draws and corpus search")
+        outputs=inputs=0
+        draws=[]
+        encoded=[]
+        mean_vectors=[]
+
+        class GeneratorBridge:
+            def generate(self,prompt):
+                nonlocal outputs,inputs
+                texts=[]
+                for index in range(config.num_hypotheses):
+                    remaining=request.budget.max_output_tokens-outputs
+                    reserve=config.num_hypotheses-index-1
+                    if remaining<=reserve:
+                        raise BudgetExceededError("HyDE output budget cannot cover remaining hypothesis draws")
+                    generation=GenerationRequest(messages=(Message("user",prompt),),temperature=config.temperature,
+                        max_tokens=min(config.max_tokens,remaining-reserve),seed=request.seed+index,stop=config.stop,
+                        metadata={"release_id":"acquire.hyde.official_external_patched","stage":"native_hypothesis",
+                            "hypothesis_index":index,"native_promptor_task":config.task})
+                    response=request.backend.generate(generation)
+                    if not isinstance(response.text,str):
+                        raise AlgorithmOutputError("HyDE generator returned non-text")
+                    inputs+=response.usage.input_tokens
+                    outputs+=response.usage.output_tokens
+                    if response.usage.output_tokens>generation.max_tokens:
+                        raise BudgetExceededError("HyDE provider exceeded requested hypothesis output cap")
+                    texts.append(response.text)
+                    draws.append(dict(text=response.text,request_hash=generation.request_hash,
+                        max_tokens=generation.max_tokens,seed=generation.seed,finish_reason=response.finish_reason))
+                return texts
+
+        class EncoderBridge:
+            def encode(self,text):
+                vectors=_validate_vectors(request.embedder.embed((text,)),expected_count=1)
+                encoded.append(vectors[0])
+                # Exercise the actual batched-singleton interface requiring the
+                # reviewed flatten patch; native code performs the mean itself.
+                return np.asarray(vectors)
+
+        class SearchBridge:
+            def search(self,vector,k):
+                if vector.ndim!=2 or vector.shape[0]!=1:
+                    raise AlgorithmOutputError("patched native HyDE returned a non-singleton matrix")
+                values=tuple(float(v) for v in vector[0])
+                mean_vectors.append(values)
+                return request.searcher.search(values,top_k=k)
+
+        promptor=prompt_namespace["Promptor"](task=config.task,language=config.language)
+        native=native_namespace["HyDE"](promptor,GeneratorBridge(),EncoderBridge(),SearchBridge())
+        cpu=time.thread_time()
+        process_cpu=time.process_time()
+        started=time.monotonic()
+        hits=native.e2e_search(request.query,k=config.top_k)
+        cpu=time.thread_time()-cpu
+        if self.fingerprint()!=identity:
+            raise ArtifactError("HyDE mounted runtime identity changed during execution")
+        return dict(identity=identity,results=hits,hypotheses=tuple(d["text"] for d in draws),draws=tuple(draws),
+            mean_vector=mean_vectors[0],encoded_vectors=tuple(encoded),native_prompt=promptor.build_prompt(request.query),
+            model_calls=len(draws),embedding_calls=len(encoded),retrieval_calls=1,
+            input_tokens=inputs,output_tokens=outputs,wall_seconds=time.monotonic()-started,
+            process_cpu_seconds_window=time.process_time()-process_cpu,
+            process_cpu_window_is_not_additive_across_concurrent_requests=True,
+            calling_thread_cpu_seconds=cpu,
+            # Delegated calls/tokens are already ledger-observed. RunMonitor
+            # also records its enclosing process CPU window at finish_run;
+            # adding the nested thread measurement would count it twice.
+            # Keep both measurements diagnostic, not additive usage charges.
+            usage=dict(model_calls=0,retrieval_calls=0,input_tokens=0,output_tokens=0,cpu_seconds=0.0),
+            usage_scope="calling_thread_cpu_lower_bound_diagnostic; outer monitor owns process CPU accounting; native-worker CPU excluded from thread measure")
+
+
+__all__=["HYDE_PATCH_PROTOCOL","HYDE_SOURCE_SHA256","HYDE_UPSTREAM_REVISION",
+    "HyDEPatchedExecutionRequest","HyDEPatchedSourceRuntime","write_hyde_patch_manifest"]

agentinputlab/integrations/full_architecture/plan_and_budget.py

@@ -0,0 +1,188 @@
+"""Source-pinned native P&B prompt construction, with no provider side effects.
+
+Only the released allocation functions and reasoning prompt are evaluated. The
+native dotenv/client setup, gold-aware evaluator and retry loop are not imported.
+The composite adapter owns the single, observed solver call after this boundary.
+"""
+
+from __future__ import annotations
+
+import ast
+import copy
+import hashlib
+import importlib
+import textwrap
+from dataclasses import dataclass
+from pathlib import Path
+from types import SimpleNamespace
+
+from agentinputlab.algorithms.decompose.plan_and_budget.cached_soft_budget import (
+    P_AND_B_UPSTREAM_REVISION,
+    CachedPlanBudgetRecord,
+    DecaySchedule,
+)
+from agentinputlab.contracts import ArtifactError, ExternalDependencyError, ValidationError
+
+PAB_NATIVE_PROMPT_MODE = "source_pinned_weighted_prompt.v1"
+PAB_SOURCE_HASHES = {
+    "inference/_5_planned_local_weighted_model.py":
+        "c4463d2a4e14882d4ff2b060b7b9cc9a93ecc7732ace5814dc72f1432c62c5ed",
+    "utils/utils.py":
+        "9c448f585251e94302e47c0c87ca61861dc5069d6255d7e106d28c4ca6610fc7",
+}
+_FUNCTIONS = {
+    "allocate_tokens", "constant_schedule", "linear_decay", "polynomial_decay",
+    "exponential_decay", "cosine_anneal",
+}
+_SCHEDULES = {
+    "constant": "constant_schedule", "linear": "linear_decay",
+    "polynomial": "polynomial_decay", "exponential": "exponential_decay",
+    "cosine": "cosine_anneal",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class PlanBudgetPromptRequest:
+    record: CachedPlanBudgetRecord
+    instruction: str
+    reference: str
+    output_format: str
+    schedule: str
+
+    def __post_init__(self):
+        if not isinstance(self.record, CachedPlanBudgetRecord):
+            raise ValidationError("P&B prompt requires a solver-only cached record")
+        if not all(isinstance(x, str) for x in (self.instruction, self.reference)):
+            raise ValidationError("P&B instruction/reference must be strings")
+        if not isinstance(self.output_format, str) or not self.output_format.strip():
+            raise ValidationError("P&B requires an explicit output format")
+        object.__setattr__(self, "schedule", DecaySchedule.parse(self.schedule).value)
+
+
+class _PromptBoundary(Exception):
+    def __init__(self, messages):
+        self.messages = messages
+
+
+class PlanAndBudgetNativePromptRuntime:
+    """Execute the hash-pinned native reasoning prefix up to its provider call.
+
+    This runtime does not call a model, return a fake response, execute a source
+    evaluator, or load the source module's environment/credentials. Source assets
+    and NumPy are explicit optional dependencies; nothing is downloaded here.
+    """
+
+    worker_id = "agentinputlab.plan-and-budget.native-prompt.v1"
+
+    def __init__(self, *, source_root: str | Path):
+        self.source_root = Path(source_root).expanduser().resolve()
+
+    def _sources(self):
+        sources = {}
+        for name, expected in PAB_SOURCE_HASHES.items():
+            path = self.source_root / name
+            try:
+                if path.stat().st_size > 128 * 1024:
+                    raise ArtifactError("P&B native source exceeds the size limit")
+                raw = path.read_bytes()
+            except OSError as exc:
+                raise ArtifactError(f"P&B native source unavailable: {name}") from exc
+            if hashlib.sha256(raw).hexdigest() != expected:
+                raise ArtifactError(f"P&B native source SHA-256 differs: {name}")
+            sources[name] = raw.decode("utf-8")
+        return sources
+
+    def fingerprint(self):
+        self._sources()
+        try:
+            numpy = importlib.import_module("numpy")
+        except ImportError as exc:
+            raise ExternalDependencyError(
+                "P&B native solver requires agentinputlab[plan-and-budget]"
+            ) from exc
+        return {
+            "runtime_id": self.worker_id,
+            "upstream_revision": P_AND_B_UPSTREAM_REVISION,
+            "source_sha256": dict(PAB_SOURCE_HASHES),
+            "numpy_version": numpy.__version__,
+            "binding_mode": PAB_NATIVE_PROMPT_MODE,
+            "model_calls": 0,
+            "native_retry_decorator": "removed_at_explicit_provider_boundary",
+            "provider_binding": "caller_observed_chat_backend",
+        }
+
+    def run(self, request: PlanBudgetPromptRequest):
+        if not isinstance(request, PlanBudgetPromptRequest):
+            raise ValidationError("P&B native prompt requires PlanBudgetPromptRequest")
+        identity = self.fingerprint()
+        sources = self._sources()
+        source = ast.parse(sources["inference/_5_planned_local_weighted_model.py"])
+        helpers = [n for n in source.body if isinstance(n, ast.FunctionDef)
+                   and n.name in _FUNCTIONS]
+        native_class = next(n for n in source.body if isinstance(n, ast.ClassDef)
+                            and n.name == "PlannedLocalWeighted_Model")
+        prompt = next(n for n in native_class.body if isinstance(n, ast.Assign)
+                      and any(isinstance(t, ast.Name) and t.id == "_prompt"
+                              for t in n.targets))
+        reasoning = copy.deepcopy(next(
+            n for n in native_class.body if isinstance(n, ast.AsyncFunctionDef)
+            and n.name == "reasoning"
+        ))
+        # The source body is unchanged. Do not import or invoke its ten-attempt
+        # retry decorator around a boundary that may already have spent tokens.
+        reasoning.decorator_list = []
+        utility = ast.parse(sources["utils/utils.py"])
+        level_map = ast.literal_eval(next(
+            n.value for n in utility.body if isinstance(n, ast.Assign)
+            and any(isinstance(t, ast.Name) and t.id == "level_map" for t in n.targets)
+        ))
+        logger = SimpleNamespace(debug=lambda *_args: None)
+
+        async def capture(messages, *, logger, return_raw):
+            del logger
+            if return_raw is not True:
+                raise ArtifactError("P&B native provider boundary differs")
+            raise _PromptBoundary(messages)
+
+        namespace = {
+            "np": importlib.import_module("numpy"), "textwrap": textwrap,
+            "Query": SimpleNamespace, "level_map": level_map, "logger": logger,
+            "MODEL_NAME": "agentinputlab-controlled-chat",
+            "COMPLETION_LLM": set(), "REASONING_LLM": set(),
+            "CHAT_LLM": {"agentinputlab-controlled-chat"}, "generate_response": capture,
+        }
+        nodes = [*helpers, prompt, reasoning]
+        exec(compile(ast.Module(body=nodes, type_ignores=[]),
+                     "pinned-p-and-b-reasoning-prefix", "exec"), namespace)
+        instance = SimpleNamespace(
+            _prompt=namespace["_prompt"], instruction=request.instruction,
+            output_format=request.output_format, decay=request.schedule, logger=logger,
+        )
+        record = request.record
+        query = SimpleNamespace(description=record.query, reference=request.reference,
+                                steps=list(record.steps), credits=list(record.credits),
+                                level=record.level)
+        coroutine = namespace["reasoning"](instance, query)
+        try:
+            # capture() has no await/yield: this enters the genuine native prefix
+            # and stops at its first provider call, without an asyncio event loop.
+            coroutine.send(None)
+        except _PromptBoundary as boundary:
+            messages = boundary.messages
+        else:  # pragma: no cover - fixed source invariant
+            raise ArtifactError("P&B native reasoning did not reach its provider boundary")
+        finally:
+            coroutine.close()
+        total_words = level_map[record.level][1]
+        allocations = tuple(int(x) for x in namespace["allocate_tokens"](
+            record.credits, total_words, namespace[_SCHEDULES[request.schedule]]
+        ))
+        return {
+            "messages": messages, "allocations": allocations,
+            "soft_word_budget": total_words, "identity": identity,
+            "usage": {"model_calls": 0, "retrieval_calls": 0,
+                      "input_tokens": 0, "output_tokens": 0},
+        }
+
+
+__all__ = ["PlanAndBudgetNativePromptRuntime", "PlanBudgetPromptRequest"]

agentinputlab/integrations/live_history.py

@@ -0,0 +1,222 @@
+"""ACON history at real agent user-turn boundaries with a shared run budget.
+
+The native environment remains authoritative. Only the agent-visible message
+view is compressed; tool databases, simulator state and evaluator data never
+enter this adapter. Tool calls/results are serialized for the text optimizer
+but preserved verbatim whenever retained in the downstream protocol.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from typing import Any
+
+from agentinputlab.contracts import ContextBlock, ExecutionBudget, FrozenAgentState, Message
+from agentinputlab.contracts.errors import ValidationError
+from agentinputlab.contracts.serialization import content_hash, to_jsonable
+from agentinputlab.observability import RunMonitor
+from agentinputlab.runner import InterventionRunner
+
+
+class NativeHistoryInputError(ValidationError):
+    """A native input cannot enter this history interface, before worker/model IO.
+
+    ``code`` is stable for caller-side routing. It does not classify a model
+    outcome or make an entire benchmark inapplicable. No message content is
+    included in the error metadata.
+    """
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+def validate_native_history_prefix(messages, *, prefix_policy="strict_system_user") -> int:
+    """Validate native prefix framing without constructing a worker or model.
+
+    Return the original first-user index. This check neither inserts a system
+    frame nor validates/compresses subsequent tool episodes; the native protocol
+    adapter remains responsible for their complete roundtrip.
+    """
+    if not isinstance(prefix_policy, str) or prefix_policy not in {
+            "strict_system_user", "preserve_pre_user_assistant"}:
+        raise NativeHistoryInputError("unknown_prefix_policy", "unknown native history prefix policy")
+    if (not isinstance(messages, Sequence) or isinstance(messages, (str, bytes))
+            or any(not isinstance(row, Mapping) for row in messages)):
+        raise NativeHistoryInputError("invalid_message_sequence", "native history requires a message sequence")
+    missing = "live ACON requires the native session to start with system then user"
+    if len(messages) < 2 or messages[0].get("role") != "system":
+        raise NativeHistoryInputError("native_system_user_boundary_missing", missing)
+    if messages[1].get("role") == "user":
+        return 1
+    if prefix_policy != "preserve_pre_user_assistant":
+        raise NativeHistoryInputError("native_system_user_boundary_missing", missing)
+    first_user = next((i for i, row in enumerate(messages) if row.get("role") == "user"), None)
+    if first_user is None:
+        raise NativeHistoryInputError("native_first_user_missing", "native greeting prefix has no first user")
+    prefix = messages[1:first_user]
+    if not prefix or any(row.get("role") != "assistant"
+            or not isinstance(row.get("content"), str) or not row["content"].strip()
+            or row.get("tool_calls") or row.get("function_call") for row in prefix):
+        raise NativeHistoryInputError("native_greeting_prefix_unsupported",
+                                     "native pre-user prefix must contain only plain assistant greetings")
+    return first_user
+
+
+def _view(message: Mapping[str, Any]) -> Message:
+    role = message.get("role")
+    if not isinstance(role, str) or not role:
+        raise ValidationError("native history message has no role")
+    content = message.get("content")
+    if message.get("tool_calls") or role in {"tool", "function"}:
+        # Upstream MemoryManager consumes USER/ASSISTANT text. Preserve tool
+        # observations as explicit text in that view, never as hidden metadata.
+        from agentinputlab.contracts.serialization import canonical_json
+        content = canonical_json(dict(message))
+        role = "assistant"
+    if not isinstance(content, str):
+        raise ValidationError("native text history message has no string content")
+    return Message(role=role, content=content, name=message.get("name"))
+
+
+def _balanced_tool_frames(messages: Sequence[Mapping[str, Any]]) -> bool:
+    pending = set()
+    for message in messages:
+        if message.get("function_call") or message.get("role") == "function":
+            return False  # legacy function framing needs its own explicit adapter
+        calls = message.get("tool_calls") or []
+        if calls:
+            if pending:
+                return False
+            pending = {call.get("id") for call in calls}
+            if None in pending or len(pending) != len(calls):
+                return False
+        elif message.get("role") == "tool":
+            identifier = message.get("tool_call_id")
+            if identifier not in pending:
+                return False
+            pending.remove(identifier)
+        elif pending:
+            return False
+    return not pending
+
+
+class ACONLiveHistory:
+    """One instance per native episode; keep metadata and causal history across turns.
+
+    The context must bind the real optimizer and native worker. A downstream
+    call and its per-call output allowance are reserved before any optimizer
+    request. Initial, intra-tool-turn and insufficient-budget branches do not
+    consume optimizer calls. Genuine optimizer failures propagate, never become
+    successful NO_OPs. ``records`` retains every decision and observed usage.
+    """
+
+    def __init__(self, method, context, *, per_call_output_tokens: int = 512,
+                 prefix_policy: str = "strict_system_user"):
+        if method.release_id != "curate.acon.history_runtime":
+            raise ValidationError("live ACON history requires the exact history runtime release")
+        if type(per_call_output_tokens) is not int or per_call_output_tokens < 1:
+            raise ValidationError("per-call history output allowance must be positive")
+        if not isinstance(prefix_policy, str) or prefix_policy not in {
+                "strict_system_user", "preserve_pre_user_assistant"}:
+            raise ValidationError("unknown native history prefix policy")
+        self.method, self.context = method, context
+        self.per_call_output_tokens = per_call_output_tokens
+        self.prefix_policy = prefix_policy
+        self.records: list[dict] = []
+        self._raw: list[dict] = []
+        self._logical: list[dict] = []
+        self._metadata: dict = {}
+
+    def fingerprint(self) -> dict:
+        fingerprint = {"release": self.method.release_id, "integration": "acon.native_user_boundary.v2",
+                "per_call_output_tokens": self.per_call_output_tokens,
+                "optimizer_tokenizer": "source-native-bound-not-target-approximation",
+                "agent_tool_frames_preserved": True,
+                "worker": dict(self.context.external_runtime.fingerprint())}
+        if self.prefix_policy != "strict_system_user":
+            fingerprint["prefix_policy"] = self.prefix_policy
+        return to_jsonable(fingerprint)
+
+    def _native_optimizer_view(self, logical):
+        """Keep a declared native greeting immutable, outside the optimizer view.
+
+        No message is invented, moved or dropped from the downstream wire.
+        The native optimizer still receives its original system/user framing;
+        only plain assistant greetings preceding the first user are excluded
+        from that mutable view and reinserted verbatim after materialization.
+        """
+        first_user = validate_native_history_prefix(logical, prefix_policy=self.prefix_policy)
+        if first_user == 1:
+            return logical, []
+        prefix = logical[1:first_user]
+        return [logical[0], *logical[first_user:]], deepcopy(prefix)
+
+    def transform(self, messages, *, state, remaining_budget):
+        raw = deepcopy(list(messages))
+        if self._raw and (len(raw) < len(self._raw) or raw[:len(self._raw)] != self._raw):
+            raise ValidationError("native history changed before its append-only boundary")
+        logical = deepcopy(self._logical) + raw[len(self._raw):] if self._raw else deepcopy(raw)
+        native_logical, immutable_prefix = self._native_optimizer_view(logical)
+        initial = {"input_raw_hash": content_hash(raw), "input_logical_hash": content_hash(logical),
+                   "remaining_budget": dict(remaining_budget)}
+        if immutable_prefix:
+            initial.update(prefix_policy=self.prefix_policy,
+                           immutable_native_prefix_hash=content_hash(immutable_prefix),
+                           immutable_native_prefix_length=len(immutable_prefix))
+        reason = None
+        if logical[-1].get("role") != "user":
+            reason = "intra_user_turn_tool_protocol_preserved"
+        elif (remaining_budget["max_model_calls"] < 2
+              or remaining_budget["max_output_tokens"] < 2 * self.per_call_output_tokens):
+            reason = "downstream_call_and_output_reserved"
+        if reason:
+            self._raw, self._logical = raw, logical
+            record = {**initial, "status": "integration_skip", "reason": reason,
+                      "usage": {"model_calls": 0, "output_tokens": 0}}
+            self.records.append(record)
+            return {"messages": deepcopy(logical), "usage": dict(record["usage"])}
+        view = tuple(_view(message) for message in native_logical)
+        # Reject protocol-orphaning assembly before the optimizer has side effects.
+        from agentinputlab.algorithms.curate.acon.common import preserved_turn_indices
+        indices = preserved_turn_indices(view, self.method.controls.preserve_last_k_turns)
+        candidate_tail = [native_logical[index] for index in indices]
+        if not _balanced_tool_frames(candidate_tail):
+            self._raw, self._logical = raw, logical
+            record = {**initial, "status": "integration_skip", "reason": "preserved_tail_has_unpaired_tool_frames",
+                      "usage": {"model_calls": 0, "output_tokens": 0}}
+            self.records.append(record)
+            return {"messages": deepcopy(logical), "usage": dict(record["usage"])}
+        frozen = FrozenAgentState(
+            query=state["query"], instruction=state.get("instruction", ""),
+            task_id=state.get("task_id", ""), messages=view,
+            context=tuple(ContextBlock(**block) for block in state.get("context", [])),
+            tool_names=tuple(state.get("tool_names", [])),
+            metadata={**state.get("metadata", {}), **self._metadata},
+            budget=ExecutionBudget(max_model_calls=remaining_budget["max_model_calls"] - 1,
+                                   max_output_tokens=remaining_budget["max_output_tokens"] - self.per_call_output_tokens))
+        monitor = RunMonitor()
+        try:
+            result = InterventionRunner(monitor=monitor).run(self.method, frozen, self.context)
+        except Exception as exc:
+            self.records.append({**initial, "status": "failed_terminal", "error_type": type(exc).__name__,
+                                 "error": str(exc), "monitor_snapshots": to_jsonable(monitor.list_snapshots())})
+            raise
+        patched = result.patch.apply(frozen)
+        if result.patch.metadata.get("applied"):
+            if tuple(patched.messages[2:]) != tuple(view[index] for index in indices):
+                raise ValidationError("ACON preserved messages differ from source-bound indices")
+            materialized = [dict(native_logical[0], content=patched.messages[0].content),
+                            *deepcopy(immutable_prefix),
+                            dict(native_logical[1], content=patched.messages[1].content), *deepcopy(candidate_tail)]
+        else:
+            materialized = logical
+        if not _balanced_tool_frames(materialized):
+            raise ValidationError("ACON materialization would orphan a native tool call")
+        self._metadata = {key: value for key, value in patched.metadata.items() if key.startswith("acon_")}
+        self._raw, self._logical = raw, materialized
+        usage = to_jsonable(result.usage)
+        self.records.append({**initial, "status": "applied" if result.patch.metadata.get("applied") else "native_threshold_skip",
+                             "output_logical_hash": content_hash(materialized), "usage": usage,
+                             "intervention": to_jsonable(result)})
+        return {"messages": deepcopy(materialized), "usage": dict(usage)}

agentinputlab/integrations/prompt_optimization/__init__.py

@@ -0,0 +1 @@
+"""Optional tuning and context-evolution integrations."""

agentinputlab/integrations/training/__init__.py

@@ -0,0 +1 @@
+"""Training recipes and checkpoint-producing integrations."""