xpander-sdk 2.0.332__tar.gz → 2.0.334__tar.gz

{xpander_sdk-2.0.332/src/xpander_sdk.egg-info → xpander_sdk-2.0.334}/PKG-INFO

@@ -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 → xpander_sdk-2.0.334}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.332",
+    version="2.0.334",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",

{xpander_sdk-2.0.332 → xpander_sdk-2.0.334}/src/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-2.0.332 → xpander_sdk-2.0.334}/src/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-2.0.334/src/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-2.0.332 → xpander_sdk-2.0.334}/src/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-2.0.332 → xpander_sdk-2.0.334}/src/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 → xpander_sdk-2.0.334/src/xpander_sdk.egg-info}/PKG-INFO

@@ -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 → xpander_sdk-2.0.334}/src/xpander_sdk.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ src/xpander_sdk/models/action_ledger.py
 src/xpander_sdk/models/activity.py
 src/xpander_sdk/models/compactization.py
 src/xpander_sdk/models/configuration.py
+src/xpander_sdk/models/context_status.py
 src/xpander_sdk/models/deep_planning.py
 src/xpander_sdk/models/events.py
 src/xpander_sdk/models/frameworks.py
@@ -127,6 +128,7 @@ tests/test_boot_shutdown_handlers.py
 tests/test_context_optimizer_chunked.py
 tests/test_context_optimizer_perf.py
 tests/test_context_optimizer_recent_actions.py
+tests/test_context_optimizer_status_events.py
 tests/test_context_optimizer_unwrap.py
 tests/test_context_optimizer_window.py
 tests/test_context_window_detection.py

xpander_sdk-2.0.334/tests/test_context_optimizer_status_events.py

@@ -0,0 +1,164 @@
+"""Unit tests for the per-turn context_status event stream."""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from xpander_sdk.core.context_optimizer import context_optimizer as co
+from xpander_sdk.core.context_optimizer.context_optimizer import (
+    XPanderContextOptimizer,
+)
+from xpander_sdk.models.events import TaskUpdateEventType
+
+
+def _mk_msg(role: str = "user", content: str = "x"):
+    return SimpleNamespace(
+        role=role,
+        content=content,
+        tool_name=None,
+        tool_call_id=None,
+        to_dict=lambda r=role, c=content: {"role": r, "content": c},
+    )
+
+
+def _make_optimizer(estimated: int = 50_000):
+    opt = XPanderContextOptimizer(
+        context_window=200_000,
+        reserved_for_output=20_000,
+        buffer_tokens=13_000,
+        chunked_compact_threshold=100_000,
+    )
+    opt.agent = SimpleNamespace(id="agent-1", configuration=MagicMock())
+    opt.task = SimpleNamespace(
+        id="task-1", organization_id="org-1", deep_planning=None
+    )
+    opt._push_activity_event = AsyncMock(return_value=None)
+    opt._estimate_tokens = MagicMock(return_value=estimated)
+    opt.layer_1_microcompact = AsyncMock(return_value=None)
+    return opt
+
+
+def _status_calls(opt) -> list:
+    return [
+        call
+        for call in opt._push_activity_event.await_args_list
+        if call.kwargs.get("event_type") == TaskUpdateEventType.ContextStatus
+    ]
+
+
+async def _drain_pending_tasks() -> None:
+    """Yield so detached create_task pushes run before asserting on AsyncMock awaits."""
+    for _ in range(5):
+        await asyncio.sleep(0)
+
+
+@pytest.mark.asyncio
+async def test_first_acompress_emits_one_status_event():
+    opt = _make_optimizer(estimated=50_000)
+    await opt.acompress(messages=[_mk_msg()])
+    await _drain_pending_tasks()
+
+    calls = _status_calls(opt)
+    assert len(calls) == 1
+    payload = calls[0].kwargs["data"]
+    assert payload.estimated_tokens == 50_000
+    assert payload.context_window == 200_000
+    assert payload.percent == 25.0
+    assert payload.compacting is False
+
+
+@pytest.mark.asyncio
+async def test_status_event_emits_every_acompress():
+    opt = _make_optimizer(estimated=50_000)
+    await opt.acompress(messages=[_mk_msg()])
+    opt._estimate_tokens.return_value = 50_500
+    await opt.acompress(messages=[_mk_msg()])
+    await _drain_pending_tasks()
+
+    assert len(_status_calls(opt)) == 2
+
+
+@pytest.mark.asyncio
+async def test_status_event_re_emitted_when_percent_bucket_changes():
+    opt = _make_optimizer(estimated=50_000)
+    await opt.acompress(messages=[_mk_msg()])
+    opt._estimate_tokens.return_value = 60_000
+    await opt.acompress(messages=[_mk_msg()])
+    await _drain_pending_tasks()
+
+    calls = _status_calls(opt)
+    assert len(calls) == 2
+    assert calls[1].kwargs["data"].percent == 30.0
+
+
+@pytest.mark.asyncio
+async def test_layer_2_brackets_with_compacting_true_then_false():
+    opt = _make_optimizer(estimated=200_000)
+
+    async def fake_call(
+        system_prompt,
+        user_prompt,
+        run_metrics=None,
+        progress_label="layer 2",
+        **kwargs,
+    ):
+        return "digest", 5, 3
+
+    with (
+        patch.object(co, "get_model", side_effect=lambda m: m),
+        patch.object(opt, "_run_llm_compaction_call", side_effect=fake_call),
+    ):
+        from agno.models.message import Message
+
+        opt.model = MagicMock(id="mock-model")
+        opt.model.get_provider = lambda: "mock"
+        messages = [
+            Message(role="system", content="sys"),
+            Message(role="user", content="u"),
+        ]
+        await opt.layer_2_auto_compact(messages=messages, trigger="auto")
+        await _drain_pending_tasks()
+
+    calls = _status_calls(opt)
+    assert len(calls) >= 2
+    assert calls[0].kwargs["data"].compacting is True
+    assert calls[-1].kwargs["data"].compacting is False
+
+
+@pytest.mark.asyncio
+async def test_layer_2_error_path_still_drops_compacting_flag():
+    opt = _make_optimizer(estimated=200_000)
+
+    async def failing_call(*a, **kw):
+        raise RuntimeError("provider exploded")
+
+    with (
+        patch.object(co, "get_model", side_effect=lambda m: m),
+        patch.object(opt, "_run_llm_compaction_call", side_effect=failing_call),
+    ):
+        from agno.models.message import Message
+
+        opt.model = MagicMock(id="mock-model")
+        opt.model.get_provider = lambda: "mock"
+        await opt.layer_2_auto_compact(
+            messages=[Message(role="system", content="sys")],
+            trigger="auto",
+        )
+        await _drain_pending_tasks()
+
+    calls = _status_calls(opt)
+    assert calls, "expected at least one context_status event"
+    assert calls[-1].kwargs["data"].compacting is False
+
+
+@pytest.mark.asyncio
+async def test_acompress_swallows_status_publish_failure():
+    opt = _make_optimizer(estimated=50_000)
+    opt._push_activity_event.side_effect = RuntimeError("redis down")
+
+    await opt.acompress(messages=[_mk_msg()])
+    await _drain_pending_tasks()