digitalkin 1.0.1.dev0__tar.gz → 1.0.2.dev1__tar.gz

{digitalkin-1.0.1.dev0 → digitalkin-1.0.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.1.dev0
+Version: 1.0.2.dev1
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International
@@ -453,13 +453,13 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ag-ui-protocol>=0.1.18
-Requires-Dist: agentic-mesh-protocol==1.0.0b0
+Requires-Dist: agentic-mesh-protocol==1.0.1.dev3
 Requires-Dist: anyio>=4.13.0
-Requires-Dist: grpcio-health-checking==1.81.0
-Requires-Dist: grpcio-reflection==1.81.0
-Requires-Dist: grpcio-status==1.81.0
-Requires-Dist: pydantic>=2.12.4
+Requires-Dist: grpcio-health-checking==1.82.1
+Requires-Dist: grpcio-reflection==1.82.1
+Requires-Dist: grpcio-status==1.82.1
 Requires-Dist: pydantic-settings>=2.14.1
+Requires-Dist: pydantic>=2.12.4
 Requires-Dist: redis[hiredis]<9,>=7.4.0
 Provides-Extra: agno
 Requires-Dist: agno>=2.6; extra == "agno"

{digitalkin-1.0.1.dev0 → digitalkin-1.0.2.dev1}/pyproject.toml

@@ -28,19 +28,19 @@
 
     dependencies = [
         "ag-ui-protocol>=0.1.18",
-        "agentic-mesh-protocol==1.0.0b0",
+        "agentic-mesh-protocol==1.0.1.dev3",
         "anyio>=4.13.0",
-        "grpcio-health-checking==1.81.0",
-        "grpcio-reflection==1.81.0",
-        "grpcio-status==1.81.0",
-        "pydantic>=2.12.4",
+        "grpcio-health-checking==1.82.1",
+        "grpcio-reflection==1.82.1",
+        "grpcio-status==1.82.1",
         "pydantic-settings>=2.14.1",
+        "pydantic>=2.12.4",
         "redis[hiredis]>=7.4.0,<9",
     ]
-    version = "1.0.1.dev0"
+    version = "1.0.2.dev1"
 
     [project.optional-dependencies]
-        agno        = [ "agno>=2.6" ]
+        agno = [ "agno>=2.6" ]
         performance = [ "uvloop>=0.21" ]
         profiling = [
             "pyinstrument>=5.1.2",
@@ -57,6 +57,22 @@
         name  = "DigitalKin.ai"
 
 [dependency-groups]
+    tests = [
+        "fakeredis[lua]>=2.35.1",
+        "freezegun>=1.5.5",
+        "grpcio-testing>=1.81.0",
+        "hdrhistogram>=0.10.3",
+        "hypothesis>=6.152.8",
+        "objgraph>=3.6",
+        "psutil>=7.2.2",
+        "pytest-asyncio>=1.3.0",
+        "pytest-benchmark>=5.2.3",
+        "pytest-cov>=7.1.0",
+        "pytest-html>=4.2.0",
+        "pytest-json-report>=1.5.0",
+        "pytest-timeout>=2.4.0",
+        "pytest>=9.0.3",
+    ]
     dev = [
         "build>=1.5.0",
         "bump-my-version>=1.3.0",
@@ -68,7 +84,7 @@
         "twine>=6.2.0",
         "types-grpcio-health-checking>=1.0.0.20260518",
         "types-grpcio-reflection>=1.0.0.20260508",
-        "types-grpcio>=1.0.0.20260518",
+        "types-grpcio>=1.82.1.20260711",
         "types-protobuf>=7.34.1.20260518",
         "typos>=1.48.0",
     ]
@@ -96,23 +112,6 @@
         "mkdocstrings>=1.0.4",
         "tomli>=2.4.1",
     ]
-    tests = [
-        "agno>=2.6",
-        "fakeredis[lua]>=2.35.1",
-        "freezegun>=1.5.5",
-        "grpcio-testing>=1.81.0",
-        "hdrhistogram>=0.10.3",
-        "hypothesis>=6.152.8",
-        "objgraph>=3.6",
-        "psutil>=7.2.2",
-        "pytest-asyncio>=1.3.0",
-        "pytest-benchmark>=4.0",
-        "pytest-cov>=7.1.0",
-        "pytest-html>=4.2.0",
-        "pytest-json-report>=1.5.0",
-        "pytest-timeout>=2.4.0",
-        "pytest>=9.0.3",
-    ]
 [tool.setuptools]
     package-dir = { "" = "src" }
 
@@ -148,12 +147,12 @@
         "buck-out",
         "build",
         "dist",
-        "scripts",
         "docs/*",
         "examples/*",
         "factory.py",
         "generate_certificates.py",
         "node_modules",
+        "scripts",
         "tests/*",
         "venv",
     ]
