digitalkin 0.3.2.dev2__py3-none-any.whl

digitalkin/modules/tool_module.py

@@ -0,0 +1,23 @@
+"""ToolModule extends BaseModule to implement specific module types."""
+
+from abc import ABC
+
+from digitalkin.models.module.module_types import (
+    InputModelT,
+    OutputModelT,
+    SecretModelT,
+    SetupModelT,
+)
+from digitalkin.modules._base_module import BaseModule  # type: ignore
+
+
+class ToolModule(
+    BaseModule[
+        InputModelT,
+        OutputModelT,
+        SetupModelT,
+        SecretModelT,
+    ],
+    ABC,
+):
+    """ToolModule extends BaseModule to implement specific module types."""

digitalkin/modules/trigger_handler.py

@@ -0,0 +1,48 @@
+"""Definition of the Trigger type."""
+
+from abc import ABC, abstractmethod
+from typing import ClassVar, Generic
+
+from digitalkin.mixins import BaseMixin
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.models.module.module_types import InputModelT, OutputModelT, SetupModelT
+
+
+class TriggerHandler(ABC, BaseMixin, Generic[InputModelT, SetupModelT, OutputModelT]):
+    """Base class for all input-trigger handlers.
+
+    Each handler declares:
+      - protocol_key: the Literal value this handler processes
+      - handle(): logic to process the validated payload
+    """
+
+    protocol: ClassVar[str]
+    input_format: type[InputModelT]
+    output_format: type[OutputModelT]
+
+    def __init__(self, context: ModuleContext) -> None:
+        """Initialize the TriggerHandler with the given context."""
+
+    @abstractmethod
+    async def handle(
+        self,
+        input_data: InputModelT,
+        setup_data: SetupModelT,
+        context: ModuleContext,
+    ) -> None:
+        """Asynchronously processes the input data specific to Handler and streams results via the provided callback.
+
+        Args:
+            input_data (InputModelT): The input data to be processed by the handler.
+            setup_data (SetupModelT): The setup or configuration data required for processing.
+            context (ModuleContext): The context object containing module-specific information and resources.
+
+        Returns:
+            Any: The result of the processing, if applicable.
+
+        Note:
+            self.send_message: : callback used to stream results.
+                (Callable[[OutputMdodelT], Coroutine[Any, Any, None]])
+
+            The callback must be awaited to ensure results are streamed correctly during processing.
+        """

digitalkin/modules/triggers/__init__.py

@@ -0,0 +1,12 @@
+"""Built-in SDK triggers.
+
+These triggers are automatically registered without requiring discovery.
+They provide standard functionality available to all modules.
+
+Note: These are internal triggers. External code should not import them directly.
+Use UtilityRegistry.get_builtin_triggers() to access the trigger classes.
+"""
+
+# No public exports - all triggers are internal
+# Access via: UtilityRegistry.get_builtin_triggers()
+__all__: list[str] = []

digitalkin/modules/triggers/healthcheck_ping_trigger.py

@@ -0,0 +1,45 @@
+"""Healthcheck ping trigger - simple alive check."""
+
+from datetime import datetime
+from typing import Any, ClassVar
+
+from digitalkin.mixins import BaseMixin
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.models.module.utility import (
+    HealthcheckPingInput,
+    HealthcheckPingOutput,
+)
+from digitalkin.modules.trigger_handler import TriggerHandler
+
+
+class HealthcheckPingTrigger(TriggerHandler, BaseMixin):
+    """Handler for simple ping healthcheck.
+
+    Responds immediately with "pong" status to verify the module is responsive.
+    """
+
+    protocol: ClassVar[str] = "healthcheck_ping"
+    input_format = HealthcheckPingInput
+    _request_time: datetime
+
+    def __init__(self, context: ModuleContext) -> None:
+        """Initialize the handler."""
+        self._request_time = datetime.now(tz=context.session.timezone)
+
+    async def handle(
+        self,
+        input_data: HealthcheckPingInput,  # noqa: ARG002
+        setup_data: Any,  # noqa: ANN401, ARG002
+        context: ModuleContext,
+    ) -> None:
+        """Handle ping healthcheck request.
+
+        Args:
+            input_data: The input trigger data (unused for healthcheck).
+            setup_data: The setup configuration (unused for healthcheck).
+            context: The module context.
+        """
+        elapsed = datetime.now(tz=context.session.timezone) - self._request_time
+        latency_ms = elapsed.total_seconds() * 1000
+        output = HealthcheckPingOutput(latency_ms=latency_ms)
+        await self.send_message(context, output)

