ofspectrum 1.1.1__py3-none-any.whl

ofspectrum/__init__.py

@@ -0,0 +1,91 @@
+"""
+OfSpectrum Python SDK
+
+Audio watermarking and AI detection API client.
+
+Example:
+    from ofspectrum import OfSpectrum
+
+    client = OfSpectrum(api_key="your_api_key")
+
+    # Create a token
+    token = client.tokens.create(name="My Token", token_type="creator")
+
+    # Encode watermark
+    result = client.audio.encode(
+        audio="input.mp3",
+        token_id=token.id,
+        output_path="watermarked.mp3"
+    )
+    print(f"Encoded {result.audio_duration}s of audio")
+
+    # Decode watermark
+    decode = client.audio.decode("suspect.mp3")
+    if decode.watermarked:
+        print(f"Found watermark: {decode.token_id}")
+
+    # Check quota
+    quota = client.quotas.get_encode_quota()
+    print(f"Remaining: {quota.remaining}/{quota.quota_limit}")
+"""
+
+__version__ = "1.0.0"
+__author__ = "OfSpectrum"
+
+from .client import OfSpectrum, AsyncOfSpectrum
+from .exceptions import (
+    OfSpectrumError,
+    AuthenticationError,
+    RateLimitError,
+    QuotaExceededError,
+    ResourceNotFoundError,
+    ValidationError,
+    WatermarkExistsError,
+    TimeoutError,
+    ServiceUnavailableError,
+    NetworkError,
+)
+from .models import (
+    Token,
+    TokenCreateParams,
+    TokenUpdateParams,
+    Notebook,
+    NotebookMedia,
+    NotebookCreateParams,
+    EncodeResult,
+    DecodeResult,
+    Quota,
+    QuotaList,
+)
+from .utils import RetryConfig, with_retry
+
+__all__ = [
+    # Client
+    "OfSpectrum",
+    "AsyncOfSpectrum",
+    # Exceptions
+    "OfSpectrumError",
+    "AuthenticationError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "ResourceNotFoundError",
+    "ValidationError",
+    "WatermarkExistsError",
+    "TimeoutError",
+    "ServiceUnavailableError",
+    "NetworkError",
+    # Models
+    "Token",
+    "TokenCreateParams",
+    "TokenUpdateParams",
+    "Notebook",
+    "NotebookMedia",
+    "NotebookCreateParams",
+    "EncodeResult",
+    "DecodeResult",
+    "Quota",
+    "QuotaList",
+    # Utils
+    "RetryConfig",
+    "with_retry",
+]

ofspectrum/client.py

