traigent 0.18.1.dev3__tar.gz → 0.18.1.dev5__tar.gz

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

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

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

{traigent-0.18.1.dev3 → traigent-0.18.1.dev5}/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.dev3 → traigent-0.18.1.dev5}/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.dev5}/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,