digitalkin 1.0.4.dev5__tar.gz → 1.0.4.dev7__tar.gz

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.4.dev5
+Version: 1.0.4.dev7
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International
@@ -453,7 +453,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ag-ui-protocol==0.1.21.dev1787220377
-Requires-Dist: agentic-mesh-protocol==1.0.2.dev2
+Requires-Dist: agentic-mesh-protocol==1.0.2
 Requires-Dist: agno<3,>=2.8.0
 Requires-Dist: anyio>=4.13.0
 Requires-Dist: grpcio-health-checking==1.82.1

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev7}/examples/services/filesystem_module.py

@@ -10,7 +10,8 @@ from pydantic import BaseModel, Field
 from digitalkin.logger import logger
 from digitalkin.models.module import ModuleStatus
 from digitalkin.modules.archetype_module import ArchetypeModule
-from digitalkin.services.filesystem.filesystem_strategy import FileFilter, UploadFileData
+from digitalkin.models.services.filesystem import FileType
+from digitalkin.services.filesystem import FileFilter, UploadFileData
 from digitalkin.services.services_config import ServicesConfig
 from digitalkin.services.services_models import ServicesMode
 
@@ -118,9 +119,9 @@ class ExampleModule(ArchetypeModule[ExampleInput, ExampleOutput, ExampleSetup, E
         file = UploadFileData(
             content=b"%s\n%s" % (processed_message.encode(), str(processed_number).encode()),
             name="example_output.txt",
-            file_type="text/plain",
+            type=FileType.DOCUMENT,
             content_type="text/plain",
-            metadata={"example_key": "example_value"},
+            metadata={"sdk_created": True},
             replace_if_exists=True,
         )
 
@@ -176,10 +177,10 @@ async def test_module() -> None:
     # Check the storage
     if module.status == ModuleStatus.STOPPED:
         files, _nb_results = await module.filesystem.get_files(
-            filters=FileFilter(name="example_output.txt", context="test-mission-123"),
+            filters=FileFilter(names=["example_output.txt"]),
         )
         for file in files:
-            await module.filesystem.update_file(file.id, file_type="updated")
+            await module.filesystem.update_file(file.id, type=FileType.OTHER)
             # module.filesystem.delete_files(filters=FileFilter(name="example_output.txt", context="test-mission-123"), permanent=True)
 
             logger.info("Retrieved file: %s with ID: %s", file.name, file.id)
@@ -188,7 +189,7 @@ async def test_module() -> None:
                 if file_record:
                     logger.info("File ID: %s", file_record.id)
                     logger.info("File name: %s", file_record.name)
-                    logger.info("File type: %s", file_record.file_type)
+                    logger.info("File type: %s", file_record.type)
                     logger.info("File status: %s", file_record.status)
                     logger.info("File content: %s", file_record.content.decode())
             except Exception:

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev7}/pyproject.toml

@@ -31,7 +31,7 @@
         # which is how a nested run's output is attributed to its author. Pinned exactly
         # because it is a dated prerelease; move to >=0.1.21 once that ships stable.
         "ag-ui-protocol==0.1.21.dev1787220377",
-        "agentic-mesh-protocol==1.0.2.dev2",
+        "agentic-mesh-protocol==1.0.2",
         "agno>=2.8.0,<3",
         "anyio>=4.13.0",
         "grpcio-health-checking==1.82.1",
@@ -41,7 +41,7 @@
         "pydantic>=2.12.4",
         "redis[hiredis]>=7.4.0,<9",
     ]
-version = "1.0.4.dev5"
+    version = "1.0.4.dev7"
 
     [project.optional-dependencies]
         agno = [ "agno>=2.6" ]
