traigent 0.18.1.dev3__tar.gz → 0.18.1.dev4__tar.gz

{traigent-0.18.1.dev3/traigent.egg-info → traigent-0.18.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traigent
-Version: 0.18.1.dev3
+Version: 0.18.1.dev4
 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

{traigent-0.18.1.dev3 → traigent-0.18.1.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traigent"
-version = "0.18.1.dev3"
+version = "0.18.1.dev4"
 authors = [
     {name = "Traigent Team", email = "opensource@traigent.ai"},
 ]

{traigent-0.18.1.dev3 → traigent-0.18.1.dev4}/traigent/cloud/analytics_client.py

@@ -143,6 +143,32 @@ _EXAMPLE_INSIGHT_RECOMMENDED_ACTIONS = frozenset(
     }
 )
 
+# Allowlists for nested aggregate fields in get_example_insights() — derived from
+# BackendAnalyticsClient's RunExampleInsights Pydantic schema (ExampleInsightsSummary,
+# ExampleInsightsCohort, ExampleInsightsRecommendation, ExampleInsightsRedactions in
+# shared_infrastructure/schemas/run_analytics.py) and from the extended fixture in
+# tests/unit/cloud/test_analytics_client.py (which documents count keys that the backend
+# schema will expose in subsequent releases). All fields are coarse-aggregated, backend-
+# redacted, and contain no proprietary per-example signals.
+_EXAMPLE_INSIGHTS_SUMMARY_KEYS: frozenset[str] = frozenset(
+    {
+        "example_count",
+        "weak_example_count",
+        "unstable_example_count",
+        "suspicious_example_count",
+        "notable_example_count",
+        "stable_example_count",
+        "dataset_quality",
+    }
+)
+_EXAMPLE_INSIGHTS_COHORT_KEYS: frozenset[str] = frozenset(
+    {"kind", "count", "impact", "safe_example_refs", "recommendation"}
+)
+_EXAMPLE_INSIGHTS_RECOMMENDATION_KEYS: frozenset[str] = frozenset({"action", "reason"})
+_EXAMPLE_INSIGHTS_REDACTIONS_KEYS: frozenset[str] = frozenset(
+    {"raw_proprietary_signals_hidden", "raw_prompt_text_hidden_by_default"}
+)
+
 
 class AnalyticsClientError(RuntimeError):
     """Raised when the analytics backend returns a malformed response.
@@ -237,6 +263,21 @@ def _project_example_insight_row(row: Any, *, index: int) -> dict[str, Any]:
     }
 
 
+def _project_aggregate(data: Any, keys: frozenset[str], *, what: str) -> dict[str, Any]:
+    """Project a mapping to its known-safe keys, dropping unknown/raw keys.
+
+    Unknown nested keys can carry proprietary signals or raw backend state.
+    This function is the nested-aggregate counterpart of the per-row construction
+    in :func:`_project_example_insight_row`: both rebuild output by allowlist so
+    nothing unknown can pass through regardless of what the backend sends.
+    """
+    if not isinstance(data, dict):
+        raise AnalyticsClientError(
+            f"Malformed example insights response: {what} must be an object."
+        )
+    return {k: v for k, v in data.items() if k in keys}
+
+
 def _quote_segment(value: str, *, field: str) -> str:
     """URL-encode a path segment, rejecting empty values up front.
 
@@ -666,18 +707,50 @@ class BackendAnalyticsClient:
                 "Malformed example insights response: example_rows must contain "
                 "at most 100 rows."
             )