digitalkin/modules/triggers/healthcheck_services_trigger.py

@@ -0,0 +1,63 @@
+"""Healthcheck services trigger - reports service health."""
+
+from typing import Any, ClassVar
+
+from digitalkin.mixins import BaseMixin
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.models.module.utility import (
+    HealthcheckServicesInput,
+    HealthcheckServicesOutput,
+    ServiceHealthStatus,
+)
+from digitalkin.modules.trigger_handler import TriggerHandler
+
+
+class HealthcheckServicesTrigger(TriggerHandler, BaseMixin):
+    """Handler for services healthcheck.
+
+    Reports the health status of all configured services (storage, cost, filesystem, etc.).
+    """
+
+    protocol: ClassVar[str] = "healthcheck_services"
+    input_format = HealthcheckServicesInput
+
+    def __init__(self, context: ModuleContext) -> None:
+        """Initialize the handler."""
+
+    async def handle(
+        self,
+        input_data: HealthcheckServicesInput,  # noqa: ARG002
+        setup_data: Any,  # noqa: ANN401, ARG002
+        context: ModuleContext,
+    ) -> None:
+        """Handle services healthcheck request.
+
+        Args:
+            input_data: The input trigger data (unused for healthcheck).
+            setup_data: The setup configuration (unused for healthcheck).
+            context: The module context.
+        """
+        service_names = ["storage", "cost", "filesystem", "registry", "user_profile"]
+        services_status: list[ServiceHealthStatus] = []
+
+        for name in service_names:
+            service = getattr(context, name, None)
+            if service is not None:
+                services_status.append(ServiceHealthStatus(name=name, status="healthy"))
+            else:
+                services_status.append(ServiceHealthStatus(name=name, status="unknown", message="Not configured"))
+
+        # Determine overall status
+        healthy_count = sum(1 for s in services_status if s.status == "healthy")
+        if healthy_count == len(services_status):
+            overall_status = "healthy"
+        elif healthy_count > 0:
+            overall_status = "degraded"
+        else:
+            overall_status = "unhealthy"
+
+        output = HealthcheckServicesOutput(
+            services=services_status,
+            overall_status=overall_status,  # type: ignore[arg-type]
+        )
+        await self.send_message(context, output)

digitalkin/modules/triggers/healthcheck_status_trigger.py

@@ -0,0 +1,52 @@
+"""Healthcheck status trigger - comprehensive module status."""
+
+import time
+from typing import Any, ClassVar
+
+from digitalkin.mixins import BaseMixin
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.models.module.utility import (
+    HealthcheckStatusInput,
+    HealthcheckStatusOutput,
+)
+from digitalkin.modules.trigger_handler import TriggerHandler
+
+
+class HealthcheckStatusTrigger(TriggerHandler, BaseMixin):
+    """Handler for comprehensive status healthcheck.
+
+    Reports detailed module status including uptime, active jobs, and metadata.
+    """
+
+    protocol: ClassVar[str] = "healthcheck_status"
+    input_format = HealthcheckStatusInput
+    _start_time: ClassVar[float] = time.time()
+
+    def __init__(self, context: ModuleContext) -> None:
+        """Initialize the handler."""
+
+    async def handle(
+        self,
+        input_data: HealthcheckStatusInput,  # noqa: ARG002
+        setup_data: Any,  # noqa: ANN401, ARG002
+        context: ModuleContext,
+    ) -> None:
+        """Handle status healthcheck request.
+
+        Args:
+            input_data: The input trigger data (unused for healthcheck).
+            setup_data: The setup configuration (unused for healthcheck).
+            context: The module context.
+        """
+        output = HealthcheckStatusOutput(
+            module_name=context.session.setup_id,
+            module_status="RUNNING",
+            uptime_seconds=time.time() - self._start_time,
+            active_jobs=1,
+            metadata={
+                "job_id": context.session.job_id,
+                "mission_id": context.session.mission_id,
+                "setup_version_id": context.session.setup_version_id,
+            },
+        )
+        await self.send_message(context, output)

digitalkin/services/__init__.py

