sovant 1.0.0__py3-none-any.whl

sovant/__init__.py

@@ -0,0 +1,63 @@
+"""
+Sovant Python SDK
+
+Official Python library for the Sovant Memory API.
+"""
+
+__version__ = "1.0.0"
+
+from .client import SovantClient, AsyncSovantClient
+from .exceptions import (
+    SovantError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    NotFoundError,
+    NetworkError,
+)
+from .types import (
+    Memory,
+    MemoryType,
+    EmotionType,
+    EmotionalContext,
+    CreateMemoryInput,
+    UpdateMemoryInput,
+    SearchOptions,
+    SearchResult,
+    Thread,
+    ThreadStatus,
+    CreateThreadInput,
+    UpdateThreadInput,
+    ThreadStats,
+    BatchCreateResult,
+    PaginatedResponse,
+)
+
+__all__ = [
+    # Client classes
+    "SovantClient",
+    "AsyncSovantClient",
+    # Exceptions
+    "SovantError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "NetworkError",
+    # Types
+    "Memory",
+    "MemoryType",
+    "EmotionType",
+    "EmotionalContext",
+    "CreateMemoryInput",
+    "UpdateMemoryInput",
+    "SearchOptions",
+    "SearchResult",
+    "Thread",
+    "ThreadStatus",
+    "CreateThreadInput",
+    "UpdateThreadInput",
+    "ThreadStats",
+    "BatchCreateResult",
+    "PaginatedResponse",
+]

sovant/base_client.py

