digitalkin 0.2.25rc1__py3-none-any.whl → 0.3.0__py3-none-any.whl

digitalkin/mixins/file_history_mixin.py

@@ -0,0 +1,99 @@
+"""Context mixins providing ergonomic access to service strategies.
+
+This module provides mixins that wrap service strategy calls with cleaner APIs,
+following Django/FastAPI patterns where context is passed explicitly to each method.
+"""
+
+from digitalkin.mixins.logger_mixin import LoggerMixin
+from digitalkin.mixins.storage_mixin import StorageMixin
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.models.services.storage import FileHistory, FileModel
+
+
+class FileHistoryMixin(StorageMixin, LoggerMixin):
+    """Mixin providing File history operations through storage strategy.
+
+    This mixin provides a higher-level API for managing File history,
+    using the storage strategy as the underlying persistence mechanism.
+    """
+
+    file_history_front: FileHistory = FileHistory(files=[])
+    FILE_HISTORY_COLLECTION = "file_history"
+    FILE_HISTORY_RECORD_ID = "full_file_history"
+
+    def _get_history_key(self, context: ModuleContext) -> str:
+        """Get session-specific history key.
+
+        Args:
+            context: Module context containing session information
+
+        Returns:
+            Unique history key for the current session
+        """
+        mission_id = getattr(context.session, "mission_id", None) or "default"
+        return f"{self.FILE_HISTORY_RECORD_ID}_{mission_id}"
+
+    def load_file_history(self, context: ModuleContext) -> FileHistory:
+        """Load File history for the current session.
+
+        Args:
+            context: Module context containing storage strategy
+
+        Returns:
+            File history object, empty if none exists or loading fails
+        """
+        history_key = self._get_history_key(context)
+
+        if self.file_history_front is None:
+            try:
+                record = self.read_storage(
+                    context,
+                    self.FILE_HISTORY_COLLECTION,
+                    history_key,
+                )
+                if record and record.data:
+                    return FileHistory.model_validate(record.data)
+            except Exception as e:
+                self.log_warning(context, f"Failed to load File history: {e}")
+        return self.file_history_front
+
+    def append_files_history(self, context: ModuleContext, files: list[FileModel]) -> None:
+        """Append a message to File history.
+
+        Args:
+            context: Module context containing storage strategy
+            role: Message role (user, assistant, system)
+            files: list of files model
+
+        Raises:
+            StorageServiceError: If history update fails
+        """
+        history_key = self._get_history_key(context)
+
+        try:
+            if not self.file_history_front.files:
+                self.file_history_front = self.load_file_history(context)
+            self.file_history_front.files.extend(files)
+        except Exception as e:
+            self.log_error(context, f"Failed to append message to File history: {e}")
+
+        try:
+            self.log_debug(context, f"Updating File history for session: {history_key}")
+            self.update_storage(
+                context,
+                self.FILE_HISTORY_COLLECTION,
+                history_key,
+                self.file_history_front.model_dump(),
+            )
+        except Exception as e:
+            self.log_error(context, f"Updating File history for session: {history_key} with error: {e}")
+
+            # Create new record
+            self.log_debug(context, f"Creating new File history for session: {history_key}")
+            self.store_storage(
+                context,
+                self.FILE_HISTORY_COLLECTION,
+                history_key,
+                self.file_history_front.model_dump(),
+                data_type="OUTPUT",
+            )

digitalkin/mixins/filesystem_mixin.py

