orizu 0.5.20 → 0.5.21

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import os
+from pathlib import Path
 from typing import Any
 from uuid import uuid4
 
@@ -102,11 +103,13 @@ class MandatoryEventSink:
 
 
 def _required_environment() -> dict[str, str]:
-    names = (
-        "ORIZU_PROJECT", "ORIZU_OPTIMIZER_VERSION_ID", "ORIZU_PROMPT_VERSION_ID",
+    names = [
+        "ORIZU_PROJECT", "ORIZU_OPTIMIZER_VERSION_ID",
         "ORIZU_DATASET_VERSION_ID", "ORIZU_SPLIT_SET_ID", "ORIZU_SCORER_VERSION_ID",
         "ORIZU_RUNNER_VERSION_ID", "ORIZU_CANDIDATE_RUNNER_DIR", "ORIZU_SCORER_RUNNER_DIR",
-    )
+    ]
+    if not os.environ.get("ORIZU_INSTRUCTION_SET_PROFILE_VERSION_ID"):
+        names.append("ORIZU_PROMPT_VERSION_ID")
     missing = [name for name in names if not os.environ.get(name)]
     if missing:
         raise RuntimeError("missing connector environment: " + ", ".join(missing))
@@ -219,7 +222,7 @@ def build_config_from_environment() -> TextGepaConfig:
     )
 
 
-def resolved_budget(config: TextGepaConfig, *, trainset_size: int, valset_size: int):
+def resolved_budget(config: TextGepaConfig, *, trainset_size: int, valset_size: int, num_components: int = 1):
     """Resolve the frozen legacy budget once for display *and* enforcement."""
     from orizu_gepa.optimizer import Budget
 
@@ -227,7 +230,7 @@ def resolved_budget(config: TextGepaConfig, *, trainset_size: int, valset_size:
         config,
         trainset_size=trainset_size,
         valset_size=valset_size,
-        num_components=1,
+        num_components=num_components,
     )
 
 
@@ -242,12 +245,23 @@ def validate_launch_contract(
     *,
     candidate_runner_dir: str | None = None,
     scorer_runner_dir: str | None = None,
+    pinned_components: dict[str, Any] | None = None,
+    instruction_set_shape: list[str] | None = None,
+    auto_promote: bool = False,
 ) -> None:
     """Refuse M1-unsupported topology before creating a run row."""
     if _enabled("ORIZU_USE_MERGE") or os.environ.get("ORIZU_MAX_MERGE_INVOCATIONS"):
         raise RuntimeError("merge is unsupported by the official GEPA connector (ALI-1506)")
-    if len(seed_candidate) != 1:
-        raise RuntimeError("multi-component candidates are unsupported by the official GEPA connector (ALI-1507)")
+    pinned = pinned_components or {}
+    if pinned:
+        raise RuntimeError("instruction_set_pinned_components_unsupported: " + ", ".join(sorted(pinned)))
+    if instruction_set_shape is not None:
+        missing = [key for key in instruction_set_shape if key not in seed_candidate]
+        extra = [key for key in seed_candidate if key not in instruction_set_shape]
+        if missing or extra:
+            raise RuntimeError("instruction_set_tuple_shape_mismatch: " + ", ".join(missing or extra))
+    if auto_promote and len(seed_candidate) != 1:
+        raise RuntimeError("instruction_set_candidate_promotion_unsupported")
     if os.environ.get("ORIZU_SAMPLING_STRATEGY") or os.environ.get("ORIZU_SELECTION_STRATEGY"):
         raise RuntimeError("P×N sampling/selection is unsupported by the official GEPA connector (ALI-1507)")
     if candidate_runner_dir is None or scorer_runner_dir is None:
@@ -399,13 +413,16 @@ def run_from_environment() -> dict[str, Any]:
     validation_split = os.environ.get("ORIZU_VALIDATION_SPLIT", "validation")
     config = build_config_from_environment()
     client = OrizuClient.from_env()
