chuk-artifacts 0.1.0__py3-none-any.whl

chuk_artifacts/__init__.py

@@ -0,0 +1,149 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/__init__.py
+"""
+Asynchronous, object-store-backed artifact manager.
+
+This package provides a high-level interface for storing and retrieving
+artifacts across multiple storage backends (S3, IBM COS, filesystem, memory)
+with metadata caching and presigned URL support.
+"""
+from __future__ import annotations
+from dotenv import load_dotenv
+
+# Core classes
+from .store import ArtifactStore
+
+# Exception classes
+from .exceptions import (
+    ArtifactStoreError,
+    ArtifactNotFoundError,
+    ArtifactExpiredError,
+    ArtifactCorruptedError,
+    ProviderError,
+    SessionError,
+)
+
+# Operation modules (for advanced usage)
+from .core import CoreStorageOperations
+from .presigned import PresignedURLOperations
+from .metadata import MetadataOperations
+from .batch import BatchOperations
+from .admin import AdminOperations
+from .store import _DEFAULT_TTL, _DEFAULT_PRESIGN_EXPIRES
+
+
+# load dot env
+load_dotenv()
+
+# version
+__version__ = "1.0.0"
+
+__all__ = [
+    # Main class
+    "ArtifactStore",
+    
+    # Exceptions
+    "ArtifactStoreError", 
+    "ArtifactNotFoundError",
+    "ArtifactExpiredError",
+    "ArtifactCorruptedError",
+    "ProviderError",
+    "SessionError",
+    
+    # Operation modules (advanced usage)
+    "CoreStorageOperations",
+    "PresignedURLOperations", 
+    "MetadataOperations",
+    "BatchOperations",
+    "AdminOperations",
+    
+    # Constants
+    "_DEFAULT_TTL",
+    "_DEFAULT_PRESIGN_EXPIRES",
+]
+
+# Convenience aliases for common operations
+def create_store(**kwargs) -> ArtifactStore:
+    """
+    Convenience function to create an ArtifactStore with sensible defaults.
+    
+    Parameters
+    ----------
+    **kwargs
+        Passed to ArtifactStore constructor
+        
+    Returns
+    -------
+    ArtifactStore
+        Configured artifact store
+        
+    Examples
+    --------
+    >>> store = create_store()  # Memory-based
+    >>> store = create_store(storage_provider="ibm_cos", bucket="my-bucket")
+    """
+    return ArtifactStore(**kwargs)
+
+
+async def quick_store(
+    data: bytes, 
+    *,
+    mime: str = "application/octet-stream",
+    summary: str = "Quick upload",
+    **store_kwargs
+) -> tuple[ArtifactStore, str]:
+    """
+    Convenience function for quick one-off artifact storage.
+    
+    Parameters
+    ----------
+    data : bytes
+        Data to store
+    mime : str, optional
+        MIME type
+    summary : str, optional
+        Description
+    **store_kwargs
+        Passed to ArtifactStore constructor
+        
+    Returns
+    -------
+    tuple
+        (store_instance, artifact_id)
+        
+    Examples
+    --------
+    >>> store, artifact_id = await quick_store(
+    ...     b"Hello world", 
+    ...     mime="text/plain",
+    ...     storage_provider="filesystem"
+    ... )
+    >>> url = await store.presign(artifact_id)
+    """
+    store = ArtifactStore(**store_kwargs)
+    artifact_id = await store.store(data, mime=mime, summary=summary)
+    return store, artifact_id
+
+
+# Module-level configuration helper
+def configure_logging(level: str = "INFO"):
+    """
+    Configure logging for the artifacts package.
+    
+    Parameters
+    ----------
+    level : str
+        Logging level (DEBUG, INFO, WARNING, ERROR)
+    """
+    import logging
+    
+    logger = logging.getLogger("chuk_artifacts")
+    logger.setLevel(getattr(logging, level.upper()))
+    
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)