@@ -0,0 +1,256 @@
+"""Base client for making API requests."""
+
+import asyncio
+import json
+import os
+from typing import Any, Dict, Optional, TypeVar, Union
+from urllib.parse import urlencode
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    SovantError,
+    ValidationError,
+)
+from .types import Config
+
+T = TypeVar("T")
+
+
+class BaseClient:
+    """Base client for synchronous API requests."""
+    
+    def __init__(self, config: Union[str, Config]):
+        if isinstance(config, str):
+            self.config = Config(api_key=config)
+        elif isinstance(config, Config):
+            self.config = config
+        else:
+            # Try to get from environment
+            api_key = os.environ.get("SOVANT_API_KEY")
+            if not api_key:
+                raise AuthenticationError("API key is required")
+            self.config = Config(api_key=api_key)
+        
+        # Ensure HTTPS is used for security
+        if not self.config.base_url.startswith("https://"):
+            raise SovantError("API base URL must use HTTPS for security")
+        
+        self.client = httpx.Client(
+            timeout=self.config.timeout,
+            headers=self._get_headers(),
+        )
+    
+    def _get_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.config.api_key}",
+            "Content-Type": "application/json",
+            "X-SDK-Version": "1.0.0",
+            "X-SDK-Language": "python",
+        }
+    
+    def _build_url(self, path: str) -> str:
+        return f"{self.config.base_url}{path}"
+    
+    def _build_query_string(self, params: Dict[str, Any]) -> str:
+        filtered_params = {
+            k: v for k, v in params.items() 
+            if v is not None
+        }
+        
+        # Handle list values
+        processed_params = {}
+        for k, v in filtered_params.items():
+            if isinstance(v, list):
+                # Convert list to comma-separated string
+                processed_params[k] = ",".join(str(item) for item in v)
+            elif isinstance(v, bool):
+                processed_params[k] = str(v).lower()
+            else:
+                processed_params[k] = str(v)
+        
+        return f"?{urlencode(processed_params)}" if processed_params else ""
+    
+    def _handle_response(self, response: httpx.Response) -> Any:
+        if response.status_code >= 200 and response.status_code < 300:
+            try:
+                return response.json()
+            except json.JSONDecodeError:
+                return None
+        
+        # Handle error responses
+        try:
+            error_data = response.json()
+            message = error_data.get("message", f"HTTP {response.status_code}")
+            details = error_data.get("details", {})
+        except json.JSONDecodeError:
+            message = f"HTTP {response.status_code} {response.reason_phrase}"
+            details = {}
+        
+        if response.status_code == 401:
+            raise AuthenticationError(message)
+        elif response.status_code == 404:
+            raise NotFoundError(message)
+        elif response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(
+                message,
+                int(retry_after) if retry_after else None
+            )
+        elif response.status_code in (400, 422):
+            raise ValidationError(message, details.get("errors"))
+        else:
+            raise SovantError(message, response.status_code, details)
+    
+    def request(
+        self,
+        method: str,
+        path: str,
+        data: Optional[Dict[str, Any]] = None,
+        retry_count: int = 0,
+    ) -> Any:
+        url = self._build_url(path)
+        
+        try:
+            response = self.client.request(
+                method,
+                url,
+                json=data if data else None,
+            )
+            return self._handle_response(response)
+        except httpx.TimeoutException:
+            raise NetworkError("Request timeout")
+        except httpx.RequestError as e:
+            if retry_count < self.config.max_retries:
+                # Exponential backoff
+                delay = self.config.retry_delay * (2 ** retry_count)
+                import time
+                time.sleep(delay)
+                return self.request(method, path, data, retry_count + 1)
+            raise NetworkError(str(e))
+    
+    def __del__(self):
+        if hasattr(self, "client"):
+            self.client.close()
+
+
+class AsyncBaseClient:
+    """Base client for asynchronous API requests."""
+    
+    def __init__(self, config: Union[str, Config]):
+        if isinstance(config, str):
+            self.config = Config(api_key=config)
+        elif isinstance(config, Config):
+            self.config = config
+        else:
+            # Try to get from environment
+            api_key = os.environ.get("SOVANT_API_KEY")
+            if not api_key:
+                raise AuthenticationError("API key is required")
+            self.config = Config(api_key=api_key)
+        
+        # Ensure HTTPS is used for security
+        if not self.config.base_url.startswith("https://"):
+            raise SovantError("API base URL must use HTTPS for security")
+        
+        self.client = httpx.AsyncClient(
+            timeout=self.config.timeout,
+            headers=self._get_headers(),
+        )
+    
+    def _get_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.config.api_key}",
+            "Content-Type": "application/json",
+            "X-SDK-Version": "1.0.0",
+            "X-SDK-Language": "python",
+        }
+    
+    def _build_url(self, path: str) -> str:
+        return f"{self.config.base_url}{path}"
+    
+    def _build_query_string(self, params: Dict[str, Any]) -> str:
+        filtered_params = {
+            k: v for k, v in params.items() 
+            if v is not None
+        }
+        
+        # Handle list values
+        processed_params = {}
+        for k, v in filtered_params.items():
+            if isinstance(v, list):
+                # Convert list to comma-separated string
+                processed_params[k] = ",".join(str(item) for item in v)
+            elif isinstance(v, bool):
+                processed_params[k] = str(v).lower()
+            else:
+                processed_params[k] = str(v)
+        
+        return f"?{urlencode(processed_params)}" if processed_params else ""
+    
+    async def _handle_response(self, response: httpx.Response) -> Any:
+        if response.status_code >= 200 and response.status_code < 300:
+            try:
+                return response.json()
+            except json.JSONDecodeError:
+                return None
+        
+        # Handle error responses
+        try:
+            error_data = response.json()
+            message = error_data.get("message", f"HTTP {response.status_code}")
+            details = error_data.get("details", {})
+        except json.JSONDecodeError:
+            message = f"HTTP {response.status_code} {response.reason_phrase}"
+            details = {}
+        
+        if response.status_code == 401:
+            raise AuthenticationError(message)
+        elif response.status_code == 404:
+            raise NotFoundError(message)
+        elif response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(
+                message,
+                int(retry_after) if retry_after else None
+            )
+        elif response.status_code in (400, 422):
+            raise ValidationError(message, details.get("errors"))
+        else:
+            raise SovantError(message, response.status_code, details)
+    
+    async def request(
+        self,
+        method: str,
+        path: str,
+        data: Optional[Dict[str, Any]] = None,
+        retry_count: int = 0,
+    ) -> Any:
+        url = self._build_url(path)
+        
+        try:
+            response = await self.client.request(
+                method,
+                url,
+                json=data if data else None,
+            )
+            return await self._handle_response(response)
+        except httpx.TimeoutException:
+            raise NetworkError("Request timeout")
+        except httpx.RequestError as e:
+            if retry_count < self.config.max_retries:
+                # Exponential backoff
+                delay = self.config.retry_delay * (2 ** retry_count)
+                await asyncio.sleep(delay)
+                return await self.request(method, path, data, retry_count + 1)
+            raise NetworkError(str(e))
+    
+    async def __aenter__(self):
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.client.aclose()