@@ -270,10 +269,10 @@
         skip-magic-trailing-comma = false
 
 [tool.mypy]
-    exclude                = [ "examples", "tests", "scripts" ]
+    exclude                = [ "examples", "scripts", "tests" ]
     ignore_missing_imports = true
-    warn_unused_ignores    = true
     warn_redundant_casts   = true
+    warn_unused_ignores    = true
 
 [tool.pytest.ini_options]
 

{digitalkin-1.0.1.dev0 → digitalkin-1.0.2.dev1}/src/digitalkin/__version__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("digitalkin")
 except PackageNotFoundError:
-    __version__ = "1.0.1.dev0"
+    __version__ = "1.0.2.dev1"

{digitalkin-1.0.1.dev0 → digitalkin-1.0.2.dev1}/src/digitalkin/community/agno/__init__.py

@@ -20,6 +20,11 @@ optional ``agno`` dependency at import time and is therefore NOT exported here;
 import it directly::
 
     from digitalkin.community.agno.module_toolkit import ModuleToolkit
+
+Default agent toolkits (``ChatHistoryTools``, ``UserProfileTools``,
+``RegistryTools``, ``DefaultToolkits``) live in
+:mod:`digitalkin.community.agno.toolkits` — imported separately because they
+require the optional ``agno`` dependency at import time.
 """
 
 from digitalkin.community.agno.agno_adapter import AgnoStreamAdapter

{digitalkin-1.0.1.dev0 → digitalkin-1.0.2.dev1}/src/digitalkin/community/agno/hitl.py

@@ -23,6 +23,7 @@ if TYPE_CHECKING:
     from agno.agent import Agent
     from agno.run.agent import RunOutput
 
+    from digitalkin.community.agno.toolkits.tool_loader import ToolLoaderTools
     from digitalkin.models.events import BaseAgentRunEvent
     from digitalkin.models.module import ModuleContext
     from digitalkin.services.storage import StorageStrategy
@@ -78,8 +79,10 @@ class PausedRunStore:
         seen: set[str] = set()
         pending: list[str] = []
         for tool in run_output.tools or []:
-            tid = getattr(tool, "tool_call_id", None)
-            if tid and tid not in seen and getattr(tool, "external_execution_required", False):
+            tid = tool.tool_call_id
+            # Skip tools already resolved in-process (e.g. a use_setup call handled by the
+            # runner): only genuinely unresolved external tools go to the front.
+            if tid and tid not in seen and tool.external_execution_required and tool.result is None:
                 seen.add(tid)
                 pending.append(tid)
         record = PausedRunRecord(
@@ -303,6 +306,7 @@ class AgnoHitlRunner:
         storage: StorageStrategy | None = None,
         store: PausedRunStore | None = None,
         dependency_key: str = "agui_tools",
+        tool_loader: ToolLoaderTools | None = None,
     ) -> None:
         """Initialize the runner.
 
@@ -314,6 +318,12 @@ class AgnoHitlRunner:
             store: Pre-built paused-run store; wins over ``storage``.
             dependency_key: Agno dependencies key carrying the AG-UI tool
                 list (must match :func:`make_tools_factory`).
+            tool_loader: The :class:`ToolLoaderTools` bound to the agent's tool list
+                (``ToolLoaderTools.find(tools)``). When present, a ``use_setup`` pause is
+                resolved and the run auto-continues instead of surfacing to the front.
+                When omitted, the runner locates it in ``agent.tools`` itself — otherwise
+                a ``use_setup`` pause would surface to the front as a frontend tool no
+                client implements, wedging the thread.
 
         Raises:
             ValueError: If neither ``storage`` nor ``store`` is provided.
@@ -323,9 +333,18 @@ class AgnoHitlRunner:
                 msg = "AgnoHitlRunner requires either `storage` or `store`."
                 raise ValueError(msg)
             store = PausedRunStore(storage)