@@ -0,0 +1,47 @@
+"""Filesystem Mixin to ease filesystem use."""
+
+from typing import Any
+
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.services.filesystem.filesystem_strategy import FilesystemRecord
+
+
+class FilesystemMixin:
+    """Mixin providing filesystem operations through the filesystem strategy.
+
+    This mixin wraps filesystem strategy calls to provide a cleaner API
+    for file operations in trigger handlers.
+    """
+
+    @staticmethod
+    def upload_files(context: ModuleContext, files: list[Any]) -> tuple[list[FilesystemRecord], int, int]:
+        """Upload files using the filesystem strategy.
+
+        Args:
+            context: Module context containing the filesystem strategy
+            files: List of files to upload
+
+        Returns:
+            Tuple of (all_files, succeeded_files, failed_files)
+
+        Raises:
+            FilesystemServiceError: If upload operation fails
+        """
+        return context.filesystem.upload_files(files)
+
+    @staticmethod
+    def get_file(context: ModuleContext, file_id: str) -> tuple[FilesystemRecord, bytes | None]:
+        """Retrieve a file by ID with the content.
+
+        Args:
+            context: Module context containing the filesystem strategy
+            file_id: Unique identifier for the file
+            include_content: Whether to include file content in response
+
+        Returns:
+            File object with metadata and optionally content
+
+        Raises:
+            FilesystemServiceError: If file retrieval fails
+        """
+        return context.filesystem.get_file(file_id, include_content=True)

digitalkin/mixins/logger_mixin.py

@@ -0,0 +1,59 @@
+"""Logger Mixin to ease and merge every logs."""
+
+from digitalkin.models.module.module_context import ModuleContext
+
+
+class LoggerMixin:
+    """Mixin providing callback operations through the callbacks strategy.
+
+    This mixin wraps callback strategy calls to provide a cleaner API
+    for logging and messaging in trigger handlers.
+    """
+
+    @staticmethod
+    def log_debug(context: ModuleContext, message: str) -> None:
+        """Log debug message using the callbacks strategy.
+
+        Args:
+            context: Module context containing the callbacks strategy
+            message: Debug message to log
+            *args: Positional arguments for message formatting
+            **kwargs: Keyword arguments for logger
+        """
+        return context.callbacks.logger.debug(message)
+
+    @staticmethod
+    def log_info(context: ModuleContext, message: str) -> None:
+        """Log info message using the callbacks strategy.
+
+        Args:
+            context: Module context containing the callbacks strategy
+            message: Info message to log
+            *args: Positional arguments for message formatting
+            **kwargs: Keyword arguments for logger
+        """
+        return context.callbacks.logger.info(message)
+
+    @staticmethod
+    def log_warning(context: ModuleContext, message: str) -> None:
+        """Log warning message using the callbacks strategy.
+
+        Args:
+            context: Module context containing the callbacks strategy
+            message: Warning message to log
+            *args: Positional arguments for message formatting
+            **kwargs: Keyword arguments for logger
+        """
+        return context.callbacks.logger.warning(message)
+
+    @staticmethod
+    def log_error(context: ModuleContext, message: str) -> None:
+        """Log error message using the callbacks strategy.
+
+        Args:
+            context: Module context containing the callbacks strategy
+            message: Error message to log
+            *args: Positional arguments for message formatting
+            **kwargs: Keyword arguments for logger
+        """
+        return context.callbacks.logger.error(message)

digitalkin/mixins/storage_mixin.py

@@ -0,0 +1,79 @@
+"""Storage Mixin to ease storage access in Triggers."""
+
+from typing import Any, Literal
+
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.services.storage.storage_strategy import StorageRecord
+
+
+class StorageMixin:
+    """Mixin providing storage operations through the storage strategy.
+
+    This mixin wraps storage strategy calls to provide a cleaner API
+    for trigger handlers.
+    """
+
+    @staticmethod
+    def store_storage(
+        context: ModuleContext,
+        collection: str,
+        record_id: str | None,
+        data: dict[str, Any],
+        data_type: Literal["OUTPUT", "VIEW", "LOGS", "OTHER"] = "OUTPUT",
+    ) -> StorageRecord:
+        """Store data using the storage strategy.
+
+        Args:
+            context: Module context containing the storage strategy
+            collection: Collection name for the data
+            record_id: Optional record identifier
+            data: Data to store
+            data_type: Type of data being stored
+
+        Returns:
+            Result from the storage strategy
+
+        Raises:
+            StorageServiceError: If storage operation fails
+        """
+        return context.storage.store(collection, record_id, data, data_type=data_type)
+
+    @staticmethod
+    def read_storage(context: ModuleContext, collection: str, record_id: str) -> StorageRecord | None:
+        """Read data from storage.
+
+        Args:
+            context: Module context containing the storage strategy
+            collection: Collection name
+            record_id: Record identifier
+
+        Returns:
+            Retrieved data
+
+        Raises:
+            StorageServiceError: If read operation fails
+        """
+        return context.storage.read(collection, record_id)
+
+    @staticmethod
+    def update_storage(
+        context: ModuleContext,
+        collection: str,
+        record_id: str,
+        data: dict[str, Any],
+    ) -> StorageRecord | None:
+        """Update existing data in storage.
+
+        Args:
+            context: Module context containing the storage strategy
+            collection: Collection name
+            record_id: Record identifier
+            data: Updated data
+
+        Returns:
+            Result from the storage strategy
+
+        Raises:
+            StorageServiceError: If update operation fails
+        """
+        return context.storage.update(collection, record_id, data)

