digitalkin 0.2.25rc0__py3-none-any.whl → 0.3.2.dev14__py3-none-any.whl

digitalkin/models/module/utility.py

@@ -0,0 +1,167 @@
+"""Utility protocols for SDK-provided functionality.
+
+These protocols are automatically available to all modules and don't need to be
+explicitly included in module output unions.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, ClassVar, Literal
+
+from pydantic import BaseModel, Field
+
+from digitalkin.models.module.base_types import DataTrigger
+
+
+class UtilityProtocol(DataTrigger):
+    """Base class for SDK-provided utility protocols.
+
+    All SDK utility protocols inherit from this class to enable:
+    - Easy identification of SDK vs user-defined protocols
+    - Auto-injection capability
+    - Consistent behavior across the SDK
+    """
+
+
+class EndOfStreamOutput(UtilityProtocol):
+    """Signal that the stream has ended."""
+
+    protocol: Literal["end_of_stream"] = "end_of_stream"  # type: ignore
+
+
+class ModuleStartInfoOutput(UtilityProtocol):
+    """Output sent when module starts with execution context.
+
+    This protocol is sent as the first message when a module starts,
+    providing the client with essential execution context information.
+    """
+
+    protocol: Literal["module_start_info"] = "module_start_info"  # type: ignore
+    job_id: str = Field(..., description="Unique job identifier")
+    mission_id: str = Field(..., description="Mission identifier")
+    setup_id: str = Field(..., description="Setup identifier")
+    setup_version_id: str = Field(..., description="Setup version identifier")
+    module_id: str = Field(..., description="Module identifier")
+    module_name: str = Field(..., description="Human-readable module name")
+    started_at: str = Field(
+        default_factory=lambda: datetime.now(tz=timezone.utc).isoformat(),
+        description="ISO timestamp when module started",
+    )
+
+
+class HealthcheckPingInput(UtilityProtocol):
+    """Input for healthcheck ping request."""
+
+    protocol: Literal["healthcheck_ping"] = "healthcheck_ping"  # type: ignore
+
+
+class HealthcheckPingOutput(UtilityProtocol):
+    """Output for healthcheck ping response.
+
+    Simple alive check that returns "pong" status.
+    """
+
+    protocol: Literal["healthcheck_ping"] = "healthcheck_ping"  # type: ignore
+    status: Literal["pong"] = "pong"
+    latency_ms: float | None = Field(
+        default=None,
+        description="Round-trip latency in milliseconds",
+    )
+
+
+class ServiceHealthStatus(BaseModel):
+    """Health status of a single service."""
+
+    name: str = Field(..., description="Name of the service")
+    status: Literal["healthy", "unhealthy", "unknown"] = Field(
+        ...,
+        description="Health status of the service",
+    )
+    message: str | None = Field(
+        default=None,
+        description="Optional message about the service status",
+    )
+
+
+class HealthcheckServicesInput(UtilityProtocol):
+    """Input for healthcheck services request."""
+
+    protocol: Literal["healthcheck_services"] = "healthcheck_services"  # type: ignore
+
+
+class HealthcheckServicesOutput(UtilityProtocol):
+    """Output for healthcheck services response.
+
+    Reports the health status of all configured services.
+    """
+
+    protocol: Literal["healthcheck_services"] = "healthcheck_services"  # type: ignore
+    services: list[ServiceHealthStatus] = Field(
+        ...,
+        description="List of service health statuses",
+    )
+    overall_status: Literal["healthy", "degraded", "unhealthy"] = Field(
+        ...,
+        description="Overall health status based on all services",
+    )
+
+
+class HealthcheckStatusInput(UtilityProtocol):
+    """Input for healthcheck status request."""
+
+    protocol: Literal["healthcheck_status"] = "healthcheck_status"  # type: ignore
+
+
+class HealthcheckStatusOutput(UtilityProtocol):
+    """Output for healthcheck status response.
+
+    Comprehensive module status including uptime, active jobs, and metadata.
+    """
+
+    protocol: Literal["healthcheck_status"] = "healthcheck_status"  # type: ignore
+    module_name: str = Field(..., description="Name of the module")
+    module_status: str = Field(..., description="Current status of the module")
+    uptime_seconds: float | None = Field(
+        default=None,
+        description="Module uptime in seconds",
+    )
+    active_jobs: int = Field(
+        default=0,
+        description="Number of currently active jobs",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional metadata about the module",
+    )
+
+
+class UtilityRegistry:
+    """Registry for SDK-provided built-in triggers.
+
+    Example:
+        builtin_triggers = UtilityRegistry.get_builtin_triggers()
+    """
+
+    _builtin_triggers: ClassVar[tuple | None] = None
+
+    @classmethod
+    def get_builtin_triggers(cls) -> tuple:
+        """Get all SDK-provided built-in trigger handlers.
+
+        Uses lazy loading to avoid circular imports with the modules package.
+
+        Returns:
+            Tuple of TriggerHandler subclasses for built-in functionality.
+        """
+        if cls._builtin_triggers is None:
+            from digitalkin.modules.triggers.healthcheck_ping_trigger import HealthcheckPingTrigger  # noqa: PLC0415
+            from digitalkin.modules.triggers.healthcheck_services_trigger import (  # noqa: PLC0415
+                HealthcheckServicesTrigger,
+            )
+            from digitalkin.modules.triggers.healthcheck_status_trigger import HealthcheckStatusTrigger  # noqa: PLC0415
+
+            cls._builtin_triggers = (
+                HealthcheckPingTrigger,
+                HealthcheckServicesTrigger,
+                HealthcheckStatusTrigger,
+            )
+        return cls._builtin_triggers

digitalkin/models/services/__init__.py

@@ -1 +1,10 @@
 """This module contains the models for the services."""
+
+from digitalkin.models.services.storage import BaseMessage, BaseRole, ChatHistory, Role
+
+__all__ = [
+    "BaseMessage",
+    "BaseRole",
+    "ChatHistory",
+    "Role",
+]

digitalkin/models/services/cost.py

@@ -38,6 +38,7 @@ class CostConfig(BaseModel):
 class CostEvent(BaseModel):
     """Pydantic model that represents a cost event registered during service execution.
 
