creacortex 0.1.0__py3-none-any.whl

creacortex/__init__.py

@@ -0,0 +1,39 @@
+"""Creacortex — Python client for the video-creative attention-analysis API.
+
+    from creacortex import Client
+
+    with Client("ace_...") as cx:
+        run = cx.analyze("ad.mp4", with_audio=True)   # upload + run + wait
+        cx.get_report(run.run_id, "diagnose")          # PDF bytes
+"""
+from .client import DEFAULT_BASE_URL, AsyncClient, Client
+from .errors import (
+    ApiError,
+    AuthError,
+    CreacortexError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    RunFailedError,
+    WaitTimeout,
+)
+from .models import Account, Run, RunListItem
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Client",
+    "AsyncClient",
+    "Run",
+    "RunListItem",
+    "Account",
+    "CreacortexError",
+    "ApiError",
+    "AuthError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "NotFoundError",
+    "RunFailedError",
+    "WaitTimeout",
+]

creacortex/client.py

@@ -0,0 +1,213 @@
+"""Sync and async clients for the Creacortex API."""
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .errors import RunFailedError, WaitTimeout, raise_for_status
+from .models import Account, Run, RunListItem
+
+DEFAULT_BASE_URL = "https://api.creacortex.ai"
+
+
+def _build_files(file: Any, filename: str | None, content_type: str) -> dict[str, Any]:
+    if isinstance(file, (str, os.PathLike)):
+        p = Path(file)
+        return {"file": (filename or p.name, p.read_bytes(), content_type)}
+    if isinstance(file, (bytes, bytearray)):
+        return {"file": (filename or "video.mp4", bytes(file), content_type)}
+    name = filename or os.path.basename(getattr(file, "name", "") or "video.mp4")
+    return {"file": (name, file, content_type)}
+
+
+class _Base:
+    def __init__(self, api_key: str, base_url: str) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._key = api_key
+        self._base = base_url.rstrip("/")
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {"X-API-Key": self._key}
+
+    def _url(self, path: str) -> str:
+        return f"{self._base}{path}"
+
+    @staticmethod
+    def _run(resp: httpx.Response) -> Run:
+        raise_for_status(resp)
+        return Run.from_api(resp.json())
+
+    @staticmethod
+    def _runs(resp: httpx.Response) -> list[RunListItem]:
+        raise_for_status(resp)
+        return [RunListItem.from_api(x) for x in resp.json()]
+
+    @staticmethod
+    def _account(resp: httpx.Response) -> Account:
+        raise_for_status(resp)
+        return Account.from_api(resp.json())
+
+    @staticmethod
+    def _bytes(resp: httpx.Response) -> bytes:
+        raise_for_status(resp)
+        return resp.content
+
+    @staticmethod
+    def _json(resp: httpx.Response) -> Any:
+        raise_for_status(resp)
+        return resp.json()
+
+    @staticmethod
+    def _video_id(resp: httpx.Response) -> str:
+        raise_for_status(resp)
+        return str(resp.json()["video_id"])
+
+
+class Client(_Base):
+    """Blocking client. Use as a context manager or call `close()` when done."""
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 60.0, transport: httpx.BaseTransport | None = None) -> None:
+        super().__init__(api_key, base_url)
+        self._http = httpx.Client(timeout=timeout, transport=transport, headers=self._headers)
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def upload_video(self, file: Any, *, filename: str | None = None,
+                     content_type: str = "video/mp4") -> str:
+        files = _build_files(file, filename, content_type)
+        return self._video_id(self._http.post(self._url("/v1/videos"), files=files))
+
+    def create_run(self, video_id: str, *, creative_id: str | None = None,
+                   with_audio: bool = False, audience: str | None = None) -> Run:
+        body = {"video_id": video_id, "creative_id": creative_id,
+                "with_audio": with_audio, "audience": audience}
+        return self._run(self._http.post(self._url("/v1/runs"), json=body))
+
+    def get_run(self, run_id: str) -> Run:
+        return self._run(self._http.get(self._url(f"/v1/runs/{run_id}")))
+
+    def list_runs(self) -> list[RunListItem]:
+        return self._runs(self._http.get(self._url("/v1/runs")))
+
+    def get_account(self) -> Account:
+        return self._account(self._http.get(self._url("/v1/account")))
+
+    def get_csv(self, run_id: str) -> bytes:
+        """Per-second analysis CSV (raw bytes)."""
+        return self._bytes(self._http.get(self._url(f"/v1/runs/{run_id}/data.csv")))
+
+    def get_export(self, run_id: str) -> Any:
+        """Gen-AI payload (parsed JSON)."""
+        return self._json(self._http.get(self._url(f"/v1/runs/{run_id}/export.json")))
+
+    def get_report(self, run_id: str, kind: str = "diagnose") -> bytes:
+        """PDF report bytes. `kind` is 'diagnose' or 'analyze'."""
+        return self._bytes(self._http.get(
+            self._url(f"/v1/runs/{run_id}/report.pdf"), params={"kind": kind}))
+
+    def wait(self, run_id: str, *, interval: float = 5.0, timeout: float = 1800.0) -> Run:
+        """Poll until the run reaches a terminal state. Raises on failure/timeout."""
+        deadline = time.monotonic() + timeout
+        while True:
+            run = self.get_run(run_id)
+            if run.failed:
+                raise RunFailedError(run.run_id, run.error)
+            if run.done:
+                return run
+            if time.monotonic() >= deadline:
+                raise WaitTimeout(f"run {run_id} not done after {timeout:.0f}s")
+            time.sleep(interval)
+
+    def analyze(self, file: Any, *, creative_id: str | None = None, with_audio: bool = False,
+                audience: str | None = None, filename: str | None = None, wait: bool = True,
+                interval: float = 5.0, timeout: float = 1800.0) -> Run:
+        """Upload, start a run, and (by default) wait for it to finish. Returns the Run."""
+        video_id = self.upload_video(file, filename=filename)
+        run = self.create_run(video_id, creative_id=creative_id,
+                              with_audio=with_audio, audience=audience)
+        return self.wait(run.run_id, interval=interval, timeout=timeout) if wait else run
+
+
+class AsyncClient(_Base):
+    """Async client. Use `async with` or `await aclose()`."""
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 60.0, transport: httpx.AsyncBaseTransport | None = None) -> None:
+        super().__init__(api_key, base_url)
+        self._http = httpx.AsyncClient(timeout=timeout, transport=transport, headers=self._headers)
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def upload_video(self, file: Any, *, filename: str | None = None,
+                           content_type: str = "video/mp4") -> str:
+        files = _build_files(file, filename, content_type)
+        return self._video_id(await self._http.post(self._url("/v1/videos"), files=files))
+
+    async def create_run(self, video_id: str, *, creative_id: str | None = None,
+                         with_audio: bool = False, audience: str | None = None) -> Run:
+        body = {"video_id": video_id, "creative_id": creative_id,
+                "with_audio": with_audio, "audience": audience}
+        return self._run(await self._http.post(self._url("/v1/runs"), json=body))
+
+    async def get_run(self, run_id: str) -> Run:
+        return self._run(await self._http.get(self._url(f"/v1/runs/{run_id}")))
+
+    async def list_runs(self) -> list[RunListItem]:
+        return self._runs(await self._http.get(self._url("/v1/runs")))
+
+    async def get_account(self) -> Account:
+        return self._account(await self._http.get(self._url("/v1/account")))
+
+    async def get_csv(self, run_id: str) -> bytes:
+        return self._bytes(await self._http.get(self._url(f"/v1/runs/{run_id}/data.csv")))
+
+    async def get_export(self, run_id: str) -> Any:
+        return self._json(await self._http.get(self._url(f"/v1/runs/{run_id}/export.json")))
+
+    async def get_report(self, run_id: str, kind: str = "diagnose") -> bytes:
+        return self._bytes(await self._http.get(
+            self._url(f"/v1/runs/{run_id}/report.pdf"), params={"kind": kind}))
+
+    async def wait(self, run_id: str, *, interval: float = 5.0, timeout: float = 1800.0) -> Run:
+        deadline = time.monotonic() + timeout
+        while True:
+            run = await self.get_run(run_id)
+            if run.failed:
+                raise RunFailedError(run.run_id, run.error)
+            if run.done:
+                return run
+            if time.monotonic() >= deadline:
+                raise WaitTimeout(f"run {run_id} not done after {timeout:.0f}s")
+            await asyncio.sleep(interval)
+
+    async def analyze(self, file: Any, *, creative_id: str | None = None, with_audio: bool = False,
+                      audience: str | None = None, filename: str | None = None, wait: bool = True,
+                      interval: float = 5.0, timeout: float = 1800.0) -> Run:
+        video_id = await self.upload_video(file, filename=filename)
+        run = await self.create_run(video_id, creative_id=creative_id,
+                                    with_audio=with_audio, audience=audience)
+        if wait:
+            return await self.wait(run.run_id, interval=interval, timeout=timeout)
+        return run

