agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/algorithms/reformulate/infocqr/student.py

@@ -0,0 +1,189 @@
+"""InfoCQR's trained T5 student, separate from its teacher and saved rewrites."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+
+from agentinputlab.contracts import (
+    AlgorithmOutputError,
+    ArtifactError,
+    BudgetExceededError,
+    ExecutionTrace,
+    ExternalDependencyError,
+    FrozenAgentState,
+    InputPatch,
+    InterventionContext,
+    PatchOp,
+    PatchOperation,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+from agentinputlab.contracts.serialization import content_hash
+from agentinputlab.observability import external_usage_counters, normalize_external_usage
+
+from .cache_replay import INFOCQR_UPSTREAM_COMMIT
+from .external import _qrecc_conversation
+
+INFOCQR_STUDENT_RELEASE = "rewrite.infocqr.t5_student_external"
+INFOCQR_STUDENT_MODE = "source_pinned_t5_student.v1"
+INFOCQR_STUDENT_SCHEMA = "agentinputlab.infocqr.student-request.v1"
+INFOCQR_STUDENT_SOURCE_HASHES = {
+    "T5QR/T5test.py": "c9c1b78d8147035ea3c300e7b29c791fb171ce399f8c1269a6e1a11b9bc05eb8",
+    "T5QR/T5train.py": "d40bc17e365d9f626fd5bf1fd14fffd3073c0b6772434a78eac6412d6fd2f4de",
+    "T5QR/utils/dataCollator.py": "3e4a466b1f729cba306b4953f1e825efde14316e83586c0952dc0e404a974d5d",
+    "T5QR/data_preprocessing.ipynb": "6a7dd60ed6f84d89d1313850732599b94e55889cdb694b00f7d2c42df97f0695",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class InfoCQRStudentRequest:
+    state_hash: str
+    task_id: str
+    query: str
+    conversation_source: str
+    conversation_no: int
+    turn_no: int
+    new_context: tuple[str, ...]
+    dataset_revision: str
+    checkpoint_manifest_sha256: str
+    seed: int
+    phase: str = "prepare"
+    schema_version: str = INFOCQR_STUDENT_SCHEMA
+
+    def __post_init__(self):
+        object.__setattr__(self, "new_context", tuple(self.new_context))
+        if self.schema_version != INFOCQR_STUDENT_SCHEMA:
+            raise ValidationError("InfoCQR student request schema differs")
+        if self.phase not in {"prepare", "generate", "discard"}:
+            raise ValidationError("InfoCQR student request phase differs")
+        for value in (self.state_hash, self.checkpoint_manifest_sha256):
+            if not _sha256(value):
+                raise ValidationError("InfoCQR student requires SHA-256 bindings")
+        if not all(isinstance(v, str) and v.strip() for v in
+                   (self.query, self.conversation_source, self.dataset_revision)):
+            raise ValidationError("InfoCQR student requires visible query/conversation/dataset")
+        if any(type(v) is not int or v < 1 for v in (self.conversation_no, self.turn_no)):
+            raise ValidationError("InfoCQR student conversation/turn IDs must be positive")
+        if (len(self.new_context) % 2 or any(not isinstance(v, str) for v in self.new_context)
+                or (self.turn_no == 1 and self.new_context)):
+            raise ValidationError("InfoCQR student requires complete visible Q/A history")
+        if type(self.seed) is not int or self.seed < 0:
+            raise ValidationError("InfoCQR student seed must be non-negative")
+
+    @property
+    def request_id(self):
+        return content_hash(self)
+
+    def external_reservation(self):
+        return {"model_calls": 1 if self.phase == "generate" else 0}
+
+    def raise_for_external_status(self, result):
+        if isinstance(result, Mapping) and result.get("status") == "empty_output":
+            raise AlgorithmOutputError("InfoCQR T5 student produced an empty rewrite; no retry")
+        if isinstance(result, Mapping) and result.get("status") == "decode_failed":
+            raise AlgorithmOutputError("InfoCQR T5 student decoding failed after generation; usage retained")
+
+
+def _sha256(value):
+    return isinstance(value, str) and len(value) == 64 and all(c in "0123456789abcdef" for c in value)
+
+
+class InfoCQRStudentExternal:
+    """Rewrite the native QReCC conversational view using an explicit T5 artifact.
+
+    The rewriter is a fixed auxiliary student, not the downstream backbone. Its
+    generation is independently accounted through context.external_runtime.
+    Neither author caches, teacher calls nor a generic t5-base can substitute.
+    """
+
+    method_id = "infocqr"
+    release_id = INFOCQR_STUDENT_RELEASE
+    family = SemanticFamily.REFORMULATE
+
+    def __init__(self, *, checkpoint_manifest_sha256: str, dataset_revision: str,
+                 profile_kind: str = "controlled_adapter", source_license_acknowledged: bool = False):
+        if not _sha256(checkpoint_manifest_sha256):
+            raise ValidationError("InfoCQR student requires a trusted checkpoint manifest SHA-256")
+        if not isinstance(dataset_revision, str) or not dataset_revision.strip():
+            raise ValidationError("InfoCQR student requires the QReCC dataset revision")
+        if profile_kind not in {"official_native", "controlled_adapter"}:
+            raise ValidationError("InfoCQR student profile kind differs")
+        if source_license_acknowledged is not True:
+            raise ValidationError("InfoCQR student requires explicit external-source acknowledgement")
+        self.checkpoint_manifest_sha256 = checkpoint_manifest_sha256
+        self.dataset_revision, self.profile_kind = dataset_revision, profile_kind
+        self.source_license_acknowledged = True
+
+    def propose(self, state: FrozenAgentState, context: InterventionContext) -> InputPatch:
+        conversation = _qrecc_conversation(state)
+        if state.metadata.get("benchmark_id", "qrecc") not in {"qrecc", "qrecc.main", "qrecc.retrieval"}:
+            raise ValidationError("InfoCQR student native release requires QReCC, not a renamed QA dataset")
+        if state.budget.max_model_calls < 1 or state.budget.max_output_tokens < 63:
+            raise BudgetExceededError("InfoCQR student requires one call and its native 63-new-token ceiling")
+        runtime = context.external_runtime
+        if runtime is None or not callable(getattr(runtime, "run", None)) or not callable(getattr(runtime, "fingerprint", None)):
+            raise ExternalDependencyError("InfoCQR student requires InfoCQRStudentRuntime with trained weights")
+        identity = runtime.fingerprint()
+        if (identity.get("mode") != INFOCQR_STUDENT_MODE
+                or identity.get("upstream_revision") != INFOCQR_UPSTREAM_COMMIT
+                or identity.get("checkpoint_manifest_sha256") != self.checkpoint_manifest_sha256
+                or identity.get("dataset_revision") != self.dataset_revision):
+            raise ArtifactError("InfoCQR student runtime/source/checkpoint/dataset binding differs")
+        if self.profile_kind == "official_native" and identity.get("provenance_kind") != "author_student":
+            raise ArtifactError("a user-trained student must not be labeled as the author's checkpoint")
+        request = InfoCQRStudentRequest(
+            state_hash=state.state_hash, task_id=state.task_id, query=state.query,
+            dataset_revision=self.dataset_revision,
+            checkpoint_manifest_sha256=self.checkpoint_manifest_sha256,
+            seed=context.seed, **conversation,
+        )
+        # Loading weights/tokenization is a zero-generation execution preflight,
+        # never a failed scientific attempt charged as one model invocation.
+        prepared = runtime.run(request)
+        if (not isinstance(prepared, Mapping) or prepared.get("status") != "ready"
+                or prepared.get("request_id") != request.request_id
+                or prepared.get("identity") != identity
+                or type(prepared.get("input_tokens")) is not int
+                or not 1 <= prepared["input_tokens"] <= 384
+                or normalize_external_usage(prepared.get("usage")).model_calls != 0):
+            raise AlgorithmOutputError("InfoCQR student execution preflight differs")
+        if (state.budget.max_context_tokens is not None
+                and prepared["input_tokens"] > state.budget.max_context_tokens):
+            runtime.run(replace(request, phase="discard"))
+            raise BudgetExceededError("InfoCQR student exceeds the input-token budget before generation")
+        request = replace(request, phase="generate")
+        response = runtime.run(request)
+        if (not isinstance(response, Mapping) or response.get("request_id") != request.request_id
+                or response.get("identity") != identity or response.get("status") != "ok"):
+            raise AlgorithmOutputError("InfoCQR student returned another request/runtime or failed status")
+        rewrite = response.get("rewrite")
+        if not isinstance(rewrite, str) or not rewrite.strip():
+            raise AlgorithmOutputError("InfoCQR student returned an empty rewrite; no fallback")
+        usage = normalize_external_usage(response.get("usage"))
+        if usage.model_calls != 1 or usage.retrieval_calls or usage.output_tokens > 63:
+            raise AlgorithmOutputError("InfoCQR student native generation usage differs")
+        return InputPatch(
+            method_id=self.method_id, release_id=self.release_id,
+            source_state_hash=state.state_hash,
+            operations=(PatchOperation(PatchOp.REPLACE_QUERY, rewrite, target="query",
+                                       rationale="source-pinned trained InfoCQR T5 student"),),
+            trace=ExecutionTrace(method_id=self.method_id, release_id=self.release_id,
+                events=(TraceEvent(TracePhase.OBSERVE, "native_t5_student", {
+                    "request_id": request.request_id, "source_text_hash": response["source_text_hash"],
+                    "checkpoint_manifest_sha256": self.checkpoint_manifest_sha256,
+                    "max_source_length": 384, "generation_max_length_including_start": 64,
+                    "target_labels_visible_to_generator": False,
+                }),), counters=external_usage_counters(usage)),
+            implementation_identity=f"external_student:InfoCQR@{INFOCQR_UPSTREAM_COMMIT}",
+            profile_kind=self.profile_kind,
+            metadata={"student_runtime": identity, "fixed_auxiliary_not_downstream_backbone": True,
+                      "native_source_logic": True, "native_environment_parity_claimed": False,
+                      "teacher_or_cache_fallback": False, "implicit_retry": False,
+                      "checkpoint_provenance_verification": "caller_receipt_not_authorship_certificate",
+                      "paper_result_parity_claimed": False},
+        )
+
+
+__all__ = ["InfoCQRStudentExternal", "InfoCQRStudentRequest"]

agentinputlab/algorithms/reformulate/query2doc/__init__.py

@@ -0,0 +1,42 @@
+"""Query2doc official-cache and QueryGym community-live profiles."""
+
+from .controlled_live import Query2DocControlledLive, Query2DocLiveBindings, Query2DocLiveConfig
+from .models import OfficialQuery2DocRow, QueryGymMode, QueryGymRawResult, QueryGymRequest
+from .official_cached import (
+    OFFICIAL_ARTIFACT_SHA256,
+    OFFICIAL_DATASET_REVISION,
+    OFFICIAL_TREC_ARTIFACTS,
+    Query2DocCache,
+    Query2DocFixtureCached,
+    Query2DocOfficialCached,
+    compose_sparse_expansion,
+)
+from .querygym_bridge import (
+    QUERYGYM_REVISION,
+    QueryGymLiveBridge,
+    QueryGymRuntime,
+    select_demonstration_ids,
+)
+from .querygym_runtime import PinnedQueryGymRuntime
+
+__all__ = [
+    "OFFICIAL_ARTIFACT_SHA256",
+    "OFFICIAL_DATASET_REVISION",
+    "OFFICIAL_TREC_ARTIFACTS",
+    "QUERYGYM_REVISION",
+    "OfficialQuery2DocRow",
+    "PinnedQueryGymRuntime",
+    "Query2DocCache",
+    "Query2DocControlledLive",
+    "Query2DocFixtureCached",
+    "Query2DocLiveBindings",
+    "Query2DocLiveConfig",
+    "Query2DocOfficialCached",
+    "QueryGymLiveBridge",
+    "QueryGymMode",
+    "QueryGymRawResult",
+    "QueryGymRequest",
+    "QueryGymRuntime",
+    "compose_sparse_expansion",
+    "select_demonstration_ids",
+]

agentinputlab/algorithms/reformulate/query2doc/controlled_live.py

@@ -0,0 +1,190 @@
+"""Dependency-locked QueryGym live Query2doc; native generation logic is unchanged."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any
+
+from agentinputlab.backends.llm import GenerationRequest
+from agentinputlab.contracts import (
+    ExecutionBudget,
+    ExternalDependencyError,
+    FrozenAgentState,
+    InputPatch,
+    InterventionContext,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping
+
+from .models import QueryGymMode
+from .querygym_bridge import QUERYGYM_REVISION, QueryGymLiveBridge
+
+
+@dataclass(frozen=True, slots=True)
+class Query2DocLiveConfig:
+    mode: QueryGymMode | str = QueryGymMode.ZERO_SHOT
+    demonstration_ids: tuple[str, ...] = ()
+    temperature: float = 0.7
+    max_tokens: int = 256
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.mode, (str, QueryGymMode)):
+            raise ValidationError("controlled Query2doc mode must be text")
+        object.__setattr__(self, "mode", QueryGymMode.parse(self.mode))
+        if isinstance(self.demonstration_ids, (str, bytes)):
+            raise ValidationError("controlled Query2doc demonstrations must be an ID sequence")
+        ids = tuple(self.demonstration_ids)
+        if any(not isinstance(i, str) or not i.strip() for i in ids) or len(set(ids)) != len(ids):
+            raise ValidationError("controlled Query2doc demonstration IDs must be unique nonempty text")
+        object.__setattr__(self, "demonstration_ids", ids)
+        if self.mode is QueryGymMode.FEW_SHOT and not ids:
+            raise ValidationError("controlled Query2doc few-shot mode requires frozen demonstration IDs")
+        if self.mode is not QueryGymMode.FEW_SHOT and ids:
+            raise ValidationError("controlled Query2doc demonstrations require few-shot mode")
+        # Reuse the public request's finite numeric/token validation without a
+        # model call. Prompt rendering still belongs to the pinned native worker.
+        GenerationRequest(prompt="configuration validation", temperature=self.temperature,
+                          max_tokens=self.max_tokens)
+
+
+_DEFAULT_CONFIG = Query2DocLiveConfig()
+
+
+def _identity(value: Any, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or not value:
+        raise ValidationError(f"controlled Query2doc {label} fingerprint must be nonempty")
+    try:
+        frozen = freeze_mapping(value)
+        content_hash(frozen)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise ValidationError(f"controlled Query2doc {label} fingerprint must be canonical JSON") from exc
+    return frozen
+
+
+def _runtime_identities(context: InterventionContext) -> dict[str, Mapping[str, Any]]:
+    values = {}
+    for label, dependency, operation in (
+        ("generator", context.backend, "generate"),
+        ("retriever", context.retriever, "retrieve"),
+        ("runtime", context.external_runtime, "reformulate"),
+    ):
+        fingerprint = getattr(dependency, "fingerprint", None)
+        if not callable(fingerprint) or not callable(getattr(dependency, operation, None)):
+            raise ExternalDependencyError(
+                f"controlled Query2doc context requires {label} with {operation}() and fingerprint()"
+            )
+        values[label] = _identity(fingerprint(), label)
+    return values
+
+
+@dataclass(frozen=True, slots=True)
+class Query2DocLiveBindings:
+    """Immutable identities/settings; executable dependencies stay in the context."""
+
+    generator: Mapping[str, Any]
+    retriever: Mapping[str, Any]
+    runtime: Mapping[str, Any]
+    budget: ExecutionBudget
+    config: Query2DocLiveConfig = _DEFAULT_CONFIG
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.budget, ExecutionBudget) or not isinstance(self.config, Query2DocLiveConfig):
+            raise ValidationError("controlled Query2doc bindings require typed budget/config")
+        for label in ("generator", "retriever", "runtime"):
+            object.__setattr__(self, label, _identity(getattr(self, label), label))
+        if self.runtime.get("revision") != QUERYGYM_REVISION:
+            raise ValidationError("controlled Query2doc runtime differs from the pinned QueryGym revision")
+        closure = self.runtime.get("source_closure_sha256")
+        if not isinstance(closure, str) or re.fullmatch(r"[0-9a-f]{64}", closure) is None:
+            raise ValidationError("controlled Query2doc requires a runtime source-closure SHA-256")
+        if content_hash(self.runtime.get("backend")) != content_hash(self.generator):
+            raise ValidationError("controlled Query2doc runtime uses a different generator identity")
+
+    @classmethod
+    def from_context(
+        cls, context: InterventionContext, *, budget: ExecutionBudget,
+        config: Query2DocLiveConfig = _DEFAULT_CONFIG,
+    ) -> Query2DocLiveBindings:
+        if not isinstance(context, InterventionContext):
+            raise ValidationError("controlled Query2doc requires an InterventionContext")
+        return cls(**_runtime_identities(context), budget=budget, config=config)
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> Query2DocLiveBindings:
+        required = {"generator", "retriever", "runtime", "budget"}
+        if not isinstance(value, Mapping) or not required.issubset(value):
+            raise ValidationError("controlled Query2doc binding recipe is missing required fields")
+        if set(value) - required - {"config"}:
+            raise ValidationError("controlled Query2doc binding recipe contains unknown fields")
+        if not isinstance(value["budget"], Mapping) or not isinstance(value.get("config", {}), Mapping):
+            raise ValidationError("controlled Query2doc budget/config recipes must be mappings")
+        try:
+            return cls(generator=value["generator"], retriever=value["retriever"], runtime=value["runtime"],
+                       budget=ExecutionBudget(**value["budget"]),
+                       config=Query2DocLiveConfig(**value.get("config", {})))
+        except TypeError as exc:
+            raise ValidationError("controlled Query2doc recipe contains invalid settings") from exc
+
+    @property
+    def binding_hash(self) -> str:
+        return content_hash(self)
+
+    def require_match(self, context: InterventionContext) -> None:
+        for label, actual in _runtime_identities(context).items():
+            if content_hash(actual) != content_hash(getattr(self, label)):
+                raise ValidationError(f"controlled Query2doc {label} fingerprint differs from binding")
+
+
+@dataclass(frozen=True, slots=True)
+class Query2DocControlledLive:
+    """Native QueryGym reformulation with locked shared-comparison dependencies.
+
+    Retrieval is not performed by a query rewriter. Binding the shared retriever
+    prevents a dispatch-time swap; the downstream benchmark driver must use it
+    with its own declared retrieval depth and remaining budget.
+    """
+
+    bindings: Query2DocLiveBindings | Mapping[str, Any]
+    profile_kind: str = "controlled_adapter"
+    method_id: str = "query2doc"
+    release_id: str = "rewrite.query2doc.controlled_live"
+    family: SemanticFamily = SemanticFamily.REFORMULATE
+
+    def __post_init__(self) -> None:
+        if isinstance(self.bindings, Mapping):
+            object.__setattr__(self, "bindings", Query2DocLiveBindings.from_mapping(self.bindings))
+        if not isinstance(self.bindings, Query2DocLiveBindings):
+            raise ValidationError("controlled Query2doc requires Query2DocLiveBindings")
+        if self.profile_kind not in {"controlled_adapter", "factorial_adapter"}:
+            raise ValidationError("controlled Query2doc profile_kind must be controlled or factorial")
+        if (self.method_id != "query2doc" or self.release_id != "rewrite.query2doc.controlled_live"
+                or self.family is not SemanticFamily.REFORMULATE):
+            raise ValidationError("controlled Query2doc identity differs from its registered profile")
+
+    def propose(self, state: FrozenAgentState, context: InterventionContext) -> InputPatch:
+        if state.budget != self.bindings.budget:
+            raise ValidationError("controlled Query2doc state budget differs from binding")
+        self.bindings.require_match(context)
+        settings = self.bindings.config
+        native = QueryGymLiveBridge(mode=settings.mode, demonstration_ids=settings.demonstration_ids,
+            temperature=settings.temperature, max_tokens=settings.max_tokens).propose(state, context)
+        self.bindings.require_match(context)
+        return replace(native, release_id=self.release_id, profile_kind=self.profile_kind,
+            trace=replace(native.trace, release_id=self.release_id, events=(
+                TraceEvent(TracePhase.PREPARE, "controlled_dependency_binding", {
+                    "binding_sha256": self.bindings.binding_hash, "budget": self.bindings.budget,
+                    "config": settings, "shared_retriever_bound_not_invoked": True}),
+                *native.trace.events)),
+            metadata={**native.metadata, "native_source_release": native.release_id,
+                "controlled_binding_sha256": self.bindings.binding_hash,
+                "dependency_identity_verification": "operator_fingerprint_equality",
+                "downstream_retrieval_performed": False, "weight_files_verified_by_binding": False,
+                "original_paper_result_parity_claimed": False})
+
+
+__all__ = ["Query2DocControlledLive", "Query2DocLiveBindings", "Query2DocLiveConfig"]

