python-base-agent 2026.2.13__py3-none-any.whl

base_agent/storage/models.py

@@ -0,0 +1,73 @@
+"""Data models for Object Storage - Based on Java ObjectStore data classes"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, BinaryIO
+
+
+@dataclass
+class ObjectSummary:
+    """
+    Summary information about an object in the object store.
+    Maps to Java: ObjectSummary.java
+    """
+
+    key: str
+    size: int
+    last_modified: datetime
+    etag: str | None = None
+
+
+@dataclass
+class ObjectMetadata:
+    """
+    Metadata for an object without retrieving its content.
+    Maps to Java: ObjectMetadata.java
+    """
+
+    content_type: str | None
+    content_length: int
+    etag: str | None
+    last_modified: datetime | None
+    metadata: dict[str, str] | None = None
+
+
+@dataclass
+class ObjectResponse:
+    """
+    Response containing an object's content stream and metadata.
+    Maps to Java: ObjectResponse.java
+    """
+
+    input_stream: BinaryIO | Any  # Can be async stream
+    content_length: int
+    content_type: str | None
+    metadata: dict[str, str] | None = None
+
+    async def close(self) -> None:
+        """Close the input stream if it's closeable."""
+        if hasattr(self.input_stream, "close"):
+            if hasattr(self.input_stream, "__aclose__"):
+                await self.input_stream.__aclose__()
+            else:
+                self.input_stream.close()
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+
+@dataclass
+class ListObjectsResponse:
+    """
+    Response from listing objects with pagination support.
+    Maps to Java: ListObjectsResponse.java
+    """
+
+    objects: list[ObjectSummary]
+    continuation_token: str | None = None
+    is_truncated: bool = False

base_agent/storage/object_store.py

@@ -0,0 +1,248 @@
+"""Object Storage abstraction - Based on Java ObjectStore.java"""
+
+from typing import Protocol
+
+from base_agent.storage.models import (
+    ListObjectsResponse,
+    ObjectMetadata,
+    ObjectResponse,
+    ObjectSummary,
+)
+
+
+class ObjectStore(Protocol):
+    """
+    Generic interface for object storage operations.
+    This abstraction allows swapping between different storage providers (S3, Azure Blob, GCS, etc.)
+
+    Maps to Java: ObjectStore.java
+    """
+
+    async def put_object(
+        self,
+        bucket: str,
+        key: str,
+        content: bytes,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> bool:
+        """
+        Store an object in the object store.
+
+        Java Reference: ObjectStore.java:29
+
+        Args:
+            bucket: The bucket name
+            key: The object key
+            content: The content to store as bytes
+            content_type: The MIME type of the content
+            metadata: Optional metadata to attach to the object
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    async def get_object(self, bucket: str, key: str) -> bytes | None:
+        """
+        Retrieve an object from the object store.
+
+        Java Reference: ObjectStore.java:66
+
+        Args:
+            bucket: The bucket name
+            key: The object key
+
+        Returns:
+            The object content as bytes, or None if not found
+        """
+        ...
+
+    async def get_object_stream(self, bucket: str, key: str) -> ObjectResponse | None:
+        """
+        Retrieve an object from the object store as a stream.
+
+        Java Reference: ObjectStore.java:75
+
+        Args:
+            bucket: The bucket name
+            key: The object key
+
+        Returns:
+            An ObjectResponse containing the input stream and metadata, or None if not found
+        """
+        ...
+
+    async def delete_object(self, bucket: str, key: str) -> bool:
+        """
+        Delete an object from the object store.
+
+        Java Reference: ObjectStore.java:84
+
+        Args:
+            bucket: The bucket name
+            key: The object key
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    async def list_objects(
+        self, bucket: str, prefix: str | None = None, max_keys: int = 1000
+    ) -> list[ObjectSummary]:
+        """
+        List objects in a bucket with optional prefix.
+
+        Java Reference: ObjectStore.java:94
+
+        Args:
+            bucket: The bucket name
+            prefix: Optional prefix to filter objects
+            max_keys: Maximum number of keys to return
+
+        Returns:
+            List of object summaries
+        """
+        ...
+
+    async def list_objects_paginated(
+        self,
+        bucket: str,
+        prefix: str | None = None,
+        max_keys: int = 1000,
+        continuation_token: str | None = None,
+    ) -> ListObjectsResponse:
+        """
+        List objects in a bucket with pagination.
+
+        Java Reference: ObjectStore.java:105
+
+        Args:
+            bucket: The bucket name
+            prefix: Optional prefix to filter objects
+            max_keys: Maximum number of keys to return
+            continuation_token: Token for pagination
+
+        Returns:
+            ListObjectsResponse containing objects and next continuation token
+        """
+        ...
+
+    async def copy_object(
+        self,
+        source_bucket: str,
+        source_key: str,
+        destination_bucket: str,
+        destination_key: str,
+    ) -> bool:
+        """
+        Copy an object within the object store.
+
+        Java Reference: ObjectStore.java:116
+
+        Args:
+            source_bucket: The source bucket name
+            source_key: The source object key
+            destination_bucket: The destination bucket name
+            destination_key: The destination object key
+
+        Returns:
+            True if successful, False otherwise
+        """
+        ...
+
+    async def object_exists(self, bucket: str, key: str) -> bool:
+        """
+        Check if an object exists.
+
+        Java Reference: ObjectStore.java:125
+
+        Args:
+            bucket: The bucket name
+            key: The object key
+
+        Returns:
+            True if the object exists, False otherwise
+        """
+        ...
+
+    async def create_bucket_if_not_exists(self, bucket: str) -> bool:
+        """
+        Create a bucket if it doesn't exist.
+
+        Java Reference: ObjectStore.java:133
+
+        Args:
+            bucket: The bucket name
+
+        Returns:
+            True if bucket was created or already exists, False on error
+        """
+        ...
+
+    async def list_buckets(self) -> list[str]:
+        """
+        List all buckets.
+
+        Java Reference: ObjectStore.java:140
+
+        Returns:
+            List of bucket names
+        """
+        ...
+
+    async def bucket_exists(self, bucket: str) -> bool:
+        """
+        Check if a bucket exists.
+
+        Java Reference: ObjectStore.java:148
+
+        Args:
+            bucket: The bucket name
+
+        Returns:
+            True if the bucket exists, False otherwise
+        """
+        ...
+
+    async def generate_presigned_url(
+        self, bucket: str, key: str, expiration_minutes: int = 60
+    ) -> str | None:
+        """
+        Generate a pre-signed URL for temporary access to an object.
+
+        Java Reference: ObjectStore.java:158
+
+        Args:
+            bucket: The bucket name
+            key: The object key
+            expiration_minutes: Expiration time in minutes
+
+        Returns:
+            The pre-signed URL, or None if not supported
+        """
+        ...
+
+    async def get_object_metadata(self, bucket: str, key: str) -> ObjectMetadata | None:
+        """
+        Get metadata for an object without retrieving its content.
+
+        Java Reference: ObjectStore.java:167
+
+        Args:
+            bucket: The bucket name
+            key: The object key
+
+        Returns:
+            Object metadata, or None if not found
+        """
+        ...
+
+    async def initialize(self) -> None:
+        """Initialize the object store connection."""
+        ...
+
+    async def close(self) -> None:
+        """Close the object store connection and cleanup resources."""
+        ...

base_agent/storage/object_store_factory.py

@@ -0,0 +1,136 @@
+"""
+Object Store factory for creating storage instances based on configuration.
+
+Maps to Java: ObjectStoreFactory.java
+"""
+
+import logging
+import os
+
+from base_agent.storage.azure_store import AzureBlobObjectStore
+from base_agent.storage.object_store import ObjectStore
+from base_agent.storage.s3_store import S3ObjectStore
+
+logger = logging.getLogger(__name__)
+
+
+class ObjectStoreFactory:
+    """
+    Factory for creating ObjectStore instances based on environment configuration.
+
+    Configuration is read from environment variables:
+    - OBJECT_STORE_TYPE: Type of storage (s3, minio, azure)
+    - Additional provider-specific variables (see specific factory methods)
+    """
+
+    @staticmethod
+    def create_object_store() -> ObjectStore:
+        """
+        Create an ObjectStore instance based on OBJECT_STORE_TYPE environment variable.
+
+        Returns:
+            ObjectStore implementation (S3ObjectStore, AzureBlobObjectStore, etc.)
+
+        Raises:
+            ValueError: If configuration is invalid or missing required variables
+            NotImplementedError: If provider type is not yet implemented
+        """
+        store_type: str = os.getenv("OBJECT_STORE_TYPE", "s3").lower()
+
+        logger.info("Creating object store with type: %s", store_type)
+
+        if store_type in ["s3", "minio"]:
+            return ObjectStoreFactory._create_s3_object_store()
+        if store_type == "azure":
+            return ObjectStoreFactory._create_azure_object_store()
+        raise ValueError(
+            f"Unsupported object store type: {store_type}. Supported types: s3, minio, azure"
+        )
+
+    @staticmethod
+    def _create_s3_object_store() -> S3ObjectStore:
+        """
+        Create an S3-compatible ObjectStore instance.
+
+        Required environment variables:
+        - OBJECT_STORE_ENDPOINT: S3 endpoint URL (e.g., http://localhost:9000)
+        - OBJECT_STORE_ACCESS_KEY: Access key ID
+        - OBJECT_STORE_SECRET_KEY: Secret access key
+        - OBJECT_STORE_REGION: AWS region (e.g., us-east-1)
+
+        Returns:
+            S3ObjectStore instance
+
+        Raises:
+            ValueError: If required configuration is missing
+        """
+        logger.info("Creating S3-compatible object store client")
+
+        # Validate required configuration
+        required_vars = [
+            "OBJECT_STORE_ENDPOINT",
+            "OBJECT_STORE_ACCESS_KEY",
+            "OBJECT_STORE_SECRET_KEY",
+            "OBJECT_STORE_REGION",
+        ]
+
+        missing_vars = [var for var in required_vars if not os.getenv(var)]
+        if missing_vars:
+            raise ValueError(
+                f"Missing required configuration for S3 object store: {', '.join(missing_vars)}"
+            )
+
+        endpoint_url = os.getenv("OBJECT_STORE_ENDPOINT")
+        access_key_id = os.getenv("OBJECT_STORE_ACCESS_KEY")
+        secret_access_key = os.getenv("OBJECT_STORE_SECRET_KEY")
+        region = os.getenv("OBJECT_STORE_REGION")
+
+        return S3ObjectStore(
+            endpoint=endpoint_url,
+            access_key=access_key_id,
+            secret_key=secret_access_key,
+            region=region,
+        )
+
+    @staticmethod
+    def _create_azure_object_store() -> AzureBlobObjectStore:
+        """
+        Create an Azure Blob Storage ObjectStore instance.
+
+        Configuration is read from environment variables:
+        - AZURE_STORAGE_CONNECTION_STRING: Full connection string (highest priority)
+        - AZURE_STORAGE_ACCOUNT: Storage account name
+        - AZURE_STORAGE_KEY: Storage account key (optional, uses AAD if not provided)
+        - AZURE_STORAGE_ENDPOINT: Custom endpoint URL (optional)
+
+        Auth priority:
+        1. Connection string (if AZURE_STORAGE_CONNECTION_STRING is set)
+        2. Account key (if AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY are set)
+        3. DefaultAzureCredential (AAD - managed identity, workload identity, etc.)
+
+        Returns:
+            AzureBlobObjectStore instance
+
+        Raises:
+            ValueError: If configuration is invalid or missing required variables
+        """
+        logger.info("Creating Azure Blob Storage object store client")
+
+        connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")
+        account = os.getenv("AZURE_STORAGE_ACCOUNT")
+        account_key = os.getenv("AZURE_STORAGE_KEY")
+        endpoint = os.getenv("AZURE_STORAGE_ENDPOINT")
+
+        # Validate configuration - need either connection string or account name
+        if not connection_string and not account:
+            raise ValueError(
+                "Azure Blob Storage requires either AZURE_STORAGE_CONNECTION_STRING "
+                "or AZURE_STORAGE_ACCOUNT to be set"
+            )
+
+        return AzureBlobObjectStore(
+            account=account,
+            endpoint=endpoint,
+            connection_string=connection_string,
+            account_key=account_key,
+        )