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

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

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

chuk_artifacts/providers/memory.py

@@ -36,6 +36,7 @@ class _MemoryS3Client:
             If None, creates isolated per-instance storage.
         """
         self._store: Dict[str, Dict[str, Any]] = shared_store if shared_store is not None else {}
+        self._is_shared_store = shared_store is not None
         self._lock = asyncio.Lock()
         self._closed = False
         
@@ -231,8 +232,11 @@ class _MemoryS3Client:
     async def close(self):
         """Clean up resources and mark client as closed."""
         if not self._closed:
-            async with self._lock:
-                self._store.clear()
+            # Only clear the store if it's NOT shared
+            # If it's shared, other clients may still need the data
+            if not self._is_shared_store:
+                async with self._lock:
+                    self._store.clear()
             self._closed = True
 
     # ------------------------------------------------------------
@@ -253,6 +257,10 @@ class _MemoryS3Client:
                 "total_objects": total_objects,
                 "total_bytes": total_bytes,
                 "closed": self._closed,
+                "is_shared_store": self._is_shared_store,
+                "store_id": id(self._store),  # Memory address for debugging
+                "client_id": id(self),        # Client instance ID
+                "store_keys": list(self._store.keys())[:5],  # First 5 keys for debugging
             }
 
     @classmethod
@@ -263,17 +271,32 @@ class _MemoryS3Client:
 
 # ---- public factory -------------------------------------------------------
 
+# Global shared storage for memory provider when used as default
+_default_shared_store: Dict[str, Dict[str, Any]] = {}
+
 def factory(shared_store: Optional[Dict[str, Dict[str, Any]]] = None) -> Callable[[], AsyncContextManager]:
     """
     Return a **zero-arg** factory that yields an async-context client.
     
+    Key behavior for memory provider:
+    - If shared_store is provided, uses that specific storage
+    - If shared_store is None, ALWAYS uses the global shared storage
+    - This ensures all memory clients in the same process share data
+    - Prevents issues where ArtifactStore operations can't see each other's data
+    
     Parameters
     ----------
     shared_store : dict, optional
         If provided, all clients created by this factory will share
-        the same storage dict. Useful for testing scenarios where
-        you need multiple clients to see the same data.
+        the same storage dict. If None, will use a global shared store
+        to ensure consistency across operations within the same process.
     """
+    
+    # CRITICAL: Always use global shared storage when none specified
+    # This prevents the common issue where each ArtifactStore operation
+    # gets a different isolated storage and can't see each other's data
+    if shared_store is None:
+        shared_store = _default_shared_store
 
     @asynccontextmanager
     async def _ctx():
@@ -307,6 +330,11 @@ async def clear_all_memory_stores():
     Emergency cleanup function that clears all active memory stores.
     Useful for test teardown.
     """
+    # Clear the global shared store
+    global _default_shared_store
+    _default_shared_store.clear()
+    
+    # Close all active instances
     instances = list(_MemoryS3Client._instances)
     for instance in instances:
         try:

chuk_artifacts/store.py

@@ -633,4 +633,50 @@ class ArtifactStore:
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        await self.close()
+        await self.close()
+
+    async def get_sandbox_info(self) -> Dict[str, Any]:
+        """
+        Get sandbox information and metadata.
+        
+        Returns
+        -------
+        Dict[str, Any]
+            Dictionary containing sandbox information including:
+            - sandbox_id: The current sandbox identifier
+            - bucket: The storage bucket name
+            - storage_provider: The storage provider type
+            - session_provider: The session provider type
+            - session_ttl_hours: Default session TTL
+            - grid_prefix_pattern: The grid path pattern for this sandbox
+            - created_at: Timestamp of when this info was retrieved
+        """
+        from datetime import datetime
+        
+        # Get session manager stats if available
+        session_stats = {}
+        try:
+            session_stats = self._session_manager.get_cache_stats()
+        except Exception:
+            pass  # Session manager might not have stats
+        
+        # Get storage stats if available
+        storage_stats = {}
+        try:
+            storage_stats = await self._admin.get_stats()
+        except Exception:
+            pass  # Storage might not have stats
+        
+        return {
+            "sandbox_id": self.sandbox_id,
+            "bucket": self.bucket,
+            "storage_provider": self._storage_provider_name,
+            "session_provider": self._session_provider_name,
+            "session_ttl_hours": self.session_ttl_hours,
+            "max_retries": self.max_retries,
+            "grid_prefix_pattern": self.get_session_prefix_pattern(),
+            "created_at": datetime.utcnow().isoformat() + "Z",
+            "session_stats": session_stats,
+            "storage_stats": storage_stats,
+            "closed": self._closed,
+        }