traigent 0.15.0__tar.gz → 0.16.0.dev0__tar.gz

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

@@ -16,19 +16,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `auto`, explicit local `grid`/`random`, zero-egress offline mode, result
   provenance, and legacy selector deprecations.
 
-## [0.14.3] - 2026-06-20
-
-### 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)
-
-### Fixed
-- Corrected the async context-manager mock in the hybrid degradation test and updated
-  `test_safety.py` integration tests for the `NotImplementedError` guard.
-
 ## [0.14.1] - 2026-06-19
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.15.0
+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,20 +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.
 
-For local-only runs with no Traigent backend egress, pass `offline=True`. For
-portal-tracked optimization, set `TRAIGENT_API_KEY` and omit the legacy
-execution-mode field.
+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>
@@ -411,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
 
@@ -475,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.15.0 → 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,20 +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.
 
-For local-only runs with no Traigent backend egress, pass `offline=True`. For
-portal-tracked optimization, set `TRAIGENT_API_KEY` and omit the legacy
-execution-mode field.
+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>
@@ -263,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
 
@@ -327,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.15.0 → 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.15.0 → traigent-0.16.0.dev0}/docs/api-reference/complete-function-specification.md

@@ -123,16 +123,16 @@ def my_agent(question: str) -> str:
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `algorithm` | `str` | `"auto"` | Optimizer selector. `"auto"` is cloud-first with local fallback on connectivity failures; `"grid"` and `"random"` run locally; smart algorithms require cloud. |
-| `offline` | `bool` | `False` | Force local-only operation with zero Traigent backend egress. |
+| `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. |
 | `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. |
-| `evaluator` | `ExternalServiceEvaluator \| HybridAPIOptions \| dict \| None` | `None` | External service evaluator bundle. Use `ExternalServiceEvaluator(hybrid_api=HybridAPIOptions(...))` for Hybrid API services. The optimizer still runs locally; the evaluator dispatches each trial to the external HTTP or MCP service. |
+| `evaluator` | `ExternalServiceEvaluator \| dict \| None` | `None` | External service evaluator bundle for API-contract integrations. This does not change optimizer routing. |
 
 **Legacy Compatibility**
 
@@ -143,13 +143,13 @@ def my_agent(question: str) -> str:
 
 **Usage Notes**
 
-- The default path is `algorithm="auto"`: cloud-first optimizer decisions with local trial execution and local fallback on connectivity failures.
+- 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.
-- Use `offline=True` when policy requires zero Traigent backend egress. `TRAIGENT_OFFLINE=1` and the legacy `TRAIGENT_OFFLINE_MODE=1` provide the same routing at the environment level.
-- `privacy_enabled` and `cloud_fallback_policy` are deprecated no-ops. `execution_mode` is deprecated compatibility input only; migrate to `algorithm`, `offline`, and `evaluator=ExternalServiceEvaluator(hybrid_api=HybridAPIOptions(...))`.
+- 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.
@@ -180,8 +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
-    algorithm="grid",
-    offline=True,
 )
 def my_agent(query: str) -> str:
     return process_query(query)
