digitalkin 1.0.5.dev2__tar.gz → 1.0.5.dev4__tar.gz

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.5.dev2
+Version: 1.0.5.dev4
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International
@@ -453,7 +453,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ag-ui-protocol==0.1.21.dev1787220377
-Requires-Dist: agentic-mesh-protocol==1.0.1
+Requires-Dist: agentic-mesh-protocol==1.0.2
 Requires-Dist: agno<3,>=2.8.0
 Requires-Dist: anyio>=4.13.0
 Requires-Dist: grpcio-health-checking==1.82.1

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/examples/services/filesystem_module.py

@@ -10,7 +10,8 @@ from pydantic import BaseModel, Field
 from digitalkin.logger import logger
 from digitalkin.models.module import ModuleStatus
 from digitalkin.modules.archetype_module import ArchetypeModule
-from digitalkin.services.filesystem.filesystem_strategy import FileFilter, UploadFileData
+from digitalkin.models.services.filesystem import FileType
+from digitalkin.services.filesystem import FileFilter, UploadFileData
 from digitalkin.services.services_config import ServicesConfig
 from digitalkin.services.services_models import ServicesMode
 
@@ -118,9 +119,9 @@ class ExampleModule(ArchetypeModule[ExampleInput, ExampleOutput, ExampleSetup, E
         file = UploadFileData(
             content=b"%s\n%s" % (processed_message.encode(), str(processed_number).encode()),
             name="example_output.txt",
-            file_type="text/plain",
+            type=FileType.DOCUMENT,
             content_type="text/plain",
-            metadata={"example_key": "example_value"},
+            metadata={"sdk_created": True},
             replace_if_exists=True,
         )
 
@@ -176,10 +177,10 @@ async def test_module() -> None:
     # Check the storage
     if module.status == ModuleStatus.STOPPED:
         files, _nb_results = await module.filesystem.get_files(
-            filters=FileFilter(name="example_output.txt", context="test-mission-123"),
+            filters=FileFilter(names=["example_output.txt"]),
         )
         for file in files:
-            await module.filesystem.update_file(file.id, file_type="updated")
+            await module.filesystem.update_file(file.id, type=FileType.OTHER)
             # module.filesystem.delete_files(filters=FileFilter(name="example_output.txt", context="test-mission-123"), permanent=True)
 
             logger.info("Retrieved file: %s with ID: %s", file.name, file.id)
@@ -188,7 +189,7 @@ async def test_module() -> None:
                 if file_record:
                     logger.info("File ID: %s", file_record.id)
                     logger.info("File name: %s", file_record.name)
-                    logger.info("File type: %s", file_record.file_type)
+                    logger.info("File type: %s", file_record.type)
                     logger.info("File status: %s", file_record.status)
                     logger.info("File content: %s", file_record.content.decode())
             except Exception:

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/pyproject.toml

@@ -31,7 +31,7 @@
         # which is how a nested run's output is attributed to its author. Pinned exactly
         # because it is a dated prerelease; move to >=0.1.21 once that ships stable.
         "ag-ui-protocol==0.1.21.dev1787220377",
-        "agentic-mesh-protocol==1.0.1",
+        "agentic-mesh-protocol==1.0.2",
         "agno>=2.8.0,<3",
         "anyio>=4.13.0",
         "grpcio-health-checking==1.82.1",
@@ -41,7 +41,7 @@
         "pydantic>=2.12.4",
         "redis[hiredis]>=7.4.0,<9",
     ]
-    version = "1.0.5.dev2"
+    version = "1.0.5.dev4"
 
     [project.optional-dependencies]
         agno = [ "agno>=2.6" ]
@@ -208,15 +208,15 @@
         ]
 
         ignore = [
-            "ANN401",  # Allow typing.Any — gRPC stubs, callbacks, and dynamic APIs require it
-            "COM812",  # Disable because of formatter incompatibility
-            "DOC502",  # Allow extraneous-exception in docstring
-            "F401",    # Allow unused imports — used for availability checks
-            "N802",    # Allow PascalCase methods — gRPC servicer convention
-            "PLC0415", # Allow lazy imports — needed to break circular dependencies
-            "PLW3201", # Allow __get_pydantic_core_schema__ — Pydantic dunder hook
-            "S105",    # Hardcoded-password
-            "S403",    # Allow pickle import
+            "any-type",                       # Allow typing.Any — gRPC stubs, callbacks, and dynamic APIs require it
+            "missing-trailing-comma",         # Disable because of formatter incompatibility
+            "docstring-extraneous-exception", # Allow extraneous-exception in docstring
+            "unused-import",                  # Allow unused imports — used for availability checks
+            "invalid-function-name",          # Allow PascalCase methods — gRPC servicer convention
+            "import-outside-top-level",       # Allow lazy imports — needed to break circular dependencies
+            "bad-dunder-method-name",         # Allow __get_pydantic_core_schema__ — Pydantic dunder hook
+            "hardcoded-password-string",      # Hardcoded-password
+            "suspicious-pickle-import",       # Allow pickle import
         ]
 
         fixable = [ "ALL" ]