@@ -0,0 +1,314 @@
+"""
+OfSpectrum API Client
+
+Main entry point for the SDK.
+"""
+
+from typing import Optional, Dict, Any
+import httpx
+
+from .resources import (
+    TokensResource,
+    NotebooksResource,
+    AudioResource,
+    QuotasResource,
+    # WebhooksResource,  # Not yet available
+)
+from .exceptions import (
+    OfSpectrumError,
+    AuthenticationError,
+    NetworkError,
+    raise_for_error,
+)
+
+
+class OfSpectrum:
+    """
+    Synchronous OfSpectrum API client.
+
+    Example:
+        from ofspectrum import OfSpectrum
+
+        client = OfSpectrum(api_key="your_api_key")
+
+        # List tokens
+        tokens = client.tokens.list()
+
+        # Encode watermark
+        result = client.audio.encode(
+            audio="input.mp3",
+            token_id=tokens[0].id,
+            output_path="watermarked.mp3"
+        )
+
+        # Check quota
+        quota = client.quotas.get_encode_quota()
+        print(f"Remaining: {quota.remaining}")
+    """
+
+    DEFAULT_BASE_URL = "https://api.ofspectrum.com/api/v1"
+    DEFAULT_TIMEOUT = 120.0
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        """
+        Initialize the OfSpectrum client.
+
+        Args:
+            api_key: Your OfSpectrum API key (64-character hex string)
+            base_url: Optional custom API base URL
+            timeout: Request timeout in seconds (default 120)
+        """
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+
+        # Initialize HTTP client
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=httpx.Timeout(timeout),
+            headers=self._default_headers(),
+        )
+
+        # Initialize resources
+        self.tokens = TokensResource(self)
+        self.notebooks = NotebooksResource(self)
+        self.audio = AudioResource(self)
+        self.quotas = QuotasResource(self)
+        # self.webhooks = WebhooksResource(self)  # Not yet available
+
+    def _default_headers(self) -> Dict[str, str]:
+        """Get default request headers"""
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": "OfSpectrum-Python-SDK/1.0.0",
+            "Accept": "application/json",
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> httpx.Response:
+        """
+        Make an HTTP request to the API.
+
+        Args:
+            method: HTTP method
+            path: API path
+            params: Query parameters
+            json: JSON body
+            data: Form data
+            files: Files to upload
+            timeout: Optional request timeout
+
+        Returns:
+            httpx.Response
+
+        Raises:
+            AuthenticationError: If API key is invalid
+            NetworkError: If network error occurs
+            OfSpectrumError: For other API errors
+        """
+        url = path if path.startswith("/") else f"/{path}"
+
+        request_kwargs = {
+            "method": method,
+            "url": url,
+        }
+
+        if params:
+            request_kwargs["params"] = params
+
+        if json:
+            request_kwargs["json"] = json
+
+        if data:
+            request_kwargs["data"] = data
+
+        if files:
+            request_kwargs["files"] = files
+
+        if timeout:
+            request_kwargs["timeout"] = timeout
+
+        try:
+            response = self._client.request(**request_kwargs)
+
+            # Check for authentication errors
+            if response.status_code == 401:
+                raise AuthenticationError(
+                    message="Invalid or expired API key",
+                    status_code=401,
+                )
+
+            return response
+
+        except httpx.TimeoutException as e:
+            raise NetworkError(f"Request timed out: {e}")
+        except httpx.ConnectError as e:
+            raise NetworkError(f"Connection failed: {e}")
+        except httpx.RequestError as e:
+            raise NetworkError(f"Network error: {e}")
+
+    def close(self):
+        """Close the HTTP client"""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+
+class AsyncOfSpectrum:
+    """
+    Asynchronous OfSpectrum API client.
+
+    Example:
+        from ofspectrum import AsyncOfSpectrum
+
+        async with AsyncOfSpectrum(api_key="your_api_key") as client:
+            tokens = await client.tokens.list()
+    """
+
+    DEFAULT_BASE_URL = "https://api.ofspectrum.com/api/v1"
+    DEFAULT_TIMEOUT = 120.0
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        """
+        Initialize the async OfSpectrum client.
+
+        Args:
+            api_key: Your OfSpectrum API key
+            base_url: Optional custom API base URL
+            timeout: Request timeout in seconds
+        """
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._client: Optional[httpx.AsyncClient] = None
+
+        # Resources will be initialized when client is opened
+        self.tokens: Optional[TokensResource] = None
+        self.notebooks: Optional[NotebooksResource] = None
+        self.audio: Optional[AudioResource] = None
+        self.quotas: Optional[QuotasResource] = None
+        # self.webhooks: Optional[WebhooksResource] = None  # Not yet available
+
+    def _default_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": "OfSpectrum-Python-SDK/1.0.0",
+            "Accept": "application/json",
+        }
+
+    async def __aenter__(self):
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=httpx.Timeout(self._timeout),
+            headers=self._default_headers(),
+        )
+
+        # Create a sync client wrapper for resources
+        # Note: For true async, resources would need async versions
+        self.tokens = TokensResource(self)
+        self.notebooks = NotebooksResource(self)
+        self.audio = AudioResource(self)
+        self.quotas = QuotasResource(self)
+        # self.webhooks = WebhooksResource(self)  # Not yet available
+
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._client:
+            await self._client.aclose()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        **kwargs
+    ) -> httpx.Response:
+        """
+        Sync request wrapper for resource compatibility.
+        For truly async operations, use the async client methods directly.
+        """
+        # For now, use a sync approach within async context
+        # A full async implementation would require async resource methods
+        import asyncio
+
+        async def _async_request():
+            if not self._client:
+                raise RuntimeError("Client not initialized. Use 'async with' context.")
+
+            url = path if path.startswith("/") else f"/{path}"
+            kwargs["url"] = url
+            kwargs["method"] = method
+
+            try:
+                response = await self._client.request(**kwargs)
+                if response.status_code == 401:
+                    raise AuthenticationError(
+                        message="Invalid or expired API key",
+                        status_code=401,
+                    )
+                return response
+            except httpx.TimeoutException as e:
+                raise NetworkError(f"Request timed out: {e}")
+            except httpx.RequestError as e:
+                raise NetworkError(f"Network error: {e}")
+
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                # We're in an async context, can't use run_until_complete
+                # Fall back to sync client for now
+                import warnings
+                warnings.warn(
+                    "AsyncOfSpectrum resource methods are currently sync. "
+                    "Use await client._async_request() for true async."
+                )
+                with httpx.Client(
+                    base_url=self._base_url,
+                    timeout=httpx.Timeout(self._timeout),
+                    headers=self._default_headers(),
+                ) as sync_client:
+                    url = path if path.startswith("/") else f"/{path}"
+                    kwargs["url"] = url
+                    kwargs["method"] = method
+                    return sync_client.request(**kwargs)
+            else:
+                return loop.run_until_complete(_async_request())
+        except RuntimeError:
+            # No event loop, use sync
+            with httpx.Client(
+                base_url=self._base_url,
+                timeout=httpx.Timeout(self._timeout),
+                headers=self._default_headers(),
+            ) as sync_client:
+                url = path if path.startswith("/") else f"/{path}"
+                kwargs["url"] = url
+                kwargs["method"] = method
+                return sync_client.request(**kwargs)

