traigent 0.12.0__tar.gz → 0.13.0.dev1__tar.gz

{traigent-0.12.0 → traigent-0.13.0.dev1}/CHANGELOG.md

@@ -6,6 +6,33 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+- **Composite telemetry rides the measures channel.** `composite_measures(run)`
+  (`traigent.knobs.telemetry`, re-exported from `traigent.knobs`) flattens a composite
+  run's RFC 0002 §3.10 content-free telemetry — `escalation_rate`, `stage_selected`, and
+  the per-gate `gate_margin_pass_rate` map — into flat, identifier-safe, numeric-only keys
+  (e.g. `composite_escalation_rate`, `composite_stage_selected`,
+  `composite_gate_0_margin_pass_rate`). Merge it into the metrics your decorated function
+  returns and the `composite_*` keys ride the existing per-trial measures wire channel as
+  ordinary numeric metrics — no new wire surface. Keys are capped with headroom below the
+  backend `MeasuresDict` 50-key ceiling (truncated deterministically with a logged warning,
+  never raised mid-trial), and the output is content-free by construction (the adapter reads
+  `run.measures` only, never `run.output`). New docs page
+  `docs/concepts/composite-knobs.md` covers the pattern catalog, executing a composite,
+  certified selection with a `binary_cascade`, and telemetry-to-measures; runnable offline
+  example at `examples/advanced/composite-knobs/composite_telemetry.py`.
+
+### Changed
+- **Unpriced models now block instead of warn-and-continue.** When a real run includes
+  models with no known pricing, the SDK now requires explicit confirmation: interactive
+  terminals get a blocking prompt; non-interactive runs fail closed before any trial.
+  Pre-approve with `cost_approved=True` (must be a real boolean) or
+  `TRAIGENT_COST_APPROVED=true` (exact value), or supply custom pricing via
+  `TRAIGENT_CUSTOM_MODEL_PRICING_JSON`/`_FILE`. `TRAIGENT_STRICT_COST_ACCOUNTING=true`
+  still hard-fails without prompting; mock runs are unaffected.
+
+## [0.12.0] - 2026-06-06
+
 ### Added
 - **Content-logging opt-out for optimization logs** (#1069). `TRAIGENT_LOG_EXAMPLE_CONTENT=false`
   (or `OptimizationLogger(..., log_example_content=False)`) keeps per-trial ids and metrics on

{traigent-0.12.0/traigent.egg-info → traigent-0.13.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.12.0
+Version: 0.13.0.dev1
 Summary: Enterprise-grade LLM optimization platform with advanced analytics and AI-powered insights
 Author-email: Traigent Team <opensource@traigent.ai>
 License-Expression: AGPL-3.0-only OR LicenseRef-Traigent-Commercial
@@ -54,7 +54,6 @@ Requires-Dist: langchain-core>=1.2.28; extra == "integrations"
 Requires-Dist: langchain-community>=0.3.27; extra == "integrations"
 Requires-Dist: langchain-anthropic>=0.2.0; extra == "integrations"
 Requires-Dist: langchain-openai>=1.1.14; extra == "integrations"
-Requires-Dist: langchain-chroma>=0.2.5; extra == "integrations"
 Requires-Dist: langchain-text-splitters>=0.3.8; extra == "integrations"
 Requires-Dist: langchain-google-genai>=2.1.4; extra == "integrations"
 Requires-Dist: openai>=2.0.0; extra == "integrations"
@@ -69,6 +68,8 @@ Requires-Dist: python-dotenv>=1.2.2; extra == "integrations"
 Requires-Dist: boto3>=1.28.0; extra == "integrations"
 Requires-Dist: botocore>=1.31.0; extra == "integrations"
 Requires-Dist: faiss-cpu>=1.7.0; sys_platform != "win32" and extra == "integrations"
+Provides-Extra: chroma
+Requires-Dist: langchain-chroma>=0.2.5; extra == "chroma"
 Provides-Extra: dspy
 Requires-Dist: dspy-ai>=2.5.0; extra == "dspy"
 Provides-Extra: pydanticai
@@ -126,7 +127,7 @@ Requires-Dist: bandit>=1.7.0; extra == "dev"
 Requires-Dist: hypothesis>=6.100.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.4.0; extra == "docs"
-Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.22.0; extra == "docs"
 Provides-Extra: ml
 Requires-Dist: traigent[analytics,bayesian]; extra == "ml"
@@ -316,7 +317,7 @@ Works with any LLM provider — [OpenAI](https://platform.openai.com/docs), [Ant
 
 ## 🚀 Walkthrough — 8 runnable examples
 
-The walkthrough examples use local mock mode through the quickstart/testing helpers — no API keys needed.
+The walkthrough examples use local mock mode through the quickstart/testing helpers with cost approval pre-set for dry runs — no provider API keys needed when calls go through LiteLLM or LangChain.
 
 <details>
 <summary>Show all 8 walkthrough steps</summary>
@@ -441,8 +442,11 @@ pip install -e ".[recommended]"
 Cost estimates, budgets, limits, alerts, and thresholds are best-effort software controls, not
 provider-side billing guarantees. Actual billing is determined by your LLM/cloud providers, and you
 remain responsible for provider charges. The legacy `TRAIGENT_MOCK_LLM=true` env var is supported
-only for backwards-compatible local scripts and is disabled when `ENVIRONMENT=production`. See
-[DISCLAIMER.md](DISCLAIMER.md) for details.
+only for backwards-compatible local scripts and is disabled when `ENVIRONMENT=production`.
+Mock mode skips the optimized-function pricing preflight for supported calls made through
+Traigent's integration/interceptor path; direct provider calls made outside that path should
+be stubbed explicitly for a guaranteed $0 rehearsal. See [DISCLAIMER.md](DISCLAIMER.md)
+for details.
 
 ### Evaluation
 

{traigent-0.12.0 → traigent-0.13.0.dev1}/README.md

@@ -169,7 +169,7 @@ Works with any LLM provider — [OpenAI](https://platform.openai.com/docs), [Ant
 
 ## 🚀 Walkthrough — 8 runnable examples
 
-The walkthrough examples use local mock mode through the quickstart/testing helpers — no API keys needed.
+The walkthrough examples use local mock mode through the quickstart/testing helpers with cost approval pre-set for dry runs — no provider API keys needed when calls go through LiteLLM or LangChain.
 
 <details>
 <summary>Show all 8 walkthrough steps</summary>
@@ -294,8 +294,11 @@ pip install -e ".[recommended]"
 Cost estimates, budgets, limits, alerts, and thresholds are best-effort software controls, not
 provider-side billing guarantees. Actual billing is determined by your LLM/cloud providers, and you
 remain responsible for provider charges. The legacy `TRAIGENT_MOCK_LLM=true` env var is supported
-only for backwards-compatible local scripts and is disabled when `ENVIRONMENT=production`. See
-[DISCLAIMER.md](DISCLAIMER.md) for details.
+only for backwards-compatible local scripts and is disabled when `ENVIRONMENT=production`.
+Mock mode skips the optimized-function pricing preflight for supported calls made through
+Traigent's integration/interceptor path; direct provider calls made outside that path should
+be stubbed explicitly for a guaranteed $0 rehearsal. See [DISCLAIMER.md](DISCLAIMER.md)
+for details.
 
 ### Evaluation
 

{traigent-0.12.0 → traigent-0.13.0.dev1}/docs/README.md

@@ -6,6 +6,15 @@
 
 ## 🚀 Quick Start
 
+Current release: Traigent SDK 0.12.0. Install with
+`pip install "traigent[recommended]"`, then run `traigent onboard`,
+`traigent auth device-login`, `traigent quickstart`,
+`traigent first-prompt --agent claude|cursor|codex`, `traigent mcp serve`, or
+`traigent recommend` as needed.
+
+License: Traigent SDK is dual-licensed under
+`AGPL-3.0-only OR LicenseRef-Traigent-Commercial`.
+
 ```python
 import litellm
 import traigent
@@ -82,11 +91,8 @@ Traigent is a **zero-code optimization platform** that automatically finds the b
 
 ## 🌐 Examples Navigator
 
-- Open: `examples/index.html` (repo copy)
-- Serve locally (avoids file:// fetch restrictions):
-  - `python -m http.server 8000`
-  - Visit `http://localhost:8000/examples/`
-- Run icon: Each code block has a play button that copies a ready-to-run mock-mode command.
+Use [Examples Guide](examples/README.md), [Start Here](examples/START_HERE.md),
+and [Quick Reference](examples/QUICK_REFERENCE.md) for runnable examples.
 
 ## 🧪 Example Guides
 
@@ -100,7 +106,7 @@ Traigent is a **zero-code optimization platform** that automatically finds the b
 
 1. **[Install Traigent](getting-started/installation.md)** - Get set up in minutes
 2. **[Follow the Getting Started Guide](getting-started/GETTING_STARTED.md)** - Your first optimization
-3. **Open the Examples** – `examples/index.html` and browse the gallery
+3. **Use the Example Guides** - Start with [Examples Guide](examples/README.md)
 4. **[Explore User Guides](user-guide/)** - Learn advanced features
 5. **[Check API Reference](api-reference/)** - Detailed technical documentation
 

traigent-0.13.0.dev1/docs/agent-skill.md

@@ -0,0 +1,35 @@
+# AI Agent Skill
+
+Traigent publishes [Agent Skills](https://agentskills.io/) — sets of instructions that teach your AI coding agent how to set up and run Traigent optimizations.
+
+When you ask your agent to "optimize this function with Traigent," the skill guides it through a **dry-run-first workflow**: validate the documented Traigent path at zero provider cost in mock mode, then switch to real execution only when you say so. If your code makes provider calls outside Traigent's optimized/evaluated path, stub those calls explicitly before treating the rehearsal as guaranteed $0.
+
+## Compatible Agents
+
+Works with Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, Windsurf, and [30+ more](https://agentskills.io/).
+
+## Install
+
+The canonical SDK skill source is [`Traigent/traigent-skills`](https://github.com/Traigent/traigent-skills). SDK checkouts do not vendor `.agents/` or `.claude/skills/` copies; install from the remote repo so your local agent cache can be updated independently.
+
+**Install all SDK skills:**
+```bash
+npx skills add Traigent/traigent-skills --skill '*'
+```
+
+**Install only the Python entry points:**
+```bash
+npx skills add Traigent/traigent-skills --skill traigent --skill traigent-quickstart
+```
+
+## What the Skill Does
+
+1. Sets up the `@traigent.optimize()` decorator
+2. Validates your dataset and config space
+3. Runs a mock optimization (zero cost) to verify the full pipeline
+4. Reports results and estimates real costs
+5. Waits for your go-ahead before spending real tokens
+
+## View the Skills
+
+[Read the canonical skill instructions →](https://github.com/Traigent/traigent-skills/tree/main/skills/traigent)

{traigent-0.12.0 → traigent-0.13.0.dev1}/docs/api-reference/complete-function-specification.md

@@ -1,6 +1,6 @@
 # Traigent SDK API Reference
 
-Authoritative reference for Traigent SDK **v0.10.0 (Beta)**.
+Authoritative reference for Traigent SDK **0.12.0**.
 
 ## Quick Navigation
 
@@ -22,7 +22,8 @@ def optimize(
     objectives: list[str] | ObjectiveSchema | None = None,
     configuration_space: dict[str, Any] | ConfigSpace | None = None,
     default_config: dict[str, Any] | None = None,
-    constraints: list[Constraint | Callable[..., Any]] | None = None,
+    constraints: list[Constraint | BoolExpr | Callable[..., Any]] | None = None,
+    safety_constraints: list[SafetyConstraint | CompoundSafetyConstraint] | None = None,
     # TVL integration
     tvl_spec: str | Path | None = None,
     tvl_environment: str | None = None,
@@ -30,16 +31,40 @@ def optimize(
     # Grouped options (preferred)
     evaluation: EvaluationOptions | dict[str, Any] | None = None,
     injection: InjectionOptions | dict[str, Any] | None = None,
+    effectuation: bool = False,
     execution: ExecutionOptions | dict[str, Any] | None = None,
     mock: MockModeOptions | dict[str, Any] | None = None,
+    strategy: str | None = None,
+    strategy_params: Mapping[str, Any] | None = None,
+    # Multi-agent configuration
+    agents: dict[str, AgentDefinition] | None = None,
+    agent_prefixes: list[str] | None = None,
+    agent_measures: dict[str, list[str]] | None = None,
+    global_measures: list[str] | None = None,
+    # Config persistence
+    auto_load_best: bool = False,
+    load_from: str | None = None,
+    config_id: str | None = None,
+    best_config_source: str = "off",
+    best_config_strict: bool = False,
+    best_config_cache_dir: str | None = None,
+    best_config_cache_ttl_seconds: int = 24 * 60 * 60,
+    best_config_stale_ok_ttl_seconds: int | None = None,
+    enable_auto_load_dev_logs: bool | None = None,
+    # Guided generation
+    prompt_rewrite: dict[str, Any] | None = None,
+    grow_dataset: dict[str, Any] | None = None,
     # Legacy compatibility
     legacy: LegacyOptimizeArgs | dict[str, Any] | None = None,
     **runtime_overrides: Any,
-) -> OptimizedFunction
+) -> Callable[[Callable[..., Any]], Any]
 ```
 
 > **New in 0.8.0** – The decorator now uses keyword-only arguments with grouped option bundles. Legacy arguments are supported via the `legacy` parameter or directly in `**runtime_overrides`. Conflicting values between a bundle and a direct keyword raise `TypeError`.
 
+`optimize(...)` is a decorator factory. Applying the returned decorator to a
+function returns Traigent's optimized wrapper.
+
 **Core Parameters**
 
 | Parameter | Type | Default | Description |
@@ -48,6 +73,13 @@ def optimize(
 | `configuration_space` | `dict[str, Any] \| ConfigSpace \| None` | `None` | Search space describing tunable parameters. Lists denote discrete choices; `(min, max)` tuples denote ranges. `Range`, `IntRange`, `LogRange`, `Choices`, and `ConfigSpace` are supported directly. Required for optimization. |
 | `default_config` | `dict[str, Any] \| None` | `None` | Baseline configuration applied before the first trial. Missing keys remain unset unless you provide defaults via `default_config` or parameter defaults (for example `Range(..., default=...)`). |
 | `constraints` | `list[Constraint \| Callable[..., Any]] \| None` | `None` | Hard constraints evaluated before running a trial. Accepts SE-friendly `Constraint` objects and/or callables that take `(config, metrics=None)` and return `True/False`. |
+| `safety_constraints` | `list[SafetyConstraint \| CompoundSafetyConstraint] \| None` | `None` | Safety metric gates evaluated as part of optimization. |
+| `strategy` | `str \| None` | `None` | Optional strategy preset name. 0.12.0 presets are advisory selection rules over completed trials. |
+| `strategy_params` | `Mapping[str, Any] \| None` | `None` | Parameters for the selected strategy preset. |
+| `effectuation` | `bool` | `False` | Enables effectuation tracking for tuned-variable observations. |
+| `agents`, `agent_prefixes`, `agent_measures`, `global_measures` | See signature | `None` | Multi-agent measurement configuration. |
+| Config persistence fields | See signature | See signature | `auto_load_best`, `load_from`, `config_id`, `best_config_*`, and cache TTL controls for persisted best configurations. |
+| Guided-generation fields | `dict[str, Any] \| None` | `None` | `prompt_rewrite` and `grow_dataset` configure guided generation; run it with `.optimize_with_guidance(provider)`. |
 
 **SE-friendly tuned variables (first-class)**
 
@@ -87,17 +119,31 @@ def my_agent(question: str) -> str:
 | `execution` | `ExecutionOptions \| dict \| None` | Bundle for execution settings including `execution_mode`, `local_storage_path`, `parallel_config`, `privacy_enabled`, and `max_total_examples`. |
 | `mock` | `MockModeOptions \| dict \| None` | **Deprecated — all fields inert.** Retained on the schema for backwards compatibility (config round-trip). Mock mode is enabled by calling `traigent.testing.enable_mock_mode_for_quickstart()` in local tutorial or test code, not via this object. The legacy `TRAIGENT_MOCK_LLM=true` env var remains available outside production for shell fixtures and backwards compatibility but emits `DeprecationWarning` when users set it directly. See issue #874. |
 
-**ExecutionOptions Fields** (open-source builds run in `edge_analytics` only; other modes are roadmap-compatible but not currently provisioned)
+**ExecutionOptions Fields**
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `execution_mode` | `str` | `"edge_analytics"` | `"edge_analytics"` runs locally. `"hybrid"` runs trials locally and submits sessions/trial metrics to the backend for portal tracking. `"cloud"` is reserved for future remote execution and fails closed with guidance to use `"hybrid"`. `"privacy"` is accepted as a legacy alias for `"hybrid"` and sets `privacy_enabled=True`. |
+| `execution_mode` | `str` | `"edge_analytics"` | `"edge_analytics"` runs locally. `"hybrid"` runs trials locally and submits sessions/trial metrics to the backend for portal tracking. `"hybrid_api"` delegates trial execution to an external service implementing the Traigent Hybrid API contract. `"privacy"` is accepted as a legacy alias for `"hybrid"` and sets `privacy_enabled=True`. `"cloud"` is reserved for future remote execution and fails closed with guidance to use `"hybrid"`. |
 | `local_storage_path` | `str \| None` | `None` | Custom directory for persisted results. Falls back to `TRAIGENT_RESULTS_FOLDER` or `~/.traigent/`. |
 | `minimal_logging` | `bool` | `True` | Suppresses verbose logs in privacy-sensitive modes. |
 | `parallel_config` | `ParallelConfig \| dict \| None` | `None` | Unified concurrency configuration. |
 | `privacy_enabled` | `bool \| None` | `None` | Redacts prompts/responses from telemetry and logs. |
 | `max_total_examples` | `int \| None` | `None` | Global sample budget across all trials (budget guardrail). |
 | `samples_include_pruned` | `bool` | `True` | Whether pruned trials count toward the sample budget. |
+| `reps_per_trial` | `int` | `1` | Number of repetitions per configuration. OSS SDK accepts only `1`; other values raise `pydantic.ValidationError` and require Traigent Enterprise. |
+| `reps_aggregation` | `str` | `"mean"` | Repetition aggregation method. OSS SDK accepts only `"mean"`; other values raise `pydantic.ValidationError` and require Traigent Enterprise. |
+| `hybrid_api_endpoint` | `str \| None` | `None` | External-agent Hybrid API base endpoint. |
+| `tunable_id` | `str \| None` | `None` | Optional Hybrid API tunable identifier. |
+| `hybrid_api_transport` | `Any \| None` | `None` | Custom Hybrid API transport object. |
+| `hybrid_api_transport_type` | `str` | `"auto"` | Hybrid API transport type selector. |
+| `hybrid_api_batch_size` | `int` | `1` | Number of examples per Hybrid API execute request. |
+| `hybrid_api_batch_parallelism` | `int` | `1` | Concurrent Hybrid API batch execution limit. |
+| `hybrid_api_keep_alive` | `bool` | `True` | Reuse Hybrid API HTTP connections. |
+| `hybrid_api_heartbeat_interval` | `float` | `30.0` | Heartbeat interval for Hybrid API transports. |
+| `hybrid_api_timeout` | `float \| None` | `None` | Hybrid API request timeout override. |
+| `hybrid_api_auth_header` | `str \| None` | `None` | Auth token/header value sent as both `Authorization` and `x-api-key`. |
+| `hybrid_api_auto_discover_tvars` | `bool` | `False` | Auto-discover Hybrid API tuned variables when supported. |
+| `cloud_fallback_policy` | `str \| None` | `None` | Legacy/future cloud fallback policy. It does not enable `execution_mode="cloud"` in 0.12.0. |
 
 **Legacy Compatibility**
 
@@ -171,6 +217,9 @@ async def optimize(
     tvl_spec: str | Path | None = None,
     tvl_environment: str | None = None,
     tvl: TVLOptions | dict[str, Any] | None = None,
+    strategy: str | None = None,
+    strategy_params: Mapping[str, Any] | None = None,
+    progress_bar: bool | None = None,
     **algorithm_kwargs: Any,
 ) -> OptimizationResult
 ```
@@ -190,6 +239,9 @@ async def optimize(
 | `tvl_spec` | `str \| Path \| None` | `None` | Load TVL spec at runtime. |
 | `tvl_environment` | `str \| None` | `None` | Environment overlay from the TVL spec. |
 | `tvl` | `TVLOptions \| dict \| None` | `None` | Structured TVL options for runtime overrides. |
+| `strategy` | `str \| None` | `None` | Runtime strategy preset override. Preset selections are advisory only. |
+| `strategy_params` | `Mapping[str, Any] \| None` | `None` | Runtime parameters for the strategy preset. |
+| `progress_bar` | `bool \| None` | `None` | Runtime progress-bar override. |
 | `**algorithm_kwargs` | `Any` | – | Extra tuning knobs. See recognised keys below. |
 
 **Recognised `algorithm_kwargs`**
@@ -201,7 +253,7 @@ async def optimize(
 | `max_total_examples` | Global sample budget across all trials. |
 | `cache_policy` | One of `"allow_repeats"` (default) or other cache policies. |
 | `cost_limit` | Maximum USD spending for this run. |
-| `cost_approved` | Skip cost approval prompt. |
+| `cost_approved` | Skip cost approval prompt only when passed as real Python `True`; strings such as `"true"` are ignored. Env approval requires exact `TRAIGENT_COST_APPROVED=true`; `1`/`yes` do not approve. |
 | `metric_limit` / `metric_name` / `metric_include_pruned` | Configure soft cumulative-metric early stopping. |
 | `budget_limit` / `budget_metric` / `budget_include_pruned` | Deprecated aliases for metric-limit controls. Use `cost_limit` for hard USD spend control. |
 | `plateau_window` / `plateau_epsilon` | Configure plateau detection stop conditions. |
@@ -229,13 +281,15 @@ def get_best_config() -> dict[str, Any] | None
 ```
 
 #### `.current_config`
-**Get/set current configuration**
+**Get current configuration**
 
 ```python
 @property
 def current_config() -> dict[str, Any]
 ```
 
+`current_config` is read-only. Change the active override with `.set_config()`.
+
 #### `.set_config()`
 **Set current configuration**
 
@@ -380,6 +434,64 @@ def override_config(
 def get_available_strategies() -> dict[str, Any]
 ```
 
+### Recommendation Catalog and Strategy Presets
+
+0.12.0 exposes local catalog helpers and advisory selection presets through
+`traigent.api`.
+
+```python
+def list_recommendation_agent_types() -> tuple[str, ...]
+
+def recommend_configuration_space(
+    agent_type: str,
+    *,
+    min_impact: str | None = None,
+    min_confidence: str | None = None,
+) -> dict[str, Any]
+```
+
+`recommend_configuration_space()` returns catalog metadata for supported
+agent/task types: knob names, suggested ranges, impact estimates, evidence
+notes, effectuation status, and apply guidance. It does not call a remote
+service.
+
+```python
+VALID_PRESET_NAMES: tuple[str, ...] = (
+    "max_accuracy_then_cheapest_within_epsilon",
+    "quality_floor_min_cost",
+    "pareto_frontier",
+)
+
+def normalize_strategy_preset(
+    preset_name: str | None,
+    params: Mapping[str, Any] | None = None,
+) -> NormalizedStrategyPreset
+
+def select_strategy_preset(
+    preset: NormalizedStrategyPreset,
+    trials: Iterable[TrialResult],
+) -> PresetSelection
+```
+
+Strategy presets are advisory selection rules over completed trials. They are
+task-local heuristics and do not provide a statistical certificate.
+
+### CLI surfaces in 0.12.0
+
+The local CLI includes these onboarding and recommendation entry points:
+
+- `traigent onboard`
+- `traigent auth device-login`
+- `traigent first-prompt --agent claude|cursor|codex`
+- `traigent quickstart`
+- `traigent mcp serve`
+- `traigent recommend`
+
+The local MCP server in this worktree exposes these tools: `auth_status`,
+`list_recommendation_agent_types`, `recommend_configuration_space`,
+`detect_tvars`, `scaffold_eval`, `validate_dataset`, `estimate_cost`,
+`run_optimization`, `get_results`, and `export_evidence`.
+
 ### `traigent.get_optimization_insights()`
 
 ```python
@@ -398,7 +510,7 @@ def get_optimization_insights(
 class OptimizationResult:
     trials: list[TrialResult]
     best_config: dict[str, Any]
-    best_score: float
+    best_score: float | None
     optimization_id: str
     duration: float
     convergence_info: dict[str, Any]
@@ -411,11 +523,16 @@ class OptimizationResult:
     total_cost: float | None = None
     total_tokens: int | None = None
     metrics: dict[str, Any] = field(default_factory=dict)
+    preset_selection: PresetSelection | None = None
+    stop_reason: StopReason | None = None
+    experiment_id: str | None = None
+    cloud_url: str | None = None
+    run_label: str | None = None
 ```
 
 **Properties:**
 - `total_trials`: Total number of trials executed
-- `successful_trials`: Number of trials that completed successfully
+- `successful_trials`: List of trials that completed successfully
 - `success_rate`: Ratio of successful trials to total trials
 
 ### TrialResult
@@ -431,6 +548,7 @@ class TrialResult:
     timestamp: datetime
     error_message: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
+    error: TrialError | None = None
 ```
 
 **Properties:**
@@ -443,10 +561,12 @@ class TrialResult:
 
 ```python
 class TrialStatus(Enum):
+    NOT_STARTED = "not_started"
     PENDING = "pending"
     RUNNING = "running"
     COMPLETED = "completed"
     FAILED = "failed"
+    CANCELLED = "cancelled"
     PRUNED = "pruned"
 ```
 
@@ -454,6 +574,7 @@ class TrialStatus(Enum):
 
 ```python
 class OptimizationStatus(Enum):
+    NOT_STARTED = "not_started"
     PENDING = "pending"
     RUNNING = "running"
     COMPLETED = "completed"
@@ -592,4 +713,4 @@ def my_function(input_text: str) -> str:
 
 ---
 
-This documentation reflects Traigent SDK v0.10.0.
+This documentation reflects Traigent SDK 0.12.0.

{traigent-0.12.0 → traigent-0.13.0.dev1}/docs/api-reference/decorator-reference.md

@@ -36,6 +36,7 @@ def optimize(
     configuration_space: dict[str, Any] | ConfigSpace | None = None,
     default_config: dict[str, Any] | None = None,
     constraints: list[Constraint | BoolExpr | Callable[..., Any]] | None = None,
+    safety_constraints: list[SafetyConstraint | CompoundSafetyConstraint] | None = None,
 
     # TVL integration
     tvl_spec: str | Path | None = None,
@@ -45,8 +46,32 @@ def optimize(
     # Grouped option bundles (preferred)
     evaluation: EvaluationOptions | dict[str, Any] | None = None,
     injection: InjectionOptions | dict[str, Any] | None = None,
+    effectuation: bool = False,
     execution: ExecutionOptions | dict[str, Any] | None = None,
     mock: MockModeOptions | dict[str, Any] | None = None,
+    strategy: str | None = None,
+    strategy_params: Mapping[str, Any] | None = None,
+
+    # Multi-agent configuration
+    agents: dict[str, AgentDefinition] | None = None,
+    agent_prefixes: list[str] | None = None,
+    agent_measures: dict[str, list[str]] | None = None,
+    global_measures: list[str] | None = None,
+
+    # Config persistence
+    auto_load_best: bool = False,
+    load_from: str | None = None,
+    config_id: str | None = None,
+    best_config_source: str = "off",
+    best_config_strict: bool = False,
+    best_config_cache_dir: str | None = None,
+    best_config_cache_ttl_seconds: int = 24 * 60 * 60,
+    best_config_stale_ok_ttl_seconds: int | None = None,
+    enable_auto_load_dev_logs: bool | None = None,
+
+    # Guided generation
+    prompt_rewrite: dict[str, Any] | None = None,
+    grow_dataset: dict[str, Any] | None = None,
 
     # Legacy compatibility
     legacy: LegacyOptimizeArgs | dict[str, Any] | None = None,
@@ -424,7 +449,8 @@ def my_function(prompt: str) -> str:
     ...
 ```
 
-Complete Example: See [06_custom_evaluator.py](../../walkthrough/real/06_custom_evaluator.py) for a full LLM-as-Judge implementation.
+Complete example: see the repository's custom evaluator walkthrough for a full
+LLM-as-Judge implementation.
 
 #### `injection`
 
@@ -436,7 +462,7 @@ from traigent.api.decorators import InjectionOptions
 
 @traigent.optimize(
     injection=InjectionOptions(
-        injection_mode="context",  # or "parameter", "attribute", "seamless"
+        injection_mode="context",  # or "parameter", "seamless"
         config_param="config",  # required when injection_mode="parameter"
         auto_override_frameworks=True,
         framework_targets=["OpenAI", "Anthropic"],
@@ -447,7 +473,7 @@ from traigent.api.decorators import InjectionOptions
 
 **InjectionOptions Fields**:
 
-- `injection_mode`: How to inject config ("context", "parameter", "attribute", "seamless")
+- `injection_mode`: How to inject config ("context", "parameter", "seamless")
 - `config_param`: Parameter name when using "parameter" mode
 - `auto_override_frameworks`: Auto-detect framework classes
 - `framework_targets`: Explicit list of framework classes
@@ -470,6 +496,8 @@ from traigent.config.parallel import ParallelConfig
         privacy_enabled=False,
         max_total_examples=1000,
         samples_include_pruned=True,
+        reps_per_trial=1,
+        reps_aggregation="mean",
     ),
     ...
 )
@@ -477,13 +505,17 @@ from traigent.config.parallel import ParallelConfig
 
 **ExecutionOptions Fields**:
 
-- `execution_mode`: "edge_analytics" for local-only runs; "hybrid" for local execution with backend/portal tracking; "cloud" is reserved for future remote execution.
+- `execution_mode`: "edge_analytics" for local-only runs; "hybrid" for local execution with backend/portal tracking; "hybrid_api" for external API-backed trial execution; "privacy" as a legacy alias for "hybrid" with privacy enabled; "cloud" is reserved for future remote execution and fails closed.
 - `local_storage_path`: Custom storage directory
 - `minimal_logging`: Reduce log verbosity
 - `parallel_config`: Concurrency configuration
 - `privacy_enabled`: Redact sensitive data
 - `max_total_examples`: Global sample budget
 - `samples_include_pruned`: Count pruned trials in budget
+- `reps_per_trial`: Repetitions per configuration. OSS SDK accepts only `1`; non-default values raise `pydantic.ValidationError` and require Traigent Enterprise.
+- `reps_aggregation`: Repetition aggregation method. OSS SDK accepts only `"mean"`; non-default values raise `pydantic.ValidationError` and require Traigent Enterprise.
+- `hybrid_api_endpoint`, `tunable_id`, `hybrid_api_transport`, `hybrid_api_transport_type`, `hybrid_api_batch_size`, `hybrid_api_batch_parallelism`, `hybrid_api_keep_alive`, `hybrid_api_heartbeat_interval`, `hybrid_api_timeout`, `hybrid_api_auth_header`, `hybrid_api_auto_discover_tvars`: Hybrid API execution controls.
+- `cloud_fallback_policy`: Legacy/future cloud fallback behavior. It does not enable `execution_mode="cloud"` in 0.12.0.
 
 #### `mock`
 
@@ -529,22 +561,28 @@ The `**runtime_overrides` parameter accepts additional settings:
 ```python
 @traigent.optimize(
     algorithm="optuna",  # "grid", "random", "bayesian", "optuna"
-    max_trials=50,
-    timeout=3600,  # seconds
     ...
 )
 ```
 
+Run controls such as `max_trials` and `timeout` are passed to `.optimize()`:
+
+```python
+result = await my_agent.optimize(max_trials=50, timeout=3600)
+```
+
 **Cost Controls**:
 
 ```python
-@traigent.optimize(
+result = await my_agent.optimize(
     cost_limit=5.00,  # USD
-    cost_approved=False,  # Prompt for approval
-    ...
+    cost_approved=False,  # Real bool only; strings do not approve
 )
 ```
 
+Env approval requires exact `TRAIGENT_COST_APPROVED=true`; `1`/`yes` do not
+approve.
+
 **Metric-Limit Controls**:
 
 ```python
@@ -665,4 +703,4 @@ def my_agent(query: str) -> str:
 - [Execution Modes Guide](../guides/execution-modes.md) - Execution mode details
 - [Thread Pool Examples](./thread-pool-examples.md) - Context propagation with threads
 - [Telemetry Documentation](./telemetry.md) - Data collection and privacy
-- [Custom Evaluator Example](../../walkthrough/real/06_custom_evaluator.py) - LLM-as-Judge implementation
+- Custom evaluator walkthrough in the repository examples - LLM-as-Judge implementation

{traigent-0.12.0 → traigent-0.13.0.dev1}/docs/api-reference/telemetry.md

@@ -24,7 +24,8 @@ During optimization runs, Traigent collects:
 - Algorithm used (grid, random, bayesian, optuna)
 - Number of trials executed
 - Total optimization duration
-- Execution mode (edge_analytics, cloud, etc.)
+- Execution mode (`edge_analytics`, `hybrid`, `hybrid_api`; `privacy` is a
+  legacy alias for `hybrid`, and `cloud` is reserved/fails closed)
 - Stop conditions triggered
 - Content-free tuned-variable observations can include knob names, enum/scalar values, numeric metrics, and aggregate effectuation events for backend optimization. Set `TRAIGENT_TVAR_OBSERVATION=off` to disable them, or use `TRAIGENT_TVAR_OBSERVATION=hashed` (default) to hash free-form string values. Only `off` and `hashed` are supported; unsupported values fall back to `hashed`.
 
@@ -80,6 +81,35 @@ The older plural spelling `TRAIGENT_TRACES_ENABLED` remains as a deprecated
 alias when the canonical flag is unset; if both are set,
 `TRAIGENT_TRACE_ENABLED` takes precedence.
 
+### Agent Workflow Spans
+
+0.12.0 exposes a public helper for adding sanitized agent/node spans to the
+active optimization workflow trace:
+
+```python
+from collections.abc import Mapping
+from typing import Any
+
+from traigent.observability import add_agent_span
+
+def add_agent_span(
+    node_id: str,
+    *,
+    span_type: str = "agent",
+    input_tokens: int | None = None,
+    output_tokens: int | None = None,
+    cost_usd: float | None = None,
+    latency_ms: float | None = None,
+    model: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> None
+```
+
+The helper is safe to call from user code. If no active optimization trial or
+workflow trace manager exists, it logs at debug level and returns. Metadata is
+limited to safe numeric values, sensitive keys such as prompt/response/output
+are dropped, and model identifiers are validated before emission.
+
 ## How Telemetry is Used
 
 Telemetry data is used for:

{traigent-0.12.0 → traigent-0.13.0.dev1}/docs/api-reference/thread-pool-examples.md

@@ -458,4 +458,4 @@ async def process_items_async(items):
 - [API Reference](./complete-function-specification.md) - Full API documentation
 - [Parallel Configuration Guide](../guides/parallel-configuration.md) - Concurrency tuning and precedence
 - [Evaluation Guide](../guides/evaluation.md) - Parallel evaluation and concurrency tips
-- [Context Management Source](../../traigent/config/context.py) - Implementation details
+- Context management implementation: see `traigent/config/context.py` in the repository source.