@@ -220,7 +218,7 @@ async def optimize(
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `algorithm` | `str \| None` | Decorator default | Optimizer to use. `"auto"` is cloud-first with local fallback on connectivity failures; `"grid"` and `"random"` stay local; 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. |
+| `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. |
@@ -256,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")

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

@@ -505,8 +505,8 @@ from traigent.config.parallel import ParallelConfig
 
 **ExecutionOptions Fields**:
 
-- `algorithm`: optimizer selector. `"auto"` is cloud-first and falls back to local grid/random on connectivity failures; `"grid"` and `"random"` are explicit local optimizers; smart algorithms require cloud and hard-error when unavailable or offline.
-- `offline`: force local-only operation with zero Traigent backend egress. `TRAIGENT_OFFLINE=1` and legacy `TRAIGENT_OFFLINE_MODE=1` provide the same behavior via environment variables.
+- `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
@@ -514,7 +514,7 @@ from traigent.config.parallel import ParallelConfig
 - `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.
-- `evaluator`: external evaluator bundle, including `ExternalServiceEvaluator(hybrid_api=HybridAPIOptions(...))`. This does not change optimizer routing; it only changes how each trial is evaluated.
+- `evaluator`: external evaluator bundle for API-contract integrations. This does not change optimizer routing; it only changes how each trial is evaluated.
 
 #### `mock`
 
@@ -564,11 +564,8 @@ The `**runtime_overrides` parameter accepts additional settings:
 )
 ```
 
-Deprecated execution inputs:
-
-- `execution_mode=` is deprecated compatibility input only; migrate to `algorithm=` / `offline=`.
-- `privacy_enabled` is a deprecated no-op. Cloud-brain optimization already avoids dataset-content egress; use `offline=True` for zero Traigent backend egress.
-- `cloud_fallback_policy` is a deprecated no-op. Use `TRAIGENT_REQUIRE_CLOUD=1` to disable `algorithm="auto"` fallback.
+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()`:
 
@@ -647,15 +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"},
-    algorithm="grid",
-    offline=True,
     parallel_config={"thread_workers": 4},
 )
 def process_ticket(ticket: str) -> str:
     return support_chain.run(ticket)
 ```
 
-### Offline Local Storage
+### No-Egress Local Storage
 
 ```python
 @traigent.optimize(
@@ -702,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
-- [Choosing the Right Optimization Model](../user-guide/choosing_optimization_model.md) - Cloud-first auto, explicit local, offline, and migration guidance
+- [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.15.0 → traigent-0.16.0.dev0}/docs/api-reference/telemetry.md

@@ -45,9 +45,9 @@ Traigent does **not** collect:
 - **API keys or credentials**
 - **Source code or function implementations**
 
-### Privacy and Offline Mode
+### Data Boundary and No-Egress Runs
 
-The cloud-brain path sends configuration identifiers and numeric metrics. It
+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:
@@ -60,17 +60,11 @@ backend egress at all:
 )
 ```
 
-Offline runs keep Traigent optimization metadata local while still allowing your
+No-egress runs keep Traigent optimization metadata local while still allowing your
 own function to call LLM providers or other services.
 
-`TRAIGENT_OFFLINE=1` and the legacy `TRAIGENT_OFFLINE_MODE=1` enable the same
-zero-egress routing without changing code. Set `TRAIGENT_REQUIRE_CLOUD=1` when
-`algorithm="auto"` must hard-error instead of falling back locally.
-
-`privacy_enabled` is deprecated and does not disable telemetry or network
-access. The default cloud-brain path is already content-free. Use
-`TRAIGENT_DISABLE_TELEMETRY=true` for telemetry opt-out and `offline=True` for
-zero Traigent backend egress.
+Use `TRAIGENT_DISABLE_TELEMETRY=true` for telemetry opt-out and `offline=True`
+for zero Traigent backend egress.
 
 ### OpenTelemetry Tracing
 
@@ -127,13 +121,13 @@ Telemetry data is used for:
 
 ## Data Retention
 
-**Offline mode**:
+**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 the Traigent backend
 
-**Cloud-brain mode**:
+**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
@@ -240,7 +234,7 @@ Each event includes:
 
 ## Local Storage Structure
 
-When using offline mode, data is stored locally:
+When using `offline=True`, data is stored locally:
 
 ```
 ~/.traigent/
@@ -274,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
@@ -287,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
 
@@ -308,7 +301,7 @@ emitter.subscribe(my_listener)
 # (unless TRAIGENT_DISABLE_TELEMETRY is set)
 ```
 
-## Security and Privacy
+## Security and Sensitive Data
 
 ### Data Sanitization
 
@@ -357,7 +350,7 @@ Traigent SDK is designed to be GDPR-compliant:
 
 For HIPAA compliance or handling sensitive data:
 
-1. **Use Offline Mode for Zero Traigent Egress**:
+1. **Use `offline=True` for Zero Traigent Egress**:
    ```python
    @traigent.optimize(
        algorithm="grid",
@@ -387,7 +380,7 @@ For HIPAA compliance or handling sensitive data:
 
 ### Q: Is telemetry enabled by default?
 
-**A**: Yes, for local optimization metadata. The default cloud-brain path sends
+**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.
 
@@ -415,7 +408,7 @@ 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 offline mode, check the JSON files in `~/.traigent/sessions/`. They
+**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?
@@ -425,6 +418,6 @@ contain the same trial metadata and metrics emitted to telemetry listeners.
 ## Related Documentation
 
 - [Decorator Reference](./decorator-reference.md) - Configuration options
-- [Choosing the Right Optimization Model](../user-guide/choosing_optimization_model.md) - cloud-first auto, explicit local, offline, env vars, and migration guidance
-- [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

{traigent-0.15.0 → traigent-0.16.0.dev0}/docs/architecture/ARCHITECTURE.md

@@ -9,9 +9,9 @@ Traigent is a zero-code LLM optimization SDK that automatically finds the best c
 - **Parameter Optimization**: Automatically tune model selection, temperature, prompts, and other parameters
 - **Multi-Objective Optimization**: Balance accuracy, cost, latency, and other metrics simultaneously
 - **Framework Integration**: Native support for LangChain, DSPy, OpenAI, Anthropic, and more
-- **Flexible Execution**: Use cloud-first `algorithm="auto"`, explicit local
-  `algorithm="grid"` / `"random"`, `offline=True` for zero Traigent backend
-  egress, or `ExternalServiceEvaluator` for external Hybrid API services.
+- **Flexible Routing**: Most users omit routing settings. Use
+  `algorithm="grid"` / `"random"` for explicit local search, or `offline=True`
+  for zero Traigent backend egress.
 - **TVL Specifications**: Define optimization specs in YAML for version control and collaboration
 
 ---
@@ -192,38 +192,35 @@ flowchart LR
 
 ---
 
-## Execution Modes
+## Optimization Routing
 
 ```mermaid
 flowchart TB
-    subgraph EdgeAnalytics["Offline Local Mode"]
+    subgraph DefaultPath["Default"]
         direction TB
-        ea_desc["Local optimization<br/>Data stays on-premise<br/>Optional telemetry"]
-        ea_local["Local Storage"]
-        ea_opt["Local Optimizer"]
+        default_desc["Smart optimizer<br/>No routing settings<br/>Portal sync when authenticated"]
+        default_portal["Traigent Portal"]
     end
 
-    subgraph CloudMode["Cloud Mode"]
+    subgraph LocalSearch["Local Search"]
         direction TB
-        cloud_desc["Reserved future remote execution<br/>Not available today<br/>Fails closed"]
-        cloud_backend["Future Traigent Cloud"]
-        cloud_storage["Future Cloud Storage"]
+        local_desc["Grid or random<br/>Trials run in your process<br/>Portal sync when authenticated"]
+        local_opt["Local Optimizer"]
     end
 
-    subgraph HybridMode["Hybrid Mode"]
+    subgraph NoEgress["No-Egress Run"]
         direction TB
-        hybrid_desc["Local trial execution<br/>Backend session/result tracking<br/>Portal-visible results"]
-        hybrid_local["Local Execution"]
-        hybrid_sync["Backend Sync"]
+        noegress_desc["offline=True<br/>Local optimizer<br/>No portal sync"]
+        local_store["Local Results"]
     end
 
-    User["Your Application"] --> EdgeAnalytics
-    User --> CloudMode
-    User --> HybridMode
+    User["Your Application"] --> DefaultPath
+    User --> LocalSearch
+    User --> NoEgress
 
-    style EdgeAnalytics fill:#e8f5e9,stroke:#2e7d32
-    style CloudMode fill:#e3f2fd,stroke:#1565c0
-    style HybridMode fill:#fff3e0,stroke:#ef6c00
+    style DefaultPath fill:#e3f2fd,stroke:#1565c0
+    style LocalSearch fill:#e8f5e9,stroke:#2e7d32
+    style NoEgress fill:#fff3e0,stroke:#ef6c00
 ```
 
 ---

{traigent-0.15.0 → traigent-0.16.0.dev0}/docs/examples/API_PATTERNS.md

@@ -155,7 +155,7 @@ df = results.to_dataframe()
 `successful_trials` is a list of successful `TrialResult` objects. Use
 `len(results.successful_trials)` when you need a count.
 
-`results.source` tells you which execution path ran:
+`results.source` tells you which routing path ran:
 `cloud_brain`, `local_fallback`, `explicit_local`, or `offline`.
 
 ## Progressive Runs
@@ -177,35 +177,10 @@ refined = await answer.optimize(
 
 ## External Service Evaluator
 
-Use `ExternalServiceEvaluator` when trials are delegated to an external service
-that implements the Traigent Hybrid API contract. This replaces the removed
-`execution_mode="hybrid_api"` plus flat `hybrid_api_*` arguments; the optimizer
-still runs locally and each trial evaluation is dispatched through the external
-service.
-
-```python
-from traigent.api.decorators import ExternalServiceEvaluator, HybridAPIOptions
-
-@traigent.optimize(
-    evaluator=ExternalServiceEvaluator(
-        hybrid_api=HybridAPIOptions(
-            endpoint="http://localhost:8080",
-            transport_type="http",
-        )
-    ),
-    configuration_space={"temperature": [0.0, 0.3]},
-    eval_dataset="data/eval.jsonl",
-    scoring_function=my_score,
-)
-def external_agent(_query: str) -> str:
-    return ""
-
-
-results = await external_agent.optimize(max_trials=10)
-```
-
-Because the optimizer is local in this setup, successful runs report
-`results.source == "explicit_local"`.
+External-service API contract integrations are documented separately. They do
+not change optimization routing: use the default smart optimizer for most runs,
+`algorithm="grid"` / `"random"` for local search, and `offline=True` only for
+zero Traigent backend egress.
 
 ## Multi-Field Evaluation Inputs
 

{traigent-0.15.0 → traigent-0.16.0.dev0}/docs/examples/LEARNING_ROADMAP.md

@@ -25,7 +25,7 @@ Outcome: you can run examples, read metrics, and tweak configuration spaces.
 Outcome: you can constrain costs, add guardrails, and tune prompts.
 
 ## Week 3: Advanced exploration (researcher)
-1. Execution modes and rollouts: `examples/advanced/execution-modes/` (local patterns + roadmap stubs)
+1. Optimization routing: `examples/advanced/optimization-routing/` (local search and no-egress examples)
 2. Context engineering & RAG eval: `examples/advanced/ai-engineering-tasks/p0_context_engineering/` and `examples/advanced/ragas/`
 3. Metrics and analysis: `examples/advanced/results-analysis/` and `examples/advanced/metric-registry/`
 4. CI/CD integration: `examples/integrations/ci-cd/`

{traigent-0.15.0 → traigent-0.16.0.dev0}/docs/examples/QUICK_REFERENCE.md

@@ -30,12 +30,11 @@ def summarize(text: str) -> str:
     return f"Summary | model={cfg['model']}"  # call your LLM here
 ```
 
-## Execution model
-- `algorithm="auto"` (default) - cloud-first optimizer decisions, local trials, local fallback on connectivity failures.
-- `algorithm="grid"` / `"random"` - explicit local optimizers with no cloud optimizer round trip.
+## Optimization routing
+- Omit routing settings for the default smart optimizer and portal sync.
+- `algorithm="grid"` / `"random"` runs local search and still syncs results when authenticated.
 - Smart algorithms such as `bayesian`, `tpe`, `optuna_tpe`, `nsga2`, and `cmaes` are cloud-only and hard-error if unavailable.
-- `offline=True`, `TRAIGENT_OFFLINE=1`, or legacy `TRAIGENT_OFFLINE_MODE=1` - zero Traigent backend egress.
-- `TRAIGENT_REQUIRE_CLOUD=1` - disables the automatic local fallback for `algorithm="auto"`.
+- `offline=True` is the zero Traigent backend egress path and does not sync to the portal.
 - Result provenance: `result.source` is `cloud_brain`, `local_fallback`, `explicit_local`, or `offline`.
 - Mock: call `traigent.testing.enable_mock_mode_for_quickstart()` in local tutorial code.