ofspectrum/exceptions.py

@@ -0,0 +1,247 @@
+"""
+OfSpectrum SDK Exceptions
+
+All exceptions inherit from OfSpectrumError for easy catching.
+"""
+
+from typing import Optional, Dict, Any
+
+
+class OfSpectrumError(Exception):
+    """Base exception for all OfSpectrum SDK errors"""
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        status_code: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        if self.code:
+            return f"[{self.code}] {self.message}"
+        return self.message
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={self.message!r}, code={self.code!r})"
+
+
+class AuthenticationError(OfSpectrumError):
+    """Raised when authentication fails (invalid API key, expired token, etc.)"""
+
+    def __init__(self, message: str = "Authentication failed", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class RateLimitError(OfSpectrumError):
+    """Raised when rate limit is exceeded"""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[int] = None,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.retry_after:
+            return f"{base} (retry after {self.retry_after}s)"
+        return base
+
+
+class QuotaExceededError(OfSpectrumError):
+    """Raised when service quota is exceeded"""
+
+    def __init__(
+        self,
+        message: str = "Quota exceeded",
+        service: Optional[str] = None,
+        remaining: int = 0,
+        reset_at: Optional[str] = None,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.service = service
+        self.remaining = remaining
+        self.reset_at = reset_at
+
+
+class ResourceNotFoundError(OfSpectrumError):
+    """Raised when a requested resource is not found"""
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        resource_type: Optional[str] = None,
+        resource_id: Optional[str] = None,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.resource_type = resource_type
+        self.resource_id = resource_id
+
+
+class ValidationError(OfSpectrumError):
+    """Raised when request validation fails"""
+
+    def __init__(
+        self,
+        message: str = "Validation error",
+        field: Optional[str] = None,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.field = field
+
+
+class WatermarkExistsError(OfSpectrumError):
+    """Raised when trying to encode a watermark on already watermarked audio"""
+
+    def __init__(self, message: str = "Audio already contains watermark", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class TimeoutError(OfSpectrumError):
+    """Raised when a request times out"""
+
+    def __init__(self, message: str = "Request timed out", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class ServiceUnavailableError(OfSpectrumError):
+    """Raised when the service is temporarily unavailable"""
+
+    def __init__(
+        self,
+        message: str = "Service temporarily unavailable",
+        retry_after: Optional[int] = None,
+        **kwargs
+    ):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class NetworkError(OfSpectrumError):
+    """Raised when a network error occurs"""
+
+    def __init__(self, message: str = "Network error", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+# Mapping from API error codes to exception classes
+ERROR_CODE_MAP = {
+    "AUTH_1001": AuthenticationError,
+    "AUTH_1002": AuthenticationError,
+    "AUTH_1003": AuthenticationError,
+    "AUTH_1004": AuthenticationError,
+    "AUTH_1005": RateLimitError,
+    "AUTH_1006": AuthenticationError,
+    "AUTH_1007": AuthenticationError,
+    "RES_2001": ResourceNotFoundError,
+    "RES_2002": OfSpectrumError,  # Forbidden
+    "RES_2003": OfSpectrumError,  # Conflict
+    "RES_2004": OfSpectrumError,  # Already exists
+    "QUOTA_3001": QuotaExceededError,
+    "QUOTA_3002": QuotaExceededError,
+    "QUOTA_3003": QuotaExceededError,
+    "QUOTA_3004": QuotaExceededError,
+    "PROC_4001": TimeoutError,
+    "PROC_4002": ValidationError,
+    "PROC_4003": WatermarkExistsError,
+    "PROC_4004": ServiceUnavailableError,
+    "PROC_4005": ValidationError,
+    "PROC_4006": ValidationError,
+    "SYS_5001": OfSpectrumError,
+    "SYS_5002": OfSpectrumError,
+    "SYS_5003": OfSpectrumError,
+    "SYS_5004": ServiceUnavailableError,
+}
+
+
+def raise_for_error(response_data, status_code: int):
+    """
+    Parse API error response and raise appropriate exception.
+
+    Args:
+        response_data: The JSON response from the API (dict or list)
+        status_code: HTTP status code
+
+    Raises:
+        OfSpectrumError: Appropriate exception based on error code
+    """
+    # If response is a list (e.g., tokens.list returns a list), it's not an error
+    if not isinstance(response_data, dict):
+        return
+
+    # Check for direct error format: {"error": "ErrorCode", "message": "..."}
+    # This is used by tokens_router and other legacy endpoints
+    if "error" in response_data and isinstance(response_data.get("error"), str):
+        error_code = response_data.get("error")
+        message = response_data.get("message", error_code)
+
+        # Map common error codes
+        if error_code == "QuotaExceeded":
+            raise QuotaExceededError(message=message, status_code=status_code or 429)
+        elif error_code == "QuotaMissing" or error_code == "QuotaCheckFailed":
+            raise QuotaExceededError(message=message, status_code=status_code or 500)
+        elif error_code == "Unauthorized":
+            raise AuthenticationError(message=message, status_code=status_code or 403)
+        elif error_code == "DuplicateName":
+            raise ValidationError(message=message, status_code=status_code or 400)
+        elif error_code == "Missing required fields" or error_code == "InvalidField":
+            raise ValidationError(message=message, status_code=status_code or 400)
+        elif error_code == "UnableToGenerate":
+            raise OfSpectrumError(message=message, code=error_code, status_code=status_code or 500)
+        else:
+            raise OfSpectrumError(message=message, code=error_code, status_code=status_code or 500)
+
+    if response_data.get("status") != "error":
+        # Also check for FastAPI validation errors (detail field)
+        if "detail" in response_data and status_code >= 400:
+            detail = response_data.get("detail")
+            if isinstance(detail, str):
+                raise OfSpectrumError(message=detail, status_code=status_code)
+            elif isinstance(detail, list):
+                # FastAPI validation error format
+                messages = [f"{d.get('loc', ['?'])[-1]}: {d.get('msg', '?')}" for d in detail]
+                raise ValidationError(message="; ".join(messages), status_code=status_code)
+        return
+
+    error = response_data.get("error", {})
+    code = error.get("code")
+    message = error.get("message", "Unknown error")
+    details = error.get("details", {})
+
+    # Get appropriate exception class
+    exc_class = ERROR_CODE_MAP.get(code, OfSpectrumError)
+
+    # Build kwargs based on exception type
+    kwargs = {
+        "message": message,
+        "code": code,
+        "status_code": status_code,
+        "details": details,
+    }
+
+    if exc_class == RateLimitError:
+        kwargs["retry_after"] = details.get("retry_after")
+    elif exc_class == QuotaExceededError:
+        kwargs["service"] = details.get("service")
+        kwargs["remaining"] = details.get("remaining", 0)
+        kwargs["reset_at"] = details.get("reset_at")
+    elif exc_class == ResourceNotFoundError:
+        kwargs["resource_type"] = details.get("resource_type")
+        kwargs["resource_id"] = details.get("resource_id")
+    elif exc_class == ValidationError:
+        kwargs["field"] = details.get("field")
+
+    raise exc_class(**kwargs)

ofspectrum/models/__init__.py

@@ -0,0 +1,21 @@
+"""
+OfSpectrum SDK Data Models
+"""
+
+from .token import Token, TokenCreateParams, TokenUpdateParams
+from .notebook import Notebook, NotebookMedia, NotebookCreateParams
+from .audio import EncodeResult, DecodeResult
+from .quota import Quota, QuotaList
+
+__all__ = [
+    "Token",
+    "TokenCreateParams",
+    "TokenUpdateParams",
+    "Notebook",
+    "NotebookMedia",
+    "NotebookCreateParams",
+    "EncodeResult",
+    "DecodeResult",
+    "Quota",
+    "QuotaList",
+]