creativai 0.1.0__py3-none-any.whl

creativai/__init__.py

@@ -0,0 +1,63 @@
+"""
+CreativAI — Official Python SDK for the CreativAI Video Intelligence Platform.
+
+Quickstart::
+
+    import creativai
+
+    client = creativai.CreativAI(api_key="sk_live_...")
+
+    # Or use the environment variable CREATIVAI_API_KEY:
+    client = creativai.CreativAI()
+
+    # Health check
+    client.health.check()
+
+    # Account info
+    info = client.users.get_users_info()
+    print(info["credits"])
+
+    # Create a collection and upload a video
+    collection = client.collections.create("my-collection")
+    cid = collection["collection_id"]
+    client.media.upload_file(cid, "/path/to/video.mp4")
+
+    # Start indexing
+    job = client.indexing.start(cid)
+
+    # Search
+    results = client.search.query(cid, "person near forklift")
+"""
+
+from .client import CreativAI
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    CreativAIError,
+    InsufficientCreditsError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    StreamingError,
+    TimeoutError,
+    ValidationError,
+)
+
+__all__ = [
+    "CreativAI",
+    # Exceptions
+    "CreativAIError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "InsufficientCreditsError",
+    "ValidationError",
+    "ServerError",
+    "TimeoutError",
+    "StreamingError",
+]
+
+__version__ = "0.1.0"

creativai/_http.py