chuk_artifacts/admin.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/admin.py
+"""
+Administrative and debugging operations
+"""
+
+from __future__ import annotations
+
+import uuid, logging
+from datetime import datetime
+from typing import Any, Dict
+
+from .base import BaseOperations
+
+logger = logging.getLogger(__name__)
+
+
+class AdminOperations(BaseOperations):
+    """FIXED: Handles administrative and debugging operations."""
+
+    async def validate_configuration(self) -> Dict[str, Any]:
+        """Validate store configuration and connectivity."""
+        results = {"timestamp": datetime.utcnow().isoformat() + "Z"}
+        
+        # Test session provider
+        try:
+            session_ctx_mgr = self.session_factory()
+            async with session_ctx_mgr as session:
+                # Test basic operations
+                test_key = f"test_{uuid.uuid4().hex}"
+                await session.setex(test_key, 10, "test_value")
+                value = await session.get(test_key)
+                
+                if value == "test_value":
+                    results["session"] = {
+                        "status": "ok", 
+                        "provider": self.session_provider_name
+                    }
+                else:
+                    results["session"] = {
+                        "status": "error", 
+                        "message": "Session store test failed",
+                        "provider": self.session_provider_name
+                    }
+        except Exception as e:
+            results["session"] = {
+                "status": "error", 
+                "message": str(e),
+                "provider": self.session_provider_name
+            }
+        
+        # Test storage provider
+        try:
+            storage_ctx_mgr = self.s3_factory()
+            async with storage_ctx_mgr as s3:
+                await s3.head_bucket(Bucket=self.bucket)
+            results["storage"] = {
+                "status": "ok", 
+                "bucket": self.bucket, 
+                "provider": self.storage_provider_name
+            }
+        except Exception as e:
+            results["storage"] = {
+                "status": "error", 
+                "message": str(e), 
+                "provider": self.storage_provider_name
+            }
+        
+        return results
+
+    async def get_stats(self) -> Dict[str, Any]:
+        """Get storage statistics."""
+        return {
+            "storage_provider": self.storage_provider_name,
+            "session_provider": self.session_provider_name,
+            "bucket": self.bucket,
+            "max_retries": self.max_retries,
+            "closed": self._artifact_store._closed,  # FIXED: Updated reference
+        }

chuk_artifacts/base.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/base.py
+"""
+base class for operation modules
+"""
+
+from __future__ import annotations
+import json, logging
+from typing import Dict, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import ArtifactStore
+
+from .exceptions import ArtifactNotFoundError, ArtifactCorruptedError, SessionError, ArtifactStoreError
+
+logger = logging.getLogger(__name__)
+
+
+class BaseOperations:
+    """Fixed base class for all operation modules."""
+    
+    def __init__(self, store: 'ArtifactStore'):
+        # FIXED: Renamed from self.store to self._artifact_store to avoid method name conflicts
+        self._artifact_store = store
+    
+    @property
+    def bucket(self) -> str:
+        return self._artifact_store.bucket
+    
+    @property
+    def s3_factory(self):
+        return self._artifact_store._s3_factory
+    
+    @property
+    def session_factory(self):
+        return self._artifact_store._session_factory
+    
+    @property
+    def storage_provider_name(self) -> str:
+        return self._artifact_store._storage_provider_name
+    
+    @property
+    def session_provider_name(self) -> str:
+        return self._artifact_store._session_provider_name
+    
+    @property
+    def max_retries(self) -> int:
+        return self._artifact_store.max_retries
+    
+    def _check_closed(self):
+        """Check if store is closed and raise error if so."""
+        if self._artifact_store._closed:
+            raise ArtifactStoreError("Store has been closed")
+    
+    async def _get_record(self, artifact_id: str) -> Dict[str, Any]:
+        """
+        Retrieve artifact metadata from session provider.
+        
+        This is a shared helper used by multiple operation modules.
+        """
+        try:
+            session_ctx_mgr = self.session_factory()
+            async with session_ctx_mgr as session:
+                raw = await session.get(artifact_id)
+        except Exception as e:
+            raise SessionError(f"Session provider error retrieving {artifact_id}: {e}") from e
+        
+        if raw is None:
+            raise ArtifactNotFoundError(f"Artifact {artifact_id} not found or expired")
+        
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            logger.error(f"Corrupted metadata for artifact {artifact_id}: {e}")
+            raise ArtifactCorruptedError(f"Corrupted metadata for artifact {artifact_id}") from e

