orizu 0.5.20 → 0.5.21

package/tsconfig.json

@@ -4,6 +4,8 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
     "rootDir": "src",
     "strict": true,
     "esModuleInterop": true,

package/vendor/orizu-gepa/src/orizu_gepa_connector/__init__.py

@@ -4,5 +4,6 @@ from .adapter import RunnerEvaluationAdapter
 from .callbacks import LifecycleHooks, OrizuCallback
 from .engine import SeedValidationRefused, run_official_gepa
 from .cli import main
+from .instruction_set_loader import load_instruction_set
 
-__all__ = ["LifecycleHooks", "OrizuCallback", "RunnerEvaluationAdapter", "SeedValidationRefused", "main", "run_official_gepa"]
+__all__ = ["LifecycleHooks", "OrizuCallback", "RunnerEvaluationAdapter", "SeedValidationRefused", "load_instruction_set", "main", "run_official_gepa"]

package/vendor/orizu-gepa/src/orizu_gepa_connector/adapter.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 from typing import Any
 
 from gepa.core.adapter import EvaluationBatch
@@ -59,8 +60,13 @@ class RunnerEvaluationAdapter:
         self.last_candidate: dict[str, str] | None = None
 
     def evaluate(self, batch: list[Any], candidate: dict[str, str], capture_traces: bool = False) -> EvaluationBatch:
+        # The exec-context can describe a multi-component wrapper for a
+        # legacy prompt run.  The candidate is the execution contract: only a
+        # map with more than one value is a tuple rewrite.
+        is_multi_component_tuple = len(candidate) > 1
         component = next(iter(candidate))
-        candidate_text = candidate[component]
+        candidate_text: str | dict[str, str] = dict(candidate) if is_multi_component_tuple else candidate[component]
+        candidate_id = json.dumps(candidate, sort_keys=True, separators=(",", ":")) if is_multi_component_tuple else component
         outputs: list[dict[str, Any]] = []
         scores: list[float] = []
         trajectories: list[dict[str, Any]] = []