@@ -0,0 +1,208 @@
+"""
+CreativAI Python SDK — internal HTTP layer
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Generator, Iterator
+
+import httpx
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    StreamingError,
+    ValidationError,
+)
+
+_DEFAULT_BASE_URL = "https://creativai-apis.com"
+_DEFAULT_TIMEOUT = 120.0  # seconds
+
+
+class _HTTPClient:
+    """Thin wrapper around httpx that handles auth, error parsing, and SSE."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        try:
+            from importlib.metadata import version as _pkg_version
+            _sdk_version = _pkg_version("creativai")
+        except Exception:
+            _sdk_version = "0.1.0"
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "X-API-Key": api_key,
+                "Accept": "application/json",
+                "User-Agent": f"creativai-python/{_sdk_version}",
+            },
+            timeout=timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Public request helpers
+    # ------------------------------------------------------------------
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> Any:
+        response = self._client.get(path, params=params)
+        return self._parse(response)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        data: dict[str, Any] | None = None,
+        files: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = self._client.post(path, json=json, data=data, files=files, params=params)
+        return self._parse(response)
+
+    def patch(self, path: str, *, json: Any = None) -> Any:
+        response = self._client.patch(path, json=json)
+        return self._parse(response)
+
+    def delete(self, path: str, *, json: Any = None, params: dict[str, Any] | None = None) -> Any:
+        response = self._client.delete(path, json=json, params=params)
+        return self._parse(response)
+
+    def put(self, path: str, *, json: Any = None, content: bytes | None = None, headers: dict[str, str] | None = None) -> Any:
+        """Used for presigned S3 PUT uploads — does NOT send API key."""
+        extra_headers = headers or {}
+        response = httpx.put(path, json=json, content=content, headers=extra_headers, timeout=_DEFAULT_TIMEOUT)
+        if response.status_code >= 400:
+            raise APIError(
+                f"S3 upload failed: HTTP {response.status_code}",
+                status_code=response.status_code,
+            )
+        return response
+
+    # ------------------------------------------------------------------
+    # SSE streaming
+    # ------------------------------------------------------------------
+
+    def stream_post(
+        self, path: str, *, json: Any = None
+    ) -> Iterator[dict[str, str]]:
+        """
+        Opens an SSE connection via POST and yields raw SSE event dicts
+        with keys ``event`` and ``data``.
+
+        Usage::
+
+            for event in client.stream_post("/api/v2/agentic-chat/sessions/xxx/chat", json={...}):
+                print(event["event"], event["data"])
+        """
+        try:
+            from httpx_sse import connect_sse
+        except ImportError as exc:
+            raise StreamingError(
+                "httpx-sse is required for streaming. "
+                "Install it with: pip install httpx-sse"
+            ) from exc
+
+        headers = {
+            "X-API-Key": self._api_key,
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+            "User-Agent": "creativai-python/0.1.0",
+        }
+        try:
+            with httpx.Client(base_url=self._base_url, timeout=None) as client:
+                with connect_sse(client, "POST", path, json=json, headers=headers) as event_source:
+                    for sse in event_source.iter_sse():
+                        yield {"event": sse.event, "data": sse.data}
+        except httpx.HTTPStatusError as exc:
+            self._raise_for_status(exc.response)
+        except httpx.TimeoutException as exc:
+            from .exceptions import TimeoutError as _TimeoutError
+            raise _TimeoutError(str(exc)) from exc
+
+    def stream_get(self, path: str, *, params: dict[str, Any] | None = None) -> Iterator[dict[str, str]]:
+        """Opens an SSE connection via GET and yields raw SSE event dicts."""
+        try:
+            from httpx_sse import connect_sse
+        except ImportError as exc:
+            raise StreamingError(
+                "httpx-sse is required for streaming. "
+                "Install it with: pip install httpx-sse"
+            ) from exc
+
+        headers = {
+            "X-API-Key": self._api_key,
+            "Accept": "text/event-stream",
+            "User-Agent": "creativai-python/0.1.0",
+        }
+        try:
+            with httpx.Client(base_url=self._base_url, timeout=None) as client:
+                with connect_sse(client, "GET", path, params=params, headers=headers) as event_source:
+                    for sse in event_source.iter_sse():
+                        yield {"event": sse.event, "data": sse.data}
+        except httpx.HTTPStatusError as exc:
+            self._raise_for_status(exc.response)
+        except httpx.TimeoutException as exc:
+            from .exceptions import TimeoutError as _TimeoutError
+            raise _TimeoutError(str(exc)) from exc
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _parse(self, response: httpx.Response) -> Any:
+        if response.status_code >= 400:
+            self._raise_for_status(response)
+        try:
+            body = response.json()
+        except Exception:
+            return response.content
+        # Unwrap the standard {"success": true, "data": ..., "error": ...} envelope
+        if isinstance(body, dict) and "data" in body:
+            return body["data"]
+        return body
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        status = response.status_code
+        try:
+            body = response.json()
+            err = body.get("error") or {}
+            message = err.get("message") or body.get("detail") or response.text
+            code = err.get("code")
+            details = err.get("details")
+        except Exception:
+            message = response.text
+            code = None
+            details = None
+
+        exc_map = {
+            401: AuthenticationError,
+            402: InsufficientCreditsError,
+            403: PermissionError,
+            404: NotFoundError,
+            422: ValidationError,
+            429: RateLimitError,
+        }
+        cls = exc_map.get(status) or (ServerError if status >= 500 else ValidationError if status == 400 else APIError)
+        raise cls(message, status_code=status, code=code, details=details)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "_HTTPClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

creativai/client.py

