digitalkin 0.3.2.dev2__py3-none-any.whl

digitalkin/services/storage/storage_strategy.py

@@ -0,0 +1,273 @@
+"""This module contains the abstract base class for storage strategies."""
+
+import datetime
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, Literal, TypeGuard
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from digitalkin.services.base_strategy import BaseStrategy
+
+
+class StorageServiceError(Exception):
+    """Base exception for Setup service errors."""
+
+
+class DataType(Enum):
+    """Enum defining the types of data that can be stored."""
+
+    OUTPUT = "OUTPUT"
+    VIEW = "VIEW"
+    LOGS = "LOGS"
+    OTHER = "OTHER"
+
+
+class StorageRecord(BaseModel):
+    """A single record stored in a collection, with metadata."""
+
+    mission_id: str = Field(..., description="ID of the mission (bucket) this doc belongs to")
+    collection: str = Field(..., description="Logical collection name")
+    record_id: str = Field(..., description="Unique ID of this record in its collection")
+    data_type: DataType = Field(default=DataType.OUTPUT, description="Category of the data of this record")
+    data: BaseModel = Field(..., description="The typed payload of this record")
+    creation_date: datetime.datetime | None = Field(default=None, description="When this record was first created")
+    update_date: datetime.datetime | None = Field(default=None, description="When this record was last modified")
+
+
+class StorageStrategy(BaseStrategy, ABC):
+    """Define CRUD + list/remove-collection against a collection/record store."""
+
+    def _validate_data(self, collection: str, data: dict[str, Any]) -> BaseModel:
+        """Validate data against the model schema for the given key.
+
+        Args:
+            collection: The unique name for the record type
+            data: The data to validate
+
+        Returns:
+            A validated model instance
+
+        Raises:
+            ValueError: If the key has no associated model or validation fails
+        """
+        model_cls = self.config.get(collection)
+        if not model_cls:
+            msg = f"No schema registered for collection '{collection}'"
+            raise ValueError(msg)
+
+        try:
+            return model_cls.model_validate(data)
+        except Exception as e:
+            msg = f"Validation failed for '{collection}': {e!s}"
+            raise ValueError(msg) from e
+
+    def _create_storage_record(
+        self,
+        collection: str,
+        record_id: str,
+        validated_data: BaseModel,
+        data_type: DataType,
+    ) -> StorageRecord:
+        """Create a storage record with metadata.
+
+        Args:
+            collection: The unique name for the record type
+            record_id: The unique ID for the record
+            validated_data: The validated data model
+            data_type: The type of data
+
+        Returns:
+            A complete storage record with metadata
+        """
+        return StorageRecord(
+            mission_id=self.mission_id,
+            collection=collection,
+            record_id=record_id,
+            data=validated_data,
+            data_type=data_type,
+        )
+
+    @staticmethod
+    def _is_valid_data_type_name(value: str) -> TypeGuard[str]:
+        return value in DataType.__members__
+
+    @abstractmethod
+    def _store(self, record: StorageRecord) -> StorageRecord:
+        """Store a new record in the storage.
+
+        Args:
+            record: The record to store
+
+        Returns:
+            The ID of the created record
+        """
+
+    @abstractmethod
+    def _read(self, collection: str, record_id: str) -> StorageRecord | None:
+        """Get records from storage by key.
+
+        Args:
+            collection: The unique name to retrieve data for
+            record_id: The unique ID of the record
+
+        Returns:
+            A storage record with validated data
+        """
+
+    @abstractmethod
+    def _update(self, collection: str, record_id: str, data: BaseModel) -> StorageRecord | None:
+        """Overwrite an existing record's payload.
+
+        Args:
+            collection: The unique name for the record type
+            record_id: The unique ID of the record
+            data: The new data to store
+
+        Returns:
+            StorageRecord: The modified record
+        """
+
+    @abstractmethod
+    def _remove(self, collection: str, record_id: str) -> bool:
+        """Delete a record from the storage.
+
+        Args:
+            collection: The unique name for the record type
+            record_id: The unique ID of the record
+
+        Returns:
+            True if the deletion was successful, False otherwise
+        """
+
+    @abstractmethod
+    def _list(self, collection: str) -> list[StorageRecord]:
+        """List all records in a collection.
+
+        Args:
+            collection: The unique name for the record type
+
+        Returns:
+            A list of storage records
+        """
+
+    @abstractmethod
+    def _remove_collection(self, collection: str) -> bool:
+        """Delete all records in a collection.
+
+        Args:
+            collection: The unique name for the record type
+
+        Returns:
+            True if the deletion was successful, False otherwise
+        """
+
+    def __init__(
+        self,
+        mission_id: str,
+        setup_id: str,
+        setup_version_id: str,
+        config: dict[str, type[BaseModel]],
+    ) -> None:
+        """Initialize the storage strategy.
+
+        Args:
+            mission_id: The ID of the mission this strategy is associated with
+            setup_id: The ID of the setup
+            setup_version_id: The ID of the setup version
+            config: A dictionary mapping names to Pydantic model classes
+        """
+        super().__init__(mission_id, setup_id, setup_version_id)
+        # Schema configuration mapping keys to model classes
+        self.config: dict[str, type[BaseModel]] = config
+
+    def store(
+        self,
+        collection: str,
+        record_id: str | None,
+        data: dict[str, Any],
+        data_type: Literal["OUTPUT", "VIEW", "LOGS", "OTHER"] = "OUTPUT",
+    ) -> StorageRecord:
+        """Store a new record in the storage.
+
+        Args:
+            collection: The unique name for the record type
+            record_id: The unique ID for the record (optional)
+            data: The data to store
+            data_type: The type of data being stored (default: OUTPUT)
+
+        Returns:
+            The ID of the created record
+
+        Raises:
+            ValueError: If the data type is invalid or if validation fails
+        """
+        if not self._is_valid_data_type_name(data_type):
+            msg = f"Invalid data type '{data_type}'. Must be one of {list(DataType.__members__.keys())}"
+            raise ValueError(msg)
+        record_id = record_id or uuid4().hex
+        data_type_enum = DataType[data_type]
+        validated_data = self._validate_data(collection, {**data, "mission_id": self.mission_id})
+        record = self._create_storage_record(collection, record_id, validated_data, data_type_enum)
+        return self._store(record)
+
+    def read(self, collection: str, record_id: str) -> StorageRecord | None:
+        """Get records from storage by key.
+
+        Args:
+            collection: The unique name to retrieve data for
+            record_id: The unique ID of the record
+
+        Returns:
+            A storage record with validated data
+        """
+        return self._read(collection, record_id)
+
+    def update(self, collection: str, record_id: str, data: dict[str, Any]) -> StorageRecord | None:
+        """Validate & overwrite an existing record.
+
+        Args:
+            collection: The unique name for the record type
+            record_id: The unique ID of the record
+            data: The new data to store
+
+        Returns:
+            StorageRecord: The modified record
+        """
+        validated_data = self._validate_data(collection, data)
+        return self._update(collection, record_id, validated_data)
+
+    def remove(self, collection: str, record_id: str) -> bool:
+        """Delete a record from the storage.
+
+        Args:
+            collection: The unique name for the record type
+            record_id: The unique ID of the record
+
+        Returns:
+            True if the deletion was successful, False otherwise
+        """
+        return self._remove(collection, record_id)
+
+    def list(self, collection: str) -> list[StorageRecord]:
+        """Get all records within a collection.
+
+        Args:
+            collection: The unique name for the record type
+
+        Returns:
+            A list of storage records
+        """
+        return self._list(collection)
+
+    def remove_collection(self, collection: str) -> bool:
+        """Wipe a record clean.
+
+        Args:
+            collection: The unique name for the record type
+
+        Returns:
+            True if the deletion was successful, False otherwise
+        """
+        return self._remove_collection(collection)

