traigent 0.18.0.dev0__tar.gz → 0.18.1.dev1__tar.gz

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0/traigent.egg-info → traigent-0.18.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.18.0.dev0
+Version: 0.18.1.dev1
 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.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traigent"
-version = "0.18.0.dev0"
+version = "0.18.1.dev1"
 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

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/traigent/adapters/execution_adapter.py

@@ -246,7 +246,6 @@ class LocalExecutionAdapter(ExecutionAdapter):
 
         else:
             # Unknown evaluation type
-            result["correct"] = False
             result["success"] = False
             result["unknown_eval_type"] = eval_type
             result["error"] = (
@@ -256,7 +255,8 @@ class LocalExecutionAdapter(ExecutionAdapter):
             )
             logger.error(
                 "Unsupported evaluation_type %r for LocalExecutionAdapter; marking "
-                "example as failed. trial_id=%s example_index=%s",
+                "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>",

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/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.18.0.dev0 → traigent-0.18.1.dev1}/traigent/analytics/cost_optimization.py

@@ -481,9 +481,9 @@ class CostOptimizationAI:
                     savings = action.estimated_savings_absolute * simulation_days
                     simulation["total_savings"] += savings
                     simulation["total_estimated_savings"] += savings
-                    simulation["savings_breakdown"][
-                        action.resource_type.value
-                    ] = savings
+                    simulation["savings_breakdown"][action.resource_type.value] = (
+                        savings
+                    )
         else:
             # Dictionary format
             if isinstance(actions, dict):

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/traigent/analytics/example_insights.py

@@ -31,6 +31,7 @@ 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
 
@@ -73,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

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/traigent/analytics/next_steps.py

@@ -24,6 +24,7 @@ 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
 
@@ -77,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
@@ -141,7 +145,8 @@ class NextStepsClient:
         Returns:
             Dict with the backend next-steps contract payload. The response
             includes a ``caveat`` field that callers should display near the
-            recommendations.
+            recommendations. If the backend includes the optional opaque
+            ``posture`` block, it is returned unchanged.
 
         Raises:
             httpx.HTTPError: If request fails. A 404 response is raised as

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/traigent/analytics/optimization_plan.py

@@ -13,6 +13,7 @@ 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
 
@@ -78,7 +79,10 @@ class OptimizationPlanClient:
                 "Install with: pip install traigent[hybrid]"
             )
 
-        self.backend_url = backend_url.rstrip("/")
+        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

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/traigent/analytics/predictive.py

@@ -206,7 +206,9 @@ class CostForecaster:
         alert_level = (
             "critical"
             if projected_overage > budget_limit * 0.1
-            else "warning" if projected_overage > 0 else "none"
+            else "warning"
+            if projected_overage > 0
+            else "none"
         )
 
         return {
@@ -455,7 +457,9 @@ class CostForecaster:
             "trend": (
                 "improving"
                 if efficiency_change < 0
-                else "degrading" if efficiency_change > 0 else "stable"
+                else "degrading"
+                if efficiency_change > 0
+                else "stable"
             ),
         }
 

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/traigent/analytics_mcp/tools.py

@@ -28,6 +28,15 @@ from typing import Any, cast
 from traigent.cloud.analytics_client import normalize_decision_intent
 from traigent.utils.logging import get_logger
 
