traigent 0.17.0.dev0__tar.gz → 0.18.0__tar.gz

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

@@ -6,6 +6,8 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-06-27
+
 ### Added
 - Added a no-content-egress cloud-brain canary test that captures serialized
   session, next-trial, metrics, and finalize payloads and asserts dataset

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.17.0.dev0
+Version: 0.18.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
@@ -36,7 +36,7 @@ Requires-Dist: jsonschema>=4.0.0
 Requires-Dist: cryptography>=46.0.7
 Requires-Dist: PyJWT[crypto]<3.0.0,>=2.13.0
 Requires-Dist: backoff>=2.2.0
-Requires-Dist: litellm==1.87.1
+Requires-Dist: litellm<2,>=1.87.1
 Requires-Dist: rank-bm25
 Requires-Dist: psutil>=5.8.0
 Requires-Dist: pydantic>=2.0.0
@@ -287,7 +287,7 @@ Works with any LLM provider — [OpenAI](https://platform.openai.com/docs), [Ant
 | **Get started** | [Installation](docs/getting-started/installation.md) · [5-minute tutorial](docs/getting-started/GETTING_STARTED.md) |
 | **User guides** | [Injection Modes](docs/user-guide/injection_modes.md) · [Configuration Spaces](docs/user-guide/configuration-spaces.md) · [Evaluation](docs/user-guide/evaluation_guide.md) |
 | **Tunable Variable Language** | [TVL Guide](docs/user-guide/tuned_variables.md) |
-| **Advanced** | [Agent Optimization](docs/user-guide/agent_optimization.md) · [Optuna Integration](docs/user-guide/optuna_integration.md) |
+| **Advanced** | [Agent Optimization](docs/user-guide/agent_optimization.md) |
 | **API reference** | [Decorator Reference](docs/api-reference/decorator-reference.md) · [Constraint DSL](docs/features/constraint-dsl.md) |
 
 </details>
@@ -376,7 +376,7 @@ The default run uses Traigent's smart optimizer when portal credentials are avai
 ```python
 @traigent.optimize(
     configuration_space={
-        "model": ["gpt-4o-mini", "claude-3-haiku-20240307", "gemini/gemini-pro"],
+        "model": ["gpt-4o-mini", "claude-haiku-4-5-20251001", "gemini/gemini-pro"],
         "temperature": [0.1, 0.5, 0.9],
     },
     objectives=["accuracy", "cost"],
@@ -460,7 +460,7 @@ for details.
 
 ### Evaluation
 
-Provide a JSONL dataset — Traigent scores outputs using semantic similarity by default:
+Provide a JSONL dataset — Traigent scores outputs by exact / case-insensitive match by default. For semantic scoring (paraphrases, summarization, translation), supply a `scoring_function` (embeddings or LLM-judge) or a `custom_evaluator`:
 
 ```jsonl
 {"input": {"question": "What is AI?"}, "output": "Artificial Intelligence"}

{traigent-0.17.0.dev0 → traigent-0.18.0}/README.md

@@ -140,7 +140,7 @@ Works with any LLM provider — [OpenAI](https://platform.openai.com/docs), [Ant
 | **Get started** | [Installation](docs/getting-started/installation.md) · [5-minute tutorial](docs/getting-started/GETTING_STARTED.md) |
 | **User guides** | [Injection Modes](docs/user-guide/injection_modes.md) · [Configuration Spaces](docs/user-guide/configuration-spaces.md) · [Evaluation](docs/user-guide/evaluation_guide.md) |
 | **Tunable Variable Language** | [TVL Guide](docs/user-guide/tuned_variables.md) |
-| **Advanced** | [Agent Optimization](docs/user-guide/agent_optimization.md) · [Optuna Integration](docs/user-guide/optuna_integration.md) |
+| **Advanced** | [Agent Optimization](docs/user-guide/agent_optimization.md) |
 | **API reference** | [Decorator Reference](docs/api-reference/decorator-reference.md) · [Constraint DSL](docs/features/constraint-dsl.md) |
 
 </details>
@@ -229,7 +229,7 @@ The default run uses Traigent's smart optimizer when portal credentials are avai
 ```python
 @traigent.optimize(
     configuration_space={
-        "model": ["gpt-4o-mini", "claude-3-haiku-20240307", "gemini/gemini-pro"],
+        "model": ["gpt-4o-mini", "claude-haiku-4-5-20251001", "gemini/gemini-pro"],
         "temperature": [0.1, 0.5, 0.9],
     },
     objectives=["accuracy", "cost"],
@@ -313,7 +313,7 @@ for details.
 
 ### Evaluation
 
-Provide a JSONL dataset — Traigent scores outputs using semantic similarity by default:
+Provide a JSONL dataset — Traigent scores outputs by exact / case-insensitive match by default. For semantic scoring (paraphrases, summarization, translation), supply a `scoring_function` (embeddings or LLM-judge) or a `custom_evaluator`:
 
 ```jsonl
 {"input": {"question": "What is AI?"}, "output": "Artificial Intelligence"}

{traigent-0.17.0.dev0 → traigent-0.18.0}/docs/api-reference/complete-function-specification.md

@@ -255,7 +255,7 @@ Unknown keys are forwarded to the optimizer and may raise errors when unsupporte
 **Example:**
 ```python
 # Run optimization with the default smart optimizer
-result = await my_agent.optimize(max_trials=50)
+result = await my_agent.optimize()
 
 # Save results
 await my_agent.save_optimization_results("results.json")

{traigent-0.17.0.dev0 → traigent-0.18.0}/docs/api-reference/decorator-reference.md

@@ -570,7 +570,7 @@ Legacy `execution_mode=` inputs are deprecated compatibility shims. Use
 Run controls such as `max_trials` and `timeout` are passed to `.optimize()`:
 
 ```python
-result = await my_agent.optimize(max_trials=50, timeout=3600)
+result = await my_agent.optimize(max_trials=10, timeout=3600)
 ```
 
 **Cost Controls**:

{traigent-0.17.0.dev0 → traigent-0.18.0}/docs/getting-started/GETTING_STARTED.md

@@ -47,6 +47,7 @@ import asyncio
 from langchain_openai import ChatOpenAI
 import traigent
 
+
 @traigent.optimize(
     configuration_space={
         "model": ["gpt-4o-mini", "gpt-4o"],
@@ -60,6 +61,7 @@ def answer(question: str) -> str:
     llm = ChatOpenAI(model=cfg["model"], temperature=cfg["temperature"])
     return llm.invoke(question).content
 
+
 # Run optimization
 result = asyncio.run(answer.optimize(max_trials=6))
 print(f"Best config: {result.best_config}")
@@ -78,6 +80,10 @@ print(f"Best score:  {result.best_score:.2%}")
 ## 🧪 Datasets
 
 - Format: JSONL with `input` and optional `output`/`expected_output`
+- Beginner examples use the flat `eval_dataset=` keyword. The bundled
+  `evaluation=EvaluationOptions(...)` form is also supported when you want to
+  group evaluation settings, but `eval_dataset=` is the recommended minimal-call
+  shape in this guide.
 - Minimal example:
 
 ```jsonl
@@ -88,15 +94,12 @@ print(f"Best score:  {result.best_score:.2%}")
 ## 🎛️ Multiple Objectives
 
 ```python
-from traigent.api.decorators import EvaluationOptions
-
 @traigent.optimize(
     objectives=["accuracy", "cost", "latency"],
-    evaluation=EvaluationOptions(eval_dataset="data.jsonl"),
+    eval_dataset="data.jsonl",
     configuration_space={"temperature": (0.0, 1.0), "model": ["gpt-4o-mini", "gpt-4o"]},
 )
-def classify(text: str) -> str:
-    ...
+def classify(text: str) -> str: ...
 ```
 
 ## 🧪 Examples
@@ -129,6 +132,7 @@ pip install litellm
 ```python
 from litellm import completion
 
+
 @traigent.optimize(
     configuration_space={
         "model": ["gpt-4o-mini", "claude-3-haiku-20240307", "gemini/gemini-pro"],
@@ -138,7 +142,9 @@ from litellm import completion
 )
 def my_agent(query: str) -> str:
     config = traigent.get_config()
-    response = completion(model=config.get("model"), messages=[{"role": "user", "content": query}])
+    response = completion(
+        model=config.get("model"), messages=[{"role": "user", "content": query}]
+    )
     return str(response.choices[0].message.content)
 ```
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traigent"
-version = "0.17.0.dev0"
+version = "0.18.0"
 authors = [
     {name = "Traigent Team", email = "opensource@traigent.ai"},
 ]
@@ -43,7 +43,7 @@ dependencies = [
     "cryptography>=46.0.7",  # CVE-2026-26007 + 3 more fixed in 46.0.7 (see #709)
     "PyJWT[crypto]>=2.13.0,<3.0.0",  # >=2.13.0: Dependabot alerts — DoS, SSRF via JWKClient, HS256 forgery, alg bypass, kid DoS
     "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.
+    "litellm>=1.87.1,<2",  # Floor: 1.84+ escaped the 1.83.x python-dotenv==1.0.1 and openai==2.24.0 exact sub-pins; 1.87.1 is the first stable release verified against this SDK. Upper bound <2 guards against a future breaking major. The demo (TraigentDemo) requires 1.88.0; this range admits it. Only the public API surface (completion, acompletion, cost_per_token, token_counter, model_cost, ModelResponse) is used — stable across the 1.x line.
     "rank-bm25",
     "psutil>=5.8.0",
     # Required by API decorators and config validation
@@ -239,6 +239,7 @@ Changelog = "https://github.com/Traigent/Traigent/blob/main/CHANGELOG.md"
 
 [project.scripts]
 traigent = "traigent.cli.main:cli"
+traigent-analytics-mcp = "traigent.analytics_mcp.server:main"
 
 [project.entry-points."traigent.validators"]
 python = "traigent_validation.validators:PythonConstraintValidator"

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

@@ -10,6 +10,6 @@ typing-extensions>=4.0.0; python_version<"3.11"
 claude-code-sdk>=0.0.14
 mcp>=1.27.0
 backoff>=2.2.0
-litellm==1.87.1
+litellm>=1.87.1,<2
 rank-bm25
 psutil>=5.8.0

{traigent-0.17.0.dev0 → traigent-0.18.0}/traigent/__init__.py

@@ -64,9 +64,16 @@ def _is_quickstart_invocation() -> bool:
     if not sys.argv:
         return False
     argv0 = sys.argv[0] or ""
-    # ``python -m traigent.examples.quickstart`` — argv[0] is the path
-    # to the quickstart's __main__.py
-    if argv0.endswith(("quickstart/__main__.py", "quickstart\\__main__.py")):
+    # ``python -m traigent.examples.quickstart`` and quickstart companion
+    # modules — argv[0] is the path to the module's .py file.
+    if argv0.endswith(
+        (
+            "quickstart/__main__.py",
+            "quickstart\\__main__.py",
+            "quickstart/publish_and_verify.py",
+            "quickstart\\publish_and_verify.py",
+        )
+    ):
         return True
     # ``traigent quickstart`` — argv[0] is the venv's bin/traigent script
     # and argv[1] is the subcommand name. Gate on argv[0] basename being
@@ -310,6 +317,14 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
     "TenantSSOConfigDTO": ("traigent.admin", "TenantSSOConfigDTO"),
     # Evaluation DTOs
     "AnnotationQueueDTO": ("traigent.evaluation", "AnnotationQueueDTO"),
+    "AnnotationQueueItemCompleteResultDTO": (
+        "traigent.evaluation",
+        "AnnotationQueueItemCompleteResultDTO",
+    ),
+    "AnnotationQueueItemCreateResultDTO": (
+        "traigent.evaluation",
+        "AnnotationQueueItemCreateResultDTO",
+    ),
     "AnnotationQueueItemDTO": ("traigent.evaluation", "AnnotationQueueItemDTO"),
     "AnnotationQueueItemListResponse": (
         "traigent.evaluation",
@@ -339,6 +354,7 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
     "ScoreRecordDTO": ("traigent.evaluation", "ScoreRecordDTO"),
     "ScoreRecordListResponse": ("traigent.evaluation", "ScoreRecordListResponse"),
     "ScoreSource": ("traigent.evaluation", "ScoreSource"),
+    "TypedMeasureDTO": ("traigent.evaluation", "TypedMeasureDTO"),
     # Observability DTOs and helpers
     "CorrelationIds": ("traigent.observability", "CorrelationIds"),
     "ObserveContext": ("traigent.observability", "ObserveContext"),
@@ -560,6 +576,8 @@ __all__ = [
     "TenantMembershipStatus",
     "TenantSSOConfigDTO",
     "AnnotationQueueDTO",
+    "AnnotationQueueItemCompleteResultDTO",
+    "AnnotationQueueItemCreateResultDTO",
     "AnnotationQueueItemDTO",
     "AnnotationQueueItemListResponse",
     "AnnotationQueueItemStatus",
@@ -578,6 +596,7 @@ __all__ = [
     "ScoreRecordDTO",
     "ScoreRecordListResponse",
     "ScoreSource",
+    "TypedMeasureDTO",
     "CorrelationIds",
     "ObserveContext",
     "ObservationDTO",

{traigent-0.17.0.dev0 → traigent-0.18.0}/traigent/_version.py

@@ -68,11 +68,6 @@ def get_version() -> str:
             "installed package metadata"
         ) from None
 
-    raise RuntimeError(
-        "Unable to resolve Traigent SDK version from pyproject.toml or "
-        "installed package metadata"
-    )
-
 
 def get_version_info() -> dict[str, str]:
     """Get detailed version information.

{traigent-0.17.0.dev0 → traigent-0.18.0}/traigent/adapters/execution_adapter.py

@@ -9,6 +9,7 @@ from abc import ABC, abstractmethod
 from typing import Any, cast
 
 from traigent.config.types import ExecutionMode
+from traigent.evaluators.base import _accuracy_values_match
 
 logger = logging.getLogger(__name__)
 
@@ -192,7 +193,7 @@ class LocalExecutionAdapter(ExecutionAdapter):
             # Exact / case-insensitive match — must stay aligned with
             # LocalEvaluator and the public docs (the tracked fix). Diverging
             # here was how "Paris" vs "paris" silently scored 0.0.
-            is_correct = str(output).strip().lower() == str(expected).strip().lower()
+            is_correct = _accuracy_values_match(output, expected)
             result["correct"] = is_correct
 
         elif eval_type == "contains":
@@ -245,8 +246,21 @@ class LocalExecutionAdapter(ExecutionAdapter):
 
         else:
             # Unknown evaluation type
-            result["correct"] = None
+            result["success"] = False
             result["unknown_eval_type"] = eval_type
+            result["error"] = (
+                f"Unsupported evaluation_type '{eval_type}'. "
+                "Use exact_match, contains, numeric, semantic with a custom evaluator, "
+                "or provide a scoring_function."
+            )
+            logger.error(
+                "Unsupported evaluation_type %r for LocalExecutionAdapter; marking "
+                "example as failed and excluding it from accuracy. "
+                "trial_id=%s example_index=%s",
+                eval_type,
+                trial_id or "<unknown>",
+                example_index if example_index is not None else "<unknown>",
+            )
 
         return result
 

{traigent-0.17.0.dev0 → traigent-0.18.0}/traigent/admin/config.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 
+from traigent.cloud.url_security import validate_cloud_base_url
 from traigent.config.backend_config import BackendConfig
 from traigent.config.tenant import TENANT_ENV_VAR, TENANT_HEADER_NAME, read_optional_env
 
@@ -22,7 +23,10 @@ class EnterpriseAdminConfig:
     extra_headers: dict[str, str] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
-        self.backend_origin = self.backend_origin.rstrip("/")
+        backend_origin = self.backend_origin.rstrip("/")
+        self.backend_origin = validate_cloud_base_url(
+            backend_origin, purpose="enterprise admin request"
+        )
         self.tenant_id = (
             self.tenant_id.strip() or None if self.tenant_id is not None else None
         )

{traigent-0.17.0.dev0 → traigent-0.18.0}/traigent/agents/specification_generator.py

@@ -443,8 +443,8 @@ class SpecificationGenerator:
         )
 
         # Update model parameters with best configuration
-        if "best_config" in optimization_results:
-            best_config = optimization_results["best_config"]
+        best_config = optimization_results.get("best_config")
+        if isinstance(best_config, dict):
             updated_params = (agent_spec.model_parameters or {}).copy()
 
             # Update with optimized parameters

{traigent-0.17.0.dev0 → traigent-0.18.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.17.0.dev0 → traigent-0.18.0}/traigent/analytics/example_insights.py

@@ -30,6 +30,8 @@ import asyncio
 import time
 from typing import Any, cast
 
+from traigent.cloud.auth import _build_api_key_auth_headers
+from traigent.cloud.url_security import validate_cloud_base_url
 from traigent.config.backend_config import DEFAULT_LOCAL_URL
 from traigent.utils.logging import get_logger
 
@@ -72,7 +74,10 @@ class ExampleInsightsClient:
                 "Install with: pip install traigent[analytics]"
             )
 
-        self.backend_url = backend_url.rstrip("/")
+        backend_url = backend_url.rstrip("/")
+        self.backend_url = validate_cloud_base_url(
+            backend_url, purpose="analytics request"
+        )
         self.timeout = timeout
 
         # Import here to avoid circular dependency
@@ -100,9 +105,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.17.0.dev0 → traigent-0.18.0}/traigent/analytics/next_steps.py

@@ -23,6 +23,8 @@ from __future__ import annotations
 
 from typing import Any, cast
 
+from traigent.cloud.auth import _build_api_key_auth_headers
+from traigent.cloud.url_security import validate_cloud_base_url
 from traigent.config.backend_config import DEFAULT_LOCAL_URL
 from traigent.utils.logging import get_logger
 
@@ -76,7 +78,10 @@ class NextStepsClient:
                 "Install with: pip install traigent[analytics]"
             )
 
-        self.backend_url = backend_url.rstrip("/")
+        backend_url = backend_url.rstrip("/")
+        self.backend_url = validate_cloud_base_url(
+            backend_url, purpose="analytics request"
+        )
         self.timeout = timeout
 
         # Import here to avoid circular dependency
@@ -102,9 +107,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.18.0/traigent/analytics/optimization_plan.py

@@ -0,0 +1,216 @@
+"""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.cloud.url_security import validate_cloud_base_url
+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]"
+            )
+
+        backend_url = backend_url.rstrip("/")
+        self.backend_url = validate_cloud_base_url(
+            backend_url, purpose="optimization plan request"
+        )
+        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)