+        cohorts_raw = payload["cohorts"]
+        if not isinstance(cohorts_raw, list):
+            raise AnalyticsClientError(
+                "Malformed example insights response: cohorts must be a list."
+            )
+        recommendations_raw = payload["recommendations"]
+        if not isinstance(recommendations_raw, list):
+            raise AnalyticsClientError(
+                "Malformed example insights response: recommendations must be a list."
+            )
 
         return {
             "run_id": payload["run_id"],
             "privacy_mode": payload["privacy_mode"],
-            "summary": payload["summary"],
+            "summary": _project_aggregate(
+                payload["summary"],
+                _EXAMPLE_INSIGHTS_SUMMARY_KEYS,
+                what="summary",
+            ),
             "example_rows": [
                 _project_example_insight_row(row, index=index)
                 for index, row in enumerate(rows)
             ],
-            "cohorts": payload["cohorts"],
-            "recommendations": payload["recommendations"],
-            "redactions": payload["redactions"],
+            "cohorts": [
+                _project_aggregate(
+                    cohort,
+                    _EXAMPLE_INSIGHTS_COHORT_KEYS,
+                    what=f"cohorts[{i}]",
+                )
+                for i, cohort in enumerate(cohorts_raw)
+            ],
+            "recommendations": [
+                _project_aggregate(
+                    rec,
+                    _EXAMPLE_INSIGHTS_RECOMMENDATION_KEYS,
+                    what=f"recommendations[{i}]",
+                )
+                for i, rec in enumerate(recommendations_raw)
+            ],
+            "redactions": _project_aggregate(
+                payload["redactions"],
+                _EXAMPLE_INSIGHTS_REDACTIONS_KEYS,
+                what="redactions",
+            ),
         }
 
 

{traigent-0.18.1.dev3 → traigent-0.18.1.dev4}/traigent/cloud/service.py

@@ -94,6 +94,40 @@ class TraigentCloudService:
         if not request.configuration_space:
             raise ValidationException("configuration_space must not be empty")
 
