chuk-artifacts 0.1.0__py3-none-any.whl

chuk_artifacts-0.1.0.dist-info/METADATA

@@ -0,0 +1,519 @@
+Metadata-Version: 2.4
+Name: chuk-artifacts
+Version: 0.1.0
+Summary: Add your description here
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chuk-tool-processor>=0.1.7
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: aioboto3>=14.3.0
+Requires-Dist: redis>=6.2.0
+Requires-Dist: ibm-cos-sdk>=2.13.5
+Requires-Dist: chuk-sessions>=0.1.0
+Provides-Extra: websocket
+Requires-Dist: websockets>=10.0; extra == "websocket"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"
+Requires-Dist: ruff>=0.4.6; extra == "dev"
+Dynamic: license-file
+
+# Chuk Artifacts
+
+[![Tests](https://img.shields.io/badge/tests-64%2F64%20passing-brightgreen)](https://github.com/your-org/chuk-artifacts)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Asynchronous, multi-backend artifact storage with metadata caching and presigned URLs**
+
+Chuk Artifacts provides a production-ready, modular artifact storage system that works seamlessly across multiple storage backends (memory, filesystem, AWS S3, IBM Cloud Object Storage) with Redis or memory-based metadata caching.
+
+## ✨ Key Features
+
+- 🏗️ **Modular Architecture**: 5 specialized operation modules for clean separation of concerns
+- 🔄 **Multi-Backend Support**: Memory, filesystem, S3, IBM COS with seamless switching
+- ⚡ **Fully Async**: Built with async/await for high performance
+- 🔗 **Presigned URLs**: Secure, time-limited access without credential exposure
+- 📊 **Batch Operations**: Efficient multi-file uploads and processing
+- 🗃️ **Metadata Caching**: Fast lookups with Redis or memory-based sessions
+- 🔧 **Zero Configuration**: Works out of the box with sensible defaults
+- 🌍 **Production Ready**: Battle-tested with comprehensive error handling
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install chuk-artifacts
+# or with uv
+uv add chuk-artifacts
+```
+
+### Basic Usage
+
+```python
+from chuk_artifacts import ArtifactStore
+
+# Zero-config setup (uses memory provider)
+store = ArtifactStore()
+
+# Store an artifact
+artifact_id = await store.store(
+    data=b"Hello, world!",
+    mime="text/plain",
+    summary="A simple greeting",
+    filename="hello.txt"
+)
+
+# Retrieve it
+data = await store.retrieve(artifact_id)
+print(data.decode())  # "Hello, world!"
+
+# Generate a presigned URL
+download_url = await store.presign_medium(artifact_id)  # 1 hour
+```
+
+### With Configuration
+
+```python
+# Production setup with S3 and Redis
+store = ArtifactStore(
+    storage_provider="s3",
+    session_provider="redis",
+    bucket="my-artifacts"
+)
+
+# Or use environment variables
+# ARTIFACT_PROVIDER=s3
+# SESSION_PROVIDER=redis
+# AWS_ACCESS_KEY_ID=your_key
+# AWS_SECRET_ACCESS_KEY=your_secret
+# ARTIFACT_BUCKET=my-artifacts
+
+store = ArtifactStore()  # Auto-loads configuration
+```
+
+## 🏗️ Architecture
+
+Chuk Artifacts uses a modular architecture with specialized operation modules:
+
+```
+ArtifactStore (Main Coordinator)
+├── CoreStorageOperations     # store() and retrieve()
+├── PresignedURLOperations    # URL generation and upload workflows
+├── MetadataOperations        # metadata, exists, delete, update
+├── BatchOperations          # store_batch() for multiple files
+└── AdminOperations          # validate_configuration, get_stats
+```
+
+This design provides:
+- **Better testability**: Each module can be tested independently
+- **Enhanced maintainability**: Clear separation of concerns
+- **Easy extensibility**: Add new operation types without touching core
+- **Improved debugging**: Isolated functionality for easier troubleshooting
+
+## 📦 Storage Providers
+
+### Memory Provider
+```python
+store = ArtifactStore(storage_provider="memory")
+```
+- Perfect for development and testing
+- Zero configuration required
+- Non-persistent (data lost on restart)
+- Isolation between async contexts
+
+### Filesystem Provider
+```python
+store = ArtifactStore(storage_provider="filesystem")
+# Set root directory
+os.environ["ARTIFACT_FS_ROOT"] = "./my-artifacts"
+```
+- Local disk storage
+- Persistent across restarts
+- `file://` URLs for local access
+- Great for development and small deployments
+
+### AWS S3 Provider
+```python
+store = ArtifactStore(storage_provider="s3")
+# Configure via environment
+os.environ.update({
+    "AWS_ACCESS_KEY_ID": "your_key",
+    "AWS_SECRET_ACCESS_KEY": "your_secret",
+    "AWS_REGION": "us-east-1",
+    "ARTIFACT_BUCKET": "my-bucket"
+})
+```
+- Industry-standard cloud storage
+- Native presigned URL support
+- Highly scalable and durable
+- Perfect for production workloads
+
+### IBM Cloud Object Storage
+```python
+# HMAC authentication
+store = ArtifactStore(storage_provider="ibm_cos")
+os.environ.update({
+    "AWS_ACCESS_KEY_ID": "your_hmac_key",
+    "AWS_SECRET_ACCESS_KEY": "your_hmac_secret",
+    "IBM_COS_ENDPOINT": "https://s3.us-south.cloud-object-storage.appdomain.cloud"
+})
+
+# IAM authentication
+store = ArtifactStore(storage_provider="ibm_cos_iam")
+os.environ.update({
+    "IBM_COS_APIKEY": "your_api_key",
+    "IBM_COS_INSTANCE_CRN": "crn:v1:bluemix:public:cloud-object-storage:..."
+})
+```
+
+## 🗃️ Session Providers
+
+### Memory Sessions
+```python
+store = ArtifactStore(session_provider="memory")
+```
+- In-memory metadata storage
+- Fast but non-persistent
+- Perfect for testing
+
+### Redis Sessions
+```python
+store = ArtifactStore(session_provider="redis")
+os.environ["SESSION_REDIS_URL"] = "redis://localhost:6379/0"
+```
+- Persistent metadata storage
+- Shared across multiple instances
+- Production-ready caching
+
+## 🎯 Common Use Cases
+
+### Web Framework Integration
+
+```python
+from chuk_artifacts import ArtifactStore
+
+# Initialize once at startup
+store = ArtifactStore(
+    storage_provider="s3",
+    session_provider="redis"
+)
+
+async def upload_file(file_content: bytes, filename: str, content_type: str):
+    """Handle file upload in FastAPI/Flask"""
+    artifact_id = await store.store(
+        data=file_content,
+        mime=content_type,
+        summary=f"Uploaded: {filename}",
+        filename=filename
+    )
+    
+    # Return download URL
+    download_url = await store.presign_medium(artifact_id)
+    return {
+        "artifact_id": artifact_id,
+        "download_url": download_url
+    }
+```
+
+### Batch Processing
+
+```python
+# Prepare multiple files
+items = [
+    {
+        "data": file1_content,
+        "mime": "image/png",
+        "summary": "Product image 1",
+        "filename": "product1.png"
+    },
+    {
+        "data": file2_content,
+        "mime": "image/png", 
+        "summary": "Product image 2",
+        "filename": "product2.png"
+    }
+]
+
+# Store all at once
+artifact_ids = await store.store_batch(items, session_id="product-images")
+```
+
+### Advanced Metadata Management
+
+```python
+# Store with custom metadata
+artifact_id = await store.store(
+    data=image_data,
+    mime="image/png",
+    summary="Product photo",
+    filename="product.png",
+    meta={
+        "product_id": "12345",
+        "photographer": "John Doe",
+        "category": "electronics"
+    }
+)
+
+# Update metadata later
+await store.update_metadata(
+    artifact_id,
+    summary="Updated product photo",
+    meta={"edited": True, "version": 2}
+)
+
+# Extend TTL
+await store.extend_ttl(artifact_id, 3600)  # Add 1 hour
+```
+
+### Context Manager Usage
+
+```python
+async with ArtifactStore() as store:
+    artifact_id = await store.store(
+        data=b"Temporary data",
+        mime="text/plain",
+        summary="Auto-cleanup example"
+    )
+    # Store automatically closed on exit
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```bash
+# Storage configuration
+ARTIFACT_PROVIDER=s3              # memory, filesystem, s3, ibm_cos, ibm_cos_iam
+ARTIFACT_BUCKET=my-artifacts       # Bucket/container name
+ARTIFACT_FS_ROOT=./artifacts       # Filesystem root (filesystem provider)
+
+# Session configuration  
+SESSION_PROVIDER=redis             # memory, redis
+SESSION_REDIS_URL=redis://localhost:6379/0
+
+# AWS/S3 configuration
+AWS_ACCESS_KEY_ID=your_key
+AWS_SECRET_ACCESS_KEY=your_secret
+AWS_REGION=us-east-1
+S3_ENDPOINT_URL=https://custom-s3.com  # Optional: custom S3 endpoint
+
+# IBM COS configuration
+IBM_COS_ENDPOINT=https://s3.us-south.cloud-object-storage.appdomain.cloud
+IBM_COS_APIKEY=your_api_key        # For IAM auth
+IBM_COS_INSTANCE_CRN=crn:v1:...    # For IAM auth
+```
+
+### Programmatic Configuration
+
+```python
+from chuk_artifacts.config import configure_s3, configure_redis_session
+
+# Configure S3 storage
+configure_s3(
+    access_key="AKIA...",
+    secret_key="...",
+    bucket="prod-artifacts",
+    region="us-west-2"
+)
+
+# Configure Redis sessions
+configure_redis_session("redis://prod-redis:6379/1")
+
+# Create store with this configuration
+store = ArtifactStore()
+```
+
+## 🧪 Testing
+
+### Run All Tests
+```bash
+# Comprehensive smoke test (64 test scenarios)
+uv run examples/artifact_smoke_test.py
+
+# Usage examples
+uv run examples/artifact_usage_examples.py
+```
+
+### Development Setup
+```python
+from chuk_artifacts.config import development_setup
+
+store = development_setup()  # Uses memory providers
+```
+
+### Testing Setup
+```python
+from chuk_artifacts.config import testing_setup
+
+store = testing_setup("./test-artifacts")  # Uses filesystem
+```
+
+## 🚀 Performance
+
+- **Async/Await**: Non-blocking I/O for high concurrency
+- **Connection Pooling**: Efficient resource usage with aioboto3
+- **Metadata Caching**: Fast lookups with Redis
+- **Batch Operations**: Reduced overhead for multiple files
+- **Streaming**: Large file support with streaming reads/writes
+
+## 🔒 Security
+
+- **Presigned URLs**: Time-limited access without credential sharing
+- **Secure Defaults**: Conservative TTL and expiration settings
+- **Credential Isolation**: Environment-based configuration
+- **Error Handling**: No sensitive data in logs or exceptions
+
+## 🛠️ Advanced Features
+
+### Custom Providers
+```python
+# Create custom storage provider
+def my_custom_factory():
+    @asynccontextmanager
+    async def _ctx():
+        client = MyCustomClient()
+        try:
+            yield client
+        finally:
+            await client.close()
+    return _ctx
+
+store = ArtifactStore(s3_factory=my_custom_factory())
+```
+
+### Error Handling
+```python
+from chuk_artifacts import (
+    ArtifactNotFoundError,
+    ArtifactExpiredError, 
+    ProviderError
+)
+
+try:
+    data = await store.retrieve("invalid-id")
+except ArtifactNotFoundError:
+    print("Artifact not found or expired")
+except ProviderError as e:
+    print(f"Storage provider error: {e}")
+```
+
+### Validation and Monitoring
+```python
+# Validate configuration
+config_status = await store.validate_configuration()
+print(f"Storage: {config_status['storage']['status']}")
+print(f"Session: {config_status['session']['status']}")
+
+# Get statistics
+stats = await store.get_stats()
+print(f"Provider: {stats['storage_provider']}")
+print(f"Bucket: {stats['bucket']}")
+```
+
+## 📝 API Reference
+
+### Core Methods
+
+#### `store(data, *, mime, summary, meta=None, filename=None, session_id=None, ttl=900)`
+Store artifact data with metadata.
+
+**Parameters:**
+- `data` (bytes): The artifact data
+- `mime` (str): MIME type (e.g., "text/plain", "image/png")
+- `summary` (str): Human-readable description
+- `meta` (dict, optional): Additional metadata
+- `filename` (str, optional): Original filename
+- `session_id` (str, optional): Session identifier for organization
+- `ttl` (int, optional): Metadata TTL in seconds (default: 900)
+
+**Returns:** `str` - Unique artifact identifier
+
+#### `retrieve(artifact_id)`
+Retrieve artifact data by ID.
+
+**Parameters:**
+- `artifact_id` (str): The artifact identifier
+
+**Returns:** `bytes` - The artifact data
+
+#### `metadata(artifact_id)`
+Get artifact metadata.
+
+**Returns:** `dict` - Metadata including size, MIME type, timestamps, etc.
+
+#### `exists(artifact_id)`
+Check if artifact exists and hasn't expired.
+
+**Returns:** `bool`
+
+#### `delete(artifact_id)`
+Delete artifact and its metadata.
+
+**Returns:** `bool` - True if deleted, False if not found
+
+### Presigned URLs
+
+#### `presign(artifact_id, expires=3600)`
+Generate presigned URL for download.
+
+#### `presign_short(artifact_id)` / `presign_medium(artifact_id)` / `presign_long(artifact_id)`
+Generate URLs with predefined durations (15min/1hr/24hr).
+
+#### `presign_upload(session_id=None, filename=None, mime_type="application/octet-stream", expires=3600)`
+Generate presigned URL for upload.
+
+**Returns:** `tuple[str, str]` - (upload_url, artifact_id)
+
+### Batch Operations
+
+#### `store_batch(items, session_id=None, ttl=900)`
+Store multiple artifacts efficiently.
+
+**Parameters:**
+- `items` (list): List of dicts with keys: data, mime, summary, meta, filename
+
+**Returns:** `list[str]` - List of artifact IDs
+
+### Admin Operations
+
+#### `validate_configuration()`
+Validate storage and session provider connectivity.
+
+#### `get_stats()`
+Get storage statistics and configuration info.
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes
+4. Run tests: `uv run examples/artifact_smoke_test.py`
+5. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- **Documentation**: [docs.example.com](https://docs.example.com)
+- **Issue Tracker**: [github.com/your-org/chuk-artifacts/issues](https://github.com/your-org/chuk-artifacts/issues)
+- **PyPI**: [pypi.org/project/chuk-artifacts](https://pypi.org/project/chuk-artifacts)
+
+## 🎯 Roadmap
+
+- [ ] Azure Blob Storage provider
+- [ ] Google Cloud Storage provider
+- [ ] Encryption at rest
+- [ ] Artifact versioning
+- [ ] Webhook notifications
+- [ ] Prometheus metrics export
+
+---
+
+**Made with ❤️ by the Chuk team**

chuk_artifacts-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+chuk_artifacts/__init__.py,sha256=-4S9FWKVcQSa2ZD3GVbmbpGZPcl0cTQN_TFZLSqV7lQ,3605
+chuk_artifacts/admin.py,sha256=g8r1nta_cDkoy_KgScTHkeeV7ij5PR6jX0GXgUYub7Y,2662
+chuk_artifacts/base.py,sha256=d3iA3AJR9wF0I3kmppkosPDxaMTgufqI6v_wW5fQfKY,2411
+chuk_artifacts/batch.py,sha256=I5WgWajuzrvqTCkQYYgpzrL1WduzxJchA3Ihv3Xvhcw,4264
+chuk_artifacts/config.py,sha256=MaUzHzKPoBUyERviEpv8JVvPybMzSksgLyj0b7AO3Sc,7664
+chuk_artifacts/core.py,sha256=rS5VWjen6aRlnAIJIhLi639VfZ2u8ORaFxrPJMfpPYE,8296
+chuk_artifacts/exceptions.py,sha256=f-s7Mg7c8vMXsbgqO2B6lMHdXcJQNvsESAY4GhJaV4g,814
+chuk_artifacts/metadata.py,sha256=CXC0j-zjKSOoACmyu6yKqcQpy35otwr-Y_3ogfcuKdE,9123
+chuk_artifacts/models.py,sha256=_foXlkr0DprqgztDw5WtlDc-s1OouLgYNp4XM1Ghp-g,837
+chuk_artifacts/presigned.py,sha256=qonNg7WMd7VmOEXAzF6GssXuPs5be2s8IJhtuFul7JM,9638
+chuk_artifacts/provider_factory.py,sha256=T0IXx1C8gygJzp417oB44_DxEaZoZR7jcdwQy8FghRE,3398
+chuk_artifacts/store.py,sha256=QdNyik5EXg2NthHnWxUnG5JMM1L7v2jO7phCL5WmvGg,16719
+chuk_artifacts/providers/__init__.py,sha256=3lN1lAy1ETT1mQslJo1f22PPR1W4CyxmsqJBclzH4NE,317
+chuk_artifacts/providers/filesystem.py,sha256=F4EjE-_ItPg0RWe7CqameVpOMjU-b7AigEBkm_ZoNrc,15280
+chuk_artifacts/providers/ibm_cos.py,sha256=K1-VAX4UVV9tA161MOeDXOKloQ0hB77jdw1-p46FwmU,4445
+chuk_artifacts/providers/ibm_cos_iam.py,sha256=VtwvCi9rMMcZx6i9l21ob6wM8jXseqvjzgCnAA82RkY,3186
+chuk_artifacts/providers/memory.py,sha256=B1C-tR1PcNz-UuDfGm1bhjPz3oITVATIMPekVbE7nm4,10487
+chuk_artifacts/providers/s3.py,sha256=eWhBhFSaobpRbazn7ySfU_7D8rm_xCfdSVqRtzXzXRY,2858
+chuk_artifacts-0.1.0.dist-info/licenses/LICENSE,sha256=SG9BmgtPBagPV0d-Fep-msdAGl-E1CeoBL7-EDRH2qA,1066
+chuk_artifacts-0.1.0.dist-info/METADATA,sha256=G_DqvAOc5JzpuPDDdMqA1ULhTk6J588gjVVvQ9_5H9A,13847
+chuk_artifacts-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+chuk_artifacts-0.1.0.dist-info/top_level.txt,sha256=1_PVMtWXR0A-ZmeH6apF9mPaMtU0i23JE6wmN4GBRDI,15
+chuk_artifacts-0.1.0.dist-info/RECORD,,

chuk_artifacts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chuk_artifacts-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Hay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chuk_artifacts-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chuk_artifacts