picsha 0.1.1__tar.gz

picsha-0.1.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: picsha
+Version: 0.1.1
+Summary: Official Python SDK for Picsha AI - Store, Encode, Understand.
+Author: Peter
+Author-email: peter@picsha.ai
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
+Requires-Dist: pydantic (>=2.6.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Picsha AI Python SDK 🐍
+
+The official Python client for Picsha AI. Designed specifically for data scientists, computational biologists, and ML engineers.
+
+## Installation
+
+We recommend using poetry:
+
+```bash
+poetry add picsha
+```
+
+Or pip:
+
+```bash
+pip install picsha
+```
+
+## Quickstart
+
+```python
+import picsha
+
+client = picsha.Client(api_key="sk_your_key_here")
+
+# 1. Semantic Search
+results = client.search(
+    query="fluorescent cancer cell cultures", 
+    mode="ai"  # Hybrid Vector Search
+)
+
+# 2. Get transformed URLs for ML pipelines
+for asset in results.assets:
+    url = asset.generate_url(width=512, height=512, format="webp")
+    print(url)
+```
+
+## Asynchronous Support
+
+For high-throughput workloads, an `AsyncClient` is included out-of-the-box:
+
+```python
+import picsha
+import asyncio
+
+async def main():
+    async with picsha.AsyncClient(api_key="sk_your_key_here") as client:
+        result = await client.search(query="cancer cells", mode="ai")
+        print(f"Found {result.total_count} assets.")
+
+asyncio.run(main())
+```
+
+See the `notebooks/` directory for full examples integrating with Pandas, PyTorch, and SciPy.
+

picsha-0.1.1/README.md

@@ -0,0 +1,54 @@
+# Picsha AI Python SDK 🐍
+
+The official Python client for Picsha AI. Designed specifically for data scientists, computational biologists, and ML engineers.
+
+## Installation
+
+We recommend using poetry:
+
+```bash
+poetry add picsha
+```
+
+Or pip:
+
+```bash
+pip install picsha
+```
+
+## Quickstart
+
+```python
+import picsha
+
+client = picsha.Client(api_key="sk_your_key_here")
+
+# 1. Semantic Search
+results = client.search(
+    query="fluorescent cancer cell cultures", 
+    mode="ai"  # Hybrid Vector Search
+)
+
+# 2. Get transformed URLs for ML pipelines
+for asset in results.assets:
+    url = asset.generate_url(width=512, height=512, format="webp")
+    print(url)
+```
+
+## Asynchronous Support
+
+For high-throughput workloads, an `AsyncClient` is included out-of-the-box:
+
+```python
+import picsha
+import asyncio
+
+async def main():
+    async with picsha.AsyncClient(api_key="sk_your_key_here") as client:
+        result = await client.search(query="cancer cells", mode="ai")
+        print(f"Found {result.total_count} assets.")
+
+asyncio.run(main())
+```
+
+See the `notebooks/` directory for full examples integrating with Pandas, PyTorch, and SciPy.

picsha-0.1.1/picsha/__init__.py

@@ -0,0 +1,16 @@
+from .client import Client, AsyncClient
+from .exceptions import PicshaError, PicshaAuthError, PicshaAPIError
+from .models import Asset, SearchResult, UploadResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "Asset",
+    "SearchResult",
+    "UploadResult",
+    "PicshaError",
+    "PicshaAuthError",
+    "PicshaAPIError"
+]

picsha-0.1.1/picsha/client.py