@@ -226,40 +226,40 @@
 
         [tool.ruff.lint.per-file-ignores]
             "tests/**/*.py" = [
-                "ANN001",
-                "ANN002",
-                "ANN003",
-                "ANN201",
-                "ANN401",
-                "ARG001",
-                "ARG002",
-                "C901",
-                "D100",
-                "D101",
-                "D102",
-                "D103",
-                "D107",
-                "D417",
-                "DOC201",
-                "DOC501",
-                "E501",
-                "ERA001",
-                "FBT001",
-                "FBT002",
-                "G004",
-                "N802",
-                "PERF203",
-                "PLC2701",
-                "PLR0911",
-                "PLR0912",
-                "PLR0914",
-                "PLR0915",
-                "PLR1702",
-                "PLR2004",
-                "PLR6301",
-                "S101",
-                "SLF001",
-                "TRY002",
+                "missing-type-function-argument",
+                "missing-type-args",
+                "missing-type-kwargs",
+                "missing-return-type-undocumented-public-function",
+                "any-type",
+                "unused-function-argument",
+                "unused-method-argument",
+                "complex-structure",
+                "undocumented-public-module",
+                "undocumented-public-class",
+                "undocumented-public-method",
+                "undocumented-public-function",
+                "undocumented-public-init",
+                "undocumented-param",
+                "docstring-missing-returns",
+                "docstring-missing-exception",
+                "line-too-long",
+                "commented-out-code",
+                "boolean-type-hint-positional-argument",
+                "boolean-default-value-positional-argument",
+                "logging-f-string",
+                "invalid-function-name",
+                "try-except-in-loop",
+                "import-private-name",
+                "too-many-return-statements",
+                "too-many-branches",
+                "too-many-locals",
+                "too-many-statements",
+                "too-many-nested-blocks",
+                "magic-value-comparison",
+                "no-self-use",
+                "assert",
+                "private-member-access",
+                "raise-vanilla-class",
             ]
 
         [tool.ruff.lint.pylint]

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/src/digitalkin/__version__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("digitalkin")
 except PackageNotFoundError:
-    __version__ = "1.0.5.dev2"
+    __version__ = "1.0.5.dev4"

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/src/digitalkin/community/agno/agno_adapter.py

@@ -676,6 +676,26 @@ class AgnoStreamAdapter:
             self._closed_tool_call_ids.add(tool_call_id)
 
         content = agno_event.content
+        if tool is not None and tool.tool_call_error:
+            # Agno flags a raised tool on the completed event, then sends a tool_call_error
+            # that the closed-id check drops — so the failure is surfaced here.
+            # TODO(validate): AGUI-TOOL-FAILED-STATUS a raised tool surfaces as ToolCallError, not success
+            logger.info(
+                "[VALIDATE AGUI-TOOL-FAILED-STATUS] tool %s (id=%s) failed: %s",
+                tool.tool_name,
+                tool_call_id,
+                tool.result,
+            )
+            return [
+                ToolCallErrorEvent(
+                    event=AgentRunEvent.TOOL_CALL_ERROR,
+                    tool=tool_info,
+                    error_message=str(tool.result) if tool.result else None,
+                    subagent_run_id=self._subagent_of(self._run_key),
+                    timestamp=timestamp,
+                    metadata=self._last_metadata,
+                )
+            ]
         return [
             ToolCallCompletedEvent(
                 event=AgentRunEvent.TOOL_CALL_COMPLETED,

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/src/digitalkin/community/agno/hitl.py

@@ -11,6 +11,7 @@ import json
 import logging
 from typing import TYPE_CHECKING, Any, ClassVar
 
+from ag_ui.core.events import Interrupt, RunFinishedInterruptOutcome
 from pydantic import BaseModel, ConfigDict, Field
 
 from digitalkin.community.agno.models import PauseInfo
@@ -268,13 +269,14 @@ class HitlEvents:
         run_id: str,
         pending_tool_call_ids: list[str],
     ) -> None:
-        """Emit an AG-UI ``RunFinished`` with ``status="awaiting_tool_result"``.
+        """Emit an AG-UI ``RunFinished`` with an interrupt outcome.
 
         This is the protocol signal telling the front "the run paused on a
-        client-side tool; execute it and reply with a ``ToolMessage``". It
-        goes out via ``context.callbacks.send_message`` (bypassing the
-        standard :class:`~digitalkin.mixins.agui_mixin.AgUiMixin` event
-        mapping, which has no notion of an "awaiting" status).
+        client-side tool; execute it and reply with a ``ToolMessage``". The
+        standard ``outcome={type: "interrupt"}`` carries one interrupt per pending
+        tool; the legacy ``result.status="awaiting_tool_result"`` is kept for
+        existing clients. When an AG-UI run is open, its state first moves the
+        tools to ``awaiting_input`` and the run to ``interrupted``.
 
         Args:
             context: Current module context.
@@ -291,11 +293,31 @@ class HitlEvents:
             AgUiRunFinishedOutput,
         )
 