digitalkin/services/user_profile/__init__.py

@@ -0,0 +1,12 @@
+"""UserProfile service package."""
+
+from digitalkin.services.user_profile.default_user_profile import DefaultUserProfile
+from digitalkin.services.user_profile.grpc_user_profile import GrpcUserProfile
+from digitalkin.services.user_profile.user_profile_strategy import UserProfileServiceError, UserProfileStrategy
+
+__all__ = [
+    "DefaultUserProfile",
+    "GrpcUserProfile",
+    "UserProfileServiceError",
+    "UserProfileStrategy",
+]

digitalkin/services/user_profile/default_user_profile.py

@@ -0,0 +1,55 @@
+"""Default user profile implementation."""
+
+from typing import Any
+
+from digitalkin.logger import logger
+from digitalkin.services.user_profile.user_profile_strategy import (
+    UserProfileServiceError,
+    UserProfileStrategy,
+)
+
+
+class DefaultUserProfile(UserProfileStrategy):
+    """Default user profile strategy with in-memory storage."""
+
+    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
+            setup_version_id: The ID of the setup version
+        """
+        super().__init__(mission_id=mission_id, setup_id=setup_id, setup_version_id=setup_version_id)
+        self.db: dict[str, dict[str, Any]] = {}
+
+    def get_user_profile(self) -> dict[str, Any]:
+        """Get user profile from in-memory storage.
+
+        Returns:
+            dict[str, Any]: User profile data
+
+        Raises:
+            UserProfileServiceError: If the user profile is not found
+        """
+        if self.mission_id not in self.db:
+            msg = f"User profile for mission {self.mission_id} not found in the database."
+            logger.warning(msg)
+            raise UserProfileServiceError(msg)
+
+        logger.debug(f"Retrieved user profile for mission_id: {self.mission_id}")
+        return self.db[self.mission_id]
+
+    def add_user_profile(self, user_profile_data: dict[str, Any]) -> None:
+        """Add a user profile to the in-memory database (helper for testing).
+
+        Args:
+            user_profile_data: Dictionary containing user profile data
+        """
+        self.db[self.mission_id] = user_profile_data
+        logger.debug(f"Added user profile for mission_id: {self.mission_id}")

digitalkin/services/user_profile/grpc_user_profile.py

@@ -0,0 +1,69 @@
+"""Digital Kin UserProfile Service gRPC Client."""
+
+from typing import Any
+
+from agentic_mesh_protocol.user_profile.v1 import (
+    user_profile_pb2,
+    user_profile_service_pb2_grpc,
+)
+from google.protobuf import json_format
+
+from digitalkin.grpc_servers.utils.grpc_client_wrapper import GrpcClientWrapper
+from digitalkin.grpc_servers.utils.grpc_error_handler import GrpcErrorHandlerMixin
+from digitalkin.logger import logger
+from digitalkin.models.grpc_servers.models import ClientConfig
+from digitalkin.services.user_profile.user_profile_strategy import UserProfileServiceError, UserProfileStrategy
+
+
+class GrpcUserProfile(UserProfileStrategy, GrpcClientWrapper, GrpcErrorHandlerMixin):
+    """This class implements the gRPC user profile service."""
+
+    def __init__(
+        self,
+        mission_id: str,
+        setup_id: str,
+        setup_version_id: str,
+        client_config: ClientConfig,
+    ) -> None:
+        """Initialize the user profile service.
+
+        Args:
+            mission_id: The ID of the mission this strategy is associated with
+            setup_id: The ID of the setup
+            setup_version_id: The ID of the setup version
+            client_config: Client configuration for gRPC connection
+        """
+        super().__init__(mission_id=mission_id, setup_id=setup_id, setup_version_id=setup_version_id)
+        channel = self._init_channel(client_config)
+        self.stub = user_profile_service_pb2_grpc.UserProfileServiceStub(channel)
+        logger.debug("Channel client 'UserProfile' initialized successfully")
+
+    def get_user_profile(self) -> dict[str, Any]:
+        """Get user profile by mission_id (which maps to user_id).
+
+        Returns:
+            dict[str, Any]: User profile data
+
+        Raises:
+            UserProfileServiceError: If the user profile cannot be retrieved
+            ServerError: If gRPC operation fails
+        """
+        with self.handle_grpc_errors("GetUserProfile", UserProfileServiceError):
+            # mission_id typically contains user context
+            request = user_profile_pb2.GetUserProfileRequest(mission_id=self.mission_id)
+            response = self.exec_grpc_query("GetUserProfile", request)
+
+            if not response.success:
+                msg = f"Failed to get user profile for mission_id: {self.mission_id}"
+                logger.error(msg)
+                raise UserProfileServiceError(msg)
+
+            # Convert proto to dict
+            user_profile_dict = json_format.MessageToDict(
+                response.user_profile,
+                preserving_proto_field_name=True,
+                always_print_fields_with_no_presence=True,
+            )
+
+            logger.debug(f"Retrieved user profile for mission_id: {self.mission_id}")
+            return user_profile_dict

digitalkin/services/user_profile/user_profile_strategy.py

@@ -0,0 +1,40 @@
+"""This module contains the abstract base class for UserProfile strategies."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from digitalkin.services.base_strategy import BaseStrategy
+
+
+class UserProfileServiceError(Exception):
+    """Base exception for UserProfile service errors."""
+
+
+class UserProfileStrategy(BaseStrategy, ABC):
+    """Abstract base class for UserProfile 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
+            setup_version_id: The ID of the setup version this strategy is associated with
+        """
+        super().__init__(mission_id, setup_id, setup_version_id)
+
+    @abstractmethod
+    def get_user_profile(self) -> dict[str, Any]:
+        """Get user profile data.
+
+        Returns:
+            dict[str, Any]: User profile data
+
+        Raises:
+            UserProfileServiceError: If the user profile cannot be retrieved
+        """

