digitalkin 1.0.4.dev5__tar.gz → 1.0.4.dev6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.4.dev5
+Version: 1.0.4.dev6
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/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.dev6}/pyproject.toml

@@ -41,7 +41,7 @@
         "pydantic>=2.12.4",
         "redis[hiredis]>=7.4.0,<9",
     ]
-version = "1.0.4.dev5"
+    version = "1.0.4.dev6"
 
     [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.dev6}/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.dev6"

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/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.dev6}/src/digitalkin/core/resilience/bulkhead.py

@@ -15,12 +15,13 @@ Usage in ModuleContext or service wrapper::
 from __future__ import annotations
 
 import asyncio
+import os
 from typing import ClassVar
 
 from typing_extensions import Self
 
 from digitalkin.core.exceptions import BulkheadFullError
-from digitalkin.models.settings.resilience import BulkheadServiceSettings, get_bulkhead_settings
+from digitalkin.models.settings.resilience import get_bulkhead_settings
 
 
 class Bulkhead:
@@ -61,10 +62,10 @@ class Bulkhead:
             del cls._instances[oldest]
 
         settings = get_bulkhead_settings()
-        # The override carries the service id in the variable name; the settings
-        # class builds that prefix itself, so nothing here touches the environment.
-        override = BulkheadServiceSettings(service_id).max
-        max_concurrent = override if override is not None else settings.default_max
+        # Per-service override has a dynamic env-var suffix, so it cannot be a
+        # static settings field — read it directly, falling back to the setting.
+        env_max = os.environ.get(f"DIGITALKIN_BULKHEAD_{service_id.upper()}_MAX")
+        max_concurrent = int(env_max) if env_max is not None else settings.default_max
 
         inst = cls(
             service_id=service_id,

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/src/digitalkin/core/task_manager/redis/proto_streams.py

@@ -43,7 +43,7 @@ class ProtoStreamReader:
         """Initialize proto stream reader.
 
         Cursor TTL comes from ``GatewayStreamSettings.redis_cursor_ttl`` (env
-        ``DIGITALKIN_GATEWAY_STREAM_REDIS_CURSOR_TTL``).
+        ``DIGITALKIN_REDIS_CURSOR_TTL``).
 
         Args:
             task_id: Unique task identifier.

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/src/digitalkin/grpc_servers/_base_server.py

@@ -35,7 +35,6 @@ from digitalkin.logger import logger
 from digitalkin.models.grpc_servers.types import GrpcServer, ServiceDescriptor, T
 from digitalkin.models.settings.server.server import get_server_settings
 from digitalkin.models.settings.utils.channel import ControlFlow, SecurityMode
-from digitalkin.utils.env_manager import EnvManager
 
 
 class BaseServer(abc.ABC):
@@ -258,9 +257,10 @@ class BaseServer(abc.ABC):
         Raises:
             SecurityError: If credentials are missing or unreadable.
         """
-        # Explicit SERVER_CHANNEL_CREDENTIALS__* paths, else the CERTIFICATE_CERT_VOLUME
-        # directory; the resolution itself raises when the key or certificate is absent.
-        creds = EnvManager.server_credentials()
+        creds = get_server_settings().channel.credentials
+        if not creds:
+            msg = "Credentials must be provided for secure server"
+            raise SecurityError(msg)
 
         try:  # ruff: ignore[too-many-statements-in-try-clause]
             if creds.key_path and creds.cert_path:

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/src/digitalkin/grpc_servers/module_server.py

@@ -1,5 +1,6 @@
 """Module gRPC server implementation for DigitalKin."""
 
+import os
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
@@ -14,12 +15,9 @@ from digitalkin.grpc_servers.gateway_servicer import GatewayServicer
 from digitalkin.grpc_servers.module_servicer import ModuleServicer
 from digitalkin.logger import logger
 from digitalkin.models.grpc_servers.models import ClientConfig
-from digitalkin.models.services.services import ServicesMode
-from digitalkin.models.settings.redis import get_redis_settings
 from digitalkin.models.settings.server.server import get_server_settings
 from digitalkin.modules._base_module import BaseModule
 from digitalkin.services.registry import GrpcRegistry
-from digitalkin.utils.env_manager import EnvManager
 
 if TYPE_CHECKING:
     from digitalkin.services.registry import RegistryStrategy
@@ -42,11 +40,6 @@ class ModuleServer(BaseServer):
     ) -> None:
         """Initialize the module server.
 
-        In remote mode an omitted ``client_config`` is built from the
-        environment, so a module no longer declares one to reach the registry
-        and the services provider. Local mode keeps it unset: there is no
-        registry to register with.
-
         Args:
             module_class: The module class to serve.
             client_config: Client configuration for services and registry.
@@ -56,8 +49,6 @@ class ModuleServer(BaseServer):
 
         super().__init__(interceptors=all_interceptors or None)
         self.module_class = module_class
-        if client_config is None and EnvManager.services_mode() == ServicesMode.REMOTE:
-            client_config = EnvManager.client_config()
         self.client_config = client_config
         self.registry: RegistryStrategy | None = None
         self.module_servicer: ModuleServicer | None = None
@@ -102,9 +93,9 @@ class ModuleServer(BaseServer):
         dispatcher process, queue, or Redis stream for dispatch.
 
         Raises:
-            RuntimeError: If DIGITALKIN_REDIS_URL resolves to an empty URL.
+            RuntimeError: If DIGITALKIN_REDIS_URL is not set.
         """
