traigent 0.18.1.dev10__tar.gz → 0.19.0__tar.gz

{traigent-0.18.1.dev10 → traigent-0.19.0}/CHANGELOG.md

@@ -6,6 +6,47 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-07-03
+
+### Added
+- `SemanticSaturationStopCondition` rebuilt from the shipped schema plan
+  (FR-SDK-SEMANTIC-SATURATION-V1).
+- Surrogate (pre-screen) evaluator: a cheap second scorer over captured
+  outputs, with an e2e co-evolution demo in mock mode.
+- Smart-pruning producer wired end-to-end: per-example pruning is reachable
+  from the SDK, with real per-example accuracy threaded into pruning progress
+  and live-e2e-confirmed correctness/durability fixes.
+- `list_sessions()` with typed `SessionSummary`; `delete_session` defaults to
+  non-destructive and `cascade=True` now calls the backend DELETE.
+- Experiment group analytics client.
+
+### Changed
+- Deprecation warnings for the legacy session contract and the
+  `edge_analytics` wire value (now `local`).
+- Self-describing default experiment names.
+- Real streaming token-cost accounting with a plausibility clamp on
+  self-reported costs; `budget.max_cost_usd` is sent on typed session create
+  so the backend cost cap arms.
+
+### Fixed
+- Abort on systematic provider failures instead of reporting fake
+  convergence; fail fast when the optimizer is unavailable instead of
+  hanging.
+- Offline-sync finalization is status-aware and skips terminal non-COMPLETED
+  experiments; sync CLI surfaces terminal-skip warnings.
+- Trial-results table no longer double-scales 0-100 metrics; cost capture
+  works when the config has no `model` key.
+- `FunctionDescriptor` identity, metric batching, and audit-alert
+  ratchet-surfaced bugs.
+
+### Security
+- `RestrictedUnpickler` pinned to a precise (module, name) allowlist,
+  closing a pickle deserialization RCE vector.
+- CLI login rate limiting enforced; file-read containment for CWE-23.
+- Sensitive tuned config values are redacted on the privacy-mode submission
+  path; safety-sensitive-key blocking is non-bypassable on best-config
+  drift; CI-approval token expiry compared in UTC.
+
 ## [0.18.0] - 2026-06-27
 
 ### Added
@@ -26,6 +67,29 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   var (`OPTUNA_ROLLOUT`, renamed during the managed-routing migration).
 - Smart algorithms (`bayesian` and the Optuna family) now route to the Traigent
   cloud; the local SDK supports `grid` and `random` only.
+- Removed 7 production-dead internal modules (`config_builder`,
+  `llm_processor`, `refactoring_utils`, `service_registry`, `event_manager`,
+  `langchain/discovery`, empty `telemetry` package) and their tests.
+
+### Fixed
+- Per-config `cost` metric is now wired to the authoritative `total_cost`, so
+  the `minimize cost` objective is no longer inert and the portal no longer
+  shows `$0` per config on a real paid run; a model unpriced at runtime is
+  surfaced on the result (and fails closed under
+  `TRAIGENT_STRICT_COST_ACCOUNTING`).
+- `traigent sync` / `traigent local sync` no longer fail every completed
+  session with `409 EXPERIMENT_HAS_NO_RUNS`; sync now creates the experiment
+  `PENDING`, uploads runs, finalizes to `COMPLETED`, resumes idempotently, and
+  returns a non-zero exit on failure.
+- Runtime `optimize(algorithm="grid"|"random")` with a portal key now stays
+  local and exhaustive instead of routing to the cloud sampler.
+- `traigent quickstart` runs on a bare install (uses base `litellm`, not the
+  `integrations` LangChain extra) and fails closed when no trial succeeds.
+- `ObjectiveDefinition` fails closed on unimplemented normalization strategies
+  (`z_score`/`robust`) instead of silently behaving like `min_max`.
+
+### Dependencies
+- Bumped `langsmith` 0.8.3 → 0.8.18 and `pydantic-settings` 2.14.1 → 2.14.2.
 
 ## [0.14.1] - 2026-06-19
 
