chuk-artifacts 0.1.0__py3-none-any.whl

chuk_artifacts/metadata.py

@@ -0,0 +1,286 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/metadata.py
+"""
+Metadata operations: exists, metadata retrieval, and deletion.
+"""
+
+from __future__ import annotations
+
+import logging, json
+from datetime import datetime
+from typing import Any, Dict, List
+
+from .base import BaseOperations
+from .exceptions import (
+    ArtifactStoreError, ArtifactNotFoundError, ArtifactExpiredError, 
+    ProviderError
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MetadataOperations(BaseOperations):
+    """Handles metadata-related operations."""
+
+    async def metadata(self, artifact_id: str) -> Dict[str, Any]:
+        """
+        Get artifact metadata.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            The artifact identifier
+            
+        Returns
+        -------
+        dict
+            Artifact metadata
+            
+        Raises
+        ------
+        ArtifactNotFoundError
+            If artifact doesn't exist or has expired
+        """
+        return await self._get_record(artifact_id)
+
+    async def exists(self, artifact_id: str) -> bool:
+        """
+        Check if artifact exists and hasn't expired.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            The artifact identifier
+            
+        Returns
+        -------
+        bool
+            True if artifact exists, False otherwise
+        """
+        try:
+            await self._get_record(artifact_id)
+            return True
+        except (ArtifactNotFoundError, ArtifactExpiredError):
+            return False
+
+    async def delete(self, artifact_id: str) -> bool:
+        """
+        Delete artifact and its metadata.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            The artifact identifier
+            
+        Returns
+        -------
+        bool
+            True if deleted, False if not found
+            
+        Raises
+        ------
+        ProviderError
+            If deletion fails
+        """
+        self._check_closed()
+        
+        try:
+            record = await self._get_record(artifact_id)
+            
+            # Delete from object storage
+            storage_ctx_mgr = self.s3_factory()
+            async with storage_ctx_mgr as s3:
+                await s3.delete_object(Bucket=self.bucket, Key=record["key"])
+            
+            # Delete metadata from session store
+            session_ctx_mgr = self.session_factory()
+            async with session_ctx_mgr as session:
+                if hasattr(session, 'delete'):
+                    await session.delete(artifact_id)
+                else:
+                    logger.warning(
+                        "Session provider doesn't support delete operation",
+                        extra={"artifact_id": artifact_id, "provider": self.session_provider_name}
+                    )
+            
+            logger.info("Artifact deleted", extra={"artifact_id": artifact_id})
+            return True
+            
+        except (ArtifactNotFoundError, ArtifactExpiredError):
+            logger.warning("Attempted to delete non-existent artifact", extra={"artifact_id": artifact_id})
+            return False
+        except Exception as e:
+            logger.error(
+                "Artifact deletion failed",
+                extra={"artifact_id": artifact_id, "error": str(e)}
+            )
+            raise ProviderError(f"Deletion failed: {e}") from e
+
+    async def update_metadata(
+        self, 
+        artifact_id: str, 
+        *,
+        summary: str = None,
+        meta: Dict[str, Any] = None,
+        filename: str = None,
+        ttl: int = None
+    ) -> Dict[str, Any]:
+        """
+        Update artifact metadata without changing the stored data.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            The artifact identifier
+        summary : str, optional
+            New summary description
+        meta : dict, optional
+            New or additional metadata fields
+        filename : str, optional
+            New filename
+        ttl : int, optional
+            New TTL for metadata
+            
+        Returns
+        -------
+        dict
+            Updated metadata record
+            
+        Raises
+        ------
+        ArtifactNotFoundError
+            If artifact doesn't exist
+        ProviderError
+            If update fails
+        """
+        self._check_closed()
+        
+        try:
+            # Get existing record
+            record = await self._get_record(artifact_id)
+            
+            # Update fields if provided
+            if summary is not None:
+                record["summary"] = summary
+            if meta is not None:
+                # Merge with existing meta, allowing overwrites
+                existing_meta = record.get("meta", {})
+                existing_meta.update(meta)
+                record["meta"] = existing_meta
+            if filename is not None:
+                record["filename"] = filename
+            if ttl is not None:
+                record["ttl"] = ttl
+            
+            # Update stored metadata
+            record["updated_at"] = datetime.utcnow().isoformat(timespec="seconds") + "Z"
+            
+            session_ctx_mgr = self.session_factory()
+            async with session_ctx_mgr as session:
+                final_ttl = ttl or record.get("ttl", 900)  # Use provided TTL or existing/default
+                await session.setex(artifact_id, final_ttl, json.dumps(record))
+            
+            logger.info(
+                "Artifact metadata updated", 
+                extra={"artifact_id": artifact_id, "updated_fields": list([
+                    k for k, v in [
+                        ("summary", summary), ("meta", meta), 
+                        ("filename", filename), ("ttl", ttl)
+                    ] if v is not None
+                ])}
+            )
+            
+            return record
+            
+        except (ArtifactNotFoundError, ArtifactExpiredError):
+            raise
+        except Exception as e:
+            logger.error(
+                "Metadata update failed",
+                extra={"artifact_id": artifact_id, "error": str(e)}
+            )
+            raise ProviderError(f"Metadata update failed: {e}") from e
+
+    async def extend_ttl(self, artifact_id: str, additional_seconds: int) -> Dict[str, Any]:
+        """
+        Extend the TTL of an artifact's metadata.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            The artifact identifier
+        additional_seconds : int
+            Additional seconds to add to the current TTL
+            
+        Returns
+        -------
+        dict
+            Updated metadata record
+            
+        Raises
+        ------
+        ArtifactNotFoundError
+            If artifact doesn't exist
+        ProviderError
+            If TTL extension fails
+        """
+        self._check_closed()
+        
+        try:
+            # Get current record to find existing TTL
+            record = await self._get_record(artifact_id)
+            current_ttl = record.get("ttl", 900)
+            new_ttl = current_ttl + additional_seconds
+            
+            # Update with extended TTL
+            return await self.update_metadata(artifact_id, ttl=new_ttl)
+            
+        except (ArtifactNotFoundError, ArtifactExpiredError):
+            raise
+        except Exception as e:
+            logger.error(
+                "TTL extension failed",
+                extra={
+                    "artifact_id": artifact_id, 
+                    "additional_seconds": additional_seconds,
+                    "error": str(e)
+                }
+            )
+            raise ProviderError(f"TTL extension failed: {e}") from e
+
+    async def list_by_session(self, session_id: str, limit: int = 100) -> List[Dict[str, Any]]:
+        """
+        List artifacts for a specific session.
+        
+        Note: This is a basic implementation that would need to be enhanced
+        with proper indexing for production use. Currently, this method
+        cannot be efficiently implemented with the session provider abstraction
+        since we don't have a way to query by session_id patterns.
+        
+        Parameters
+        ----------
+        session_id : str
+            Session identifier to search for
+        limit : int, optional
+            Maximum number of artifacts to return
+            
+        Returns
+        -------
+        list
+            List of metadata records for artifacts in the session
+            
+        Raises
+        ------
+        NotImplementedError
+            This method requires additional indexing infrastructure
+        """
+        # This would require either:
+        # 1. A separate index of session_id -> artifact_ids 
+        # 2. Storage provider support for prefix queries
+        # 3. Enhanced session provider with query capabilities
+        
+        raise NotImplementedError(
+            "list_by_session requires additional indexing infrastructure. "
+            "Consider implementing session-based indexing or using storage "
+            "provider list operations if available."
+        )

chuk_artifacts/models.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/models.py
+from typing import Any, Dict
+from pydantic import BaseModel, Field
+
+
+class ArtifactEnvelope(BaseModel):
+    """
+    A tiny, model-friendly wrapper describing a stored artefact.
+
+    The *bytes*, *mime_type*, etc. let the UI reason about the file
+    without ever uploading the raw payload into the chat context.
+    """
+
+    success: bool = True
+    artifact_id: str                        # opaque handle for look-ups
+    mime_type: str                          # e.g. "image/png", "text/csv"
+    bytes: int                              # size on disk
+    summary: str                            # human-readable description / alt
+    meta: Dict[str, Any] = Field(default_factory=dict)
+
+    class Config:
+        extra = "allow"                     # future-proof: lets tools add keys

chuk_artifacts/presigned.py

@@ -0,0 +1,267 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/presigned.py
+"""
+Presigned URL operations: download URLs, upload URLs, and upload registration.
+"""
+
+from __future__ import annotations
+
+import uuid, time, logging, json
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from .base import BaseOperations
+from .exceptions import (
+    ArtifactStoreError, ArtifactNotFoundError, ArtifactExpiredError, 
+    ProviderError, SessionError
+)
+
+logger = logging.getLogger(__name__)
+
+_ANON_PREFIX = "anon"
+_DEFAULT_TTL = 900
+_DEFAULT_PRESIGN_EXPIRES = 3600
+
+
+class PresignedURLOperations(BaseOperations):
+    """Handles all presigned URL operations."""
+
+    async def presign(self, artifact_id: str, expires: int = _DEFAULT_PRESIGN_EXPIRES) -> str:
+        """Generate a presigned URL for artifact download."""
+        self._check_closed()
+        
+        start_time = time.time()
+        
+        try:
+            record = await self._get_record(artifact_id)
+            
+            storage_ctx_mgr = self.s3_factory()
+            async with storage_ctx_mgr as s3:
+                url = await s3.generate_presigned_url(
+                    "get_object",
+                    Params={"Bucket": self.bucket, "Key": record["key"]},
+                    ExpiresIn=expires,
+                )
+                
+                duration_ms = int((time.time() - start_time) * 1000)
+                logger.info(
+                    "Presigned URL generated",
+                    extra={
+                        "artifact_id": artifact_id,
+                        "expires_in": expires,
+                        "duration_ms": duration_ms,
+                    }
+                )
+                
+                return url
+                
+        except (ArtifactNotFoundError, ArtifactExpiredError):
+            raise
+        except Exception as e:
+            duration_ms = int((time.time() - start_time) * 1000)
+            logger.error(
+                "Presigned URL generation failed",
+                extra={
+                    "artifact_id": artifact_id,
+                    "error": str(e),
+                    "duration_ms": duration_ms,
+                }
+            )
+            
+            if "oauth" in str(e).lower() or "credential" in str(e).lower():
+                raise NotImplementedError(
+                    "This provider cannot generate presigned URLs with the "
+                    "current credential type (e.g. OAuth). Use HMAC creds instead."
+                ) from e
+            else:
+                raise ProviderError(f"Presigned URL generation failed: {e}") from e
+
+    async def presign_short(self, artifact_id: str) -> str:
+        """Generate a short-lived presigned URL (15 minutes)."""
+        return await self.presign(artifact_id, expires=900)
+    
+    async def presign_medium(self, artifact_id: str) -> str:
+        """Generate a medium-lived presigned URL (1 hour)."""
+        return await self.presign(artifact_id, expires=3600)
+    
+    async def presign_long(self, artifact_id: str) -> str:
+        """Generate a long-lived presigned URL (24 hours)."""
+        return await self.presign(artifact_id, expires=86400)
+
+    async def presign_upload(
+        self, 
+        session_id: str | None = None,
+        filename: str | None = None,
+        mime_type: str = "application/octet-stream",
+        expires: int = _DEFAULT_PRESIGN_EXPIRES
+    ) -> tuple[str, str]:
+        """Generate a presigned URL for uploading a new artifact."""
+        self._check_closed()
+        
+        start_time = time.time()
+        
+        # Generate artifact ID and key path
+        artifact_id = uuid.uuid4().hex
+        scope = session_id or f"{_ANON_PREFIX}_{artifact_id}"
+        key = f"sess/{scope}/{artifact_id}"
+        
+        try:
+            storage_ctx_mgr = self.s3_factory()
+            async with storage_ctx_mgr as s3:
+                url = await s3.generate_presigned_url(
+                    "put_object",
+                    Params={
+                        "Bucket": self.bucket, 
+                        "Key": key,
+                        "ContentType": mime_type
+                    },
+                    ExpiresIn=expires,
+                )
+                
+                duration_ms = int((time.time() - start_time) * 1000)
+                logger.info(
+                    "Upload presigned URL generated",
+                    extra={
+                        "artifact_id": artifact_id,
+                        "key": key,
+                        "mime_type": mime_type,
+                        "expires_in": expires,
+                        "duration_ms": duration_ms,
+                    }
+                )
+                
+                return url, artifact_id
+                
+        except Exception as e:
+            duration_ms = int((time.time() - start_time) * 1000)
+            logger.error(
+                "Upload presigned URL generation failed",
+                extra={
+                    "artifact_id": artifact_id,
+                    "error": str(e),
+                    "duration_ms": duration_ms,
+                }
+            )
+            
+            if "oauth" in str(e).lower() or "credential" in str(e).lower():
+                raise NotImplementedError(
+                    "This provider cannot generate presigned URLs with the "
+                    "current credential type (e.g. OAuth). Use HMAC creds instead."
+                ) from e
+            else:
+                raise ProviderError(f"Upload presigned URL generation failed: {e}") from e
+
+    async def register_uploaded_artifact(
+        self,
+        artifact_id: str,
+        *,
+        mime: str,
+        summary: str,
+        meta: Dict[str, Any] | None = None,
+        filename: str | None = None,
+        session_id: str | None = None,
+        ttl: int = _DEFAULT_TTL,
+    ) -> bool:
+        """Register metadata for an artifact uploaded via presigned URL."""
+        self._check_closed()
+        
+        start_time = time.time()
+        
+        # Reconstruct the key path
+        scope = session_id or f"{_ANON_PREFIX}_{artifact_id}"
+        key = f"sess/{scope}/{artifact_id}"
+        
+        try:
+            # Verify the object exists and get its size
+            storage_ctx_mgr = self.s3_factory()
+            async with storage_ctx_mgr as s3:
+                try:
+                    response = await s3.head_object(Bucket=self.bucket, Key=key)
+                    file_size = response.get('ContentLength', 0)
+                except Exception:
+                    logger.warning(f"Artifact {artifact_id} not found in storage")
+                    return False
+            
+            # Build metadata record
+            record = {
+                "scope": scope,
+                "key": key,
+                "mime": mime,
+                "summary": summary,
+                "meta": meta or {},
+                "filename": filename,
+                "bytes": file_size,
+                "sha256": None,  # We don't have the hash since we didn't upload it directly
+                "stored_at": datetime.utcnow().isoformat(timespec="seconds") + "Z",
+                "ttl": ttl,
+                "storage_provider": self.storage_provider_name,
+                "session_provider": self.session_provider_name,
+                "uploaded_via_presigned": True,  # Flag to indicate upload method
+            }
+
+            # Cache metadata using session provider
+            session_ctx_mgr = self.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 metadata registered after presigned upload",
+                extra={
+                    "artifact_id": artifact_id,
+                    "bytes": file_size,
+                    "mime": mime,
+                    "duration_ms": duration_ms,
+                }
+            )
+
+            return True
+
+        except Exception as e:
+            duration_ms = int((time.time() - start_time) * 1000)
+            logger.error(
+                "Artifact metadata registration failed",
+                extra={
+                    "artifact_id": artifact_id,
+                    "error": str(e),
+                    "duration_ms": duration_ms,
+                }
+            )
+            
+            if "session" in str(e).lower() or "redis" in str(e).lower():
+                raise SessionError(f"Metadata registration failed: {e}") from e
+            else:
+                raise ProviderError(f"Metadata registration failed: {e}") from e
+
+    async def presign_upload_and_register(
+        self,
+        *,
+        mime: str,
+        summary: str,
+        meta: Dict[str, Any] | None = None,
+        filename: str | None = None,
+        session_id: str | None = None,
+        ttl: int = _DEFAULT_TTL,
+        expires: int = _DEFAULT_PRESIGN_EXPIRES
+    ) -> tuple[str, str]:
+        """Convenience method combining presign_upload and pre-register metadata."""
+        # Generate presigned URL
+        upload_url, artifact_id = await self.presign_upload(
+            session_id=session_id,
+            filename=filename,
+            mime_type=mime,
+            expires=expires
+        )
+        
+        # Pre-register metadata (with unknown file size)
+        await self.register_uploaded_artifact(
+            artifact_id,
+            mime=mime,
+            summary=summary,
+            meta=meta,
+            filename=filename,
+            session_id=session_id,
+            ttl=ttl
+        )
+        
+        return upload_url, artifact_id

