digitalkin 0.3.1.dev2__py3-none-any.whl → 0.3.2a3__py3-none-any.whl

digitalkin/grpc_servers/utils/utility_schema_extender.py

@@ -0,0 +1,106 @@
+"""Utility schema extender for gRPC API responses.
+
+This module extends module schemas with SDK utility protocols for API responses.
+"""
+
+import types
+from typing import Annotated, Union, get_args, get_origin
+
+from pydantic import Field, create_model
+
+from digitalkin.models.module.module_types import DataModel
+from digitalkin.models.module.utility import (
+    EndOfStreamOutput,
+    HealthcheckPingInput,
+    HealthcheckPingOutput,
+    HealthcheckServicesInput,
+    HealthcheckServicesOutput,
+    HealthcheckStatusInput,
+    HealthcheckStatusOutput,
+)
+from digitalkin.models.services.cost import CostLimit
+
+
+class UtilitySchemaExtender:
+    """Extends module schemas with SDK utility protocols for API responses.
+
+    This class provides methods to create extended Pydantic models that include
+    both user-defined protocols and SDK utility protocols in their schemas.
+    """
+
+    _output_protocols = (
+        EndOfStreamOutput,
+        HealthcheckPingOutput,
+        HealthcheckServicesOutput,
+        HealthcheckStatusOutput,
+    )
+
+    _input_protocols = (
+        HealthcheckPingInput,
+        HealthcheckServicesInput,
+        HealthcheckStatusInput,
+    )
+
+    @classmethod
+    def _extract_union_types(cls, annotation: type) -> tuple:
+        """Extract individual types from a Union or Annotated[Union, ...] annotation.
+
+        Returns:
+            A tuple of individual types contained in the Union.
+        """
+        if get_origin(annotation) is Annotated:
+            inner_args = get_args(annotation)
+            if inner_args:
+                return cls._extract_union_types(inner_args[0])
+        if get_origin(annotation) is Union or isinstance(annotation, types.UnionType):
+            return get_args(annotation)
+        return (annotation,)
+
+    @classmethod
+    def create_extended_output_model(cls, base_model: type[DataModel]) -> type[DataModel]:
+        """Create an extended output model that includes utility output protocols.
+
+        Args:
+            base_model: The module's output_format class (a DataModel subclass).
+
+        Returns:
+            A new DataModel subclass with root typed as Union[original_types, utility_types].
+        """
+        original_annotation = base_model.model_fields["root"].annotation
+        original_types = cls._extract_union_types(original_annotation)
+        extended_types = (*original_types, *cls._output_protocols)
+        union_type = Union[extended_types]  # type: ignore[valid-type] # noqa: UP007
+        extended_root = Annotated[union_type, Field(discriminator="protocol")]  # type: ignore[valid-type]
+        return create_model(
+            f"{base_model.__name__}Utilities",
+            __base__=DataModel,
+            root=(extended_root, ...),
+            annotations=(dict[str, str], Field(default={})),
+        )
+
+    @classmethod
+    def create_extended_input_model(cls, base_model: type[DataModel]) -> type[DataModel]:
+        """Create an extended input model that includes utility input protocols.
+
+        Args:
+            base_model: The module's input_format class (a DataModel subclass).
+
+        Returns:
+            A new DataModel subclass with root typed as Union[original_types, utility_types],
+            and includes cost_limits field for cost control.
+        """
+        original_annotation = base_model.model_fields["root"].annotation
+        original_types = cls._extract_union_types(original_annotation)
+        extended_types = (*original_types, *cls._input_protocols)
+        union_type = Union[extended_types]  # type: ignore[valid-type] # noqa: UP007
+        extended_root = Annotated[union_type, Field(discriminator="protocol")]  # type: ignore[valid-type]
+        return create_model(
+            f"{base_model.__name__}Utilities",
+            __base__=DataModel,
+            root=(extended_root, ...),
+            annotations=(dict[str, str], Field(default={})),
+            cost_limits=(
+                list[CostLimit] | None,
+                Field(default=None, description="Optional cost limits for this invocation"),
+            ),
+        )

digitalkin/models/__init__.py

@@ -1,6 +1,6 @@
 """This package contains the models for DigitalKin."""
 