@@ -0,0 +1,30 @@
+"""This package contains the abstract base class for all services."""
+
+from digitalkin.services.agent import AgentStrategy, DefaultAgent
+from digitalkin.services.communication import CommunicationStrategy, DefaultCommunication, GrpcCommunication
+from digitalkin.services.cost import CostStrategy, DefaultCost
+from digitalkin.services.filesystem import DefaultFilesystem, FilesystemStrategy
+from digitalkin.services.identity import DefaultIdentity, IdentityStrategy
+from digitalkin.services.registry import DefaultRegistry, RegistryStrategy
+from digitalkin.services.snapshot import DefaultSnapshot, SnapshotStrategy
+from digitalkin.services.storage import DefaultStorage, StorageStrategy
+
+__all__ = [
+    "AgentStrategy",
+    "CommunicationStrategy",
+    "CostStrategy",
+    "DefaultAgent",
+    "DefaultCommunication",
+    "DefaultCost",
+    "DefaultFilesystem",
+    "DefaultIdentity",
+    "DefaultRegistry",
+    "DefaultSnapshot",
+    "DefaultStorage",
+    "FilesystemStrategy",
+    "GrpcCommunication",
+    "IdentityStrategy",
+    "RegistryStrategy",
+    "SnapshotStrategy",
+    "StorageStrategy",
+]

digitalkin/services/agent/__init__.py

@@ -0,0 +1,6 @@
+"""This module is responsible for handling the agent services."""
+
+from digitalkin.services.agent.agent_strategy import AgentStrategy
+from digitalkin.services.agent.default_agent import DefaultAgent
+
+__all__ = ["AgentStrategy", "DefaultAgent"]

digitalkin/services/agent/agent_strategy.py