digitalkin/models/module/__init__.py

@@ -5,6 +5,7 @@ from digitalkin.models.module.module_context import ModuleContext
 from digitalkin.models.module.module_types import (
     DataModel,
     DataTrigger,
+    DataTriggerT,
     InputModelT,
     OutputModelT,
     SecretModelT,
@@ -15,6 +16,7 @@ from digitalkin.models.module.module_types import (
 __all__ = [
     "DataModel",
     "DataTrigger",
+    "DataTriggerT",
     "InputModelT",
     "Module",
     "ModuleContext",

digitalkin/models/module/module.py

@@ -2,7 +2,15 @@
 
 from enum import Enum, auto
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
+
+
+class ModuleCodeModel(BaseModel):
+    """typed error/code model."""
+
+    code: str = Field(...)
+    message: str | None = Field(default=None)
+    short_description: str | None = Field(default=None)
 
 
 class ModuleStatus(Enum):

digitalkin/models/module/module_context.py

@@ -1,24 +1,108 @@
 """Define the module context used in the triggers."""
 
 from types import SimpleNamespace
+from typing import Any
 
+from digitalkin.services.agent.agent_strategy import AgentStrategy
 from digitalkin.services.cost.cost_strategy import CostStrategy
 from digitalkin.services.filesystem.filesystem_strategy import FilesystemStrategy
+from digitalkin.services.identity.identity_strategy import IdentityStrategy
+from digitalkin.services.registry.registry_strategy import RegistryStrategy
+from digitalkin.services.snapshot.snapshot_strategy import SnapshotStrategy
 from digitalkin.services.storage.storage_strategy import StorageStrategy
 
 
-class ModuleContext(SimpleNamespace):
-    """ModuleContext provides a container for strategies and resources used by a module.
+class Session(SimpleNamespace):
+    """Session data container with mandatory setup_id and mission_id."""
+
+    mission_id: str
+    setup_version_id: str
+
+    def __init__(self, mission_id: str, setup_version_id: str, **kwargs: dict[str, Any]) -> None:
+        """Init Module Session.
+
+        Args:
+            mission_id: current mission_id.
+            setup_version_id: used setup config.
+            kwargs: user defined session variables.
+
+        Raises:
+            ValueError: If mandatory args are missing
+        """
+        if not setup_version_id:
+            msg = "setup_version_id is mandatory and cannot be empty"
+            raise ValueError(msg)
+        if not mission_id:
+            msg = "mission_id is mandatory and cannot be empty"
+            raise ValueError(msg)
+
+        self.mission_id = mission_id
+        self.setup_version_id = setup_version_id
+
+        super().__init__(**kwargs)
 
-    Attributes:
-        cost (CostStrategy): The strategy used to calculate or manage costs within the module.
-        filesystem (FilesystemStrategy): The strategy for interacting with the filesystem.
-        storage (StorageStrategy): The strategy for handling storage operations.
+
+class ModuleContext:
+    """ModuleContext provides a container for strategies and resources used by a module.
 
     This context object is designed to be passed to module components, providing them with
     access to shared strategies and resources. Additional attributes may be set dynamically.
     """
 
+    # services list
+    agent: AgentStrategy
     cost: CostStrategy
     filesystem: FilesystemStrategy
+    identity: IdentityStrategy
+    registry: RegistryStrategy
+    snapshot: SnapshotStrategy
     storage: StorageStrategy
+
+    session: Session
+    callbacks: SimpleNamespace
+    metadata: SimpleNamespace
+    helpers: SimpleNamespace
+    state: SimpleNamespace = SimpleNamespace()
+
+    def __init__(  # noqa: PLR0913, PLR0917
+        self,
+        agent: AgentStrategy,
+        cost: CostStrategy,
+        filesystem: FilesystemStrategy,
+        identity: IdentityStrategy,
+        registry: RegistryStrategy,
+        snapshot: SnapshotStrategy,
+        storage: StorageStrategy,
+        session: dict[str, Any],
+        metadata: dict[str, Any] = {},
+        helpers: dict[str, Any] = {},
+        callbacks: dict[str, Any] = {},
+    ) -> None:
+        """Register mandatory services, session, metadata and callbacks.
+
+        Args:
+            agent: AgentStrategy.
+            cost: CostStrategy.
+            filesystem: FilesystemStrategy.
+            identity: IdentityStrategy.
+            registry: RegistryStrategy.
+            snapshot: SnapshotStrategy.
+            storage: StorageStrategy.
+            metadata: dict defining differents Module metadata.
+            helpers: dict different user defined helpers.
+            session: dict referring the session IDs or informations.
+            callbacks: Functions allowing user to agent interaction.
+        """
+        # Core services
+        self.agent = agent
+        self.cost = cost
+        self.filesystem = filesystem
+        self.identity = identity
+        self.registry = registry
+        self.snapshot = snapshot
+        self.storage = storage
+
+        self.metadata = SimpleNamespace(**metadata)
+        self.session = Session(**session)
+        self.helpers = SimpleNamespace(**helpers)
+        self.callbacks = SimpleNamespace(**callbacks)

digitalkin/models/module/module_types.py

@@ -9,9 +9,9 @@ from digitalkin.logger import logger
 
 
 class DataTrigger(BaseModel):
-    """Defines the root input model exposing the protocol.
+    """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.
+    The mandatory protocol is important to define the module beahvior following the user or agent input/output.
 
     Example:
         class MyInput(DataModel):
@@ -31,9 +31,9 @@ DataTriggerT = TypeVar("DataTriggerT", bound=DataTrigger)
 
 
 class DataModel(BaseModel, Generic[DataTriggerT]):
-    """Base definition of input model showing mandatory root fields.
+    """Base definition of input/output model showing mandatory root fields.
 
-    The Model define the Module Input, usually referring to multiple input type defined by an union.
+    The Model define the Module Input/output, usually referring to multiple input/output type defined by an union.
 
     Example:
         class ModuleInput(DataModel):
@@ -102,4 +102,4 @@ class SetupModel(BaseModel):
             __config__=ConfigDict(arbitrary_types_allowed=True),
             **clean_fields,
         )
-        return cast("type[SetupModelT]", m)
+        return cast("type[SetupModelT]", m)  # type: ignore

digitalkin/models/module/task_monitor.py

@@ -0,0 +1,51 @@
+"""."""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class TaskStatus(Enum):
+    """."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    CANCELLED = "cancelled"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class SignalType(Enum):
+    """."""
+
+    START = "start"
+    STOP = "stop"
+    CANCEL = "cancel"
+    PAUSE = "pause"
+    RESUME = "resume"
+    STATUS = "status"
+
+    ACK_CANCEL = "ack_cancel"
+    ACK_PAUSE = "ack_pause"
+    ACK_RESUME = "ack_resume"
+    ACK_STATUS = "ack_status"
+
+
+class SignalMessage(BaseModel):
+    """."""
+
+    task_id: str = Field(..., description="Unique identifier for the task")
+    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")
+    model_config = {"use_enum_values": True}
+
+
+class HeartbeatMessage(BaseModel):
+    """."""
+
+    task_id: str = Field(..., description="Unique identifier for the task")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

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/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"
+    HUMAN = "human"
+    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")