creacortex/errors.py

@@ -0,0 +1,78 @@
+"""Exceptions raised by the Creacortex client."""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class CreacortexError(Exception):
+    """Base class for every error this library raises."""
+
+
+class ApiError(CreacortexError):
+    """An HTTP error returned by the API (status >= 400)."""
+
+    def __init__(
+        self, status_code: int, message: str, *, response: httpx.Response | None = None,
+    ) -> None:
+        super().__init__(f"[{status_code}] {message}")
+        self.status_code = status_code
+        self.message = message
+        self.response = response
+
+
+class AuthError(ApiError):
+    """Invalid or missing API key (401)."""
+
+
+class InsufficientCreditsError(ApiError):
+    """The project does not have enough credits to run the analysis (402)."""
+
+
+class RateLimitError(ApiError):
+    """Too many requests — slow down (429)."""
+
+
+class NotFoundError(ApiError):
+    """The requested run (or resource) does not exist (404)."""
+
+
+class RunFailedError(CreacortexError):
+    """The analysis run finished with status='failed'."""
+
+    def __init__(self, run_id: str, error: str | None) -> None:
+        super().__init__(f"run {run_id} failed: {error or 'unknown error'}")
+        self.run_id = run_id
+        self.error = error
+
+
+class WaitTimeout(CreacortexError):
+    """A run did not reach a terminal state within the wait timeout."""
+
+
+_STATUS_ERRORS: dict[int, type[ApiError]] = {
+    401: AuthError,
+    402: InsufficientCreditsError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def raise_for_status(resp: httpx.Response) -> None:
+    """Map an error response to the appropriate typed exception."""
+    if resp.status_code < 400:
+        return
+    detail = _detail(resp)
+    cls = _STATUS_ERRORS.get(resp.status_code, ApiError)
+    raise cls(resp.status_code, detail, response=resp)
+
+
+def _detail(resp: httpx.Response) -> str:
+    try:
+        body: Any = resp.json()
+    except Exception:  # noqa: BLE001 — non-JSON error body
+        return resp.text or resp.reason_phrase
+    if isinstance(body, dict) and "detail" in body:
+        return str(body["detail"])
+    return str(body)

creacortex/models.py

@@ -0,0 +1,98 @@
+"""Typed response models. Plain dataclasses built from the API's JSON."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+# Run lifecycle states. `done` and `failed` are terminal.
+QUEUED = "queued"
+RUNNING = "running"
+DONE = "done"
+FAILED = "failed"
+TERMINAL = frozenset({DONE, FAILED})
+
+
+@dataclass(frozen=True)
+class Run:
+    """An analysis run and the URLs to its results once ready."""
+
+    run_id: str
+    status: str
+    creative_id: str | None = None
+    with_audio: bool = False
+    error: str | None = None
+    ready: bool = False
+    csv_url: str | None = None
+    export_url: str | None = None
+    diagnose_pdf_url: str | None = None
+    analyze_pdf_url: str | None = None
+
+    @property
+    def done(self) -> bool:
+        return self.status == DONE
+
+    @property
+    def failed(self) -> bool:
+        return self.status == FAILED
+
+    @property
+    def terminal(self) -> bool:
+        return self.status in TERMINAL
+
+    @classmethod
+    def from_api(cls, d: dict[str, Any]) -> Run:
+        return cls(
+            run_id=d["run_id"],
+            status=d["status"],
+            creative_id=d.get("creative_id"),
+            with_audio=bool(d.get("with_audio", False)),
+            error=d.get("error"),
+            ready=bool(d.get("ready", False)),
+            csv_url=d.get("csv_url"),
+            export_url=d.get("export_url"),
+            diagnose_pdf_url=d.get("diagnose_pdf_url"),
+            analyze_pdf_url=d.get("analyze_pdf_url"),
+        )
+
+
+@dataclass(frozen=True)
+class RunListItem:
+    """A run as returned by `list_runs` (lighter than `Run`)."""
+
+    run_id: str
+    status: str
+    creative_id: str | None
+    with_audio: bool
+    ready: bool
+    created_at: datetime
+
+    @classmethod
+    def from_api(cls, d: dict[str, Any]) -> RunListItem:
+        return cls(
+            run_id=d["run_id"],
+            status=d["status"],
+            creative_id=d.get("creative_id"),
+            with_audio=bool(d.get("with_audio", False)),
+            ready=bool(d.get("ready", False)),
+            created_at=datetime.fromisoformat(d["created_at"]),
+        )
+
+
+@dataclass(frozen=True)
+class Account:
+    """Credit balance for the API key's project."""
+
+    project: str | None
+    balance: float
+    quota: float
+    used: float
+
+    @classmethod
+    def from_api(cls, d: dict[str, Any]) -> Account:
+        return cls(
+            project=d.get("project"),
+            balance=float(d["balance"]),
+            quota=float(d["quota"]),
+            used=float(d.get("used", 0.0)),
+        )

creacortex-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: creacortex
+Version: 0.1.0
+Summary: Python client for the Creacortex video-creative attention-analysis API
+Project-URL: Homepage, https://creacortex.ai
+Author: Creacortex
+License: MIT
+License-File: LICENSE
+Keywords: advertising,analytics,api,attention,creacortex,video
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# creacortex
+
+Python client for the **Creacortex** video-creative attention-analysis API.
+
+Upload a video creative, run it through the pipeline, and pull back per-second
+attention data, a Gen-AI optimization payload, and PDF reports.
+
+## Install
+
+```bash
+pip install creacortex
+```
+
+## Quick start
+
+```python
+from creacortex import Client
+
+with Client("ace_your_api_key") as cx:
+    # one call: upload + start + wait for completion
+    run = cx.analyze("ad.mp4", with_audio=True, creative_id="summer-promo")
+
+    csv = cx.get_csv(run.run_id)                 # per-second analysis (bytes)
+    payload = cx.get_export(run.run_id)          # Gen-AI insights (dict)
+    pdf = cx.get_report(run.run_id, "diagnose")  # PDF report (bytes)
+```
+
+Get an API key from **Usage & billing → API keys** in the dashboard. It is sent
+as the `X-API-Key` header.
+
+## Async
+
+```python
+import asyncio
+from creacortex import AsyncClient
+
+async def main():
+    async with AsyncClient("ace_your_api_key") as cx:
+        run = await cx.analyze("ad.mp4")
+        print(await cx.get_export(run.run_id))
+
+asyncio.run(main())
+```
+
+## Step by step
+
+`analyze()` is a convenience over the raw endpoints, which you can also call directly:
+
+```python
+video_id = cx.upload_video("ad.mp4")
+run = cx.create_run(video_id, with_audio=True, audience="men 20-45, mobile gamers")
+run = cx.wait(run.run_id)                # poll until done (or RunFailedError / WaitTimeout)
+
+for item in cx.list_runs():
+    print(item.run_id, item.status, item.ready)
+
+print(cx.get_account().balance)          # credits left
+```
+
+`upload_video` / `analyze` accept a file path, raw `bytes`, or a binary file object.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `AuthError` | invalid/missing API key (401) |
+| `InsufficientCreditsError` | not enough credits (402) |
+| `RateLimitError` | too many requests (429) |
+| `NotFoundError` | unknown run (404) |
+| `RunFailedError` | the run finished with `status="failed"` |
+| `WaitTimeout` | `wait()` exceeded its timeout |
+| `ApiError` | any other HTTP error (has `.status_code`) |
+
+All inherit from `CreacortexError`.
+
+## Configuration
+
+```python
+Client("ace_...", base_url="https://api.creacortex.ai", timeout=60.0)
+```
+
+## License
+
+MIT

creacortex-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+creacortex/__init__.py,sha256=MYqy4Y_EWDtllOiihSszSdv78J6AANTU_rs3aIydFNQ,892
+creacortex/client.py,sha256=k1Iplv09wEg0Qvd8fPVztJJDij5oWZFTN9u0hA4QJFA,8801
+creacortex/errors.py,sha256=OE8pp0JDmXsBz-ZAj9t6_x8mf5kBR_PSlfYu1vuDECE,2139
+creacortex/models.py,sha256=Ju39mSXxWlQO3sQ_Fxw74mbOknN5lVcvyyBmbg5Z8RE,2590
+creacortex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+creacortex-0.1.0.dist-info/METADATA,sha256=1YoL3rxP49FCJDMVORljMA99oPREAI0l2gN1USEMCjo,2994
+creacortex-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+creacortex-0.1.0.dist-info/licenses/LICENSE,sha256=Srvb_fua232oRVeo451wZ9Fp0EVZmdLcCKfPwt91zjc,1067
+creacortex-0.1.0.dist-info/RECORD,,

creacortex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

creacortex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Creacortex
+
+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.