+        if tool_loader is None:
+            # Lazy import: ToolLoaderTools requires the optional agno dependency at
+            # import time, while this module must stay importable without it (same
+            # convention as the rest of community.agno). vars(): test fakes may not
+            # carry a tools attribute at all.
+            from digitalkin.community.agno.toolkits.tool_loader import ToolLoaderTools
+
+            tool_loader = ToolLoaderTools.find(vars(agent).get("tools"))
         self._agent = agent
         self._store = store
         self._dependency_key = dependency_key
+        self._tool_loader = tool_loader
 
     async def run(
         self,
@@ -360,7 +379,9 @@ class AgnoHitlRunner:
             yield_run_output=True,
             dependencies={self._dependency_key: agui_tools or []},
         )
-        return await self._drive(stream=stream, send=send, thread_id=thread_id, run_output_cls=RunOutput)
+        return await self._drive(
+            stream=stream, send=send, thread_id=thread_id, run_output_cls=RunOutput, agui_tools=agui_tools
+        )
 
     async def continue_paused_run(
         self,
@@ -437,7 +458,9 @@ class AgnoHitlRunner:
             yield_run_output=True,
             dependencies={self._dependency_key: agui_tools or []},
         )
-        pause_info = await self._drive(stream=stream, send=send, thread_id=thread_id, run_output_cls=RunOutput)
+        pause_info = await self._drive(
+            stream=stream, send=send, thread_id=thread_id, run_output_cls=RunOutput, agui_tools=agui_tools
+        )
 
         if pause_info is None:
             await self._store.delete(thread_id)
@@ -612,31 +635,108 @@ class AgnoHitlRunner:
         send: Callable[[BaseAgentRunEvent], Coroutine[Any, Any, None]],
         thread_id: str,
         run_output_cls: type[RunOutput],
+        agui_tools: list[AgUiTool] | None = None,
     ) -> PauseInfo | None:
-        """Drain an Agno stream, forward events, persist on pause.
+        """Drain an Agno stream, forward events, and persist or auto-continue on pause.
+
+        A ``use_setup`` pause (dynamic tool load) is resolved in-process and the run
+        auto-continues with the enlarged tool list; a frontend-tool pause is persisted and
+        surfaced. The loop is bounded so a model that keeps calling ``use_setup`` cannot spin
+        forever.
+
+        Args:
+            stream: The Agno event stream to drain.
+            send: Digitalkin-event callback for each forwarded event.
+            thread_id: AG-UI thread identifier (storage key on a frontend pause).
+            run_output_cls: The ``RunOutput`` class used to spot the terminal run object.
+            agui_tools: Frontend tools to re-pass to Agno on an auto-continue.
 
         Returns:
-            :class:`PauseInfo` on pause, ``None`` otherwise.
+            :class:`PauseInfo` on a frontend pause, ``None`` on completion.
         """
         from digitalkin.community.agno.agno_adapter import AgnoStreamAdapter
 
-        adapter = AgnoStreamAdapter()
-        final_run_output: RunOutput | None = None
+        for _ in range(20):
+            adapter = AgnoStreamAdapter()
+            final_run_output: RunOutput | None = None
 
-        async for raw_event in stream:
-            if isinstance(raw_event, run_output_cls):
-                final_run_output = raw_event
-                continue
-            for event in adapter.to_digitalkin_events(raw_event):
+            async for raw_event in stream:
+                if isinstance(raw_event, run_output_cls):
+                    final_run_output = raw_event
+                    continue
+                for event in adapter.to_digitalkin_events(raw_event):
+                    await send(event)
+
+            for event in adapter.flush():
                 await send(event)
 
-        for event in adapter.flush():
-            await send(event)
+            if not (adapter.is_paused and final_run_output is not None and final_run_output.is_paused):
+                return None
+
+            # Resolve any use_setup calls in-process; if the pause has nothing left for the
+            # front, auto-continue so discover -> load -> use reads as a single turn.
+            if await self._load_paused_tools(final_run_output) and not self._pending_external(final_run_output):
+                stream = self._agent.acontinue_run(
+                    run_response=final_run_output,
+                    stream=True,
+                    stream_events=True,
+                    yield_run_output=True,
+                    dependencies={self._dependency_key: agui_tools or []},
+                )
+                continue
 
-        if adapter.is_paused and final_run_output is not None and getattr(final_run_output, "is_paused", False):
             pause_info = await self._store.save(run_output=final_run_output, thread_id=thread_id)
             # Attach AG-UI-shaped messages so the front can materialise the tool_call.
             pause_info.new_messages = HitlEvents.agno_messages_to_agui(final_run_output.messages or [])
             return pause_info
 
+        logger.warning("AgnoHitlRunner: auto-continue limit reached for thread_id=%s", thread_id)
+        from digitalkin.models.events import AgentRunEvent, RunErrorEvent
+
+        await send(
+            RunErrorEvent(
+                event=AgentRunEvent.RUN_ERROR,
+                error_type="auto_continue_limit",
+                content=(
+                    "The run was stopped after too many consecutive in-process tool "
+                    "loads (use_setup). Send a new message to continue."
+                ),
+                error_details=None,
+                timestamp=None,
+                metadata=None,
+            )
+        )
         return None
+
+    async def _load_paused_tools(self, run_output: RunOutput) -> bool:
+        """Resolve ``use_setup`` calls in a paused run, writing each tool result in place.
+
+        Args:
+            run_output: The paused Agno run.
+
+        Returns:
+            ``True`` if at least one ``use_setup`` call was handled, else ``False`` (no
+            loader wired, or the pause carries only frontend tools).
+        """
+        if self._tool_loader is None:
+            return False
+        handled = False
+        loader_tool = self._tool_loader.tool_name
+        for tool in run_output.tools or []:
+            if tool.external_execution_required and tool.result is None and tool.tool_name == loader_tool:
+                setup_id = (tool.tool_args or {}).get("setup_id", "")
+                tool.result = await self._tool_loader.load(setup_id)
+                handled = True
+        return handled
+
+    @staticmethod
+    def _pending_external(run_output: RunOutput) -> bool:
+        """Report whether any external tool in the paused run still needs a result.
+
+        Args:
+            run_output: The paused Agno run (after :meth:`_load_paused_tools`).
+
+        Returns:
+            ``True`` if a frontend tool call remains unresolved (must go to the front).
+        """
+        return any(tool.external_execution_required and tool.result is None for tool in run_output.tools or [])

{digitalkin-1.0.1.dev0 → digitalkin-1.0.2.dev1}/src/digitalkin/community/agno/module_toolkit.py

@@ -16,10 +16,10 @@ from typing import Any
 
 from ag_ui.core.events import CustomEvent as AgUiCustomEvent
 from agno.media import Image
-from agno.tools import Toolkit
 from agno.tools.function import Function, ToolResult
 
 from digitalkin.community.agno.models import ToolCallMetadata, ToolOutputMetadata
+from digitalkin.community.agno.toolkits.base import DkToolkit
 from digitalkin.core.profiling.step_timer import StepTimer
 from digitalkin.logger import logger
 from digitalkin.models.module import ModuleContext
@@ -38,7 +38,7 @@ TOOL_CONTENT_PROTOCOL = "tool_content"
 AGUI_CUSTOM_PROTOCOL = "agui_custom"
 
 
-class ModuleToolkit(Toolkit):
+class ModuleToolkit(DkToolkit):
     """Agno Toolkit wrapper for SDK module tools.
 
     Wraps a ToolModuleInfo containing multiple ToolDefinitions into
@@ -170,7 +170,7 @@ class ModuleToolkit(Toolkit):
             or tool_module_info.module_name
             or tool_module_info.slug.replace(":", "_").replace(".", "_")
         )
-        super().__init__(name=f"{toolkit_name}_toolkit", tools=agno_functions)
+        super().__init__(name=f"{toolkit_name}_toolkit", tools=agno_functions, context=self._context)
 
     @property
     def module_id(self) -> str:

digitalkin-1.0.2.dev1/src/digitalkin/community/agno/toolkits/__init__.py

@@ -0,0 +1,24 @@
+"""Default Agno toolkits for DigitalKin modules.
+
+Requires the optional ``agno`` dependency — importing this subpackage without
+``agno`` installed raises ModuleNotFoundError. The parent
+``digitalkin.community.agno`` package stays importable without agno.
+"""
+
+from digitalkin.community.agno.toolkits.base import DkToolkit
+from digitalkin.community.agno.toolkits.chat_history import ChatHistoryTools
+from digitalkin.community.agno.toolkits.defaults import DefaultToolkits
+from digitalkin.community.agno.toolkits.registry import RegistryTools
+from digitalkin.community.agno.toolkits.setup import SetupTools
+from digitalkin.community.agno.toolkits.tool_loader import ToolLoaderTools
+from digitalkin.community.agno.toolkits.user_profile import UserProfileTools
+
+__all__ = [
+    "ChatHistoryTools",
+    "DefaultToolkits",
+    "DkToolkit",
+    "RegistryTools",
+    "SetupTools",
+    "ToolLoaderTools",
+    "UserProfileTools",
+]

