traigent 0.18.1.dev8__tar.gz → 0.18.1.dev10__tar.gz

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

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

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

{traigent-0.18.1.dev8 → traigent-0.18.1.dev10}/traigent/cloud/backend_client.py

@@ -64,7 +64,7 @@ from traigent.cloud.privacy_operations import PrivacyOperations
 from traigent.cloud.session_operations import SessionOperations
 from traigent.cloud.session_types import SessionCreationResult
 from traigent.cloud.subset_selection import SmartSubsetSelector
-from traigent.cloud.trial_operations import TrialOperations
+from traigent.cloud.trial_operations import TrialOperations, TrialSlotResult
 from traigent.cloud.url_security import (
     CloudUrlUnreachableError,
     validate_cloud_base_url,
@@ -1879,16 +1879,15 @@ class BackendIntegratedClient:
             self._trial_ops.register_trial_start_sync(session_id, trial_id, config),
         )
 
-    async def request_trial_slot(self, session_id: str) -> str | None:
+    async def request_trial_slot(self, session_id: str) -> TrialSlotResult:
         """Acquire a backend-minted trial id (configuration_run) for a session.
         Delegates to trial_operations module.
 
         Returns:
-            The backend-minted trial id, or ``None`` when no slot could be
-            acquired (offline / transport unavailable / non-2xx / backend
-            declined). ``None`` never means "use a client id".
+            A neutral slot result: acquired backend trial id, explicit
+            optimization-complete signal, or unavailable/error.
         """
-        return cast(str | None, await self._trial_ops.request_trial_slot(session_id))
+        return await self._trial_ops.request_trial_slot(session_id)
 
     def _generate_trial_id(
         self,

{traigent-0.18.1.dev8 → traigent-0.18.1.dev10}/traigent/cloud/trial_operations.py

@@ -11,6 +11,7 @@ import concurrent.futures
 import hashlib
 import json
 import re
+from dataclasses import dataclass
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any
 
@@ -42,6 +43,30 @@ if TYPE_CHECKING:
 logger = get_logger(__name__)
 
 
+@dataclass(frozen=True)
+class TrialSlotResult:
+    """Neutral result for a backend trial-slot request."""
+
+    trial_id: str | None = None
+    optimization_complete: bool = False
+    reason: str | None = None
+
+    def __bool__(self) -> bool:
+        return bool(self.trial_id)
+
+    @classmethod
+    def acquired(cls, trial_id: str) -> "TrialSlotResult":
+        return cls(trial_id=trial_id)
+
+    @classmethod
+    def complete(cls, reason: str | None = None) -> "TrialSlotResult":
+        return cls(optimization_complete=True, reason=reason)
+
+    @classmethod
+    def unavailable(cls) -> "TrialSlotResult":
+        return cls()
+
+
 class TrialOperations:
     """Handles trial management operations."""
 
@@ -380,7 +405,7 @@ class TrialOperations:
     async def request_trial_slot(
         self,
         session_id: str,
-    ) -> str | None:
+    ) -> TrialSlotResult:
         """Acquire a BACKEND-minted trial id (configuration_run) for a session.
 
         The backend mints configuration_run ids only through its
@@ -392,25 +417,26 @@ class TrialOperations:
         and the backend's own suggested config is irrelevant to the SDK.
 
         Returns:
-            The backend-minted trial id, or ``None`` when no slot could be
-            acquired (offline mode, transport unavailable, non-2xx, or the
-            backend declined to suggest a further trial). ``None`` NEVER means
-            "use a client id" — callers fail closed on it (Rule 2: no fake
-            trial acknowledgment).
+            A neutral slot result. ``trial_id`` means a backend-minted slot was
+            acquired. ``optimization_complete`` means a successful next-trial
+            response explicitly returned ``should_continue=False`` without a
+            trial id. Any other no-slot/error condition returns an unavailable
+            result; callers still fail closed on it (Rule 2: no fake trial
+            acknowledgment).
         """
-        # Skip backend calls in offline mode — None lets callers distinguish
-        # "skipped" from "acquired" (Rule 2: no fake completion).
+        # Skip backend calls in offline mode — an unavailable result lets
+        # callers distinguish "skipped" from "acquired" (Rule 2: no fake completion).
         if is_backend_offline():
             logger.debug(
                 "Offline mode: skipping trial-slot request for session %s",
                 session_id,
             )