-from digitalkin.models.module import Module, ModuleStatus
+from digitalkin.models.module.module import Module, ModuleStatus
 
 __all__ = [
     "Module",

digitalkin/models/core/job_manager_models.py

@@ -2,17 +2,9 @@
 
 from enum import Enum
 
-from pydantic import BaseModel
-
 from digitalkin.core.job_manager.base_job_manager import BaseJobManager
 
 
-class StreamCodeModel(BaseModel):
-    """Typed error/code model."""
-
-    code: str
-
-
 class JobManagerMode(Enum):
     """Job manager mode."""
 

digitalkin/models/core/task_monitor.py

@@ -18,7 +18,10 @@ class TaskStatus(Enum):
 
 
 class CancellationReason(Enum):
-    """Reason for task cancellation - helps distinguish cleanup vs real cancellation."""
+    """Reason for task termination - helps distinguish normal completion, cleanup, and real cancellation."""
+
+    # Normal completion
+    COMPLETED = "completed"  # Task finished successfully
 
     # Cleanup cancellations (not errors)
     SUCCESS_CLEANUP = "success_cleanup"  # Main task completed, cleaning up helper tasks
@@ -55,10 +58,27 @@ class SignalMessage(BaseModel):
 
     task_id: str = Field(..., description="Unique identifier for the task")
     mission_id: str = Field(..., description="Identifier for the mission")
+    setup_id: str = Field(default="", description="Identifier for the setup")
+    setup_version_id: str = Field(default="", description="Identifier for the setup version")
     status: TaskStatus = Field(..., description="Current status of the task")
     action: SignalType = Field(..., description="Type of signal action")
     timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
     payload: dict[str, Any] = Field(default={}, description="Optional payload for the signal")
+
+    # Enhanced logging fields
+    cancellation_reason: CancellationReason | None = Field(
+        default=None,
+        description="Reason for cancellation if status is CANCELLED",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Human-readable error message if task failed",
+    )
+    exception_traceback: str | None = Field(
+        default=None,
+        description="Full traceback if task failed with exception",
+    )
+
     model_config = {"use_enum_values": True}
 
 
@@ -67,4 +87,6 @@ class HeartbeatMessage(BaseModel):
 
     task_id: str = Field(..., description="Unique identifier for the task")
     mission_id: str = Field(..., description="Identifier for the mission")
+    setup_id: str = Field(default="", description="Identifier for the setup")
+    setup_version_id: str = Field(default="", description="Identifier for the setup version")
     timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

digitalkin/models/grpc_servers/models.py

@@ -65,6 +65,42 @@ class ServerCredentials(BaseModel):
         return v
 
 
+class RetryPolicy(BaseModel):
+    """gRPC retry policy configuration for resilient connections.
+
+    Attributes:
+        max_attempts: Maximum retry attempts including the original call
+        initial_backoff: Initial backoff duration (e.g., "0.1s")
+        max_backoff: Maximum backoff duration (e.g., "10s")
+        backoff_multiplier: Multiplier for exponential backoff
+        retryable_status_codes: gRPC status codes that trigger retry
+    """
+
+    max_attempts: int = Field(default=5, ge=1, le=10, description="Maximum retry attempts including the original call")
+    initial_backoff: str = Field(default="0.1s", description="Initial backoff duration (e.g., '0.1s')")
+    max_backoff: str = Field(default="10s", description="Maximum backoff duration (e.g., '10s')")
+    backoff_multiplier: float = Field(default=2.0, ge=1.0, description="Multiplier for exponential backoff")
+    retryable_status_codes: list[str] = Field(
+        default_factory=lambda: ["UNAVAILABLE", "RESOURCE_EXHAUSTED"],
+        description="gRPC status codes that trigger retry",
+    )
+
+    model_config = {"extra": "forbid", "frozen": True}
+
+    def to_service_config_json(self) -> str:
+        """Serialize to gRPC service config JSON string.
+
+        Returns:
+            JSON string for grpc.service_config channel option.
+        """
+        codes = "[" + ",".join(f'"{c}"' for c in self.retryable_status_codes) + "]"
+        return (
+            f'{{"methodConfig":[{{"name":[{{}}],"retryPolicy":{{"maxAttempts":{self.max_attempts},'
+            f'"initialBackoff":"{self.initial_backoff}","maxBackoff":"{self.max_backoff}",'
+            f'"backoffMultiplier":{self.backoff_multiplier},"retryableStatusCodes":{codes}}}}}]}}'
+        )
+
+
 class ClientCredentials(BaseModel):
     """Model for client credentials in secure mode.
 
@@ -170,15 +206,47 @@ class ClientConfig(ChannelConfig):
         security: Security mode (secure/insecure)
         credentials: Client credentials for secure mode
         channel_options: Additional channel options
+        retry_policy: Retry policy for failed RPCs
     """
 
     credentials: ClientCredentials | None = Field(None, description="Client credentials for secure mode")
+    retry_policy: RetryPolicy = Field(default_factory=lambda: RetryPolicy(), description="Retry policy for failed RPCs")  # noqa: PLW0108
     channel_options: list[tuple[str, Any]] = Field(
         default_factory=lambda: [
-            ("grpc.max_receive_message_length", 100 * 1024 * 1024),  # 100MB
-            ("grpc.max_send_message_length", 100 * 1024 * 1024),  # 100MB
+            ("grpc.max_receive_message_length", 100 * 1024 * 1024),
+            ("grpc.max_send_message_length", 100 * 1024 * 1024),
+            # === DNS Re-resolution (Critical for Container Environments) ===
+            # Minimum milliseconds between DNS re-resolution attempts (500 ms)
+            # When connection fails, gRPC will re-query DNS after this interval
+            # Solves: Container restarts with new IPs causing "No route to host"
+            ("grpc.dns_min_time_between_resolutions_ms", 500),
+            # Initial delay before first reconnection attempt (1 second)
+            ("grpc.initial_reconnect_backoff_ms", 1000),
+            # Maximum delay between reconnection attempts (10 seconds)
+            # Prevents overwhelming the network during extended outages
+            ("grpc.max_reconnect_backoff_ms", 10000),
+            # Minimum delay between reconnection attempts (500ms)
+            # Ensures rapid recovery for brief network glitches
+            ("grpc.min_reconnect_backoff_ms", 500),
+            # === Keepalive Settings (Detect Dead Connections) ===
+            # Send keepalive ping every 60 seconds when connection is idle
+            # Proactively detects dead connections before RPC calls fail
+            ("grpc.keepalive_time_ms", 60000),
+            # Wait 20 seconds for keepalive response before declaring connection dead
+            # Triggers reconnection (with DNS re-resolution) if pong not received
+            ("grpc.keepalive_timeout_ms", 20000),
+            # Send keepalive pings even when no RPCs are in flight
+            # Essential for long-lived connections that may sit idle
+            ("grpc.keepalive_permit_without_calls", True),
+            # Minimum interval between HTTP/2 pings (30 seconds)
+            # Must be >= server's grpc.http2.min_ping_interval_without_data_ms (10s)
+            ("grpc.http2.min_time_between_pings_ms", 30000),
+            # === Retry Configuration ===
+            # Enable automatic retry for failed RPCs (1 = enabled)
+            # Works with retryable status codes: UNAVAILABLE, RESOURCE_EXHAUSTED
+            ("grpc.enable_retries", 1),
         ],
-        description="Additional channel options",
+        description="Resilient gRPC channel options with DNS re-resolution, keepalive, and retries",
     )
 
     @field_validator("credentials")
@@ -204,6 +272,15 @@ class ClientConfig(ChannelConfig):
             raise ConfigurationError(msg)
         return v
 
+    @property
+    def grpc_options(self) -> list[tuple[str, Any]]:
+        """Get channel options with retry policy service config.
+
+        Returns:
+            Full list of gRPC channel options.
+        """
+        return [*self.channel_options, ("grpc.service_config", self.retry_policy.to_service_config_json())]
+
 
 class ServerConfig(ChannelConfig):
     """Base configuration for gRPC servers.
@@ -223,10 +300,18 @@ class ServerConfig(ChannelConfig):
     credentials: ServerCredentials | None = Field(None, description="Server credentials for secure mode")
     server_options: list[tuple[str, Any]] = Field(
         default_factory=lambda: [
-            ("grpc.max_receive_message_length", 100 * 1024 * 1024),  # 100MB
-            ("grpc.max_send_message_length", 100 * 1024 * 1024),  # 100MB
+            ("grpc.max_receive_message_length", 100 * 1024 * 1024),
+            ("grpc.max_send_message_length", 100 * 1024 * 1024),
+            # === Keepalive Permission (Required for Client Keepalive) ===
+            # Allow clients to send keepalive pings without active RPCs
+            # Without this, server rejects client keepalives with GOAWAY
+            ("grpc.keepalive_permit_without_calls", True),
+            # Minimum interval server allows between client pings (10 seconds)
+            # Prevents "too_many_pings" GOAWAY errors
+            # Must match or be less than client's http2.min_time_between_pings_ms
+            ("grpc.http2.min_ping_interval_without_data_ms", 10000),
         ],
-        description="Additional server options",
+        description="gRPC server options with keepalive support",
     )
     enable_reflection: bool = Field(default=True, description="Enable reflection for the server")
     enable_health_check: bool = Field(default=True, description="Enable health check service")
@@ -259,10 +344,12 @@ class ModuleServerConfig(ServerConfig):
     """Configuration for Module gRPC server.
 
     Attributes:
-        registry_address: Address of the registry server
+        advertise_host: Public hostname/IP sent to registry for discovery. Falls back to host if not set.
     """
 
-    registry_address: str = Field(..., description="Address of the registry server")
+    advertise_host: str | None = Field(
+        None, description="Public hostname/IP sent to registry for discovery. Falls back to host if not set."
+    )
 
 
 class RegistryServerConfig(ServerConfig):

digitalkin/models/module/__init__.py

@@ -1,28 +1,41 @@
 """This module contains the models for the modules."""
 
-from digitalkin.models.module.module import Module, ModuleStatus
 from digitalkin.models.module.module_context import ModuleContext
 from digitalkin.models.module.module_types import (
     DataModel,
     DataTrigger,
-    DataTriggerT,
-    InputModelT,
-    OutputModelT,
-    SecretModelT,
     SetupModel,
-    SetupModelT,
+)
+from digitalkin.models.module.tool_cache import (
+    ToolCache,
+    ToolDefinition,
+    ToolModuleInfo,
+    ToolParameter,
+)
+from digitalkin.models.module.tool_reference import (
+    ToolReference,
+    tool_reference_input,
+)
+from digitalkin.models.module.utility import (
+    EndOfStreamOutput,
+    ModuleStartInfoOutput,
+    UtilityProtocol,
+    UtilityRegistry,
 )
 
 __all__ = [
     "DataModel",
     "DataTrigger",
-    "DataTriggerT",
-    "InputModelT",
-    "Module",
+    "EndOfStreamOutput",
     "ModuleContext",
-    "ModuleStatus",
-    "OutputModelT",
-    "SecretModelT",
+    "ModuleStartInfoOutput",
     "SetupModel",
-    "SetupModelT",
+    "ToolCache",
+    "ToolDefinition",
+    "ToolModuleInfo",
+    "ToolParameter",
+    "ToolReference",
+    "UtilityProtocol",
+    "UtilityRegistry",
+    "tool_reference_input",
 ]

digitalkin/models/module/base_types.py

@@ -0,0 +1,61 @@
+"""Base types for module models."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, ClassVar, Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from digitalkin.models.module.setup_types import SetupModel
+
+
+class DataTrigger(BaseModel):
+    """Defines the root input/output model exposing the protocol.
+
+    The mandatory protocol is important to define the module beahvior following the user or agent input/output.
+
+    Example:
+        class MyInput(DataModel):
+            root: DataTrigger
+            user_define_data: Any
+
+        # Usage
+        my_input = MyInput(root=DataTrigger(protocol="message"))
+        print(my_input.root.protocol)  # Output: message
+    """
+
+    protocol: ClassVar[str]
+    created_at: str = Field(
+        default_factory=lambda: datetime.now(tz=timezone.utc).isoformat(),
+        title="Created At",
+        description="Timestamp when the payload was created.",
+    )
+
+
+DataTriggerT = TypeVar("DataTriggerT", bound=DataTrigger)
+
+
+class DataModel(BaseModel, Generic[DataTriggerT]):
+    """Base definition of input/output model showing mandatory root fields.
+
+    The Model define the Module Input/output, usually referring to multiple input/output type defined by an union.
+
+    Example:
+        class ModuleInput(DataModel):
+            root: FileInput | MessageInput
+    """
+
+    root: DataTriggerT
+    annotations: dict[str, str] = Field(
+        default={},
+        title="Annotations",
+        description="Additional metadata or annotations related to the output. ex {'role': 'user'}",
+    )
+
+
+InputModelT = TypeVar("InputModelT", bound=DataModel)
+OutputModelT = TypeVar("OutputModelT", bound=DataModel)
+SecretModelT = TypeVar("SecretModelT", bound=BaseModel)
+SetupModelT = TypeVar("SetupModelT", bound="SetupModel")