chuk-artifacts 0.1.0__py3-none-any.whl

chuk_artifacts/config.py

@@ -0,0 +1,338 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/config.py
+"""
+Configuration helpers for ArtifactStore.
+
+Provides convenient functions to set up common configurations
+without needing to write .env files or remember all the variable names.
+"""
+
+import os
+from typing import Dict, Optional
+from .store import ArtifactStore
+
+
+def configure_memory() -> Dict[str, str]:
+    """
+    Configure for in-memory storage (development/testing).
+    
+    Returns
+    -------
+    dict
+        Environment variables that were set
+    """
+    env_vars = {
+        "ARTIFACT_PROVIDER": "memory",
+        "SESSION_PROVIDER": "memory",
+        "ARTIFACT_BUCKET": "mcp-artifacts"
+    }
+    
+    for key, value in env_vars.items():
+        os.environ[key] = value
+    
+    return env_vars
+
+
+def configure_filesystem(root: str = "./artifacts") -> Dict[str, str]:
+    """
+    Configure for local filesystem storage.
+    
+    Parameters
+    ----------
+    root : str
+        Root directory for artifact storage
+        
+    Returns
+    -------
+    dict
+        Environment variables that were set
+    """
+    env_vars = {
+        "ARTIFACT_PROVIDER": "filesystem", 
+        "SESSION_PROVIDER": "memory",
+        "ARTIFACT_FS_ROOT": root,
+        "ARTIFACT_BUCKET": "mcp-artifacts"
+    }
+    
+    for key, value in env_vars.items():
+        os.environ[key] = value
+    
+    return env_vars
+
+
+def configure_s3(
+    *,
+    access_key: str,
+    secret_key: str, 
+    bucket: str,
+    endpoint_url: Optional[str] = None,
+    region: str = "us-east-1",
+    session_provider: str = "memory"
+) -> Dict[str, str]:
+    """
+    Configure for S3-compatible storage.
+    
+    Parameters
+    ----------
+    access_key : str
+        AWS access key ID
+    secret_key : str
+        AWS secret access key
+    bucket : str
+        S3 bucket name
+    endpoint_url : str, optional
+        Custom S3 endpoint (for MinIO, DigitalOcean, etc.)
+    region : str
+        AWS region
+    session_provider : str
+        Session provider (memory or redis)
+        
+    Returns
+    -------
+    dict
+        Environment variables that were set
+    """
+    env_vars = {
+        "ARTIFACT_PROVIDER": "s3",
+        "SESSION_PROVIDER": session_provider,
+        "AWS_ACCESS_KEY_ID": access_key,
+        "AWS_SECRET_ACCESS_KEY": secret_key,
+        "AWS_REGION": region,
+        "ARTIFACT_BUCKET": bucket
+    }
+    
+    if endpoint_url:
+        env_vars["S3_ENDPOINT_URL"] = endpoint_url
+    
+    for key, value in env_vars.items():
+        os.environ[key] = value
+    
+    return env_vars
+
+
+def configure_redis_session(redis_url: str = "redis://localhost:6379/0") -> Dict[str, str]:
+    """
+    Configure Redis for session storage.
+    
+    Parameters
+    ----------
+    redis_url : str
+        Redis connection URL
+        
+    Returns
+    -------
+    dict
+        Environment variables that were set
+    """
+    env_vars = {
+        "SESSION_PROVIDER": "redis",
+        "SESSION_REDIS_URL": redis_url
+    }
+    
+    for key, value in env_vars.items():
+        os.environ[key] = value
+    
+    return env_vars
+
+
+def configure_ibm_cos(
+    *,
+    access_key: str,
+    secret_key: str,
+    bucket: str,
+    endpoint: str = "https://s3.us-south.cloud-object-storage.appdomain.cloud",
+    region: str = "us-south",
+    session_provider: str = "memory"
+) -> Dict[str, str]:
+    """
+    Configure for IBM Cloud Object Storage (HMAC).
+    
+    Parameters
+    ----------
+    access_key : str
+        HMAC access key
+    secret_key : str
+        HMAC secret key
+    bucket : str
+        COS bucket name
+    endpoint : str
+        IBM COS endpoint URL
+    region : str
+        IBM COS region
+    session_provider : str
+        Session provider (memory or redis)
+        
+    Returns
+    -------
+    dict
+        Environment variables that were set
+    """
+    env_vars = {
+        "ARTIFACT_PROVIDER": "ibm_cos",
+        "SESSION_PROVIDER": session_provider,
+        "AWS_ACCESS_KEY_ID": access_key,
+        "AWS_SECRET_ACCESS_KEY": secret_key,
+        "AWS_REGION": region,
+        "IBM_COS_ENDPOINT": endpoint,
+        "ARTIFACT_BUCKET": bucket
+    }
+    
+    for key, value in env_vars.items():
+        os.environ[key] = value
+    
+    return env_vars
+
+
+def configure_ibm_cos_iam(
+    *,
+    api_key: str,
+    instance_crn: str,
+    bucket: str,
+    endpoint: str = "https://s3.us-south.cloud-object-storage.appdomain.cloud",
+    session_provider: str = "memory"
+) -> Dict[str, str]:
+    """
+    Configure for IBM Cloud Object Storage (IAM).
+    
+    Parameters
+    ----------
+    api_key : str
+        IBM Cloud API key
+    instance_crn : str
+        COS instance CRN
+    bucket : str
+        COS bucket name
+    endpoint : str
+        IBM COS endpoint URL
+    session_provider : str
+        Session provider (memory or redis)
+        
+    Returns
+    -------
+    dict
+        Environment variables that were set
+    """
+    env_vars = {
+        "ARTIFACT_PROVIDER": "ibm_cos_iam",
+        "SESSION_PROVIDER": session_provider,
+        "IBM_COS_APIKEY": api_key,
+        "IBM_COS_INSTANCE_CRN": instance_crn,
+        "IBM_COS_ENDPOINT": endpoint,
+        "ARTIFACT_BUCKET": bucket
+    }
+    
+    for key, value in env_vars.items():
+        os.environ[key] = value
+    
+    return env_vars
+
+
+def create_store() -> ArtifactStore:
+    """
+    Create a new ArtifactStore instance with current environment configuration.
+    
+    Returns
+    -------
+    ArtifactStore
+        Configured store instance
+    """
+    return ArtifactStore()
+
+
+# Convenience functions for common setups
+def development_setup() -> ArtifactStore:
+    """Set up for local development (memory storage)."""
+    configure_memory()
+    return create_store()
+
+
+def testing_setup(artifacts_dir: str = "./test-artifacts") -> ArtifactStore:
+    """Set up for testing (filesystem storage)."""
+    configure_filesystem(artifacts_dir)
+    return create_store()
+
+
+def production_setup(
+    *,
+    storage_type: str,
+    **kwargs
+) -> ArtifactStore:
+    """
+    Set up for production use.
+    
+    Parameters
+    ----------
+    storage_type : str
+        Storage type: 's3', 'ibm_cos', 'ibm_cos_iam'
+    **kwargs
+        Configuration parameters for the chosen storage type
+        
+    Returns
+    -------
+    ArtifactStore
+        Configured store instance
+    """
+    if storage_type == "s3":
+        configure_s3(**kwargs)
+    elif storage_type == "ibm_cos":
+        configure_ibm_cos(**kwargs)
+    elif storage_type == "ibm_cos_iam":
+        configure_ibm_cos_iam(**kwargs)
+    else:
+        raise ValueError(f"Unknown storage type: {storage_type}")
+    
+    return create_store()
+
+
+# Usage examples in docstring
+__doc__ += """
+
+Usage Examples
+--------------
+
+**Quick development setup:**
+```python
+from chuk_artifacts.config import development_setup
+
+store = development_setup()  # Uses memory, no persistence
+```
+
+**Testing with filesystem:**
+```python
+from chuk_artifacts.config import testing_setup
+
+store = testing_setup("./test-data")  # Persists to filesystem
+```
+
+**Production with S3:**
+```python
+from chuk_artifacts.config import production_setup
+
+store = production_setup(
+    storage_type="s3",
+    access_key="AKIA...",
+    secret_key="...", 
+    bucket="prod-artifacts",
+    session_provider="redis"
+)
+```
+
+**Custom configuration:**
+```python
+from chuk_artifacts.config import configure_s3, configure_redis_session, create_store
+
+# Set up S3 storage
+configure_s3(
+    access_key="AKIA...",
+    secret_key="...",
+    bucket="my-bucket",
+    endpoint_url="https://nyc3.digitaloceanspaces.com"  # DigitalOcean Spaces
+)
+
+# Set up Redis sessions
+configure_redis_session("redis://localhost:6379/1")
+
+# Create store with this configuration
+store = create_store()
+```
+"""