agentinputlab/algorithms/reformulate/query2doc/models.py

@@ -0,0 +1,95 @@
+"""Dependency-free Query2doc bridge models."""
+
+from __future__ import annotations
+
+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
+
+
+class QueryGymMode(StrEnum):
+    ZERO_SHOT = "zs"
+    COT = "cot"
+    FEW_SHOT = "few_shot"
+
+    @classmethod
+    def parse(cls, value: str | QueryGymMode) -> QueryGymMode:
+        if isinstance(value, cls):
+            return value
+        normalized = value.strip().lower().replace("-", "_")
+        aliases = {
+            "zero_shot": cls.ZERO_SHOT,
+            "zero": cls.ZERO_SHOT,
+            "zs": cls.ZERO_SHOT,
+            "cot": cls.COT,
+            "fs": cls.FEW_SHOT,
+            "fewshot": cls.FEW_SHOT,
+            "few_shot": cls.FEW_SHOT,
+        }
+        try:
+            return aliases[normalized]
+        except KeyError as exc:
+            raise ValidationError(f"unsupported QueryGym Query2doc mode: {value!r}") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class OfficialQuery2DocRow:
+    query_id: str
+    query: str
+    pseudo_doc: str
+    split: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.query_id:
+            raise ValidationError("Query2doc cache row requires query_id")
+        if not self.query:
+            raise ValidationError("Query2doc cache row requires query")
+        if not self.pseudo_doc:
+            raise ValidationError("Query2doc cache row requires pseudo_doc")
+
+
+@dataclass(frozen=True, slots=True)
+class QueryGymRequest:
+    query_id: str
+    query: str
+    mode: QueryGymMode
+    demonstration_ids: tuple[str, ...] = ()
+    temperature: float = 0.7
+    max_tokens: int = 256
+    seed: int = 0
+    backend_fingerprint: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "demonstration_ids", tuple(self.demonstration_ids))
+        object.__setattr__(self, "backend_fingerprint", freeze_mapping(self.backend_fingerprint))
+        if not self.query:
+            raise ValidationError("QueryGym request requires a non-empty query")
+        if self.max_tokens < 1:
+            raise ValidationError("QueryGym max_tokens must be positive")
+        if self.temperature < 0:
+            raise ValidationError("QueryGym temperature must be non-negative")
+        if self.mode is QueryGymMode.FEW_SHOT and not self.demonstration_ids:
+            raise ValidationError("QueryGym few-shot mode requires fixed demonstration IDs")
+
+    def external_reservation(self) -> Mapping[str, int]:
+        """One Query2doc reformulation always attempts exactly one model call."""
+
+        return {"model_calls": 1}
+
+
+@dataclass(frozen=True, slots=True)
+class QueryGymRawResult:
+    reformulated: str
+    generated_text: str = ""
+    prompt_hash: str = ""
+    fallback: bool = False
+    usage: Mapping[str, int | float] = field(default_factory=dict)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "usage", freeze_mapping(self.usage))
+        object.__setattr__(self, "metadata", freeze_mapping(self.metadata))