chuk_artifacts/batch.py

@@ -0,0 +1,115 @@
+# ===========================================================================
+# chuk_artifacts/batch.py - Batch operations
+# ===========================================================================
+"""
+Batch operations for multiple artifacts.
+"""
+
+from __future__ import annotations
+
+import uuid, hashlib, json, logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from .base import BaseOperations
+from .exceptions import ArtifactStoreError
+
+logger = logging.getLogger(__name__)
+
+_ANON_PREFIX = "anon"
+_DEFAULT_TTL = 900
+
+
+class BatchOperations(BaseOperations):
+    """Handles batch operations for multiple artifacts."""
+
+    async def store_batch(
+        self,
+        items: List[Dict[str, Any]],
+        session_id: str | None = None,
+        ttl: int = _DEFAULT_TTL,
+    ) -> List[str]:
+        """Store multiple artifacts in a batch operation."""
+        self._check_closed()
+        
+        artifact_ids = []
+        failed_items = []
+        
+        for i, item in enumerate(items):
+            try:
+                artifact_id = uuid.uuid4().hex
+                scope = session_id or f"{_ANON_PREFIX}_{artifact_id}"
+                key = f"sess/{scope}/{artifact_id}"
+                
+                # Store in object storage
+                await self._store_with_retry(
+                    item["data"], key, item["mime"], 
+                    item.get("filename"), scope
+                )
+                
+                # Prepare metadata record
+                record = {
+                    "scope": scope,
+                    "key": key,
+                    "mime": item["mime"],
+                    "summary": item["summary"],
+                    "meta": item.get("meta", {}),
+                    "filename": item.get("filename"),
+                    "bytes": len(item["data"]),
+                    "sha256": hashlib.sha256(item["data"]).hexdigest(),
+                    "stored_at": datetime.utcnow().isoformat(timespec="seconds") + "Z",
+                    "ttl": ttl,
+                    "storage_provider": self.storage_provider_name,
+                    "session_provider": self.session_provider_name,
+                }
+                
+                # Store metadata via session provider
+                session_ctx_mgr = self.session_factory()
+                async with session_ctx_mgr as session:
+                    await session.setex(artifact_id, ttl, json.dumps(record))
+                
+                artifact_ids.append(artifact_id)
+                
+            except Exception as e:
+                logger.error(f"Batch item {i} failed: {e}")
+                failed_items.append(i)
+                artifact_ids.append(None)  # Placeholder
+        
+        if failed_items:
+            logger.warning(f"Batch operation completed with {len(failed_items)} failures")
+        
+        return artifact_ids
+
+    async def _store_with_retry(self, data: bytes, key: str, mime: str, filename: str, scope: str):
+        """Store data with retry logic (copied from core for batch operations)."""
+        import asyncio
+        
+        last_exception = None
+        
+        for attempt in range(self.max_retries):
+            try:
+                storage_ctx_mgr = self.s3_factory()
+                async with storage_ctx_mgr as s3:
+                    await s3.put_object(
+                        Bucket=self.bucket,
+                        Key=key,
+                        Body=data,
+                        ContentType=mime,
+                        Metadata={"filename": filename or "", "scope": scope},
+                    )
+                return  # Success
+                
+            except Exception as e:
+                last_exception = e
+                if attempt < self.max_retries - 1:
+                    wait_time = 2 ** attempt  # Exponential backoff
+                    logger.warning(
+                        f"Batch storage attempt {attempt + 1} failed, retrying in {wait_time}s",
+                        extra={"error": str(e), "attempt": attempt + 1}
+                    )
+                    await asyncio.sleep(wait_time)
+                else:
+                    logger.error(f"All {self.max_retries} batch storage attempts failed")
+        
+        raise last_exception
+