chuk-artifacts 0.3__py3-none-any.whl → 0.4.1__py3-none-any.whl

chuk_artifacts/__init__.py

@@ -12,6 +12,7 @@ from dotenv import load_dotenv
 
 # Core classes
 from .store import ArtifactStore
+from .models import ArtifactEnvelope
 
 # Exception classes
 from .exceptions import (
@@ -42,6 +43,9 @@ __all__ = [
     # Main class
     "ArtifactStore",
     
+    # Models
+    "ArtifactEnvelope",
+    
     # Exceptions
     "ArtifactStoreError", 
     "ArtifactNotFoundError",
@@ -146,4 +150,4 @@ def configure_logging(level: str = "INFO"):
             "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
         )
         handler.setFormatter(formatter)
-        logger.addHandler(handler)
+        logger.addHandler(handler)

chuk_artifacts/core.py

@@ -19,7 +19,7 @@ from typing import Any, Dict, Optional, TYPE_CHECKING
 if TYPE_CHECKING:
     from .store import ArtifactStore
 
-from .exceptions import ArtifactStoreError, ProviderError, SessionError
+from .exceptions import ArtifactStoreError, ProviderError, SessionError, ArtifactNotFoundError
 
 logger = logging.getLogger(__name__)
 
@@ -102,44 +102,55 @@ class CoreStorageOperations:
                 raise ProviderError(f"Storage failed: {e}") from e
 
     async def update_file(
-            self,
-            artifact_id: str,
-            new_data: bytes,
-            *,
-            mime: Optional[str] = None,
-            summary: Optional[str] = None,
-            meta: Optional[Dict[str, Any]] = None,
-            filename: Optional[str] = None,
-            ttl: Optional[int] = None,
-        ) -> None:
-            """
-            Update the contents of an existing artifact.
+        self,
+        artifact_id: str,
+        new_data: Optional[bytes] = None,
+        *,
+        mime: Optional[str] = None,
+        summary: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+        filename: Optional[str] = None,
+        ttl: Optional[int] = None,
+    ) -> bool:
+        """
+        Update an artifact's content, metadata, filename, summary, or mime type.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            ID of the artifact to update
+        new_data : bytes, optional
+            New data to overwrite the existing artifact
+        mime : str, optional
+            New MIME type
+        summary : str, optional
+            New summary
+        meta : dict, optional
+            Updated metadata
+        filename : str, optional
+            New filename
+        ttl : int, optional
+            New TTL
+            
+        Returns
+        -------
+        bool
+            True if update was successful
+        """
+        if self.artifact_store._closed:
+            raise ArtifactStoreError("Store is closed")
 
-            Parameters
-            ----------
-            artifact_id : str
-                ID of the artifact to update.
-            new_data : bytes
-                New data to overwrite the existing artifact.
-            mime : Optional[str]
-                Optional new MIME type.
-            summary : Optional[str]
-                Optional new summary.
-            meta : Optional[Dict[str, Any]]
-                Optional updated metadata.
-            filename : Optional[str]
-                Optional new filename.
-            ttl : Optional[int]
-                Optional TTL to reset (if provided).
-            """
-            if self.artifact_store._closed:
-                raise ArtifactStoreError("Store is closed")
+        if not any([new_data is not None, meta is not None, filename is not None, 
+                   summary is not None, mime is not None, ttl is not None]):
+            raise ValueError("At least one update parameter must be provided.")
 
-            try:
-                record = await self._get_record(artifact_id)
-                key = record["key"]
-                session_id = record["session_id"]
+        try:
+            record = await self._get_record(artifact_id)
+            key = record["key"]
+            session_id = record["session_id"]
 
+            # Update data if provided
+            if new_data is not None:
                 # Overwrite in object storage
                 await self._store_with_retry(
                     new_data,
@@ -148,31 +159,37 @@ class CoreStorageOperations:
                     filename or record.get("filename"),
                     session_id,
                 )
+                
+                # Update size and hash in metadata
+                record["bytes"] = len(new_data)
+                record["sha256"] = hashlib.sha256(new_data).hexdigest()
 
-                # Update metadata
-                record.update({
-                    "mime": mime or record["mime"],
-                    "summary": summary or record["summary"],
-                    "meta": meta or record["meta"],
-                    "filename": filename or record.get("filename"),
-                    "bytes": len(new_data),
-                    "sha256": hashlib.sha256(new_data).hexdigest(),
-                    "updated_at": datetime.utcnow().isoformat() + "Z",
-                     "ttl": ttl or record["ttl"],
-                })
+            # Update metadata fields
+            if mime is not None:
+                record["mime"] = mime
+            if summary is not None:
+                record["summary"] = summary
+            if filename is not None:
+                record["filename"] = filename
+            if meta is not None:
+                record["meta"] = meta
+            if ttl is not None:
+                record["ttl"] = ttl
 
-                if ttl is not None:
-                    record["ttl"] = ttl
+            # Add update timestamp
+            record["updated_at"] = datetime.utcnow().isoformat() + "Z"
 
-                session_ctx_mgr = self.artifact_store._session_factory()
-                async with session_ctx_mgr as session:
-                    await session.setex(artifact_id, record["ttl"], json.dumps(record))
+            # Store updated metadata
+            session_ctx_mgr = self.artifact_store._session_factory()
+            async with session_ctx_mgr as session:
+                await session.setex(artifact_id, record["ttl"], json.dumps(record))
 
-                logger.info("Artifact updated successfully", extra={"artifact_id": artifact_id})
+            logger.info("Artifact updated successfully", extra={"artifact_id": artifact_id})
+            return True
 
-            except Exception as e:
-                logger.error(f"Update failed for artifact {artifact_id}: {e}")
-                raise ProviderError(f"Artifact update failed: {e}") from e
+        except Exception as e:
+            logger.error(f"Update failed for artifact {artifact_id}: {e}")
+            raise ProviderError(f"Artifact update failed: {e}") from e
             
     async def retrieve(self, artifact_id: str) -> bytes:
         """Retrieve artifact data."""
@@ -246,7 +263,7 @@ class CoreStorageOperations:
         raise last_exception
 
     async def _get_record(self, artifact_id: str) -> Dict[str, Any]:
-        """Get artifact metadata."""
+        """Get artifact metadata record from session provider."""
         try:
             session_ctx_mgr = self.artifact_store._session_factory()
             async with session_ctx_mgr as session:
@@ -255,7 +272,7 @@ class CoreStorageOperations:
             raise SessionError(f"Session error for {artifact_id}: {e}") from e
         
         if raw is None:
-            raise ProviderError(f"Artifact {artifact_id} not found")
+            raise ArtifactNotFoundError(f"Artifact {artifact_id} not found")
         
         try:
             return json.loads(raw)

chuk_artifacts/grid.py

@@ -1,28 +1,161 @@
+# -*- coding: utf-8 -*-
 # chuk_artifacts/grid.py
 """Utility helpers for grid-style paths.
 
-Pattern: grid/{sandbox_id}/{session_id}/{artifact_id}[/{subpath}]"""
+Pattern: grid/{sandbox_id}/{session_id}/{artifact_id}[/{subpath}]
+
+All components (sandbox_id, session_id, artifact_id) must be non-empty strings
+to ensure proper grid organization and prevent path collisions.
+"""
 
 from typing import Optional, Dict
 
 _ROOT = "grid"
 
 
+class GridError(ValueError):
+    """Raised when grid path operations encounter invalid input."""
+    pass
+
+
+def _validate_component(component: str, name: str) -> None:
+    """Validate a grid path component."""
+    if not isinstance(component, str):
+        raise GridError(f"{name} must be a string, got {type(component).__name__}")
+    if not component:
+        raise GridError(f"{name} cannot be empty")
+    if "/" in component:
+        raise GridError(f"{name} cannot contain '/' characters: {component!r}")
+
+
 def canonical_prefix(sandbox_id: str, session_id: str) -> str:
+    """
+    Generate canonical prefix for a sandbox/session combination.
+    
+    Args:
+        sandbox_id: Non-empty sandbox identifier
+        session_id: Non-empty session identifier
+        
+    Returns:
+        Canonical prefix ending with '/'
+        
+    Raises:
+        GridError: If any component is invalid
+    """
+    _validate_component(sandbox_id, "sandbox_id")
+    _validate_component(session_id, "session_id")
+    
     return f"{_ROOT}/{sandbox_id}/{session_id}/"
 
 
 def artifact_key(sandbox_id: str, session_id: str, artifact_id: str) -> str:
+    """
+    Generate artifact key for grid storage.
+    
+    Args:
+        sandbox_id: Non-empty sandbox identifier
+        session_id: Non-empty session identifier  
+        artifact_id: Non-empty artifact identifier
+        
+    Returns:
+        Grid artifact key
+        
+    Raises:
+        GridError: If any component is invalid
+    """
+    _validate_component(sandbox_id, "sandbox_id")
+    _validate_component(session_id, "session_id")
+    _validate_component(artifact_id, "artifact_id")
+    
     return f"{_ROOT}/{sandbox_id}/{session_id}/{artifact_id}"
 
 
-def parse(key: str) -> Optional[Dict[str, str]]:
+def parse(key: str) -> Optional[Dict[str, Optional[str]]]:
+    """
+    Parse a grid key into components.
+    
+    Args:
+        key: Grid key to parse
+        
+    Returns:
+        Dictionary with components, or None if invalid
+        
+    Examples:
+        >>> parse("grid/sandbox/session/artifact")
+        {'sandbox_id': 'sandbox', 'session_id': 'session', 'artifact_id': 'artifact', 'subpath': None}
+        
+        >>> parse("grid/sandbox/session/artifact/sub/path")
+        {'sandbox_id': 'sandbox', 'session_id': 'session', 'artifact_id': 'artifact', 'subpath': 'sub/path'}
+        
+        >>> parse("invalid/key")
+        None
+    """
+    if not isinstance(key, str):
+        return None
+        
     parts = key.split("/")
-    if len(parts) < 4 or parts[0] != _ROOT:
+    
+    # Must have at least 4 parts: root, sandbox, session, artifact
+    if len(parts) < 4:
         return None
+        
+    # Must start with correct root
+    if parts[0] != _ROOT:
+        return None
+    
+    # Extract components
+    sandbox_id = parts[1]
+    session_id = parts[2] 
+    artifact_id = parts[3]
+    
+    # Validate that core components are non-empty
+    if not sandbox_id or not session_id or not artifact_id:
+        return None
+    
+    # Handle subpath
+    subpath = None
+    if len(parts) > 4:
+        subpath_parts = parts[4:]
+        subpath = "/".join(subpath_parts)
+        # Convert empty subpath to None for consistency
+        if subpath == "":
+            subpath = None
+    
     return {
-        "sandbox_id": parts[1],
-        "session_id": parts[2],
-        "artifact_id": parts[3] if len(parts) > 3 else None,
-        "subpath": "/".join(parts[4:]) if len(parts) > 4 else None,
+        "sandbox_id": sandbox_id,
+        "session_id": session_id,
+        "artifact_id": artifact_id,
+        "subpath": subpath,
     }
+
+
+def is_valid_grid_key(key: str) -> bool:
+    """
+    Check if a string is a valid grid key.
+    
+    Args:
+        key: String to validate
+        
+    Returns:
+        True if valid grid key, False otherwise
+    """
+    return parse(key) is not None
+
+
+def validate_grid_key(key: str) -> Dict[str, Optional[str]]:
+    """
+    Validate and parse a grid key, raising an exception if invalid.
+    
+    Args:
+        key: Grid key to validate
+        
+    Returns:
+        Parsed grid components
+        
+    Raises:
+        GridError: If key is invalid
+    """
+    result = parse(key)
+    if result is None:
+        raise GridError(f"Invalid grid key: {key!r}")
+    return result

chuk_artifacts/metadata.py

@@ -53,6 +53,7 @@ class MetadataOperations:
             # Delete metadata from session provider
             session_ctx_mgr = self.artifact_store._session_factory()
             async with session_ctx_mgr as session:
+                # Fix: hasattr is not async, don't await it
                 if hasattr(session, 'delete'):
                     await session.delete(artifact_id)
             

chuk_artifacts/models.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # chuk_artifacts/models.py
 from typing import Any, Dict
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, ConfigDict
 
 
 class ArtifactEnvelope(BaseModel):
@@ -19,5 +19,5 @@ class ArtifactEnvelope(BaseModel):
     summary: str                            # human-readable description / alt
     meta: Dict[str, Any] = Field(default_factory=dict)
 
-    class Config:
-        extra = "allow"                     # future-proof: lets tools add keys
+    # Pydantic V2 configuration using ConfigDict
+    model_config = ConfigDict(extra="allow")  # future-proof: lets tools add keys

chuk_artifacts/providers/filesystem.py

@@ -88,7 +88,9 @@ class _FilesystemClient:
         
         async with self._lock:
             await self._ensure_parent_dir(object_path)
+            # Write the main object file
             await asyncio.to_thread(object_path.write_bytes, Body)
+            # Write the metadata file
             await self._write_metadata(meta_path, ContentType, Metadata, len(Body), etag)
 
         return {
@@ -110,7 +112,16 @@ class _FilesystemClient:
         meta_path = self._get_metadata_path(object_path)
 
         if not object_path.exists():
-            raise FileNotFoundError(f"NoSuchKey: {Key}")
+            # Mimic S3 NoSuchKey error
+            error = {
+                "Error": {
+                    "Code": "NoSuchKey",
+                    "Message": "The specified key does not exist.",
+                    "Key": Key,
+                    "BucketName": Bucket,
+                }
+            }
+            raise Exception(f"NoSuchKey: {error}")
 
         async with self._lock:
             body = await asyncio.to_thread(object_path.read_bytes)
@@ -142,7 +153,16 @@ class _FilesystemClient:
         meta_path = self._get_metadata_path(object_path)
 
         if not object_path.exists():
-            raise FileNotFoundError(f"NoSuchKey: {Key}")
+            # Mimic S3 NoSuchKey error
+            error = {
+                "Error": {
+                    "Code": "NoSuchKey",
+                    "Message": "The specified key does not exist.",
+                    "Key": Key,
+                    "BucketName": Bucket,
+                }
+            }
+            raise Exception(f"NoSuchKey: {error}")
 
         async with self._lock:
             metadata = await self._read_metadata(meta_path)
@@ -163,7 +183,7 @@ class _FilesystemClient:
             
         bucket_path = self._root / Bucket
         if not bucket_path.exists():
-            raise FileNotFoundError(f"NoSuchBucket: {Bucket}")
+            bucket_path.mkdir(parents=True, exist_ok=True)
             
         return {"ResponseMetadata": {"HTTPStatusCode": 200}}
 

chuk_artifacts/providers/ibm_cos.py

@@ -2,74 +2,30 @@
 # chuk_artifacts/providers/ibm_cos.py
 """
 Factory for an aioboto3 client wired for IBM Cloud Object Storage (COS).
-Supports both IAM and HMAC auth.
 
-aioboto3 ≥ 12 returns an *async-context* client, so we expose
-    • factory() - preferred, used by provider_factory
-    • client()  - retained for backward-compat tests/manual use
+AUTO-GENERATED by IBM COS Signature Tester
+Best configuration: Signature v2 + Virtual (IBM COS Alt)
+Score: 10/10
+Tested on: 2025-06-20 16:03:24
 """
 
 from __future__ import annotations
 import os, aioboto3
-from aioboto3.session import AioConfig  # ✅ CRITICAL: Import AioConfig
+from aioboto3.session import AioConfig
 from typing import Optional, Callable, AsyncContextManager
 
-# ──────────────────────────────────────────────────────────────────
-# internal helper that actually builds the client
-# ──────────────────────────────────────────────────────────────────
-def _build_client(
-    *,
-    endpoint_url: str,
-    region: str,
-    ibm_api_key: Optional[str],
-    ibm_instance_crn: Optional[str],
-    access_key: Optional[str],
-    secret_key: Optional[str],
-):
-    session = aioboto3.Session()
-
-    # IAM auth (preferred)
-    if not access_key and not secret_key:
-        return session.client(
-            "s3",
-            endpoint_url=endpoint_url,
-            region_name=region,
-            ibm_api_key_id=ibm_api_key,
-            ibm_service_instance_id=ibm_instance_crn,
-            # ✅ Use SigV2 for IBM COS IAM + path style
-            config=AioConfig(
-                signature_version='s3',
-                s3={'addressing_style': 'path'}
-            )
-        )
-
-    # HMAC auth
-    return session.client(
-        "s3",
-        endpoint_url=endpoint_url,
-        region_name=region,
-        aws_access_key_id=access_key,
-        aws_secret_access_key=secret_key,
-        # ✅ Use SigV2 for IBM COS HMAC + path style
-        config=AioConfig(
-            signature_version='s3',
-            s3={'addressing_style': 'path'}
-        )
-    )
-
 
-# ──────────────────────────────────────────────────────────────────
-# public factory  (provider_factory expects this)
-# ──────────────────────────────────────────────────────────────────
 def factory(
     *,
     endpoint_url: Optional[str] = None,
     region: str = "us-south",
     access_key: Optional[str] = None,
     secret_key: Optional[str] = None,
-):
+) -> Callable[[], AsyncContextManager]:
     """
     Return an async-context S3 client for IBM COS (HMAC only).
+    
+    Tested configuration: Signature v2 + Virtual (IBM COS Alt)
     """
     endpoint_url = endpoint_url or os.getenv(
         "IBM_COS_ENDPOINT",
@@ -78,18 +34,21 @@ def factory(
     access_key = access_key or os.getenv("AWS_ACCESS_KEY_ID")
     secret_key = secret_key or os.getenv("AWS_SECRET_ACCESS_KEY")
     
-    # ✅ Extract region from endpoint to ensure they match
+    # Extract region from endpoint
     if endpoint_url:
         if "us-south" in endpoint_url:
             region = "us-south"
         elif "us-east" in endpoint_url:
-            region = "us-east-1"
+            region = "us-east"
         elif "eu-gb" in endpoint_url:
             region = "eu-gb"
         elif "eu-de" in endpoint_url:
             region = "eu-de"
+        elif "jp-tok" in endpoint_url:
+            region = "jp-tok"
+        elif "au-syd" in endpoint_url:
+            region = "au-syd"
     
-    # Check AWS_REGION environment variable as override
     env_region = os.getenv('AWS_REGION')
     if env_region:
         region = env_region
@@ -109,13 +68,56 @@ def factory(
             region_name=region,
             aws_access_key_id=access_key,
             aws_secret_access_key=secret_key,
-            # ✅ CRITICAL: IBM COS requires Signature Version 2 for writes AND presigned URLs
             config=AioConfig(
                 signature_version='s3',
-                s3={
-                    'addressing_style': 'path'  # Also ensure path-style addressing
+                s3={'addressing_style': 'virtual'},
+                read_timeout=60,
+                connect_timeout=30,
+                retries={
+                    'max_attempts': 3,
+                    'mode': 'adaptive'
                 }
             )
         )
 
-    return _make
+    return _make
+
+
+def client(
+    *,
+    endpoint_url: Optional[str] = None,
+    region: Optional[str] = None,
+    access_key: Optional[str] = None,
+    secret_key: Optional[str] = None,
+):
+    """Return an aioboto3 S3 client context manager for IBM COS."""
+    session = aioboto3.Session()
+    
+    endpoint_url = endpoint_url or os.getenv(
+        "IBM_COS_ENDPOINT",
+        "https://s3.us-south.cloud-object-storage.appdomain.cloud"
+    )
+    
+    if not region:
+        if "us-south" in endpoint_url:
+            region = "us-south"
+        elif "us-east" in endpoint_url:
+            region = "us-east"
+        elif "eu-gb" in endpoint_url:
+            region = "eu-gb"
+        else:
+            region = "us-south"
+    
+    return session.client(
+        "s3",
+        endpoint_url=endpoint_url,
+        region_name=region,
+        aws_access_key_id=access_key or os.getenv("AWS_ACCESS_KEY_ID"),
+        aws_secret_access_key=secret_key or os.getenv("AWS_SECRET_ACCESS_KEY"),
+        config=AioConfig(
+            signature_version='s3',
+            s3={'addressing_style': 'virtual'},
+            read_timeout=60,
+            connect_timeout=30
+        )
+    )