Add AWS S3 ResourcesRepository

Author: KaQuMiQ

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "uv_build"
 [project]
 name = "draive"
 description = "Framework designed to simplify and accelerate the development of LLM-based applications."
-version = "0.93.4"
+version = "0.94.0"
 readme = "README.md"
 maintainers = [
   { name = "Kacper Kaliński", email = "[email protected]" },
@@ -41,6 +41,7 @@ mistral = ["mistralai~=1.9"]
 gemini = ["google-genai~=1.50", "google-api-core"]
 ollama = ["ollama~=0.6.0"]
 bedrock = ["boto3~=1.40"]
+aws = ["boto3~=1.40"]
 vllm = ["openai~=2.8"]
 mcp = ["mcp~=1.21"]
 opentelemetry = [

src/draive/aws/__init__.py

@@ -0,0 +1,9 @@
+from draive.aws.client import AWS
+from draive.aws.types import AWSAccessDenied, AWSError, AWSResourceNotFound
+
+__all__ = (
+    "AWS",
+    "AWSAccessDenied",
+    "AWSError",
+    "AWSResourceNotFound",
+)

src/draive/aws/api.py

@@ -0,0 +1,68 @@
+from typing import Any
+
+from boto3 import Session  # pyright: ignore[reportMissingTypeStubs]
+from haiway import asynchronous
+
+__all__ = [
+    "AWSAPI",
+]
+
+
+class AWSAPI:
+    """Low-level AWS session and client management.
+
+    Provides an asynchronous S3 client initializer that other mixins
+    can rely on without duplicating boto3 session wiring.
+    """
+
+    __slots__ = (
+        "_s3_client",
+        "_session",
+    )
+
+    def __init__(
+        self,
+        region_name: str | None = None,
+        access_key_id: str | None = None,
+        secret_access_key: str | None = None,
+    ) -> None:
+        """Create an AWS session.
+
+        Parameters
+        ----------
+        region_name
+            Preferred AWS region for the session. Defaults to the
+            region configured in the environment or AWS profiles.
+        access_key_id
+            Optional access key identifier used for credential override.
+        secret_access_key
+            Optional secret key paired with ``access_key_id`` for override.
+        """
+        # using dict as kwargs since existence of some
+        # arguments when initializing session changes
+        # the session configuration, even if using None
+        kwargs: dict[str, object] = {}
+
+        if key_id := access_key_id:
+            kwargs["aws_access_key_id"] = key_id
+
+        if key := secret_access_key:
+            kwargs["aws_secret_access_key"] = key
+
+        if region := region_name:
+            kwargs["region_name"] = region
+
+        self._session: Session = Session(**kwargs)
+        self._s3_client: Any
+
+    @asynchronous
+    def _prepare_client(self) -> None:
+        self._s3_client = self._session.client(  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
+            service_name="s3",
+        )
+
+    @property
+    def region(self) -> str | None:
+        """Currently configured AWS region for the session."""
+
+        return self._session.region_name  # pyright: ignore[reportUnknownMemberType, reportReturnType, reportUnknownVariableType]

src/draive/aws/client.py

@@ -0,0 +1,78 @@
+from collections.abc import Collection, Iterable
+from types import TracebackType
+from typing import final
+
+from haiway import State
+
+from draive.aws.api import AWSAPI
+from draive.aws.s3 import AWSS3Mixin
+from draive.resources import ResourcesRepository
+
+__all__ = ("AWS",)
+
+
+@final
+class AWS(
+    AWSS3Mixin,
+    AWSAPI,
+):
+    """AWS service facade bundling S3 and repository integrations.
+
+    Parameters
+    ----------
+    region_name
+        Preferred AWS region. Falls back to profile or environment
+        configuration when omitted.
+    access_key_id
+        Optional access key identifier used to override ambient
+        credentials.
+    secret_access_key
+        Secret key paired with ``access_key_id`` when overriding
+        credentials.
+    features
+        Collection of repository feature classes to activate while the
+        client is bound in a context manager.
+    """
+    __slots__ = ("_features",)
+
+    def __init__(
+        self,
+        region_name: str | None = None,
+        access_key_id: str | None = None,
+        secret_access_key: str | None = None,
+        features: Collection[type[ResourcesRepository]] | None = None,
+    ) -> None:
+        super().__init__(
+            region_name=region_name,
+            access_key_id=access_key_id,
+            secret_access_key=secret_access_key,
+        )
+
+        self._features: Collection[type[ResourcesRepository]]
+        if features is not None:
+            self._features = features
+
+        else:
+            self._features = (ResourcesRepository,)
+
+    async def __aenter__(self) -> Iterable[State]:
+        """Prepare the AWS client and bind selected features to context."""
+        await self._prepare_client()
+
+        if ResourcesRepository in self._features:
+            return (
+                ResourcesRepository(
+                    fetching=self.fetch,
+                    uploading=self.upload,
+                ),
+            )
+
+        return ()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """No-op cleanup to satisfy the async context manager protocol."""