xpander-sdk 2.0.332__py3-none-any.whl → 2.0.334__py3-none-any.whl

xpander_sdk/__init__.py

@@ -15,7 +15,7 @@ Main Components:
 For more information, visit: https://xpander.ai
 """
 
-__version__ = "2.0.332"
+__version__ = "2.0.334"
 
 # Backend-related imports
 from .modules.backend.backend_module import Backend

xpander_sdk/core/context_optimizer/context_optimizer.py

@@ -259,6 +259,11 @@ class XPanderContextOptimizer(MapReduceMixin, CompressionManager):
         default_factory=set, init=False, repr=False
     )
 
+    _last_emitted_status_pct: Optional[int] = field(
+        default=None, init=False, repr=False
+    )
+    _compacting: bool = field(default=False, init=False, repr=False)
+
     # In-memory cache + write queue for Layer 1 offloaded blobs. The optimizer
     # writes encrypted bytes here synchronously and the cache spawns the
     # actual workspace POST in the background; the agno tool hook short-
@@ -544,6 +549,8 @@ class XPanderContextOptimizer(MapReduceMixin, CompressionManager):
         # Layer 1: always runs — offload large tool results to workspace
         await self.layer_1_microcompact(messages)
 
+        await self._publish_context_status(messages)
+
         # Layer 3: agent-requested manual compaction (takes priority)
         if self.compact_requested:
             focus = self.compact_focus
@@ -1046,6 +1053,78 @@ class XPanderContextOptimizer(MapReduceMixin, CompressionManager):
             ),
         )
 
+    async def apublish_context_status(
+        self, messages: List[Message]
+    ) -> "Optional[Any]":
+        """Force-emit a context_status snapshot and return the payload; for mid-loop hooks (tool-call completions, sub-execution boundaries) where the caller wants to refresh the indicator without changing the compacting flag."""
+        if not messages:
+            return None
+        return await self._publish_context_status(messages, force=True)
+
+    async def apublish_final_context_status(
+        self, messages: List[Message]
+    ) -> "Optional[Any]":
+        """Force-emit a final context_status with compacting cleared; called at agno run end (RunCompleted/Cancelled/Error) so the indicator settles on post-final-message state."""
+        if not messages:
+            return None
+        self._compacting = False
+        return await self._publish_context_status(messages, force=True)
+
+    async def _publish_context_status(
+        self,
+        messages: List[Message],
+        *,
+        force: bool = False,
+    ) -> "Optional[Any]":
+        """Emit a context_status snapshot for the chat UI indicator; returns the payload (or None if unconfigured / estimate failed)."""
+        if not self.agent or not self.task:
+            return None
+
+        from xpander_sdk.models.context_status import ContextStatus
+        from xpander_sdk.models.events import TaskUpdateEventType
+
+        try:
+            estimated = self._estimate_tokens(messages)
+        except Exception as exc:
+            logger.debug(f"[context-optimizer] context_status estimate failed: {exc}")
+            return None
+
+        window = max(1, int(self.context_window))
+        pct = max(0.0, min(100.0, (estimated / window) * 100.0))
+        self._last_emitted_status_pct = int(pct)
+
+        payload = ContextStatus(
+            estimated_tokens=estimated,
+            context_window=window,
+            percent=round(pct, 1),
+            auto_compact_threshold=self._auto_compact_threshold,
+            emergency_threshold=self._emergency_compact_threshold,
+            compacting=self._compacting,
+        )
+
+        coro = self._push_activity_event(
+            event_type=TaskUpdateEventType.ContextStatus,
+            data=payload,
+        )
+        try:
+            task = asyncio.create_task(coro)
+        except RuntimeError as exc:
+            logger.debug(f"[context-optimizer] context_status schedule failed: {exc}")
+            coro.close()
+            return payload
+
+        def _log_status_task_exception(t: "asyncio.Task[Any]") -> None:
+            if t.cancelled():
+                return
+            exc = t.exception()
+            if exc is not None:
+                logger.debug(
+                    f"[context-optimizer] context_status publish failed: {exc}"
+                )
+
+        task.add_done_callback(_log_status_task_exception)
+        return payload
+
     # Progress-emission rate-limiter state. Reset at the start of every
     # ``layer_2_auto_compact`` call by ``_reset_progress_state``.
     _progress_last_percent: float = field(default=-1.0, init=False, repr=False)
@@ -1379,6 +1458,9 @@ class XPanderContextOptimizer(MapReduceMixin, CompressionManager):
             f"threshold={self._auto_compact_threshold:,})"
         )
 
+        self._compacting = True
+        await self._publish_context_status(messages, force=True)
+
         # Publish start event (fire-and-forget)
         await self._publish_compaction_start(
             trigger=trigger,
@@ -1574,6 +1656,9 @@ class XPanderContextOptimizer(MapReduceMixin, CompressionManager):
                 reduce_phase_seconds=telemetry.get("reduce_phase_seconds"),
             )
 
+            self._compacting = False
+            await self._publish_context_status(messages, force=True)
+
             ratio = (
                 f"{(1 - post_tokens / pre_tokens) * 100:.1f}%"
                 if pre_tokens > 0
@@ -1665,9 +1750,9 @@ class XPanderContextOptimizer(MapReduceMixin, CompressionManager):
                 f"(trigger={trigger}, consecutive_failures={self._auto_compact_consecutive_failures}/"
                 f"{MAX_CONSECUTIVE_COMPACT_FAILURES}): {exc}"
             )
-            # Publish error event (fire-and-forget)
             await self._publish_compaction_error(trigger=trigger, error=str(exc))
-            # Messages are NOT modified on failure — agent continues with full context
+            self._compacting = False
+            await self._publish_context_status(messages, force=True)
 
     # ================================================================== #
     #  Pre-retry helpers

xpander_sdk/models/context_status.py

@@ -0,0 +1,31 @@
+from pydantic import Field
+
+from xpander_sdk.models.shared import XPanderSharedModel
+
+
+class ContextStatus(XPanderSharedModel):
+    """Per-turn snapshot of the LLM context window for the chat UI indicator."""
+
+    estimated_tokens: int = Field(
+        ...,
+        description="Rough token count of the current message list (post-Layer-1 microcompaction).",
+    )
+    context_window: int = Field(
+        ..., description="Model context window size in tokens."
+    )
+    percent: float = Field(
+        ...,
+        description="estimated_tokens / context_window * 100, clamped to [0, 100].",
+    )
+    auto_compact_threshold: int = Field(
+        ...,
+        description="Token level at which Layer 2 auto-compaction fires.",
+    )
+    emergency_threshold: int = Field(
+        ...,
+        description="Token level at which the emergency safety net (88%) fires.",
+    )
+    compacting: bool = Field(
+        default=False,
+        description="True while a Layer 2 compaction is in flight on the current turn.",
+    )

xpander_sdk/models/events.py

@@ -91,6 +91,9 @@ class TaskUpdateEventType(str, Enum):
     # task compaction
     TaskCompactization = "task_compactization"
 
+    # context window status (per-turn snapshot, delta-gated)
+    ContextStatus = "context_status"
+
     # agent gateway
     AgentGatewayDecision = "agent_gateway_decision"
 

xpander_sdk/modules/backend/frameworks/agno.py

@@ -604,7 +604,7 @@ async def build_agent_args(
         {
             "name": xpander_agent.name,
             "model": model,
-            "description": xpander_agent.instructions.description,
+            "description": xpander_agent.description if xpander_agent.description and xpander_agent.description is not None and len(xpander_agent.description) != 0 else xpander_agent.instructions.description,
             "instructions": (
                 task.instructions_override
                 if task.instructions_override

{xpander_sdk-2.0.332.dist-info → xpander_sdk-2.0.334.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.332
+Version: 2.0.334
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.332.dist-info → xpander_sdk-2.0.334.dist-info}/RECORD

@@ -1,4 +1,4 @@
-xpander_sdk/__init__.py,sha256=dq6zgIyyOVFGKAtBvRQDC9_HrQ_l8OniBV4AGtsuGN8,3262
+xpander_sdk/__init__.py,sha256=jk-W2v05q-llpoU37bZkiv-XHMf7OLVUTNj3zOPOMx4,3262
 xpander_sdk/consts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/consts/api_routes.py,sha256=n6kC105wVvycmSWfPYTAmUreHSJhf8v2rY7QvB-yhc4,2997
 xpander_sdk/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -10,7 +10,7 @@ xpander_sdk/core/context_optimizer/action_ledger.py,sha256=tEMZUHWFmqXlFv1DqwnHY
 xpander_sdk/core/context_optimizer/compact_retry_result.py,sha256=2vVvZ0NTiQS2HHobzlAqOicGbk6CYKnoSX23zrqkk_Q,553
 xpander_sdk/core/context_optimizer/completion_evidence.py,sha256=V4J0CZP7HeVlseBqaHryt5IO2UGpywPKGJGIe8elmJk,7844
 xpander_sdk/core/context_optimizer/constants.py,sha256=szWwUHbq2ol27xDFNOEza5qb1fVASkYLvrAJlAmB7p4,8579
-xpander_sdk/core/context_optimizer/context_optimizer.py,sha256=ypUFvmBGqfmMRXHQEp9Ar_28pXOU_pNAv8KZ_kTrj5U,94225
+xpander_sdk/core/context_optimizer/context_optimizer.py,sha256=enncSRm0DlEMf6iU9qsuthiLxjU7BTfCgNEcklzaR3U,97493
 xpander_sdk/core/context_optimizer/encryption.py,sha256=CHIHGi_jjhFykZg5U84-tCqPDpmv4oQ1CHtfa_Gwa88,1914
 xpander_sdk/core/context_optimizer/error_patterns.py,sha256=BCp17HbZKgc-RvaUfLWX0npAeewgBX2RqSAmwpKcSlc,2679
 xpander_sdk/core/context_optimizer/finalize_mode.py,sha256=IztEicji7GJ6xRZjktisSnYOd8uOXz1TXajV86C1fuw,11595
@@ -31,8 +31,9 @@ xpander_sdk/models/action_ledger.py,sha256=qPnPj6_LzUN6Q5vVhWrjbGXDDOhQndKvwCH0p
 xpander_sdk/models/activity.py,sha256=pRqvJFHLLPxSA2x7M-S3h2evE0rt5Y2ueB7Q-zWrQZg,4646
 xpander_sdk/models/compactization.py,sha256=JmlAv_0uvPUqRKVuN63icKLVofZWjCp3hQvqMyofFtc,8002
 xpander_sdk/models/configuration.py,sha256=5vOgkioyj4IGFf7HRdalnkP65r6ey3r8rBUt3iFhU2U,3266
+xpander_sdk/models/context_status.py,sha256=qwgAwy0PefVTsZmdI2HzY1rxH-twenWYp72aO3bk1hw,1022
 xpander_sdk/models/deep_planning.py,sha256=opB30Akv9LZ2QLyPbkCG37569eL5_QyZpQlGiGduHkQ,558
-xpander_sdk/models/events.py,sha256=yTnEIxyDpbJDIQrnYAEQF0PctzAJbL3CyhTILe4P7_Q,2947
+xpander_sdk/models/events.py,sha256=8f-0rG_JJFRwkQYecedTH6udrpl61v2nvl9OtPJw7uU,3046
 xpander_sdk/models/frameworks.py,sha256=pmo05YINaYiQoDiUYao48pttEGrY8HUmwAl46O05PTM,2864
 xpander_sdk/models/generic.py,sha256=E4Ud94vitMCc_xfULOJ4y8b7pFHerFS24HANzzitwjo,772
 xpander_sdk/models/notifications.py,sha256=JX8wlUhWgZb-aUfsiVXINNZAK9rCn5DAwesLkYr5YAE,4135
@@ -56,7 +57,7 @@ xpander_sdk/modules/backend/events_registry.py,sha256=arlbPOwTj7DEONkLQbp2MMb8qE
 xpander_sdk/modules/backend/decorators/__init__.py,sha256=ub9c8G0Ll6AuCvfcFB6rqR8iamMJxtcW7QjWw3WSkPU,106
 xpander_sdk/modules/backend/decorators/on_auth_event.py,sha256=FwZIYD8TVqRFxex12zH5W4GOzXZjQGf5kp4XFbA7KC8,4673
 xpander_sdk/modules/backend/frameworks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk/modules/backend/frameworks/agno.py,sha256=mU-dZfnBE7YTihOvXZ_b2kyXr22xvw_0uL2-14rm5pA,126243
+xpander_sdk/modules/backend/frameworks/agno.py,sha256=VE7AEIblMpChVN5vCUtuOnJ5iwOL3Yngs7eSkv_lLik,126385
 xpander_sdk/modules/backend/frameworks/dispatch.py,sha256=eC35T4krqzk_rRNIGFc68TBs7URcRdKdnwUZ1nNYe4o,1957
 xpander_sdk/modules/backend/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/backend/utils/extra_headers.py,sha256=eYXIsHAMhBYw7RMrA_wzdxL5qAosEe-wUUkAuor0i-0,1634
@@ -113,8 +114,8 @@ xpander_sdk/utils/event_loop.py,sha256=CDiybs1SCguuynlwlYOA38-68CCqy6T3xIfjPuhzO
 xpander_sdk/utils/generic.py,sha256=OSlcWDUjRtyYYBWeg6S4uxkcINKP0_z4pt9D8efcZW8,128
 xpander_sdk/utils/tools.py,sha256=XZN5239Kid6Q1LeT7rYzFjrdDsNy6K_uhi5vYfNUUyE,1299
 xpander_sdk/utils/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk-2.0.332.dist-info/licenses/LICENSE,sha256=XfXDOGoyJbLakLShycg1ZvSvTn1yisMoGVYBkeBYhw0,1262
-xpander_sdk-2.0.332.dist-info/METADATA,sha256=n6NwYa6lWAFrjLmRQ4BjUrR40ABSVIP9fI--R7DxN7Y,22146
-xpander_sdk-2.0.332.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-xpander_sdk-2.0.332.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
-xpander_sdk-2.0.332.dist-info/RECORD,,
+xpander_sdk-2.0.334.dist-info/licenses/LICENSE,sha256=XfXDOGoyJbLakLShycg1ZvSvTn1yisMoGVYBkeBYhw0,1262
+xpander_sdk-2.0.334.dist-info/METADATA,sha256=ZCF5fqUYncShVZ7sc6KDcmHHckiBsOEh_h9EeQPCuqA,22146
+xpander_sdk-2.0.334.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+xpander_sdk-2.0.334.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
+xpander_sdk-2.0.334.dist-info/RECORD,,