+    profile_version_id = os.environ.get("ORIZU_INSTRUCTION_SET_PROFILE_VERSION_ID")
     prompt_context, trainset = client.fetch_exec_context(
-        prompt_version_id=env["ORIZU_PROMPT_VERSION_ID"], runner_version_id=env["ORIZU_RUNNER_VERSION_ID"],
+        prompt_version_id=os.environ.get("ORIZU_PROMPT_VERSION_ID"), runner_version_id=env["ORIZU_RUNNER_VERSION_ID"],
         dataset_version_id=env["ORIZU_DATASET_VERSION_ID"], split_set_id=env["ORIZU_SPLIT_SET_ID"], split=train_split,
+        instruction_set_profile_version_id=profile_version_id,
     )
     _, valset = client.fetch_exec_context(
-        prompt_version_id=env["ORIZU_PROMPT_VERSION_ID"], runner_version_id=env["ORIZU_RUNNER_VERSION_ID"],
+        prompt_version_id=os.environ.get("ORIZU_PROMPT_VERSION_ID"), runner_version_id=env["ORIZU_RUNNER_VERSION_ID"],
         dataset_version_id=env["ORIZU_DATASET_VERSION_ID"], split_set_id=env["ORIZU_SPLIT_SET_ID"], split=validation_split,
+        instruction_set_profile_version_id=profile_version_id,
     )
     scorer_context, _ = client.fetch_scorer_exec_context(
         scorer_version_id=env["ORIZU_SCORER_VERSION_ID"], runner_version_id=os.environ.get("ORIZU_SCORER_RUNNER_VERSION_ID"),
@@ -423,11 +440,20 @@ def run_from_environment() -> dict[str, Any]:
             f"scorer-contract failure before launch for {env['ORIZU_SCORER_VERSION_ID']}: {error}"
         ) from error
     hooks = LifecycleHooks()
-    seed_candidate = {"prompt": prompt_context.body or ""}
+    instruction_set = prompt_context.instruction_set or {}
+    shape = instruction_set.get("shape") if isinstance(instruction_set.get("shape"), list) else None
+    components = instruction_set.get("components") if isinstance(instruction_set.get("components"), dict) else None
+    if profile_version_id and (not shape or not components):
+        raise RuntimeError("instruction_set_tuple_incomplete")
+    seed_candidate = ({key: components[key] for key in shape if isinstance(components.get(key), str)}
+                      if profile_version_id and shape and components else {"prompt": prompt_context.body or ""})
     validate_launch_contract(
         seed_candidate,
         candidate_runner_dir=env["ORIZU_CANDIDATE_RUNNER_DIR"],
         scorer_runner_dir=env["ORIZU_SCORER_RUNNER_DIR"],
+        pinned_components=instruction_set.get("pinned_components") if profile_version_id and isinstance(instruction_set, dict) else None,
+        instruction_set_shape=shape if profile_version_id else None,
+        auto_promote=config.auto_promote,
     )
     preflight_adapter = RunnerEvaluationAdapter(
         candidate_runner_dir=env["ORIZU_CANDIDATE_RUNNER_DIR"], scorer_runner_dir=env["ORIZU_SCORER_RUNNER_DIR"],
@@ -449,7 +475,7 @@ def run_from_environment() -> dict[str, Any]:
     except ScorerContractError as error:
         raise RuntimeError(f"scorer-contract failure before launch for {env['ORIZU_SCORER_VERSION_ID']}: {error}") from error
     preflight_metric_calls = int(preflight_verdict.get("preflight_metric_calls", 0))
-    budget = resolved_budget(config, trainset_size=len(trainset), valset_size=len(valset))
+    budget = resolved_budget(config, trainset_size=len(trainset), valset_size=len(valset), num_components=len(seed_candidate))
     budget_kind, budget_limit = budget.budget_kind, budget.limit
     metadata = {
         **_metadata_from_environment(),
@@ -463,11 +489,23 @@ def run_from_environment() -> dict[str, Any]:
         "dataset_size": len(trainset) + len(valset), "train_count": len(trainset), "validation_count": len(valset),
         "num_threads": preflight_adapter.num_threads_plan.to_payload(),
     }
+    is_multi_component_instruction_set = bool(
+        profile_version_id and isinstance(shape, list) and len(shape) > 1
+    )
     run_id = client.start_run(
         project=env["ORIZU_PROJECT"], optimizer_version_id=env["ORIZU_OPTIMIZER_VERSION_ID"],
-        prompt_version_id=env["ORIZU_PROMPT_VERSION_ID"], scorer_version_id=scorer_context.scorer_version_id or env["ORIZU_SCORER_VERSION_ID"],
+        # A set of one is the legacy prompt subject.  Only a genuine component
+        # map is attributed to the profile version instead of a prompt version.
+        prompt_version_id=(
+            None if is_multi_component_instruction_set else prompt_context.prompt_version_id
+        ),
+        instruction_set_profile_version_id=(
+            profile_version_id if is_multi_component_instruction_set else None
+        ),
+        scorer_version_id=scorer_context.scorer_version_id or env["ORIZU_SCORER_VERSION_ID"],
         dataset_version_id=env["ORIZU_DATASET_VERSION_ID"], split_set_id=env["ORIZU_SPLIT_SET_ID"],
         train_split=train_split, validation_split=validation_split, metadata=metadata,
+        model_config_settings_version_id=instruction_set.get("model_config_settings_version_id") if isinstance(instruction_set, dict) else None,
     )
     print(json.dumps({"optimization_run_id": run_id}), flush=True)
     # The frozen sink treats ``None`` as no local artifact writer.  Keep that
@@ -524,9 +562,40 @@ def run_from_environment() -> dict[str, Any]:
             proposal_count=lambda: callback.candidate_proposals,
         ))
     try:
