agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/algorithms/acquire/hyde.py

@@ -0,0 +1,296 @@
+"""Clean-room HyDE formula with injectable generation, embedding, and search.
+
+This module implements the formula described in the HyDE paper rather than
+copying the unlicensed upstream source.  Hypothetical documents are query
+surrogates only.  Only documents returned by the injected corpus searcher are
+materialized as evidence.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from agentinputlab.backends.llm import GenerationRequest, LLMBackend
+from agentinputlab.backends.retrieval import RetrievalResult
+from agentinputlab.backends.vector import DenseEmbedder, VectorSearcher
+from agentinputlab.contracts import (
+    AlgorithmOutputError,
+    ContextBlock,
+    ExecutionTrace,
+    ExternalDependencyError,
+    FrozenAgentState,
+    InputPatch,
+    InterventionContext,
+    PatchOp,
+    PatchOperation,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+
+Vector = tuple[float, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class HyDEConfig:
+    num_hypotheses: int = 8
+    max_tokens: int = 512
+    temperature: float = 0.7
+    top_k: int = 5
+    prompt_template: str = (
+        "Write a passage that would answer the question. "
+        "The passage should be factual and self-contained.\n\n"
+        "Question: {query}\n\nPassage:"
+    )
+
+    def __post_init__(self) -> None:
+        for name in ("num_hypotheses", "max_tokens", "top_k"):
+            value = getattr(self, name)
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise ValidationError(f"HyDE {name} must be a positive integer")
+        if (
+            isinstance(self.temperature, bool)
+            or not isinstance(self.temperature, (int, float))
+            or not math.isfinite(self.temperature)
+            or self.temperature < 0
+        ):
+            raise ValidationError("HyDE temperature must be finite and non-negative")
+        if not isinstance(self.prompt_template, str):
+            raise ValidationError("HyDE prompt_template must be text")
+        try:
+            self.prompt_template.format(query="probe")
+        except (KeyError, ValueError) as exc:
+            raise ValidationError(
+                "HyDE prompt_template must accept only the {query} field"
+            ) from exc
+
+
+@dataclass(slots=True)
+class HyDECleanRoom:
+    """Paper-formula implementation: mean(query, hypothetical-doc embeddings)."""
+
+    embedder: DenseEmbedder | None = None
+    searcher: VectorSearcher | None = None
+    generator: LLMBackend | None = None
+    config: HyDEConfig = HyDEConfig()
+    method_id: str = "hyde"
+    release_id: str = "acquire.hyde.paper_reimplementation"
+    family: SemanticFamily = SemanticFamily.ACQUIRE
+
+    def propose(self, state: FrozenAgentState, context: InterventionContext) -> InputPatch:
+        if not state.query.strip():
+            raise ValidationError("HyDE requires a non-empty retrieval query")
+        backend = self.generator or context.backend
+        if backend is None:
+            raise ExternalDependencyError("HyDE requires an injected LLM generation backend")
+        embedder = self.embedder or context.dense_embedder
+        searcher = self.searcher or context.vector_searcher
+        if not isinstance(embedder, DenseEmbedder):
+            raise ExternalDependencyError("HyDE requires an injected DenseEmbedder")
+        if not isinstance(searcher, VectorSearcher):
+            raise ExternalDependencyError("HyDE requires an injected VectorSearcher")
+
+        try:
+            prompt = self.config.prompt_template.format(query=state.query)
+        except (KeyError, ValueError) as exc:
+            raise ValidationError("invalid HyDE prompt template") from exc
+
+        hypotheses: list[str] = []
+        empty_generations: list[int] = []
+        for index in range(self.config.num_hypotheses):
+            response = backend.generate(
+                GenerationRequest(
+                    prompt=prompt,
+                    temperature=self.config.temperature,
+                    max_tokens=self.config.max_tokens,
+                    seed=context.seed + index,
+                    metadata={
+                        "method_id": self.method_id,
+                        "release_id": self.release_id,
+                        "hypothesis_index": index,
+                    },
+                )
+            )
+            if not isinstance(response.text, str):
+                raise AlgorithmOutputError("HyDE generator returned a non-text response")
+            text = response.text.strip()
+            if text:
+                hypotheses.append(text)
+            else:
+                empty_generations.append(index)
+        if not hypotheses:
+            raise AlgorithmOutputError("HyDE generator returned no usable hypothetical documents")
+
+        encoded = embedder.embed((state.query, *hypotheses))
+        vectors = _validate_vectors(encoded, expected_count=1 + len(hypotheses))
+        mean_vector = _arithmetic_mean(vectors)
+        results = _validate_results(
+            searcher.search(mean_vector, top_k=self.config.top_k),
+            top_k=self.config.top_k,
+        )
+        if not results:
+            raise AlgorithmOutputError("HyDE vector search returned no corpus documents")
+
+        evidence = tuple(_context_from_result(result) for result in results)
+        warnings = (f"empty_hypothesis_indices={empty_generations}",) if empty_generations else ()
+        trace = ExecutionTrace(
+            method_id=self.method_id,
+            release_id=self.release_id,
+            events=(
+                TraceEvent(
+                    TracePhase.PREPARE,
+                    "hyde_config",
+                    {
+                        "num_hypotheses": self.config.num_hypotheses,
+                        "temperature": self.config.temperature,
+                        "max_tokens": self.config.max_tokens,
+                        "top_k": self.config.top_k,
+                    },
+                ),
+                TraceEvent(
+                    TracePhase.PROPOSE,
+                    "hypothetical_documents",
+                    {
+                        "documents": tuple(hypotheses),
+                        "semantic_role": "synthetic_query_surrogate",
+                        "empty_generation_indices": tuple(empty_generations),
+                    },
+                ),
+                TraceEvent(
+                    TracePhase.OBSERVE,
+                    "mean_embedding",
+                    {
+                        "vector_count": len(vectors),
+                        "dimension": len(mean_vector),
+                        "mean_vector": mean_vector,
+                    },
+                ),
+                TraceEvent(
+                    TracePhase.FINALIZE,
+                    "real_corpus_results",
+                    {
+                        "document_ids": tuple(item.document.doc_id for item in results),
+                        "ranks": tuple(item.rank for item in results),
+                    },
+                ),
+            ),
+            counters={
+                "model_calls": self.config.num_hypotheses,
+                "hypotheses_used": len(hypotheses),
+                "embedding_calls": 1,
+                "retrieval_calls": 1,
+            },
+            warnings=warnings,
+        )
+        return InputPatch(
+            method_id=self.method_id,
+            release_id=self.release_id,
+            source_state_hash=state.state_hash,
+            operations=(
+                PatchOperation(
+                    PatchOp.ADD_CONTEXT,
+                    evidence,
+                    target="retrieved_evidence",
+                    rationale="real documents retrieved with the HyDE mean embedding",
+                ),
+            ),
+            trace=trace,
+            implementation_identity="clean_room_paper_formula",
+            profile_kind="controlled_adapter",
+            metadata={
+                "synthetic_documents_are_evidence": False,
+                "generator_fingerprint": dict(backend.fingerprint()),
+                "embedder_fingerprint": dict(embedder.fingerprint()),
+                "searcher_fingerprint": dict(searcher.fingerprint()),
+            },
+        )
+
+
+def _validate_vectors(
+    encoded: Sequence[Sequence[float]], *, expected_count: int
+) -> tuple[Vector, ...]:
+    try:
+        vectors = tuple(tuple(float(value) for value in row) for row in encoded)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise AlgorithmOutputError("HyDE embedder returned non-numeric vectors") from exc
+    if len(vectors) != expected_count:
+        raise AlgorithmOutputError(
+            f"HyDE embedder returned {len(vectors)} vectors; expected {expected_count}"
+        )
+    if not vectors or not vectors[0]:
+        raise AlgorithmOutputError("HyDE embeddings must have a non-zero dimension")
+    dimension = len(vectors[0])
+    for vector in vectors:
+        if len(vector) != dimension:
+            raise AlgorithmOutputError("HyDE embeddings have inconsistent dimensions")
+        if not all(math.isfinite(value) for value in vector):
+            raise AlgorithmOutputError("HyDE embeddings must contain only finite values")
+    return vectors
+
+
+def _arithmetic_mean(vectors: Sequence[Vector]) -> Vector:
+    return tuple(
+        sum(vector[index] for vector in vectors) / len(vectors) for index in range(len(vectors[0]))
+    )
+
+
+def _validate_results(
+    values: Sequence[RetrievalResult],
+    *,
+    top_k: int,
+) -> tuple[RetrievalResult, ...]:
+    try:
+        results = tuple(values)
+    except TypeError as exc:
+        raise AlgorithmOutputError("HyDE searcher returned a non-sequence result") from exc
+    if not all(isinstance(item, RetrievalResult) for item in results):
+        raise AlgorithmOutputError("HyDE searcher returned a non-RetrievalResult item")
+    if len(results) > top_k:
+        raise AlgorithmOutputError("HyDE searcher returned more than top_k documents")
+    document_ids = [item.document.doc_id for item in results]
+    if len(document_ids) != len(set(document_ids)):
+        raise AlgorithmOutputError("HyDE searcher returned duplicate document IDs")
+    if tuple(item.rank for item in results) != tuple(range(1, len(results) + 1)):
+        raise AlgorithmOutputError("HyDE searcher ranks must be contiguous and one-based")
+    if not all(math.isfinite(item.score) for item in results):
+        raise AlgorithmOutputError("HyDE search scores must be finite")
+    return results
+
+
+def _context_from_result(result: RetrievalResult) -> ContextBlock:
+    document = result.document
+    if not document.doc_id or not document.corpus_revision:
+        raise AlgorithmOutputError(
+            "HyDE search results require document ID and corpus revision provenance"
+        )
+    reserved = {
+        "corpus_revision",
+        "document_id",
+        "evidence_kind",
+        "rank",
+        "retrieval_features",
+        "title",
+    }
+    overlap = reserved & set(document.metadata)
+    if overlap:
+        raise AlgorithmOutputError(
+            "HyDE document metadata uses reserved provenance keys: " + ", ".join(sorted(overlap))
+        )
+    return ContextBlock(
+        block_id=document.doc_id,
+        text=document.text,
+        source=document.source if hasattr(document, "source") else document.corpus_revision,
+        score=result.score,
+        metadata={
+            **dict(document.metadata),
+            "document_id": document.doc_id,
+            "title": document.title,
+            "corpus_revision": document.corpus_revision,
+            "rank": result.rank,
+            "retrieval_features": dict(result.features),
+            "evidence_kind": "real_corpus_document",
+        },
+    )

agentinputlab/algorithms/acquire/hyde_controlled.py

@@ -0,0 +1,200 @@
+"""Dependency-locked public HyDE profile using the unchanged clean-room formula.
+
+Only immutable data is retained on the intervention. Executable dependencies
+come from the runner's instrumented context, so generation, embedding and search
+remain observable and budgeted. Fingerprint equality is an operator identity
+binding, not independent verification of model weights or benchmark parity.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any
+
+from agentinputlab.contracts import (
+    ExecutionBudget,
+    ExternalDependencyError,
+    FrozenAgentState,
+    InputPatch,
+    InterventionContext,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping
+
+from .hyde import HyDECleanRoom, HyDEConfig
+
+_DEFAULT_CONFIG = HyDEConfig()
+
+
+def _identity(value: Any, *, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or not value:
+        raise ValidationError(f"HyDE {label} fingerprint must be a non-empty mapping")
+    try:
+        result = freeze_mapping(value)
+        content_hash(result)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise ValidationError(f"HyDE {label} fingerprint must be finite canonical JSON") from exc
+    return result
+
+
+def _context_identities(context: InterventionContext) -> dict[str, Mapping[str, Any]]:
+    identities = {}
+    for label, dependency, operation in (
+        ("generator", context.backend, "generate"),
+        ("embedder", context.dense_embedder, "embed"),
+        ("searcher", context.vector_searcher, "search"),
+    ):
+        fingerprint = getattr(dependency, "fingerprint", None)
+        if not callable(fingerprint) or not callable(getattr(dependency, operation, None)):
+            raise ExternalDependencyError(
+                f"controlled HyDE requires context {label} with {operation}() and fingerprint()"
+            )
+        identities[label] = _identity(fingerprint(), label=label)
+    return identities
+
+
+@dataclass(frozen=True, slots=True)
+class HyDEControlledBindings:
+    """Freeze shared runtime identities, method settings and resource ceilings.
+
+    Supply reviewed fingerprints explicitly or capture them before dispatch with
+    ``from_context``. The latter records the caller's current dependencies; it
+    does not independently certify those dependencies or freeze their internals.
+    A changed fingerprint is rejected both before and after execution.
+    """
+
+    generator: Mapping[str, Any]
+    embedder: Mapping[str, Any]
+    searcher: Mapping[str, Any]
+    budget: ExecutionBudget
+    config: HyDEConfig = _DEFAULT_CONFIG
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.budget, ExecutionBudget):
+            raise ValidationError("controlled HyDE bindings require an ExecutionBudget")
+        if not isinstance(self.config, HyDEConfig):
+            raise ValidationError("controlled HyDE bindings require a HyDEConfig")
+        for name in ("generator", "embedder", "searcher"):
+            object.__setattr__(self, name, _identity(getattr(self, name), label=name))
+
+    @classmethod
+    def from_context(
+        cls,
+        context: InterventionContext,
+        *,
+        budget: ExecutionBudget,
+        config: HyDEConfig = _DEFAULT_CONFIG,
+    ) -> HyDEControlledBindings:
+        """Capture identities without generating, embedding, searching or downloading."""
+
+        if not isinstance(context, InterventionContext):
+            raise ValidationError("controlled HyDE requires an InterventionContext")
+        return cls(**_context_identities(context), budget=budget, config=config)
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> HyDEControlledBindings:
+        """Read a data-only construction recipe for the registry/CLI builder."""
+
+        required = {"generator", "embedder", "searcher", "budget"}
+        if not isinstance(value, Mapping) or not required.issubset(value):
+            raise ValidationError("controlled HyDE binding recipe is missing required fields")
+        if set(value) - required - {"config"}:
+            raise ValidationError("controlled HyDE binding recipe contains unknown fields")
+        if not isinstance(value["budget"], Mapping) or not isinstance(
+            value.get("config", {}), Mapping
+        ):
+            raise ValidationError("controlled HyDE budget and config recipes must be mappings")
+        try:
+            return cls(
+                generator=value["generator"],
+                embedder=value["embedder"],
+                searcher=value["searcher"],
+                budget=ExecutionBudget(**value["budget"]),
+                config=HyDEConfig(**value.get("config", {})),
+            )
+        except TypeError as exc:
+            raise ValidationError("controlled HyDE recipe has invalid setting fields") from exc
+
+    @property
+    def binding_hash(self) -> str:
+        return content_hash(self)
+
+    def require_match(self, context: InterventionContext) -> None:
+        for name, actual in _context_identities(context).items():
+            if content_hash(actual) != content_hash(getattr(self, name)):
+                raise ValidationError(f"controlled HyDE {name} fingerprint differs from binding")
+
+
+@dataclass(frozen=True, slots=True)
+class HyDEControlled:
+    """Run genuine HyDE under explicit shared dependencies and fixed settings.
+
+    ``factorial_adapter`` labels a caller-controlled configuration; it is not
+    proof of experimental comparability or original-paper result parity.
+    """
+
+    bindings: HyDEControlledBindings | Mapping[str, Any]
+    profile_kind: str = "controlled_adapter"
+    method_id: str = "hyde"
+    release_id: str = "acquire.hyde.controlled"
+    family: SemanticFamily = SemanticFamily.ACQUIRE
+
+    def __post_init__(self) -> None:
+        if isinstance(self.bindings, Mapping):
+            object.__setattr__(self, "bindings", HyDEControlledBindings.from_mapping(self.bindings))
+        if not isinstance(self.bindings, HyDEControlledBindings):
+            raise ValidationError("controlled HyDE requires HyDEControlledBindings")
+        if self.profile_kind not in {"controlled_adapter", "factorial_adapter"}:
+            raise ValidationError("controlled HyDE profile_kind must be controlled or factorial")
+        if (
+            self.method_id != "hyde"
+            or self.release_id != "acquire.hyde.controlled"
+            or self.family is not SemanticFamily.ACQUIRE
+        ):
+            raise ValidationError("controlled HyDE identity differs from its registered profile")
+
+    def propose(self, state: FrozenAgentState, context: InterventionContext) -> InputPatch:
+        if state.budget != self.bindings.budget:
+            raise ValidationError("controlled HyDE state budget differs from binding")
+        self.bindings.require_match(context)
+        patch = HyDECleanRoom(
+            config=self.bindings.config,
+            method_id=self.method_id,
+            release_id=self.release_id,
+            family=self.family,
+        ).propose(state, context)
+        self.bindings.require_match(context)
+        return replace(
+            patch,
+            profile_kind=self.profile_kind,
+            trace=replace(
+                patch.trace,
+                events=(
+                    TraceEvent(
+                        TracePhase.PREPARE,
+                        "controlled_dependency_binding",
+                        {
+                            "binding_hash": self.bindings.binding_hash,
+                            "budget": self.bindings.budget,
+                            "config": self.bindings.config,
+                            "identity_verification": "operator_fingerprint_equality",
+                        },
+                    ),
+                    *patch.trace.events,
+                ),
+            ),
+            metadata={
+                **patch.metadata,
+                "controlled_binding_sha256": self.bindings.binding_hash,
+                "dependency_identity_verification": "operator_fingerprint_equality",
+                "weight_files_verified_by_binding": False,
+                "original_paper_result_parity_claimed": False,
+            },
+        )
+
+
+__all__ = ["HyDEControlled", "HyDEControlledBindings"]

agentinputlab/algorithms/acquire/hyde_external.py

@@ -0,0 +1,148 @@
+"""Thin native-source HyDE wrapper; source, clients and weights are not vendored."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from agentinputlab.backends.llm import GenerationRequest, LLMBackend, ModelCapability
+from agentinputlab.backends.vector import DenseEmbedder, VectorSearcher
+from agentinputlab.contracts import (
+    ArtifactError,
+    ExecutionTrace,
+    ExternalDependencyError,
+    FrozenAgentState,
+    InputPatch,
+    InterventionContext,
+    PatchOp,
+    PatchOperation,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping
+from agentinputlab.integrations.full_architecture.hyde import (
+    HYDE_PATCH_PROTOCOL,
+    HYDE_UPSTREAM_REVISION,
+    HyDEPatchedExecutionRequest,
+)
+
+from .hyde import _context_from_result, _validate_results, _validate_vectors
+
+HYDE_EXTERNAL_RELEASE="acquire.hyde.official_external_patched"
+_TASKS={"web search","scifact","arguana","trec-covid","fiqa","dbpedia-entity","trec-news","mr-tydi"}
+
+
+@dataclass(frozen=True,slots=True)
+class HyDENativeConfig:
+    task: str="web search"
+    language: str="en"
+    num_hypotheses: int=8
+    max_tokens: int=512
+    temperature: float=0.7
+    top_k: int=10
+    stop: tuple[str,...]=("\n\n\n",)
+
+    def __post_init__(self):
+        if not isinstance(self.task,str) or self.task not in _TASKS or not isinstance(self.language,str) or not self.language.strip():
+            raise ValidationError("HyDE native promptor task/language is invalid")
+        for value in (self.num_hypotheses,self.max_tokens,self.top_k):
+            if type(value) is not int or value<1:
+                raise ValidationError("HyDE draw count/output cap/top_k must be positive integers")
+        if isinstance(self.stop,(str,bytes)):
+            raise ValidationError("HyDE stop must be a sequence of stop strings")
+        object.__setattr__(self,"stop",tuple(self.stop))
+        GenerationRequest(prompt="configuration",max_tokens=self.max_tokens,temperature=self.temperature,stop=self.stop)
+
+
+def _identities(context):
+    values={}
+    for name,obj in (("generator",context.backend),("embedder",context.dense_embedder),
+                     ("searcher",context.vector_searcher),("native_runtime",context.external_runtime)):
+        if obj is None or not callable(getattr(obj,"fingerprint",None)):
+            raise ExternalDependencyError(f"HyDE external profile requires context {name}")
+        raw=obj.fingerprint()
+        if not isinstance(raw,Mapping) or not raw:
+            raise ArtifactError("HyDE external dependency fingerprint must be nonempty")
+        try:
+            values[name]=freeze_mapping(raw)
+            content_hash(values[name])
+        except (TypeError,ValueError) as exc:
+            raise ArtifactError("HyDE external dependency fingerprint must be canonical finite data") from exc
+    return values
+
+
+@dataclass(frozen=True,slots=True)
+class HyDEOfficialExternalPatched:
+    config: HyDENativeConfig | Mapping[str,Any]=HyDENativeConfig()
+    method_id: str="hyde"
+    release_id: str=HYDE_EXTERNAL_RELEASE
+    family: SemanticFamily=SemanticFamily.ACQUIRE
+
+    def __post_init__(self):
+        if isinstance(self.config,Mapping):
+            try:
+                object.__setattr__(self,"config",HyDENativeConfig(**self.config))
+            except TypeError as exc:
+                raise ValidationError("HyDE external configuration has unknown fields") from exc
+        if not isinstance(self.config,HyDENativeConfig):
+            raise ValidationError("HyDE external profile requires HyDENativeConfig")
+        if self.method_id!="hyde" or self.release_id!=HYDE_EXTERNAL_RELEASE or self.family is not SemanticFamily.ACQUIRE:
+            raise ValidationError("HyDE external profile identity differs from registry")
+
+    def propose(self,state:FrozenAgentState,context:InterventionContext)->InputPatch:
+        if not state.query.strip():
+            raise ValidationError("HyDE requires a nonempty source query")
+        if not isinstance(context.backend,LLMBackend) or not {ModelCapability.CHAT,ModelCapability.COMPLETION}.intersection(context.backend.capabilities):
+            raise ExternalDependencyError("HyDE requires a chat or completion backend")
+        if not isinstance(context.dense_embedder,DenseEmbedder) or not isinstance(context.vector_searcher,VectorSearcher):
+            raise ExternalDependencyError("HyDE requires a dense embedder and corpus vector searcher")
+        identities=_identities(context)
+        native=identities["native_runtime"]
+        if native.get("binding_mode")!=HYDE_PATCH_PROTOCOL or native.get("upstream_revision")!=HYDE_UPSTREAM_REVISION:
+            raise ArtifactError("HyDE external runtime does not match reviewed source/patch protocol")
+        runtime=context.external_runtime
+        if not callable(getattr(runtime,"run",None)):
+            raise ExternalDependencyError("HyDE external runtime requires run()")
+        result=runtime.run(HyDEPatchedExecutionRequest(state.query,self.config,context.seed,state.budget,
+            context.backend,context.dense_embedder,context.vector_searcher))
+        if not isinstance(result,Mapping) or result.get("identity")!=native:
+            raise ArtifactError("HyDE runtime response identity differs")
+        if content_hash(_identities(context))!=content_hash(identities):
+            raise ArtifactError("HyDE dependency identities changed during execution")
+        hypotheses=result["hypotheses"]
+        if len(hypotheses)!=self.config.num_hypotheses or any(not isinstance(v,str) for v in hypotheses):
+            raise ArtifactError("HyDE runtime returned a different hypothesis inventory")
+        vectors=_validate_vectors(result["encoded_vectors"],expected_count=self.config.num_hypotheses+1)
+        mean=_validate_vectors((result["mean_vector"],),expected_count=1)[0]
+        expected=tuple(sum(v[i] for v in vectors)/len(vectors) for i in range(len(vectors[0])))
+        if len(mean)!=len(expected) or any(abs(a-b)>1e-10*max(1,abs(a),abs(b)) for a,b in zip(mean,expected,strict=True)):
+            raise ArtifactError("native patched HyDE did not average query plus every hypothesis")
+        hits=_validate_results(result["results"],top_k=self.config.top_k)
+        if not hits:
+            raise ArtifactError("native patched HyDE returned no real corpus hits")
+        return InputPatch(method_id=self.method_id,release_id=self.release_id,source_state_hash=state.state_hash,
+            operations=(PatchOperation(PatchOp.ADD_CONTEXT,tuple(_context_from_result(r) for r in hits),
+                target="retrieved_evidence",rationale="real corpus evidence from patched native HyDE"),),
+            trace=ExecutionTrace(method_id=self.method_id,release_id=self.release_id,
+                events=(TraceEvent(TracePhase.PREPARE,"external_source_patch",native),
+                    TraceEvent(TracePhase.PROPOSE,"native_hypotheses",{"documents":hypotheses,
+                        "prompt":result["native_prompt"],"draws":result["draws"],"empty_indices":tuple(i for i,h in enumerate(hypotheses) if not h.strip())}),
+                    TraceEvent(TracePhase.OBSERVE,"patched_native_mean",{"mean_vector":mean,"dimension":len(mean),"vector_count":len(vectors)}),
+                    TraceEvent(TracePhase.OBSERVE,"native_runtime_resources",{
+                        "wall_seconds":result["wall_seconds"],"cpu_seconds":result["calling_thread_cpu_seconds"],
+                        "cpu_measurement_is_diagnostic_not_additional_usage":True,
+                        "cpu_scope":result["usage_scope"],"process_cpu_seconds_window":result["process_cpu_seconds_window"],
+                        "process_cpu_windows_not_additive":True}),
+                    TraceEvent(TracePhase.FINALIZE,"real_corpus_hits",{"document_ids":tuple(r.document.doc_id for r in hits)})),
+                counters={name:result[name] for name in ("model_calls","embedding_calls","retrieval_calls","input_tokens","output_tokens")}),
+            implementation_identity=f"external_hyde@{HYDE_UPSTREAM_REVISION}:flatten_singleton_patch",
+            profile_kind="official_native",metadata={"runtime":native,"dependency_fingerprints":identities,
+                "source_algorithm_executed":True,"native_source_entrypoint":"HyDE.e2e_search",
+                "hypotheses_are_evidence":False,"native_empty_hypotheses_retained":True,
+                "original_generator_client_used":False,"generation_transport":"serial_observed_no_logprob_reordering",
+                "original_batch_sampling_or_paper_result_parity_claimed":False,"source_redistributed":False})
+
+
+__all__=["HYDE_EXTERNAL_RELEASE","HyDENativeConfig","HyDEOfficialExternalPatched"]

agentinputlab/algorithms/acquire/ircot.py

@@ -0,0 +1,28 @@
+"""Canonical import path for the IRCoT external-worker adapter."""
+
+from agentinputlab.integrations.external_workers.ircot import (
+    IRCOT_UPSTREAM_COMMIT,
+    IRCoTControlledWorker,
+    IRCoTControls,
+    IRCoTWorkerRequest,
+    IRCoTWorkerResponse,
+)
+
+from .ircot_common_support import (
+    IRCoTCommonSupport,
+    IRCoTCommonSupportConfig,
+    IRCoTCommonSupportResult,
+    IRCoTCommonSupportStep,
+)
+
+__all__ = [
+    "IRCOT_UPSTREAM_COMMIT",
+    "IRCoTCommonSupport",
+    "IRCoTCommonSupportConfig",
+    "IRCoTCommonSupportResult",
+    "IRCoTCommonSupportStep",
+    "IRCoTControlledWorker",
+    "IRCoTControls",
+    "IRCoTWorkerRequest",
+    "IRCoTWorkerResponse",
+]