-        redis_url = get_redis_settings().pool.url.get_secret_value()
+        redis_url = os.environ.get("DIGITALKIN_REDIS_URL")
         if not redis_url:
             msg = "DIGITALKIN_REDIS_URL is required. The gateway needs Redis for stream persistence."
             raise RuntimeError(msg)

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/src/digitalkin/grpc_servers/module_servicer.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import json
+import os
 import time
 from argparse import ArgumentParser, Namespace
 from collections.abc import Awaitable, Callable
@@ -27,7 +28,6 @@ from digitalkin.models.module.module import ModuleCodeModel
 from digitalkin.models.module.setup_types import SetupModel
 from digitalkin.models.services.services import ServicesMode
 from digitalkin.models.settings.gateway import get_gateway_settings
-from digitalkin.models.settings.redis import get_redis_settings
 from digitalkin.models.settings.server.servicer import get_module_servicer_settings
 from digitalkin.modules._base_module import BaseModule
 from digitalkin.services.registry import GrpcRegistry, RegistryStrategy
@@ -37,7 +37,6 @@ from digitalkin.services.setup.setup_strategy import SetupStrategy, SetupVersion
 from digitalkin.services.user_profile import DefaultUserProfile, GrpcUserProfile, UserProfileStrategy
 from digitalkin.utils.arg_parser import ArgParser
 from digitalkin.utils.development_mode_action import DevelopmentModeMappingAction
-from digitalkin.utils.env_manager import EnvManager
 
 
 class ModuleServicer(module_service_pb2_grpc.ModuleServiceServicer, ArgParser):