-        reflection_lm = make_gepa_reflection_lm(
+        proposal_observability: Any | None = None
+        proposal_budget: Any | None = None
+        custom_candidate_proposer = None
+        if os.environ.get("ORIZU_CANDIDATE_PROPOSER") == "skilled-proposer":
+            # DSPy and skilled-proposer are installed only in the manager
+            # published opt-in venv.  Keeping this import inside the exact
+            # selection branch preserves the established no-flag process.
+            from .skilled_proposer_bridge import (
+                ProposalCallBudget,
+                ProposalObservability,
+                make_skilled_proposer_from_environment,
+            )
+            artifact_root = (local_logger.directory if local_logger is not None
+                             else Path.cwd() / ".orizu" / "proposal-observability" / run_id)
+            proposal_budget = ProposalCallBudget(
+                max_calls=_optional_int("ORIZU_PROPOSAL_MAX_CALLS"),
+                max_tokens=_optional_int("ORIZU_PROPOSAL_MAX_TOKENS"),
+            )
+            proposal_observability = ProposalObservability(
+                event_log_root=artifact_root / "proposal-observability",
+                durable_failure_root=artifact_root / "proposal-failures",
+                budget=proposal_budget,
+            )
+            custom_candidate_proposer = make_skilled_proposer_from_environment(
+                config=config,
+                observability=proposal_observability,
+                budget=proposal_budget,
+            )
+            if custom_candidate_proposer is None:
+                raise RuntimeError("ALI_1505_PROPOSER_FACTORY_REFUSED_SELECTED_VALUE")
+
+        reflection_lm = None if custom_candidate_proposer is not None else make_gepa_reflection_lm(
             context_supplier=lambda: (
-                next(iter((adapter.last_candidate or seed_candidate).values())),
+                adapter.last_candidate or seed_candidate,
                 adapter.last_row_evaluations,
             ),
             config=config,
@@ -541,7 +610,10 @@ def run_from_environment() -> dict[str, Any]:
                                    callback=callback, hooks=hooks, max_metric_calls=effective_metric_limit,
                                    stop_callbacks=stoppers, allow_degenerate_seed=config.allow_degenerate_seed,
                                    reflection_lm=reflection_lm, seed_already_validated=True,
-                                   config=config)
+                                   custom_candidate_proposer=custom_candidate_proposer,
+                                   proposal_budget=proposal_budget,
+                                   config=config,
+                                   module_selector=os.environ.get("ORIZU_COMPONENT_SELECTOR", "round_robin").replace("-", "_"))
         require_durable_logging(sink, callback)
         best_id = str(result.best_idx)
         best_score = float(result.val_aggregate_scores[result.best_idx])
@@ -588,7 +660,7 @@ def run_from_environment() -> dict[str, Any]:
             promoted_prompt_version_id = sink.promote_candidate(
                 candidate_id=best_id,
                 prompt_id=prompt_id,
-                parent_prompt_version_id=env["ORIZU_PROMPT_VERSION_ID"],
+                parent_prompt_version_id=prompt_context.prompt_version_id,
                 body=next(iter(best_candidate.values())),
                 body_kind=prompt_context.body_kind,
                 provider_settings=prompt_context.provider_settings,
@@ -596,20 +668,26 @@ def run_from_environment() -> dict[str, Any]:
                 label=config.promotion_label,
             )
         if local_logger is not None:
+            best_candidate = result.candidates[result.best_idx]
             local_logger.write_result(TextGepaResult(
                 run_id=run_id,
                 best_candidate_id=best_id,
-                best_candidate_text=next(iter(result.candidates[result.best_idx].values())),
+                best_candidate_text=(best_candidate if len(best_candidate) > 1
+                                     else next(iter(best_candidate.values()))),
                 best_score=best_score,
                 seed_score=seed_score,
                 promoted_prompt_version_id=promoted_prompt_version_id,
                 budget=budget,
             ))
-            local_logger.write_lm_stats(
-                total_cost=float(getattr(reflection_lm, "total_cost", 0.0)),
-                total_tokens_in=int(getattr(reflection_lm, "total_tokens_in", 0)),
-                total_tokens_out=int(getattr(reflection_lm, "total_tokens_out", 0)),
-            )
+            if proposal_observability is not None:
+                proposal_observability.write_terminal_lm_stats_artifact()
+            else:
+                local_logger.write_lm_stats(
+                    total_cost=float(getattr(reflection_lm, "total_cost", 0.0)),
+                    total_tokens_in=int(getattr(reflection_lm, "total_tokens_in", 0)),
+                    total_tokens_out=int(getattr(reflection_lm, "total_tokens_out", 0)),
+                    total_tokens=int(getattr(reflection_lm, "total_tokens", 0)),
+                )
         if budget_exhausted:
             client.update_run(
                 run_id,

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

@@ -0,0 +1,381 @@
+"""Typed DSPy bridge for the opt-in skilled-proposer integration.
+
+This module deliberately owns proposal-LM observability.  It does not use
+``dspy.LM`` or LiteLLM: every completion reaches the frozen provider transport
+through ``complete_reflection_messages`` and is recorded before DSPy sees its
+response.
+"""
+
+from __future__ import annotations
+
+import atexit
+import dataclasses
+import json
+import os
+import shutil
+import tempfile
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+try:
+    import dspy
+except ModuleNotFoundError as error:
+    if error.name != "dspy":
+        raise
+    dspy = None
+
+if TYPE_CHECKING:
+    import dspy as dspy_types
+
+from orizu_gepa.reflection import ProviderCompletion, complete_reflection_messages
+from orizu_gepa.optimizer import TextGepaConfig
+
+_SELECTION_ENV = "ORIZU_CANDIDATE_PROPOSER"
+_SELECTION_VALUE = "skilled-proposer"
+_SUPPORTED_ROLES = {"system", "user", "assistant"}
+_ALLOWED_DSPY_REQUEST_FIELDS = frozenset({"temperature", "max_tokens", "cache"})
+_DspyBaseLM = dspy.BaseLM if dspy is not None else object
+
+
+def _require_dspy() -> Any:
+    if dspy is None:
+        raise RuntimeError("ALI_1505_DSPY_UNAVAILABLE")
+    return dspy
+
+
+def _usage_totals() -> dict[str, int]:
+    return {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0}
+
+
+def _require_usage(usage: dict[str, int]) -> dict[str, int]:
+    try:
+        normalized = {name: int(usage[name]) for name in _usage_totals()}
+    except (KeyError, TypeError, ValueError) as error:
+        raise RuntimeError("ALI_1505_PROPOSAL_USAGE_INVALID") from error
+    if any(value < 0 for value in normalized.values()):
+        raise RuntimeError("ALI_1505_PROPOSAL_USAGE_INVALID")
+    return normalized
+
+
+@dataclass
+class ProposalCallBudget:
+    """The connector-owned proposal ledger; GEPA metric accounting is separate."""
+
+    max_calls: int | None = None
+    max_tokens: int | None = None
+    call_count: int = 0
+    usage: dict[str, int] = field(default_factory=_usage_totals)
+
+    def record(self, usage: dict[str, int] | None = None) -> None:
+        self.call_count += 1
+        if usage is None:
+            return
+        normalized = _require_usage(usage)
+        for name, value in normalized.items():
+            self.usage[name] += value
+
+    def has_safe_boundary_stop(self) -> bool:
+        return ((self.max_calls is not None and self.call_count >= self.max_calls) or
+                (self.max_tokens is not None and self.usage["total_tokens"] >= self.max_tokens))
+
+
+class ProposalObservability:
+    """Durable per-provider-call proposal evidence and aggregate raw usage."""
+
+    def __init__(self, *, event_log_root: Path, durable_failure_root: Path, budget: ProposalCallBudget | None = None):
+        self.event_log_root = event_log_root
+        self.durable_failure_root = durable_failure_root
+        self.events: list[dict[str, Any]] = []
+        self.budget = budget or ProposalCallBudget()
+        self._temporary_root: Path | None = None
+
+    @classmethod
+    def local_for_test(
+        cls,
+        *,
+        event_log_root: Path | None = None,
+        durable_failure_root: Path | None = None,
+    ) -> "ProposalObservability":
+        root = Path(tempfile.mkdtemp(prefix="orizu-ali1505-proposal-events-"))
+        result = cls(
+            event_log_root=event_log_root or root / "events",
+            durable_failure_root=durable_failure_root or root / "durable-failures",
+        )
+        result._temporary_root = root
+        atexit.register(shutil.rmtree, root, ignore_errors=True)
+        return result
+
+    def bind_budget(self, budget: ProposalCallBudget) -> None:
+        self.budget = budget
+
+    def close(self) -> None:
+        if self._temporary_root is not None:
+            shutil.rmtree(self._temporary_root, ignore_errors=True)
+            self._temporary_root = None
+
+    def __del__(self) -> None:
+        self.close()
+
+    def _append_event(self, event: dict[str, Any]) -> None:
+        self.event_log_root.mkdir(parents=True, exist_ok=True)
+        with (self.event_log_root / "events.jsonl").open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, sort_keys=True) + "\n")
+        self.events.append(event)
+
+    def _write_durable_failure(self, *, code: str, detail: str, correlation_id: str | None = None) -> None:
+        try:
+            self.durable_failure_root.mkdir(parents=True, exist_ok=True)
+            payload: dict[str, Any] = {"source": "skilled_proposer", "code": code, "detail": detail}
+            if correlation_id is not None:
+                payload["correlation_id"] = correlation_id
+            (self.durable_failure_root / "latest.json").write_text(
+                json.dumps(payload, sort_keys=True) + "\n", encoding="utf-8",
+            )
+        except Exception:
+            # The original delivery failure remains the actionable error.  A
+            # second durable-store failure cannot be made durable by retrying it.
+            return
+
+    def record_success(self, event: dict[str, Any], usage: dict[str, int]) -> None:
+        self.budget.record(usage)
+        self._append_event(event)
+
+    def record_provider_failure(
+        self,
+        event: dict[str, Any],
+        *,
+        code: str,
+        detail: str,
+        usage: dict[str, int] | None = None,
+    ) -> None:
+        self.budget.record(usage)
+        self._write_durable_failure(code=code, detail=detail, correlation_id=event.get("correlation_id"))
+        self._append_event(event)
+
+    def record_event_failure(self, error: Exception, *, correlation_id: str) -> None:
+        self._write_durable_failure(
+            code="proposal_observability_event_failed", detail=str(error), correlation_id=correlation_id,
+        )
+
+    def terminal_stats(self) -> dict[str, Any]:
+        return {"call_count": self.budget.call_count, "usage": dict(self.budget.usage)}
+
+    def terminal_lm_stats(self) -> dict[str, int]:
+        return {
+            "total_tokens_in": self.budget.usage["input_tokens"],
+            "total_tokens_out": self.budget.usage["output_tokens"],
+            "total_tokens": self.budget.usage["total_tokens"],
+        }
+
+    def write_terminal_lm_stats_artifact(self) -> str:
+        self.event_log_root.mkdir(parents=True, exist_ok=True)
+        path = self.event_log_root / "lm_stats.json"
+        path.write_text(json.dumps(self.terminal_lm_stats(), sort_keys=True) + "\n", encoding="utf-8")
+        return str(path)
+
+    def read_durable_failure(self) -> dict[str, Any]:
+        return json.loads((self.durable_failure_root / "latest.json").read_text(encoding="utf-8"))
+
+    def has_safe_boundary_stop(self) -> bool:
+        return self.budget.has_safe_boundary_stop()
+
+
+def _reject(message: str, *, code: str = "proposal_dspy_request_rejected") -> Any:
+    return _require_dspy().LMError(message, code=code)
+
+
+def _provider_messages(request: "dspy_types.LMRequest") -> list[dict[str, str]]:
+    if request.tools:
+        raise _reject("proposal_dspy_request_rejected: tools are not supported")
+    messages: list[dict[str, str]] = []
+    for message in request.messages:
+        dumped = message.model_dump()
+        role = dumped.get("role")
+        if role not in _SUPPORTED_ROLES:
+            raise _reject(f"proposal_dspy_request_rejected: unsupported message role {role!r}")
+        text_parts: list[str] = []
+        for part in dumped.get("parts", []):
+            if part.get("type") != "text" or not isinstance(part.get("text"), str):
+                raise _reject("proposal_dspy_request_rejected: only text message parts are supported")
+            text_parts.append(part["text"])
+        if not text_parts:
+            raise _reject("proposal_dspy_request_rejected: text messages must contain at least one text part")
+        messages.append({"role": role, "content": "".join(text_parts)})
+    return messages
+
+
+def _request_config(request: "dspy_types.LMRequest", base: TextGepaConfig) -> TextGepaConfig:
+    config = request.config
+    unsupported = {
+        name: value
+        for name, value in config.model_dump().items()
+        if name not in _ALLOWED_DSPY_REQUEST_FIELDS and value not in (None, {})
+    }
+    if unsupported:
+        raise _reject("proposal_dspy_request_rejected: unsupported DSPy generation configuration")
+    cache = config.cache
+    if cache is not None and (getattr(cache, "enabled", False) or getattr(cache, "rollout_id", None) is not None):
+        raise _reject("proposal_dspy_cache_rejected: proposal response caching is disabled", code="proposal_dspy_cache_rejected")
+    changes: dict[str, Any] = {}
+    if config.temperature is not None:
+        changes["reflection_temperature"] = config.temperature
+    if config.max_tokens is not None:
+        if config.max_tokens <= 0:
+            raise _reject("proposal_dspy_request_rejected: max_tokens must be positive")
+        changes["reflection_max_tokens"] = config.max_tokens
+    return dataclasses.replace(base, **changes) if changes else base
+
+
+def _loopback_endpoint(endpoint: str) -> str:
+    parsed = urlparse(endpoint)
+    if parsed.scheme not in {"http", "https"} or parsed.hostname not in {"127.0.0.1", "::1", "localhost"}:
+        raise ValueError("ALI_1505_BRIDGE_ENDPOINT_OVERRIDE_NOT_LOOPBACK")
+    if parsed.username or parsed.password:
+        raise ValueError("ALI_1505_BRIDGE_ENDPOINT_OVERRIDE_INVALID")
+    return endpoint
+
+
+class OrizuSkilledProposerLM(_DspyBaseLM):
+    """A typed DSPy LM whose only completion path is Orizu's provider transport."""
+
+    forward_contract = "typed_lm"
+
+    def __init__(
+        self,
+        *,
+        config: TextGepaConfig,
+        observability: ProposalObservability,
+        endpoint_override: str | None = None,
+        ssl_cert_file: str | None = None,
+    ) -> None:
+        # Provider retries belong exclusively to the frozen transport.  DSPy
+        # must not retry after a durable-event failure and create unrecorded
+        # duplicate proposal attempts.
+        _require_dspy().BaseLM.__init__(
+            self,
+            config.reflection_model,
+            temperature=config.reflection_temperature,
+            max_tokens=config.reflection_max_tokens,
+            cache=False,
+            num_retries=0,
+        )
+        self._config = config
+        self._observability = observability
+        self._endpoint_override = _loopback_endpoint(endpoint_override) if endpoint_override else None
+        self._ssl_cert_file = ssl_cert_file
+
+    def forward(self, request: "dspy_types.LMRequest") -> "dspy_types.LMResponse":
+        dspy_module = _require_dspy()
+        correlation_id = uuid.uuid4().hex
+        if request.model != self.model:
+            raise _reject(
+                "proposal_dspy_model_rejected: requested model differs from the configured reflection model",
+                code="proposal_dspy_model_rejected",
+            )
+        messages = _provider_messages(request)
+        config = _request_config(request, self._config)
+        try:
+            completion: ProviderCompletion = complete_reflection_messages(
+                model=self.model,
+                messages=messages,
+                config=config,
+                endpoint_override=self._endpoint_override,
+                ssl_cert_file=self._ssl_cert_file,
+                # The explicit loopback harness must never receive a real
+                # provider credential from this process.
+                api_key_override="loopback-test-key" if self._endpoint_override else None,
+            )
+        except Exception as error:
+            provider_code = getattr(error, "code", None)
+            failure_usage = getattr(error, "usage", None)
+            failure_event = {
+                "source": "skilled_proposer",
+                "status": "failure",
+                "attempt": 1,
+                "correlation_id": correlation_id,
+                "provider": "openai" if self.model.startswith("openai/") else "anthropic",
+                "cache_state": "disabled",
+                "failure_code": provider_code or "ALI_1505_PROPOSAL_TRANSPORT_FAILURE",
+            }
+            if failure_usage is not None:
+                failure_event["usage"] = failure_usage
+            try:
+                self._observability.record_provider_failure(
+                    failure_event,
+                    code="proposal_provider_transport_failed",
+                    detail=str(error),
+                    usage=failure_usage,
+                )
+            except Exception as event_error:
+                self._observability.record_event_failure(event_error, correlation_id=correlation_id)
+                raise RuntimeError("proposal_observability_event_failed") from event_error
+            raise dspy_module.LMError(
+                f"proposal_provider_transport_failed: {error}",
+                code="proposal_provider_transport_failed",
+                model=self.model,
+                provider="orizu",
+                provider_code=provider_code,
+            ) from error
+
+        usage = _require_usage(completion.usage)
+        success_event = {
+            "source": "skilled_proposer",
+            "status": "success",
+            "attempt": 1,
+            "correlation_id": correlation_id,
+            "provider": completion.provider,
+            "model": self.model,
+            "request_id": completion.request_id,
+            "latency_ms": completion.latency_ms,
+            "usage": usage,
+            "cache_state": "disabled",
+        }
+        try:
+            self._observability.record_success(success_event, usage)
+        except Exception as error:
+            self._observability.record_event_failure(error, correlation_id=correlation_id)
+            raise RuntimeError("proposal_observability_event_failed") from error
+        return dspy_module.LMResponse.from_text(completion.text, model=self.model, usage=usage, cache_hit=False)
+
+
+def make_skilled_proposer_bridge(
+    *,
+    config: TextGepaConfig,
+    observability: ProposalObservability,
+    budget: ProposalCallBudget,
+    endpoint_override: str | None = None,
+    ssl_cert_file: str | None = None,
+) -> OrizuSkilledProposerLM:
+    """Create the cache-disabled typed LM passed to unmodified SkilledProposer."""
+    observability.bind_budget(budget)
+    return OrizuSkilledProposerLM(
+        config=config,
+        observability=observability,
+        endpoint_override=endpoint_override,
+        ssl_cert_file=ssl_cert_file,
+    )
+
+
+def make_skilled_proposer_from_environment(
+    *,
+    config: TextGepaConfig,
+    observability: ProposalObservability,
+    budget: ProposalCallBudget | None = None,
+    endpoint_override: str | None = None,
+) -> Any | None:
+    """Create the opt-in proposer only for the exact selected environment value."""
+    if os.environ.get(_SELECTION_ENV) != _SELECTION_VALUE:
+        return None
+    from skilled_proposer import SkilledProposer
+
+    bridge = make_skilled_proposer_bridge(
+        config=config,
+        observability=observability,
+        budget=budget or ProposalCallBudget(),
+        endpoint_override=endpoint_override,
+        ssl_cert_file=os.environ.get("SSL_CERT_FILE"),
+    )
+    return SkilledProposer(prompt_model=bridge)

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