@@ -208,15 +208,15 @@ version = "1.0.4.dev5"
         ]
 
         ignore = [
-            "ANN401",  # Allow typing.Any — gRPC stubs, callbacks, and dynamic APIs require it
-            "COM812",  # Disable because of formatter incompatibility
-            "DOC502",  # Allow extraneous-exception in docstring
-            "F401",    # Allow unused imports — used for availability checks
-            "N802",    # Allow PascalCase methods — gRPC servicer convention
-            "PLC0415", # Allow lazy imports — needed to break circular dependencies
-            "PLW3201", # Allow __get_pydantic_core_schema__ — Pydantic dunder hook
-            "S105",    # Hardcoded-password
-            "S403",    # Allow pickle import
+            "any-type",                       # Allow typing.Any — gRPC stubs, callbacks, and dynamic APIs require it
+            "missing-trailing-comma",         # Disable because of formatter incompatibility
+            "docstring-extraneous-exception", # Allow extraneous-exception in docstring
+            "unused-import",                  # Allow unused imports — used for availability checks
+            "invalid-function-name",          # Allow PascalCase methods — gRPC servicer convention
+            "import-outside-top-level",       # Allow lazy imports — needed to break circular dependencies
+            "bad-dunder-method-name",         # Allow __get_pydantic_core_schema__ — Pydantic dunder hook
+            "hardcoded-password-string",      # Hardcoded-password
+            "suspicious-pickle-import",       # Allow pickle import
         ]
 
         fixable = [ "ALL" ]
@@ -226,40 +226,40 @@ version = "1.0.4.dev5"
 
         [tool.ruff.lint.per-file-ignores]
             "tests/**/*.py" = [
-                "ANN001",
-                "ANN002",
-                "ANN003",
-                "ANN201",
-                "ANN401",
-                "ARG001",
-                "ARG002",
-                "C901",
-                "D100",
-                "D101",
-                "D102",
-                "D103",
-                "D107",
-                "D417",
-                "DOC201",
-                "DOC501",
-                "E501",
-                "ERA001",
-                "FBT001",
-                "FBT002",
-                "G004",
-                "N802",
-                "PERF203",
-                "PLC2701",
-                "PLR0911",
-                "PLR0912",
-                "PLR0914",
-                "PLR0915",
-                "PLR1702",
-                "PLR2004",
-                "PLR6301",
-                "S101",
-                "SLF001",
-                "TRY002",
+                "missing-type-function-argument",
+                "missing-type-args",
+                "missing-type-kwargs",
+                "missing-return-type-undocumented-public-function",
+                "any-type",
+                "unused-function-argument",
+                "unused-method-argument",
+                "complex-structure",
+                "undocumented-public-module",
+                "undocumented-public-class",
+                "undocumented-public-method",
+                "undocumented-public-function",
+                "undocumented-public-init",
+                "undocumented-param",
+                "docstring-missing-returns",
+                "docstring-missing-exception",
+                "line-too-long",
+                "commented-out-code",
+                "boolean-type-hint-positional-argument",
+                "boolean-default-value-positional-argument",
+                "logging-f-string",
+                "invalid-function-name",
+                "try-except-in-loop",
+                "import-private-name",
+                "too-many-return-statements",
+                "too-many-branches",
+                "too-many-locals",
+                "too-many-statements",
+                "too-many-nested-blocks",
+                "magic-value-comparison",
+                "no-self-use",
+                "assert",
+                "private-member-access",
+                "raise-vanilla-class",
             ]
 
         [tool.ruff.lint.pylint]

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev7}/src/digitalkin/__version__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("digitalkin")
 except PackageNotFoundError:
-    __version__ = "1.0.4.dev5"
+    __version__ = "1.0.4.dev7"

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev7}/src/digitalkin/community/agno/toolkits/registry/action.py

@@ -147,7 +147,7 @@ class SearchAction(RegistryAction):
             "tags": setup.tags,
             "visibility": setup.visibility.value if setup.visibility else None,
             "status": setup.status.value if setup.status else None,
-            "documentation": (setup.documentation or "")[: self._DOC_PREVIEW_CHARS],
+            "description": (setup.documentation or "")[: self._DOC_PREVIEW_CHARS],
         }
         # Only service setups carry a map. Omitting the key rather than rendering an empty
         # one keeps the feature out of the tools and kins surfaces entirely.

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev7}/src/digitalkin/mixins/file_history_mixin.py

@@ -10,7 +10,8 @@ from digitalkin.logger import logger
 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