@@ -0,0 +1,19 @@
+"""This module contains the abstract base class for agent strategies."""
+
+from abc import ABC, abstractmethod
+
+from digitalkin.services.base_strategy import BaseStrategy
+
+
+class AgentStrategy(BaseStrategy, ABC):
+    """Abstract base class for agent strategies."""
+
+    @abstractmethod
+    def start(self) -> None:
+        """Start the agent."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def stop(self) -> None:
+        """Stop the agent."""
+        raise NotImplementedError

digitalkin/services/agent/default_agent.py

@@ -0,0 +1,13 @@
+"""Default agent implementation for the agent service."""
+
+from digitalkin.services.agent.agent_strategy import AgentStrategy
+
+
+class DefaultAgent(AgentStrategy):
+    """Default agent implementation for the agent service."""
+
+    def start(self) -> None:
+        """Start the agent."""
+
+    def stop(self) -> None:
+        """Stop the agent."""

digitalkin/services/base_strategy.py

@@ -0,0 +1,22 @@
+"""This module contains the abstract base class for storage strategies."""
+
+from abc import ABC
+
+
+class BaseStrategy(ABC):
+    """Abstract base class for all strategies.
+
+    This class defines the interface for all strategies.
+    """
+
+    def __init__(self, mission_id: str, setup_id: str, setup_version_id: str) -> None:
+        """Initialize the strategy.
+
+        Args:
+            mission_id: The ID of the mission this strategy is associated with
+            setup_id: The ID of the setup this strategy is associated with
+            setup_version_id: The ID of the setup version this strategy is associated with
+        """
+        self.mission_id: str = mission_id
+        self.setup_id: str = setup_id
+        self.setup_version_id: str = setup_version_id

digitalkin/services/communication/__init__.py

@@ -0,0 +1,7 @@
+"""Communication service for module-to-module interaction."""
+
+from digitalkin.services.communication.communication_strategy import CommunicationStrategy
+from digitalkin.services.communication.default_communication import DefaultCommunication
+from digitalkin.services.communication.grpc_communication import GrpcCommunication
+
+__all__ = ["CommunicationStrategy", "DefaultCommunication", "GrpcCommunication"]

digitalkin/services/communication/communication_strategy.py

@@ -0,0 +1,76 @@
+"""Abstract base class for communication strategies."""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator, Awaitable, Callable
+
+from digitalkin.services.base_strategy import BaseStrategy
+
+
+class CommunicationStrategy(BaseStrategy, ABC):
+    """Abstract base class for module-to-module communication.
+
+    This service enables:
+    - Archetype → Tool communication
+    - Archetype → Archetype communication
+    - Tool → Tool communication
+    - Any module → Any module communication
+
+    The service wraps the Module Service protocol from agentic-mesh-protocol.
+    """
+
+    @abstractmethod
+    async def get_module_schemas(
+        self,
+        module_address: str,
+        module_port: int,
+        *,
+        llm_format: bool = False,
+    ) -> dict[str, dict]:
+        """Get module schemas (input/output/setup/secret).
+
+        Args:
+            module_address: Target module address
+            module_port: Target module port
+            llm_format: Return LLM-friendly format (simplified schema)
+
+        Returns:
+            Dictionary containing schemas:
+            {
+                "input": {...},
+                "output": {...},
+                "setup": {...},
+                "secret": {...}
+            }
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def call_module(
+        self,
+        module_address: str,
+        module_port: int,
+        input_data: dict,
+        setup_id: str,
+        mission_id: str,
+        callback: Callable[[dict], Awaitable[None]] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        """Call a module and stream responses.
+
+        Uses Module Service StartModule RPC to execute the module.
+        Streams responses as they are generated by the module.
+
+        Args:
+            module_address: Target module address
+            module_port: Target module port
+            input_data: Input data as dictionary
+            setup_id: Setup configuration ID
+            mission_id: Mission context ID
+            callback: Optional callback for each response
+
+        Yields:
+            Streaming responses from module as dictionaries
+        """
+        # Make this an actual async generator to satisfy type checkers
+        if False:  # pragma: no cover
+            yield {}
+        raise NotImplementedError

digitalkin/services/communication/default_communication.py

@@ -0,0 +1,101 @@
+"""Default communication implementation (local, for testing)."""
+
+from collections.abc import AsyncGenerator, Awaitable, Callable
+
+from digitalkin.logger import logger
+from digitalkin.services.communication.communication_strategy import CommunicationStrategy
+
+
+class DefaultCommunication(CommunicationStrategy):
+    """Default communication strategy (local implementation).
+
+    This implementation is primarily for testing and development.
+    For production, use GrpcCommunication to connect to remote modules.
+    """
+
+    def __init__(
+        self,
+        mission_id: str,
+        setup_id: str,
+        setup_version_id: str,
+    ) -> None:
+        """Initialize the default communication service.
+
+        Args:
+            mission_id: Mission identifier
+            setup_id: Setup identifier
+            setup_version_id: Setup version identifier
+        """
+        super().__init__(mission_id, setup_id, setup_version_id)
+        logger.debug("Initialized DefaultCommunication (local)")
+
+    async def get_module_schemas(  # noqa: PLR6301
+        self,
+        module_address: str,
+        module_port: int,
+        *,
+        llm_format: bool = False,
+    ) -> dict[str, dict]:
+        """Get module schemas (local implementation returns empty schemas).
+
+        Args:
+            module_address: Target module address
+            module_port: Target module port
+            llm_format: Return LLM-friendly format
+
+        Returns:
+            Empty schemas dictionary
+        """
+        logger.debug(
+            "DefaultCommunication.get_module_schemas called (returns empty)",
+            extra={
+                "module_address": module_address,
+                "module_port": module_port,
+                "llm_format": llm_format,
+            },
+        )
+        return {
+            "input": {},
+            "output": {},
+            "setup": {},
+            "secret": {},
+        }
+
+    async def call_module(  # noqa: PLR6301
+        self,
+        module_address: str,
+        module_port: int,
+        input_data: dict,  # noqa: ARG002
+        setup_id: str,
+        mission_id: str,
+        callback: Callable[[dict], Awaitable[None]] | None = None,
+    ) -> AsyncGenerator[dict, None]:
+        """Call module (local implementation yields empty response).
+
+        Args:
+            module_address: Target module address
+            module_port: Target module port
+            input_data: Input data
+            setup_id: Setup ID
+            mission_id: Mission ID
+            callback: Optional callback
+
+        Yields:
+            Empty response dictionary
+        """
+        logger.debug(
+            "DefaultCommunication.call_module called (returns empty)",
+            extra={
+                "module_address": module_address,
+                "module_port": module_port,
+                "setup_id": setup_id,
+                "mission_id": mission_id,
+            },
+        )
+
+        # Yield empty response
+        response = {"status": "error", "message": "Local communication not implemented"}
+        if callback:
+            await callback(response)
+        yield response
+        return  # Explicit return for async generator