chuk_artifacts/provider_factory.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/provider_factory.py
+"""
+Resolve the storage back-end requested via **ARTIFACT_PROVIDER**.
+
+Built-in providers
+──────────────────
+• **memory** (default) - in-process, non-persistent store (unit tests, demos)
+• **fs**, **filesystem** - local filesystem rooted at `$ARTIFACT_FS_ROOT`
+• **s3** - plain AWS or any S3-compatible endpoint
+• **ibm_cos** - IBM COS, HMAC credentials (Signature V2)
+• **ibm_cos_iam** - IBM COS, IAM API-key / OAuth signature
+
+Any other value is resolved dynamically as
+`chuk_artifacts.providers.<name>.factory()`.
+"""
+
+from __future__ import annotations
+
+import os
+from importlib import import_module
+from typing import Callable, AsyncContextManager
+
+__all__ = ["factory_for_env"]
+
+
+# ──────────────────────────────────────────────────────────────────
+# Public factory selector
+# ──────────────────────────────────────────────────────────────────
+
+def factory_for_env() -> Callable[[], AsyncContextManager]:
+    """Return a provider-specific factory based on `$ARTIFACT_PROVIDER`."""
+
+    provider = os.getenv("ARTIFACT_PROVIDER", "memory").lower().strip()
+
+    # Fast paths for the built-ins ------------------------------------------------
+    # Memory first as it's the default
+    if provider in ("memory", "mem", "inmemory"):
+        from .providers import memory
+        return memory.factory()
+
+    if provider in ("fs", "filesystem"):
+        from .providers import filesystem
+        return filesystem.factory()
+
+    if provider == "s3":
+        from .providers import s3
+        return s3.factory()
+
+    if provider == "ibm_cos":
+        from .providers import ibm_cos
+        return ibm_cos.factory()  # returns the zero-arg factory callable
+
+    if provider == "ibm_cos_iam":
+        from .providers import ibm_cos_iam
+        return ibm_cos_iam.factory  # note: function itself is already the factory
+
+    # ---------------------------------------------------------------------------
+    # Fallback: dynamic lookup – allows user-supplied provider implementations.
+    # ---------------------------------------------------------------------------
+    try:
+        mod = import_module(f"chuk_artifacts.providers.{provider}")
+    except ModuleNotFoundError as exc:
+        # Provide helpful error message with available providers
+        available = ["memory", "filesystem", "s3", "ibm_cos", "ibm_cos_iam"]
+        raise ValueError(
+            f"Unknown storage provider '{provider}'. "
+            f"Available providers: {', '.join(available)}"
+        ) from exc
+    
+    if not hasattr(mod, "factory"):
+        raise AttributeError(
+            f"Provider '{provider}' lacks a factory() function"
+        )
+    # For dynamic providers, call factory() to get the actual factory function
+    factory_func = mod.factory
+    if callable(factory_func):
+        # If it's a function that returns a factory, call it
+        try:
+            return factory_func()
+        except TypeError:
+            # If it's already the factory function, return it directly
+            return factory_func
+    return factory_func

chuk_artifacts/providers/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/providers/__init__.py
+"""
+Convenience re-exports so caller code can do:
+
+    from chuk_artifacts.providers import s3, ibm_cos, memory, filesystem
+"""
+from . import s3, ibm_cos, memory, filesystem, ibm_cos_iam
+
+__all__ = ["s3", "ibm_cos", "memory", "filesystem", "ibm_cos_iam"]