@@ -0,0 +1,127 @@
+import os
+import httpx
+from typing import Optional, List, Dict, Any
+
+from .exceptions import PicshaAuthError, PicshaAPIError
+from .models import Asset, SearchResult, UploadResult
+
+class BaseClient:
+    """Base class for shared client configurations."""
+    DEFAULT_BASE_URL = "https://api.picsha.ai/v1"
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
+        self.api_key = api_key or os.environ.get("PICSHA_API_KEY")
+        if not self.api_key:
+            raise PicshaAuthError("API Key is missing. Pass it to the Client or set PICSHA_API_KEY env var.")
+            
+        self.base_url = base_url or self.DEFAULT_BASE_URL
+        self.headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": "picsha-python-sdk/0.1.0"
+        }
+
+    def _handle_error(self, response: httpx.Response):
+        if response.status_code in (401, 403):
+            raise PicshaAuthError("Unauthorized. Invalid API key or insufficient permissions.")
+        
+        try:
+            error_data = response.json()
+        except Exception:
+            error_data = {"text": response.text}
+        raise PicshaAPIError(f"API Request Failed to {response.url.path}", status_code=response.status_code, details=error_data)
+
+class Client(BaseClient):
+    """Synchronous client for interacting with the Picsha AI API."""
+    
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
+        super().__init__(api_key, base_url)
+        self._client = httpx.Client(base_url=self.base_url, headers=self.headers)
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        response = self._client.request(method, path, **kwargs)
+        if not response.is_success:
+            self._handle_error(response)
+        return response.json()
+
+    def search(self, query: str, mode: str = "ai", limit: int = 10, offset: int = 0) -> SearchResult:
+        data = self._request("GET", "search", params={
+            "q": query, "mode": mode, "limit": limit, "offset": offset
+        })
+        return SearchResult(**data)
+
+    def upload(self, file_path: str, tags: Optional[List[str]] = None, metadata: Optional[Dict[str, Any]] = None, ephemeral: bool = False) -> UploadResult:
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+            
+        filename = os.path.basename(file_path)
+        data = {}
+        if tags:
+            data["tags"] = ",".join(tags) 
+        if metadata:
+            import json
+            data["metadata"] = json.dumps(metadata)
+            
+        params = {}
+        if ephemeral:
+            params["ephemeral"] = "true"
+            
+        with open(file_path, "rb") as f:
+            files = {"file": (filename, f)}
+            response_data = self._request("POST", "assets", params=params, data=data, files=files)
+            
+        return UploadResult(**response_data)
+
+
+class AsyncClient(BaseClient):
+    """Asynchronous client for interacting with the Picsha AI API."""
+    
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
+        super().__init__(api_key, base_url)
+        self._client = httpx.AsyncClient(base_url=self.base_url, headers=self.headers)
+
+    async def _request(self, method: str, path: str, **kwargs) -> Any:
+        response = await self._client.request(method, path, **kwargs)
+        if not response.is_success:
+            self._handle_error(response)
+        return response.json()
+
+    async def search(self, query: str, mode: str = "ai", limit: int = 10, offset: int = 0) -> SearchResult:
+        data = await self._request("GET", "search", params={
+            "q": query, "mode": mode, "limit": limit, "offset": offset
+        })
+        return SearchResult(**data)
+
+    async def upload(self, file_path: str, tags: Optional[List[str]] = None, metadata: Optional[Dict[str, Any]] = None, ephemeral: bool = False) -> UploadResult:
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+            
+        filename = os.path.basename(file_path)
+        data = {}
+        if tags:
+            data["tags"] = ",".join(tags) 
+        if metadata:
+            import json
+            data["metadata"] = json.dumps(metadata)
+            
+        params = {}
+        if ephemeral:
+            params["ephemeral"] = "true"
+            
+        with open(file_path, "rb") as f:
+            # We read bytes into memory for V1 async simplified uploads via httpx
+            file_bytes = f.read()
+            
+        files = {"file": (filename, file_bytes)}
+        response_data = await self._request("POST", "assets", params=params, data=data, files=files)
+            
+        return UploadResult(**response_data)
+
+    async def close(self):
+        """Close the underlying async httpx client."""
+        await self._client.aclose()
+        
+    async def __aenter__(self):
+        return self
+        
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

picsha-0.1.1/picsha/exceptions.py

@@ -0,0 +1,14 @@
+class PicshaError(Exception):
+    """Base exception for Picsha SDK"""
+    pass
+
+class PicshaAuthError(PicshaError):
+    """Raised when an API Key is invalid or missing"""
+    pass
+
+class PicshaAPIError(PicshaError):
+    """Raised when the API returns an error response"""
+    def __init__(self, message: str, status_code: int = None, details: dict = None):
+        super().__init__(f"{message} (HTTP {status_code})")
+        self.status_code = status_code
+        self.details = details or {}

picsha-0.1.1/picsha/models.py

@@ -0,0 +1,49 @@
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, Field
+
+class AssetTransformationOptions(BaseModel):
+    width: Optional[int] = None
+    height: Optional[int] = None
+    format: Optional[str] = None
+    quality: Optional[int] = None
+    crop: Optional[str] = None
+
+class Asset(BaseModel):
+    id: str
+    url: str
+    original_filename: Optional[str] = None
+    mime_type: Optional[str] = None
+    size_bytes: Optional[int] = None
+    tags: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    
+    def generate_url(self, **kwargs) -> str:
+        """
+        Generate a transformed image URL locally (similar to Cloudinary SDK).
+        Example: asset.generate_url(width=512, format="webp")
+        """
+        # A simple naive implementation, but matches a CDN proxy approach
+        # For Picsha, we might pass params as query string to our delivery pipeline
+        from urllib.parse import urlparse, urlencode, urlunparse
+        
+        parsed = urlparse(self.url)
+        query_params = {}
+        if parsed.query:
+            # simple parsing just for demo
+            pass 
+        
+        if kwargs:
+            query_params.update(kwargs)
+            
+        new_query = urlencode(query_params)
+        return urlunparse((parsed.scheme, parsed.netloc, parsed.path, parsed.params, new_query, parsed.fragment))
+
+class SearchResult(BaseModel):
+    assets: List[Asset]
+    total_count: int
+    has_more: bool
+
+class UploadResult(BaseModel):
+    success: bool
+    asset: Optional[Asset] = None
+    message: Optional[str] = None

picsha-0.1.1/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "picsha"
+version = "0.1.1"
+description = "Official Python SDK for Picsha AI - Store, Encode, Understand."
+authors = ["Peter <peter@picsha.ai>"] # Assumed from path, will configure accordingly
+readme = "README.md"
+packages = [{include = "picsha"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+httpx = "^0.27.0"
+pydantic = "^2.6.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"