traigent 0.18.0__tar.gz → 0.18.1.dev0__tar.gz

{traigent-0.18.0/traigent.egg-info → traigent-0.18.1.dev0}/PKG-INFO

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

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

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

@@ -145,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 → traigent-0.18.1.dev0}/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 → traigent-0.18.1.dev0}/traigent/cli/next_steps_command.py

@@ -70,6 +70,12 @@ def _print_next_steps_table(payload: dict[str, Any]) -> None:
     experiment_run_id = payload.get("experiment_run_id", "unknown")
     console.print(f"\n[bold blue]Next Steps for {experiment_run_id}[/bold blue]\n")
 
+    posture = payload.get("posture")
+    if isinstance(posture, dict):
+        summary_text = posture.get("summary_text")
+        if summary_text:
+            console.print(f"[bold]Posture:[/bold] {summary_text}\n")
+
     rows = payload.get("next_steps") or []
     if rows:
         table = Table(show_header=True, header_style="bold magenta")

{traigent-0.18.0 → traigent-0.18.1.dev0}/traigent/cloud/api_key_manager.py

@@ -290,12 +290,12 @@ class APIKeyManager:
         alphanumerics or underscores after the prefix.
         Returns False for any deviation so callers can reject suspicious values early.
 
-        Supported formats:
-        - `tg_`: Standard Traigent API keys (64 characters total)
-        - `uk_`: User/utility keys issued by the backend (46 characters total)
-        - `sk_`: Service keys issued by the backend (46 characters total)
-        - `ak_`: Admin keys issued by the backend (46 characters total)
-        - `tk_`: Temporary keys issued by the backend (46 characters total)
+        Supported formats:
+        - `tg_`: Standard Traigent API keys (64 characters total)
+        - `uk_`: User/utility keys issued by the backend (46 characters total)
+        - `sk_`: Service keys issued by the backend (46 characters total)
+        - `ak_`: Admin keys issued by the backend (46 characters total)
+        - `tk_`: Temporary keys issued by the backend (46 characters total)
 
         Args:
             key: API key to validate
@@ -307,13 +307,13 @@ class APIKeyManager:
             return False
 
         # Define valid prefixes and their expected total lengths
-        prefix_lengths = {
-            "tg_": 64,  # Standard Traigent API keys
-            "uk_": 46,  # User/utility keys from backend
-            "sk_": 46,  # Service keys from backend
-            "ak_": 46,  # Admin keys from backend
-            "tk_": 46,  # Temporary keys from backend
-        }
+        prefix_lengths = {
+            "tg_": 64,  # Standard Traigent API keys
+            "uk_": 46,  # User/utility keys from backend
+            "sk_": 46,  # Service keys from backend
+            "ak_": 46,  # Admin keys from backend
+            "tk_": 46,  # Temporary keys from backend
+        }
 
         # Find matching prefix
         matched_prefix = None

{traigent-0.18.0 → traigent-0.18.1.dev0}/traigent/cloud/api_operations.py

@@ -36,6 +36,10 @@ from traigent.core.session_types import (
 )
 from traigent.utils.env_config import is_backend_offline
 from traigent.utils.exceptions import MetricExtractionError
+from traigent.utils.artifact_fingerprints import (
+    artifact_fingerprints_to_wire,
+    fingerprint_meta_to_wire,
+)
 from traigent.utils.logging import get_logger
 from traigent.utils.validation import validate_numeric_metric
 
@@ -654,6 +658,7 @@ class ApiOperations:
             payload["tvl_governance"] = wire_governance
         if getattr(session_request, "warm_start_from", None):
             payload["warm_start_from"] = session_request.warm_start_from
