traigent 0.14.3__tar.gz → 0.16.0.dev0__tar.gz

{traigent-0.14.3 → traigent-0.16.0.dev0}/CHANGELOG.md

@@ -4,18 +4,17 @@ All notable changes to Traigent SDK are documented in this file.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.14.3] - 2026-06-20
+## [Unreleased]
 
-### Changed
-- **Removed the JS bridge from the `@optimize` decorator path** and added a guard for
-  `safety_constraints`. (#1371)
-
-### Security
-- Addressed scoped Aikido security findings. (#1374)
+### Added
+- Added a no-content-egress cloud-brain canary test that captures serialized
+  session, next-trial, metrics, and finalize payloads and asserts dataset
+  example content never crosses the backend boundary.
 
-### Fixed
-- Corrected the async context-manager mock in the hybrid degradation test and updated
-  `test_safety.py` integration tests for the `NotImplementedError` guard.
+### Changed
+- Rewrote execution-mode guidance around `algorithm` and `offline`: cloud-first
+  `auto`, explicit local `grid`/`random`, zero-egress offline mode, result
+  provenance, and legacy selector deprecations.
 
 ## [0.14.1] - 2026-06-19
 

{traigent-0.14.3/traigent.egg-info → traigent-0.16.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.14.3
+Version: 0.16.0.dev0
 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
@@ -276,7 +276,7 @@ Works with any LLM provider — [OpenAI](https://platform.openai.com/docs), [Ant
 |------|----------|------|
 | **Get started quickly** | [Quick Start Guide](docs/getting-started/GETTING_STARTED.md) | 5 min |
 | **Understand the architecture** | [Architecture Overview](docs/architecture/ARCHITECTURE.md) | 5 min |
-| **Track local runs in the portal** | [Hybrid portal tracking](#portal-hybrid-tracking) | 5 min |
+| **Track runs in the portal** | [Portal tracking](#portal-tracking) | 5 min |
 | **Try examples locally, then make runs portal-visible** | [Mock walkthrough](walkthrough/mock/) (8 steps) → [Portal](https://portal.traigent.ai) | 15 min |
 | **Read the full API reference** | [Decorator Reference →](docs/api-reference/decorator-reference.md) | — |
 
@@ -341,7 +341,7 @@ The walkthrough examples use local mock mode through the quickstart/testing help
 | 5 | `python walkthrough/mock/05_rag_parallel.py` | RAG optimization with parallel evaluation |
 | 6 | `python walkthrough/mock/06_custom_evaluator.py` | Define your own success metrics |
 | 7 | `python walkthrough/mock/07_multi_provider.py` | Compare OpenAI, Anthropic, Google in one run |
-| 8 | `python walkthrough/mock/08_privacy_modes.py` | Local-only privacy-first execution |
+| 8 | `python walkthrough/mock/08_privacy_modes.py` | No-egress local execution |
 
 </details>
 
@@ -349,18 +349,18 @@ The walkthrough examples use local mock mode through the quickstart/testing help
 
 ---
 
-<a id="portal-hybrid-tracking"></a>
+<a id="portal-tracking"></a>
 
-### ☁️ Traigent Portal & Hybrid Tracking
+### ☁️ Traigent 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.
+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; most users do not need any routing settings.
 
-`execution_mode=”cloud”` is reserved for future remote agent execution and is not available yet.
+The default run uses Traigent's smart optimizer when portal credentials are available. Local `grid` and `random` searches still sync results to the portal when authenticated. Use `offline=True` only when a run must avoid Traigent backend egress; offline runs do not sync.
 
 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** — portal tracking is automatic; no `execution_mode` needed
+4. **Run** — portal tracking is automatic
 
 <details>
 <summary>Credential priority and multi-provider setup</summary>
@@ -409,14 +409,14 @@ def multi_provider_agent(question: str) -> str:
 | **Parallel execution** | Concurrent trials and example-level parallelism |
 | **Error resilience** | Interactive pause on rate limits and budget caps — resume or stop gracefully |
 | **Live progress** | Auto-enabled progress bar in interactive terminals (`progress_bar=False` to disable) |
-| **Privacy-first** | Local execution mode keeps all data on your machine |
+| **No-egress option** | `offline=True` keeps Traigent optimization traffic local when policy requires it |
 
 **TraigentDemo** — Streamlit playground, use cases, and research benchmarks
 
 ---
 
 <details>
-<summary>📦 Installation details, execution modes, CLI, and more</summary>
+<summary>📦 Installation details, optimization routing, CLI, and more</summary>
 
 ### Installation
 
@@ -473,15 +473,18 @@ Provide a JSONL dataset — Traigent scores outputs using semantic similarity by
 
 **[Evaluation guide →](docs/guides/evaluation.md)** — custom evaluators, dataset formats, troubleshooting
 
-### Execution Modes
+### Optimization Routing
 
-| Mode | Status | Privacy | Algorithm | Best For |
-|------|--------|---------|-----------|----------|
-| **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 |
+| Request | Where optimization decisions come from | Portal sync |
+|------|--------|---------|
+| Omit routing settings | Traigent smart optimizer when authenticated | Yes |
+| `algorithm="grid"` or `"random"` | Local search in your Python process | Yes, unless `offline=True` |
+| Smart algorithm name, such as `"bayesian"` or `"optuna_tpe"` | Traigent cloud optimizer | Yes |
+| `offline=True` | Local only, zero Traigent backend egress | No |
 
-**[Execution modes guide →](docs/guides/execution-modes.md)** — mode comparisons, privacy details, migration path
+Most users should omit these settings. Use `grid` or `random` for explicit local search; use `offline=True` only for no-egress runs.
+
+**[Optimization routing guide →](docs/guides/execution-modes.md)** — defaults, local search, portal sync, and migration notes
 
 ### Quick Reference
 

{traigent-0.14.3 → traigent-0.16.0.dev0}/README.md

@@ -128,7 +128,7 @@ Works with any LLM provider — [OpenAI](https://platform.openai.com/docs), [Ant
 |------|----------|------|
 | **Get started quickly** | [Quick Start Guide](docs/getting-started/GETTING_STARTED.md) | 5 min |
 | **Understand the architecture** | [Architecture Overview](docs/architecture/ARCHITECTURE.md) | 5 min |
-| **Track local runs in the portal** | [Hybrid portal tracking](#portal-hybrid-tracking) | 5 min |
+| **Track runs in the portal** | [Portal tracking](#portal-tracking) | 5 min |
 | **Try examples locally, then make runs portal-visible** | [Mock walkthrough](walkthrough/mock/) (8 steps) → [Portal](https://portal.traigent.ai) | 15 min |
 | **Read the full API reference** | [Decorator Reference →](docs/api-reference/decorator-reference.md) | — |
 
@@ -193,7 +193,7 @@ The walkthrough examples use local mock mode through the quickstart/testing help
 | 5 | `python walkthrough/mock/05_rag_parallel.py` | RAG optimization with parallel evaluation |
 | 6 | `python walkthrough/mock/06_custom_evaluator.py` | Define your own success metrics |
 | 7 | `python walkthrough/mock/07_multi_provider.py` | Compare OpenAI, Anthropic, Google in one run |
-| 8 | `python walkthrough/mock/08_privacy_modes.py` | Local-only privacy-first execution |
+| 8 | `python walkthrough/mock/08_privacy_modes.py` | No-egress local execution |
 
 </details>
 
@@ -201,18 +201,18 @@ The walkthrough examples use local mock mode through the quickstart/testing help
 
 ---
 
-<a id="portal-hybrid-tracking"></a>
+<a id="portal-tracking"></a>
 
-### ☁️ Traigent Portal & Hybrid Tracking
+### ☁️ Traigent 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.
+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; most users do not need any routing settings.
 
-`execution_mode=”cloud”` is reserved for future remote agent execution and is not available yet.
+The default run uses Traigent's smart optimizer when portal credentials are available. Local `grid` and `random` searches still sync results to the portal when authenticated. Use `offline=True` only when a run must avoid Traigent backend egress; offline runs do not sync.
 
 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** — portal tracking is automatic; no `execution_mode` needed
+4. **Run** — portal tracking is automatic
 
 <details>
 <summary>Credential priority and multi-provider setup</summary>
@@ -261,14 +261,14 @@ def multi_provider_agent(question: str) -> str:
 | **Parallel execution** | Concurrent trials and example-level parallelism |
 | **Error resilience** | Interactive pause on rate limits and budget caps — resume or stop gracefully |
 | **Live progress** | Auto-enabled progress bar in interactive terminals (`progress_bar=False` to disable) |
-| **Privacy-first** | Local execution mode keeps all data on your machine |
+| **No-egress option** | `offline=True` keeps Traigent optimization traffic local when policy requires it |
 
 **TraigentDemo** — Streamlit playground, use cases, and research benchmarks
 
 ---
 
 <details>
-<summary>📦 Installation details, execution modes, CLI, and more</summary>
+<summary>📦 Installation details, optimization routing, CLI, and more</summary>
 
 ### Installation
 
@@ -325,15 +325,18 @@ Provide a JSONL dataset — Traigent scores outputs using semantic similarity by
 
 **[Evaluation guide →](docs/guides/evaluation.md)** — custom evaluators, dataset formats, troubleshooting
 
-### Execution Modes
+### Optimization Routing
 
-| Mode | Status | Privacy | Algorithm | Best For |
-|------|--------|---------|-----------|----------|
-| **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 |
+| Request | Where optimization decisions come from | Portal sync |
+|------|--------|---------|
+| Omit routing settings | Traigent smart optimizer when authenticated | Yes |
+| `algorithm="grid"` or `"random"` | Local search in your Python process | Yes, unless `offline=True` |
+| Smart algorithm name, such as `"bayesian"` or `"optuna_tpe"` | Traigent cloud optimizer | Yes |
+| `offline=True` | Local only, zero Traigent backend egress | No |
 
-**[Execution modes guide →](docs/guides/execution-modes.md)** — mode comparisons, privacy details, migration path
+Most users should omit these settings. Use `grid` or `random` for explicit local search; use `offline=True` only for no-egress runs.
+
+**[Optimization routing guide →](docs/guides/execution-modes.md)** — defaults, local search, portal sync, and migration notes
 
 ### Quick Reference
 

{traigent-0.14.3 → traigent-0.16.0.dev0}/docs/README.md

@@ -53,7 +53,7 @@ def answer_question(question: str) -> str:
 - **[Optuna Integration](user-guide/optuna_integration.md)** - Optuna-backed optimizers, coordinator, and adapter
 
 ### 🧭 [Guides](guides/)
-- **[Execution Modes](guides/execution-modes.md)** - Local, hybrid portal tracking, and reserved cloud execution behavior
+- **[Optimization Routing](guides/execution-modes.md)** - Default smart optimization, local search, portal sync, and no-egress runs
 - **[Evaluation](guides/evaluation.md)** - Evaluation best practices and troubleshooting
 - **[Parallel Configuration](guides/parallel-configuration.md)** - Concurrency settings and tuning
 - **[Secrets Management](guides/secrets_management.md)** - Securely manage API keys

{traigent-0.14.3 → traigent-0.16.0.dev0}/docs/api-reference/complete-function-specification.md

@@ -116,34 +116,23 @@ def my_agent(question: str) -> str:
 | --- | --- | --- |
 | `evaluation` | `EvaluationOptions \| dict \| None` | Bundle for `eval_dataset`, `custom_evaluator`, `scoring_function`, and `metric_functions`. |
 | `injection` | `InjectionOptions \| dict \| None` | Bundle for `injection_mode`, `config_param`, `auto_override_frameworks`, and `framework_targets`. |
-| `execution` | `ExecutionOptions \| dict \| None` | Bundle for execution settings including `execution_mode`, `local_storage_path`, `parallel_config`, `privacy_enabled`, and `max_total_examples`. |
+| `execution` | `ExecutionOptions \| dict \| None` | Bundle for execution settings including `algorithm`, `offline`, `local_storage_path`, `parallel_config`, 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**
 
 | 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. `"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"`. |
+| `algorithm` | `str` | `"auto"` | Optimizer selector. `"auto"` uses Traigent's smart optimizer when authenticated; `"grid"` and `"random"` run local search; smart algorithms require cloud. |
+| `offline` | `bool` | `False` | Force local-only operation with zero Traigent backend egress and no portal sync. |
 | `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. |
+| `minimal_logging` | `bool` | `True` | Suppresses verbose logs. |
 | `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. |
+| `evaluator` | `ExternalServiceEvaluator \| dict \| None` | `None` | External service evaluator bundle for API-contract integrations. This does not change optimizer routing. |
 
 **Legacy Compatibility**
 
@@ -154,11 +143,13 @@ def my_agent(question: str) -> str:
 
 **Usage Notes**
 
-- The default execution mode is `"edge_analytics"`. Use `"hybrid"` for portal-tracked optimization with local trial execution.
+- The default path is `algorithm="auto"`: Traigent smart optimization when portal credentials are available, with trials executing in your process.
+- Set `TRAIGENT_REQUIRE_CLOUD=1` to turn that connectivity fallback into a hard error.
 - Prefer the grouped option classes (`EvaluationOptions`, `InjectionOptions`, `ExecutionOptions`) when you need to adjust several related knobs. Import them from `traigent.api.decorators` and pass either instances or plain dicts. `MockModeOptions` is **deprecated** (all fields inert; see the `mock` row above and issue #874) — do not use it for new code.
 - `parallel_config=ParallelConfig(...)` remains the primary way to control concurrency. Set global defaults via `traigent.configure(parallel_config=...)`, override them in the decorator, and fine-tune per `.optimize()` call. Later scopes override earlier ones field-by-field.
 - `ParallelConfig` lives in `traigent.config.parallel`. You can pass either an instance or a simple `dict` with the same keys.
-- `privacy_enabled=True` applies in local and hybrid contexts. `cloud` remote execution is not available yet.
+- Use `offline=True` when policy requires zero Traigent backend egress. Local `grid` and `random` runs still sync results to the portal unless `offline=True`.
+- Legacy `execution_mode` inputs are deprecated compatibility shims. Use `algorithm` and `offline` for new code.
 - `config_param` is required whenever you choose `injection_mode="parameter"`; forgetting it leaves your function without injected configs.
 - Provide plain lists for quick starts; Traigent infers orientations (maximize for accuracy-like metrics, minimize for cost/latency) and assigns equal weights. Use an `ObjectiveSchema` when you need explicit control over orientations, weights, or metric metadata.
 - Inline tuned-variable definitions accept `Range`, `IntRange`, `LogRange`, `Choices`, or numeric `(low, high)` tuples. Inline lists are not recognized; use `Choices([...])` instead.
@@ -189,7 +180,6 @@ Later scopes override earlier ones field-by-field. The runtime resolution logs t
         "temperature": (0.0, 1.0)
     },
     evaluation={"eval_dataset": "evals.jsonl"},  # Grouped option bundle
-    execution={"execution_mode": "edge_analytics"},
 )
 def my_agent(query: str) -> str:
     return process_query(query)
@@ -228,7 +218,7 @@ async def optimize(
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `algorithm` | `str \| None` | Decorator default | Optimizer to use: `"grid"`, `"random"`, `"bayesian"`, `"optuna"`. |
+| `algorithm` | `str \| None` | Decorator default | Optimizer to use. Omit it for the default smart optimizer. `"grid"` and `"random"` run local search and still sync results when authenticated. Explicit smart algorithms such as `"bayesian"`, `"tpe"`, `"optuna_tpe"`, `"optuna_random"`, `"optuna_grid"`, `"optuna_cmaes"`, `"optuna_nsga2"`, `"nsga2"`, `"nsgaii"`, `"nsga_ii"`, `"cmaes"`, and `"cma_es"` require cloud and hard-error when unavailable or offline. |
 | `max_trials` | `int \| None` | Decorator default | Maximum number of trials to execute. `None` means unlimited. |
 | `timeout` | `float \| None` | Decorator default | Wall-clock budget in seconds. |
 | `save_to` | `str \| None` | `None` | Optional path to persist results after completion. |
@@ -264,8 +254,8 @@ Unknown keys are forwarded to the optimizer and may raise errors when unsupporte
 
 **Example:**
 ```python
-# Run optimization
-result = await my_agent.optimize(algorithm="grid", max_trials=50)
+# Run optimization with the default smart optimizer
+result = await my_agent.optimize(max_trials=50)
 
 # Save results
 await my_agent.save_optimization_results("results.json")
@@ -535,6 +525,9 @@ class OptimizationResult:
 - `successful_trials`: List of trials that completed successfully
 - `success_rate`: Ratio of successful trials to total trials
 
+`metadata["source"]` records result provenance as one of `cloud_brain`,
+`local_fallback`, `explicit_local`, or `offline`.
+
 ### TrialResult
 
 ```python

{traigent-0.14.3 → traigent-0.16.0.dev0}/docs/api-reference/decorator-reference.md

@@ -489,11 +489,11 @@ from traigent.config.parallel import ParallelConfig
 
 @traigent.optimize(
     execution=ExecutionOptions(
-        execution_mode="edge_analytics",
+        algorithm="grid",
+        offline=True,
         local_storage_path="./my_results",
         minimal_logging=True,
         parallel_config=ParallelConfig(thread_workers=4, trial_concurrency=2),
-        privacy_enabled=False,
         max_total_examples=1000,
         samples_include_pruned=True,
         reps_per_trial=1,
@@ -505,17 +505,16 @@ from traigent.config.parallel import ParallelConfig
 
 **ExecutionOptions Fields**:
 
-- `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.
+- `algorithm`: optimizer selector. `"auto"` is the default smart optimizer; `"grid"` and `"random"` run local search and still sync results when authenticated; smart algorithms require cloud and hard-error when unavailable or offline.
+- `offline`: force local-only operation with zero Traigent backend egress and no portal sync.
 - `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.
+- `evaluator`: external evaluator bundle for API-contract integrations. This does not change optimizer routing; it only changes how each trial is evaluated.
 
 #### `mock`
 
@@ -565,6 +564,9 @@ The `**runtime_overrides` parameter accepts additional settings:
 )
 ```
 
+Legacy `execution_mode=` inputs are deprecated compatibility shims. Use
+`algorithm=` and `offline=` for new code.
+
 Run controls such as `max_trials` and `timeout` are passed to `.optimize()`:
 
 ```python
@@ -642,16 +644,13 @@ def answer_question(question: str) -> str:
         lambda cfg, metrics: metrics.get("cost", 0) <= 0.10 if metrics else True,
     ],
     evaluation={"eval_dataset": "support_tickets.jsonl"},
-    execution={
-        "execution_mode": "edge_analytics",
-        "parallel_config": {"thread_workers": 4},
-    },
+    parallel_config={"thread_workers": 4},
 )
 def process_ticket(ticket: str) -> str:
     return support_chain.run(ticket)
 ```
 
-### Edge Analytics with Privacy
+### No-Egress Local Storage
 
 ```python
 @traigent.optimize(
@@ -661,12 +660,10 @@ def process_ticket(ticket: str) -> str:
         "temperature": [0.1, 0.3, 0.5],
     },
     evaluation={"eval_dataset": "medical_qa.jsonl"},
-    execution={
-        "execution_mode": "edge_analytics",
-        "local_storage_path": "./medical_optimizations",
-        "privacy_enabled": True,
-        "minimal_logging": True,
-    },
+    algorithm="grid",
+    offline=True,
+    local_storage_path="./medical_optimizations",
+    minimal_logging=True,
 )
 def medical_assistant(query: str) -> str:
     return process_medical_query(query)
@@ -700,7 +697,7 @@ def my_agent(query: str) -> str:
 - [Complete Function Specification](./complete-function-specification.md) - Full API reference
 - [Evaluation Guide](../user-guide/evaluation_guide.md) - Understanding accuracy metrics, evaluation methods, and troubleshooting
 - [Injection Modes Guide](../user-guide/injection_modes.md) - Configuration injection patterns
-- [Execution Modes Guide](../guides/execution-modes.md) - Execution mode details
+- [Choosing the Right Optimization Model](../user-guide/choosing_optimization_model.md) - Default smart optimization, local search, no-egress runs, and migration guidance
 - [Thread Pool Examples](./thread-pool-examples.md) - Context propagation with threads
-- [Telemetry Documentation](./telemetry.md) - Data collection and privacy
+- [Telemetry Documentation](./telemetry.md) - Data collection and no-egress controls
 - Custom evaluator walkthrough in the repository examples - LLM-as-Judge implementation

{traigent-0.14.3 → traigent-0.16.0.dev0}/docs/api-reference/telemetry.md

@@ -24,8 +24,7 @@ During optimization runs, Traigent collects:
 - Algorithm used (grid, random, bayesian, optuna)
 - Number of trials executed
 - Total optimization duration
-- Execution mode (`edge_analytics`, `hybrid`, `hybrid_api`; `privacy` is a
-  legacy alias for `hybrid`, and `cloud` is reserved/fails closed)
+- Result source (`cloud_brain`, `local_fallback`, `explicit_local`, or `offline`)
 - 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`.
 
@@ -46,25 +45,26 @@ Traigent does **not** collect:
 - **API keys or credentials**
 - **Source code or function implementations**
 
-### Privacy Mode
+### Data Boundary and No-Egress Runs
 
-When `privacy_enabled=True` is set in ExecutionOptions:
+The default portal-backed path sends configuration identifiers and numeric metrics. It
+does not send dataset example inputs, expected outputs, prompts, responses, or
+example metadata. Use `offline=True` when your policy requires no Traigent
+backend egress at all:
 
 ```python
 @traigent.optimize(
-    execution={
-        "privacy_enabled": True,
-    },
+    algorithm="grid",
+    offline=True,
     ...
 )
 ```
 
-Traigent will:
-- Redact prompts/responses from stored evaluation artifacts when possible
-- Minimize logged content while keeping metrics and configuration metadata
-- Keep results local in open-source builds
+No-egress runs keep Traigent optimization metadata local while still allowing your
+own function to call LLM providers or other services.
 
-Privacy mode does not disable telemetry; use `TRAIGENT_DISABLE_TELEMETRY=true` for a full opt-out.
+Use `TRAIGENT_DISABLE_TELEMETRY=true` for telemetry opt-out and `offline=True`
+for zero Traigent backend egress.
 
 ### OpenTelemetry Tracing
 
@@ -121,14 +121,14 @@ Telemetry data is used for:
 
 ## Data Retention
 
-**Edge Analytics Mode** (default):
+**No-egress runs**:
 - All data is stored **locally** on your machine
 - Data is kept in `~/.traigent/` or your specified `local_storage_path`
 - You control retention - delete files as needed
-- No data is sent to external servers
+- No data is sent to the Traigent backend
 
-**Cloud/Hybrid Mode** (managed service only):
-- Metadata can be sent to Traigent backend for optimization coordination
+**Portal-backed runs**:
+- Configuration IDs/schema and numeric metrics can be sent to Traigent backend for optimization coordination
 - Retention policies depend on your managed-service agreement
 - You can request data deletion at any time
 
@@ -234,7 +234,7 @@ Each event includes:
 
 ## Local Storage Structure
 
-When using edge_analytics mode, data is stored locally:
+When using `offline=True`, data is stored locally:
 
 ```
 ~/.traigent/
@@ -251,9 +251,7 @@ You can customize the storage location:
 
 ```python
 @traigent.optimize(
-    execution={
-        "local_storage_path": "./my_optimizations",
-    },
+    local_storage_path="./my_optimizations",
     ...
 )
 ```
@@ -270,8 +268,7 @@ example record includes the input **query**, the model **response**, and the
 > cards, API keys / bearer tokens, etc.). Free-text content in prompts and
 > responses (names, addresses, proprietary data) is stored **verbatim**.
 
-To keep ids and metrics while omitting that content — without enabling full
-privacy mode — disable content logging:
+To keep ids and metrics while omitting that content, disable content logging:
 
 ```bash
 export TRAIGENT_LOG_EXAMPLE_CONTENT=false   # also accepts 0 / no / off
@@ -283,7 +280,7 @@ and `error`, but `query` / `response` / `expected` are `null`.
 
 Traigent writes a `.gitignore` (`*`) into the log root so this content is not
 accidentally committed, but you should still keep `.traigent/` out of version
-control and CI artifact collection in privacy-sensitive projects.
+control and CI artifact collection in sensitive projects.
 
 ## Telemetry Listeners
 
@@ -304,7 +301,7 @@ emitter.subscribe(my_listener)
 # (unless TRAIGENT_DISABLE_TELEMETRY is set)
 ```
 
-## Security and Privacy
+## Security and Sensitive Data
 
 ### Data Sanitization
 
@@ -353,10 +350,11 @@ Traigent SDK is designed to be GDPR-compliant:
 
 For HIPAA compliance or handling sensitive data:
 
-1. **Enable Privacy Mode**:
+1. **Use `offline=True` for Zero Traigent Egress**:
    ```python
    @traigent.optimize(
-       execution={"privacy_enabled": True},
+       algorithm="grid",
+       offline=True,
        ...
    )
    ```
@@ -369,10 +367,9 @@ For HIPAA compliance or handling sensitive data:
 3. **Use Local Storage Only**:
    ```python
    @traigent.optimize(
-       execution={
-           "execution_mode": "edge_analytics",
-           "local_storage_path": "/secure/location",
-       },
+       algorithm="grid",
+       offline=True,
+       local_storage_path="/secure/location",
        ...
    )
    ```
@@ -383,7 +380,9 @@ For HIPAA compliance or handling sensitive data:
 
 ### Q: Is telemetry enabled by default?
 
-**A**: Yes, but only for local optimization metadata. In the default `edge_analytics` mode, all data stays on your machine.
+**A**: Yes, for local optimization metadata. The default portal-backed path sends
+configuration IDs/schema and numeric metrics only; use `offline=True` for zero
+Traigent backend egress.
 
 ### Q: How do I verify telemetry is disabled?
 
@@ -404,11 +403,13 @@ print(os.getenv("TRAIGENT_DISABLE_TELEMETRY"))
 
 ### Q: Can I enable telemetry for some optimizations but not others?
 
-**A**: The `TRAIGENT_DISABLE_TELEMETRY` environment variable is process-wide. `privacy_enabled` reduces stored content but does not disable telemetry.
+**A**: The `TRAIGENT_DISABLE_TELEMETRY` environment variable is process-wide.
+Use `offline=True` when you need to disable Traigent backend egress for a run.
 
 ### Q: Where can I see what telemetry data was collected?
 
-**A**: In edge_analytics mode, check the JSON files in `~/.traigent/sessions/`. They contain the same trial metadata and metrics emitted to telemetry listeners.
+**A**: With `offline=True`, check the JSON files in `~/.traigent/sessions/`. They
+contain the same trial metadata and metrics emitted to telemetry listeners.
 
 ### Q: Can I contribute telemetry data to improve Traigent?
 
@@ -417,6 +418,6 @@ print(os.getenv("TRAIGENT_DISABLE_TELEMETRY"))
 ## Related Documentation
 
 - [Decorator Reference](./decorator-reference.md) - Configuration options
-- [Execution Modes Guide](../guides/execution-modes.md) - Edge Analytics vs Cloud
-- [Privacy & Security](../contributing/SECURITY.md) - Security practices
+- [Choosing the Right Optimization Model](../user-guide/choosing_optimization_model.md) - defaults, local search, no-egress runs, and migration guidance
+- [Security](../contributing/SECURITY.md) - Security practices
 - [API Reference](./complete-function-specification.md) - Full API documentation