digitalkin/utils/__init__.py

@@ -0,0 +1,29 @@
+"""General utils folder."""
+
+from digitalkin.utils.dynamic_schema import (
+    DEFAULT_TIMEOUT,
+    DynamicField,
+    Fetcher,
+    ResolveResult,
+    get_dynamic_metadata,
+    get_fetchers,
+    has_dynamic,
+    resolve,
+    resolve_safe,
+)
+
+# Alias for cleaner API: `Dynamic` is shorter than `DynamicField`
+Dynamic = DynamicField
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "Dynamic",
+    "DynamicField",
+    "Fetcher",
+    "ResolveResult",
+    "get_dynamic_metadata",
+    "get_fetchers",
+    "has_dynamic",
+    "resolve",
+    "resolve_safe",
+]

digitalkin/utils/arg_parser.py

@@ -0,0 +1,92 @@
+"""ArgParser and Action classes to ease command lines arguments settings."""
+
+import logging
+from argparse import ArgumentParser, Namespace, _HelpAction, _SubParsersAction  # noqa: PLC2701
+from collections.abc import Sequence
+from typing import Any
+
+from digitalkin.logger import logger
+
+logger.setLevel(logging.INFO)
+
+
+class ArgParser:
+    """ArgParse Abstract class to join all argparse argument in the same parser.
+
+    Custom help display to allow multiple parser and subparser help message.
+
+    Examples:
+    --------
+    Inherit this class in your base class.
+    Override '_add_parser_args', '_add_exclusive_args' and '_add_subparser_args'.
+
+    class WindowHandler(ArgParser):
+
+        @staticmethod
+        def _add_screen_parser_args(parser) -> None:
+            parser.add_argument(
+                "-f", "--fps", type=int, default=60, help="Screen FPS", dest="fps"
+            )
+
+        def _add_media_parser_args(self, parser) -> None:
+            parser.add_argument(
+                "-w",
+                "--workers",
+                type=int,
+                default=3,
+                help="Number of worker processing media in background",
+                dest="media_worker_count"
+            )
+
+        def _add_parser_args(self, parser) -> None:
+            super()._add_parser_args(parser)
+            self._add_screen_parser_args(parser)
+            self._add_media_parser_args(parser)
+
+        def __init__(self):
+            # init the parser
+            super().__init__()
+    """
+
+    args: Namespace
+
+    """
+        Override methods
+    """
+
+    class HelpAction(_HelpAction):
+        """Custom HelpAction to display subparsers helps too."""
+
+        def __call__(
+            self,
+            parser: ArgumentParser,
+            namespace: Namespace,  # noqa: ARG002
+            values: str | Sequence[Any] | None,  # noqa: ARG002
+            option_string: str | None = None,  # noqa: ARG002
+        ) -> None:
+            """Override the HelpActions as it doesn't handle subparser well."""
+            parser.print_help()
+            subparsers_actions = [action for action in parser._actions if isinstance(action, _SubParsersAction)]  # noqa: SLF001
+            for subparsers_action in subparsers_actions:
+                for choice, subparser in subparsers_action.choices.items():
+                    logger.info("Subparser '%s':\n%s", choice, subparser.format_help())
+            parser.exit()
+
+    """
+        Private methods
+    """
+
+    def _add_parser_args(self, parser: ArgumentParser) -> None:
+        parser.add_argument("-h", "--help", action=self.HelpAction, help="help usage")
+
+    def _add_exclusive_args(self, parser: ArgumentParser) -> None: ...
+
+    def _add_subparser_args(self, parser: ArgumentParser) -> None: ...
+
+    def __init__(self, prog: str = "PROG") -> None:
+        """Create prser and call abstract methods."""
+        self.parser = ArgumentParser(prog=prog, conflict_handler="resolve", add_help=False)
+        self._add_parser_args(self.parser)
+        self._add_exclusive_args(self.parser)
+        self._add_subparser_args(self.parser)
+        self.args, _ = self.parser.parse_known_args()