+        self._attach_artifact_fingerprint_payload(payload, session_request)
         return payload
 
     def _build_legacy_session_payload(
@@ -697,8 +702,26 @@ class ApiOperations:
         # BE may not consume it yet; the SDK must still forward it.
         if getattr(session_request, "warm_start_from", None):
             payload["warm_start_from"] = session_request.warm_start_from
+        self._attach_artifact_fingerprint_payload(payload, session_request)
         return payload
 
+    @staticmethod
+    def _attach_artifact_fingerprint_payload(
+        payload: dict[str, Any],
+        session_request: SessionCreationRequest,
+    ) -> None:
+        artifact_fingerprints = artifact_fingerprints_to_wire(
+            getattr(session_request, "artifact_fingerprints", None)
+        )
+        if artifact_fingerprints is not None:
+            payload["artifact_fingerprints"] = artifact_fingerprints
+
+        fingerprint_meta = fingerprint_meta_to_wire(
+            getattr(session_request, "fingerprint_meta", None)
+        )
+        if fingerprint_meta is not None:
+            payload["fingerprint_meta"] = fingerprint_meta
+
     def _build_connector(self) -> Any | None:
         """Create an aiohttp connector when custom transport settings are required."""
 

{traigent-0.18.0 → traigent-0.18.1.dev0}/traigent/cloud/backend_client.py

@@ -8,6 +8,7 @@ for better maintainability and adherence to software engineering principles.
 
 import asyncio
 import concurrent.futures
+import json
 import os
 import secrets
 import sys
@@ -24,7 +25,7 @@ from urllib.parse import quote, urlparse, urlunparse
 # Import and re-export BackendClientConfig for backward compatibility
 from traigent.cloud._aiohttp_compat import AIOHTTP_AVAILABLE, aiohttp
 from traigent.cloud.api_operations import ApiOperations
-from traigent.cloud.auth import AuthenticationError
+from traigent.cloud.auth import AuthenticationError, _build_api_key_auth_headers
 from traigent.cloud.backend_bridges import SDKBackendBridge, SessionExperimentMapping
 from traigent.cloud.backend_bridges import bridge as _bridge
 from traigent.cloud.backend_components import (
@@ -116,6 +117,48 @@ _ALLOWED_EXAMPLE_FEATURE_KINDS = frozenset({"simhash_v1"})
 _JSON_CONTENT_TYPE = "application/json"
 _SDK_USER_AGENT = get_sdk_user_agent()
 _SYNC_BACKEND_TRANSIENT_STATUSES = frozenset({408, 429, *range(500, 600)})
+_INTERACTION_POLICY_REQUIRED_KEYS = frozenset(
+    {
+        "schema_version",
+        "profile",
+        "policy_text",
+        "question_budget",
+        "options_max",
+        "jargon_level",
+        "next_skill_hint",
+        "fallback_policy",
+    }
+)
+_INTERACTION_POLICY_PROFILE_REQUIRED_KEYS = frozenset(
+    {
+        "schema_version",
+        "control",
+        "expertise",
+        "pace",
+        "source",
+        "confidence",
+    }
+)
+_INTERACTION_POLICY_RESPONSE_SCHEMA_VERSION = "traigent.agent_interaction.response.v1"
+_INTERACTION_POLICY_PROFILE_SCHEMA_VERSION = "traigent.interaction_policy.v1"
+
+STATIC_POLICY_TEXT = (
+    "Adapt to the user's interaction profile — persona "
+    "(control=delegate|guided|inspect, expertise=se|ds|unknown) and session "
+    "mood (pace=execute|balanced|explore); default guided,se,balanced; infer "
+    "from explicit statements first then behavior, corrections win. Always be "
+    "concise. Match terminology to expertise: plain words and define each term "
+    "once for se; compact statistics/optimization terms for ds. When asking, "
+    "show at most 3 options, mark one Recommended, give one short trade-off "
+    "each. For delegate/execute, proceed with the recommended reversible "
+    "action and ask only at hard gates (paid/provider calls, data egress, "
+    "destructive edits, service-owned decisions, missing required facts); for "
+    "inspect/explore, give brief rationale before asking. Always recommend "
+    "the next skill or action. Never weaken safety (dry-run before paid runs; "
+    "approval before cost or egress; service-returned plans are authoritative) "
+    "and never put persona or private content into telemetry, metadata, names, "
+    "logs, or provenance."
+)
 
 
 class _SyncBackendTransientError(RetryableError):
@@ -563,6 +606,10 @@ class BackendIntegratedClient:
         # Read-only analytics accessor (lazily exposed via the ``analytics``
         # property). Kept separate from the write paths above.
         self._analytics_ns: AnalyticsNamespace | None = None
+        self._interaction_policy_cache: dict[
+            tuple[str | None, str | None], dict[str, Any]
+        ] = {}
+        self._interaction_policy_fallback_logged = False
 
     @property
     def analytics(self) -> "AnalyticsNamespace":
@@ -577,12 +624,286 @@ class BackendIntegratedClient:
             self._analytics_ns = AnalyticsNamespace(self)
         return self._analytics_ns
 
+    def _log_local_interaction_policy_once(self) -> None:
+        if self._interaction_policy_fallback_logged:
+            return
+        logger.info("using local interaction policy")
+        self._interaction_policy_fallback_logged = True
+
+    def _static_interaction_policy(self) -> dict[str, Any]:
+        self._log_local_interaction_policy_once()
+        return {
+            "schema_version": _INTERACTION_POLICY_RESPONSE_SCHEMA_VERSION,
+            "profile": {
+                "control": "guided",
+                "expertise": "se",
+                "pace": "balanced",
+                "source": "default",
+                "confidence": 0.0,
+                "schema_version": _INTERACTION_POLICY_PROFILE_SCHEMA_VERSION,
+            },
+            "policy_text": STATIC_POLICY_TEXT,
+            "question_budget": 2,
+            "options_max": 3,
+            "jargon_level": "plain",
+            "next_skill_hint": None,
+            "fallback_policy": "static_v1",
+        }
+
+    @staticmethod
+    def _interaction_policy_cache_key(
+        *,
+        harness: str | None,
+        skill: str | None,
+    ) -> tuple[str | None, str | None]:
+        def _normalize(value: str | None) -> str | None:
+            if not isinstance(value, str):
+                return value
+            cleaned = value.strip()
+            return cleaned or None
+
+        return (_normalize(harness), _normalize(skill))
+
+    @staticmethod
+    def _build_interaction_policy_params(
+        *,
+        harness: str | None,
+        skill: str | None,
+        signals: Any,
+    ) -> dict[str, str] | None:
+        params: dict[str, str] = {}
+        if isinstance(harness, str) and harness.strip():
+            params["harness"] = harness.strip()
+        if isinstance(skill, str) and skill.strip():
+            params["skill"] = skill.strip()
+        if signals is not None:
+            params["signals"] = json.dumps(
+                signals, separators=(",", ":"), sort_keys=True
+            )
+        return params or None
+
+    @staticmethod
+    def _normalize_interaction_policy_payload(payload: Any) -> dict[str, Any]:
+        if not isinstance(payload, dict):
+            raise CloudServiceError(
+                "Interaction policy endpoint returned a non-JSON object response"
+            )
+
+        data = payload.get("data", payload)
+        if not isinstance(data, dict):
+            raise CloudServiceError(
+                "Interaction policy endpoint returned invalid response data"
+            )
+
+        missing = sorted(_INTERACTION_POLICY_REQUIRED_KEYS - data.keys())
+        if missing:
+            raise CloudServiceError(
+                "Interaction policy endpoint returned malformed response: "
+                f"missing {', '.join(missing)}"
+            )
+
+        if data.get("schema_version") != _INTERACTION_POLICY_RESPONSE_SCHEMA_VERSION:
+            raise CloudServiceError(
+                "Interaction policy endpoint returned unsupported response schema"
+            )
+
+        profile = data.get("profile")
+        if not isinstance(profile, dict):
+            raise CloudServiceError(
+                "Interaction policy endpoint returned malformed profile"
+            )
+
+        missing_profile = sorted(
+            _INTERACTION_POLICY_PROFILE_REQUIRED_KEYS - profile.keys()
+        )
+        if missing_profile:
+            raise CloudServiceError(
+                "Interaction policy endpoint returned malformed profile: "
+                f"missing {', '.join(missing_profile)}"
+            )
+
+        if profile.get("schema_version") != _INTERACTION_POLICY_PROFILE_SCHEMA_VERSION:
+            raise CloudServiceError(
+                "Interaction policy endpoint returned unsupported profile schema"
+            )
+
+        return {
+            "schema_version": data["schema_version"],
+            "profile": {
+                "control": profile["control"],
+                "expertise": profile["expertise"],
+                "pace": profile["pace"],
+                "source": profile["source"],
+                "confidence": profile["confidence"],
+                "schema_version": profile["schema_version"],
+            },
+            "policy_text": data["policy_text"],
+            "question_budget": data["question_budget"],
+            "options_max": data["options_max"],
+            "jargon_level": data["jargon_level"],
+            "next_skill_hint": data["next_skill_hint"],
+            "fallback_policy": data["fallback_policy"],
+        }
+
+    def _cache_interaction_policy(
+        self,
+        *,
+        cache_key: tuple[str | None, str | None],
+        policy: Mapping[str, Any],
+        etag: str | None,
+    ) -> None:
+        profile = policy.get("profile")
+        cached_profile: dict[str, Any] | None = None
+        if isinstance(profile, Mapping):
+            cached_profile = {
+                "control": profile.get("control"),
+                "expertise": profile.get("expertise"),
+                "pace": profile.get("pace"),
+                "source": profile.get("source"),
+                "confidence": profile.get("confidence"),
+                "schema_version": profile.get("schema_version"),
+            }
+        self._interaction_policy_cache[cache_key] = {
+            "etag": etag,
+            "policy_text": policy["policy_text"],
+            "profile": cached_profile,
+        }
+
+    def _cached_interaction_policy(
+        self, cache_key: tuple[str | None, str | None]
+    ) -> dict[str, Any] | None:
+        cached = self._interaction_policy_cache.get(cache_key)
+        if not isinstance(cached, dict):
+            return None
+
+        policy_text = cached.get("policy_text")
+        if not isinstance(policy_text, str):
+            return None
+
+        profile = cached.get("profile")
+        if not isinstance(profile, dict):
+            return None
+
+        restored = {
+            "schema_version": _INTERACTION_POLICY_RESPONSE_SCHEMA_VERSION,
+            "profile": {
+                "control": profile.get("control"),
+                "expertise": profile.get("expertise"),
+                "pace": profile.get("pace"),
+                "source": profile.get("source"),
+                "confidence": profile.get("confidence"),
+                "schema_version": profile.get("schema_version"),
+            },
+            "policy_text": policy_text,
+            "question_budget": 2,
+            "options_max": 3,
+            "jargon_level": "plain",
+            "next_skill_hint": None,
+            "fallback_policy": "static_v1",
+        }
+        return restored
+
     @property
     def session_bridge(self) -> "SDKBackendBridge":
         """Return the shared session bridge (exposed for test patching)."""
 
         return bridge
 
+    async def get_interaction_policy(
+        self,
+        *,
+        harness: str | None = None,
+        skill: str | None = None,
+        signals: Any = None,
+    ) -> dict[str, Any]:
+        """Return the backend persona-interaction policy seed for this session.
+
+        The backend response is a seed for the agent's starting interaction
+        profile only. Explicit user corrections made in-conversation remain
+        authoritative and must override this seed.
+        """
+        from traigent.utils.env_config import is_mock_llm
+
+        if cloud_backend_egress_disabled(self.no_egress):
+            return self._static_interaction_policy()
+
+        api_key = os.getenv("TRAIGENT_API_KEY") or self._api_key_fallback
+        if not api_key or is_mock_llm() or not AIOHTTP_AVAILABLE:
+            return self._static_interaction_policy()
+
+        cache_key = self._interaction_policy_cache_key(
+            harness=harness,
+            skill=skill,
+        )
+        cached = self._interaction_policy_cache.get(cache_key)
+
+        headers = _build_api_key_auth_headers(api_key)
+        headers.setdefault("User-Agent", _SDK_USER_AGENT)
+        cached_etag = cached.get("etag") if isinstance(cached, dict) else None
+        if isinstance(cached_etag, str) and cached_etag:
+            headers["If-None-Match"] = cached_etag
+
+        try:
+            params = self._build_interaction_policy_params(
+                harness=harness,
+                skill=skill,
+                signals=signals,
+            )
+            backend_origin = (
+                self.backend_config.backend_base_url or BackendConfig.get_backend_url()
+            ).rstrip("/")
+            url = f"{backend_origin}/api/v1/auth/me/interaction-policy"
+
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    url,
+                    headers=headers,
+                    params=params,
+                    timeout=aiohttp.ClientTimeout(total=self.timeout),
+                ) as response:
+                    if response.status == 304:
+                        cached_policy = self._cached_interaction_policy(cache_key)
+                        if cached_policy is not None:
+                            return cached_policy
+                        raise CloudServiceError(
+                            "Interaction policy cache miss for backend 304 response"
+                        )
+
+                    if response.status >= 400:
+                        error_text = await response.text()
+                        raise CloudServiceError(
+                            "Interaction policy request failed with HTTP "
+                            f"{response.status}: {error_text[:200]}"
+                        )
+
+                    try:
+                        payload = await response.json()
+                    except Exception as exc:
+                        raise CloudServiceError(
+                            "Interaction policy endpoint returned non-JSON response"
+                        ) from exc
+
+                    policy = self._normalize_interaction_policy_payload(payload)
+                    self._cache_interaction_policy(
+                        cache_key=cache_key,
+                        policy=policy,
+                        etag=response.headers.get("ETag"),
+                    )
+                    return policy
+        except (
+            aiohttp.ClientError,
+            TimeoutError,
+            CloudServiceError,
+            AuthenticationError,
+            TypeError,
+            ValueError,
+        ) as exc:
+            logger.debug(
+                "Interaction policy request failed; using local fallback: %s",
+                exc,
+            )
+            return self._static_interaction_policy()
+
     def _resolve_local_storage_path(self, override: str | None) -> Path:
         """Determine the root path for local fallback storage."""
 
@@ -960,6 +1281,8 @@ class BackendIntegratedClient:
         promotion_policy: dict[str, Any] | None = None,
         tvl_governance: dict[str, Any] | None = None,
         warm_start_from: str | None = None,
+        artifact_fingerprints: dict[str, str | None] | None = None,
+        fingerprint_meta: dict[str, Any] | None = None,
     ) -> SessionCreationResult:
         """Synchronous wrapper for creating a session.
         Delegates to session_operations module. Phase 8: objectives are
@@ -974,6 +1297,8 @@ class BackendIntegratedClient:
             promotion_policy=promotion_policy,
             tvl_governance=tvl_governance,
             warm_start_from=warm_start_from,
+            artifact_fingerprints=artifact_fingerprints,
+            fingerprint_meta=fingerprint_meta,
         )
 
     async def create_hybrid_session(

{traigent-0.18.0 → traigent-0.18.1.dev0}/traigent/cloud/client.py

@@ -36,6 +36,10 @@ 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.exceptions import ValidationError as ValidationException
 from traigent.utils.logging import get_logger
 from traigent.utils.retry import NetworkError, RateLimitError, retry_http_request
@@ -1570,6 +1574,8 @@ class TraigentCloudClient(BaseTraigentClient):
         optimization_strategy: dict[str, Any] | None = None,
         user_id: str | None = None,
         billing_tier: str = "standard",
+        artifact_fingerprints: dict[str, str | None] | None = None,
+        fingerprint_meta: dict[str, Any] | None = None,
     ) -> SessionCreationResponse:
         """Create a new optimization session for interactive optimization.
 