+try:
+    import httpx
+except ImportError:  # pragma: no cover - BackendAnalyticsClient reports this first
+    _HTTP_STATUS_ERRORS: tuple[type[BaseException], ...] = ()
+    _HTTP_TRANSPORT_ERRORS: tuple[type[BaseException], ...] = ()
+else:
+    _HTTP_STATUS_ERRORS = (httpx.HTTPStatusError,)
+    _HTTP_TRANSPORT_ERRORS = (httpx.TransportError,)
+
 logger = get_logger(__name__)
 
 ANALYTICS_TOOL_NAMES: tuple[str, ...] = (
@@ -48,14 +57,29 @@ ANALYTICS_TOOL_NAMES: tuple[str, ...] = (
 _SUPPORTED_CHART_KINDS: tuple[str, ...] = ("run_pareto", "run_correlations")
 
 
-def _failure(message: str, *, code: str = "invalid_input") -> dict[str, Any]:
-    return {"ok": False, "code": code, "message": message}
+def _failure(
+    message: str,
+    *,
+    code: str = "invalid_input",
+    http_status: int | None = None,
+    backend_url: str | None = None,
+) -> dict[str, Any]:
+    return {
+        "ok": False,
+        "code": code,
+        "message": message,
+        "http_status": http_status,
+        "backend_url": (
+            backend_url if backend_url is not None else _resolved_backend_url()
+        ),
+    }
 
 
-def _auth_failure() -> dict[str, Any]:
+def _auth_failure(*, backend_url: str | None = None) -> dict[str, Any]:
     return _failure(
         "Analytics authentication failed; configure valid Traigent credentials.",
         code="authentication_failed",
+        backend_url=backend_url,
     )
 
 
@@ -80,7 +104,106 @@ async def _new_analytics_client() -> Any:
     from traigent.cloud.analytics_client import BackendAnalyticsClient
 
     credential_kwargs = await resolve_analytics_read_client_credentials()
-    return BackendAnalyticsClient(**credential_kwargs)
+    return BackendAnalyticsClient(
+        api_key=credential_kwargs.get("api_key"),
+        jwt_token=credential_kwargs.get("jwt_token"),
+    )
+
+
+def _resolved_backend_url(client: Any | None = None) -> str | None:
+    candidate = getattr(client, "backend_url", None)
+    if not candidate:
+        try:
+            from traigent.config.backend_config import BackendConfig
+
+            candidate = BackendConfig.get_backend_url()
+        except Exception:  # pragma: no cover - defensive structured fallback
+            return None
+    return _sanitize_url(str(candidate))
+
+
+def _response_payload(response: Any | None) -> Any:
+    if response is None:
+        return None
+    try:
+        return response.json()
+    except Exception:
+        return None
+
+
+def _iter_payload_text(payload: Any) -> Any:
+    if isinstance(payload, dict):
+        for value in payload.values():
+            yield from _iter_payload_text(value)
+    elif isinstance(payload, list):
+        for value in payload:
+            yield from _iter_payload_text(value)
+    elif isinstance(payload, str):
+        yield payload
+
+
+def _signals_not_ready(response: Any | None) -> bool:
+    payload = _response_payload(response)
+    for text in _iter_payload_text(payload):
+        normalized = text.lower().replace("_", " ").replace("-", " ")
+        if (
+            "not ready" in normalized
+            or "not yet computed" in normalized
+            or "not computed" in normalized
+            or "not yet available" in normalized
+            or "compute to trigger" in normalized
+            or "analytics pending" in normalized
+        ):
+            return True
+    return False
+
+
+def _http_status_failure(
+    exc: BaseException,
+    *,
+    what: str,
+    backend_url: str | None,
+) -> dict[str, Any]:
+    response = getattr(exc, "response", None)
+    status = getattr(response, "status_code", None)
+    status = int(status) if isinstance(status, int) else None
+
+    if status == 401:
+        return _failure(
+            "Analytics authentication failed; configure valid Traigent credentials.",
+            code="authentication_failed",
+            http_status=status,
+            backend_url=backend_url,
+        )
+    if status == 403:
+        return _failure(
+            "Analytics request was forbidden by the backend; check project permissions "
+            "or whether a WAF/Cloudflare rule is blocking the request.",
+            code="forbidden",
+            http_status=status,
+            backend_url=backend_url,
+        )
+    if status == 404:
+        if _signals_not_ready(response):
+            return _failure(
+                f"The backend found the run, but {what} analytics are not ready yet.",
+                code="not_ready",
+                http_status=status,
+                backend_url=backend_url,
+            )
+        return _failure(
+            f"The requested {what} was not found on the configured backend.",
+            code="not_found",
+            http_status=status,
+            backend_url=backend_url,
+        )
+
+    return _failure(
+        f"Could not retrieve {what} from the backend.",
+        code="backend_unavailable",
+        http_status=status,
+        backend_url=backend_url,
+    )
 
 
 async def _call_backend(coro_factory: Any, *, what: str) -> dict[str, Any]:
@@ -94,6 +217,7 @@ async def _call_backend(coro_factory: Any, *, what: str) -> dict[str, Any]:
     from traigent.cloud.analytics_client import AnalyticsClientError
     from traigent.cloud.auth import InvalidCredentialsError
 
+    client = None
     try:
         client = await _new_analytics_client()
     except ImportError as exc:
@@ -102,6 +226,7 @@ async def _call_backend(coro_factory: Any, *, what: str) -> dict[str, Any]:
         logger.debug("Analytics %s authentication failed: %s", what, exc)
         return _auth_failure()
 
+    backend_url = _resolved_backend_url(client)
     try:
         async with client as reader:
             data = await coro_factory(reader)
@@ -109,10 +234,21 @@ async def _call_backend(coro_factory: Any, *, what: str) -> dict[str, Any]:
         return _failure(
             f"The backend returned a malformed {what} response.",
             code="malformed_response",
+            backend_url=backend_url,
         )
     except InvalidCredentialsError as exc:
         logger.debug("Analytics %s authentication failed: %s", what, exc)
-        return _auth_failure()
+        return _auth_failure(backend_url=backend_url)
+    except _HTTP_STATUS_ERRORS as exc:
+        logger.debug("Analytics %s request returned HTTP status", what, exc_info=True)
+        return _http_status_failure(exc, what=what, backend_url=backend_url)
+    except _HTTP_TRANSPORT_ERRORS as exc:
+        logger.debug("Analytics %s transport failed: %s", what, exc)
+        return _failure(
+            f"Could not retrieve {what} from the backend.",
+            code="backend_unavailable",
+            backend_url=backend_url,
+        )
     except Exception as exc:  # noqa: BLE001 - normalize all transport failures
         # Do not surface raw exception text: it can contain the backend URL,
         # auth header echoes, or response bodies. Log at debug for operators.
@@ -120,6 +256,7 @@ async def _call_backend(coro_factory: Any, *, what: str) -> dict[str, Any]:
         return _failure(
             f"Could not retrieve {what} from the backend.",
             code="backend_unavailable",
+            backend_url=backend_url,
         )
 
     return {"ok": True, what.replace(" ", "_"): data}
@@ -161,7 +298,7 @@ async def health_check_tool() -> dict[str, Any]:
 
 
 def _sanitize_url(url: str | None) -> str | None:
-    """Strip any userinfo (``user:pass@``) from a URL before returning it."""
+    """Strip userinfo and query material from a URL before returning it."""
     if not url:
         return url
     from urllib.parse import urlsplit, urlunsplit
@@ -175,7 +312,7 @@ def _sanitize_url(url: str | None) -> str | None:
         if parts.port is not None:
             host = f"{host}:{parts.port}"
         parts = parts._replace(netloc=host)
-    return urlunsplit(parts)
+    return urlunsplit(parts._replace(query="", fragment=""))
 
 
 def _mask_api_key(api_key: str | None) -> dict[str, Any]:

{traigent-0.18.0.dev0 → traigent-0.18.1.dev1}/traigent/api/agent_inference.py

@@ -36,6 +36,12 @@ if TYPE_CHECKING:
 logger = get_logger(__name__)
 
 
+__all__ = [
+    "build_agent_configuration",
+    "extract_parameter_agents",
+]
+
+
 def build_agent_configuration(
     configuration_space: dict[str, Any],
     explicit_agents: dict[str, AgentDefinition] | None = None,