traigent 0.18.1.dev4__tar.gz → 0.18.1.dev6__tar.gz

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

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

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

{traigent-0.18.1.dev4 → traigent-0.18.1.dev6}/traigent/api/decorators.py

@@ -43,6 +43,7 @@ Examples:
 from __future__ import annotations
 
 import inspect
+import os
 from collections.abc import Callable, Collection, Mapping
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -2011,6 +2012,79 @@ def _suggest_detected_tvars(
         return None
 
 
+def _build_default_experiment_name(
+    func_name: str,
+    resolved_schema: ObjectiveSchema | None,
+    resolved_configuration_space: dict[str, Any] | None,
+    *,
+    max_knobs: int = 4,
+    max_total_length: int = 120,
+) -> str:
+    """Build a self-describing default experiment name when none is provided.
+
+    Combines the function name, objective names, and tuned-variable (knob) names
+    into a concise, deterministic, human-meaningful string.  Format::
+
+        <func_name>[<obj1>,<obj2>,...][<knob1>,<knob2>,...]
+
+    Args:
+        func_name: The decorated function's ``__name__``.
+        resolved_schema: Resolved objective schema (from ``_resolve_objective_schema``).
+        resolved_configuration_space: Normalized configuration-space dict whose keys
+            are the tuned-variable names.
+        max_knobs: Maximum number of knob names to display before appending ``,...``.
+        max_total_length: Hard cap on the final string length (excess is truncated).
+
+    Returns:
+        A deterministic, human-readable default experiment name.
+    """
+    # Build the objective suffix — always preserved in the output.
+    obj_suffix = ""
+    if resolved_schema is not None:
+        obj_names = [obj.name for obj in resolved_schema.objectives]
+        obj_suffix = f"[{','.join(obj_names)}]"
+
+    # Build the knob suffix; cap list length to avoid excessively long names.
+    knob_suffix = ""
+    if resolved_configuration_space:
+        knob_names = list(resolved_configuration_space.keys())
+        if len(knob_names) > max_knobs:
+            displayed = knob_names[:max_knobs]
+            knob_suffix = f"[{','.join(displayed)},...]"
+        else:
+            knob_suffix = f"[{','.join(knob_names)}]"
+
+    # Invariant: the objectives + knob sections are the self-describing payload
+    # and must never be sacrificed to the length cap.  Truncate only the
+    # function-name prefix (appending "~" to signal the cut), never the suffix.
+    suffix = obj_suffix + knob_suffix
+    func_budget = max_total_length - len(suffix)
+
+    if func_budget <= 0:
+        # Suffix alone meets or exceeds the cap — omit the function-name prefix.
+        if len(suffix) <= max_total_length:
+            return suffix
+        # Extreme edge case: even the suffix is over budget.  Preserve at least
+        # the objectives and one knob name by trimming the knob list.
+        if resolved_configuration_space:
+            knob_names_list = list(resolved_configuration_space.keys())
+            min_knob_suffix = f"[{knob_names_list[0]}]"
+            combined = obj_suffix + min_knob_suffix
+            if len(combined) <= max_total_length:
+                return combined
+        return obj_suffix[:max_total_length]
+
+    # Fit the function name into the remaining budget, marking any cut with "~".
+    if len(func_name) <= func_budget:
+        func_part = func_name
+    elif func_budget >= 2:
+        func_part = func_name[: func_budget - 1] + "~"
+    else:
+        func_part = func_name[:func_budget]
+
+    return func_part + suffix
+
+
 def optimize(  # NOSONAR(S107)
     *,
     objectives: list[str] | ObjectiveSchema | None = None,
@@ -2760,6 +2834,36 @@ def optimize(  # NOSONAR(S107)
             config_param,
         )
 
+        # Experiment name resolution (#1422).
+        #
+        # _experiment_name on OptimizedFunction stores ONLY the explicit decorator value
+        # so the getter can lazily check TRAIGENT_EXPERIMENT_NAME at each access —
+        # callers that set the env var AFTER decoration must see it take effect.
+        #
+        # The self-describing default (func name + objectives + knobs) is precomputed
+        # here because the inputs are fully resolved at decoration time; it is stored
+        # in _default_experiment_name and used by the getter as the last resort, after
+        # the explicit value and the env var are both absent.
+        #
+        # Priority resolved in OptimizedFunction.experiment_name getter (highest → lowest):
+        #   1. Explicit experiment_name decorator argument → _experiment_name (not None).
+        #   2. TRAIGENT_EXPERIMENT_NAME env var — checked at ACCESS time (not decoration time).
+        #   3. Self-describing default → _default_experiment_name.
+        #   4. Bare func.__name__ (if no objectives/knobs were registered).
+        default_experiment_name: str | None = None
+        if experiment_name_value is None:
+            default_experiment_name = _build_default_experiment_name(
+                func.__name__, resolved_schema, resolved_configuration_space
+            )
+
+        # Approximate resolved name for the creation log (decoration-time snapshot only).
+        effective_experiment_name = (
+            experiment_name_value
+            or os.environ.get("TRAIGENT_EXPERIMENT_NAME")
+            or default_experiment_name
+            or func.__name__
+        )
+
         optimized_func: OptimizedFunction[_P, _R] = OptimizedFunction(  # type: ignore[assignment]
             func=func,
             eval_dataset=eval_dataset,
@@ -2819,8 +2923,11 @@ def optimize(  # NOSONAR(S107)
             # Optimizer limits (extracted from combined_settings)
             max_trials=max_trials_value,
             _max_trials_explicit=max_trials_explicit,
-            # Experiment display name (overrides func.__name__ in portal/storage)
+            # Experiment display name: only the explicit value goes into _experiment_name
+            # so that TRAIGENT_EXPERIMENT_NAME is checked lazily at access time.
+            # The precomputed self-describing default is stored separately.
             experiment_name=experiment_name_value,
+            _default_experiment_name=default_experiment_name,
             # Warm-start: seed this run from a prior experiment's learned configs.
             warm_start_from=warm_start_from_value,
             # Guided-generation defaults (consumed by optimize_with_guidance)
@@ -2834,9 +2941,8 @@ def optimize(  # NOSONAR(S107)
         optimized_func.hybrid_api_options = hybrid_api_options
         optimized_func.offline = execution_policy.offline
 
-        effective_name = experiment_name_value or func.__name__
         logger.info(
-            f"Created optimizable function: {func.__name__} (experiment_name={effective_name!r})"
+            f"Created optimizable function: {func.__name__} (experiment_name={effective_experiment_name!r})"
         )
 
         # cast so mypy sees OptimizedFunction[_P, _R] rather than

{traigent-0.18.1.dev4 → traigent-0.18.1.dev6}/traigent/cloud/client.py

@@ -33,13 +33,13 @@ else:  # pragma: no cover - minimal environments without aiohttp
 
 from traigent.config.backend_config import BackendConfig
 from traigent.evaluators.base import Dataset
-from traigent.utils.env_config import is_backend_offline
-from traigent.utils.error_handler import OfflineModeError
-from traigent.utils.error_handler import TraigentError as HelpfulTraigentError
 from traigent.utils.artifact_fingerprints import (
     artifact_fingerprints_to_wire,
     fingerprint_meta_to_wire,
 )
+from traigent.utils.env_config import is_backend_offline
+from traigent.utils.error_handler import OfflineModeError
+from traigent.utils.error_handler import TraigentError as HelpfulTraigentError
 from traigent.utils.exceptions import ValidationError as ValidationException
 from traigent.utils.logging import get_logger
 from traigent.utils.retry import NetworkError, RateLimitError, retry_http_request
@@ -62,6 +62,7 @@ from .models import (
     SessionCreationRequest,
     SessionCreationResponse,
     SessionObjectiveDefinition,
+    SessionSummary,
     TrialResultSubmission,
     TrialSuggestion,
 )
@@ -1517,8 +1518,16 @@ class TraigentCloudClient(BaseTraigentClient):
                 f"Failed to finalize session: {e}", "session_finalization", e
             ) from e
 
-    async def delete_session(self, session_id: str, cascade: bool = True) -> bool:
-        """Delete a session using the backend cleanup endpoint."""
+    async def delete_session(self, session_id: str, cascade: bool = False) -> bool:
+        """Delete a session via ``DELETE /api/v1/sessions/<id>``.
+
+        Non-destructive by default (``cascade=False``), matching the backend
+        default: only the session and its run artifacts are removed. Pass
+        ``cascade=True`` to additionally hard-delete the parent experiment when
+        the deleted session was its last run. Use this with
+        :meth:`list_sessions` to enumerate and clean up orphaned / zombie
+        "running" sessions from the client.
+        """
         if not session_id:
             raise ValueError("session_id is required")
 
@@ -1556,6 +1565,68 @@ class TraigentCloudClient(BaseTraigentClient):
                 f"Failed to delete session: {exc}", "session_delete", exc
             ) from exc
 
+    async def list_sessions(
+        self,
+        status: str | None = None,
+        pattern: str | None = None,
+        limit: int | None = None,
+    ) -> list[SessionSummary]:
+        """List sessions via ``GET /api/v1/sessions``.
+
+        Enumerates the caller's optimization sessions so orphaned / zombie
+        "running" sessions can be found and cleaned up with
+        :meth:`delete_session`. Returns typed :class:`SessionSummary` objects.
+
+        Args:
+            status: Optional lifecycle filter (server-side ``status`` query param).
+            pattern: Optional session-id match (server-side ``pattern`` query
+                param).
+            limit: Optional cap on the number of summaries returned. The backend
+                does not support a server-side limit, so this is applied
+                client-side after the response is received.
+
+        Returns:
+            A list of :class:`SessionSummary` (empty when there are none).
+        """
+        self._raise_if_backend_egress_disabled("list sessions")
+        await self._ensure_session()
+        if self._aio_session is None:
+            raise CloudServiceError(_SESSION_NOT_INITIALIZED)
+
+        params: dict[str, str] = {}
+        if status is not None:
+            params["status"] = str(status)
+        if pattern is not None:
+            params["pattern"] = str(pattern)
+
+        url = f"{self.api_base_url}/sessions"
+        try:
+            async with self._aio_session.get(url, params=params) as response:
+                if response.status != 200:
+                    error_text = await response.text()
+                    raise CloudServiceError(
+                        f"Failed to list sessions: status={response.status} "
+                        f"body={error_text[:200]}"
+                    )
+                data = await response.json()
+        except aiohttp.ClientError as exc:
+            await self._reset_http_session("list_sessions network error")
+            raise StandardizedClientError(
+                f"Failed to list sessions: {exc}", "session_list", exc
+            ) from exc
+
+        raw_sessions = data.get("sessions") if isinstance(data, dict) else None
+        if not isinstance(raw_sessions, list):
+            raw_sessions = []
+        summaries = [
+            SessionSummary.from_dict(item)
+            for item in raw_sessions
+            if isinstance(item, dict)
+        ]
+        if limit is not None and limit >= 0:
+            summaries = summaries[:limit]
+        return summaries
+
     # Stateful optimization methods for interactive model
 
     async def create_optimization_session(

{traigent-0.18.1.dev4 → traigent-0.18.1.dev6}/traigent/cloud/models.py

@@ -139,6 +139,40 @@ class OptimizationSession:
         )
 
 
+@dataclass
+class SessionSummary:
+    """Lightweight summary of a session from ``GET /api/v1/sessions``.
+
+    Returned by :meth:`traigent.cloud.client.TraigentCloudClient.list_sessions`.
+    Maps the backend session-list contract
+    (``optimization/optimization_session_list_response_schema.json``):
+    ``session_id`` and
+    ``status`` are always present; ``created_at`` / ``progress`` when the server
+    provides them. Forward-compatible — any additional server fields are kept in
+    ``extra`` rather than dropped, so the SDK can enumerate and clean up orphaned
+    sessions without a release per new field.
+    """
+
+    session_id: str
+    status: str
+    created_at: str | None = None
+    progress: dict[str, Any] | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SessionSummary:
+        """Build a summary from one backend session object, tolerating extras."""
+        known = {"session_id", "status", "created_at", "progress"}
+        progress = data.get("progress")
+        return cls(
+            session_id=str(data.get("session_id", "")),
+            status=str(data.get("status", "")),
+            created_at=data.get("created_at"),
+            progress=progress if isinstance(progress, dict) else None,
+            extra={k: v for k, v in data.items() if k not in known},
+        )
+
+
 @dataclass
 class DatasetSubsetIndices:
     """Indices for selecting a subset of the dataset."""

{traigent-0.18.1.dev4 → traigent-0.18.1.dev6}/traigent/core/optimized_function.py

@@ -615,8 +615,16 @@ class OptimizedFunction(Generic[_P, _R]):
         self.max_trials = kwargs.pop("max_trials", DEFAULT_MAX_TRIALS)
         kwargs["max_trials"] = self.max_trials
 
-        # Experiment display name: decorator param > TRAIGENT_EXPERIMENT_NAME > func.__name__
+        # Experiment display name: decorator param > TRAIGENT_EXPERIMENT_NAME > self-describing default > func.__name__
+        # _experiment_name holds ONLY the explicit decorator value (None when absent).
+        # _default_experiment_name holds the precomputed self-describing default string
+        # (func name + objectives + knobs) that decorators.py computed at decoration time.
+        # The experiment_name getter resolves lazily so TRAIGENT_EXPERIMENT_NAME can be
+        # changed AFTER decoration and still take effect.
         self._experiment_name: str | None = kwargs.pop("experiment_name", None)
+        self._default_experiment_name: str | None = kwargs.pop(
+            "_default_experiment_name", None
+        )
 
         self.timeout = kwargs.pop("timeout", None)
         kwargs["timeout"] = self.timeout
@@ -3479,15 +3487,20 @@ Remediation:
         """Resolved experiment display name for portal/storage.
 
         Resolution order (highest to lowest priority):
-        1. ``experiment_name`` passed to ``@traigent.optimize()``
-        2. ``TRAIGENT_EXPERIMENT_NAME`` environment variable
-        3. Decorated function's ``__name__``
+        1. ``experiment_name`` passed to ``@traigent.optimize()`` — stored in ``_experiment_name``.
+        2. ``TRAIGENT_EXPERIMENT_NAME`` environment variable — checked at access time, so
+           setting it after decoration still takes effect.
+        3. Self-describing default precomputed at decoration time (func name + objectives + knobs)
+           — stored in ``_default_experiment_name``.
+        4. Decorated function's ``__name__`` (bare fallback when no objectives/knobs exist).
         """
         if self._experiment_name is not None:
             return self._experiment_name
         env_name = os.environ.get("TRAIGENT_EXPERIMENT_NAME")
         if env_name:
             return env_name
+        if self._default_experiment_name is not None:
+            return self._default_experiment_name
         return self.__name__
 
     @property

{traigent-0.18.1.dev4 → traigent-0.18.1.dev6}/traigent/utils/results_table.py

@@ -111,12 +111,28 @@ def _format_config_value(val: Any) -> str:
     return str(val)
 
 
+def _format_percent_metric(val: float) -> str:
+    """Format a quality metric (accuracy / score / ...) as a percent string.
+
+    Metrics reach the table on either a 0-1 fraction scale or an already-percent
+    0-100 scale (e.g. a 0-100 ``accuracy`` of 79.16). Mirror the frontend rule
+    (``percentFormatting``): a value ``> 1`` is already a percent and is rendered
+    as-is (79.16 -> ``"79.2%"``); a value ``<= 1`` is a fraction and scaled
+    (0.79 -> ``"79.0%"``). This never double-scales, so a 0-100 metric can no
+    longer render as ">100%" (the prior ``f"{val:.1%}"`` turned 79.16 into
+    "7916.2%").
+    """
+    if val > 1.0:
+        return f"{val:.1f}%"
+    return f"{val:.1%}"
+
+
 def _format_metric_value(metric: str, val: float) -> str:
     if metric == "cost":
         return f"${val:.5f}"
     if metric == "latency":
         return f"{val:.3f}s"
-    return f"{val:.1%}"
+    return _format_percent_metric(val)
 
 
 def _coerce_float(value: Any) -> float | None:

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

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