@@ -1611,6 +1617,8 @@ class TraigentCloudClient(BaseTraigentClient):
                 optimization_strategy=optimization_strategy,
                 user_id=user_id,
                 billing_tier=billing_tier,
+                artifact_fingerprints=artifact_fingerprints,
+                fingerprint_meta=fingerprint_meta,
             )
 
         if self._aio_session is None:
@@ -1857,6 +1865,16 @@ class TraigentCloudClient(BaseTraigentClient):
         # Warm-start: prior experiment id (empty string treated as absent).
         if request.warm_start_from:
             payload["warm_start_from"] = request.warm_start_from
+        artifact_fingerprints = artifact_fingerprints_to_wire(
+            getattr(request, "artifact_fingerprints", None)
+        )
+        if artifact_fingerprints is not None:
+            payload["artifact_fingerprints"] = artifact_fingerprints
+        fingerprint_meta = fingerprint_meta_to_wire(
+            getattr(request, "fingerprint_meta", None)
+        )
+        if fingerprint_meta is not None:
+            payload["fingerprint_meta"] = fingerprint_meta
         return payload
 
     @staticmethod

{traigent-0.18.0 → traigent-0.18.1.dev0}/traigent/cloud/models.py

@@ -202,6 +202,8 @@ class SessionCreationRequest:
     user_id: str | None = None
     billing_tier: str = "standard"
     metadata: dict[str, Any] = field(default_factory=dict)
+    artifact_fingerprints: dict[str, str | None] | None = None
+    fingerprint_meta: dict[str, Any] | None = None
     # Alternative parameter names for test compatibility
     problem_type: str | None = None
 

{traigent-0.18.0 → traigent-0.18.1.dev0}/traigent/cloud/session_operations.py

@@ -329,6 +329,8 @@ class SessionOperations:
         promotion_policy: dict[str, Any] | None = None,
         tvl_governance: dict[str, Any] | None = None,
         warm_start_from: str | None = None,
+        artifact_fingerprints: dict[str, str | None] | None = None,
+        fingerprint_meta: dict[str, Any] | None = None,
     ) -> SessionCreationResult:
         """Create a session with backend metadata submission.
 
@@ -446,6 +448,8 @@ class SessionOperations:
                 user_id=None,  # Privacy preserving
                 billing_tier="privacy",
                 metadata=metadata or {},
+                artifact_fingerprints=artifact_fingerprints,
+                fingerprint_meta=fingerprint_meta,
             )
 
             try: