orizu 0.3.7 → 0.4.1

package/vendor/orizu-gepa-python/src/orizu_gepa/optimizer.py

@@ -44,7 +44,7 @@ Return only the complete updated parameter text, exactly as it should be used by
 Do not include analysis, explanation, labels, XML tags, or a surrounding markdown code fence.
 Your response will be used verbatim as the next candidate."""
 
-AUTO_NUM_THREADS_HARD_CAP = 8
+AUTO_NUM_THREADS_HARD_CAP = 64
 AUTO_NUM_THREADS_WORKER_MEMORY_BYTES = 512 * 1024 * 1024
 AUTO_NUM_THREADS_MEMORY_RESERVE_BYTES = 1024 * 1024 * 1024
 AUTO_NUM_THREADS_FD_HEADROOM = 64
@@ -142,6 +142,10 @@ class ReflectionResult:
     candidate_text: str
 
 
+class RetryableReflectionError(RuntimeError):
+    """Raised when a transient reflection-provider failure remains after retries."""
+
+
 def _dspy_auto_metric_budget(
     *,
     num_components: int,
@@ -170,13 +174,37 @@ def _dspy_auto_metric_budget(
     return total
 
 
+def _approx_metric_calls_for_candidate_budget(
+    *,
+    candidate_proposals: int,
+    trainset_size: int,
+    valset_size: int,
+    minibatch_size: int,
+) -> int:
+    """Estimate row-level metric calls for proposal-count budgets."""
+    safe_proposals = max(0, candidate_proposals)
+    safe_valset_size = max(0, valset_size)
+    safe_trainset_size = max(0, trainset_size)
+    safe_minibatch_size = max(0, minibatch_size)
+    sampled_train_rows = min(safe_trainset_size, safe_minibatch_size)
+    per_iteration = (2 * sampled_train_rows) + safe_valset_size
+    return safe_valset_size + (safe_proposals * per_iteration)
+
+
 @dataclass
 class Budget:
     budget_kind: str
     limit: int
+    approx_metric_call_limit: int | None = None
     used_metric_calls: int = 0
+    used_reflection_failure_metric_charges: int = 0
     used_full_evals: int = 0
     used_candidate_proposals: int = 0
+    used_iterations: int = 0
+
+    def __post_init__(self) -> None:
+        if self.approx_metric_call_limit is None and self.budget_kind == "max_metric_calls":
+            self.approx_metric_call_limit = self.limit
 
     @classmethod
     def from_config(
@@ -188,11 +216,33 @@ class Budget:
         num_components: int = 1,
     ) -> "Budget":
         if config.max_metric_calls is not None:
-            return cls("max_metric_calls", config.max_metric_calls)
+            return cls(
+                "max_metric_calls",
+                config.max_metric_calls,
+                approx_metric_call_limit=config.max_metric_calls,
+            )
         if config.max_full_evals is not None:
-            return cls("max_metric_calls", config.max_full_evals * (trainset_size + valset_size))
+            metric_limit = config.max_full_evals * (trainset_size + valset_size)
+            return cls(
+                "max_metric_calls",
+                metric_limit,
+                approx_metric_call_limit=metric_limit,
+            )
         if config.max_candidate_proposals is not None:
-            return cls("max_candidate_proposals", config.max_candidate_proposals)
+            return cls(
+                "max_candidate_proposals",
+                config.max_candidate_proposals,
+                approx_metric_call_limit=_approx_metric_calls_for_candidate_budget(
+                    candidate_proposals=config.max_candidate_proposals,
+                    trainset_size=trainset_size,
+                    valset_size=valset_size,
+                    minibatch_size=config.minibatch_size,
+                ),
+            )
+        if config.max_iterations is not None:
+            return cls("max_iterations", config.max_iterations)
+        if not config.budget:
+            raise ValueError("No optimization budget configured.")
         preset = "medium" if config.budget == "auto" else config.budget
         preset_candidates = {
             "light": 6,
@@ -200,46 +250,106 @@ class Budget:
             "heavy": 18,
             "high": 18,
         }.get(preset, 6)
+        metric_limit = _dspy_auto_metric_budget(
+            num_components=num_components,
+            num_candidates=preset_candidates,
+            valset_size=valset_size,
+        )
         return cls(
             "max_metric_calls",
-            _dspy_auto_metric_budget(
-                num_components=num_components,
-                num_candidates=preset_candidates,
-                valset_size=valset_size,
-            ),
+            metric_limit,
+            approx_metric_call_limit=metric_limit,
         )
 
+    @property
+    def metric_budget_used(self) -> int:
+        return self.used_metric_calls + self.used_reflection_failure_metric_charges
+
     @property
     def used(self) -> int:
         if self.budget_kind == "max_full_evals":
             return self.used_full_evals
         if self.budget_kind == "max_candidate_proposals":
             return self.used_candidate_proposals
-        return self.used_metric_calls
+        if self.budget_kind == "max_iterations":
+            return self.used_iterations
+        return self.metric_budget_used
 
     @property
     def remaining(self) -> int:
         return max(0, self.limit - self.used)
 
+    @property
+    def metric_calls_remaining(self) -> int:
+        if self.approx_metric_call_limit is None:
+            return 0
+        if self.remaining == 0:
+            return 0
+        return max(0, self.approx_metric_call_limit - self.metric_budget_used)
+
+    @property
+    def progress_percent(self) -> float:
+        if self.remaining == 0:
+            return 100.0
+        if self.approx_metric_call_limit is None:
+            if self.limit <= 0:
+                return 100.0 if self.used > 0 else 0.0
+            return min(100.0, max(0.0, (self.used / self.limit) * 100.0))
+        if self.approx_metric_call_limit <= 0:
+            # A zero-sized budget with any recorded metric work should still read as complete.
+            return 100.0 if self.metric_budget_used > 0 else 0.0
+        return min(100.0, max(0.0, (self.metric_budget_used / self.approx_metric_call_limit) * 100.0))
+
     def allows_iteration(self) -> bool:
         return self.remaining > 0
 
+    def charge_retryable_reflection_failure(self) -> None:
+        if self.budget_kind == "max_metric_calls":
+            self.used_reflection_failure_metric_charges += 1
+
     def to_payload(self) -> dict[str, Any]:
         return {
             "budget_kind": self.budget_kind,
             "limit": self.limit,
             "used": self.used,
             "remaining": self.remaining,
+            "approx_metric_call_limit": self.approx_metric_call_limit,
+            "metric_call_budget": self.approx_metric_call_limit,
+            "metric_calls_remaining": self.metric_calls_remaining,
+            "metric_budget_used": self.metric_budget_used,
             "used_metric_calls": self.used_metric_calls,
+            "used_reflection_failure_metric_charges": self.used_reflection_failure_metric_charges,
             "used_full_evals": self.used_full_evals,
             "used_candidate_proposals": self.used_candidate_proposals,
+            "used_iterations": self.used_iterations,
+            "iteration_budget": self.limit if self.budget_kind == "max_iterations" else None,
+            "iterations_remaining": self.remaining if self.budget_kind == "max_iterations" else None,
+        }
+
+    def progress_payload(self, *, stage: str, iteration: int | None) -> dict[str, Any]:
+        percent = round(self.progress_percent, 1)
+        return {
+            "stage": stage,
+            "iteration": iteration,
+            "percent": percent,
+            "progress_percent": percent,
+            "metric_calls_used": self.used_metric_calls,
+            "metric_budget_used": self.metric_budget_used,
+            "metric_call_budget": self.approx_metric_call_limit,
+            "approx_metric_call_budget": self.approx_metric_call_limit,
+            "metric_calls_remaining": self.metric_calls_remaining,
+            "is_over_budget": (
+                self.approx_metric_call_limit is not None and
+                self.metric_budget_used > self.approx_metric_call_limit
+            ),
+            "budget": self.to_payload(),
         }
 
 
 @dataclass(frozen=True)
 class TextGepaConfig:
-    budget: str = "light"
-    max_iterations: int = 3
+    budget: str | None = "auto"
+    max_iterations: int | None = None
     minibatch_size: int = 3
     num_threads: int | str = "auto"
     candidate_selection_strategy: str = "pareto"
@@ -250,6 +360,8 @@ class TextGepaConfig:
     reflection_model: str = "anthropic/claude-opus-4-7"
     reflection_temperature: float | None = None
     reflection_max_tokens: int | None = None
+    reflection_retry_attempts: int = 3
+    reflection_http_timeout_seconds: int = 180
     reflection_prompt_template: str | None = None
     reflection_provider_settings: dict[str, Any] = field(default_factory=dict)
     objective: str = "Improve this text candidate to maximize evaluator score while preserving intended behavior."
@@ -524,7 +636,8 @@ def resolve_num_threads(
     parsed = _parse_requested_num_threads(requested)
     row_bound = max(1, max(minibatch_size, validation_count))
     detected_cpu_count = cpu_count if cpu_count is not None else os.cpu_count()
-    cpu_bound = max(1, detected_cpu_count or 1)
+    normalized_cpu_count = max(1, detected_cpu_count or 1)
+    cpu_bound = normalized_cpu_count * 2
     resolved_hard_cap = hard_cap or _positive_int_env(
         "ORIZU_GEPA_AUTO_THREADS_MAX",
         AUTO_NUM_THREADS_HARD_CAP,
@@ -960,10 +1073,30 @@ def evaluate_candidate(
     ]
 
 
+def _log_iteration_progress(
+    event_sink: EventSink,
+    *,
+    budget: Budget,
+    iteration: int,
+    candidate_id: str | None,
+) -> None:
+    event_sink.log_event(
+        "optimization_progress",
+        budget.progress_payload(stage="iteration_completed", iteration=iteration),
+        event_layer="extension",
+        iteration=iteration,
+        candidate_id=candidate_id,
+    )
+
+
 def _completed_all_rows(results: list[RowEvaluation], rows: list[DatasetRow]) -> bool:
     return len(results) == len(rows)
 
 
+def _has_future_iteration(config: TextGepaConfig, iteration: int) -> bool:
+    return config.max_iterations is None or iteration < config.max_iterations
+
+
 def optimize_loaded_text_candidate(
     *,
     run_id: str,
@@ -998,6 +1131,7 @@ def optimize_loaded_text_candidate(
     metric_key = _metric_key(scorer_context)
     higher_is_better = scorer_context.higher_is_better
     budget_exhausted = False
+    failed_reflection_count = 0
 
     try:
         event_sink.log_event("run_started", {
@@ -1095,7 +1229,8 @@ def optimize_loaded_text_candidate(
             )
             budget_exhausted = True
 
-        for iteration in range(1, config.max_iterations + 1):
+        iteration = 1
+        while config.max_iterations is None or iteration <= config.max_iterations:
             if not budget.allows_iteration():
                 break
 
@@ -1215,6 +1350,7 @@ def optimize_loaded_text_candidate(
                     iteration=iteration,
                     candidate_id=parent_candidate_id,
                 )
+                budget.used_iterations += 1
                 event_sink.log_event("budget_updated", budget.to_payload(), event_layer="extension", iteration=iteration)
                 event_sink.log_event(
                     "iteration_completed",
@@ -1233,7 +1369,13 @@ def optimize_loaded_text_candidate(
                     iteration=iteration,
                     candidate_id=best_candidate_id,
                 )
-                if iteration < config.max_iterations and not budget.allows_iteration():
+                _log_iteration_progress(
+                    event_sink,
+                    budget=budget,
+                    iteration=iteration,
+                    candidate_id=best_candidate_id,
+                )
+                if _has_future_iteration(config, iteration) and not budget.allows_iteration():
                     event_sink.log_event(
                         "budget_exhausted",
                         {
@@ -1248,6 +1390,7 @@ def optimize_loaded_text_candidate(
                     )
                     budget_exhausted = True
                     break
+                iteration += 1
                 continue
 
             event_sink.log_event(
@@ -1261,7 +1404,68 @@ def optimize_loaded_text_candidate(
                 iteration=iteration,
                 candidate_id=parent_candidate_id,
             )
-            reflection = reflector(parent_text, parent_results, config)
+            try:
+                reflection = reflector(parent_text, parent_results, config)
+            except RetryableReflectionError as error:
+                failed_reflection_count += 1
+                budget.used_candidate_proposals += 1
+                budget.used_iterations += 1
+                budget.charge_retryable_reflection_failure()
+                event_sink.log_event(
+                    "reflection_failed",
+                    {
+                        "parent_candidate_id": parent_candidate_id,
+                        "row_ids": [row.id for row in minibatch],
+                        "error": str(error),
+                        "error_type": type(error).__name__,
+                        "budget": budget.to_payload(),
+                    },
+                    event_layer="extension",
+                    iteration=iteration,
+                    candidate_id=parent_candidate_id,
+                )
+                event_sink.log_event("budget_updated", budget.to_payload(), event_layer="extension", iteration=iteration)
+                event_sink.log_event(
+                    "iteration_completed",
+                    {
+                        "parent_candidate_id": parent_candidate_id,
+                        "child_candidate_id": None,
+                        "parent_train_score_total": parent_total,
+                        "child_train_score_total": None,
+                        "child_validation_score": None,
+                        "best_candidate_id": best_candidate_id,
+                        "best_validation_score": best_score,
+                        "reflection_failed": True,
+                        "reflection_error": str(error),
+                        "reflection_error_type": type(error).__name__,
+                        "budget": budget.to_payload(),
+                    },
+                    iteration=iteration,
+                    candidate_id=best_candidate_id,
+                )
+                _log_iteration_progress(
+                    event_sink,
+                    budget=budget,
+                    iteration=iteration,
+                    candidate_id=best_candidate_id,
+                )
+                if _has_future_iteration(config, iteration) and not budget.allows_iteration():
+                    event_sink.log_event(
+                        "budget_exhausted",
+                        {
+                            "stage": "iteration_completed",
+                            "completed_iteration": iteration,
+                            "budget": budget.to_payload(),
+                            "decision_rule": "budget is checked only between iterations",
+                        },
+                        event_layer="extension",
+                        iteration=iteration,
+                        candidate_id=best_candidate_id,
+                    )
+                    budget_exhausted = True
+                    break
+                iteration += 1
+                continue
             child_id = _candidate_id(iteration, reflection.candidate_text)
             child_text = reflection.candidate_text
             candidate_text_by_id[child_id] = child_text
@@ -1523,6 +1727,7 @@ def optimize_loaded_text_candidate(
                     parent_candidate_id=parent_candidate_id,
                 )
 
+            budget.used_iterations += 1
             event_sink.log_event("budget_updated", budget.to_payload(), event_layer="extension", iteration=iteration)
             event_sink.log_event(
                 "iteration_completed",
@@ -1539,7 +1744,13 @@ def optimize_loaded_text_candidate(
                 iteration=iteration,
                 candidate_id=best_candidate_id,
             )
-            if iteration < config.max_iterations and not budget.allows_iteration():
+            _log_iteration_progress(
+                event_sink,
+                budget=budget,
+                iteration=iteration,
+                candidate_id=best_candidate_id,
+            )
+            if _has_future_iteration(config, iteration) and not budget.allows_iteration():
                 event_sink.log_event(
                     "budget_exhausted",
                     {
@@ -1554,6 +1765,7 @@ def optimize_loaded_text_candidate(
                 )
                 budget_exhausted = True
                 break
+            iteration += 1
 
         if budget_exhausted:
             event_sink.log_event(
@@ -1565,6 +1777,7 @@ def optimize_loaded_text_candidate(
                     "seed_validation_score": seed_score,
                     "higher_is_better": higher_is_better,
                     "budget": budget.to_payload(),
+                    "failed_reflection_count": failed_reflection_count,
                 },
             )
             event_sink.finish_run(
@@ -1575,6 +1788,7 @@ def optimize_loaded_text_candidate(
                     "seed_score": seed_score,
                     "budget": budget.to_payload(),
                     "pause_reason": "budget_exhausted",
+                    "failed_reflection_count": failed_reflection_count,
                 },
             )
             return TextGepaResult(
@@ -1613,6 +1827,7 @@ def optimize_loaded_text_candidate(
                 "metric_key": metric_key,
                 "higher_is_better": higher_is_better,
                 "budget": budget.to_payload(),
+                "failed_reflection_count": failed_reflection_count,
             },
         )
         event_sink.finish_run(
@@ -1625,6 +1840,7 @@ def optimize_loaded_text_candidate(
                 "metric_key": metric_key,
                 "higher_is_better": higher_is_better,
                 "budget": budget.to_payload(),
+                "failed_reflection_count": failed_reflection_count,
             },
         )
         return TextGepaResult(

package/vendor/orizu-gepa-python/src/orizu_gepa/reflection.py

@@ -2,14 +2,31 @@ from __future__ import annotations
 
 import json
 import os
+import random
+import socket
 import ssl
 import subprocess
 import tempfile
+import time
 import urllib.error
 import urllib.request
+from collections.abc import Callable
 from typing import Any
 
-from .optimizer import ReflectionResult, RowEvaluation, TextGepaConfig, build_reflection_prompt, extract_candidate_text
+from .optimizer import (
+    ReflectionResult,
+    RetryableReflectionError,
+    RowEvaluation,
+    TextGepaConfig,
+    build_reflection_prompt,
+    extract_candidate_text,
+)
+
+
+RETRYABLE_HTTP_STATUS_CODES = {429, 500, 502, 503, 504, 529}
+RETRY_BACKOFF_BASE_SECONDS = 5.0
+RETRY_BACKOFF_JITTER_SECONDS = 5.0
+RETRYABLE_DIRECT_ERRORS = (TimeoutError, socket.timeout, ConnectionResetError, ConnectionAbortedError)
 
 
 def _read_anthropic_response_with_curl(api_key: str, payload: dict[str, Any]) -> dict[str, Any]:
@@ -40,6 +57,73 @@ def _read_anthropic_response_with_curl(api_key: str, payload: dict[str, Any]) ->
     return json.loads(result.stdout)
 
 
+def _validate_positive_http_config(value: int, name: str) -> int:
+    if value <= 0:
+        raise RuntimeError(f"{name} must be positive")
+    return value
+
+
+def _retry_backoff_seconds(attempt: int) -> float:
+    return (RETRY_BACKOFF_BASE_SECONDS * (2 ** attempt)) + random.uniform(0, RETRY_BACKOFF_JITTER_SECONDS)
+
+
+def _is_retryable_http_status(status_code: int) -> bool:
+    return status_code in RETRYABLE_HTTP_STATUS_CODES
+
+
+def _is_retryable_url_error(error: urllib.error.URLError) -> bool:
+    return isinstance(error.reason, RETRYABLE_DIRECT_ERRORS)
+
+
+def _read_json_response_with_retries(
+    request: urllib.request.Request,
+    *,
+    timeout_seconds: int,
+    retry_attempts: int,
+    failure_prefix: str,
+    ssl_fallback: Callable[[], dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    timeout_seconds = _validate_positive_http_config(timeout_seconds, "reflection_http_timeout_seconds")
+    retry_attempts = _validate_positive_http_config(retry_attempts, "reflection_retry_attempts")
+
+    for attempt in range(retry_attempts):
+        try:
+            with urllib.request.urlopen(request, timeout=timeout_seconds) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as error:
+            if _is_retryable_http_status(error.code) and attempt < retry_attempts - 1:
+                time.sleep(_retry_backoff_seconds(attempt))
+                continue
+            detail = error.read().decode("utf-8", errors="replace")
+            if _is_retryable_http_status(error.code):
+                raise RetryableReflectionError(
+                    f"{failure_prefix} retryable HTTP failure after {retry_attempts} attempts: "
+                    f"{error.code} {detail}"
+                ) from error
+            raise RuntimeError(f"{failure_prefix}: {error.code} {detail}") from error
+        except urllib.error.URLError as error:
+            if isinstance(error.reason, ssl.SSLCertVerificationError) and ssl_fallback is not None:
+                return ssl_fallback()
+            if _is_retryable_url_error(error):
+                if attempt < retry_attempts - 1:
+                    time.sleep(_retry_backoff_seconds(attempt))
+                    continue
+                raise RetryableReflectionError(
+                    f"{failure_prefix} retryable connection failure after {retry_attempts} attempts: "
+                    f"{error.reason}"
+                ) from error
+            raise
+        except RETRYABLE_DIRECT_ERRORS as error:
+            if attempt < retry_attempts - 1:
+                time.sleep(_retry_backoff_seconds(attempt))
+                continue
+            raise RetryableReflectionError(
+                f"{failure_prefix} timed out after {retry_attempts} attempts: {error}"
+            ) from error
+
+    raise RetryableReflectionError(f"{failure_prefix} failed after {retry_attempts} attempts")
+
+
 def _merge_provider_settings(
     payload: dict[str, Any],
     settings: dict[str, Any],
@@ -143,16 +227,13 @@ def reflect_with_anthropic(parent_text: str, parent_results: list[RowEvaluation]
             "content-type": "application/json",
         },
     )
-    try:
-        with urllib.request.urlopen(request, timeout=180) as response:
-            data = json.loads(response.read().decode("utf-8"))
-    except urllib.error.HTTPError as error:
-        detail = error.read().decode("utf-8", errors="replace")
-        raise RuntimeError(f"Reflection LM failed: {error.code} {detail}") from error
-    except urllib.error.URLError as error:
-        if not isinstance(error.reason, ssl.SSLCertVerificationError):
-            raise
-        data = _read_anthropic_response_with_curl(api_key, payload)
+    data = _read_json_response_with_retries(
+        request,
+        timeout_seconds=config.reflection_http_timeout_seconds,
+        retry_attempts=config.reflection_retry_attempts,
+        failure_prefix="Reflection LM failed",
+        ssl_fallback=lambda: _read_anthropic_response_with_curl(api_key, payload),
+    )
     parts = data.get("content") or []
     text = "".join(part.get("text", "") for part in parts if isinstance(part, dict))
     return ReflectionResult(
@@ -180,12 +261,12 @@ def reflect_with_openai(parent_text: str, parent_results: list[RowEvaluation], c
             "Content-Type": "application/json",
         },
     )
-    try:
-        with urllib.request.urlopen(request, timeout=180) as response:
-            data = json.loads(response.read().decode("utf-8"))
-    except urllib.error.HTTPError as error:
-        detail = error.read().decode("utf-8", errors="replace")
-        raise RuntimeError(f"OpenAI reflection LM failed: {error.code} {detail}") from error
+    data = _read_json_response_with_retries(
+        request,
+        timeout_seconds=config.reflection_http_timeout_seconds,
+        retry_attempts=config.reflection_retry_attempts,
+        failure_prefix="OpenAI reflection LM failed",
+    )
     text = _extract_openai_output_text(data)
     if not text:
         raise RuntimeError("OpenAI reflection LM returned no output text")

package/vendor/skills/orizu-cli/SKILL.md

@@ -22,15 +22,18 @@ Skip this skill when:
 
 - Node.js 20+ installed.
 - Install the CLI: `npm i -g orizu`.
-- Install this skill from the CLI package: `orizu install-skill --target agent-user --yes`.
+- Install this skill from the CLI package: `orizu install-skill --agent codex --yes` (or `--agent claude`; advanced target IDs remain available via `--target`).
+- Or read the bundled skill in place without installing: `orizu skills path --json` returns `root`, `skillMd`, `source`, `cliVersion`, and `skillHash`.
+- After CLI upgrades, check installed copies with `orizu skills status` and refresh them with `orizu skills update`.
 - Rediscover the command surface any time with `orizu --help`, `orizu <group> --help`, or `orizu capabilities --json`.
+- Every command supports `--json` (prefix `orizu --json <cmd>` or trailing flag) and emits a single JSON document; prefer it over parsing human-formatted text. Long-running commands emit the JSON summary as the final stdout line.
 - Login callback requires `127.0.0.1:43123`.
 - Credentials are stored at `~/.config/orizu/credentials.json`.
 - Current `orizu login` creates a user-owned personal access token for the CLI and stores it as a v3 API-key credential. The raw token is not recoverable after creation.
 
 ## Login
 
-- Verify auth: `orizu whoami`.
+- Verify auth: `orizu whoami --json` (returns `{user, server}`; non-zero exit means sign in is needed).
 - Start the login flow: `orizu login` (opens a browser tab).
 - Approving login in the browser creates a personal access token for that Orizu user. The token inherits the user's current team/project access and loses access if the user's role or membership changes.
 - Clear local credentials and revoke the current CLI token: `orizu logout`.
@@ -86,6 +89,8 @@ orizu tasks create --project <teamSlug>/<projectSlug> --dataset <datasetId> --ap
 
 # Open the returned task URL and test the draft manually before assigning.
 orizu tasks publish --task <taskId> --assignees <userId1,userId2>
+# Or publish exact row assignments:
+orizu tasks publish --task <taskId> --assignment-file ./assignments.jsonl
 
 orizu tasks status --task <taskId>
 orizu tasks report set --task <taskId> --report-file ./task-report.md
@@ -143,12 +148,14 @@ Local execution workflow:
 7. Diff before/after on a held-out set; ship if it holds.
 
 Bundled `run-gepa` reflection behavior:
+- Budget controls are mutually exclusive. Use at most one of `--budget auto|light|medium|heavy`, `--max-metric-calls <n>`, `--max-full-evals <n>`, or `--max-iterations <n>`. If none is provided, `run-gepa` uses `--budget auto`, the balanced medium preset.
 - The reflective LM's final text is used verbatim as the next candidate prompt. It should return only the complete updated prompt body, not analysis, labels, XML tags, or markdown fences.
 - Keep provider-native reasoning controls separate from the prompt text with `--reflection-provider-settings <json|@file>`.
 - Reflection max-token limits are explicit config, not implicit defaults. Use `--reflection-max-tokens <n>` when a provider requires an output cap; this maps to Anthropic `max_tokens` and OpenAI `max_output_tokens`.
 - Anthropic native Messages reflection requires `max_tokens`, so `run-gepa` with an `anthropic/...` reflection model must receive `--reflection-max-tokens <n>` and should fail fast if it is omitted. OpenAI reflection may omit `max_output_tokens` unless the user explicitly wants a cap.
+- Reflection HTTP calls retry transient provider failures by default (`--reflection-retry-attempts 3`, `--reflection-http-timeout-seconds 180`). Retryable failures include timeouts, connection reset/abort, HTTP 429, and common server/capacity statuses. If reflection still fails after retries, `run-gepa` logs `reflection_failed`, counts the proposal against budget, and continues to the next iteration.
 - By default, `run-gepa` skips reflection and child creation when every row in the selected parent mini-batch is already perfect (`1.0` for higher-is-better scorers, `0.0` for lower-is-better scorers). This saves reflection tokens because the child cannot beat a saturated mini-batch. Use `--no-skip-perfect-parent-reflection` to force reflection anyway, or `--skip-perfect-parent-reflection` to make the default explicit in scripted runs.
-- By default, `run-gepa` sets `--num-threads auto` for row evaluations. Auto uses mini-batch size, validation-set size, CPU count, memory estimate, file-descriptor limit, and an 8-thread hard cap to avoid launching too many runner subprocesses at once. Use `--num-threads <n>` only when the runner/provider capacity is known.
+- By default, `run-gepa` sets `--num-threads auto` for row evaluations. Auto uses mini-batch size, validation-set size, 2x CPU count, memory estimate, file-descriptor limit, and a 64-thread default ceiling to avoid launching too many runner subprocesses at once while still scaling large runs. Set `ORIZU_GEPA_AUTO_THREADS_MAX` or use `--num-threads <n>` only when the runner/provider capacity is known.
 - `run-gepa` writes complete local logs by default under `logs/<optimization_run_id>`; override with `--log-dir <dir>` or disable with `--no-local-log`.
 - Server optimization events redact row snapshots and reflection prompts by default; the local log keeps full row inputs, outputs, scores, feedback, reflection prompts, and reflection responses for later agent analysis.
 - OpenAI example: `--reflection-model openai/gpt-5 --reflection-provider-settings '{"reasoning":{"effort":"medium","summary":"auto"}}'`.
@@ -170,9 +177,9 @@ Detailed walkthrough — GEPA mechanics, Orizu-tracked optimization, optional DS
 # Execution rules
 
 - Prefer explicit flags in non-TTY contexts; reserve interactive fallback for TTY.
-- Canonical selectors: `--team`, `--project`, `--app`, `--task`, `--dataset`, `--assignees`.
-- `tasks create` creates drafts by default. Test the returned task URL manually, then use `tasks publish --task <taskId> --assignees <userId1,userId2>` after approval.
-- `tasks assign` and `tasks publish` take user IDs, not emails.
+- Canonical selectors: `--team`, `--project`, `--app`, `--task`, `--dataset`, `--assignees`, `--assignment-file`.
+- `tasks create` creates drafts by default. Test the returned task URL manually, then use `tasks publish --task <taskId> --assignees <userId1,userId2>` or `tasks publish --task <taskId> --assignment-file <path>` after approval.
+- `tasks assign --assignees` and `tasks publish --assignees` take user IDs, not emails. `--assignment-file` accepts emails or user IDs in JSONL rows shaped as `{ "rowId": "...", "assignee": "..." }` or `{ "rowId": "...", "assignees": ["..."] }`.
 - `datasets edit-rows` requires a non-empty string `id` on each row in `--file`.
 - `datasets delete-rows` uses `--row-ids` as the canonical selector.
 - `datasets delete` requires interactive terminal confirmation; there is no non-interactive confirmation option.