+from digitalkin.models.services.filesystem import FileMetadata
+from digitalkin.models.services.storage import FileHistory
 from digitalkin.models.settings.module import get_module_settings
 
 
@@ -84,7 +85,7 @@ class FileHistoryMixin(StorageMixin, LoggerMixin):
         self._fh_cache[history_key] = history
         return history
 
-    async def append_files_history(self, context: ModuleContext, files: list[FileModel]) -> None:
+    async def append_files_history(self, context: ModuleContext, files: list[FileMetadata]) -> None:
         """Append files to file history.
 
         Files are added to the in-memory cache immediately. A storage
@@ -93,7 +94,7 @@ class FileHistoryMixin(StorageMixin, LoggerMixin):
 
         Args:
             context: Module context containing storage strategy.
-            files: List of file models to append.
+            files: Files to append.
         """
         history_key = self._get_fh_history_key(context)
         file_history = await self.load_file_history(context)

digitalkin-1.0.4.dev7/src/digitalkin/mixins/filesystem_mixin.py

@@ -0,0 +1,220 @@
+"""Filesystem Mixin to ease filesystem use."""
+
+from digitalkin.logger import logger
+from digitalkin.models.module.module_context import ModuleContext
+from digitalkin.models.services.filesystem import FileMetadata, FileType, FileUploadMetadata
+from digitalkin.models.services.services import Context
+from digitalkin.models.services.storage import Visibility
+from digitalkin.services.filesystem.filesystem_strategy import FileFilter, FilesystemRecord, UploadFileData
+
+
+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
+    async def upload_files(
+        context: ModuleContext, files: list[UploadFileData]
+    ) -> 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 await context.filesystem.upload_files(files)
+
+    @staticmethod
+    async def upload_file(
+        context: ModuleContext,
+        name: str,
+        content: bytes,
+        content_type: str,
+        type: FileType | None = None,  # Matches the canonical field name # ruff: ignore[builtin-argument-shadowing]
+        visibility: Visibility = Visibility.UNSPECIFIED,
+        *,
+        sdk_created: bool = False,
+    ) -> FileMetadata | None:
+        """Upload a single file, inferring its type from the MIME type when not given.
+
+        Args:
+            context: Module context containing the filesystem strategy
+            name: The name of the file
+            content: The content of the file
+            content_type: The MIME type of the file
+            type: The category of the file; inferred from `content_type` when omitted
+            visibility: Read-access scope; UNSPECIFIED lets the service default it
+            sdk_created: Whether this file is a module deliverable
+
+        Returns:
+            The uploaded file, or None when the upload failed.
+        """
+        try:
+            records, _uploaded, failed = await context.filesystem.upload_files([
+                UploadFileData(
+                    content=content,
+                    name=name,
+                    type=type or FileType.from_content_type(content_type),
+                    content_type=content_type,
+                    metadata=FileUploadMetadata(sdk_created=sdk_created, filename=name),
+                    replace_if_exists=True,
+                    visibility=visibility,
+                )
+            ])
+        except Exception:
+            logger.exception("Failed to upload file '%s' (%s)", name, content_type, extra=context.session.current_ids())
+            return None
+        if failed or not records:
+            logger.error("Upload rejected for file '%s' (%s)", name, content_type, extra=context.session.current_ids())
+            return None
+        return records[0]
+
+    @staticmethod
+    async def get_file(
+        context: ModuleContext,
+        file_id: str,
+        file_context: Context = Context.MISSIONS,
+        *,
+        include_content: bool = True,
+    ) -> FilesystemRecord:
+        """Retrieve a file by ID, with its content by default.
+
+        Args:
+            context: Module context containing the filesystem strategy
+            file_id: Unique identifier for the file
+            file_context: The owner context to look the file up in
+            include_content: Whether to include file content in the response
+
+        Returns:
+            File object with metadata and optionally content
+
+        Raises:
+            FilesystemServiceError: If file retrieval fails
+        """
+        return await context.filesystem.get_file(file_id, context=file_context, include_content=include_content)
+
+    @staticmethod
+    async def get_files(
+        context: ModuleContext,
+        filters: FileFilter,
+        *,
+        include_content: bool = False,
+    ) -> list[FilesystemRecord]:
+        """List files matching the given filters.
+
+        Args:
+            context: Module context containing the filesystem strategy
+            filters: Filter criteria for the files
+            include_content: Whether to include file content in the response
+
+        Returns:
+            Matching file records, empty when the lookup fails.
+        """
+        try:
+            records, _total = await context.filesystem.get_files(filters, include_content=include_content)
+        except Exception:
+            logger.exception("Failed to list files", extra=context.session.current_ids())
+            return []
+        return records
+
+    @staticmethod
+    async def delete_file(
+        context: ModuleContext,
+        file_id: str,
+        file_context: Context = Context.MISSIONS,
+        *,
+        permanent: bool = False,
+    ) -> bool:
+        """Delete a file.
+
+        Args:
+            context: Module context containing the filesystem strategy
+            file_id: Unique identifier for the file
+            file_context: The owner context to look the file up in
+            permanent: Whether to permanently delete the file
+
+        Returns:
+            True when the file was deleted.
+        """
+        try:
+            results, _deleted, _failed = await context.filesystem.delete_files(
+                FileFilter(context=file_context, file_ids=[file_id]),
+                permanent=permanent,
+            )
+        except Exception:
+            logger.exception("Failed to delete file '%s'", file_id, extra=context.session.current_ids())
+            return False
+        return results.get(file_id, False)
+
+    @staticmethod
+    async def resolve_files(
+        context: ModuleContext,
+        files: list[FileMetadata],
+        file_context: Context = Context.MISSIONS,
+    ) -> list[FileMetadata]:
+        """Backfill empty fields from what the filesystem service holds.
+
+        A setup form may submit little more than an id; the persisted entry has to stay
+        displayable, so anything the caller left empty is filled from the stored record.
+        A file the service cannot return is kept as submitted rather than dropped.
+
+        Args:
+            context: Module context containing the filesystem strategy
+            files: The files as submitted
+            file_context: The owner context the files live in; setup-time uploads are
+                scoped to the setup, not the mission
+
+        Returns:
+            The files, with empty fields filled in where the service could resolve them.
+        """
+        resolved: list[FileMetadata] = []
+        for file in files:
+            try:
+                record = await context.filesystem.get_file(file.id, context=file_context, include_content=False)
+            except Exception:
+                logger.warning(
+                    "Could not resolve file '%s'; keeping it as submitted",
+                    file.id,
+                    exc_info=True,
+                    extra=context.session.current_ids(),
+                )
+                resolved.append(file)
+                continue
+            resolved.append(
+                file.model_copy(
+                    update={
+                        "name": file.name or record.name,
+                        "type": file.type if file.type is not FileType.UNSPECIFIED else record.type,
+                        "content_type": file.content_type or record.content_type,
+                        "size_bytes": file.size_bytes or record.size_bytes,
+                        "file_url": file.file_url or record.file_url,
+                    }
+                )
+            )
+        return resolved
+
+    @staticmethod
+    async def set_visibility(context: ModuleContext, file_id: str, visibility: Visibility) -> FilesystemRecord:
+        """Change the read-access scope of an already uploaded file.
+
+        Visibility is otherwise write-once at upload time, so this is the only way to
+        widen or narrow access to a file the module has already produced.
+
+        Args:
+            context: Module context containing the filesystem strategy
+            file_id: Unique identifier for the file
+            visibility: The new read-access scope; UNSPECIFIED leaves it unchanged
+
+        Returns:
+            The updated file record.
+        """
+        return await context.filesystem.update_file(file_id, visibility=visibility)

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev7}/src/digitalkin/models/module/__init__.py

