traigent 0.13.0.dev1__tar.gz → 0.14.0__tar.gz

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

@@ -4,7 +4,7 @@ All notable changes to Traigent SDK are documented in this file.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.14.0] - 2026-06-19
 
 ### Added
 - **Composite telemetry rides the measures channel.** `composite_measures(run)`
@@ -23,6 +23,12 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   example at `examples/advanced/composite-knobs/composite_telemetry.py`.
 
 ### Changed
+- **Timing metrics now emit canonical millisecond keys** (#1225). Model latency is
+  reported as `response_time_ms`, evaluation wall time is reported as
+  `execution_time_ms`, and execution duration is no longer copied into
+  `response_time_ms`. Legacy seconds keys `model_response_time` and
+  `function_duration` remain populated for one minor-version compatibility window;
+  remove them after the next minor once downstream dashboards have migrated.
 - **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.
@@ -31,6 +37,24 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `TRAIGENT_CUSTOM_MODEL_PRICING_JSON`/`_FILE`. `TRAIGENT_STRICT_COST_ACCOUNTING=true`
   still hard-fails without prompting; mock runs are unaffected.
 
+### Removed
+- **`BudgetStopCondition` class removed.** The class is no longer exported from any
+  public module. Replace usage with `cost_limit=<value>` in `.optimize()` calls, or
+  use `metric_limit=<value>` + `metric_name=<name>` for metric-based stopping.
+- **`TRAIGENT_TRACES_ENABLED` environment variable removed.** The deprecated plural-form
+  alias is no longer read. Use `TRAIGENT_TRACE_ENABLED=true` (singular) instead. Setting
+  the old variable will have no effect and tracing will remain disabled.
+- **`OptimizedFunction.config_space` property removed.** The property has been removed
+  from the public API. Access the configuration space through the `TVLParameterAgent`
+  interface or via decorator introspection helpers.
+- **`strategy=` non-preset alias removed.** Passing an unrecognized string to `strategy=`
+  in `.optimize()` now raises `ValueError` immediately rather than falling back silently.
+  Use one of the documented preset names.
+- **`budget_limit`, `budget_metric`, `budget_include_pruned` runtime override keys
+  removed.** Passing any of these as keyword arguments to `.optimize()` now raises
+  `TypeError`. Migrate to `cost_limit=<value>` for cost-based stopping, or
+  `metric_limit=<value>` + `metric_name=<name>` for metric-based stopping.
+
 ## [0.12.0] - 2026-06-06
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.13.0.dev1
+Version: 0.14.0
 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
@@ -34,7 +34,7 @@ Requires-Dist: aiohttp<4.0,>=3.14.0
 Requires-Dist: requests>=2.33.0
 Requires-Dist: jsonschema>=4.0.0
 Requires-Dist: cryptography>=46.0.7
-Requires-Dist: PyJWT[crypto]<3.0.0,>=2.12.0
+Requires-Dist: PyJWT[crypto]<3.0.0,>=2.13.0
 Requires-Dist: backoff>=2.2.0
 Requires-Dist: litellm==1.87.1
 Requires-Dist: rank-bm25
@@ -163,28 +163,38 @@ Our mission: **Anything you can measure, we can improve.** Whether it's accuracy
 
 **Quick Install:**
 
-macOS / Linux:
+Install from PyPI — no clone required (Python 3.11+):
 
 ```bash
-git clone https://github.com/Traigent/Traigent.git
-cd Traigent
+# pip
+pip install "traigent[recommended]"
+
+# uv (into the active venv, or `uv add` into a uv project)
+uv pip install "traigent[recommended]"
+uv add "traigent[recommended]"
+```
+
+<details>
+<summary>Prefer an isolated virtual environment first?</summary>
+
+macOS / Linux:
 
+```bash
 python3 -m venv .venv
 source .venv/bin/activate
-pip install -e ".[recommended]"
+pip install "traigent[recommended]"
 ```
 
 Windows PowerShell:
 
 ```powershell
-git clone https://github.com/Traigent/Traigent.git
-cd Traigent
-
 python -m venv .venv
 .venv\Scripts\Activate.ps1
-pip install -e ".[recommended]"
+pip install "traigent[recommended]"
 ```
 
+</details>
+
 For more options, see [Installation details](#installation).
 
 **Try it now - no API keys needed:**
@@ -343,14 +353,14 @@ The walkthrough examples use local mock mode through the quickstart/testing help
 
 ### ☁️ Traigent Portal & Hybrid Tracking
 
-Connect to [Traigent Portal](https://portal.traigent.ai) to view results, compare trials, and collaborate. The supported portal-visible SDK path today is `execution_mode="hybrid"`: trials run locally, while session and trial metrics are stored in the backend for portal tracking.
+Connect to [Traigent Portal](https://portal.traigent.ai) to view results, compare trials, and collaborate. Portal tracking is enabled automatically when `TRAIGENT_API_KEY` is set — you do not need to set `execution_mode`. The SDK auto-selects the mode based on algorithm and transport.
 
-`execution_mode="cloud"` is reserved for future remote agent execution. It is not available yet and fails with: “Cloud remote execution is not available yet; use hybrid for portal-tracked optimization.”
+`execution_mode=”cloud”` is reserved for future remote agent execution and is not available yet.
 
 1. **Sign up** at [portal.traigent.ai](https://portal.traigent.ai) — verify your email to activate
 2. **Create an API key** — click your name (top-right) → **API Keys** → **+ Create API Key**
-3. **Connect** — run `traigent auth login` or set `export TRAIGENT_API_KEY="sk_..."`  <!-- pragma: allowlist secret -->
-4. **Run with hybrid tracking** — set `execution_mode="hybrid"` for portal-visible optimization
+3. **Connect** — run `traigent auth login` or set `export TRAIGENT_API_KEY=”sk_...”`  <!-- pragma: allowlist secret -->
+4. **Run** — portal tracking is automatic; no `execution_mode` needed
 
 <details>
 <summary>Credential priority and multi-provider setup</summary>
@@ -392,7 +402,7 @@ def multi_provider_agent(question: str) -> str:
 | Feature | Description |
 |---------|-------------|
 | **Zero-code integration** | Add `@traigent.optimize()` to existing code — no refactoring |
-| **Multi-algorithm** | Random, Grid, Bayesian (TPE, NSGA-II, CMA-ES) via Optuna |
+| **Multi-algorithm** | Random and Grid locally; Bayesian (TPE, NSGA-II, CMA-ES) via the Traigent cloud |
 | **Multi-objective** | Optimize accuracy, latency, cost, and custom metrics simultaneously |
 | **Framework support** | LangChain, OpenAI SDK, Anthropic, LiteLLM, and any LLM provider |
 | **Cost tracking** | Integrated tokencost library with 500+ model pricing |
@@ -410,19 +420,20 @@ def multi_provider_agent(question: str) -> str:
 
 ### Installation
 
-Python 3.11+ on Linux, macOS, or Windows. For coordinated release validation, install from this repository source tree.
+Python 3.11+ on Linux, macOS, or Windows. The published package on [PyPI](https://pypi.org/project/traigent/) is the recommended way to install — `pip install "traigent[recommended]"` or `uv add "traigent[recommended]"`. No repository checkout is required to use the SDK or its `traigent` CLI.
 
 | Feature Set | Description |
 |-------------|-------------|
 | `[recommended]` | All user-facing features (default) |
 | `[integrations]` | LangChain, OpenAI, Anthropic adapters |
 | `[analytics]` | Visualization and analytics |
-| `[bayesian]` | Bayesian optimization (TPE, NSGA-II) |
+| `[bayesian]` | Bayesian optimization dependencies (used by the Traigent cloud; not available locally) |
 | `[all]` | Everything |
 
 **[Full installation guide →](docs/getting-started/installation.md)**
 
-Source install with `pip`:
+Contributor / source install (only needed to hack on Traigent itself or run the
+coordinated release-validation suite — not required to use the SDK):
 
 ```bash
 git clone https://github.com/Traigent/Traigent.git
@@ -466,8 +477,8 @@ Provide a JSONL dataset — Traigent scores outputs using semantic similarity by
 
 | Mode | Status | Privacy | Algorithm | Best For |
 |------|--------|---------|-----------|----------|
-| **Local** (`edge_analytics`) | ✅ Available | ✅ Complete | All (Random/Grid/Bayesian/Optuna) | Local/private runs |
-| **Hybrid** (`hybrid`) | ✅ Available | ✅ Trial execution local | All (Random/Grid/Bayesian/Optuna) | Portal-tracked runs |
+| **Local** (`edge_analytics`) | ✅ Available | ✅ Complete | Random, Grid | Local/private runs |
+| **Hybrid** (`hybrid`) | ✅ Available | ✅ Trial execution local | Random, Grid + cloud smart algorithms | Portal-tracked runs |
 | **Cloud** (`cloud`) | 🚧 Reserved | Not available | Future remote execution | Do not use yet |
 
 **[Execution modes guide →](docs/guides/execution-modes.md)** — mode comparisons, privacy details, migration path
@@ -479,7 +490,7 @@ Provide a JSONL dataset — Traigent scores outputs using semantic similarity by
 | `configuration_space` | `@traigent.optimize()` | Parameters to test (required) |
 | `objectives` | `@traigent.optimize()` | Metrics to optimize for |
 | `eval_dataset` | `@traigent.optimize()` | Dataset for evaluation |
-| `algorithm` | `.optimize()` call | `"random"`, `"grid"`, `"bayesian"` |
+| `algorithm` | `.optimize()` call | `"random"`, `"grid"` (local); smart algorithms run in the Traigent cloud |
 | `max_trials` | `.optimize()` call | Number of configurations to test |
 | `progress_bar` | `.optimize()` call | `True` / `False` / `None` (auto) — live progress bar |
 

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

@@ -15,28 +15,38 @@ Our mission: **Anything you can measure, we can improve.** Whether it's accuracy
 
 **Quick Install:**
 
-macOS / Linux:
+Install from PyPI — no clone required (Python 3.11+):
 
 ```bash
-git clone https://github.com/Traigent/Traigent.git
-cd Traigent
+# pip
+pip install "traigent[recommended]"
+
+# uv (into the active venv, or `uv add` into a uv project)
+uv pip install "traigent[recommended]"
+uv add "traigent[recommended]"
+```
+
+<details>
+<summary>Prefer an isolated virtual environment first?</summary>
+
+macOS / Linux:
 
+```bash
 python3 -m venv .venv
 source .venv/bin/activate
-pip install -e ".[recommended]"
+pip install "traigent[recommended]"
 ```
 
 Windows PowerShell:
 
 ```powershell
-git clone https://github.com/Traigent/Traigent.git
-cd Traigent
-
 python -m venv .venv
 .venv\Scripts\Activate.ps1
-pip install -e ".[recommended]"
+pip install "traigent[recommended]"
 ```
 
+</details>
+
 For more options, see [Installation details](#installation).
 
 **Try it now - no API keys needed:**
@@ -195,14 +205,14 @@ The walkthrough examples use local mock mode through the quickstart/testing help
 
 ### ☁️ Traigent Portal & Hybrid Tracking
 
-Connect to [Traigent Portal](https://portal.traigent.ai) to view results, compare trials, and collaborate. The supported portal-visible SDK path today is `execution_mode="hybrid"`: trials run locally, while session and trial metrics are stored in the backend for portal tracking.
+Connect to [Traigent Portal](https://portal.traigent.ai) to view results, compare trials, and collaborate. Portal tracking is enabled automatically when `TRAIGENT_API_KEY` is set — you do not need to set `execution_mode`. The SDK auto-selects the mode based on algorithm and transport.
 
-`execution_mode="cloud"` is reserved for future remote agent execution. It is not available yet and fails with: “Cloud remote execution is not available yet; use hybrid for portal-tracked optimization.”
+`execution_mode=”cloud”` is reserved for future remote agent execution and is not available yet.
 
 1. **Sign up** at [portal.traigent.ai](https://portal.traigent.ai) — verify your email to activate
 2. **Create an API key** — click your name (top-right) → **API Keys** → **+ Create API Key**
-3. **Connect** — run `traigent auth login` or set `export TRAIGENT_API_KEY="sk_..."`  <!-- pragma: allowlist secret -->
-4. **Run with hybrid tracking** — set `execution_mode="hybrid"` for portal-visible optimization
+3. **Connect** — run `traigent auth login` or set `export TRAIGENT_API_KEY=”sk_...”`  <!-- pragma: allowlist secret -->
+4. **Run** — portal tracking is automatic; no `execution_mode` needed
 
 <details>
 <summary>Credential priority and multi-provider setup</summary>
@@ -244,7 +254,7 @@ def multi_provider_agent(question: str) -> str:
 | Feature | Description |
 |---------|-------------|
 | **Zero-code integration** | Add `@traigent.optimize()` to existing code — no refactoring |
-| **Multi-algorithm** | Random, Grid, Bayesian (TPE, NSGA-II, CMA-ES) via Optuna |
+| **Multi-algorithm** | Random and Grid locally; Bayesian (TPE, NSGA-II, CMA-ES) via the Traigent cloud |
 | **Multi-objective** | Optimize accuracy, latency, cost, and custom metrics simultaneously |
 | **Framework support** | LangChain, OpenAI SDK, Anthropic, LiteLLM, and any LLM provider |
 | **Cost tracking** | Integrated tokencost library with 500+ model pricing |
@@ -262,19 +272,20 @@ def multi_provider_agent(question: str) -> str:
 
 ### Installation
 
-Python 3.11+ on Linux, macOS, or Windows. For coordinated release validation, install from this repository source tree.
+Python 3.11+ on Linux, macOS, or Windows. The published package on [PyPI](https://pypi.org/project/traigent/) is the recommended way to install — `pip install "traigent[recommended]"` or `uv add "traigent[recommended]"`. No repository checkout is required to use the SDK or its `traigent` CLI.
 
 | Feature Set | Description |
 |-------------|-------------|
 | `[recommended]` | All user-facing features (default) |
 | `[integrations]` | LangChain, OpenAI, Anthropic adapters |
 | `[analytics]` | Visualization and analytics |
-| `[bayesian]` | Bayesian optimization (TPE, NSGA-II) |
+| `[bayesian]` | Bayesian optimization dependencies (used by the Traigent cloud; not available locally) |
 | `[all]` | Everything |
 
 **[Full installation guide →](docs/getting-started/installation.md)**
 
-Source install with `pip`:
+Contributor / source install (only needed to hack on Traigent itself or run the
+coordinated release-validation suite — not required to use the SDK):
 
 ```bash
 git clone https://github.com/Traigent/Traigent.git
@@ -318,8 +329,8 @@ Provide a JSONL dataset — Traigent scores outputs using semantic similarity by
 
 | Mode | Status | Privacy | Algorithm | Best For |
 |------|--------|---------|-----------|----------|
-| **Local** (`edge_analytics`) | ✅ Available | ✅ Complete | All (Random/Grid/Bayesian/Optuna) | Local/private runs |
-| **Hybrid** (`hybrid`) | ✅ Available | ✅ Trial execution local | All (Random/Grid/Bayesian/Optuna) | Portal-tracked runs |
+| **Local** (`edge_analytics`) | ✅ Available | ✅ Complete | Random, Grid | Local/private runs |
+| **Hybrid** (`hybrid`) | ✅ Available | ✅ Trial execution local | Random, Grid + cloud smart algorithms | Portal-tracked runs |
 | **Cloud** (`cloud`) | 🚧 Reserved | Not available | Future remote execution | Do not use yet |
 
 **[Execution modes guide →](docs/guides/execution-modes.md)** — mode comparisons, privacy details, migration path
@@ -331,7 +342,7 @@ Provide a JSONL dataset — Traigent scores outputs using semantic similarity by
 | `configuration_space` | `@traigent.optimize()` | Parameters to test (required) |
 | `objectives` | `@traigent.optimize()` | Metrics to optimize for |
 | `eval_dataset` | `@traigent.optimize()` | Dataset for evaluation |
-| `algorithm` | `.optimize()` call | `"random"`, `"grid"`, `"bayesian"` |
+| `algorithm` | `.optimize()` call | `"random"`, `"grid"` (local); smart algorithms run in the Traigent cloud |
 | `max_trials` | `.optimize()` call | Number of configurations to test |
 | `progress_bar` | `.optimize()` call | `True` / `False` / `None` (auto) — live progress bar |
 

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

@@ -560,7 +560,7 @@ The `**runtime_overrides` parameter accepts additional settings:
 
 ```python
 @traigent.optimize(
-    algorithm="optuna",  # "grid", "random", "bayesian", "optuna"
+    algorithm="grid",  # "grid" or "random" (local); smart algorithms run in the Traigent cloud
     ...
 )
 ```

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

@@ -77,9 +77,9 @@ export TRAIGENT_TRACE_ENABLED=true
 
 `TRAIGENT_TRACE_ENABLED` is the canonical tracing flag and defaults to
 `false`. It controls SDK span emission and workflow trace tracker creation.
-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.
+The older plural spelling `TRAIGENT_TRACES_ENABLED` is **no longer supported**
+as of 0.13.0 and is silently ignored. If you were using `TRAIGENT_TRACES_ENABLED`,
+migrate to `TRAIGENT_TRACE_ENABLED`.
 
 ### Agent Workflow Spans
 

{traigent-0.13.0.dev1 → traigent-0.14.0}/docs/examples/API_PATTERNS.md

@@ -193,6 +193,115 @@ def external_agent(_query: str) -> str:
 results = await external_agent.optimize(max_trials=10)
 ```
 
+## Multi-Field Evaluation Inputs
+
+Many tasks need more than a single input string. A text2SQL task, for example,
+requires both the natural-language question (`input`) and the database name
+(`db_id`) and ground-truth SQL (`gold_sql`) for evaluation. The SDK supports
+this through `example.metadata`.
+
+### How extra JSONL fields are routed
+
+When the SDK loads a JSONL dataset it applies the following mapping for each row:
+
+| JSONL key | Maps to |
+|---|---|
+| `input` (or `input_data`) | `example.input_data` |
+| `expected_output` (or `expected`, `output`, `answer`, `target`, `label`) | `example.expected_output` |
+| **every other key** | `example.metadata` (a `dict`) |
+
+A row like:
+
+```jsonl
+{"input": "How many employees live in each city?", "expected_output": "3 rows", "db_id": "company", "gold_sql": "SELECT city, COUNT(*) FROM employees GROUP BY city"}
+```
+
+produces an `EvaluationExample` where:
+- `example.input_data` → `"How many employees live in each city?"`
+- `example.expected_output` → `"3 rows"`
+- `example.metadata` → `{"db_id": "company", "gold_sql": "SELECT city, COUNT(*) FROM employees GROUP BY city"}`
+
+### Accessing metadata in a custom evaluator
+
+Use `custom_evaluator` to read extra fields alongside the function output.
+The evaluator receives the raw `EvaluationExample` and must return an
+`ExampleResult`:
+
+```python
+import traigent
+from traigent.api.types import ExampleResult
+
+
+def sql_evaluator(func, config, example):
+    db_id = example.metadata.get("db_id", "default")
+    gold_sql = example.metadata.get("gold_sql", "")
+
+    predicted_sql = func(example.input_data)
+    correct = predicted_sql.strip().lower() == gold_sql.strip().lower()
+    return ExampleResult(
+        actual_output=predicted_sql,
+        score=1.0 if correct else 0.0,
+        success=correct,
+    )
+
+
+@traigent.optimize(
+    eval_dataset="data/text2sql.jsonl",
+    custom_evaluator=sql_evaluator,
+    objectives=["accuracy"],
+    configuration_space={
+        "model": ["claude-3-haiku-20240307"],
+        "temperature": [0.0, 0.3],
+    },
+)
+def text2sql_agent(question: str) -> str:
+    cfg = traigent.get_config()
+    return call_llm(question, model=cfg["model"], temperature=cfg["temperature"])
+```
+
+> **Note:** a plain `scoring_function(output, expected)` does not receive
+> `example.metadata`. Use `custom_evaluator` whenever the task needs extra
+> fields beyond the predicted and expected outputs.
+
+### Multi-field input dict
+
+When the optimized function itself needs multiple inputs, set `input` to a
+JSON object:
+
+```jsonl
+{"input": {"question": "Find all cities with more than 100 employees", "schema": "employees(id, city, dept)"}, "expected_output": "SELECT city FROM employees GROUP BY city HAVING COUNT(*) > 100"}
+```
+
+The SDK passes the dict's keys as keyword arguments if the function signature
+matches (either via named parameters or `**kwargs`):
+
+```python
+@traigent.optimize(
+    eval_dataset="data/text2sql.jsonl",
+    scoring_function=my_score,
+    objectives=["accuracy"],
+    configuration_space={"model": ["claude-3-haiku-20240307"], "temperature": [0.0]},
+)
+def text2sql_agent(question: str, schema: str) -> str:
+    cfg = traigent.get_config()
+    return call_llm(
+        f"Schema: {schema}\nQuestion: {question}",
+        model=cfg["model"],
+        temperature=cfg["temperature"],
+    )
+```
+
+Alternatively, accept `**kwargs` to keep the signature flexible:
+
+```python
+@traigent.optimize(...)
+def text2sql_agent(**kwargs) -> str:
+    cfg = traigent.get_config()
+    question = kwargs["question"]
+    schema = kwargs.get("schema", "")
+    return call_llm(f"Schema: {schema}\nQ: {question}", model=cfg["model"])
+```
+
 ## Mock Smoke Tests
 
 For tutorials and CI smoke tests, call mock mode explicitly near the top of the

{traigent-0.13.0.dev1 → traigent-0.14.0}/docs/getting-started/GETTING_STARTED.md

@@ -146,13 +146,11 @@ def my_agent(query: str) -> str:
 
 ## 🔒 Execution Model
 
-Traigent executes your code locally. The default is `execution_mode="edge_analytics"` (local).
+Traigent executes your code locally. **You do not need to set `execution_mode`** — the SDK auto-selects it based on your algorithm and configuration.
 
-`execution_mode="hybrid"` runs trials locally while sending session and trial metrics to the backend so results appear in the Traigent portal.
+Portal tracking (results visible in the Traigent portal) is enabled automatically when `TRAIGENT_API_KEY` is set. For grid/random search, the auto-selected mode is `edge_analytics`; for smart algorithms (Bayesian, TPE), it is `hybrid`.
 
-`execution_mode="cloud"` is reserved for future remote execution. It is not available yet and fails with: “Cloud remote execution is not available yet; use hybrid for portal-tracked optimization.”
-
-If you want website-visible results today, use `hybrid`; do not switch to `cloud`.
+`execution_mode=”cloud”` is reserved for future remote execution and is not available yet.
 
 To run fully local (no Traigent backend communication), set `TRAIGENT_OFFLINE_MODE=true`.
 

{traigent-0.13.0.dev1 → traigent-0.14.0}/docs/guides/execution-modes.md

@@ -1,24 +1,27 @@
 # Traigent Execution Modes Guide
 
-> **Current status:** Traigent executes trials locally. The default is `execution_mode="edge_analytics"` (local-only). Use `execution_mode="hybrid"` when you want local execution plus backend/portal tracking. `execution_mode="cloud"` is reserved for future remote execution and fails with: “Cloud remote execution is not available yet; use hybrid for portal-tracked optimization.”
+> **Current status (0.13+):** Traigent auto-selects the execution mode — you do not need to set `execution_mode` explicitly. Portal tracking is enabled automatically when `TRAIGENT_API_KEY` is set, regardless of mode. `execution_mode=”cloud”` is reserved for future remote execution and is not available yet.
 
 ## Overview
 
-Use `edge_analytics` (default) to run locally. Use `hybrid` for website-visible results while keeping trials on your machine. Do not use `cloud` yet; remote agent execution is not implemented.
+**You do not need to set `execution_mode`.** The SDK picks the right mode automatically:
 
-To run fully local (no Traigent backend communication), set `TRAIGENT_OFFLINE_MODE=true`.
+- **Grid/random search (typical Python decorator use)** → `edge_analytics` (local execution; portal-tracked when `TRAIGENT_API_KEY` is present)
+- **Smart algorithms (Bayesian, TPE, CMA-ES)** → `hybrid` (cloud-assisted orchestration; requires API key)
+- **External REST agent service** → `hybrid_api` (your service receives suggestions via the Hybrid Mode REST API)
 
-## Migration Note
+Portal tracking (results visible in the Traigent portal) is a function of having `TRAIGENT_API_KEY` set, not of the execution mode.
 
-If you want optimization results in the Traigent website, use `execution_mode="hybrid"`, not `execution_mode="cloud"`. Hybrid is the supported production path for portal-tracked SDK optimization. Cloud is reserved for a future product path where Traigent Cloud runs the remote agent execution itself.
+To run fully local (no Traigent backend communication), set `TRAIGENT_OFFLINE_MODE=true` or omit `TRAIGENT_API_KEY`.
 
 ## Modes at a Glance
 
-| Mode | OSS availability | Status | Notes |
-| --- | --- | --- | --- |
-| `edge_analytics` | Available | Supported | Local execution and local results |
-| `hybrid` | Available | Supported | Local execution plus backend session/trial tracking |
-| `cloud` | Reserved | Not implemented | Remote execution path fails closed |
+| Mode | When auto-selected | Notes |
+| --- | --- | --- |
+| `edge_analytics` | Grid/random search | Local execution; portal-visible when API key is set |
+| `hybrid` | Smart algorithms (Bayesian, TPE, …) | Cloud-assisted orchestration; API key required |
+| `hybrid_api` | External REST agent service configured | Your agent receives suggestions via REST |
+| `cloud` | (reserved) | Remote execution — not implemented yet; fails closed |
 
 ## Local Mode (`edge_analytics`)
 
@@ -64,11 +67,15 @@ def my_agent(query: str) -> str:
 - CI smoke tests and demos (`TRAIGENT_MOCK_LLM=true`)
 - Budget-conscious experiments
 
-## Hybrid Mode
+## Hybrid Mode (`hybrid`)
 
-Hybrid mode is the production path for portal-tracked SDK runs today. The SDK creates a backend session, runs each trial locally, and submits trial metrics to the backend session/result endpoints so the run appears in the portal.
+Auto-selected when a smart algorithm (Bayesian, TPE, CMA-ES, NSGA-II) is requested. The SDK uses cloud-assisted orchestration for suggestion generation while running each trial locally.
 
-Use `hybrid` when you want results to appear in the Traigent website. Use `edge_analytics` when you want fully local runs with no backend dependency.
+`hybrid` is **not** the mode to set for "I want portal visibility with grid/random search" — that is `edge_analytics` with `TRAIGENT_API_KEY` set. Use `hybrid` only if you explicitly need smart cloud-assisted optimization algorithms.
+
+## Hybrid API Mode (`hybrid_api`)
+
+Auto-selected when a Hybrid Mode REST endpoint or transport is configured (`hybrid_api_endpoint` / `hybrid_api_transport`). Your external agent service receives trial suggestions via the Traigent Hybrid Mode REST API.
 
 ## Cloud Roadmap
 

{traigent-0.13.0.dev1 → traigent-0.14.0}/docs/user-guide/agent_optimization.md

@@ -2,7 +2,7 @@
 
 This guide describes the planned Model 2 agent-specification API.
 
-> **Current status:** Remote agent optimization in Traigent Cloud is not implemented yet. The `execution_mode="cloud"` path fails closed with: “Cloud remote execution is not available yet; use hybrid for portal-tracked optimization.” Use `execution_mode="hybrid"` for portal-visible SDK runs today; trials still execute locally.
+> **Current status:** Remote agent optimization in Traigent Cloud is not implemented yet. The `execution_mode="cloud"` path fails closed with: “Cloud remote execution is not available yet; use hybrid for portal-tracked optimization.” Mode is auto-selected; set `TRAIGENT_API_KEY` for portal-visible runs.
 
 ## Overview
 

{traigent-0.13.0.dev1 → traigent-0.14.0}/docs/user-guide/choosing_optimization_model.md

@@ -2,7 +2,7 @@
 
 Traigent SDK currently supports local execution and portal-tracked local execution. This guide separates supported modes from future remote execution paths.
 
-> **Current status:** Use `execution_mode="edge_analytics"` for fully local runs and `execution_mode="hybrid"` for portal-tracked runs where trials still execute locally. `execution_mode="cloud"` and managed remote agent execution are not implemented yet and fail closed with guidance to use `hybrid`.
+> **Current status (0.13+):** The SDK auto-selects `execution_mode` — you do not need to set it. Portal tracking is enabled by having `TRAIGENT_API_KEY` set. For fully offline runs, set `TRAIGENT_OFFLINE_MODE=true`. `execution_mode="cloud"` is not implemented yet.
 
 ## Quick Decision Guide
 
@@ -164,12 +164,13 @@ async with cloud_client:
 # response includes optimization details and best configuration
 ```
 
-### Supported Hybrid Approach
+### Portal-Tracked Runs
 
-Use `execution_mode="hybrid"` when you want the supported portal-tracked path:
-- Trials execute locally.
-- The backend stores session metadata and trial metrics.
-- Results appear in the Traigent portal without using the unavailable remote cloud execution path.
+To get results in the Traigent portal: set `TRAIGENT_API_KEY` and run normally. The SDK sends session/trial metrics to the backend automatically. **No `execution_mode` change needed.**
+
+- For grid/random search: auto-selected mode is `edge_analytics`; portal tracking is on when API key is present.
+- For smart algorithms (Bayesian, TPE, CMA-ES): auto-selected mode is `hybrid`.
+- For external REST agent services: configure `hybrid_api_endpoint`; auto-selected mode is `hybrid_api`.
 
 ## Decision Factors
 
@@ -231,14 +232,14 @@ Use `execution_mode="hybrid"` when you want the supported portal-tracked path:
 ### From Local-Only to Portal-Tracked:
 
 1. Keep the optimized function and dataset unchanged.
-2. Authenticate with `traigent auth device-login`, run `traigent onboard` for guided setup, or set `TRAIGENT_API_KEY` in CI/non-interactive environments.
-3. Set `execution_mode="hybrid"`.
+2. Authenticate: run `traigent auth device-login`, `traigent onboard`, or set `TRAIGENT_API_KEY` in CI/non-interactive environments.
+3. Run normally — the SDK sends metrics to the portal automatically.
 4. Confirm the run appears in Traigent Portal.
 
 ### From Accidental Cloud Usage:
 
-1. Replace `execution_mode="cloud"` with `execution_mode="hybrid"` when you want website results.
-2. Use `execution_mode="edge_analytics"` and `TRAIGENT_OFFLINE_MODE=true` when you want no backend dependency.
+1. Remove `execution_mode="cloud"` — set `TRAIGENT_API_KEY` for portal-tracked runs (mode is auto-selected).
+2. Use `TRAIGENT_OFFLINE_MODE=true` when you want no backend dependency.
 3. Treat cloud remote execution docs and APIs as roadmap/reference material until the product path is released.
 
 ## Performance Tips
@@ -270,8 +271,6 @@ Use `execution_mode="hybrid"` when you want the supported portal-tracked path:
 
 Choose based on your primary constraints:
 
-- **Privacy/local-only**: `edge_analytics`
-- **Website-visible results**: `hybrid`
+- **Privacy/local-only (no portal)**: `edge_analytics` + `TRAIGENT_OFFLINE_MODE=true`
+- **Portal-visible results**: set `TRAIGENT_API_KEY`; mode auto-selected (`edge_analytics` for grid/random, `hybrid` for smart algorithms)
 - **Remote cloud execution**: reserved for a future release
-
-For now, users wanting website results should use `hybrid`, not `cloud`.

{traigent-0.13.0.dev1 → traigent-0.14.0}/docs/user-guide/interactive_optimization.md

@@ -2,7 +2,7 @@
 
 This guide documents Traigent's interactive optimization model for client-side execution with remote guidance.
 
-> **Current status:** The generic `InteractiveOptimizer` can be used with a real `RemoteGuidanceService` implementation, but Traigent Cloud remote guidance is not a supported production path yet. Use `execution_mode="hybrid"` for portal-tracked SDK optimization today; use `execution_mode="edge_analytics"` for fully local runs.
+> **Current status:** The generic `InteractiveOptimizer` can be used with a real `RemoteGuidanceService` implementation, but Traigent Cloud remote guidance is not a supported production path yet. Mode is auto-selected; set `TRAIGENT_API_KEY` for portal-tracked runs, or `TRAIGENT_OFFLINE_MODE=true` for fully local runs.
 
 ## Overview
 
@@ -85,7 +85,7 @@ and name the result-submission method `submit_trial_result`. Use
 signature differences into your code.
 
 > Backend availability: the Traigent Cloud remote-guidance endpoints back
-> these adapter calls. Use `execution_mode="hybrid"` if you only need
+> these adapter calls. Use `edge_analytics` mode (auto-selected) if you only need
 > portal-tracked SDK runs with local trial execution.