+        run = context.agui_run
+        tools = run.state["tools"] if run is not None else {}
+        interrupts = [
+            Interrupt(
+                id=tool_call_id,
+                reason="tool_call",
+                tool_call_id=tool_call_id,
+                message=f"Waiting for the result of {tools.get(tool_call_id, {}).get('name') or 'a frontend tool'}",
+            )
+            for tool_call_id in pending_tool_call_ids
+        ]
+        if run is not None and run.open:
+            run.open = False
+            await run.update(
+                context,
+                *((("tools", tid, "status"), "awaiting_input") for tid in pending_tool_call_ids if tid in tools),
+                (("interrupts",), [i.model_dump(mode="json", by_alias=True, exclude_none=True) for i in interrupts]),
+                (("run", "status"), "interrupted"),
+            )
         output = AgUiOutput(
             root=AgUiRunFinishedOutput(
                 event=AgUiRunFinishedEvent(
                     thread_id=thread_id,
                     run_id=run_id,
+                    outcome=RunFinishedInterruptOutcome(interrupts=interrupts) if interrupts else None,
                     result={
                         "status": _AWAITING_STATUS,
                         "pending_tool_call_ids": pending_tool_call_ids,

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/src/digitalkin/community/agno/module_toolkit.py

@@ -25,6 +25,7 @@ from digitalkin.logger import logger
 from digitalkin.models.module import ModuleContext
 from digitalkin.models.module.ag_ui import AgUiCustomEventOutput, AgUiOutput
 from digitalkin.models.module.tool_cache import ToolDefinition, ToolModuleInfo
+from digitalkin.services.communication.exceptions import ToolCallError
 
 # Default timeout for tool calls in seconds
 DEFAULT_TOOL_TIMEOUT_SECONDS = 300
@@ -265,7 +266,14 @@ class ModuleToolkit(DkToolkit):
         # callbacks is a dict-driven SimpleNamespace (module_context.py:168);
         # send_message may legitimately be absent outside a running job.
         send_message = vars(context.callbacks).get("send_message")
+        value = event.get("value")
+        url = value.get("url") if isinstance(value, dict) else None
         if send_message is None:
+            logger.warning(
+                "Dropped custom event '%s' url=%s: no send_message on the agent context",
+                event["name"],
+                url,
+            )
             return
 
         try:
@@ -275,10 +283,15 @@ class ModuleToolkit(DkToolkit):
             await send_message(
                 AgUiOutput(
                     root=AgUiCustomEventOutput(
-                        event=AgUiCustomEvent(name=event["name"], value=event.get("value")),
+                        event=AgUiCustomEvent(name=event["name"], value=value),
                     )
                 )
             )
+            logger.info(
+                "Relayed custom event '%s' url=%s to the agent stream",
+                event["name"],
+                url,
+            )
         except Exception:
             logger.exception("Failed to relay custom event '%s' to the agent stream", event["name"])
 
@@ -467,6 +480,10 @@ class ModuleToolkit(DkToolkit):
         Wraps the SDK module's async generator function into an async function
         that Agno can consume, with proper error handling and response formatting.
 
+        A failure raises ``ToolCallError`` carrying the same JSON body a success-path caller
+        would have read: Agno hands ``str(exc)`` to the model unchanged and flags the call
+        ``tool_call_error``, which is what marks the tool failed for the front.
+
         Returns:
             Async function that calls the SDK tool and returns a JSON result, or a
             ToolResult when the tool returned images alongside its text output.
@@ -509,14 +526,14 @@ class ModuleToolkit(DkToolkit):
                 duration_ms = round((time.perf_counter() - start_time) * 1000, 2)
                 error_msg = f"Tool '{tool_name}' timed out after {timeout}s"
                 logger.warning("%s task_id=%s", error_msg, task_id)
-                return handle_failure(tool_name, error_msg, duration_ms)
+                raise ToolCallError(handle_failure(tool_name, error_msg, duration_ms))
 
             except Exception as e:
                 outcome = "error"
                 duration_ms = round((time.perf_counter() - start_time) * 1000, 2)
                 error_msg = f"Failed to call tool '{tool_name}': {e!s}"
                 logger.warning("%s task_id=%s", error_msg, task_id, exc_info=True)
-                return handle_failure(tool_name, error_msg, duration_ms)
+                raise ToolCallError(handle_failure(tool_name, error_msg, duration_ms))
 
             else:
                 call_timer.mark("gen_consume")
@@ -536,7 +553,7 @@ class ModuleToolkit(DkToolkit):
 
                 outcome = "no_success"
                 error_msg = ModuleToolkit._extract_error_message(error_frame)
-                return handle_failure(tool_name, error_msg, duration_ms)
+                raise ToolCallError(handle_failure(tool_name, error_msg, duration_ms))
 
             finally:
                 call_timer.mark("respond")

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/src/digitalkin/community/agno/toolkits/registry/action.py

@@ -23,6 +23,7 @@ from digitalkin.models.services.registry import (
 
 if TYPE_CHECKING:
     from digitalkin.community.agno.toolkits.registry.base import RegistryActionCtx
+    from digitalkin.models.services.registry import SetupSummary
 
 
 class GetAction(RegistryAction):
@@ -124,23 +125,36 @@ class SearchAction(RegistryAction):
         # would both contradict ``total_returned`` and, at exactly ``cap`` rows, promise an empty
         # next page.
         truncated = len(usable) > cap
-        rows = [
-            {
-                "setup_id": setup.setup_id,
-                "name": setup.name,
-                "module_name": setup.module_name,
-                "version": setup.setup_version,
-                # Echoed because they are filterable: a caller cannot use the ``tags``,
-                # ``visibilities`` or ``statuses`` filters without first seeing the values in use.
-                "tags": setup.tags,
-                "visibility": setup.visibility.value if setup.visibility else None,
-                "status": setup.status.value if setup.status else None,
-                "description": (setup.documentation or "")[: self._DOC_PREVIEW_CHARS],
-            }
-            for setup in usable[:cap]
-        ]
+        rows = [self._row(setup) for setup in usable[:cap]]
         return {"total_returned": len(rows), "truncated": truncated, "offset": self.offset, "setups": rows}
 
+    def _row(self, setup: SetupSummary) -> dict[str, Any]:
+        """Trim one search hit to the fields a caller can act on.
+
+        Args:
+            setup: The summary returned by the registry.
+
+        Returns:
+            The rendered row.
+        """
+        row: dict[str, Any] = {
+            "setup_id": setup.setup_id,
+            "name": setup.name,
+            "module_name": setup.module_name,
+            "version": setup.setup_version,
+            # Echoed because they are filterable: a caller cannot use the ``tags``,
+            # ``visibilities`` or ``statuses`` filters without first seeing the values in use.
+            "tags": setup.tags,
+            "visibility": setup.visibility.value if setup.visibility else None,
+            "status": setup.status.value if setup.status else None,
+            "description": (setup.documentation or "")[: self._DOC_PREVIEW_CHARS],
+        }
+        # Only service setups carry a map. Omitting the key rather than rendering an empty
+        # one keeps the feature out of the tools and kins surfaces entirely.
+        if setup.structure:
+            row["structure"] = setup.structure
+        return row
+
 
 class UpdateAction(RegistryAction):
     """Update an instance: cut a new version of its configuration, and rename it.
@@ -166,6 +180,20 @@ class UpdateAction(RegistryAction):
         "without changing what the instance currently serves, then activate it later with "
         "``set_version``.",
     )
+    documentation: str | None = Field(
+        default=None,
+        description="Free text describing what this instance is for, indexed by ``search``. "
+        "Omit to keep the text the instance already has; pass a string to replace it, or an "
+        "empty string to clear it.",
+    )
+
+    def _type_payload(self) -> dict[str, Any]:  # ruff: ignore[no-self-use]
+        """Fields this object type adds to the update.
+
+        Returns:
+            Nothing by default; ``services_manager`` overrides it to refresh the structure map.
+        """
+        return {}
 
     async def execute(self, ctx: RegistryActionCtx) -> Any:
         """Cut a new version of the setup's content and rename it.
@@ -184,6 +212,10 @@ class UpdateAction(RegistryAction):
             "name": self.name,
             "content": self.content,
             "set_as_current": self.set_as_current,
+            "documentation": (
+                setup.current_setup_version.documentation if self.documentation is None else self.documentation
+            ),
+            **self._type_payload(),
         })
 
 

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/src/digitalkin/community/agno/toolkits/registry/base.py

@@ -171,22 +171,23 @@ class RegistryAction(BaseAction[RegistryActionCtx], ABC):
 
     writes: ClassVar[bool] = False
 
-    @field_validator("name", check_fields=False)
+    @field_validator("name", "documentation", check_fields=False)
     @classmethod
-    def _name_has_no_control_chars(cls, value: str) -> str:
-        """Reject control characters in a user-facing ``name`` so it fails loudly, not silently.
+    def _text_has_no_control_chars(cls, value: str | None) -> str | None:
+        """Reject control characters in user-facing free text so it fails loudly, not silently.
 
-        The action's ``name`` bypasses the content validator, so without this a NUL byte or ANSI
-        escape would reach persistence and be stripped there, altering the value without telling
-        the caller. Applies to any action declaring ``name`` (update, service create).
+        ``name`` and ``documentation`` bypass the content validator, so without this a NUL byte
+        or ANSI escape would reach persistence and be stripped there, altering the value without
+        telling the caller. Applies to any action declaring either (update, service create).
+        ``None`` is the "leave unchanged" marker on update and has nothing to check.
 
         Returns:
-            The name unchanged when clean.
+            The value unchanged when clean.
 
         Raises:
-            ValueError: The name carries a control character.
+            ValueError: The value carries a control character.
         """
-        return SetupContentValidator.reject_control_chars(value)
+        return value if value is None else SetupContentValidator.reject_control_chars(value)
 
     @field_validator("content", check_fields=False)
     @classmethod
@@ -346,7 +347,11 @@ class RegistryObjectToolKit(DkToolkit):
         Also echoes ``visibility`` back in the caller's vocabulary — the input enum is
         ``public``/``private``/``internal`` but the backend returns the proto name
         ``VISIBILITY_INTERNAL``, so a naive round-trip fails. Strip the prefix and
-        lower-case it so the field read back matches the field written.
+        lower-case it so the field read back matches the field written. Confined to the
+        model branch on purpose: every action carrying a real setup visibility returns a
+        ``SetupData``, while the actions returning a plain dict return a *configuration*
+        (``load``) or its key map (``structure``), where a key called ``visibility`` is the
+        service's own data and rewriting it would corrupt what the caller asked for.
 
         Args:
             value: A Pydantic model, proto message, or plain scalar/collection.

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/src/digitalkin/community/agno/toolkits/registry/loader/action.py

@@ -134,7 +134,7 @@ class LoadToolAction(LoadAction):
             )
         return None
 
-    async def execute(self, ctx: LoadActionCtx) -> LoadOutcome:  # noqa: C901, PLR0911 — each return is a distinct, LLM-readable outcome
+    async def execute(self, ctx: LoadActionCtx) -> LoadOutcome:  # ruff: ignore[complex-structure, too-many-return-statements] — each return is a distinct, LLM-readable outcome
         """Resolve the setup into a ModuleToolkit and append it to the live tool list.
 
         Idempotent per ``setup_id``; never raises. The setup's family is read first so a

{digitalkin-1.0.5.dev2 → digitalkin-1.0.5.dev4}/src/digitalkin/community/agno/toolkits/registry/loader/kit.py

@@ -63,7 +63,7 @@ class LoadManager(DkToolkit):
         """
         self._base_tools = base_tools
 
-    async def load_manager(self, action: LoadActions) -> str:  # noqa: ARG002 — schema-only stub, never run
+    async def load_manager(self, action: LoadActions) -> str:  # ruff: ignore[unused-method-argument] — schema-only stub, never run
         """Load a discovered object into the agent so it becomes usable right now.
 
         Loading is a two-step flow, and this is step two: first DISCOVER the object with its