orizu 0.5.19 → 0.5.21

package/vendor/gepa-python/src/gepa/utils/stdio_capture.py

@@ -0,0 +1,145 @@
+"""
+Thread-safe stdout/stderr capture utilities for GEPA evaluation.
+
+When ``capture_stdio=True`` is set in :class:`EngineConfig`, these utilities
+replace ``sys.stdout`` and ``sys.stderr`` with per-thread wrappers so that
+print output produced inside an evaluator is captured without polluting the
+main process output or leaking between concurrent evaluations.
+
+Classes:
+    ThreadLocalStreamCapture: A ``sys.stdout``/``sys.stderr`` replacement
+        that routes writes to a private buffer on threads that have opted in,
+        while passing all other threads through to the original stream.
+    StreamCaptureManager: Reference-counted manager that installs/removes the
+        capture wrappers, allowing multiple concurrent ``optimize_anything``
+        calls to share them safely.
+"""
+
+import io
+import sys
+import threading
+from typing import Any
+
+
+class ThreadLocalStreamCapture:
+    """A ``sys.stdout`` / ``sys.stderr`` replacement that captures output per-thread.
+
+    Threads that have called :meth:`start_capture` get their writes routed to a
+    private ``StringIO``; all other threads pass through to the original stream.
+    """
+
+    def __init__(self, original: Any) -> None:
+        self._original = original
+        self._local = threading.local()
+
+    # -- file-like interface --------------------------------------------------
+
+    def write(self, text: str) -> int:
+        if getattr(self._local, "capturing", False):
+            return self._local.buffer.write(text)
+        return self._original.write(text)
+
+    def flush(self) -> None:
+        if getattr(self._local, "capturing", False):
+            self._local.buffer.flush()
+        self._original.flush()
+
+    def fileno(self) -> int:
+        # Always delegate to the original stream so that libraries (tqdm, rich,
+        # subprocess, logging handlers, etc.) that call sys.stdout.fileno()
+        # continue to work even while this thread is being captured.
+        return self._original.fileno()
+
+    @property
+    def encoding(self) -> str:
+        return self._original.encoding
+
+    @property
+    def errors(self) -> str | None:
+        return self._original.errors
+
+    def isatty(self) -> bool:
+        if getattr(self._local, "capturing", False):
+            return False
+        return self._original.isatty()
+
+    def writable(self) -> bool:
+        return True
+
+    def readable(self) -> bool:
+        return False
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._original, name)
+
+    # -- capture control ------------------------------------------------------
+
+    def start_capture(self) -> None:
+        """Start capturing for the current thread."""
+        assert not getattr(self._local, "capturing", False), (
+            "start_capture() called while already capturing on this thread. "
+            "Call stop_capture() first to retrieve the buffered output."
+        )
+        self._local.capturing = True
+        self._local.buffer = io.StringIO()
+
+    def stop_capture(self) -> str:
+        """Stop capturing and return the captured text for the current thread.
+
+        Safe to call even if :meth:`start_capture` was never called on this
+        thread — returns an empty string in that case.
+        """
+        if not getattr(self._local, "capturing", False):
+            return ""
+        self._local.capturing = False
+        text = self._local.buffer.getvalue()
+        self._local.buffer = io.StringIO()
+        return text
+
+
+class StreamCaptureManager:
+    """Reference-counted manager for per-thread stdout/stderr capture.
+
+    Allows multiple concurrent optimize_anything calls with capture_stdio=True
+    to share the same stream wrappers. sys.stdout/stderr are only restored when
+    the last user releases.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._refcount = 0
+        self._stdout_capturer: ThreadLocalStreamCapture | None = None
+        self._stderr_capturer: ThreadLocalStreamCapture | None = None
+        self._original_stdout: Any = None
+        self._original_stderr: Any = None
+
+    def acquire(self) -> tuple[ThreadLocalStreamCapture, ThreadLocalStreamCapture]:
+        """Install capture wrappers (or reuse existing). Returns (stdout_cap, stderr_cap)."""
+        with self._lock:
+            if self._refcount == 0:
+                self._original_stdout = sys.stdout
+                self._original_stderr = sys.stderr
+                self._stdout_capturer = ThreadLocalStreamCapture(sys.stdout)
+                self._stderr_capturer = ThreadLocalStreamCapture(sys.stderr)
+                sys.stdout = self._stdout_capturer  # type: ignore[assignment]
+                sys.stderr = self._stderr_capturer  # type: ignore[assignment]
+            self._refcount += 1
+            assert self._stdout_capturer is not None and self._stderr_capturer is not None
+            return self._stdout_capturer, self._stderr_capturer
+
+    def release(self) -> None:
+        """Decrement ref count. Restores original streams when last user releases."""
+        with self._lock:
+            self._refcount -= 1
+            if self._refcount <= 0:
+                if self._original_stdout is not None:
+                    sys.stdout = self._original_stdout
+                if self._original_stderr is not None:
+                    sys.stderr = self._original_stderr
+                self._stdout_capturer = None
+                self._stderr_capturer = None
+                self._refcount = 0
+
+
+# Module-level singleton shared across all optimize_anything calls.
+stream_manager = StreamCaptureManager()

package/vendor/gepa-python/src/gepa/utils/stop_condition.py

@@ -0,0 +1,230 @@
+"""
+Utility functions for graceful stopping of GEPA runs.
+"""
+
+import os
+import signal
+import time
+from typing import Literal, Protocol, runtime_checkable
+
+from gepa.core.state import GEPAState
+
+
+@runtime_checkable
+class StopperProtocol(Protocol):
+    """
+    Protocol for stop condition objects.
+
+    A stopper is a callable object that returns True when the optimization should stop.
+    """
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        """
+        Check if the optimization should stop.
+
+        Args:
+            gepa_state: The current GEPA state containing optimization information
+
+        Returns:
+            True if the optimization should stop, False otherwise.
+        """
+        ...
+
+
+class TimeoutStopCondition(StopperProtocol):
+    """Stop callback that stops after a specified timeout."""
+
+    def __init__(self, timeout_seconds: float):
+        self.timeout_seconds = timeout_seconds
+        self.start_time = time.time()
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        # return true if timeout has been reached
+        return time.time() - self.start_time > self.timeout_seconds
+
+
+class FileStopper(StopperProtocol):
+    """
+    Stop callback that stops when a specific file exists.
+    """
+
+    def __init__(self, stop_file_path: str):
+        self.stop_file_path = stop_file_path
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        # returns true if stop file exists
+        return os.path.exists(self.stop_file_path)
+
+    def remove_stop_file(self):
+        # remove the stop file
+        if os.path.exists(self.stop_file_path):
+            os.remove(self.stop_file_path)
+
+
+class ScoreThresholdStopper(StopperProtocol):
+    """
+    Stop callback that stops when a score threshold is reached.
+    """
+
+    def __init__(self, threshold: float):
+        self.threshold = threshold
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        # return true if score threshold is reached
+        try:
+            current_best_score = (
+                max(gepa_state.program_full_scores_val_set) if gepa_state.program_full_scores_val_set else 0.0
+            )
+            return current_best_score >= self.threshold
+        except Exception:
+            return False
+
+
+class NoImprovementStopper(StopperProtocol):
+    """
+    Stop callback that stops after a specified number of iterations without improvement.
+    """
+
+    def __init__(self, max_iterations_without_improvement: int):
+        self.max_iterations_without_improvement = max_iterations_without_improvement
+        self.best_score = float("-inf")
+        self.iterations_without_improvement = 0
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        # return true if max iterations without improvement reached
+        try:
+            current_score = (
+                max(gepa_state.program_full_scores_val_set) if gepa_state.program_full_scores_val_set else 0.0
+            )
+            if current_score > self.best_score:
+                self.best_score = current_score
+                self.iterations_without_improvement = 0
+            else:
+                self.iterations_without_improvement += 1
+
+            return self.iterations_without_improvement >= self.max_iterations_without_improvement
+        except Exception:
+            return False
+
+    def reset(self):
+        """Reset the counter (useful when manually improving the score)."""
+        self.iterations_without_improvement = 0
+
+
+class SignalStopper(StopperProtocol):
+    """Stop callback that stops when a signal is received."""
+
+    def __init__(self, signals=None):
+        self.signals = signals or [signal.SIGINT, signal.SIGTERM]
+        self._stop_requested = False
+        self._original_handlers = {}
+        self._setup_signal_handlers()
+
+    def _setup_signal_handlers(self):
+        """Set up signal handlers for graceful shutdown."""
+
+        def signal_handler(signum, frame):
+            self._stop_requested = True
+
+        # Store original handlers and set new ones
+        for sig in self.signals:
+            try:
+                self._original_handlers[sig] = signal.signal(sig, signal_handler)
+            except (OSError, ValueError):
+                # Signal not available on this platform
+                pass
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        # return true if a signal was received
+        return self._stop_requested
+
+    def cleanup(self):
+        """Restore original signal handlers."""
+        for sig, handler in self._original_handlers.items():
+            try:
+                signal.signal(sig, handler)
+            except (OSError, ValueError):
+                pass
+
+
+class MaxTrackedCandidatesStopper(StopperProtocol):
+    """
+    Stop callback that stops after a maximum number of tracked candidates.
+    """
+
+    def __init__(self, max_tracked_candidates: int):
+        self.max_tracked_candidates = max_tracked_candidates
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        # return true if max tracked candidates reached
+        return len(gepa_state.program_candidates) >= self.max_tracked_candidates
+
+
+class MaxMetricCallsStopper(StopperProtocol):
+    """
+    Stop callback that stops after a maximum number of metric calls.
+    """
+
+    def __init__(self, max_metric_calls: int):
+        self.max_metric_calls = max_metric_calls
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        # return true if max metric calls reached
+        return gepa_state.total_num_evals >= self.max_metric_calls
+
+
+class MaxReflectionCostStopper(StopperProtocol):
+    """Stop once the reflection LM's cumulative cost (USD) reaches a budget.
+
+    Reads ``lm.total_cost`` from the :class:`~gepa.lm.LM` instance passed
+    at construction time.  Custom callables wrapped in ``TrackingLM``
+    always report ``0.0`` cost and never trip this stopper.
+    """
+
+    def __init__(self, max_reflection_cost_usd: float, reflection_lm: object | None = None):
+        self.max_reflection_cost_usd = max_reflection_cost_usd
+        self._reflection_lm = reflection_lm
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        cost = getattr(self._reflection_lm, "total_cost", 0.0)
+        return cost >= self.max_reflection_cost_usd
+
+
+class MaxCandidateProposalsStopper(StopperProtocol):
+    """
+    Stop callback that stops after a maximum number of candidate proposals.
+
+    Note: state.i starts at -1, and is incremented at the START of each loop iteration.
+    The stopper is checked BEFORE the increment, so when state.i = N-1, we're about to
+    run proposal N. To allow exactly max_proposals proposals, we stop when
+    state.i >= max_proposals - 1 (i.e., we've completed max_proposals proposals).
+    """
+
+    def __init__(self, max_proposals: int):
+        self.max_proposals = max_proposals
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        return gepa_state.i >= self.max_proposals - 1
+
+
+class CompositeStopper(StopperProtocol):
+    """
+    Stop callback that combines multiple stopping conditions.
+
+    Allows combining several stoppers and stopping when any or all of them are triggered.
+    """
+
+    def __init__(self, *stoppers: StopperProtocol, mode: Literal["any", "all"] = "any"):
+        # initialize composite stopper
+
+        self.stoppers = stoppers
+        self.mode = mode
+
+    def __call__(self, gepa_state: GEPAState) -> bool:
+        # return true if stopping condition is met
+        if self.mode == "any":
+            return any(stopper(gepa_state) for stopper in self.stoppers)
+        elif self.mode == "all":
+            return all(stopper(gepa_state) for stopper in self.stoppers)
+        else:
+            raise ValueError(f"Unknown mode: {self.mode}")