+        # Detect boolean values before any network or compute work.
+        # bool is a subclass of int in Python; use type(v) is bool so that
+        # real ints/floats (including 0/1) are NOT mistakenly rejected.
+        # Catches booleans in ALL supported value shapes:
+        #   - scalar bool: {"flag": True}
+        #   - list/tuple of values: {"flag": [True, False]}
+        #   - typed param dict: {"flag": {"type": "categorical", "choices": [True, False]}}
+        def _cs_value_contains_bool(value: Any) -> bool:
+            if type(value) is bool:
+                return True
+            if isinstance(value, (list, tuple)):
+                return any(type(v) is bool for v in value)
+            if isinstance(value, dict):
+                for _key in ("choices", "values"):
+                    seq = value.get(_key)
+                    if isinstance(seq, (list, tuple)) and any(
+                        type(v) is bool for v in seq
+                    ):
+                        return True
+            return False
+
+        _bool_knobs = [
+            key
+            for key, value in request.configuration_space.items()
+            if _cs_value_contains_bool(value)
+        ]
+        if _bool_knobs:
+            _field_refs = ", ".join(f'"{k}"' for k in _bool_knobs)
+            raise ValidationException(
+                f"configuration_space[{_field_refs}]: boolean values are not "
+                f"supported by the cloud session API — encode as strings "
+                f'(e.g. "true"/"false") or 0/1'
+            )
+
         validate_or_raise(
             CoreValidators.validate_list(
                 request.objectives,

{traigent-0.18.1.dev3 → traigent-0.18.1.dev4}/traigent/cloud/session_operations.py

@@ -71,6 +71,68 @@ def _get_session_creation_failure_detail(
     return None
 
 
+# Transient signals: the SDK could not REACH/validate the backend (the auth
+# layer fails closed on these for safety, but the run should still degrade
+# gracefully as it did before, not hard-fail).
+_AUTH_TRANSIENT_MARKERS = (
+    "timed out",
+    "timeout",
+    "transport error",
+    "rate limited",
+    "temporarily unavailable",
+    "service unavailable",
+    "connection",
+)
+# Definitive signals: the backend REJECTED the credential (user-actionable;
+# fix the key). Only these fail closed.
+_AUTH_REJECTION_MARKERS = (
+    "unauthorized",
+    "invalid api key",
+    "invalid_api_key",
+    "api_key_validation_failed",
+    "reported key invalid",
+    "revoked",
+    "forbidden",
+    "expired",
+    "permission",
+)
+
+
+def _is_definitive_auth_rejection(exc: Exception) -> bool:
+    """True only when an auth failure is a DEFINITIVE credential rejection.
+
+    A configured key that the backend rejected (invalid / revoked / expired /
+    unauthorized / forbidden — typically 401/403) is user-actionable and must
+    fail closed. A transient inability to validate the key (timeout / transport
+    error / 5xx / 429 during ``/keys/validate``) is NOT a rejection: the auth
+    layer fails closed on it for safety, but the optimization run should still
+    degrade gracefully (as before), not hard-fail. Ambiguous errors default to
+    NOT a rejection, preserving the prior resilient fallback.
+    """
+    # Primary source: the real session API attaches the HTTP status on the
+    # structured failure detail (api_operations._handle_session_error maps a
+    # 401/403 to AuthenticationError with exc.session_creation_failure). A bare
+    # exc.status_code is a secondary source.
+    detail = getattr(exc, "session_creation_failure", None)
+    detail_status = getattr(detail, "status_code", None)
+    if isinstance(detail_status, int) and detail_status in (401, 403):
+        return True
+    if isinstance(detail_status, int) and (
+        detail_status == 429 or detail_status >= 500
+    ):
+        return False
+    status = getattr(exc, "status_code", None)
+    if isinstance(status, int):
+        if status in (401, 403):
+            return True
+        if status == 429 or status >= 500:
+            return False
+    msg = str(exc).lower()
+    if any(marker in msg for marker in _AUTH_TRANSIENT_MARKERS):
+        return False
+    return any(marker in msg for marker in _AUTH_REJECTION_MARKERS)
+
+
 class SessionOperations:
     """Handles session management operations."""
 
@@ -97,6 +159,63 @@ class SessionOperations:
         """Validate that an integer is positive."""
         validate_or_raise(CoreValidators.validate_positive_int(value, field_name))
 
+    @staticmethod
+    def _config_value_contains_bool(value: Any) -> bool:
+        """Return True if a configuration_space value contains boolean(s).
+
+        Handles all supported parameter shapes:
+          - scalar bool: ``True`` / ``False``
+          - list/tuple of values containing a bool: ``[True, False]``
+          - typed/structured dict whose ``choices`` or ``values`` list contains a
+            bool: ``{"type": "categorical", "choices": [True, False]}``
+
+        Note: ``bool`` is a subclass of ``int`` in Python.  We use
+        ``type(v) is bool`` so plain ints/floats (including 0/1) are NOT
+        rejected — only literal ``True``/``False`` values.
+        """
+        if type(value) is bool:
+            return True
+        if isinstance(value, (list, tuple)):
+            return any(type(v) is bool for v in value)
+        if isinstance(value, dict):
+            for key in ("choices", "values"):
+                seq = value.get(key)
+                if isinstance(seq, (list, tuple)) and any(type(v) is bool for v in seq):
+                    return True
+        return False
+
+    @staticmethod
+    def _validate_configuration_space_no_bools(
+        space: dict[str, Any], field_name: str
+    ) -> None:
+        """Raise ValidationException when a parameter contains boolean values.
+
+        The cloud session API rejects boolean knobs with a generic HTTP 400
+        VALIDATION_ERROR that names no field.  Catching the problem client-side
+        gives a clear, actionable error before any network round-trip.
+
+        Catches booleans in ALL supported configuration_space value shapes:
+          - scalar bool: ``{"flag": True}``
+          - list/tuple of values: ``{"flag": [True, False]}``
+          - typed param dict: ``{"flag": {"type": "categorical", "choices": [True, False]}}``
+
+        Note: ``bool`` is a subclass of ``int`` in Python.  We use
+        ``type(v) is bool`` (not ``isinstance``) so plain ints and floats such
+        as 0/1 are NOT rejected — only literal ``True``/``False`` values.
+        """
+        offending = [
+            key
+            for key, value in space.items()
+            if SessionOperations._config_value_contains_bool(value)
+        ]
+        if offending:
+            field_refs = ", ".join(f'"{k}"' for k in offending)
+            raise ValidationException(
+                f"{field_name}[{field_refs}]: boolean values are not supported "
+                f"by the cloud session API — encode as strings "
+                f'(e.g. "true"/"false") or 0/1'
+            )
+
     def _raise_if_backend_egress_disabled(self, operation: str) -> None:
         """Fail closed before any backend HTTP request."""
 
@@ -321,6 +440,54 @@ class SessionOperations:
                 storage_e,
             )
 
+    def _auth_fallback_result(
+        self,
+        exc: Exception,
+        fallback_id: str,
+        detail: str,
+        failure_response: SessionCreationFailureDetail | None,
+        function_name: str,
+        intends_cloud_egress: bool,
+    ) -> SessionCreationResult:
+        """Build the fallback result for a non-fail-loud AuthenticationError.
+
+        A run that INTENDS cloud egress but hit a non-definitive auth failure
+        (could-not-validate / transient) takes the UNREACHABLE contract: degrade
+        to LOCAL but FLAG it (degraded=True + SESSION_FAILED + WARN) so it is
+        never mistaken for a managed run. A LOCAL-routed run only ever wanted
+        OPTIONAL backend tracking, so a rejected/invalid key is irrelevant: it
+        continues untracked locally (degraded=False) — intentional local
+        execution, NOT a downgrade (#1421).
+        """
+        if intends_cloud_egress:
+            logger.warning(
+                "Managed session creation failed (could not validate credentials "
+                "— backend unreachable) for '%s'; degrading to LOCAL execution — "
+                "results are NOT tracked on the backend (set offline=True to make "
+                "this explicit): %s",
+                function_name,
+                exc,
+            )
+            return SessionCreationResult.fallback(
+                session_id=fallback_id,
+                reason=SessionCreationFailureReason.SESSION_FAILED,
+                detail=detail,
+                failure_response=failure_response,
+                degraded=True,
+            )
+        logger.warning(
+            "Backend tracking unavailable (auth) for local run '%s'; continuing "
+            "untracked locally: %s",
+            function_name,
+            exc,
+        )
+        return SessionCreationResult.fallback(
+            session_id=fallback_id,
+            reason=SessionCreationFailureReason.AUTH,
+            detail=detail,
+            failure_response=failure_response,
+        )
+
     def create_session(
         self,
         function_name: str,
@@ -350,6 +517,7 @@ class SessionOperations:
         """
         self._validate_non_empty_string(function_name, "function_name")
         self._validate_mapping(search_space, "search_space")
+        self._validate_configuration_space_no_bools(search_space, "configuration_space")
         self._validate_non_empty_string(optimization_goal, "optimization_goal")
         if metadata is not None and not isinstance(metadata, dict):
             raise ValidationException("metadata must be a dictionary if provided")
@@ -361,7 +529,32 @@ class SessionOperations:
         # misconfiguration, and old-BE typed rejection as success.
         governed = bool(promotion_policy or tvl_governance)
 
+        # Does this run actually INTEND cloud egress (managed / auto-cloud)? The
+        # backend session manager sets this from the runtime-resolved execution
+        # policy before calling us (mirrors the existing ``no_egress`` flag). A
+        # LOCAL-routed run (algorithm grid/random, offline, or runtime-resolved
+        # -to-local) creates a backend session only for OPTIONAL tracking — a
+        # configured-but-invalid/rejected key is irrelevant to it and must NOT
+        # hard-fail the local optimization. Default True keeps fail-closed for
+        # direct callers that do not declare intent. (#1421 regression.)
+        intends_cloud_egress = bool(getattr(self.client, "cloud_egress_intent", True))
+
         def _must_fail_loud(exc: Exception) -> bool:
+            # A DEFINITIVELY rejected credential (invalid / revoked / expired /
+            # unauthorized — a key WAS configured; the no-key path returns
+            # NO_API_KEY before any HTTP) is a user-actionable error on a run
+            # that INTENDS cloud egress: silently degrading such a managed run
+            # to a local/anonymous one would change execution semantics (managed
+            # Bayesian -> local search), drop the backend/billing/governance
+            # record, and present the degraded run as success — so fail closed.
+            # On a LOCAL-routed run the same rejected key is irrelevant (zero
+            # cloud egress), so do NOT fail loud. A *transient* failure to
+            # reach/validate the backend is never a rejection and still degrades
+            # gracefully (see _is_definitive_auth_rejection).
+            if isinstance(exc, AuthenticationError):
+                return governed or (
+                    intends_cloud_egress and _is_definitive_auth_rejection(exc)
+                )
             return governed or isinstance(
                 exc, (CloudEgressBlockedError, SessionContractError)
             )
@@ -578,27 +771,40 @@ class SessionOperations:
                 await self._reset_client_session("create_session auth_failure")
                 if _must_fail_loud(e):
                     raise
-                logger.warning("Backend auth failed for '%s': %s", function_name, e)
                 failure_response = _get_session_creation_failure_detail(e)
                 fallback_id = self._create_local_fallback_session(
                     function_name, search_space, optimization_goal, metadata
                 )
-                return SessionCreationResult.fallback(
-                    session_id=fallback_id,
-                    reason=SessionCreationFailureReason.AUTH,
-                    detail=(
-                        failure_response.one_line_summary()
-                        if failure_response
-                        else str(e)[:200]
-                    ),
-                    failure_response=failure_response,
+                detail = (
+                    failure_response.one_line_summary()
+                    if failure_response
+                    else str(e)[:200]
+                )
+                return self._auth_fallback_result(
+                    e,
+                    fallback_id,
+                    detail,
+                    failure_response,
+                    function_name,
+                    intends_cloud_egress,
                 )
 
             except (TimeoutError, CloudServiceError, OSError) as e:
                 await self._reset_client_session("create_session fallback")
                 if _must_fail_loud(e):
                     raise
-                logger.debug("Backend unavailable for '%s': %s", function_name, e)
+                # A configured key intended a managed/cloud run, but the backend
+                # was unreachable. We degrade to LOCAL execution for resilience —
+                # but this is a DOWNGRADE (managed search/tracking is lost), so
+                # surface it at WARNING and flag degraded=True on the result so a
+                # caller never mistakes the local run for a managed one.
+                logger.warning(
+                    "Managed session creation failed (backend unreachable) for "
+                    "'%s'; degrading to LOCAL execution — results are NOT tracked "
+                    "on the backend (set offline=True to make this explicit): %s",
+                    function_name,
+                    e,
+                )
                 failure_response = _get_session_creation_failure_detail(e)
                 fallback_id = self._create_local_fallback_session(
                     function_name, search_space, optimization_goal, metadata
@@ -616,6 +822,7 @@ class SessionOperations:
                     typed_legacy_session_create_400=bool(
                         getattr(e, "typed_legacy_session_create_400", False)
                     ),
+                    degraded=True,
                 )
 
         # Run async method in sync context
@@ -644,39 +851,41 @@ class SessionOperations:
         except AuthenticationError as exc:
             if _must_fail_loud(exc):
                 raise
-            # Issue #1373 (the "outer create_session swallow"): an auth/scope
-            # failure that ESCAPES _create_session_async (e.g. from the
-            # has_api_key preflight, or the async-runner machinery) on a
-            # non-governed run must NOT fall to debug-only — a failed publish
-            # would be invisible at the default log level. Mirror the inner
-            # sibling (~:573) and surface at WARNING. The two sites are
-            # mutually exclusive per failure (a single AuthenticationError is
-            # caught by exactly one handler), so this does not double-log.
-            logger.warning(
-                "Backend auth failed for '%s': %s",
-                function_name,
-                exc,
-            )
+            # Issue #1373 "outer create_session swallow": an auth failure that
+            # ESCAPES _create_session_async (e.g. the has_api_key preflight or
+            # the async-runner machinery). A DEFINITIVE rejection on a cloud-
+            # intended run fails loud above. Reaching here is a non-definitive
+            # auth failure OR a LOCAL-routed run — both handled by the shared
+            # helper (cloud-intent: degrade+flag; local: continue untracked).
+            # The two auth sites are mutually exclusive per failure.
             failure_response = _get_session_creation_failure_detail(exc)
             fallback_id = self._create_local_fallback_session(
                 function_name, search_space, optimization_goal, metadata
             )
-            return SessionCreationResult.fallback(
-                session_id=fallback_id,
-                reason=SessionCreationFailureReason.AUTH,
-                detail=(
-                    failure_response.one_line_summary()
-                    if failure_response
-                    else str(exc)[:200]
-                ),
-                failure_response=failure_response,
+            detail = (
+                failure_response.one_line_summary()
+                if failure_response
+                else str(exc)[:200]
+            )
+            return self._auth_fallback_result(
+                exc,
+                fallback_id,
+                detail,
+                failure_response,
+                function_name,
+                intends_cloud_egress,
             )
 
         except (TimeoutError, CloudServiceError, OSError) as exc:
             if _must_fail_loud(exc):
                 raise
-            logger.debug(
-                "Error in create_session for function '%s': %s",
+            # Backend unreachable on the outer path — same downgrade semantics as
+            # the inner sibling: WARN + flag degraded so the local run is never
+            # mistaken for a managed one.
+            logger.warning(
+                "Managed session creation failed (backend unreachable) for '%s'; "
+                "degrading to LOCAL execution — results are NOT tracked on the "
+                "backend (set offline=True to make this explicit): %s",
                 function_name,
                 exc,
             )
@@ -694,6 +903,7 @@ class SessionOperations:
                 reason=SessionCreationFailureReason.SESSION_FAILED,
                 detail=detail,
                 failure_response=failure_response,
+                degraded=True,
             )
 
         except Exception as exc:
@@ -703,8 +913,11 @@ class SessionOperations:
             # governed/contract failures, which must stay loud.
             if _must_fail_loud(exc):
                 raise
-            logger.debug(
-                "Unexpected error in create_session for function '%s': %s",
+            # An unexpected error that degrades a managed run to local is still a
+            # downgrade — surface at WARNING and flag degraded (was debug-only).
+            logger.warning(
+                "Unexpected error in create_session for '%s'; degrading to LOCAL "
+                "execution — results are NOT tracked on the backend: %s",
                 function_name,
                 exc,
             )
@@ -715,6 +928,7 @@ class SessionOperations:
                 session_id=fallback_id,
                 reason=SessionCreationFailureReason.SESSION_FAILED,
                 detail=str(exc)[:200],
+                degraded=True,
             )
 
     async def create_hybrid_session(

{traigent-0.18.1.dev3 → traigent-0.18.1.dev4}/traigent/config/api_keys.py

@@ -62,12 +62,21 @@ class APIKeyManager:
             "openai": "OPENAI_API_KEY",
             "anthropic": "ANTHROPIC_API_KEY",
             "cohere": "COHERE_API_KEY",
-            "huggingface": "HF_API_KEY",
+            # HuggingFace: native HF_TOKEN first; HF_API_KEY kept for back-compat
+            "huggingface": "HF_TOKEN",
         }
 
         # Check environment first (most secure)
         if provider in env_names:
-            env_key = os.getenv(env_names[provider])
+            if provider == "huggingface":
+                # Native-first alias chain: HF_TOKEN -> HUGGING_FACE_HUB_TOKEN -> HF_API_KEY
+                env_key = (
+                    os.getenv("HF_TOKEN")
+                    or os.getenv("HUGGING_FACE_HUB_TOKEN")
+                    or os.getenv("HF_API_KEY")
+                )
+            else:
+                env_key = os.getenv(env_names[provider])
             if env_key:
                 return env_key
 

{traigent-0.18.1.dev3 → traigent-0.18.1.dev4}/traigent/core/backend_session_manager.py

@@ -760,6 +760,17 @@ class BackendSessionManager:
             if slug_hash:
                 portal_name = f"{portal_name} ({slug_hash})"
 
+            # Tell create_session whether this run actually INTENDS cloud egress
+            # (managed / auto-cloud) vs. a LOCAL-routed run (grid/random/offline/
+            # runtime-resolved-to-local) that only wants OPTIONAL backend
+            # tracking. A configured-but-invalid/rejected key must fail closed
+            # for the former but must NOT hard-fail the latter (#1421). Mirrors
+            # the existing ``no_egress`` flag set on the same client.
+            _policy = policy_from_config(self._traigent_config)
+            self._backend_client.cloud_egress_intent = bool(
+                policy_requires_cloud(_policy) or policy_is_cloud_brain(_policy)
+            )
+
             raw_result = self._backend_client.create_session(
                 function_name=portal_name,
                 search_space=getattr(self._optimizer, "config_space", {}),
@@ -1447,9 +1458,8 @@ class BackendSessionManager:
             result.metadata.get("statistical_significance") if result.metadata else None
         )
         if stat_sig:
-            summary_stats_with_aggregation["metadata"]["statistical_significance"] = (
-                stat_sig
-            )
+            agg_meta = summary_stats_with_aggregation["metadata"]
+            agg_meta["statistical_significance"] = stat_sig
 
         try:
             successful_trials = len([t for t in result.trials if t.is_successful])

{traigent-0.18.1.dev3 → traigent-0.18.1.dev4}/traigent/core/session_types.py

@@ -115,6 +115,16 @@ class SessionCreationResult:
     project_id: str | None = None
     tenant_id: str | None = None
     typed_legacy_session_create_400: bool = False
+    # Execution-path transparency (so a caller never mistakes a local run for a
+    # managed/cloud one). ``execution_path`` is "connected" for a real backend
+    # session and "local_fallback" for any local result. ``backend_fallback`` is
+    # True whenever the run is local. ``degraded`` is True ONLY when the user
+    # intended a managed/cloud run but the backend was unreachable and we fell
+    # back to local — it stays False for intentional local execution (offline
+    # mode / no API key), which is a deliberate configuration, not a downgrade.
+    execution_path: str | None = None
+    backend_fallback: bool = False
+    degraded: bool = False
 
     def __str__(self) -> str:
         """Return the session ID string for backwards compatibility.
@@ -145,6 +155,9 @@ class SessionCreationResult:
             backend_connected=True,
             project_id=project_id,
             tenant_id=tenant_id,
+            execution_path="connected",
+            backend_fallback=False,
+            degraded=False,
         )
 
     @classmethod
@@ -155,8 +168,15 @@ class SessionCreationResult:
         detail: str | None = None,
         failure_response: SessionCreationFailureDetail | None = None,
         typed_legacy_session_create_400: bool = False,
+        degraded: bool = False,
     ) -> SessionCreationResult:
-        """Factory for a local-fallback session after backend failure."""
+        """Factory for a local-fallback session after backend failure.
+
+        ``degraded`` must be set True by callers where the user intended a
+        managed/cloud run but the backend was unreachable (an unintended
+        downgrade); it stays False for intentional local execution (offline
+        mode / no API key configured).
+        """
         return cls(
             session_id=session_id,
             backend_connected=False,
@@ -164,4 +184,7 @@ class SessionCreationResult:
             failure_detail=detail,
             failure_response=failure_response,
             typed_legacy_session_create_400=typed_legacy_session_create_400,
+            execution_path="local_fallback",
+            backend_fallback=True,
+            degraded=degraded,
         )