@@ -56,7 +55,9 @@ class ModuleServicer(module_service_pb2_grpc.ModuleServiceServicer, ArgParser):
         parser.add_argument(
             "-d",
             "--dev-mode",
+            env_var="SERVICE_MODE",
             choices=ServicesMode.__members__,
+            default="local",
             action=DevelopmentModeMappingAction,
             dest="services_mode",
             help="Define Module Service configurations for endpoints",
@@ -69,13 +70,13 @@ class ModuleServicer(module_service_pb2_grpc.ModuleServiceServicer, ArgParser):
             module_class: The module type to serve.
 
         Raises:
-            RuntimeError: If DIGITALKIN_REDIS_URL resolves to an empty URL.
+            RuntimeError: If DIGITALKIN_REDIS_URL is not set.
         """
         super().__init__()
         module_class.discover()
         self.module_class = module_class
 
-        redis_url = get_redis_settings().pool.url.get_secret_value()
+        redis_url = os.environ.get("DIGITALKIN_REDIS_URL")
         if not redis_url:
             msg = "DIGITALKIN_REDIS_URL is required"
             raise RuntimeError(msg)
@@ -89,7 +90,10 @@ class ModuleServicer(module_service_pb2_grpc.ModuleServiceServicer, ArgParser):
         # Access-control client gating the setup cache. Always built, always called (fail-closed).
         if self.args.services_mode == ServicesMode.REMOTE:
             up_cfg = self.module_class.services_config_params.get("user_profile") or {}
-            up_client_config = up_cfg.get("client_config") or EnvManager.client_config()
+            up_client_config = up_cfg.get("client_config")
+            if not up_client_config:
+                msg = "user_profile client_config is required for setup access control"
+                raise RuntimeError(msg)
             self.user_profile = GrpcUserProfile("", "", "", up_client_config)
         else:
             self.user_profile = DefaultUserProfile("", "", "")

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/src/digitalkin/grpc_servers/utils/circuit_breaker.py

@@ -15,7 +15,7 @@ from typing import ClassVar
 from digitalkin.grpc_servers.exceptions import CircuitOpenError
 from digitalkin.logger import logger
 from digitalkin.models.grpc_servers.circuit_breaker import CBState
-from digitalkin.models.settings.client.client import get_client_settings
+from digitalkin.models.settings.grpc_client import get_circuit_breaker_settings
 
 
 class CircuitBreaker:
@@ -45,7 +45,7 @@ class CircuitBreaker:
         """Get existing circuit breaker for a service or create one.
 
         Thresholds come from ``CircuitBreakerSettings`` (env
-        ``CLIENT_CIRCUIT_BREAKER_FAIL_MAX``, ``CLIENT_CIRCUIT_BREAKER_RESET_TIMEOUT``).
+        ``DIGITALKIN_CB_FAIL_MAX``, ``DIGITALKIN_CB_RESET_TIMEOUT``).
 
         Args:
             service_id: Service identifier.
@@ -54,7 +54,7 @@ class CircuitBreaker:
             Circuit breaker for this service.
         """
         if service_id not in cls._instances:
-            settings = get_client_settings().circuit_breaker
+            settings = get_circuit_breaker_settings()
             cls._instances[service_id] = cls(service_id, settings.fail_max, settings.reset_timeout)
         return cls._instances[service_id]
 

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/src/digitalkin/grpc_servers/utils/grpc_client_wrapper.py

@@ -21,7 +21,7 @@ from digitalkin.grpc_servers.interceptors.request_ids import RequestIdClientInte
 from digitalkin.grpc_servers.utils.circuit_breaker import CircuitBreaker
 from digitalkin.logger import logger
 from digitalkin.models.grpc_servers.models import ClientConfig
-from digitalkin.models.settings.client.client import get_client_settings
+from digitalkin.models.settings.grpc_client import get_grpc_client_settings
 from digitalkin.models.settings.utils.channel import SecurityMode
 
 
@@ -240,7 +240,7 @@ class GrpcClientWrapper:
 
         Retries on transient errors (UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED)
         with exponential backoff. Retry count and backoff base are configurable
-        via CLIENT_MAX_RETRIES and CLIENT_BACKOFF_BASE_MS.
+        via DIGITALKIN_GRPC_QUERY_MAX_RETRIES and DIGITALKIN_GRPC_QUERY_BACKOFF_BASE_MS.
 
         Arguments:
             query_endpoint: rpc query name (e.g., "GetSetup", "CreateSetupVersion")
@@ -269,10 +269,10 @@ class GrpcClientWrapper:
             error_msg = f"[gRPC-client:{self.service_name}.{query_endpoint}] {e}"
             raise ServerError(error_msg) from e
 
-        client_settings = get_client_settings()
-        eff_timeout = timeout if timeout is not None else client_settings.timeout
-        max_retries = client_settings.max_retries
-        backoff_base_ms = client_settings.backoff_base_ms
+        grpc_settings = get_grpc_client_settings()
+        eff_timeout = timeout if timeout is not None else grpc_settings.timeout
+        max_retries = grpc_settings.max_retries
+        backoff_base_ms = grpc_settings.backoff_base_ms
         backoff_delays = tuple(backoff_base_ms / 1000 * (2**i) for i in range(max_retries))
         last_error: grpc.RpcError | None = None
 

{digitalkin-1.0.4.dev5 → digitalkin-1.0.4.dev6}/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.dev6/src/digitalkin/mixins/filesystem_mixin.py

@@ -0,0 +1,215 @@
+"""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)
+            return None
+        if failed or not records:
+            logger.error("Upload rejected for file '%s' (%s)", name, content_type)
+            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")
+            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)
+            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)
+                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)