-            return None
+            return TrialSlotResult.unavailable()
         self._raise_if_backend_egress_disabled("get next trial")
 
         if not AIOHTTP_AVAILABLE:
             logger.warning("aiohttp not available, skipping trial-slot request")
-            return None
+            return TrialSlotResult.unavailable()
 
         try:
             headers = await self.client.auth_manager.augment_headers(
@@ -446,7 +472,21 @@ class TrialOperations:
                                 trial_id,
                                 session_id,
                             )
-                            return trial_id
+                            return TrialSlotResult.acquired(trial_id)
+                        if (
+                            isinstance(data, dict)
+                            and data.get("should_continue") is False
+                        ):
+                            reason = data.get("stop_reason") or data.get("reason")
+                            logger.info(
+                                "Backend next-trial completed optimization for session %s "
+                                "(reason=%s)",
+                                session_id,
+                                reason,
+                            )
+                            return TrialSlotResult.complete(
+                                str(reason) if reason else None
+                            )
                         logger.info(
                             "Backend next-trial returned no slot for session %s "
                             "(should_continue=%s)",
@@ -457,7 +497,7 @@ class TrialOperations:
                                 else None
                             ),
                         )
-                        return None
+                        return TrialSlotResult.unavailable()
                     if response.status == 403:
                         error_msg = await response.text()
                         self._log_ownership_forbidden(
@@ -466,26 +506,26 @@ class TrialOperations:
                             response.status,
                             error_msg,
                         )
-                        return None
+                        return TrialSlotResult.unavailable()
                     logger.warning(
                         "Failed to acquire trial slot for session %s: HTTP %s",
                         session_id,
                         response.status,
                     )
-                    return None
+                    return TrialSlotResult.unavailable()
         except Exception as exc:
             if is_backend_offline():
                 logger.debug(
                     "Offline mode: trial-slot request encountered %s; skipping",
                     exc,
                 )
-                return None
+                return TrialSlotResult.unavailable()
             logger.exception(
                 "Error requesting trial slot for session %s (%s)",
                 session_id,
                 self._describe_backend(),
             )
-            return None
+            return TrialSlotResult.unavailable()
 
     def _extract_measures_from_metrics(
         self, metrics: dict[str, Any]

{traigent-0.18.1.dev8 → traigent-0.18.1.dev10}/traigent/core/backend_session_manager.py

@@ -8,6 +8,7 @@ import asyncio
 import inspect
 import threading
 from collections.abc import Callable, Coroutine
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, cast
 
 from traigent._version import get_version
@@ -133,6 +134,27 @@ def _backend_disabled_label(reason: SessionCreationFailureReason | None) -> str:
     return "unknown"
 
 
+@dataclass(frozen=True)
+class BackendTrialSlotAcquisition:
+    """Core-local interpretation of a backend trial-slot request."""
+
+    trial_id: str | None = None
+    optimization_complete: bool = False
+    reason: str | None = None
+
+
+@dataclass(frozen=True)
+class BackendTrialSubmissionOutcome:
+    """Terminal submission outcome consumed by the orchestrator."""
+
+    optimization_complete: bool = False
+    reason: str | None = None
+
+    @classmethod
+    def complete(cls, reason: str | None = None) -> BackendTrialSubmissionOutcome:
+        return cls(optimization_complete=True, reason=reason)
+
+
 def _format_untracked_warning_block(
     result: SessionCreationResult,
     classification: SessionCreationFailureClassification,
@@ -940,7 +962,7 @@ class BackendSessionManager:
         session_id: str | None,
         dataset_name: str = "dataset",
         content_scores: dict[str, dict[int, float]] | None = None,
-    ) -> bool:
+    ) -> bool | BackendTrialSubmissionOutcome:
         """Submit trial to backend.
 
         Args:
@@ -951,7 +973,9 @@ class BackendSessionManager:
                 per-run features once at session creation.
 
         Returns:
-            True if submission succeeded
+            True if submission succeeded, False if skipped, or a terminal
+            optimization-complete outcome when the backend gracefully closed the
+            cloud run.
         """
         if self._egress_disabled() or not self._backend_client or not session_id:
             return False