chuk_artifacts/core.py

@@ -0,0 +1,215 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/core.py
+"""
+core storage operations.
+"""
+
+from __future__ import annotations
+
+import uuid, hashlib, time, asyncio, logging, json
+from datetime import datetime
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import ArtifactStore
+
+from .exceptions import (
+    ArtifactStoreError, ArtifactNotFoundError, ArtifactExpiredError, 
+    ArtifactCorruptedError, ProviderError, SessionError
+)
+
+logger = logging.getLogger(__name__)
+
+_ANON_PREFIX = "anon"
+_DEFAULT_TTL = 900
+
+
+class CoreStorageOperations:
+    """core storage operations without BaseOperations inheritance."""
+
+    def __init__(self, artifact_store: 'ArtifactStore'):
+        self.artifact_store = artifact_store  # Renamed to avoid conflicts
+        logger.info(f"CoreStorageOperations initialized with store: {type(artifact_store)}")
+
+    async def store(
+        self,
+        data: bytes,
+        *,
+        mime: str,
+        summary: str,
+        meta: Dict[str, Any] | None = None,
+        filename: str | None = None,
+        session_id: str | None = None,
+        ttl: int = _DEFAULT_TTL,
+    ) -> str:
+        """Store artifact data with metadata."""
+        if self.artifact_store._closed:
+            raise ArtifactStoreError("Store has been closed")
+        
+        start_time = time.time()
+        artifact_id = uuid.uuid4().hex
+        
+        scope = session_id or f"{_ANON_PREFIX}_{artifact_id}"
+        key = f"sess/{scope}/{artifact_id}"
+
+        try:
+            # Store in object storage with retries
+            await self._store_with_retry(data, key, mime, filename, scope)
+
+            # Build metadata record
+            record = {
+                "scope": scope,
+                "key": key,
+                "mime": mime,
+                "summary": summary,
+                "meta": meta or {},
+                "filename": filename,
+                "bytes": len(data),
+                "sha256": hashlib.sha256(data).hexdigest(),
+                "stored_at": datetime.utcnow().isoformat(timespec="seconds") + "Z",
+                "ttl": ttl,
+                "storage_provider": self.artifact_store._storage_provider_name,
+                "session_provider": self.artifact_store._session_provider_name,
+            }
+
+            # Cache metadata using session provider
+            session_ctx_mgr = self.artifact_store._session_factory()
+            async with session_ctx_mgr as session:
+                await session.setex(artifact_id, ttl, json.dumps(record))
+
+            duration_ms = int((time.time() - start_time) * 1000)
+            logger.info(
+                "Artifact stored successfully",
+                extra={
+                    "artifact_id": artifact_id,
+                    "bytes": len(data),
+                    "mime": mime,
+                    "duration_ms": duration_ms,
+                    "storage_provider": self.artifact_store._storage_provider_name,
+                }
+            )
+
+            return artifact_id
+
+        except Exception as e:
+            duration_ms = int((time.time() - start_time) * 1000)
+            logger.error(
+                "Artifact storage failed",
+                extra={
+                    "artifact_id": artifact_id,
+                    "error": str(e),
+                    "duration_ms": duration_ms,
+                    "storage_provider": self.artifact_store._storage_provider_name,
+                },
+                exc_info=True
+            )
+            
+            if "session" in str(e).lower() or "redis" in str(e).lower():
+                raise SessionError(f"Metadata caching failed: {e}") from e
+            else:
+                raise ProviderError(f"Storage operation failed: {e}") from e
+
+    async def _store_with_retry(self, data: bytes, key: str, mime: str, filename: str, scope: str):
+        """Store data with retry logic."""
+        last_exception = None
+        
+        for attempt in range(self.artifact_store.max_retries):
+            try:
+                storage_ctx_mgr = self.artifact_store._s3_factory()
+                async with storage_ctx_mgr as s3:
+                    await s3.put_object(
+                        Bucket=self.artifact_store.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.artifact_store.max_retries - 1:
+                    wait_time = 2 ** attempt  # Exponential backoff
+                    logger.warning(
+                        f"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.artifact_store.max_retries} storage attempts failed")
+        
+        raise last_exception
+
+    async def retrieve(self, artifact_id: str) -> bytes:
+        """Retrieve artifact data directly."""
+        if self.artifact_store._closed:
+            raise ArtifactStoreError("Store has been closed")
+        
+        start_time = time.time()
+        
+        try:
+            record = await self._get_record(artifact_id)
+            
+            storage_ctx_mgr = self.artifact_store._s3_factory()
+            async with storage_ctx_mgr as s3:
+                response = await s3.get_object(Bucket=self.artifact_store.bucket, Key=record["key"])
+                
+                # Handle different response formats from different providers
+                if hasattr(response["Body"], "read"):
+                    data = await response["Body"].read()
+                elif isinstance(response["Body"], bytes):
+                    data = response["Body"]
+                else:
+                    data = bytes(response["Body"])
+                
+                # Verify integrity if SHA256 is available
+                if "sha256" in record and record["sha256"]:
+                    computed_hash = hashlib.sha256(data).hexdigest()
+                    if computed_hash != record["sha256"]:
+                        raise ArtifactCorruptedError(
+                            f"SHA256 mismatch: expected {record['sha256']}, got {computed_hash}"
+                        )
+                
+                duration_ms = int((time.time() - start_time) * 1000)
+                logger.info(
+                    "Artifact retrieved successfully",
+                    extra={
+                        "artifact_id": artifact_id,
+                        "bytes": len(data),
+                        "duration_ms": duration_ms,
+                    }
+                )
+                
+                return data
+                
+        except (ArtifactNotFoundError, ArtifactExpiredError, ArtifactCorruptedError):
+            raise
+        except Exception as e:
+            duration_ms = int((time.time() - start_time) * 1000)
+            logger.error(
+                "Artifact retrieval failed",
+                extra={
+                    "artifact_id": artifact_id,
+                    "error": str(e),
+                    "duration_ms": duration_ms,
+                }
+            )
+            raise ProviderError(f"Retrieval failed: {e}") from e
+
+    async def _get_record(self, artifact_id: str) -> Dict[str, Any]:
+        """Retrieve artifact metadata from session provider."""
+        try:
+            session_ctx_mgr = self.artifact_store._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/exceptions.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/exceptions.py
+"""
+Exception classes for artifact store operations.
+"""
+
+from __future__ import annotations
+
+
+class ArtifactStoreError(Exception):
+    """Base exception for artifact store operations."""
+    pass
+
+
+class ArtifactNotFoundError(ArtifactStoreError):
+    """Raised when an artifact cannot be found."""
+    pass
+
+
+class ArtifactExpiredError(ArtifactStoreError):
+    """Raised when an artifact has expired."""
+    pass
+
+
+class ArtifactCorruptedError(ArtifactStoreError):
+    """Raised when artifact metadata is corrupted."""
+    pass
+
+
+class ProviderError(ArtifactStoreError):
+    """Raised when the storage provider encounters an error."""
+    pass
+
+
+class SessionError(ArtifactStoreError):
+    """Raised when the session provider encounters an error."""
+    pass