chuk-artifacts 0.2.2__py3-none-any.whl → 0.4__py3-none-any.whl

chuk_artifacts/core.py

@@ -101,6 +101,79 @@ class CoreStorageOperations:
             else:
                 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.
+
+            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")
+
+            try:
+                record = await self._get_record(artifact_id)
+                key = record["key"]
+                session_id = record["session_id"]
+
+                # Overwrite in object storage
+                await self._store_with_retry(
+                    new_data,
+                    key,
+                    mime or record["mime"],
+                    filename or record.get("filename"),
+                    session_id,
+                )
+
+                # 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"],
+                })
+
+                if ttl is not None:
+                    record["ttl"] = ttl
+
+                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})
+
+            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."""
         if self.artifact_store._closed:

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

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import json
 import logging
-from typing import Any, Dict, List, Optional, TYPE_CHECKING
+from typing import Any, Dict, List, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from .store import ArtifactStore
@@ -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)
             
@@ -68,7 +69,7 @@ class MetadataOperations:
         try:
             artifacts = []
             # Use the session manager's canonical prefix instead of building our own
-            prefix = self.artifact_store._session_manager.get_canonical_prefix(session_id)
+            prefix = self.artifact_store.get_canonical_prefix(session_id)
             
             storage_ctx_mgr = self.artifact_store._s3_factory()
             async with storage_ctx_mgr as s3:
@@ -82,7 +83,7 @@ class MetadataOperations:
                     for obj in response.get('Contents', []):
                         key = obj['Key']
                         # Parse the grid key using chuk_sessions
-                        parsed = self.artifact_store._session_manager.parse_grid_key(key)
+                        parsed = self.artifact_store.parse_grid_key(key)
                         if parsed and parsed.get('artifact_id'):
                             artifact_id = parsed['artifact_id']
                             try:
@@ -93,7 +94,7 @@ class MetadataOperations:
                     
                     return artifacts[:limit]
             
-            logger.warning(f"Storage provider doesn't support listing")
+            logger.warning("Storage provider doesn't support listing")
             return []
             
         except Exception as e:

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
+        )
+    )

chuk_artifacts/providers/ibm_cos_iam.py

@@ -5,6 +5,11 @@ Async wrapper for IBM Cloud Object Storage using IAM API-key (oauth).
 
 ✓ Fits the aioboto3-style interface that ArtifactStore expects:
     • async put_object(...)
+    • async get_object(...)
+    • async head_object(...)
+    • async delete_object(...)
+    • async list_objects_v2(...)
+    • async head_bucket(...)
     • async generate_presigned_url(...)
 ✓ No HMAC keys required - just IBM_COS_APIKEY + IBM_COS_INSTANCE_CRN.
 
@@ -27,6 +32,7 @@ from ibm_botocore.client import Config
 
 # ─────────────────────────────────────────────────────────────────────
 def _sync_client():
+    """Create synchronous IBM COS client with IAM authentication."""
     endpoint = os.getenv(
         "IBM_COS_ENDPOINT",
         "https://s3.us-south.cloud-object-storage.appdomain.cloud",
@@ -49,19 +55,52 @@ def _sync_client():
 
 # ─────────────────────────────────────────────────────────────────────
 class _AsyncIBMClient:
-    """Minimal async façade over synchronous ibm_boto3 S3 client."""
+    """Complete async façade over synchronous ibm_boto3 S3 client."""
+    
     def __init__(self, sync_client):
         self._c = sync_client
 
-    # ---- methods used by ArtifactStore -------------------------------------
-    async def put_object(self, **kw) -> Dict[str, Any]:
-        return await asyncio.to_thread(self._c.put_object, **kw)
+    # ---- Core S3 operations used by ArtifactStore -------------------------
+    async def put_object(self, **kwargs) -> Dict[str, Any]:
+        """Store object in IBM COS."""
+        return await asyncio.to_thread(self._c.put_object, **kwargs)
 
-    async def generate_presigned_url(self, *a, **kw) -> str:
-        return await asyncio.to_thread(self._c.generate_presigned_url, *a, **kw)
+    async def get_object(self, **kwargs) -> Dict[str, Any]:
+        """Retrieve object from IBM COS."""
+        return await asyncio.to_thread(self._c.get_object, **kwargs)
 
-    # ---- cleanup -----------------------------------------------------------
+    async def head_object(self, **kwargs) -> Dict[str, Any]:
+        """Get object metadata from IBM COS."""
+        return await asyncio.to_thread(self._c.head_object, **kwargs)
+
+    async def delete_object(self, **kwargs) -> Dict[str, Any]:
+        """Delete object from IBM COS."""
+        return await asyncio.to_thread(self._c.delete_object, **kwargs)
+
+    async def list_objects_v2(self, **kwargs) -> Dict[str, Any]:
+        """List objects in IBM COS bucket."""
+        return await asyncio.to_thread(self._c.list_objects_v2, **kwargs)
+
+    async def head_bucket(self, **kwargs) -> Dict[str, Any]:
+        """Check if bucket exists in IBM COS."""
+        return await asyncio.to_thread(self._c.head_bucket, **kwargs)
+
+    async def generate_presigned_url(self, *args, **kwargs) -> str:
+        """Generate presigned URL for IBM COS object."""
+        return await asyncio.to_thread(self._c.generate_presigned_url, *args, **kwargs)
+
+    # ---- Additional operations for completeness ---------------------------
+    async def copy_object(self, **kwargs) -> Dict[str, Any]:
+        """Copy object within IBM COS."""
+        return await asyncio.to_thread(self._c.copy_object, **kwargs)
+
+    async def delete_objects(self, **kwargs) -> Dict[str, Any]:
+        """Delete multiple objects from IBM COS."""
+        return await asyncio.to_thread(self._c.delete_objects, **kwargs)
+
+    # ---- Cleanup -----------------------------------------------------------
     async def close(self):
+        """Close the underlying sync client."""
         await asyncio.to_thread(self._c.close)
 
 
@@ -69,6 +108,11 @@ class _AsyncIBMClient:
 def factory() -> Callable[[], AsyncContextManager]:
     """
     Return a zero-arg callable that yields an async-context-manager.
+    
+    Returns
+    -------
+    Callable[[], AsyncContextManager]
+        Factory function that creates IBM COS IAM client context managers
     """
 
     @asynccontextmanager