@@ -1,5 +1,9 @@
 """Module model exports. Import ag_ui types from ``digitalkin.models.module.ag_ui``."""
 
+from digitalkin.models.module.knowledge_files import (
+    KnowledgeFileFormatError,
+    knowledge_files_input,
+)
 from digitalkin.models.module.loaded_tools import (
     LOADED_TOOLS_STORAGE_CONFIG,
     LoadedToolRecord,
@@ -34,6 +38,7 @@ __all__ = [
     "DataModel",
     "DataTrigger",
     "EndOfStreamOutput",
+    "KnowledgeFileFormatError",
     "LoadedToolRecord",
     "LoadedToolStore",
     "ModuleContext",
@@ -47,5 +52,6 @@ __all__ = [
     "ToolSelection",
     "UtilityProtocol",
     "UtilityRegistry",
+    "knowledge_files_input",
     "tool_reference_input",
 ]

digitalkin-1.0.4.dev7/src/digitalkin/models/module/knowledge_files.py

@@ -0,0 +1,87 @@
+"""Setup field for files a module ingests at config-setup time.
+
+Declares the pair every file-consuming module needs — the selected files and the
+formats it accepts — so the field, its widget options and its validation stay
+identical across modules::
+
+    class MySetup(SetupModel):
+        knowledge_files: knowledge_files_input(extensions=[".json"]) = Field(
+            default_factory=list,
+            title="Knowledge Files",
+            description="Files imported into setup-scoped storage at config-setup time.",
+        )
+
+The allowed formats reach the front-end file widget as ``ui:options.accept`` and are
+enforced again on submit, since the widget's filter is only a hint.
+"""
+
+from collections.abc import Sequence
+from typing import Annotated, Any
+
+from pydantic import AfterValidator, Field
+
+from digitalkin.models.services.filesystem import FileMetadata, FileType
+
+
+class KnowledgeFileFormatError(ValueError):
+    """A submitted file is not in a format the module accepts."""
+
+
+def knowledge_files_input(
+    extensions: Sequence[str] = (),
+    file_types: Sequence[FileType] = (),
+    *,
+    multiple: bool = True,
+    config: bool = True,
+) -> Any:
+    """Build the annotated type for a setup field holding uploaded files.
+
+    Args:
+        extensions: Accepted file extensions, leading dot included (e.g. ``.pdf``).
+            Empty accepts any extension.
+        file_types: Accepted categories. Empty accepts any category.
+        multiple: Whether the widget allows selecting more than one file.
+        config: Whether the field belongs to the config-setup schema rather than
+            the runtime setup schema.
+
+    Returns:
+        Annotated type for use in a `SetupModel` field.
+    """
+    allowed_extensions = frozenset(e.lower() if e.startswith(".") else f".{e.lower()}" for e in extensions)
+    allowed_types = frozenset(file_types)
+
+    def validate_formats(files: list[FileMetadata]) -> list[FileMetadata]:
+        """Reject any file whose extension or category the module does not accept.
+
+        Returns:
+            The files, unchanged.
+
+        Raises:
+            KnowledgeFileFormatError: If a file is in an unaccepted format.
+        """
+        for file in files:
+            # A bare-id submission carries no name yet; the format is checked once the
+            # filesystem service has resolved it, not guessed at here.
+            suffix = f".{file.name.rsplit('.', 1)[-1].lower()}" if "." in file.name else ""
+            if suffix and allowed_extensions and suffix not in allowed_extensions:
+                msg = f"'{file.name}' is not an accepted format; expected one of {sorted(allowed_extensions)}"
+                raise KnowledgeFileFormatError(msg)
+            if allowed_types and file.type is not FileType.UNSPECIFIED and file.type not in allowed_types:
+                msg = (
+                    f"'{file.name}' is a {file.type.name} file; expected one of {sorted(t.name for t in allowed_types)}"
+                )
+                raise KnowledgeFileFormatError(msg)
+        return files
+
+    ui_options: dict[str, Any] = {"multiple": multiple}
+    if allowed_extensions:
+        ui_options["accept"] = sorted(allowed_extensions)
+    schema_extra: dict[str, Any] = {"ui:widget": "file", "ui:options": ui_options}
+    if config:
+        schema_extra["config"] = True
+
+    return Annotated[
+        list[FileMetadata],
+        Field(json_schema_extra=schema_extra),
+        AfterValidator(validate_formats),
+    ]

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev7}/src/digitalkin/models/services/__init__.py

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