digitalkin 0.4.0.dev1__tar.gz → 0.4.1.dev1__tar.gz

{digitalkin-0.4.0.dev1 → digitalkin-0.4.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 0.4.0.dev1
+Version: 0.4.1.dev1
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International

{digitalkin-0.4.0.dev1 → digitalkin-0.4.1.dev1}/pyproject.toml

@@ -35,7 +35,7 @@
         "grpcio-status==1.78.0",
         "pydantic==2.12.5",
     ]
-    version = "0.4.0.dev1"
+    version = "0.4.1.dev1"
 
     [project.optional-dependencies]
         profiling = [

{digitalkin-0.4.0.dev1 → digitalkin-0.4.1.dev1}/src/digitalkin/__version__.py

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

digitalkin-0.4.1.dev1/src/digitalkin/community/agno/__init__.py

@@ -0,0 +1,43 @@
+"""Agno framework integration for DigitalKin.
+
+Adapters, converters, and HITL helpers for building DigitalKin modules
+on top of the Agno agent framework. Exports:
+
+- :class:`AgnoStreamAdapter` — Agno streaming events → DigitalKin events.
+- :func:`agui_tool_to_external_function` / :func:`make_tools_factory` —
+  register AG-UI client-side (frontend) tools as Agno external Functions.
+- :class:`AgnoHitlRunner`, :class:`PausedRunStore`, :class:`PauseInfo`,
+  :class:`PausedRunRecord`, :data:`HITL_STORAGE_CONFIG`,
+  :func:`emit_awaiting_tool_result` — human-in-the-loop (HITL) runner
+  that persists a paused Agno run via the module's
+  :class:`~digitalkin.services.storage.StorageStrategy` and resumes it
+  when the front replies with a ``ToolMessage``.
+"""
+
+from digitalkin.community.agno.agno_adapter import AgnoStreamAdapter
+from digitalkin.community.agno.agui_tools import (
+    agui_tool_to_external_function,
+    make_tools_factory,
+)
+from digitalkin.community.agno.hitl import (
+    HITL_STORAGE_CONFIG,
+    AgnoHitlRunner,
+    PausedRunRecord,
+    PausedRunStore,
+    PauseInfo,
+    emit_awaiting_tool_result,
+    emit_messages_snapshot,
+)
+
+__all__ = [
+    "HITL_STORAGE_CONFIG",
+    "AgnoHitlRunner",
+    "AgnoStreamAdapter",
+    "PauseInfo",
+    "PausedRunRecord",
+    "PausedRunStore",
+    "agui_tool_to_external_function",
+    "emit_awaiting_tool_result",
+    "emit_messages_snapshot",
+    "make_tools_factory",
+]

{digitalkin-0.4.0.dev1 → digitalkin-0.4.1.dev1}/src/digitalkin/community/agno/agno_adapter.py

@@ -69,8 +69,30 @@ class AgnoStreamAdapter:
         self._active_run_id: str | None = None
         self._completed_run_ids: set[str] = set()
 
+        # HITL pause state — populated when a RunPausedEvent is seen
+        # (tools with external_execution=True). Callers can inspect these
+        # after streaming to decide whether to persist and resume later.
+        self._is_paused: bool = False
+        self._paused_tool_executions: list[Any] = []
+        self._paused_requirements: list[Any] = []
+
         self._dispatch: dict[Any, Callable[[Any, Any], list[BaseAgentRunEvent]]] | None = None
 
+    @property
+    def is_paused(self) -> bool:
+        """Whether the last stream ended on a run_paused event (external tool HITL)."""
+        return self._is_paused
+
+    @property
+    def paused_tool_executions(self) -> list[Any]:
+        """Agno ``ToolExecution`` objects awaiting external execution (HITL)."""
+        return list(self._paused_tool_executions)
+
+    @property
+    def paused_requirements(self) -> list[Any]:
+        """Agno ``RunRequirement`` objects carried by the paused run."""
+        return list(self._paused_requirements)
+
     def to_digitalkin_events(self, agno_event: Any) -> list[BaseAgentRunEvent]:
         """Convert one Agno event into one or more DigitalKin events.
 
@@ -95,6 +117,7 @@ class AgnoStreamAdapter:
                 RunEvent.run_content: self._handle_run_content,
                 RunEvent.run_completed: self._handle_run_completed,
                 RunEvent.run_error: self._handle_run_error,
+                RunEvent.run_paused: self._handle_run_paused,
                 RunEvent.reasoning_started: self._handle_reasoning_started,
                 RunEvent.reasoning_content_delta: self._handle_reasoning_content_delta,
                 RunEvent.reasoning_step: self._handle_reasoning_step,
@@ -331,6 +354,82 @@ class AgnoStreamAdapter:
             )
         ]
 
+    def _handle_run_paused(self, agno_event: Any, timestamp: Any) -> list[BaseAgentRunEvent]:
+        """Handle ``RunEvent.run_paused`` — HITL pause on external tool execution.
+
+        Agno does NOT emit ``tool_call_started`` / ``tool_call_completed`` for
+        tools declared with ``external_execution=True`` (see
+        ``agno/models/base.py`` where the emission is short-circuited). The
+        front therefore never sees the corresponding AG-UI ``ToolCallStart``
+        / ``ToolCallArgs`` / ``ToolCallEnd`` events unless we synthesize them.
+
+        This handler:
+
+        1. Closes any active reasoning / content sequence.
+        2. Iterates ``RunPausedEvent.tools`` and emits one pair of
+           ``ToolCallStartedEvent`` + ``ToolCallCompletedEvent`` per tool.
+           The ``ToolCallCompletedEvent`` carries ``content=None`` and
+           ``tool.result=None`` so the downstream AG-UI bridge emits
+           ``ToolCallEnd`` *without* a ``ToolCallResult`` (guarded by the
+           ``if result_content:`` check in ``AgUiMixin``).
+        3. Records pause state on the adapter (``is_paused``,
+           ``paused_tool_executions``, ``paused_requirements``) so callers
+           can detect the pause after streaming and persist the run for
+           later resumption.
+
+        Returns:
+            Synthesized tool-call events for the paused tools. The caller
+            is responsible for subsequently emitting the AG-UI
+            ``RunFinished`` with ``result.status = "awaiting_tool_result"``
+            — this adapter stays protocol-agnostic.
+        """
+        events: list[BaseAgentRunEvent] = []
+
+        if self._reasoning_active:
+            events.extend(self._close_reasoning(timestamp))
+        if self._content_active:
+            events.extend(self._close_content(timestamp))
+
+        tools = getattr(agno_event, "tools", None) or []
+        requirements = getattr(agno_event, "requirements", None) or []
+
+        self._is_paused = True
+        self._paused_tool_executions = list(tools)
+        self._paused_requirements = list(requirements)
+
+        for tool_exec in tools:
+            tool_call_id = getattr(tool_exec, "tool_call_id", None)
+            tool_info = ToolInfo(
+                tool_call_id=tool_call_id,
+                tool_name=getattr(tool_exec, "tool_name", None),
+                tool_args=getattr(tool_exec, "tool_args", None),
+                result=None,
+            )
+            logger.debug(
+                "Synthesizing tool-call events for external_execution tool %s (id=%s)",
+                tool_info.tool_name,
+                tool_call_id,
+            )
+            events.extend((
+                ToolCallStartedEvent(
+                    event=AgentRunEvent.TOOL_CALL_STARTED,
+                    tool=tool_info,
+                    timestamp=timestamp,
+                    metadata=None,
+                ),
+                ToolCallCompletedEvent(
+                    event=AgentRunEvent.TOOL_CALL_COMPLETED,
+                    tool=tool_info,
+                    content=None,
+                    timestamp=timestamp,
+                    metadata=None,
+                ),
+            ))
+            if tool_call_id:
+                self._closed_tool_call_ids.add(tool_call_id)
+
+        return events
+
     def _handle_tool_call_error(self, agno_event: Any, timestamp: Any) -> list[BaseAgentRunEvent]:
         """Handle RunEvent.tool_call_error.
 

digitalkin-0.4.1.dev1/src/digitalkin/community/agno/agui_tools.py

@@ -0,0 +1,122 @@
+"""AG-UI frontend tools → Agno external Functions.
+
+The AG-UI protocol lets the client declare its own tools in
+``RunAgentInput.tools``. Those tools are meant to be executed on the
+frontend (a UI widget, a browser-local API call, a user prompt, …) rather
+than by the agent process. This module provides the glue to expose them
+to an Agno :class:`~agno.agent.Agent` as regular :class:`~agno.tools.function.Function`
+objects marked with ``external_execution=True``: when the LLM "calls" one,
+Agno pauses the run (via :class:`~agno.run.agent.RunPausedEvent`) instead
+of executing an entrypoint — letting the caller stream the tool-call
+events to the front and resume later via :meth:`~agno.agent.Agent.acontinue_run`.
+
+Usage::
+
+    from digitalkin.community.agno import make_tools_factory
+    from agno.agent import Agent
+
+    agent = Agent(
+        tools=make_tools_factory([AsyncDuckDuckGoTools()]),
+        cache_callables=False,           # critical — see make_tools_factory
+        ...
+    )
+
+    async for ev in agent.arun(
+        message,
+        dependencies={"agui_tools": input_data.tools},
+        stream=True,
+        stream_events=True,
+    ):
+        ...
+
+Notes:
+    ``dependencies`` is Agno's standard per-run injection bus. We use it
+    as a transport channel to hand the frontend tools to the tools
+    factory on every run — the tools themselves are actually registered
+    through the ``tools=factory`` mechanism, not through ``dependencies``.
+    ``cache_callables=False`` is required so the factory is re-invoked on
+    each run (otherwise the first resolved tool list is cached forever and
+    subsequent requests would not see new frontend tools).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ag_ui.core.types import Tool as AgUiTool
+    from agno.run.base import RunContext
+    from agno.tools.function import Function
+
+_DEFAULT_DEPENDENCY_KEY = "agui_tools"
+
+
+def _unreachable_entrypoint(**_: Any) -> None:
+    """Placeholder — never invoked because ``external_execution=True`` pauses the run."""
+
+
+def agui_tool_to_external_function(tool: AgUiTool) -> Function:
+    """Wrap an AG-UI tool definition as an Agno external ``Function``.
+
+    The resulting :class:`Function` carries the AG-UI schema as-is (Agno
+    accepts raw JSON Schema via ``parameters``) and is marked with
+    ``external_execution=True`` so Agno emits the tool-call events but
+    skips the entrypoint and pauses the run when the LLM invokes it.
+
+    Args:
+        tool: An :class:`ag_ui.core.types.Tool` from ``RunAgentInput.tools``.
+
+    Returns:
+        An :class:`agno.tools.function.Function` ready to be plugged into
+        an Agno agent's tool list.
+    """
+    from agno.tools.function import Function  # pyright: ignore[reportMissingImports]
+
+    parameters = tool.parameters or {"type": "object", "properties": {}, "required": []}
+    return Function(
+        name=tool.name,
+        description=tool.description,
+        parameters=parameters,
+        entrypoint=_unreachable_entrypoint,
+        external_execution=True,
+        skip_entrypoint_processing=True,
+    )
+
+
+def make_tools_factory(
+    base_tools: list[Any],
+    dependency_key: str = _DEFAULT_DEPENDENCY_KEY,
+) -> Callable[[RunContext], list[Any]]:
+    """Build an Agno ``tools`` factory that merges base tools with per-run AG-UI tools.
+
+    The returned callable is the value you pass to ``Agent(tools=...)``. On
+    every run, Agno resolves the factory with the current
+    :class:`~agno.run.base.RunContext` (see
+    :func:`agno.utils.callables.aresolve_callable_tools`). The factory
+    reads ``run_context.dependencies[dependency_key]`` — the list of
+    :class:`~ag_ui.core.types.Tool` you passed via
+    ``agent.arun(dependencies={dependency_key: [...]})`` — converts them to
+    external :class:`Function` objects, and concatenates them with the
+    ``base_tools``.
+
+    Args:
+        base_tools: Toolkits / Functions always available to the agent
+            (e.g. ``AsyncDuckDuckGoTools()``). Passed through unchanged.
+        dependency_key: The key in ``run_context.dependencies`` under which
+            the caller places the per-run AG-UI tool list. Defaults to
+            ``"agui_tools"``.
+
+    Returns:
+        A callable suitable for :class:`agno.agent.Agent`'s ``tools=``
+        parameter. Set ``cache_callables=False`` on the ``Agent`` so this
+        factory is re-invoked on every run.
+    """
+
+    def factory(run_context: RunContext) -> list[Any]:
+        deps = getattr(run_context, "dependencies", None) or {}
+        agui_tools: list[AgUiTool] = deps.get(dependency_key) or []
+        return [*base_tools, *[agui_tool_to_external_function(t) for t in agui_tools]]
+
+    return factory