agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/algorithms/decompose/plan_and_budget/cached_soft_budget.py

@@ -0,0 +1,362 @@
+"""MIT-source-compatible Plan-and-Budget allocation and prompt materialization."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import MappingProxyType
+
+from agentinputlab.artifacts import load_pinned_json_mapping
+from agentinputlab.contracts import (
+    ArtifactError,
+    ExecutionTrace,
+    FrozenAgentState,
+    InputPatch,
+    InterventionContext,
+    PatchOp,
+    PatchOperation,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+from agentinputlab.contracts.enums import StrEnum
+
+P_AND_B_UPSTREAM_REVISION = "2ca2d90c6d3d630ec2b11cc22e0f56751f7f2b7e"
+
+
+class DecaySchedule(StrEnum):
+    CONSTANT = "constant"
+    LINEAR = "linear"
+    POLYNOMIAL = "polynomial"
+    EXPONENTIAL = "exponential"
+    COSINE = "cosine"
+
+    @classmethod
+    def parse(cls, value: str | DecaySchedule) -> DecaySchedule:
+        if isinstance(value, cls):
+            return value
+        try:
+            return cls(value.strip().lower())
+        except ValueError as exc:
+            raise ValidationError(f"unsupported Plan-and-Budget decay: {value!r}") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class CachedPlanBudgetRecord:
+    record_id: str
+    query: str
+    steps: tuple[str, ...]
+    credits: tuple[float, ...]
+    level: int
+    audit_warnings: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "steps", tuple(self.steps))
+        object.__setattr__(self, "credits", tuple(float(item) for item in self.credits))
+        object.__setattr__(self, "audit_warnings", tuple(self.audit_warnings))
+        if not self.record_id:
+            raise ArtifactError("Plan-and-Budget cached record requires id")
+        if not self.query:
+            raise ArtifactError("Plan-and-Budget cached record requires query")
+        if not self.steps:
+            raise ArtifactError("Plan-and-Budget cached record requires steps")
+        if len(self.steps) != len(self.credits):
+            raise ArtifactError("Plan-and-Budget steps/credits length mismatch")
+        if any(not math.isfinite(item) or item < 0 for item in self.credits):
+            raise ArtifactError("Plan-and-Budget credits must be finite and non-negative")
+        if sum(self.credits) <= 0:
+            raise ArtifactError("Plan-and-Budget credits must have positive mass")
+        if not 1 <= self.level <= 5:
+            raise ArtifactError("Plan-and-Budget level must be in [1, 5]")
+
+
+def load_cached_record(row: Mapping[str, object]) -> CachedPlanBudgetRecord:
+    """Project an upstream row to a solver-visible view, physically dropping gold."""
+
+    record_id = str(row.get("id", row.get("query_id", "")))
+    query = str(row.get("query", row.get("problem", "")))
+    raw_steps = row.get("steps", ())
+    raw_credits = row.get("credits", ())
+    if isinstance(raw_steps, (str, bytes)) or not isinstance(raw_steps, Sequence):
+        raise ArtifactError("Plan-and-Budget steps must be a sequence")
+    if isinstance(raw_credits, (str, bytes)) or not isinstance(raw_credits, Sequence):
+        raise ArtifactError("Plan-and-Budget credits must be a sequence")
+    steps = tuple(str(item) for item in raw_steps)
+    try:
+        credits = tuple(float(item) for item in raw_credits)
+        level = int(row.get("level", 0))
+    except (TypeError, ValueError) as exc:
+        raise ArtifactError("invalid Plan-and-Budget credit/level value") from exc
+    warnings = []
+    if not 2 <= len(steps) <= 5:
+        warnings.append("cached_step_count_outside_prompt_intended_2_to_5")
+    if not math.isclose(sum(credits), 100.0, rel_tol=0.0, abs_tol=1e-9):
+        warnings.append("cached_credit_sum_not_100")
+    if any(key in row for key in ("reference", "solution", "answer", "gold")):
+        warnings.append("gold_fields_removed_from_solver_view")
+    return CachedPlanBudgetRecord(
+        record_id=record_id,
+        query=query,
+        steps=steps,
+        credits=credits,
+        level=level,
+        audit_warnings=tuple(warnings),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class PlanAndBudgetCache:
+    """Solver-only records loaded from a caller-pinned native cache envelope.
+
+    Byte verification does not establish authorship, licensing, the generating
+    model, or generation cost. Keep that provenance in the trusted source receipt.
+    """
+
+    records: Mapping[str, CachedPlanBudgetRecord]
+    artifact_sha256: str
+    verification: str = field(default="caller_declared_digest", init=False)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.artifact_sha256, str) or (
+            len(self.artifact_sha256) != 64
+            or any(c not in "0123456789abcdef" for c in self.artifact_sha256)
+        ):
+            raise ArtifactError("Plan-and-Budget cache requires a SHA-256 digest")
+        copied = dict(self.records)
+        if not copied or any(
+            not isinstance(record, CachedPlanBudgetRecord) or key != record.record_id
+            for key, record in copied.items()
+        ):
+            raise ArtifactError("Plan-and-Budget cache requires records keyed by exact id")
+        object.__setattr__(self, "records", MappingProxyType(copied))
+
+    @classmethod
+    def from_native_json(
+        cls, path: str | Path, *, expected_sha256: str, max_bytes: int = 8 * 1024 * 1024
+    ) -> PlanAndBudgetCache:
+        """Load the upstream ``{last_question_total, stats: [...]}`` format.
+
+        References, solutions and answers are physically absent from the returned
+        records. This loader does not download assets or run their generator.
+        """
+        payload = load_pinned_json_mapping(
+            path, expected_sha256=expected_sha256, max_bytes=max_bytes
+        )
+        if set(payload) != {"last_question_total", "stats"}:
+            raise ArtifactError("Plan-and-Budget native cache envelope differs")
+        if type(payload["last_question_total"]) not in (int, float) or payload["last_question_total"] < 0:
+            raise ArtifactError("Plan-and-Budget native cache timing field differs")
+        rows = payload["stats"]
+        if not isinstance(rows, list) or not rows:
+            raise ArtifactError("Plan-and-Budget native cache stats must be a non-empty list")
+        records = {}
+        for row in rows:
+            if not isinstance(row, dict):
+                raise ArtifactError("Plan-and-Budget native cache row must be an object")
+            required = {"id", "query", "steps", "credits", "level"}
+            if not required <= row.keys() or row.keys() - required - {
+                "reference", "solution", "answer", "gold"
+            }:
+                raise ArtifactError("Plan-and-Budget native cache row fields differ")
+            if not all(isinstance(row[key], str) and row[key].strip() for key in ("id", "query")):
+                raise ArtifactError("Plan-and-Budget native cache id/query must be non-empty strings")
+            if not isinstance(row["steps"], list) or any(
+                not isinstance(step, str) or not step.strip() for step in row["steps"]
+            ):
+                raise ArtifactError("Plan-and-Budget native steps must be non-empty strings")
+            if not isinstance(row["credits"], list) or any(
+                type(credit) not in (int, float) for credit in row["credits"]
+            ) or type(row["level"]) is not int:
+                raise ArtifactError("Plan-and-Budget native credit/level types differ")
+            record = load_cached_record(row)
+            if record.record_id in records:
+                raise ArtifactError("duplicate Plan-and-Budget native cache record id")
+            records[record.record_id] = record
+        result = cls(records, expected_sha256.lower())
+        object.__setattr__(result, "verification", "caller_sha256_verified")
+        return result
+
+
+def _schedule_weights(schedule: DecaySchedule, count: int) -> tuple[float, ...]:
+    values = []
+    for index in range(count):
+        if schedule is DecaySchedule.CONSTANT:
+            weight = 1.0
+        elif schedule is DecaySchedule.LINEAR:
+            weight = count - index
+        elif schedule is DecaySchedule.POLYNOMIAL:
+            weight = float((count - index) ** 2)
+        elif schedule is DecaySchedule.EXPONENTIAL:
+            weight = 0.9**index
+        elif schedule is DecaySchedule.COSINE:
+            weight = (
+                0.5 * (1.0 + math.cos(math.pi * index / (count - 1))) + 0.1 if count > 1 else 1.0
+            )
+        else:  # pragma: no cover - enum exhaustiveness
+            raise ValidationError(f"unsupported schedule: {schedule}")
+        values.append(float(weight))
+    return tuple(values)
+
+
+def allocate_tokens(
+    credits: Sequence[float],
+    total_tokens: int,
+    schedule: str | DecaySchedule = DecaySchedule.CONSTANT,
+) -> tuple[int, ...]:
+    """Pure-Python port of upstream ``allocate_tokens``.
+
+    The upstream name says tokens, although its runtime inserts the allocations
+    as soft *word* budgets.  The caller must preserve that semantic distinction.
+    """
+
+    if total_tokens < 0:
+        raise ValidationError("total_tokens must be non-negative")
+    values = tuple(float(item) for item in credits)
+    if not values:
+        raise ValidationError("credits cannot be empty")
+    if any(not math.isfinite(item) or item < 0 for item in values):
+        raise ValidationError("credits must be finite and non-negative")
+    schedule_value = DecaySchedule.parse(schedule)
+    weights = _schedule_weights(schedule_value, len(values))
+    combined = tuple(credit * weight for credit, weight in zip(values, weights, strict=True))
+    mass = sum(combined)
+    if mass <= 0:
+        raise ValidationError("weighted credits must have positive mass")
+    normalized = tuple(item / mass for item in combined)
+    allocations = [math.floor(item * total_tokens) for item in normalized]
+    difference = total_tokens - sum(allocations)
+    # NumPy argsort tie behavior was not an intentional method contribution.
+    # Stable index ordering makes the port deterministic while preserving the
+    # upstream descending-combined allocation rule.
+    order = sorted(range(len(normalized)), key=lambda index: (-normalized[index], index))
+    for index in order[:difference]:
+        allocations[index] += 1
+    return tuple(allocations)
+
+
+def render_soft_budget_instruction(
+    record: CachedPlanBudgetRecord,
+    allocations: Sequence[int],
+) -> str:
+    if len(record.steps) != len(allocations):
+        raise ValidationError("steps/allocations length mismatch")
+    decomposed = "\n\n".join(
+        f"{step} Please only think a little, and directly solve it using up to {budget} words."
+        for step, budget in zip(record.steps, allocations, strict=True)
+    )
+    return (
+        f"The problem has difficulty level {record.level} out of 5. "
+        "You may follow these sub-questions or use another method that works best "
+        "towards the final answer. All credit is awarded for the correct final "
+        "answer.\n\n"
+        f"{decomposed}"
+    )
+
+
+class PlanAndBudgetCachedSoftBudget:
+    method_id = "plan_and_budget"
+    release_id = "plan.plan_and_budget.native_cached_soft_budget"
+    family = SemanticFamily.DECOMPOSE
+
+    def __init__(
+        self,
+        records: Mapping[str, CachedPlanBudgetRecord] | PlanAndBudgetCache,
+        *,
+        total_word_budget: int,
+        schedule: str | DecaySchedule = DecaySchedule.CONSTANT,
+    ) -> None:
+        if total_word_budget < 0:
+            raise ValidationError("total_word_budget must be non-negative")
+        self.cache_sha256 = records.artifact_sha256 if isinstance(records, PlanAndBudgetCache) else None
+        self.cache_verification = (
+            records.verification if isinstance(records, PlanAndBudgetCache) else "caller_mapping_unverified"
+        )
+        self.records = dict(records.records if isinstance(records, PlanAndBudgetCache) else records)
+        self.total_word_budget = total_word_budget
+        self.schedule = DecaySchedule.parse(schedule)
+
+    def propose(self, state: FrozenAgentState, context: InterventionContext) -> InputPatch:
+        record_id = state.task_id or str(state.metadata.get("query_id", ""))
+        try:
+            record = self.records[record_id]
+        except KeyError as exc:
+            raise ArtifactError(f"no cached Plan-and-Budget record for {record_id!r}") from exc
+        if record.query != state.query:
+            raise ArtifactError(f"Plan-and-Budget cached query mismatch for {record_id!r}")
+        allocations = allocate_tokens(
+            record.credits,
+            self.total_word_budget,
+            self.schedule,
+        )
+        instruction = render_soft_budget_instruction(record, allocations)
+        trace = ExecutionTrace(
+            method_id=self.method_id,
+            release_id=self.release_id,
+            events=(
+                TraceEvent(
+                    TracePhase.PREPARE,
+                    "cached_plan_budget_record",
+                    {
+                        "record_id": record.record_id,
+                        "steps": record.steps,
+                        "credits": record.credits,
+                        "credit_sum": sum(record.credits),
+                        "level": record.level,
+                        "audit_warnings": record.audit_warnings,
+                        "gold_visible_to_solver": False,
+                        "cache_artifact_sha256": self.cache_sha256,
+                    },
+                ),
+                TraceEvent(
+                    TracePhase.PROPOSE,
+                    "soft_word_budget_allocation",
+                    {
+                        "schedule": self.schedule.value,
+                        "total_budget": self.total_word_budget,
+                        "budget_unit": "soft_words",
+                        "allocation_tie_policy": "stable_source_index",
+                        "allocations": allocations,
+                        "decoder_hard_cap_applied": False,
+                        "instruction": instruction,
+                    },
+                ),
+            ),
+            counters={
+                "optimizer_model_calls": 0,
+                "planned_steps": len(record.steps),
+                "allocated_soft_words": sum(allocations),
+            },
+            warnings=record.audit_warnings,
+        )
+        return InputPatch(
+            method_id=self.method_id,
+            release_id=self.release_id,
+            source_state_hash=state.state_hash,
+            operations=(
+                PatchOperation(
+                    PatchOp.APPEND_INSTRUCTION,
+                    value=instruction,
+                    target="instruction",
+                    rationale="Plan-and-Budget cached weighted soft word budgets",
+                ),
+            ),
+            trace=trace,
+            implementation_identity=f"minimal_mit_port:junhongmit/P-and-B@{P_AND_B_UPSTREAM_REVISION}",
+            profile_kind="official_native",
+            metadata={
+                "implementation_origin": "official_mit_minimal_port",
+                "cached_decomposition": True,
+                "budget_unit": "soft_words",
+                "allocation_tie_policy": "stable_source_index",
+                "numpy_tie_order_parity_claimed": False,
+                "hard_decoder_cap": False,
+                "gold_fields_removed": True,
+                "cache_artifact_sha256": self.cache_sha256,
+                "cache_verification": self.cache_verification,
+                "historical_cache_generation_cost": "unknown_not_free",
+                "paper_result_parity_claimed": False,
+            },
+        )

agentinputlab/algorithms/decompose/plan_and_budget/decomposer_component.py

@@ -0,0 +1,107 @@
+"""Evaluator-blind first-stage component of the controlled P&B adaptation.
+
+Shares its existing generalized decomposition prompt/parser unchanged. This is
+not credit assessment, budget allocation, the upstream full solver or a claim
+of native released-cache/paper-result parity.
+"""
+
+from __future__ import annotations
+
+import math
+
+from agentinputlab.backends.llm import GenerationRequest, LLMBackend, ModelCapability
+from agentinputlab.contracts import (
+    BudgetExceededError,
+    CapabilityError,
+    ExecutionTrace,
+    ExternalDependencyError,
+    FrozenAgentState,
+    InputPatch,
+    InterventionContext,
+    PatchOp,
+    PatchOperation,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+from agentinputlab.contracts.serialization import content_hash
+
+from .cached_soft_budget import P_AND_B_UPSTREAM_REVISION
+from .regenerated_soft_budget import (
+    _decomposition_prompt,
+    _decomposition_system,
+    _parse_decomposition,
+)
+
+
+class PlanAndBudgetDecomposerComponent:
+    method_id = "plan_and_budget"
+    release_id = "plan.plan_and_budget.decomposer_component"
+    family = SemanticFamily.DECOMPOSE
+
+    def __init__(self, *, domain="general question answering", initial_level=3,
+                 decomposition_max_tokens=768, temperature=0.0):
+        if not isinstance(domain, str) or not domain.strip():
+            raise ValidationError("Plan-and-Budget domain must be non-empty")
+        if type(initial_level) is not int or not 1 <= initial_level <= 5:
+            raise ValidationError("Plan-and-Budget initial_level must be in [1, 5]")
+        if type(decomposition_max_tokens) is not int or decomposition_max_tokens < 1:
+            raise ValidationError("decomposition_max_tokens must be positive")
+        if isinstance(temperature, bool) or not isinstance(temperature, (int, float)):
+            raise ValidationError("temperature must be finite and non-negative")
+        if not math.isfinite(temperature) or temperature < 0:
+            raise ValidationError("temperature must be finite and non-negative")
+        self.domain, self.initial_level = domain, initial_level
+        self.decomposition_max_tokens, self.temperature = decomposition_max_tokens, temperature
+
+    def propose(self, state: FrozenAgentState, context: InterventionContext) -> InputPatch:
+        if not state.query.strip():
+            raise ValidationError("Plan-and-Budget requires a non-empty query")
+        if state.budget.max_model_calls < 1 or state.budget.max_output_tokens < 1:
+            raise BudgetExceededError("decomposer component has no generation budget")
+        backend = context.backend
+        if backend is None:
+            raise ExternalDependencyError("decomposer component requires an injected LLMBackend")
+        if not isinstance(backend, LLMBackend) or ModelCapability.COMPLETION not in backend.capabilities:
+            raise CapabilityError("decomposer component requires completion capability")
+        system = _decomposition_system(self.domain)
+        prompt = _decomposition_prompt(state.query, level=self.initial_level)
+        # Match the existing controlled full profile's FIRST-stage reservation.
+        # The component does not spend the reserved half on a credit assessor.
+        cap = min(self.decomposition_max_tokens, max(1, state.budget.max_output_tokens // 2))
+        request = GenerationRequest(prompt=prompt, system=system, temperature=self.temperature,
+            max_tokens=cap, seed=context.seed, metadata={"method_id": self.method_id,
+                "release_id": self.release_id, "stage": "decomposition",
+                "upstream_revision": P_AND_B_UPSTREAM_REVISION})
+        response = backend.generate(request)
+        steps, warnings = _parse_decomposition(response.text)
+        instruction = "Suggested sub-questions:\n" + "\n\n".join(
+            f"{index}. {step}" for index, step in enumerate(steps, 1)
+        )
+        return InputPatch(method_id=self.method_id, release_id=self.release_id,
+            source_state_hash=state.state_hash,
+            operations=(PatchOperation(PatchOp.APPEND_INSTRUCTION, value=instruction,
+                target="instruction", rationale="controlled P&B decomposition-only component"),),
+            implementation_identity=f"controlled_p_and_b_first_stage@{P_AND_B_UPSTREAM_REVISION}",
+            profile_kind="controlled_adapter",
+            trace=ExecutionTrace(method_id=self.method_id, release_id=self.release_id,
+                events=(TraceEvent(TracePhase.PROPOSE, "decomposition_component", {
+                    "steps": steps, "initial_level": self.initial_level,
+                    "decomposition_request_sha256": content_hash({"system": system, "prompt": prompt}),
+                    "optimizer_input_projection": "query_only", "gold_visible_to_optimizer": False,
+                    "credit_assessment_executed": False, "solver_executed": False}),),
+                counters={"model_calls": 1, "optimizer_model_calls": 1,
+                    "input_tokens": response.usage.input_tokens,
+                    "output_tokens": response.usage.output_tokens, "planned_steps": len(steps)},
+                warnings=warnings),
+            metadata={"component_only": True, "full_system": False, "steps": steps,
+                "live_decomposition": True, "optimizer_input_projection": "query_only",
+                "credit_assessment_executed": False, "budget_allocation_executed": False,
+                "solver_executed": False, "hard_decoder_cap": False,
+                "gold_fields_visible_to_optimizer": False, "paper_result_parity_claimed": False,
+                "source_profile": "native_regenerated_soft_budget_first_stage",
+                "decomposition_fallback": "decomposition_parse_fallback_to_direct_solve" in warnings})
+
+
+__all__ = ["PlanAndBudgetDecomposerComponent"]

agentinputlab/algorithms/decompose/plan_and_budget/full.py

@@ -0,0 +1,205 @@
+"""Complete P&B preparation, native weighted prompt and observed answer call."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import replace
+from types import MappingProxyType
+
+from agentinputlab.backends.llm import GenerationRequest, LLMBackend, ModelCapability
+from agentinputlab.contracts import (
+    AlgorithmOutputError,
+    ArtifactError,
+    BudgetExceededError,
+    CapabilityError,
+    CompositeResult,
+    ExecutionTrace,
+    ExternalDependencyError,
+    FrozenAgentState,
+    InterventionContext,
+    Message,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+
+from .cached_soft_budget import (
+    P_AND_B_UPSTREAM_REVISION,
+    CachedPlanBudgetRecord,
+    DecaySchedule,
+    PlanAndBudgetCache,
+)
+from .regenerated_soft_budget import PlanAndBudgetRegeneratedSoftBudget
+
+
+class PlanAndBudgetFull:
+    """Run a complete answer-producing workflow, not an input patch.
+
+    Cached mode requires an exact ID/query match. Live mode regenerates two
+    solver-only fields without labels. Both use the original native weighted
+    reasoning prompt and level-dependent soft word budgets, followed by one
+    generation. The caller retains the benchmark's independent official scorer.
+    """
+
+    method_id = "plan_and_budget"
+    release_id = "plan.plan_and_budget.full"
+    family = SemanticFamily.DECOMPOSE
+
+    def __init__(
+        self, *, output_format: str,
+        records: Mapping[str, CachedPlanBudgetRecord] | PlanAndBudgetCache | None = None,
+        domain: str = "general question answering", initial_level: int = 3,
+        schedule: str | DecaySchedule = DecaySchedule.CONSTANT,
+        decomposition_max_tokens: int = 512, assessment_max_tokens: int = 512,
+        max_solver_tokens: int = 512, temperature: float = 0.0,
+    ):
+        if not isinstance(output_format, str) or not output_format.strip():
+            raise ValidationError("P&B full requires an explicit output format")
+        if (type(max_solver_tokens) is not int or max_solver_tokens < 1
+                or type(temperature) not in (int, float)
+                or not math.isfinite(temperature) or temperature < 0):
+            raise ValidationError("P&B solver token cap/temperature is invalid")
+        self.output_format, self.max_solver_tokens = output_format, max_solver_tokens
+        self.temperature = temperature
+        self.schedule = DecaySchedule.parse(schedule)
+        self.cache_sha256 = records.artifact_sha256 if isinstance(records, PlanAndBudgetCache) else None
+        self.cache_verification = records.verification if isinstance(records, PlanAndBudgetCache) else None
+        if isinstance(records, PlanAndBudgetCache):
+            records = records.records
+        if records is not None and (not records or any(
+            not isinstance(value, CachedPlanBudgetRecord) or key != value.record_id
+            for key, value in records.items()
+        )):
+            raise ArtifactError("P&B full requires solver-only records keyed by exact ID")
+        self.records = MappingProxyType(dict(records)) if records is not None else None
+        self.preparation = PlanAndBudgetRegeneratedSoftBudget(
+            domain=domain, initial_level=initial_level, schedule=self.schedule,
+            decomposition_max_tokens=decomposition_max_tokens,
+            assessment_max_tokens=assessment_max_tokens, temperature=temperature,
+        )
+
+    def run(self, state: FrozenAgentState, context: InterventionContext) -> CompositeResult:
+        from agentinputlab.integrations.full_architecture.plan_and_budget import (
+            PAB_NATIVE_PROMPT_MODE,
+            PlanBudgetPromptRequest,
+        )
+
+        if not state.query.strip():
+            raise ValidationError("P&B full requires a non-empty query")
+        if state.messages or state.tool_names:
+            raise CapabilityError("P&B native solver accepts visible QA context, not a tool/history loop")
+        needed_calls = 1 if self.records is not None else 3
+        if (state.budget.max_model_calls < needed_calls
+                or state.budget.max_output_tokens < needed_calls):
+            raise BudgetExceededError(f"P&B full requires at least {needed_calls} model calls/tokens")
+        backend = context.backend
+        if not isinstance(backend, LLMBackend):
+            raise ExternalDependencyError("P&B full requires an injected LLMBackend")
+        if ModelCapability.CHAT not in backend.capabilities:
+            raise CapabilityError("P&B full requires the controlled chat backend binding")
+        runtime = context.external_runtime
+        if (runtime is None or not callable(getattr(runtime, "run", None))
+                or not callable(getattr(runtime, "fingerprint", None))):
+            raise ExternalDependencyError("P&B full requires PlanAndBudgetNativePromptRuntime")
+        identity = runtime.fingerprint()
+        if (identity.get("binding_mode") != PAB_NATIVE_PROMPT_MODE
+                or identity.get("upstream_revision") != P_AND_B_UPSTREAM_REVISION):
+            raise ArtifactError("P&B full native runtime binding/revision differs")
+        events, warnings = (), ()
+        input_tokens = output_tokens = prep_calls = 0
+        if self.records is not None:
+            record = self.records.get(state.task_id)
+            if record is None or record.query != state.query:
+                raise ArtifactError("P&B full cached ID/query does not match; no live fallback")
+            warnings = record.audit_warnings
+        else:
+            # Reserve at least one output token/call for the solver. Actual
+            # provider usage, including failed preparation, is ledger-observed.
+            prep_state = replace(state, budget=replace(
+                state.budget, max_model_calls=state.budget.max_model_calls - 1,
+                max_output_tokens=state.budget.max_output_tokens - 1,
+            ))
+            patch = self.preparation.propose(prep_state, context)
+            decomposition, assessment = patch.trace.events[:2]
+            record = CachedPlanBudgetRecord(
+                record_id=state.task_id or state.state_hash, query=state.query,
+                steps=tuple(decomposition.payload["steps"]),
+                credits=tuple(assessment.payload["credits"]),
+                level=assessment.payload["evaluated_level"],
+                audit_warnings=patch.trace.warnings,
+            )
+            events, warnings = patch.trace.events[:2], patch.trace.warnings
+            input_tokens = patch.trace.counters["input_tokens"]
+            output_tokens = patch.trace.counters["output_tokens"]
+            prep_calls = 2
+        envelope = runtime.run(PlanBudgetPromptRequest(
+            record=record, instruction=state.instruction,
+            reference="\n\n".join(
+                (f"[{block.block_id}] {block.text}" if block.block_id else block.text)
+                + f"\nSupport ID: {block.metadata.get('official_support_id', block.block_id)}"
+                + (f"\nSource: {block.source}" if block.source else "")
+                for block in state.context
+            ),
+            output_format=self.output_format, schedule=self.schedule.value,
+        ))
+        if not isinstance(envelope, Mapping) or envelope.get("identity") != identity:
+            raise ArtifactError("P&B native prompt response identity differs")
+        remaining = state.budget.max_output_tokens - output_tokens
+        if remaining < 1:
+            raise BudgetExceededError("P&B preparation exhausted the solver output budget")
+        request = GenerationRequest(
+            messages=tuple(Message(**message) for message in envelope["messages"]),
+            temperature=self.temperature, max_tokens=min(self.max_solver_tokens, remaining),
+            seed=context.seed + prep_calls,
+            metadata={"release_id": self.release_id, "stage": "native_weighted_solver",
+                      "upstream_revision": P_AND_B_UPSTREAM_REVISION},
+        )
+        response = backend.generate(request)
+        if not isinstance(response.text, str) or not response.text.strip():
+            raise AlgorithmOutputError("P&B solver returned an empty final answer; no retry")
+        if response.usage.output_tokens > request.max_tokens:
+            raise BudgetExceededError("P&B solver usage exceeded its requested output cap")
+        return CompositeResult(
+            method_id=self.method_id, release_id=self.release_id,
+            source_state_hash=state.state_hash, final_answer=response.text,
+            evidence=state.context,
+            trace=ExecutionTrace(
+                method_id=self.method_id, release_id=self.release_id,
+                events=(*events, TraceEvent(TracePhase.PREPARE, "native_soft_word_allocation", {
+                    "allocations": envelope["allocations"],
+                    "total_soft_words": envelope["soft_word_budget"],
+                    "schedule": self.schedule.value, "tie_policy": "native_numpy_argsort",
+                }), TraceEvent(TracePhase.OBSERVE, "solver_answer", {
+                    "request_hash": request.request_hash, "finish_reason": response.finish_reason,
+                    "max_output_tokens": request.max_tokens, "seed": request.seed,
+                })),
+                counters={"model_calls": prep_calls + 1, "optimizer_model_calls": prep_calls,
+                          "input_tokens": input_tokens + response.usage.input_tokens,
+                          "output_tokens": output_tokens + response.usage.output_tokens},
+                warnings=warnings,
+            ),
+            implementation_identity=f"native_weighted_solver:P-and-B@{P_AND_B_UPSTREAM_REVISION}",
+            profile_kind="controlled_adapter",
+            metadata={
+                "cached_decomposition": self.records is not None,
+                "cache_artifact_sha256": self.cache_sha256,
+                "cache_verification": self.cache_verification,
+                "native_prompt_runtime": identity,
+                "solver_calls": 1, "per_step_model_calls": False,
+                "budget_unit": "soft_words", "per_step_hard_token_cap": False,
+                "decoder_output_cap": request.max_tokens,
+                "native_sampling_defaults_preserved": False,
+                "sampling_policy": "explicit_caller_temperature_seed_cap_and_backend_defaults",
+                "native_retry_policy_preserved": False,
+                "transport_policy": "one_attempt_no_implicit_retry",
+                "native_gold_evaluator_executed": False,
+                "official_scoring": "caller_owned_separate_benchmark_scorer",
+                "gold_fields_visible_to_optimizer": False,
+                "paper_result_parity_claimed": False,
+            },
+        )
+
+
+__all__ = ["PlanAndBudgetFull"]