@@ -36,3 +36,20 @@ class MaxCandidateProposalsStopper:
 
     def __call__(self, state):
         return self.proposal_count() >= self.max_candidate_proposals
+
+
+class ProposalBudgetStopper:
+    """Stop only between GEPA iterations after an owned proposal budget trips.
+
+    A custom candidate proposer does not pass through GEPA's ``reflection_lm``
+    or its cost tracking.  Its typed DSPy bridge instead records raw provider
+    usage in an Orizu-owned ledger.  This stopper deliberately reads only that
+    ledger and never changes ``state.total_num_evals``: metric-call budgeting
+    remains evaluator-only.
+    """
+
+    def __init__(self, proposal_budget):
+        self.proposal_budget = proposal_budget
+
+    def __call__(self, state):
+        return self.proposal_budget.has_safe_boundary_stop() and state.i >= 0

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

@@ -98,9 +98,10 @@ def translate_callback(event_name: str, event: dict[str, Any], *, run_id: str, *
 
     if event_name == "on_optimization_start":
         event_type = "run_started"
+        payload.pop("components", None)
         payload.update({
             "seed_candidate_text": next(iter(components.values()), None),
-            "components": components,
+            "seed_components": components,
             "trainset_size": event.get("trainset_size"),
             "valset_size": event.get("valset_size"),
         })