traigent 0.16.0.dev0__tar.gz → 0.17.0__tar.gz

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

@@ -6,6 +6,8 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-06-23
+
 ### Added
 - Added a no-content-egress cloud-brain canary test that captures serialized
   session, next-trial, metrics, and finalize payloads and asserts dataset
@@ -16,6 +18,38 @@ 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.
 
+### Removed
+- Removed public pruner exports: `CeilingPruner`, `CeilingPrunerConfig`,
+  `StatisticalInferiorityPruner`, and `StatisticalInferiorityPrunerConfig`.
+- Dropped the `optuna` runtime dependency.
+- Removed `register_optuna_optimizers` and the legacy Optuna feature flag/env
+  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
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.16.0.dev0
+Version: 0.17.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
@@ -38,7 +38,6 @@ Requires-Dist: PyJWT[crypto]<3.0.0,>=2.13.0
 Requires-Dist: backoff>=2.2.0
 Requires-Dist: litellm==1.87.1
 Requires-Dist: rank-bm25
-Requires-Dist: optuna>=4.5.0
 Requires-Dist: psutil>=5.8.0
 Requires-Dist: pydantic>=2.0.0
 Provides-Extra: analytics

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

@@ -50,7 +50,7 @@ def answer_question(question: str) -> str:
 - **[Injection Modes](user-guide/injection_modes.md)** - Different ways to integrate Traigent
 - **[Interactive Optimization](user-guide/interactive_optimization.md)** - Real-time optimization workflows
 - **[Evaluation Guide](user-guide/evaluation_guide.md)** - Measure and improve performance
-- **[Optuna Integration](user-guide/optuna_integration.md)** - Optuna-backed optimizers, coordinator, and adapter
+- **[Smart Optimization](user-guide/smart_optimization.md)** - Backend-routed smart optimizer strategies
 
 ### 🧭 [Guides](guides/)
 - **[Optimization Routing](guides/execution-modes.md)** - Default smart optimization, local search, portal sync, and no-egress runs

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

@@ -164,61 +164,23 @@ Any other value (including unset) means telemetry is enabled.
 
 When `TRAIGENT_DISABLE_TELEMETRY` is set:
 
-1. **No telemetry events are emitted** - The `OptunaMetricsEmitter` immediately returns without recording
+1. **No telemetry events are emitted** - SDK telemetry collectors return without recording
 2. **No metrics are sent to collectors** - MetricsCollector calls are skipped
 3. **Optimization still works normally** - Only telemetry is disabled, not functionality
 4. **Local results are still saved** - Optimization results are still persisted locally for your use
 
 ## Telemetry Implementation
 
-### OptunaMetricsEmitter
-
-The main telemetry component is `OptunaMetricsEmitter` in `traigent/telemetry/optuna_metrics.py`:
-
-```python
-from traigent.telemetry.optuna_metrics import OptunaMetricsEmitter
-
-# Telemetry is automatically disabled when env var is set
-emitter = OptunaMetricsEmitter(
-    metrics_collector=collector,
-    listeners=[my_listener],
-)
-
-# This call does nothing if TRAIGENT_DISABLE_TELEMETRY is set
-emitter.emit_trial_update(
-    event="trial_completed",
-    trial_id=123,
-    study_name="my_optimization",
-    payload={"metrics": {"accuracy": 0.95}},
-)
-```
-
-### Implementation Details
-
-The `OptunaMetricsEmitter` checks the environment variable on initialization:
-
-```python
-class OptunaMetricsEmitter:
-    def __init__(self, ...):
-        self._disabled = os.getenv("TRAIGENT_DISABLE_TELEMETRY", "").lower() in (
-            "1",
-            "true",
-            "yes",
-        )
-
-    def emit_trial_update(self, ...):
-        if self._disabled:
-            return {}  # No-op when disabled
-
-        # Normal telemetry emission
-        ...
-```
+Telemetry is routed through optimization storage, observability clients, and
+workflow tracing. The previous SDK-local Optuna telemetry emitter has been
+removed with the local Optuna dependency; smart optimizer telemetry is now a
+backend concern.
 
 ### Event Types
 
 When telemetry is enabled, the following events may be emitted (not exhaustive):
 