digitalkin-1.0.2.dev1/src/digitalkin/community/agno/toolkits/base.py

@@ -0,0 +1,103 @@
+"""Shared base for DigitalKin agno toolkits.
+
+Codifies the format/return conventions established by
+:class:`~digitalkin.community.agno.module_toolkit.ModuleToolkit`: a canonical
+``{"output"|"error", "metadata"}`` JSON envelope (:meth:`_ok`/:meth:`_fail`) and
+best-effort AG-UI custom-event notifications on the agent's own stream
+(:meth:`_notify`). Every toolkit returns consistently and never raises into the
+agent loop.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from ag_ui.core.events import CustomEvent as AgUiCustomEvent
+from agno.tools import Toolkit
+
+from digitalkin.logger import logger
+from digitalkin.models.module.ag_ui import AgUiCustomEventOutput, AgUiOutput
+
+if TYPE_CHECKING:
+    from digitalkin.models.module import ModuleContext
+
+
+class DkToolkit(Toolkit):
+    """Base class for DigitalKin agno toolkits.
+
+    Subclasses register bound async tool methods and return via :meth:`_ok`/
+    :meth:`_fail` so the agent always receives the same envelope and the tool
+    never raises. Passing a :class:`ModuleContext` enables :meth:`_notify`,
+    which pushes AG-UI custom events onto the caller's gRPC stream.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        tools: list[Any],
+        context: ModuleContext | None = None,
+        external_execution_required_tools: list[str] | None = None,
+    ) -> None:
+        """Initialize the toolkit.
+
+        Args:
+            name: Toolkit name registered with Agno.
+            tools: Bound tool callables to expose to the agent.
+            context: Module context; when present, :meth:`_notify` can emit AG-UI events.
+            external_execution_required_tools: Tool names Agno must pause on (executed
+                outside the agent loop) instead of running their entrypoint.
+        """
+        self._ctx = context
+        super().__init__(
+            name=name,
+            tools=tools,
+            external_execution_required_tools=external_execution_required_tools or [],
+        )
+
+    @staticmethod
+    def _ok(output: Any, **metadata: Any) -> str:
+        """Build the canonical success envelope.
+
+        Args:
+            output: The tool result payload (JSON-serializable).
+            metadata: Extra metadata fields (e.g. ``tool``).
+
+        Returns:
+            JSON string ``{"output": ..., "metadata": {"success": true, ...}}``.
+        """
+        return json.dumps({"output": output, "metadata": {"success": True, **metadata}}, ensure_ascii=False)
+
+    @staticmethod
+    def _fail(error: str, **metadata: Any) -> str:
+        """Build the canonical error envelope.
+
+        Args:
+            error: Human/LLM-readable error message.
+            metadata: Extra metadata fields (e.g. ``tool``).
+
+        Returns:
+            JSON string ``{"error": ..., "metadata": {"success": false, ...}}``.
+        """
+        return json.dumps({"error": error, "metadata": {"success": False, **metadata}}, ensure_ascii=False)
+
+    async def _notify(self, name: str, value: Any) -> None:
+        """Emit an AG-UI custom event on the agent's output stream (best-effort).
+
+        No-op when there is no context or ``send_message`` is not installed (e.g. outside a
+        running job). Never raises — a notification failure must not fail the tool call.
+
+        Args:
+            name: Custom event name.
+            value: Custom event payload (JSON-serializable).
+        """
+        if self._ctx is None:
+            return
+        # callbacks is a dict-driven SimpleNamespace; send_message is attached during prepare().
+        send_message = vars(self._ctx.callbacks).get("send_message")
+        if send_message is None:
+            return
+        try:
+            await send_message(AgUiOutput(root=AgUiCustomEventOutput(event=AgUiCustomEvent(name=name, value=value))))
+        except Exception:
+            logger.exception("Failed to emit custom event '%s' to the agent stream", name)