@@ -123,6 +187,13 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **`langgraph-checkpoint` 3.x → 4.x:** the 4.0 release drops default deserialization of payloads serialized with the legacy `"json"` serde mode. Users running `langgraph` with a persistent checkpoint saver (SQLite, Postgres, Redis, etc.) whose stored state contains JSON-format blobs will see deserialization failures unless they configure `serde` with an explicit `allowed_json_modules` list. Traigent does not bind `langgraph-checkpoint` directly — it arrives transitively through the `langgraph` dependency — so this only affects projects that also use `langgraph` checkpointers in their own code. See [CVE-2026-27794](https://github.com/langchain-ai/langgraph/security/advisories) for the underlying RCE that motivated removing the default.
 
 ### Changed
+- **CI approval gate:** running `optimize()` in local/offline mode within a CI
+  environment now requires explicit approval via `TRAIGENT_RUN_APPROVED=1`.
+  `TRAIGENT_MOCK_LLM` no longer bypasses this gate — mock and offline runs in
+  CI are intentionally included (a purpose-built approval signal replaces an
+  env-var bypass of a security control). Cloud-mode runs are unaffected.
+  Migration: set `TRAIGENT_RUN_APPROVED=1` in CI for legitimately-approved
+  runs.
 - **Strict evidence modes now fail closed in promotion** (#1103,
   FR-SDK-FAIL-CLOSED-PROMOTION-V1). When a TVL promotion policy declares a strict
   evidence mode — `require_calibration.enabled: true` or `chance_constraints` —

{traigent-0.18.1.dev10/traigent.egg-info → traigent-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.18.1.dev10
+Version: 0.19.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
@@ -92,7 +92,7 @@ Requires-Dist: mcp>=1.27.0; extra == "hybrid"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.27.0; extra == "mcp"
 Provides-Extra: internal-schema
-Requires-Dist: traigent-schema==4.1.0; extra == "internal-schema"
+Requires-Dist: traigent-schema==4.7.1; extra == "internal-schema"
 Provides-Extra: test
 Requires-Dist: pytest>=9.0.3; extra == "test"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"

{traigent-0.18.1.dev10 → traigent-0.19.0}/docs/api-reference/complete-function-specification.md

@@ -247,6 +247,7 @@ async def optimize(
 | `metric_limit` / `metric_name` / `metric_include_pruned` | Configure soft cumulative-metric early stopping. |
 | `budget_limit` / `budget_metric` / `budget_include_pruned` | Deprecated aliases for metric-limit controls. Use `cost_limit` for hard USD spend control. |
 | `plateau_window` / `plateau_epsilon` | Configure plateau detection stop conditions. |
+| `semantic_saturation` | Configure opt-in semantic saturation. Uses per-example metric-vector churn plus continuous objective improvement and emits sanitized diagnostics in `OptimizationResult.metadata["semantic_saturation"]`. |
 | `parameter_order` | Grid search only: mapping of parameter names to numeric priorities. Lower values vary slowest; higher values vary fastest. |
 | `order` | Alias for `parameter_order` (grid search only). |
 

{traigent-0.18.1.dev10 → traigent-0.19.0}/docs/api-reference/telemetry.md

@@ -16,7 +16,11 @@ During optimization runs, Traigent collects:
 - Trial suggested/intermediate/completed timestamps
 - Trial status (completed, failed, pruned)
 - Trial duration
-- Trial configuration (parameter values being tested, with internal keys stripped)
+- Trial configuration. On the default portal-backed path, this includes tuned
+  config-space key/value pairs being tested, with internal keys stripped. If you
+  tune prompt variants or other free-text strings as configuration values, those
+  tuned values are sent on the default path so the portal can display winning
+  configs.
 - Trial metrics (accuracy, cost, latency, etc.)
 
 **Optimization Run Metadata**:
@@ -26,7 +30,7 @@ During optimization runs, Traigent collects:
 - Total optimization duration
 - 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`.
+- 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 the `tvar_observation_v1` metadata sub-field, or use `TRAIGENT_TVAR_OBSERVATION=hashed` (default) to hash free-form string values in that sub-field. Only `off` and `hashed` are supported; unsupported values fall back to `hashed`. This setting does not control the trial `config` field.
 
 **Performance Metrics**:
 - LLM API response times
@@ -36,7 +40,8 @@ During optimization runs, Traigent collects:
 
 ### What is NOT Collected
 
-Traigent does **not** collect:
+Outside tuned configuration values explicitly sent on the default portal-backed
+path, Traigent does **not** collect:
 
 - **User prompts or inputs**
 - **LLM responses or outputs**
@@ -47,10 +52,25 @@ Traigent does **not** collect:
 
 ### Data Boundary and No-Egress Runs
 
-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:
+The default portal-backed path sends tuned config-space values and numeric
+metrics. This is deliberate: the portal uses those values to display and compare
+winning configs. If a prompt variant, persona instruction, model name, or other
+string is part of the tuned configuration space, the default path sends that
+string value. It does not send dataset example inputs, expected outputs, model
+responses, or example metadata unless you put that content into the tuned
+configuration itself.
+
+Use privacy-mode redaction when you need backend coordination without sending
+tuned string values. Privacy submissions preserve which keys were tuned, but
+redact sensitive-key values and all string/free-text config values. Numeric,
+boolean, and `None` config values still pass through. This redaction is gated by
+the run's effective `TraigentConfig.privacy_enabled` setting, including
+configuration loaded from `TRAIGENT_PRIVACY_MODE=true` for compatibility. Do not
+use `@traigent.optimize(..., privacy_enabled=True)` for new code; that decorator
+keyword is deprecated and emits a warning. Use `offline=True` instead when the
+requirement is no Traigent backend egress.
+
+Use `offline=True` when your policy requires no Traigent backend egress at all:
 
 ```python
 @traigent.optimize(
@@ -63,8 +83,10 @@ backend egress at all:
 No-egress runs keep Traigent optimization metadata local while still allowing your
 own function to call LLM providers or other services.
 
-Use `TRAIGENT_DISABLE_TELEMETRY=true` for telemetry opt-out and `offline=True`
-for zero Traigent backend egress.
+Use `TRAIGENT_DISABLE_TELEMETRY=true` for SDK telemetry opt-out, effective
+`TraigentConfig.privacy_enabled` privacy mode to redact tuned string config
+values on privacy-mode submissions, and `offline=True` for zero Traigent backend
+egress.
 
 ### OpenTelemetry Tracing
 
@@ -128,7 +150,7 @@ Telemetry data is used for:
 - No data is sent to the Traigent backend
 
 **Portal-backed runs**:
-- Configuration IDs/schema and numeric metrics can be sent to Traigent backend for optimization coordination
+- Tuned config-space values, 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
 
@@ -249,7 +271,10 @@ control and CI artifact collection in sensitive projects.
 ### Data Sanitization
 
 Configuration data is sanitized before telemetry. Private/internal keys
-(starting with `_`) are automatically removed.
+(starting with `_`) are automatically removed. On default portal-backed
+submissions, tuned config values are otherwise sent unchanged so the portal can
+display winning configs. On privacy-mode submissions, sensitive-key values and
+all string/free-text config values are redacted while preserving the tuned keys.
 
 ### Error Handling
 
@@ -305,9 +330,10 @@ For HIPAA compliance or handling sensitive data:
 
 ### Q: Is telemetry enabled by default?
 
-**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.
+**A**: Yes, for local optimization metadata. The default portal-backed path can
+send tuned config-space values, configuration IDs/schema, and numeric metrics;
+use privacy-mode redaction when backend coordination is needed without tuned
+string values, or `offline=True` for zero Traigent backend egress.
 
 ### Q: How do I verify telemetry is disabled?
 

{traigent-0.18.1.dev10 → traigent-0.19.0}/docs/architecture/stop_conditions.md

@@ -29,6 +29,7 @@ Built-in implementations:
 | `MetricLimitStopCondition` | Soft stop when the cumulative value of a named completed-trial metric reaches a limit. | `metric_limit`, `metric_name`, `metric_include_pruned`. |
 | `CostLimitStopCondition` | Hard money-spend guard backed by `CostEnforcer` permits before execution starts. Parallel-safe. | `cost_limit`, `cost_approved`. |
 | `HypervolumeConvergenceStopCondition` | Stops when hypervolume improvement remains below a threshold across a sliding window. | `convergence_metric="hypervolume_improvement"`, `convergence_window`, `convergence_threshold`. |
+| `SemanticSaturationStopCondition` | Stops when per-example quality vectors are stable and monitored continuous objectives are no longer improving. | `semantic_saturation={...}`. |
 
 `budget_limit` remains as a deprecated alias for `metric_limit` for compatibility.
 New code should not use it.
@@ -81,6 +82,35 @@ The orchestrator instantiates the conditions during construction via
 between optimizations. `_should_stop()` evaluates all configured conditions before
 fallback logic (timeout or optimizer-provided stop signals).
 
+## Semantic saturation
+
+`semantic_saturation` is an opt-in stop condition for runs where aggregate
+accuracy alone is not enough to decide convergence. It only reads `example_id`
+and numeric or boolean values from each example's `metrics` map. It never reads
+or emits inputs, expected outputs, actual outputs, model text, or document
+content.
+
+The condition selects the latest completed trials with distinct configuration
+signatures, warms up until `max(window, min_trials)` distinct configs are
+available, then evaluates the latest `window` configs:
+
+* Quality metrics come from `example_score_metrics`/`accuracy_metrics` or from
+  accuracy-like and binary per-example metrics.
+* Quality saturation is measured as churn across common example IDs, gated by
+  `min_overlap`, `score_tolerance`, and `churn_threshold`.
+* Continuous objectives come from `continuous_objectives`/`objectives`, the
+  `ObjectiveSchema`, or cost/latency/token-like aggregate metrics.
+* Continuous objectives use direction-aware best improvement over the window,
+  compared to `relative_improvement_epsilon` and
+  `absolute_improvement_epsilon`.
+
+The run stops only when every quality metric and every continuous objective is
+saturated. When it fires, `OptimizationResult.stop_reason` is
+`"semantic_saturation"`. The latest sanitized decision payload is emitted under
+`OptimizationResult.metadata["semantic_saturation"]` and follows TraigentSchema
+`optimization/semantic_saturation_schema.json`; example ID lists are capped by
+`max_example_ids`.
+
 ## Vendor-error pause semantics
 
 When every trial in a parallel batch fails with a vendor-classifiable error
@@ -175,6 +205,8 @@ All three examples share the same stop-condition machinery with no additional
 plumbing.
 
 Built-in convergence stops report `OptimizationResult.stop_reason = "convergence"`.
+Semantic saturation reports
+`OptimizationResult.stop_reason = "semantic_saturation"`.
 Custom stop-condition instances still report the generic `"condition"` reason
 unless they are explicitly mapped into the public `StopReason` contract.
 
@@ -186,6 +218,11 @@ Unit coverage lives under:
   - Max-trial threshold (including invalid inputs).
   - Plateau detection, weight handling, reset semantics, and parameter validation.
   - Metric-limit enforcement, compatibility fallback, and pruned-trial filtering.
+  - Stop-condition exports include semantic saturation.
+* `tests/unit/core/test_semantic_saturation_stop_condition.py` – verifies:
+  - Stable vectors, boolean scores, aggregate-flat no-stop behavior, repeated
+    config warmup, cost-improving continuation, schema-valid result metadata,
+    and the privacy boundary.
 * `tests/unit/core/test_orchestrator.py` – integration tests for plateau and metric limit
   within the orchestrator, ensuring early termination and reasonable counts in
   sequential runs.

{traigent-0.18.1.dev10 → traigent-0.19.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traigent"
-version = "0.18.1.dev10"
+version = "0.19.0"
 authors = [
     {name = "Traigent Team", email = "opensource@traigent.ai"},
 ]
@@ -137,7 +137,7 @@ mcp = [
 
 # Internal schema validation support for DTO strict-validation paths.
 internal_schema = [
-    "traigent-schema==4.1.0",
+    "traigent-schema==4.7.1",
 ]
 
 # Testing dependencies
@@ -199,7 +199,9 @@ ml = [
     "scipy>=1.7.0",
 ]
 
-# DeepEval integration (LLM evaluation metrics as optimization objectives)
+# DeepEval integration (LLM evaluation metrics as optimization objectives).
+# Explicit opt-in only while Aikido/deepeval#2497 telemetry exfiltration remains
+# unfixed upstream; Traigent applies telemetry and TracerProvider guards at import.
 deepeval = [
     "deepeval>=1.0.0",
 ]

{traigent-0.18.1.dev10 → traigent-0.19.0}/traigent/adapters/execution_adapter.py

@@ -153,12 +153,12 @@ class LocalExecutionAdapter(ExecutionAdapter):
             }
 
         except Exception as e:
-            logger.error(f"Edge Analytics execution failed: {str(e)}")
+            logger.error(f"Local execution failed: {str(e)}")
             raise
 
     async def get_execution_mode(self) -> str:
         """Get execution mode."""
-        return ExecutionMode.EDGE_ANALYTICS.value
+        return ExecutionMode.LOCAL.value
 
     def _evaluate_output(
         self,

{traigent-0.18.1.dev10 → traigent-0.19.0}/traigent/analytics/predictive.py

@@ -760,18 +760,6 @@ class PerformanceForecaster:
         else:
             avg_score = 0.5
 
-        # Check for missing metrics and add warnings
-        warnings = {}
-        if (
-            isinstance(config_or_config_history, dict)
-            and "metrics" in config_or_config_history
-        ):
-            metrics = config_or_config_history["metrics"]
-            expected_metrics = ["accuracy", "cost", "latency"]
-            missing = [m for m in expected_metrics if m not in metrics]
-            if missing:
-                warnings["missing_metrics"] = missing
-
         result = {
             "expected_improvement": 0.05,
             "confidence": 0.7,
@@ -780,9 +768,6 @@ class PerformanceForecaster:
             "predicted_score": avg_score,
         }
 
-        if warnings:
-            result["warnings"] = warnings
-
         return result
 
 

{traigent-0.18.1.dev10 → traigent-0.19.0}/traigent/analytics/render.py

@@ -19,6 +19,7 @@ optional dependency (``pip install 'traigent[analytics]'`` or
 
 from __future__ import annotations
 
+import math
 from pathlib import Path
 from typing import Any, Literal
 
@@ -92,7 +93,7 @@ def _as_float(value: Any) -> float | None:
     else:
         return None
     # Reject NaN/inf so matplotlib never plots a meaningless point.
-    if result != result or result in (float("inf"), float("-inf")):
+    if not math.isfinite(result):
         return None
     return result
 

{traigent-0.18.1.dev10 → traigent-0.19.0}/traigent/api/decorators.py

@@ -84,6 +84,7 @@ from traigent.config.types import (
     ExecutionMode,
     InjectionMode,
     ResolvedExecutionPolicy,
+    _warn_deprecated_once,
     is_traigent_disabled,
     resolve_execution_policy,
     validate_algorithm_name,
@@ -132,6 +133,20 @@ class EvaluationOptions(BaseModel):
     custom_evaluator: Callable[..., Any] | None = None
     scoring_function: Callable[..., Any] | None = None
     metric_functions: dict[str, Callable[..., Any]] | None = None
+    #: Optional cheap "surrogate" (pre-screen) scorer applied to the SAME outputs
+    #: the primary evaluator already produced, per example. It scores captured
+    #: outputs only and NEVER re-executes the decorated function. Same calling
+    #: convention as ``scoring_function`` — ``(output, expected_output=None,
+    #: example=None)`` — returning a float in [0, 1] (or a dict with
+    #: ``surrogate_score``/``score``). Results ride alongside primary metrics as
+    #: ``surrogate_score`` and feed the backend's per-evaluator score tensor.
+    surrogate_evaluator: Callable[..., Any] | None = None
+    #: Optional explicit id for the surrogate descriptor's ``evaluator_id`` (the
+    #: key the backend tensor uses for this scorer). When omitted, the id is
+    #: derived from the callable's ``__name__``/class name (or ``"surrogate"`` for
+    #: anonymous scorers). A runtime ``optimize(surrogate_evaluator_name=...)``
+    #: overrides this decorator value.
+    surrogate_evaluator_name: str | None = None
 
 
 class InjectionOptions(BaseModel):
@@ -463,6 +478,67 @@ def _validate_custom_evaluator_signature(evaluator: Callable[..., Any]) -> None:
         )
 
 
+def _validate_surrogate_evaluator_signature(surrogate: Callable[..., Any]) -> None:
+    """Validate a surrogate (pre-screen) evaluator at decoration time.
+
+    A surrogate SCORES already-captured outputs — it must accept the output as
+    its first argument (like ``scoring_function``), and must NOT look like a
+    func-executor (``func, config, example``) which would imply re-execution.
+
+    Raises:
+        ValidationError: If not callable, or the signature looks like a
+            func-executor / cannot accept the captured output.
+    """
+    if not callable(surrogate):
+        raise ValidationError("surrogate_evaluator must be callable")
+
+    if inspect.isfunction(surrogate) or inspect.ismethod(surrogate):
+        callable_to_check: Any = surrogate
+    else:
+        callable_to_check = getattr(surrogate, "__call__", surrogate)  # noqa: B004
+
+    try:
+        sig = inspect.signature(callable_to_check)
+    except (ValueError, TypeError):
+        logger.debug(
+            "Could not inspect surrogate_evaluator signature, skipping validation"
+        )
+        return
+
+    params = list(sig.parameters.values())
+    if params and params[0].name == "self":
+        params = params[1:]
+
+    param_names = {p.name for p in params}
+    if {"func", "config"} <= param_names:
+        raise ValidationError(
+            "surrogate_evaluator scores already-captured outputs and must not "
+            "re-execute the decorated function.\n\n"
+            "Expected: surrogate_evaluator(output, expected_output=None, example=None) "
+            "-> float in [0, 1]\n"
+            f"Got:      ({', '.join(p.name for p in params)})\n\n"
+            "This looks like a custom_evaluator (func, config, example). A "
+            "surrogate is a cheap scorer of outputs, like scoring_function."
+        )
+
+    accepts_output = any(
+        p.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        )
+        for p in params
+    )
+    if not accepts_output:
+        raise ValidationError(
+            "surrogate_evaluator must accept the captured output as its first "
+            "argument, e.g. surrogate_evaluator(output, expected_output=None, "
+            "example=None)."
+        )
+
+
 def _warn_context_mode_param_shadowing(
     func: Callable[..., Any],
     configuration_space: Any,
@@ -578,6 +654,7 @@ _OPTIMIZE_DEFAULTS: dict[str, Any] = {
     # Early stopping parameters
     "plateau_window": None,  # Stop if no improvement for N trials
     "plateau_epsilon": None,  # Improvement threshold for plateau detection
+    "semantic_saturation": None,  # Opt-in semantic saturation stop condition config
     # Multi-agent configuration
     "agents": None,  # Explicit agent definitions
     "agent_prefixes": None,  # Prefix-based agent inference
@@ -656,6 +733,7 @@ _ALLOWED_RUNTIME_OVERRIDE_KEYS = frozenset(
         "metric_include_pruned",
         "plateau_window",
         "plateau_epsilon",
+        "semantic_saturation",
         "cost_limit",
         "cost_approved",
         "tie_breakers",
@@ -666,34 +744,28 @@ _ALLOWED_RUNTIME_OVERRIDE_KEYS = frozenset(
 
 def _warn_for_legacy_execution_options(keys: set[str]) -> None:
     """Emit coarse deprecation warnings for legacy execution option names."""
-    import warnings
-
-    if keys & {"execution_mode"}:
-        warnings.warn(
-            "execution_mode is deprecated as a public optimizer selector. Use "
-            "algorithm='auto'|'grid'|'random' and offline=True for no egress.",
-            DeprecationWarning,
-            stacklevel=4,
-        )
     if keys & {"privacy_enabled"}:
-        warnings.warn(
+        _warn_deprecated_once(
+            "optimize.privacy_enabled",
             "privacy_enabled is deprecated and has no effect. Use offline=True "
-            "for no egress.",
-            DeprecationWarning,
+            "for no egress. This compatibility option will be removed in a "
+            "future major release.",
             stacklevel=4,
         )
     if keys & {"cloud_fallback_policy"}:
-        warnings.warn(
+        _warn_deprecated_once(
+            "optimize.cloud_fallback_policy",
             "cloud_fallback_policy is deprecated and has no effect. Set "
-            "TRAIGENT_REQUIRE_CLOUD=1 to disable fallback.",
-            DeprecationWarning,
+            "TRAIGENT_REQUIRE_CLOUD=1 to disable fallback. This compatibility "
+            "option will be removed in a future major release.",
             stacklevel=4,
         )
     if keys & set(_LEGACY_HYBRID_API_OPTION_MAP):
-        warnings.warn(
+        _warn_deprecated_once(
+            "optimize.hybrid_api_flat_options",
             "Flat hybrid_api_* optimize options are deprecated. Pass an "
-            "ExternalServiceEvaluator or evaluator options dict instead.",
-            DeprecationWarning,
+            "ExternalServiceEvaluator or evaluator options dict instead. This "
+            "compatibility option will be removed in a future major release.",
             stacklevel=4,
         )
 
@@ -1575,7 +1647,7 @@ def _runtime_execution_mode_for_policy(
     if external_evaluator is not None:
         return ExecutionMode.HYBRID_API
     if policy.intent is ExecutionIntent.LOCAL_ONLY:
-        return ExecutionMode.EDGE_ANALYTICS
+        return ExecutionMode.LOCAL
     return ExecutionMode.HYBRID
 
 
@@ -1627,7 +1699,7 @@ def _resolve_actual_execution_mode(
 ) -> str:
     """Resolve legacy execution mode from provided or global config."""
     if (
-        execution_mode == ExecutionMode.EDGE_ANALYTICS.value
+        execution_mode == ExecutionMode.LOCAL.value
         and "execution_mode" in _GLOBAL_CONFIG
     ):
         result: str = str(_GLOBAL_CONFIG["execution_mode"])
@@ -1644,7 +1716,7 @@ def _log_execution_mode_warnings(
     minimal_logging: bool,
 ) -> None:
     """Log warnings for incompatible runtime settings."""
-    if minimal_logging and execution_mode_enum is not ExecutionMode.EDGE_ANALYTICS:
+    if minimal_logging and execution_mode_enum is not ExecutionMode.LOCAL:
         logger.warning(
             "minimal_logging is only effective for offline local runs. "
             "It will be ignored for the selected managed execution path."
@@ -2280,6 +2352,11 @@ def optimize(  # NOSONAR(S107)
                 Requires metric_name. Use for counters such as total tokens or
                 cumulative latency, not hard money-spend control.
             metric_name: Metric summed by metric_limit.
+            semantic_saturation: Opt-in stop condition config matching
+                TraigentSchema
+                ``optimization/semantic_saturation_schema.json``. When provided,
+                the SDK evaluates per-example metric-vector churn and continuous
+                objective improvement using sanitized diagnostics only.
 
         Additional controls:
             legacy: Adapter for the legacy decorator signature. Accepts either a
@@ -2289,8 +2366,9 @@ def optimize(  # NOSONAR(S107)
                 the decorator. The currently supported keys are:
                 ``metric_limit``, ``metric_name``,
                 ``metric_include_pruned``, ``plateau_window``,
-                ``plateau_epsilon``, ``cost_limit``, ``cost_approved``,
-                ``tie_breakers``, and ``tvl_parameter_agents``.
+                ``plateau_epsilon``, ``semantic_saturation``, ``cost_limit``,
+                ``cost_approved``, ``tie_breakers``, and
+                ``tvl_parameter_agents``.
                 Note: ``algorithm`` and ``max_trials`` are first-class
                 parameters of this decorator (not in ``**runtime_overrides``);
                 ``timeout`` is supported on
@@ -2639,6 +2717,20 @@ def optimize(  # NOSONAR(S107)
     if custom_evaluator is not None:
         _validate_custom_evaluator_signature(custom_evaluator)
 
+    # Optional surrogate (pre-screen) scorer from the evaluation bundle. Resolved
+    # here (decorator source only) and validated early; stashed on the
+    # OptimizedFunction below so the evaluator factory can attach it.
+    surrogate_evaluator = (
+        evaluation_bundle.surrogate_evaluator if evaluation_bundle is not None else None
+    )
+    surrogate_evaluator_name = (
+        evaluation_bundle.surrogate_evaluator_name
+        if evaluation_bundle is not None
+        else None
+    )
+    if surrogate_evaluator is not None:
+        _validate_surrogate_evaluator_signature(surrogate_evaluator)
+
     (
         injection_mode,
         config_param,
@@ -2969,6 +3061,13 @@ def optimize(  # NOSONAR(S107)
         optimized_func.external_service_evaluator = external_service_evaluator
         optimized_func.hybrid_api_options = hybrid_api_options
         optimized_func.offline = execution_policy.offline
+        # Surrogate (pre-screen) scorer: read via getattr by the evaluator
+        # factory (_create_effective_evaluator). Absent when unconfigured, so the
+        # no-surrogate path stays byte-identical.
+        if surrogate_evaluator is not None:
+            optimized_func._surrogate_evaluator = surrogate_evaluator
+            if isinstance(surrogate_evaluator_name, str) and surrogate_evaluator_name:
+                optimized_func._surrogate_evaluator_name = surrogate_evaluator_name
 
         logger.info(
             f"Created optimizable function: {func.__name__} (experiment_name={effective_experiment_name!r})"