-- `trial_suggested` - Optuna proposed a new trial configuration
+- `trial_suggested` - An optimizer proposed a new trial configuration
 - `trial_intermediate` - Intermediate metric reported (pruning signal)
 - `trial_completed` - A trial finished successfully
 - `trial_failed` - A trial encountered an error
@@ -282,49 +244,12 @@ 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 sensitive projects.
 
-## Telemetry Listeners
-
-You can subscribe to telemetry events for your own monitoring:
-
-```python
-from traigent.telemetry.optuna_metrics import OptunaMetricsEmitter
-
-def my_listener(event_data: dict):
-    print(f"Trial event: {event_data['event']}")
-    print(f"Trial ID: {event_data['trial_id']}")
-    print(f"Metrics: {event_data.get('payload', {})}")
-
-emitter = OptunaMetricsEmitter()
-emitter.subscribe(my_listener)
-
-# Your listener will be called for each telemetry event
-# (unless TRAIGENT_DISABLE_TELEMETRY is set)
-```
-
 ## Security and Sensitive Data
 
 ### Data Sanitization
 
-Configuration data is automatically sanitized before telemetry:
-
-```python
-from traigent.telemetry.optuna_metrics import sanitize_config
-
-config = {
-    "model": "gpt-4",
-    "temperature": 0.7,
-    "_internal_key": "should_not_be_logged",
-}
-
-safe_config = sanitize_config(config)
-# Returns: {"model": "gpt-4", "temperature": 0.7"}
-```
-
-Private/internal keys (starting with `_`) are automatically removed.
-
-### Thread Safety
-
-The `OptunaMetricsEmitter` is thread-safe and uses `threading.RLock` to protect listener subscription operations.
+Configuration data is sanitized before telemetry. Private/internal keys
+(starting with `_`) are automatically removed.
 
 ### Error Handling
 

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

@@ -13,7 +13,7 @@ python examples/core/simple-prompt/run.py
 # With real LLMs
 export ANTHROPIC_API_KEY="your-key" # pragma: allowlist secret
 export OPENAI_API_KEY="your-key" # pragma: allowlist secret