digitalkin/utils/development_mode_action.py

@@ -0,0 +1,51 @@
+"""ArgParser and Action classes to ease command lines arguments settings."""
+
+import logging
+import os
+from argparse import Action, ArgumentParser, Namespace
+from collections.abc import Sequence
+from typing import Any
+
+from digitalkin.logger import logger
+from digitalkin.services.services_models import ServicesMode
+
+logger.setLevel(logging.INFO)
+
+
+class DevelopmentModeMappingAction(Action):
+    """ArgParse Action to map an environment variable to a ServicesMode enum."""
+
+    def __init__(
+        self,
+        env_var: str,
+        required: bool = True,  # noqa: FBT001, FBT002
+        default: str | None = None,
+        **kwargs: dict[str, Any],
+    ) -> None:
+        """Initialize the DevelopmentModeMappingAction."""
+        default = ServicesMode(os.environ.get(env_var, default))
+
+        if required and default:
+            required = False
+        super().__init__(default=default, required=required, **kwargs)  # type: ignore
+
+    def __call__(
+        self,
+        parser: ArgumentParser,  # noqa: ARG002
+        namespace: Namespace,
+        values: str | Sequence[Any] | None,
+        option_string: str | None = None,  # noqa: ARG002
+    ) -> None:
+        """Set the attribute to the corresponding class.
+
+        Raises:
+            TypeError: if the value is not a string.
+        """
+        # Check if the value is a string and convert it to lowercase
+        if isinstance(values, str):
+            values = values.lower()
+        else:
+            msg = "values must be a string"
+            raise TypeError(msg)
+        mode = ServicesMode(values)
+        setattr(namespace, self.dest, mode)