@@ -990,12 +1014,14 @@ class BackendSessionManager:
             )
             return False
 
-        await self._log_trial_to_backend(
+        submission_outcome = await self._log_trial_to_backend(
             session_id=session_id,
             trial_result=trial_result,
             score=score,
             metadata=trial_metadata,
         )
+        if submission_outcome is not None and submission_outcome.optimization_complete:
+            return submission_outcome
 
         return True
 
@@ -1045,36 +1071,53 @@ class BackendSessionManager:
         """
         return (session_id, trial_id) in self._acknowledged_trials
 
+    @staticmethod
+    def _coerce_backend_trial_slot(slot: Any) -> BackendTrialSlotAcquisition:
+        """Normalize legacy string/None and structured slot results."""
+
+        if isinstance(slot, str) and slot:
+            return BackendTrialSlotAcquisition(trial_id=slot)
+        if getattr(slot, "optimization_complete", False) is True:
+            reason = getattr(slot, "reason", None)
+            return BackendTrialSlotAcquisition(
+                optimization_complete=True,
+                reason=str(reason) if reason else None,
+            )
+        trial_id = getattr(slot, "trial_id", None)
+        if isinstance(trial_id, str) and trial_id:
+            return BackendTrialSlotAcquisition(trial_id=trial_id)
+        return BackendTrialSlotAcquisition()
+
     async def _acquire_backend_trial_id(
         self, session_id: str, trial_result: TrialResult
-    ) -> str | None:
+    ) -> BackendTrialSlotAcquisition:
         """Acquire (once per started trial) a backend-minted trial id.
 
         Reuses a previously acquired backend id for the same client trial so
-        retries of submit_trial don't burn extra slots. Returns ``None`` when
-        the backend declined to mint a slot (offline / transport / non-2xx),
-        in which case the caller fails closed.
+        retries of submit_trial don't burn extra slots. Returns a structured
+        outcome so graceful backend completion is not collapsed into the genuine
+        no-slot/error path.
         """
         client = self._backend_client
         if self._egress_disabled() or client is None:
-            return None
+            return BackendTrialSlotAcquisition()
 
         client_trial_id = str(trial_result.trial_id)
         if (trial_result.metadata or {}).get("backend_trial_id_acquired"):
             self._started_trials.add((session_id, client_trial_id))
-            return client_trial_id
+            return BackendTrialSlotAcquisition(trial_id=client_trial_id)
         # If this trial already mapped to an acknowledged backend id, reuse it.
         for sid, bid in self._started_trials:
             if sid == session_id and bid == client_trial_id:
                 # client_trial_id already IS a backend id from a prior pass.
-                return client_trial_id
+                return BackendTrialSlotAcquisition(trial_id=client_trial_id)
 
         requester = getattr(client, "request_trial_slot", None)
         if not callable(requester):
-            return None
+            return BackendTrialSlotAcquisition()
         try:
             slot = requester(session_id)
-            backend_trial_id = await slot if inspect.isawaitable(slot) else slot
+            slot_result = await slot if inspect.isawaitable(slot) else slot
         except Exception as exc:
             logger.debug(
                 "Backend trial-slot request failed for session %s trial %s: %s",
@@ -1082,12 +1125,12 @@ class BackendSessionManager:
                 client_trial_id,
                 exc,
             )
-            return None
+            return BackendTrialSlotAcquisition()
 
-        if isinstance(backend_trial_id, str) and backend_trial_id:
-            self._started_trials.add((session_id, backend_trial_id))
-            return backend_trial_id
-        return None
+        acquisition = self._coerce_backend_trial_slot(slot_result)
+        if acquisition.trial_id:
+            self._started_trials.add((session_id, acquisition.trial_id))
+        return acquisition
 
     async def _log_trial_to_backend(
         self,
@@ -1095,14 +1138,14 @@ class BackendSessionManager:
         trial_result: TrialResult,
         score: float | None,
         metadata: dict[str, Any],
-    ) -> None:
+    ) -> BackendTrialSubmissionOutcome | None:
         """Submit trial metrics to backend when possible."""
 
         if self._egress_disabled() or not self._backend_client or not session_id:
-            return
+            return None
 
         if not self._backend_tracking_enabled:
-            return
+            return None
 
         sanitized_score = float(score) if score is not None else None
         metadata_payload = dict(metadata)
@@ -1122,7 +1165,7 @@ class BackendSessionManager:
                 session_id,
                 trial_result.trial_id,
             )
-            return
+            return None
 
         logger.debug(
             "Submitting trial %s for session %s",
@@ -1151,7 +1194,7 @@ class BackendSessionManager:
                 session_id,
                 trial_result.trial_id,
             )
-            return
+            return None
 
         # Build payload for backend session endpoint.
         metrics_payload: dict[str, Any] = dict(trial_result.metrics or {})
@@ -1194,9 +1237,17 @@ class BackendSessionManager:
             # "Trial ... not found in session". So acquire a backend slot and
             # rebind this trial to it BEFORE submitting. The optimizer still
             # owns the config; the slot is purely the backend's trial handle.
-            backend_trial_id = await self._acquire_backend_trial_id(
-                session_id, trial_result
-            )
+            acquisition = await self._acquire_backend_trial_id(session_id, trial_result)
+            if acquisition.optimization_complete:
+                logger.info(
+                    "Backend reported optimization complete for session %s while "
+                    "submitting client trial %s (reason=%s)",
+                    session_id,
+                    trial_result.trial_id,
+                    acquisition.reason,
+                )
+                return BackendTrialSubmissionOutcome.complete(acquisition.reason)
+            backend_trial_id = acquisition.trial_id
             if backend_trial_id is None:
                 # Fail closed: no acknowledged backend slot ⇒ NO submission and
                 # NO acknowledgment. The certified-selection report will then
@@ -1210,7 +1261,7 @@ class BackendSessionManager:
                     session_id,
                     trial_result.trial_id,
                 )
-                return
+                return None
             # Rebind in place: _best_trial_cached holds this same object, so the
             # incumbent's trial_id becomes the backend id the report needs.
             trial_result.trial_id = backend_trial_id

{traigent-0.18.1.dev8 → traigent-0.18.1.dev10}/traigent/core/orchestrator.py

@@ -101,6 +101,7 @@ from traigent.core.workflow_trace_manager import WorkflowTraceManager
 from traigent.evaluators.base import BaseEvaluator, Dataset
 from traigent.metrics.registry import clone_registry
 from traigent.optimizers.base import BaseOptimizer
+from traigent.optimizers.interactive_optimizer import CloudBrainOptimizationComplete
 from traigent.tvl.promotion_gate import PromotionGate
 from traigent.utils.callbacks import CallbackManager, OptimizationCallback, ProgressInfo
 from traigent.utils.env_config import (  # noqa: F401
@@ -1378,6 +1379,7 @@ class OptimizationOrchestrator:
         *,
         log_on_success: bool,
         permit: Permit | None = None,
+        submit_to_backend: bool = True,
     ) -> int:
         """Update orchestrator state after a single trial completes.
 
@@ -1443,13 +1445,14 @@ class OptimizationOrchestrator:
             # on _consumed_examples during parallel trial execution
             self._register_examples_attempted(trial_result)
 
-        if self.backend_client and session_id:
+        submission_outcome: Any = None
+        if submit_to_backend and self.backend_client and session_id:
             pre_submit_trial_id = (
                 str(trial_result.trial_id)
                 if getattr(trial_result, "trial_id", None) is not None
                 else None
             )
-            await self.backend_session_manager.submit_trial(
+            submission_outcome = await self.backend_session_manager.submit_trial(
                 trial_result=trial_result,
                 session_id=session_id,
                 dataset_name=getattr(self, "_dataset_name", "dataset"),
@@ -1487,6 +1490,12 @@ class OptimizationOrchestrator:
         if should_log:
             self._log_progress(new_count)
 
+        if getattr(submission_outcome, "optimization_complete", False) is True:
+            reason = getattr(submission_outcome, "reason", None)
+            raise CloudBrainOptimizationComplete(
+                str(reason) if reason else "cloud brain completed optimization"
+            )
+
         return new_count
 
     def _calculate_parallel_batch_caps(
@@ -1838,6 +1847,9 @@ class OptimizationOrchestrator:
         - Exceptions (due to return_exceptions=True in gather)
         - None for trials cancelled due to cost limit
         """
+        terminal_completion: CloudBrainOptimizationComplete | None = None
+        submit_to_backend = True
+
         for batch_offset, (config, permitted_result, optuna_id) in enumerate(
             zip(scheduled_configs, results, scheduled_optuna_ids, strict=False)
         ):
@@ -1895,7 +1907,13 @@ class OptimizationOrchestrator:
                     optuna_trial_id=optuna_id,
                     log_on_success=False,
                     permit=permit,
+                    submit_to_backend=submit_to_backend,
                 )
+            except CloudBrainOptimizationComplete as complete:
+                if terminal_completion is None:
+                    terminal_completion = complete
+                submit_to_backend = False
+                trial_count = len(self._trials)
             except Exception:
                 # Release permit on any exception to prevent stranding
                 # (only if permit is still active - wasn't already released)
@@ -1906,6 +1924,8 @@ class OptimizationOrchestrator:
                         permit.id,
                     )
                 raise
+        if terminal_completion is not None:
+            raise terminal_completion
         return trial_count
 
     def _apply_cap_and_prevent_excess(
@@ -2588,6 +2608,10 @@ class OptimizationOrchestrator:
                 self._stop_reason = "vendor_error"
                 return trial_count, "break"
             return trial_count, "continue"  # User chose to resume
+        except CloudBrainOptimizationComplete as complete:
+            self._stop_reason = cast(StopReason, complete.stop_reason)
+            logger.info("Cloud brain completed optimization: %s", complete.reason)
+            return len(self._trials), "break"
 
     @staticmethod
     def _vendor_retry_settings() -> tuple[int, float]:

{traigent-0.18.1.dev8 → traigent-0.18.1.dev10}/traigent/core/trial_lifecycle.py

@@ -431,11 +431,7 @@ class TrialLifecycle:
                     lambda: frozenset(),
                 )(),
             )
-            if isinstance(backend_trial_id, str) and backend_trial_id:
-                metadata = dict(result.metadata or {})
-                metadata["backend_trial_id_acquired"] = True
-                metadata["backend_trial_id_source"] = "cloud_brain"
-                result.metadata = metadata
+            self._mark_backend_trial_id_acquired(result, backend_trial_id)
             self._apply_budget_metadata(result, closure, budget_exhausted)
             self._apply_effectuation_metadata(result, func)
 
@@ -463,6 +459,7 @@ class TrialLifecycle:
                 prune_error,
                 is_pruned=True,
             )
+            self._mark_backend_trial_id_acquired(result, backend_trial_id)
             self._apply_effectuation_metadata(result, func)
             record_trial_result(span, status="pruned", error=str(prune_error))
             end_time = time.time()
@@ -479,6 +476,7 @@ class TrialLifecycle:
                 optuna_trial_id,
                 constraint_error,
             )
+            self._mark_backend_trial_id_acquired(result, backend_trial_id)
             self._apply_effectuation_metadata(result, func)
             record_trial_result(span, status="failed", error=str(constraint_error))
             end_time = time.time()
@@ -523,6 +521,7 @@ class TrialLifecycle:
                 optuna_trial_id,
                 exc,
             )
+            self._mark_backend_trial_id_acquired(result, backend_trial_id)
             self._apply_effectuation_metadata(result, func)
             record_trial_result(span, status="failed", error=str(exc))
             end_time = time.time()
@@ -533,6 +532,18 @@ class TrialLifecycle:
             if lease is not None and closure is None:
                 closure = self._finalize_budget_lease(lease)
 
+    @staticmethod
+    def _mark_backend_trial_id_acquired(
+        result: TrialResult,
+        backend_trial_id: str | None,
+    ) -> None:
+        if not isinstance(backend_trial_id, str) or not backend_trial_id:
+            return
+        metadata = dict(result.metadata or {})
+        metadata["backend_trial_id_acquired"] = True
+        metadata["backend_trial_id_source"] = "cloud_brain"
+        result.metadata = metadata
+
     def _apply_effectuation_metadata(
         self,
         result: TrialResult,