+    # DEPRECATED
     :param cost_name: Identifier for the cost configuration.
     :param cost_type: The type of cost.
     :param usage: The amount or units consumed.

digitalkin/models/services/registry.py

@@ -0,0 +1,35 @@
+"""Registry data models."""
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class RegistryModuleStatus(str, Enum):
+    """Module status in the registry."""
+
+    UNSPECIFIED = "unspecified"
+    READY = "ready"
+    ACTIVE = "active"
+    ARCHIVED = "archived"
+
+
+class RegistryModuleType(str, Enum):
+    """Module type in the registry."""
+
+    UNSPECIFIED = "unspecified"
+    ARCHETYPE = "archetype"
+    TOOL = "tool"
+
+
+class ModuleInfo(BaseModel):
+    """Module information from registry."""
+
+    module_id: str
+    module_type: RegistryModuleType
+    address: str
+    port: int
+    version: str
+    name: str = ""
+    documentation: str | None = None
+    status: RegistryModuleStatus | None = None

digitalkin/models/services/storage.py

@@ -1,10 +1,44 @@
 """Storage model."""
 
-from pydantic import BaseModel
+from enum import Enum
+from typing import Any
 
+from pydantic import BaseModel, Field
 
-class StorageModel(BaseModel):
-    """Storage model."""
 
-    data: object
-    type: str
+class BaseRole(str, Enum):
+    """Officially supported Role Enum for chat messages."""
+
+    ASSISTANT = "assistant"
+    USER = "user"
+    SYSTEM = "system"
+
+
+Role = BaseRole | str
+
+
+class BaseMessage(BaseModel):
+    """Base Model representing a simple message in the chat history."""
+
+    role: Role = Field(..., description="Role of the message sender")
+    content: Any = Field(..., description="The content of the message | preferably a BaseModel.")
+
+
+class ChatHistory(BaseModel):
+    """Storage chat history model for the OpenAI Archetype module."""
+
+    messages: list[BaseMessage] = Field(..., description="List of messages in the chat history")
+
+
+class FileModel(BaseModel):
+    """File model."""
+
+    file_id: str = Field(..., description="ID of the file")
+    name: str = Field(..., description="Name of the file")
+    metadata: dict[str, Any] = Field(..., description="Metadata of the file")
+
+
+class FileHistory(BaseModel):
+    """File history model."""
+
+    files: list[FileModel] = Field(..., description="List of files")

digitalkin/modules/__init__.py

@@ -4,4 +4,8 @@ from digitalkin.modules.archetype_module import ArchetypeModule
 from digitalkin.modules.tool_module import ToolModule
 from digitalkin.modules.trigger_handler import TriggerHandler
 
-__all__ = ["ArchetypeModule", "ToolModule", "TriggerHandler"]
+__all__ = [
+    "ArchetypeModule",
+    "ToolModule",
+    "TriggerHandler",
+]