@@ -0,0 +1,161 @@
+"""
+CreativAI Python SDK — Main client
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ._http import _HTTPClient, _DEFAULT_BASE_URL, _DEFAULT_TIMEOUT
+from .resources import (
+    AgenticChat,
+    Chat,
+    Collections,
+    DataPlates,
+    Health,
+    Indexing,
+    Invoices,
+    Jobs,
+    KnowledgeExtraction,
+    LiveStream,
+    Media,
+    OnlineSearch,
+    Organizations,
+    Projects,
+    Search,
+    Sharing,
+    SubPlates,
+    Subscriptions,
+    Tasks,
+    Transactions,
+    Transfers,
+    UploadIntegrations,
+    Uploads,
+    Users,
+    YouTubeSearch,
+)
+
+
+class CreativAI:
+    """The main entry point for the CreativAI Python SDK.
+
+    Instantiate with your API key (or set the ``CREATIVAI_API_KEY`` environment
+    variable) and start using the namespaced resource clients.
+
+    Example::
+
+        import creativai
+
+        client = creativai.CreativAI(api_key="sk_live_...")
+
+        # Create a collection
+        collection = client.collections.create("my-videos")
+        cid = collection["collection_id"]
+
+        # Upload a local file
+        client.media.upload_file(cid, "clip.mp4")
+
+        # Index it
+        job = client.indexing.start(cid)
+        print(job["indexing_id"])
+
+        # Search
+        results = client.search.query(cid, "person walking near forklift")
+
+        # Agentic chat
+        session = client.agentic_chat.create_session(cid)
+        for event in client.agentic_chat.chat(session["session_id"], "What are the most common activities?"):
+            if event["event"] == "answer":
+                print(event["data"].get("text", ""))
+
+    Args:
+        api_key: Your CreativAI API key (``sk_live_...``). Falls back to the
+            ``CREATIVAI_API_KEY`` environment variable.
+        base_url: Override the default API base URL.
+        timeout: Request timeout in seconds (default 120).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("CREATIVAI_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "An API key is required. Pass api_key= or set the CREATIVAI_API_KEY "
+                "environment variable. Keys begin with 'sk_live_'."
+            )
+        self._http = _HTTPClient(resolved_key, base_url=base_url, timeout=timeout)
+
+        # Resource clients — each maps to a logical section of the API
+        self.health = Health(self._http)
+        self.organizations = Organizations(self._http)
+        self.projects = Projects(self._http)
+        self.collections = Collections(self._http)
+        self.media = Media(self._http)
+        self.uploads = Uploads(self._http)
+        self.transfers = Transfers(self._http)
+        self.indexing = Indexing(self._http)
+        self.search = Search(self._http)
+        self.data_plates = DataPlates(self._http)
+        self.sub_plates = SubPlates(self._http)
+        self.knowledge_extraction = KnowledgeExtraction(self._http)
+        self.chat = Chat(self._http)
+        self.agentic_chat = AgenticChat(self._http)
+        self.jobs = Jobs(self._http)
+        self.sharing = Sharing(self._http)
+        self.tasks = Tasks(self._http)
+        self.live_stream = LiveStream(self._http)
+        self.online_search = OnlineSearch(self._http)
+        self.youtube_search = YouTubeSearch(self._http)
+        self.transactions = Transactions(self._http)
+        self.users = Users(self._http)
+        self.subscriptions = Subscriptions(self._http)
+        self.invoices = Invoices(self._http)
+        self.upload_integrations = UploadIntegrations(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def as_mcp_server(self) -> Any:
+        """Return a FastMCP server instance pre-wired to this client.
+
+        Requires the ``creativai-mcp`` package to be installed::
+
+            pip install creativai-mcp
+
+        Example::
+
+            import creativai, uvicorn
+            from starlette.applications import Starlette
+
+            client = creativai.CreativAI()
+            mcp_server = client.as_mcp_server()
+            # Run stdio (for Claude Desktop / Cursor):
+            mcp_server.run(transport="stdio")
+            # Or mount as ASGI for HTTP/SSE:
+            app = mcp_server.sse_app()
+            uvicorn.run(app, port=8090)
+        """
+        try:
+            from creativai_mcp.server import build_server  # type: ignore[import]
+        except ImportError as exc:
+            raise ImportError(
+                "The 'creativai-mcp' package is required to use as_mcp_server(). "
+                "Install it with: pip install creativai-mcp"
+            ) from exc
+        return build_server(api_key=self._http._api_key)
+
+    def __enter__(self) -> "CreativAI":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"CreativAI(base_url={self._http._base_url!r})"

creativai/exceptions.py

@@ -0,0 +1,78 @@
+"""
+CreativAI Python SDK — exceptions
+"""
+
+from __future__ import annotations
+from typing import Any
+
+
+class CreativAIError(Exception):
+    """Base exception for all CreativAI SDK errors."""
+
+    def __init__(self, message: str, *, code: str | None = None, details: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={self.message!r}, code={self.code!r})"
+
+
+class APIError(CreativAIError):
+    """Raised when the API returns an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message, code=code, details=details)
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"status_code={self.status_code}, "
+            f"message={self.message!r}, "
+            f"code={self.code!r})"
+        )
+
+
+class AuthenticationError(APIError):
+    """Raised for 401 Unauthorized — invalid or missing API key."""
+
+
+class PermissionError(APIError):
+    """Raised for 403 Forbidden — caller lacks permission."""
+
+
+class NotFoundError(APIError):
+    """Raised for 404 Not Found."""
+
+
+class RateLimitError(APIError):
+    """Raised for 429 Too Many Requests."""
+
+
+class InsufficientCreditsError(APIError):
+    """Raised for 402 Payment Required — not enough credits."""
+
+
+class ValidationError(APIError):
+    """Raised for 400/422 validation failures."""
+
+
+class ServerError(APIError):
+    """Raised for 5xx server-side errors."""
+
+
+class TimeoutError(CreativAIError):
+    """Raised when a request times out."""
+
+
+class StreamingError(CreativAIError):
+    """Raised when an SSE streaming connection fails."""

creativai/resources/__init__.py

@@ -0,0 +1,53 @@
+from .health import Health
+from .organizations import Organizations
+from .projects import Projects
+from .collections import Collections
+from .media import Media
+from .uploads import Uploads
+from .transfers import Transfers
+from .indexing import Indexing
+from .search import Search
+from .data_plates import DataPlates
+from .sub_plates import SubPlates
+from .knowledge_extraction import KnowledgeExtraction
+from .chat import Chat
+from .agentic_chat import AgenticChat
+from .jobs import Jobs
+from .sharing import Sharing
+from .tasks import Tasks
+from .live_stream import LiveStream
+from .online_search import OnlineSearch
+from .youtube_search import YouTubeSearch
+from .transactions import Transactions
+from .users import Users
+from .subscriptions import Subscriptions
+from .invoices import Invoices
+from .upload_integrations import UploadIntegrations
+
+__all__ = [
+    "Health",
+    "Organizations",
+    "Projects",
+    "Collections",
+    "Media",
+    "Uploads",
+    "Transfers",
+    "Indexing",
+    "Search",
+    "DataPlates",
+    "SubPlates",
+    "KnowledgeExtraction",
+    "Chat",
+    "AgenticChat",
+    "Jobs",
+    "Sharing",
+    "Tasks",
+    "LiveStream",
+    "OnlineSearch",
+    "YouTubeSearch",
+    "Transactions",
+    "Users",
+    "Subscriptions",
+    "Invoices",
+    "UploadIntegrations",
+]

creativai/resources/agentic_chat.py

@@ -0,0 +1,122 @@
+"""
+CreativAI SDK — Agentic Chat resource (SSE streaming)
+"""
+
+from __future__ import annotations
+import json
+from typing import Any, Iterator
+from .._http import _HTTPClient
+
+_PREFIX = "/api/v2/agentic-chat"
+
+
+class AgenticChat:
+    def __init__(self, http: _HTTPClient) -> None:
+        self._http = http
+
+    # ------------------------------------------------------------------
+    # Session management
+    # ------------------------------------------------------------------
+
+    def create_session(self, collection_id: str, *, title: str | None = None, **kwargs: Any) -> Any:
+        """POST /api/v2/agentic-chat/sessions — Create a new agentic chat session (HTTP 201)."""
+        body: dict[str, Any] = {"collection_id": collection_id, **kwargs}
+        if title is not None:
+            body["title"] = title
+        return self._http.post(f"{_PREFIX}/sessions", json=body)
+
+    def list_sessions(self, *, collection_id: str | None = None, limit: int = 20, **kwargs: Any) -> Any:
+        """GET /api/v2/agentic-chat/sessions — List sessions, optionally filtered by collection."""
+        params: dict[str, Any] = {"limit": limit, **kwargs}
+        if collection_id is not None:
+            params["collection_id"] = collection_id
+        return self._http.get(f"{_PREFIX}/sessions", params=params)
+
+    def get_session(self, session_id: str) -> Any:
+        """GET /api/v2/agentic-chat/sessions/{session_id} — Get session details."""
+        return self._http.get(f"{_PREFIX}/sessions/{session_id}")
+
+    def delete_session(self, session_id: str) -> Any:
+        """DELETE /api/v2/agentic-chat/sessions/{session_id} — Delete a session."""
+        return self._http.delete(f"{_PREFIX}/sessions/{session_id}")
+
+    def get_messages(self, session_id: str) -> Any:
+        """GET /api/v2/agentic-chat/sessions/{session_id}/messages — Get full message history and session state."""
+        return self._http.get(f"{_PREFIX}/sessions/{session_id}/messages")
+
+    def get_status(self, session_id: str) -> Any:
+        """GET /api/v2/agentic-chat/sessions/{session_id}/status — Check current agent status."""
+        return self._http.get(f"{_PREFIX}/sessions/{session_id}/status")
+
+    def get_events(self, session_id: str, **params: Any) -> Any:
+        """GET /api/v2/agentic-chat/sessions/{session_id}/events — Poll new agent events since last call."""
+        return self._http.get(f"{_PREFIX}/sessions/{session_id}/events", params=params or None)
+
+    def stop(self, session_id: str, **kwargs: Any) -> Any:
+        """POST /api/v2/agentic-chat/sessions/{session_id}/stop — Stop the agent at the current step."""
+        return self._http.post(f"{_PREFIX}/sessions/{session_id}/stop", json=kwargs or None)
+
+    def resume(self, session_id: str, **kwargs: Any) -> Any:
+        """POST /api/v2/agentic-chat/sessions/{session_id}/resume — Resume an interrupted agent."""
+        return self._http.post(f"{_PREFIX}/sessions/{session_id}/resume", json=kwargs or None)
+
+    def search_feedback(self, session_id: str, feedback: Any, **kwargs: Any) -> Any:
+        """POST .../search-feedback — Respond to a ``search_feedback_required`` interrupt."""
+        return self._http.post(
+            f"{_PREFIX}/sessions/{session_id}/search-feedback",
+            json={"feedback": feedback, **kwargs},
+        )
+
+    # ------------------------------------------------------------------
+    # Streaming chat
+    # ------------------------------------------------------------------
+
+    def chat(
+        self,
+        session_id: str,
+        message: str,
+        **kwargs: Any,
+    ) -> Iterator[dict[str, Any]]:
+        """POST .../chat — Send a message and stream SSE events from the agent.
+
+        Yields parsed event dicts with at minimum ``event`` (event type) and
+        ``data`` (parsed JSON payload) keys.
+
+        SSE event types (non-exhaustive):
+            ``thinking``, ``search``, ``create_plate``, ``extract_knowledge``,
+            ``web_search``, ``youtube_search``, ``synthesize``,
+            ``answer``, ``done``, ``error``, ``search_feedback_required``
+
+        Example::
+
+            for event in client.agentic_chat.chat(session_id, "What activities are common?"):
+                if event["event"] == "answer":
+                    print(event["data"]["text"])
+
+        Args:
+            session_id: Active session identifier.
+            message: User message text.
+        """
+        body: dict[str, Any] = {"message": message, **kwargs}
+        for raw in self._http.stream_post(f"{_PREFIX}/sessions/{session_id}/chat", json=body):
+            event_type = raw["event"]
+            raw_data = raw["data"]
+            try:
+                data = json.loads(raw_data) if raw_data else {}
+            except json.JSONDecodeError:
+                data = {"text": raw_data}
+            yield {"event": event_type, "data": data}
+
+    def subscribe_stream(self, session_id: str) -> Iterator[dict[str, Any]]:
+        """GET .../stream — Subscribe to a running agent's SSE stream (reconnect-safe).
+
+        Yields the same parsed event dicts as :meth:`chat`.
+        """
+        for raw in self._http.stream_get(f"{_PREFIX}/sessions/{session_id}/stream"):
+            event_type = raw["event"]
+            raw_data = raw["data"]
+            try:
+                data = json.loads(raw_data) if raw_data else {}
+            except json.JSONDecodeError:
+                data = {"text": raw_data}
+            yield {"event": event_type, "data": data}