-python examples/core/multi-objective-tradeoff/run_openai_optuna.py
+python examples/core/multi-objective-tradeoff/run_openai_backend_smart.py
 ```
 
 ## Core optimize pattern

{traigent-0.16.0.dev0 → traigent-0.17.0}/docs/getting-started/installation.md

@@ -36,7 +36,7 @@ License: Traigent SDK is dual-licensed under AGPL-3.0-only OR LicenseRef-Traigen
 | **`recommended`** | **All user-facing features (integrations + analytics + bayesian + visualization + hybrid + pydanticai)** | **`pip install "traigent[recommended]"`** |
 | `integrations` | LangChain, OpenAI, Anthropic, MLflow, W&B | `pip install -e ".[integrations]"` |
 | `analytics` | numpy, pandas, matplotlib | `pip install -e ".[analytics]"` |
-| `bayesian` | Optuna + sklearn/scipy | `pip install -e ".[bayesian]"` |
+| `bayesian` | scikit-learn + scipy | `pip install -e ".[bayesian]"` |
 | `visualization` | matplotlib, plotly | `pip install -e ".[visualization]"` |
 | `hybrid` | HTTP/2 transport plus MCP-backed hybrid integrations | `pip install -e ".[hybrid]"` |
 | `cloud` | Reserved dependencies for future remote execution; not required for portal-tracked `hybrid` runs | `pip install -e ".[cloud]"` |

{traigent-0.16.0.dev0 → traigent-0.17.0}/docs/user-guide/README.md

@@ -11,7 +11,7 @@ Comprehensive guides for using Traigent SDK features and capabilities.
 - **[Injection Modes](injection_modes.md)** - Different ways to integrate Traigent with your code
 - **[Interactive Optimization](interactive_optimization.md)** - Real-time optimization workflows and monitoring
 - **[Evaluation Guide](evaluation_guide.md)** - Measure and improve model performance
-- **[Optuna Integration](optuna_integration.md)** - Use the Optuna-backed optimizers and distributed coordinator
+- **[Smart Optimization](smart_optimization.md)** - Use backend-routed smart optimizer strategies
 
 ## Learning Path
 
@@ -21,7 +21,7 @@ Comprehensive guides for using Traigent SDK features and capabilities.
 
 **Tuned Variables**: Use [Tuned Variables](tuned_variables.md) to auto-detect parameters and discover callables
 
-**Advanced Users**: Explore [Agent Optimization](agent_optimization.md), [Interactive Optimization](interactive_optimization.md), and [Optuna Integration](optuna_integration.md)
+**Advanced Users**: Explore [Agent Optimization](agent_optimization.md), [Interactive Optimization](interactive_optimization.md), and [Smart Optimization](smart_optimization.md)
 
 **Evaluation**: Use [Evaluation Guide](evaluation_guide.md) to measure success
 

traigent-0.17.0/docs/user-guide/smart_optimization.md

@@ -0,0 +1,65 @@
+# Smart Optimization
+
+Traigent SDKs expose a small local optimizer surface by default:
+
+- `grid`
+- `random`
+
+Smart optimization is backend-routed. Use a TraigentBackend typed session or
+hybrid SDK mode when you need guided search beyond the local defaults.
+
+## Public Smart Strategies
+
+| Strategy         | Runs In         | Use Case                                                 |
+| ---------------- | --------------- | -------------------------------------------------------- |
+| `bayesian`       | TraigentBackend | Public alias for guided TPE-style search                 |
+| `tpe`            | TraigentBackend | Guided search over categorical and continuous spaces     |
+| `optuna`         | TraigentBackend | Managed Optuna-family routing                            |
+| `optuna_tpe`     | TraigentBackend | Explicit TPE routing                                     |
+| `optuna_random`  | TraigentBackend | Managed random-search routing                            |
+| `optuna_grid`    | TraigentBackend | Managed grid-search routing                              |
+| `optuna_cmaes`   | TraigentBackend | Managed CMA-ES routing                                   |
+| `optuna_nsga2`   | TraigentBackend | Managed NSGA-II routing                                  |
+| `nsga2`          | TraigentBackend | NSGA-II alias                                            |
+| `nsgaii`         | TraigentBackend | NSGA-II alias                                            |
+| `nsga_ii`        | TraigentBackend | NSGA-II alias                                            |
+| `cmaes`          | TraigentBackend | CMA-ES alias                                             |
+| `cma_es`         | TraigentBackend | CMA-ES alias                                             |
+
+Local SDK runs accept `grid` and `random`. Smart strategies listed above are
+validated by the SDK and routed to TraigentBackend.
+
+## Python Hybrid Session Example
+
+```python
+import traigent
+from traigent import Choices, Range
+
+
+@traigent.optimize(
+    eval_dataset=[
+        {"input": "What is the capital of France?", "expected": "Paris"},
+        {"input": "What is the capital of Germany?", "expected": "Berlin"},
+    ],
+    objectives=["accuracy", "cost"],
+    model=Choices(["fast", "accurate"]),
+    temperature=Range(0.0, 1.0),
+)
+def answer_quality(question: str, model: str, temperature: float) -> str:
+    return call_model(question, model=model, temperature=temperature)
+
+
+result = await answer_quality.optimize(
+    max_trials=12,
+    algorithm="tpe",
+)
+```
+
+Use `bayesian`, `tpe`, or one of the accepted Optuna-family aliases when you
+want managed smart search through TraigentBackend.
+
+## Local Defaults
+
+For offline/local SDK runs, keep using `grid` or `random`. These require no
+backend service and remain deterministic/reproducible under the existing local
+SDK execution path.

{traigent-0.16.0.dev0 → traigent-0.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traigent"
-version = "0.16.0.dev0"
+version = "0.17.0"
 authors = [
     {name = "Traigent Team", email = "opensource@traigent.ai"},
 ]
@@ -45,8 +45,6 @@ dependencies = [
     "backoff>=2.2.0",
     "litellm==1.87.1",  # Stable pin: 1.83.x python-dotenv==1.0.1 and 1.83.14 openai==2.24.0 sub-pins are gone from stable 1.84+ (1.87.1 ships openai>=2.20,<3 and python-dotenv>=1.0,<2, compatible with langchain-openai>=1.1.14). Keep pinned + verified on bumps; no need for RC/dev builds anymore.
     "rank-bm25",
-    # Required by core optimizer modules
-    "optuna>=4.5.0",
     "psutil>=5.8.0",
     # Required by API decorators and config validation
     "pydantic>=2.0.0",

{traigent-0.16.0.dev0 → traigent-0.17.0}/requirements/requirements-all.txt

@@ -4,10 +4,10 @@
 
 -r requirements.txt
 -r requirements-analytics.txt
--r requirements-bayesian.txt
--r requirements-integrations.txt
--r requirements-security.txt
--r requirements-hybrid.txt
+-r requirements-bayesian.txt
+-r requirements-integrations.txt
+-r requirements-security.txt
+-r requirements-hybrid.txt
 
 # Visualization
 matplotlib>=3.5.0

traigent-0.17.0/requirements/requirements-bayesian.txt

@@ -0,0 +1,2 @@
+scikit-learn>=1.0.0
+scipy>=1.7.0

{traigent-0.16.0.dev0 → traigent-0.17.0}/requirements/requirements-dev.txt

@@ -3,10 +3,10 @@
 # Excludes Chroma until chromadb has a patched release for CVE-2026-45829.
 
 -r requirements.txt
--r requirements-analytics.txt
--r requirements-bayesian.txt
--r requirements-integrations.txt
--r requirements-security.txt
+-r requirements-analytics.txt
+-r requirements-bayesian.txt
+-r requirements-integrations.txt
+-r requirements-security.txt
 
 # Development and testing
 pytest>=9.0.3

{traigent-0.16.0.dev0 → traigent-0.17.0}/requirements/requirements-test.txt

@@ -12,14 +12,14 @@ rapidfuzz>=3.14.0
 # Core dependencies needed for tests
 -r requirements.txt
 
-# Analytics dependencies needed for insights tests
--r requirements-analytics.txt
-
-# Bayesian dependencies needed for optimization tests
--r requirements-bayesian.txt
-
-# Security dependencies needed for enterprise tests
--r requirements-security.txt
+# Analytics dependencies needed for insights tests
+-r requirements-analytics.txt
+
+# Bayesian dependencies needed for optimization tests
+-r requirements-bayesian.txt
+
+# Security dependencies needed for enterprise tests
+-r requirements-security.txt
 
 # Integration dependencies needed for framework tests
 -r requirements-integrations.txt

{traigent-0.16.0.dev0 → traigent-0.17.0}/requirements/requirements.txt

@@ -12,5 +12,4 @@ mcp>=1.27.0
 backoff>=2.2.0
 litellm==1.87.1
 rank-bm25
-optuna>=4.5.0
 psutil>=5.8.0

{traigent-0.16.0.dev0 → traigent-0.17.0}/traigent/analytics/__init__.py

@@ -92,6 +92,7 @@ except ImportError:
         PerformancePredictor,
     )
     from .next_steps import NextStepsClient
+    from .optimization_plan import OptimizationPlanClient
 
     # Predictive analytics
     from .predictive import (
@@ -130,6 +131,7 @@ __all__ = [
     # Example Insights
     "ExampleInsightsClient",
     "NextStepsClient",
+    "OptimizationPlanClient",
     # Historical analytics
     "HistoricalAnalyticsEngine",
     "OptimizationHistory",

{traigent-0.16.0.dev0 → traigent-0.17.0}/traigent/analytics/example_insights.py

@@ -30,6 +30,7 @@ import asyncio
 import time
 from typing import Any, cast
 
+from traigent.cloud.auth import _build_api_key_auth_headers
 from traigent.config.backend_config import DEFAULT_LOCAL_URL
 from traigent.utils.logging import get_logger
 
@@ -100,9 +101,9 @@ class ExampleInsightsClient:
 
         raise_if_backend_offline("ExampleInsightsClient request")
         if self._client is None:
-            headers = {}
+            headers: dict[str, str] = {}
             if self.api_key:
-                headers["Authorization"] = f"Bearer {self.api_key}"
+                headers.update(_build_api_key_auth_headers(self.api_key))
 
             self._client = httpx.AsyncClient(
                 base_url=self.backend_url,

{traigent-0.16.0.dev0 → traigent-0.17.0}/traigent/analytics/next_steps.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 from typing import Any, cast
 
+from traigent.cloud.auth import _build_api_key_auth_headers
 from traigent.config.backend_config import DEFAULT_LOCAL_URL
 from traigent.utils.logging import get_logger
 
@@ -102,9 +103,9 @@ class NextStepsClient:
 
         raise_if_backend_offline("NextStepsClient request")
         if self._client is None:
-            headers = {}
+            headers: dict[str, str] = {}
             if self.api_key:
-                headers["Authorization"] = f"Bearer {self.api_key}"
+                headers.update(_build_api_key_auth_headers(self.api_key))
 
             self._client = httpx.AsyncClient(
                 base_url=self.backend_url,

traigent-0.17.0/traigent/analytics/optimization_plan.py

@@ -0,0 +1,212 @@
+"""Client for retrieving backend-provided pre-run optimization plans.
+
+This module provides an async-first thin client for:
+``POST /api/v1/optimization/plan``.
+
+The backend owns all planning intelligence. The SDK only sends the request
+context, validates the response has the required top-level contract keys, and
+returns the allowlisted payload unchanged.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, cast
+
+from traigent.config.backend_config import DEFAULT_LOCAL_URL
+from traigent.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+try:
+    import httpx
+
+    HTTPX_AVAILABLE = True
+except ImportError:
+    HTTPX_AVAILABLE = False
+    httpx = None  # type: ignore
+
+
+_REQUIRED_RESPONSE_KEYS = {
+    "schema_version",
+    "phase",
+    "plan",
+    "steps",
+    "evidence_level",
+    "caveat",
+    "advisory",
+}
+
+
+def _build_auth_headers(credential: str | None) -> dict[str, str]:
+    """Return optimization-plan auth headers for an API-key credential."""
+    from traigent.cloud.auth import _build_api_key_auth_headers
+
+    # OptimizationPlanClient accepts API-key credentials only. Reuse the same
+    # X-API-Key-only construction as AuthManager._get_api_key_headers
+    # (cloud/auth.py) and do not infer JWT mode from string shape.
+    return _build_api_key_auth_headers(credential)
+
+
+class OptimizationPlanClient:
+    """Client for retrieving allowlisted pre-run optimization plans.
+
+    Thread Safety: Safe for concurrent use (httpx.AsyncClient is thread-safe).
+    """
+
+    def __init__(
+        self,
+        backend_url: str = DEFAULT_LOCAL_URL,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+    ):
+        """Initialize OptimizationPlanClient.
+
+        Args:
+            backend_url: Backend API base URL. The backend must expose the
+                optimization plan endpoint.
+            api_key: API key for authentication (None uses env var
+                TRAIGENT_API_KEY)
+            timeout: Default timeout for HTTP requests in seconds
+
+        Raises:
+            ImportError: If httpx is not installed
+        """
+        if not HTTPX_AVAILABLE:
+            raise ImportError(
+                "httpx is required for OptimizationPlanClient. "
+                "Install with: pip install traigent[hybrid]"
+            )
+
+        self.backend_url = backend_url.rstrip("/")
+        self.timeout = timeout
+
+        # Import here to avoid circular dependency
+        from traigent.config.backend_config import get_no_credentials_hint
+        from traigent.utils.env_config import get_api_key
+
+        self.api_key = get_api_key("traigent") if api_key is None else api_key
+        if not self.api_key:
+            logger.warning(
+                "No API key found for OptimizationPlanClient. %s",
+                get_no_credentials_hint(),
+            )
+
+        self._client: httpx.AsyncClient | None = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        """Get or create async HTTP client.
+
+        Returns:
+            Configured httpx.AsyncClient instance
+        """
+        from traigent.utils.env_config import raise_if_backend_offline
+
+        raise_if_backend_offline("OptimizationPlanClient request")
+        if self._client is None:
+            headers: dict[str, str] = {}
+            if self.api_key:
+                headers.update(_build_auth_headers(self.api_key))
+
+            self._client = httpx.AsyncClient(
+                base_url=self.backend_url,
+                headers=headers,
+                timeout=self.timeout,
+            )
+
+        return self._client
+
+    async def close(self) -> None:
+        """Close HTTP client and release resources."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> OptimizationPlanClient:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    async def get_optimization_plan(
+        self,
+        *,
+        task_description: str,
+        dataset_size: int,
+        dataset_has_holdout: bool,
+        objectives: Sequence[str],
+        max_trials: int,
+        cost_limit_usd: float,
+        task_type: str | None = None,
+        agent_shape: str | None = None,
+        weights: dict[str, float] | None = None,
+        offline: bool | None = None,
+    ) -> dict[str, Any]:
+        """Retrieve a backend-provided pre-run optimization plan.
+
+        The backend must expose ``POST /api/v1/optimization/plan`` and returns
+        the bare allowlisted optimization plan contract payload.
+
+        Args:
+            task_description: Natural-language description of the optimization
+                task.
+            dataset_size: Number of available examples.
+            dataset_has_holdout: Whether the dataset already has a holdout split.
+            objectives: Objective metric names to plan against.
+            max_trials: Maximum trial count requested for the planned run.
+            cost_limit_usd: Maximum approved spend for the planned run, in USD.
+            task_type: Optional safe task category.
+            agent_shape: Optional safe label for the agent shape.
+            weights: Optional objective-name to relative-weight map.
+            offline: Optional request for a fully offline plan.
+
+        Returns:
+            Dict with the backend optimization plan contract payload.
+
+        Raises:
+            httpx.HTTPError: If request fails.
+            ValueError: If the backend returns a non-object JSON payload or an
+                object missing required optimization-plan contract keys.
+        """
+        body: dict[str, Any] = {
+            "task_description": task_description,
+            "dataset": {
+                "size": dataset_size,
+                "has_holdout": dataset_has_holdout,
+            },
+            "objectives": list(objectives),
+            "budget": {
+                "max_trials": max_trials,
+                "cost_limit_usd": cost_limit_usd,
+            },
+        }
+        if task_type is not None:
+            body["task_type"] = task_type
+        if agent_shape is not None:
+            body["agent_shape"] = agent_shape
+        if weights is not None:
+            body["weights"] = dict(weights)
+        if offline is not None:
+            body["offline"] = offline
+
+        client = self._get_client()
+        response = await client.post("/api/v1/optimization/plan", json=body)
+        response.raise_for_status()
+
+        payload = response.json()
+        if not isinstance(payload, dict):
+            raise ValueError(
+                "Malformed optimization-plan response: expected a JSON object "
+                "matching the optimization-plan contract."
+            )
+
+        missing = sorted(_REQUIRED_RESPONSE_KEYS - payload.keys())
+        if missing:
+            raise ValueError(
+                "Malformed optimization-plan response: missing required key(s): "
+                f"{', '.join(missing)}."
+            )
+
+        return cast(dict[str, Any], payload)

{traigent-0.16.0.dev0 → traigent-0.17.0}/traigent/api/types.py

@@ -693,6 +693,15 @@ class OptimizationResult:
     cloud_url: str | None = None
     run_label: str | None = None
 
+    # User-facing, non-fatal warnings about this run (issue #1407). Populated
+    # when the run hit a money-correctness gap that the user should see — e.g.
+    # one or more models priced to $0 at runtime (a model hard-coded in the
+    # optimized function body that no pricing table covers), which silently
+    # under-reports spend. Empty by default. Each entry is a human-readable
+    # remediation message; structured codes live in ``warning_codes``.
+    warnings: list[str] = field(default_factory=list)
+    warning_codes: list[str] = field(default_factory=list)
+
     # Provenance of this result (issue #1265): "backend" when the run was
     # tracked end-to-end on the cloud backend, "local" when it was computed
     # locally — either an intentionally local mode or a hybrid/cloud run that