@@ -74,7 +80,7 @@ class RunnerEvaluationAdapter:
         try:
             row_evaluations = evaluate_candidate(
                 candidate_text=candidate_text,
-                candidate_id=component,
+                candidate_id=candidate_id,
                 rows=batch,
                 split="official_gepa",
                 prompt_context=self.prompt_context,

package/vendor/orizu-gepa/src/orizu_gepa_connector/callbacks.py

@@ -248,9 +248,12 @@ class OrizuCallback:
     def on_proposal_start(self, event: dict[str, Any]) -> None:
         iteration = int(event["iteration"])
         self._flush_pending_parent_minibatches(iteration)
+        parent_candidate = event.get("parent_candidate")
         self._reflection_contexts[iteration] = {
             "iteration": iteration,
             "parent_candidate_id": self._selected_parent_by_iteration.get(iteration),
+            "components_to_update": list(event.get("components") or []),
+            "parent_candidate": dict(parent_candidate) if isinstance(parent_candidate, dict) else None,
         }
         self._emit("on_proposal_start", event)
 
@@ -495,18 +498,29 @@ class OrizuCallback:
     def _emit_buffered_proposal(self, event: dict[str, Any], candidate_id: str) -> None:
         iteration = int(event["iteration"])
         parent_id = self._selected_parent_by_iteration.get(iteration)
-        components = event.get("new_instructions") or {}
+        context = self._reflection_contexts.get(iteration, {})
+        parent_candidate = context.get("parent_candidate")
+        new_instructions = event.get("new_instructions") or {}
+        components = {
+            **(parent_candidate if isinstance(parent_candidate, dict) else {}),
+            **(new_instructions if isinstance(new_instructions, dict) else {}),
+        }
         bounded_components = {}
         truncated = False
         for key, value in components.items():
             bounded, did_truncate = _bounded(value, self.max_payload_chars)
             bounded_components[key] = bounded
             truncated = truncated or did_truncate
+        selected = list(context.get("components_to_update") or [])
         body, body_truncated = _bounded(next(iter(components.values()), None), self.max_payload_chars)
+        payload = {"components": bounded_components, "components_to_update": selected,
+                   "payload_truncated": truncated or body_truncated}
+        if ((isinstance(parent_candidate, dict) and len(parent_candidate) == 1)
+                or (parent_candidate is None and len(components) == 1)):
+            payload["body"] = body
         self.sink.emit(
             "candidate_proposed",
-            {"body": body, "components": bounded_components,
-             "payload_truncated": truncated or body_truncated},
+            payload,
             iteration=iteration,
             candidate_id=candidate_id,
             parent_candidate_id=parent_id,

package/vendor/orizu-gepa/src/orizu_gepa_connector/engine.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
+import dataclasses
 import json
 import random
 from typing import Any
@@ -13,6 +14,7 @@ from orizu_gepa.optimizer import TextGepaConfig
 
 from .callbacks import LifecycleHooks, OrizuCallback
 from .preflight import validate_seed_and_scorer
+from .stop_conditions import ProposalBudgetStopper
 
 
 def _row_id(row: Any, index: int) -> str:
@@ -84,8 +86,8 @@ def _preflight_row_evidence(rows: list[Any], scores: list[float], outputs: list[
     return evidence
 
 
-def validate_seed_before_run(*, seed_candidate: dict[str, str], valset: list[Any], adapter: Any,
-                             hooks: LifecycleHooks, allow_degenerate_seed: bool) -> dict[str, Any]:
+def _validate_seed_before_run(*, seed_candidate: dict[str, str], valset: list[Any], adapter: Any,
+                              hooks: LifecycleHooks, allow_degenerate_seed: bool) -> tuple[dict[str, Any], Any, list[Any]]:
     """Cheap scorer preflight; GEPA owns the single full seed validation."""
     # The approved cap bounds preflight spend. With a binary scorer and a seed
     # that is correct 70% of the time, all three sampled rows can still score
@@ -103,23 +105,60 @@ def validate_seed_before_run(*, seed_candidate: dict[str, str], valset: list[Any
     hooks.emit("seed_validated", verdict)
     if not verdict["allowed"]:
         raise SeedValidationRefused(verdict)
+    return verdict, seed_evaluation, preflight_rows
+
+
+def validate_seed_before_run(*, seed_candidate: dict[str, str], valset: list[Any], adapter: Any,
+                             hooks: LifecycleHooks, allow_degenerate_seed: bool) -> dict[str, Any]:
+    """Validate the seed and return the durable public preflight verdict."""
+    verdict, _evaluation, _rows = _validate_seed_before_run(
+        seed_candidate=seed_candidate,
+        valset=valset,
+        adapter=adapter,
+        hooks=hooks,
+        allow_degenerate_seed=allow_degenerate_seed,
+    )
     return verdict
 
 
+class _PreflightReusingAdapter:
+    """Serve GEPA's immediate seed evaluation from the completed preflight."""
+
+    def __init__(self, adapter: Any, seed_candidate: dict[str, str], rows: list[Any], evaluation: Any):
+        self._adapter = adapter
+        self._seed_candidate = seed_candidate
+        self._rows = rows
+        self._evaluation = evaluation
+        self._served_seed = False
+
+    def evaluate(self, batch: list[Any], candidate: dict[str, str], capture_traces: bool = False):
+        if (not self._served_seed and not capture_traces and candidate == self._seed_candidate
+                and list(batch) == self._rows):
+            self._served_seed = True
+            return self._evaluation
+        return self._adapter.evaluate(batch, candidate, capture_traces=capture_traces)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._adapter, name)
+
+
 def run_official_gepa(
     *,
     seed_candidate: dict[str, str],
     trainset: list[Any],
     valset: list[Any],
     adapter: Any,
-    callback: OrizuCallback,
+    callback: Any,
     hooks: LifecycleHooks,
     max_metric_calls: int | None = None,
     stop_callbacks: Sequence[Callable[[Any], bool]] = (),
     allow_degenerate_seed: bool = False,
     reflection_lm: Callable[[str], str] | None = None,
+    custom_candidate_proposer: Callable[..., dict[str, str]] | None = None,
+    proposal_budget: Any | None = None,
     seed_already_validated: bool = False,
     config: TextGepaConfig | None = None,
+    module_selector: str = "round_robin",
 ) -> Any:
     """Run GEPA after the launch-time seed check and emit named lifecycle hooks.
 
@@ -135,8 +174,10 @@ def run_official_gepa(
         callback.evaluation_adapter = adapter
         callback.validation_row_ids = [_row_id(row, index) for index, row in enumerate(valset)]
 
+    preflight_evaluation = None
+    preflight_rows: list[Any] = []
     if not seed_already_validated:
-        validate_seed_before_run(
+        _verdict, preflight_evaluation, preflight_rows = _validate_seed_before_run(
             seed_candidate=seed_candidate,
             valset=valset,
             adapter=adapter,
@@ -144,6 +185,27 @@ def run_official_gepa(
             allow_degenerate_seed=allow_degenerate_seed,
         )
 
+    # GEPA 0.1.4 reads this optional protocol attribute directly in its
+    # reflective proposer, even when a custom proposer owns the call. Our
+    # runner adapter supplies it; lightweight adapters used by the real GEPA
+    # boundary do not. Normalize the vendor's optional slot without replacing
+    # an adapter-owned proposer.
+    if custom_candidate_proposer is not None and not hasattr(adapter, "propose_new_texts"):
+        adapter.propose_new_texts = None
+
+    gepa_adapter = adapter
+    if custom_candidate_proposer is not None and preflight_evaluation is not None:
+        # A one-row low metric ceiling otherwise pays for this same seed row a
+        # second time inside GEPA before it reaches the custom proposal. The
+        # cached result is already a real evaluator result from this call's
+        # mandatory preflight; only the duplicate evaluator invocation is
+        # removed, never the separate proposal ledger.
+        gepa_adapter = _PreflightReusingAdapter(adapter, seed_candidate, preflight_rows, preflight_evaluation)
+    if custom_candidate_proposer is not None:
+        # GEPA refuses an adapter-owned proposer alongside its explicit custom
+        # proposer. The latter is the selected skilled-proposer path.
+        gepa_adapter.propose_new_texts = None
+
     config = config or TextGepaConfig()
     candidate_selection_strategy: Any = config.candidate_selection_strategy
     # Official GEPA's string shortcut fixes epsilon at 0.1.  Use its public
@@ -154,24 +216,54 @@ def run_official_gepa(
             rng=random.Random(config.seed),
         )
 
+    owned_stop_callbacks = list(stop_callbacks)
+    if proposal_budget is not None:
+        owned_stop_callbacks.append(ProposalBudgetStopper(proposal_budget))
+
+    reflection_minibatch_size = config.minibatch_size
+    if custom_candidate_proposer is not None and max_metric_calls is not None:
+        # GEPA's metric stopper is evaluated at iteration boundaries.  Do not
+        # let its default three-row reflection batch overshoot a deliberately
+        # smaller evaluator-only ceiling before that boundary is observed.
+        reflection_minibatch_size = min(
+            reflection_minibatch_size,
+            max(1, max_metric_calls - len(valset)),
+        )
+
     kwargs: dict[str, Any] = {
         "seed_candidate": seed_candidate,
         "trainset": trainset,
         "valset": valset,
-        "adapter": adapter,
+        "adapter": gepa_adapter,
         "callbacks": [callback],
-        "stop_callbacks": list(stop_callbacks) or None,
+        "stop_callbacks": owned_stop_callbacks or None,
         "max_metric_calls": max_metric_calls,
         "candidate_selection_strategy": candidate_selection_strategy,
         "skip_perfect_score": config.skip_perfect_parent_reflection,
-        "reflection_minibatch_size": config.minibatch_size,
+        "reflection_minibatch_size": reflection_minibatch_size,
         "cache_evaluation": config.cache_evaluations,
         "seed": config.seed,
         "display_progress_bar": False,
         "raise_on_exception": True,
+        "module_selector": module_selector,
     }
     if reflection_lm is not None:
         kwargs["reflection_lm"] = reflection_lm
+        # The connector implements GEPA's component-aware strategy protocol;
+        # passing it as a bare callable would discard the selected component.
+        kwargs["reflection_strategy"] = reflection_lm
+    if custom_candidate_proposer is not None:
+        kwargs["custom_candidate_proposer"] = custom_candidate_proposer
     kwargs["trainset"] = _with_row_identities(trainset)
     kwargs["valset"] = _with_row_identities(valset)
-    return optimize(**kwargs)
+    result = optimize(**kwargs)
+    if custom_candidate_proposer is not None and preflight_evaluation is not None:
+        # GEPA's state correctly counts its seed evaluation, but this run
+        # served that evaluation from the already-accounted launch preflight.
+        # Its public metric result must consequently retain M1's convention:
+        # GEPA result counts exclude the one caller preflight, while the
+        # adapter's physical count is result + one.
+        total = getattr(result, "total_metric_calls", None)
+        if isinstance(total, int):
+            result = dataclasses.replace(result, total_metric_calls=max(0, total - len(preflight_rows)))
+    return result

package/vendor/orizu-gepa/src/orizu_gepa_connector/instruction_set_loader.py

@@ -0,0 +1,52 @@
+"""Offline reader for the ALI-1532 synced instruction-set layout."""
+
+import json
+from pathlib import Path
+
+
+class InstructionSetLoaderError(Exception):
+    def __init__(self, code: str):
+        self.code = code
+        super().__init__(code)
+
+
+def _inside(root: Path, candidate: Path) -> bool:
+    try:
+        candidate.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def load_instruction_set(directory: str, name: str, model_config_identity: str) -> dict[str, str]:
+    root = (Path(directory) / name).resolve()
+    if not root.is_dir():
+        raise InstructionSetLoaderError("instruction_set_not_synced")
+    manifest_path = root / "manifest.json"
+    if not manifest_path.is_file():
+        raise InstructionSetLoaderError("instruction_set_manifest_missing")
+    try:
+        manifest = json.loads(manifest_path.read_text())
+    except (OSError, json.JSONDecodeError) as error:
+        raise InstructionSetLoaderError("instruction_set_manifest_missing") from error
+    if manifest.get("manifestVersion") != 1:
+        raise InstructionSetLoaderError("instruction_set_manifest_version_unsupported")
+    if manifest.get("filteredTo") and model_config_identity not in manifest["filteredTo"]:
+        raise InstructionSetLoaderError("instruction_set_profile_not_synced")
+    production = next((profile.get("production") for profile in manifest.get("profiles", []) if profile.get("modelConfigIdentity") == model_config_identity), None)
+    material = production or manifest.get("default", {})
+    values: dict[str, str] = {}
+    for key in manifest.get("shape", []):
+        if key in material.get("pinnedComponents", {}):
+            raise InstructionSetLoaderError("instruction_set_component_unavailable")
+        relative = material.get("files", {}).get(key)
+        if not relative:
+            raise InstructionSetLoaderError("instruction_set_profile_key_missing")
+        path = (root / relative).resolve()
+        if not _inside(root, path):
+            raise InstructionSetLoaderError("instruction_set_path_unsafe")
+        try:
+            values[key] = path.read_text()
+        except OSError as error:
+            raise InstructionSetLoaderError("instruction_set_component_unreadable") from error
+    return values

package/vendor/orizu-gepa/src/orizu_gepa_connector/reflection.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 from collections.abc import Callable
+from dataclasses import replace
+import json
 from typing import Any
 
-from orizu_gepa.optimizer import build_reflection_prompt
+from orizu_gepa.optimizer import DEFAULT_REFLECTION_PROMPT_TEMPLATE, build_reflection_prompt
 from orizu_gepa.reflection import reflect_with_provider
 
 
@@ -26,16 +28,14 @@ class GepaReflectionLM:
     GEPA intentionally catches reflection failures per proposal.  That keeps an
     optimization alive, but means the connector is the final durable boundary
     for the actual exception.  This wrapper records it *before* re-raising to
-    GEPA's safe helper and exposes the same estimated usage shape as GEPA's
-    ``TrackingLM``.
+    GEPA's safe helper and exposes provider-measured token usage in GEPA's
+    ``TrackingLM``-shaped fields.
     """
 
-    _CHARS_PER_TOKEN = 4
-
     def __init__(
         self,
         *,
-        context_supplier: Callable[[], tuple[str, list[Any]]],
+        context_supplier: Callable[[], tuple[str | dict[str, str], list[Any]]],
         config: Any,
         failure_reporter: Callable[..., None] | None,
         success_reporter: Callable[[str], None] | None,
@@ -46,6 +46,7 @@ class GepaReflectionLM:
         self._success_reporter = success_reporter
         self._total_tokens_in = 0
         self._total_tokens_out = 0
+        self._total_tokens = 0
 
     @property
     def total_cost(self) -> float:
@@ -59,15 +60,46 @@ class GepaReflectionLM:
     def total_tokens_out(self) -> int:
         return self._total_tokens_out
 
+    @property
+    def total_tokens(self) -> int:
+        return self._total_tokens
+
+    def _account_usage(self, usage: Any) -> None:
+        if not isinstance(usage, dict):
+            raise RuntimeError("ALI_1505_PROVIDER_USAGE_MISSING: reflection transport returned no provider usage")
+        try:
+            input_tokens = int(usage["input_tokens"])
+            output_tokens = int(usage["output_tokens"])
+            total_tokens = int(usage["total_tokens"])
+        except (KeyError, TypeError, ValueError) as error:
+            raise RuntimeError("ALI_1505_PROVIDER_USAGE_INVALID: reflection transport returned invalid provider usage") from error
+        if min(input_tokens, output_tokens, total_tokens) < 0:
+            raise RuntimeError("ALI_1505_PROVIDER_USAGE_INVALID: reflection transport returned negative provider usage")
+        self._total_tokens_in += input_tokens
+        self._total_tokens_out += output_tokens
+        self._total_tokens += total_tokens
+
     def __call__(self, gepa_prompt: str) -> str:
-        parent_text, parent_results = self._context_supplier()
+        parent_candidate, parent_results = self._context_supplier()
+        parent_text = (
+            json.dumps(parent_candidate, sort_keys=True, separators=(",", ":"))
+            if isinstance(parent_candidate, dict) and len(parent_candidate) > 1
+            else next(iter(parent_candidate.values()))
+            if isinstance(parent_candidate, dict)
+            else parent_candidate
+        )
         try:
             # Prompt validation is part of the provider attempt. Keep it
             # inside this boundary so GEPA cannot silently swallow its error.
             provider_prompt = build_reflection_prompt(parent_text, parent_results, self._config)
-            self._total_tokens_in += max(1, len(provider_prompt) // self._CHARS_PER_TOKEN)
             result = reflect_with_provider(parent_text, parent_results, self._config)
+            response = result.response
+            provider_prompt = getattr(result, "prompt", provider_prompt)
+            self._account_usage(getattr(result, "usage", None))
         except Exception as error:
+            billable_usage = getattr(error, "usage", None)
+            if billable_usage is not None:
+                self._account_usage(billable_usage)
             if self._failure_reporter is not None:
                 self._failure_reporter(
                     error=error,
@@ -76,17 +108,65 @@ class GepaReflectionLM:
                     parent_results=parent_results,
                 )
             raise
-        response = result.response
-        provider_prompt = getattr(result, "prompt", provider_prompt)
-        self._total_tokens_out += max(1, len(response) // self._CHARS_PER_TOKEN)
         if self._success_reporter is not None:
             self._success_reporter(str(provider_prompt))
         return response
 
+    def reflect(
+        self,
+        candidate: dict[str, str],
+        reflective_dataset: Any,
+        components_to_update: list[str],
+    ) -> tuple[Any, "GepaReflectionLM"]:
+        """Implement GEPA's component-aware ReflectionLM protocol.
+
+        The callable protocol has no selected-component information.  GEPA's
+        newer protocol does, so tuples must use it rather than reverse-engineer
+        a key from a rendered vendor prompt.
+        """
+        from gepa.proposer.reflective_mutation.reflection_lm import ReflectionProposal
+
+        _, parent_results = self._context_supplier()
+        full_candidate = candidate
+        proposal = ReflectionProposal(new_texts={}, prompts={}, raw_lm_outputs={})
+        for component in components_to_update:
+            if component not in candidate:
+                continue
+            parent_text = candidate[component]
+            others = {key: value for key, value in full_candidate.items() if key != component}
+            config = self._config
+            if others:
+                template = config.reflection_prompt_template or DEFAULT_REFLECTION_PROMPT_TEMPLATE
+                config = replace(
+                    config,
+                    reflection_prompt_template=(
+                        f"{template}\n\nOther instruction-set components (read-only): "
+                        f"{json.dumps(others, sort_keys=True, ensure_ascii=False)}"
+                    ),
+                )
+            provider_prompt = ""
+            try:
+                provider_prompt = build_reflection_prompt(parent_text, parent_results, config)
+                result = reflect_with_provider(parent_text, parent_results, config)
+                self._account_usage(getattr(result, "usage", None))
+            except Exception as error:
+                billable_usage = getattr(error, "usage", None)
+                if billable_usage is not None:
+                    self._account_usage(billable_usage)
+                if self._failure_reporter is not None:
+                    self._failure_reporter(error=error, gepa_prompt=provider_prompt, parent_text=parent_text, parent_results=parent_results)
+                raise
+            proposal.new_texts[component] = result.response
+            proposal.prompts[component] = getattr(result, "prompt", provider_prompt)
+            proposal.raw_lm_outputs[component] = result.response
+            if self._success_reporter is not None:
+                self._success_reporter(str(proposal.prompts[component]))
+        return proposal, self
+
 
 def make_gepa_reflection_lm(
     *,
-    context_supplier: Callable[[], tuple[str, list[Any]]],
+    context_supplier: Callable[[], tuple[str | dict[str, str], list[Any]]],
     config: Any,
     failure_reporter: Callable[..., None] | None = None,
     success_reporter: Callable[[str], None] | None = None,