sovant/client.py

@@ -0,0 +1,87 @@
+"""Main client for the Sovant SDK."""
+
+from typing import Any, Dict, Union
+
+from .base_client import AsyncBaseClient, BaseClient
+from .resources import AsyncMemories, AsyncThreads, Memories, Threads
+from .types import Config
+
+
+class SovantClient:
+    """Synchronous client for the Sovant API."""
+    
+    def __init__(self, api_key: Union[str, Config, None] = None):
+        """
+        Initialize the Sovant client.
+        
+        Args:
+            api_key: API key string, Config object, or None (uses env var)
+        """
+        if api_key is None:
+            import os
+            api_key = os.environ.get("SOVANT_API_KEY", "")
+        
+        if isinstance(api_key, str):
+            config = Config(api_key=api_key)
+        else:
+            config = api_key
+        
+        self.memories = Memories(config)
+        self.threads = Threads(config)
+        self._config = config
+    
+    def ping(self) -> Dict[str, str]:
+        """Test API connection."""
+        client = BaseClient(self._config)
+        return client.request("GET", "/health")
+    
+    def get_usage(self) -> Dict[str, Any]:
+        """Get current API usage and quota."""
+        client = BaseClient(self._config)
+        return client.request("GET", "/usage")
+
+
+class AsyncSovantClient:
+    """Asynchronous client for the Sovant API."""
+    
+    def __init__(self, api_key: Union[str, Config, None] = None):
+        """
+        Initialize the async Sovant client.
+        
+        Args:
+            api_key: API key string, Config object, or None (uses env var)
+        """
+        if api_key is None:
+            import os
+            api_key = os.environ.get("SOVANT_API_KEY", "")
+        
+        if isinstance(api_key, str):
+            config = Config(api_key=api_key)
+        else:
+            config = api_key
+        
+        self.memories = AsyncMemories(config)
+        self.threads = AsyncThreads(config)
+        self._config = config
+    
+    async def ping(self) -> Dict[str, str]:
+        """Test API connection."""
+        async with AsyncBaseClient(self._config) as client:
+            return await client.request("GET", "/health")
+    
+    async def get_usage(self) -> Dict[str, Any]:
+        """Get current API usage and quota."""
+        async with AsyncBaseClient(self._config) as client:
+            return await client.request("GET", "/usage")
+    
+    async def __aenter__(self):
+        """Context manager entry."""
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        # Clean up any open connections
+        if hasattr(self.memories, "client"):
+            await self.memories.client.aclose()
+        if hasattr(self.threads, "client"):
+            await self.threads.client.aclose()

sovant/exceptions.py

@@ -0,0 +1,58 @@
+"""Exception classes for the Sovant SDK."""
+
+from typing import Any, Dict, Optional
+
+
+class SovantError(Exception):
+    """Base exception for all Sovant errors."""
+    
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.details = details or {}
+
+
+class AuthenticationError(SovantError):
+    """Raised when authentication fails."""
+    
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(message, 401)
+
+
+class RateLimitError(SovantError):
+    """Raised when rate limit is exceeded."""
+    
+    def __init__(self, message: str = "Rate limit exceeded", retry_after: Optional[int] = None):
+        super().__init__(message, 429)
+        self.retry_after = retry_after
+
+
+class ValidationError(SovantError):
+    """Raised when validation fails."""
+    
+    def __init__(
+        self,
+        message: str = "Validation failed",
+        errors: Optional[Dict[str, list[str]]] = None,
+    ):
+        super().__init__(message, 400)
+        self.errors = errors or {}
+
+
+class NotFoundError(SovantError):
+    """Raised when a resource is not found."""
+    
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message, 404)
+
+
+class NetworkError(SovantError):
+    """Raised when a network error occurs."""
+    
+    def __init__(self, message: str = "Network request failed"):
+        super().__init__(message)

sovant/resources/__init__.py

@@ -0,0 +1,6 @@
+"""Resources for the Sovant SDK."""
+
+from .memories import AsyncMemories, Memories
+from .threads import AsyncThreads, Threads
+
+__all__ = ["Memories", "AsyncMemories", "Threads", "AsyncThreads"]