creacortex 0.2.0__tar.gz → 0.3.0__tar.gz

creacortex-0.3.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.3.0
+
+Segment-aware runs: `app or game × platform`.
+
+### Breaking
+
+- `calibration_commit` / `calibrationCommit` now require `app_or_game` and `platform`
+  (`appOrGame` / `platform` in Node). Calibration is fitted **per pair**, and the tags apply to
+  the whole uploaded file.
+
+### Added
+
+- `create_run` / `createRun` and `analyze` accept optional `app_or_game` + `platform`
+  (`appOrGame` / `platform`). Pass **both or neither** — a half pair is rejected with `422`.
+  Unknown values are created automatically; spelling is normalised, so `"  applovin "` resolves
+  to the existing `"AppLovin"` instead of creating a duplicate.
+- `get_segments()` / `getSegments()` — known tags and per-pair sample sizes, so you can see what
+  a forecast would be based on before spending credits. Platforms ship with a shared base list;
+  apps and games are private to your account.
+- `Segments` / `SegmentPair` models. A pair's `state` is `ok` (>= `min_size`), `thin`
+  (provisional) or `empty` — **no forecast is issued** for an empty pair. Python exposes
+  `SegmentPair.forecastable`.
+- `Run` and `RunListItem` carry `app_or_game` / `platform` (`appOrGame` / `platform`), `None`
+  when the run is untagged.
+
+### Notes
+
+- Tags are optional. An untagged run behaves exactly as before: the forecast is compared against
+  all videos in the project.
+- Excel exports now import as-is — semicolon separators, a leading BOM and decimal commas
+  (`3,55`) are detected automatically.
+
+## 0.2.0
+
+Calibration endpoints, typed errors, `analyze()` one-call helper.
+
+## 0.1.0
+
+Initial release.

{creacortex-0.2.0 → creacortex-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: creacortex
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python client for the Creacortex video-creative attention-analysis API
 Project-URL: Homepage, https://creacortex.ai
 Author: Creacortex
@@ -40,7 +40,8 @@ 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")
+    run = cx.analyze("ad.mp4", with_audio=True, creative_id="summer-promo",
+                     app_or_game="Raid Shadow Legends", platform="AppLovin")
 
     csv = cx.get_csv(run.run_id)                 # per-second analysis (bytes)
     payload = cx.get_export(run.run_id)          # Gen-AI insights (dict)
@@ -81,17 +82,57 @@ print(cx.get_account().balance)          # credits left
 
 `upload_video` / `analyze` accept a file path, raw `bytes`, or a binary file object.
 
+## Segments: app or game × platform
+
+A forecast is only meaningful against comparable creatives, so runs can be tagged with an
+**app or game** and a **platform**. When both are set, the prediction and the percentiles are
+computed **only from creatives of that same pair**.
+
+```python
+run = cx.create_run(video_id, app_or_game="Raid Shadow Legends", platform="AppLovin")
+run.app_or_game        # "Raid Shadow Legends" — canonical spelling as stored
+```
+
+Tags are optional. Leave them out and the run stays untagged: the forecast is compared against
+all videos in the project, exactly as before. Pass **both or neither** — one alone is rejected.
+
+Unknown values are created automatically, and spelling is normalised: `"  applovin "` resolves to
+the existing `"AppLovin"` instead of creating a duplicate. Platforms come with a shared base list
+(AppLovin, Unity Ads, Mintegral, ironSource, Liftoff, Moloco, Meta Ads, Google Ads, TikTok Ads,
+Pangle, Chartboost, Digital Turbine); apps and games are private to your account.
+
+Check what a forecast would be based on before you spend credits:
+
+```python
+segs = cx.get_segments()
+segs.apps_or_games          # your apps
+segs.platforms              # base list + your own
+segs.min_size               # 50 — below this a forecast is flagged as provisional
+
+for pair in segs.pairs:
+    print(pair.app_or_game, pair.platform, pair.size, pair.state, pair.forecastable)
+```
+
+Pair states: **`ok`** (>= `min_size`) — normal forecast; **`thin`** (1..`min_size`-1) — returned
+but provisional; **`empty`** (no data) — **no forecast is issued** for that run. Upload calibration
+data for the pair to unlock it.
+
 ## Calibration
 
 Improve prediction accuracy (and unlock all metrics) by calibrating on your real performance data.
-Any CSV works — map your columns to our fields:
+Any CSV works — map your columns to our fields. Calibration is fitted **per segment**, so
+`app_or_game` and `platform` are required on commit: they tag the whole file.
+
+Exports from Excel are handled as-is — semicolon separators, a leading BOM and decimal commas
+(`3,55`) are all detected automatically.
 
 ```python
 csv = open("performance.csv", "rb").read()
 a = cx.calibration_analyze(csv)                       # detected columns + guessed mapping
 mapping = {**a["guess"], "creative_id": "Ad name"}    # adjust if needed
 cx.calibration_preview(csv, mapping, min_impressions=50000)   # cost + impression split
-cx.calibration_commit(csv, mapping, process_unmatched=True)   # charge + fit; returns summary
+cx.calibration_commit(csv, mapping, process_unmatched=True,   # charge + fit; returns summary
+                      app_or_game="Raid Shadow Legends", platform="AppLovin")
 
 cx.get_account().calibrated   # True once fitted
 ```

{creacortex-0.2.0 → creacortex-0.3.0}/README.md

@@ -1,99 +1,140 @@
-# 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.
-
-## Calibration
-
-Improve prediction accuracy (and unlock all metrics) by calibrating on your real performance data.
-Any CSV works — map your columns to our fields:
-
-```python
-csv = open("performance.csv", "rb").read()
-a = cx.calibration_analyze(csv)                       # detected columns + guessed mapping
-mapping = {**a["guess"], "creative_id": "Ad name"}    # adjust if needed
-cx.calibration_preview(csv, mapping, min_impressions=50000)   # cost + impression split
-cx.calibration_commit(csv, mapping, process_unmatched=True)   # charge + fit; returns summary
-
-cx.get_account().calibrated   # True once fitted
-```
-
-## 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
+
+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",
+                     app_or_game="Raid Shadow Legends", platform="AppLovin")
+
+    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.
+
+## Segments: app or game × platform
+
+A forecast is only meaningful against comparable creatives, so runs can be tagged with an
+**app or game** and a **platform**. When both are set, the prediction and the percentiles are
+computed **only from creatives of that same pair**.
+
+```python
+run = cx.create_run(video_id, app_or_game="Raid Shadow Legends", platform="AppLovin")
+run.app_or_game        # "Raid Shadow Legends" — canonical spelling as stored
+```
+
+Tags are optional. Leave them out and the run stays untagged: the forecast is compared against
+all videos in the project, exactly as before. Pass **both or neither** — one alone is rejected.
+
+Unknown values are created automatically, and spelling is normalised: `"  applovin "` resolves to
+the existing `"AppLovin"` instead of creating a duplicate. Platforms come with a shared base list
+(AppLovin, Unity Ads, Mintegral, ironSource, Liftoff, Moloco, Meta Ads, Google Ads, TikTok Ads,
+Pangle, Chartboost, Digital Turbine); apps and games are private to your account.
+
+Check what a forecast would be based on before you spend credits:
+
+```python
+segs = cx.get_segments()
+segs.apps_or_games          # your apps
+segs.platforms              # base list + your own
+segs.min_size               # 50 — below this a forecast is flagged as provisional
+
+for pair in segs.pairs:
+    print(pair.app_or_game, pair.platform, pair.size, pair.state, pair.forecastable)
+```
+
+Pair states: **`ok`** (>= `min_size`) — normal forecast; **`thin`** (1..`min_size`-1) — returned
+but provisional; **`empty`** (no data) — **no forecast is issued** for that run. Upload calibration
+data for the pair to unlock it.
+
+## Calibration
+
+Improve prediction accuracy (and unlock all metrics) by calibrating on your real performance data.
+Any CSV works — map your columns to our fields. Calibration is fitted **per segment**, so
+`app_or_game` and `platform` are required on commit: they tag the whole file.
+
+Exports from Excel are handled as-is — semicolon separators, a leading BOM and decimal commas
+(`3,55`) are all detected automatically.
+
+```python
+csv = open("performance.csv", "rb").read()
+a = cx.calibration_analyze(csv)                       # detected columns + guessed mapping
+mapping = {**a["guess"], "creative_id": "Ad name"}    # adjust if needed
+cx.calibration_preview(csv, mapping, min_impressions=50000)   # cost + impression split
+cx.calibration_commit(csv, mapping, process_unmatched=True,   # charge + fit; returns summary
+                      app_or_game="Raid Shadow Legends", platform="AppLovin")
+
+cx.get_account().calibrated   # True once fitted
+```
+
+## 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.2.0 → creacortex-0.3.0}/pyproject.toml

@@ -1,44 +1,44 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "creacortex"
-version = "0.2.0"
-description = "Python client for the Creacortex video-creative attention-analysis API"
-readme = "README.md"
-requires-python = ">=3.9"
-license = { text = "MIT" }
-authors = [{ name = "Creacortex" }]
-keywords = ["creacortex", "video", "advertising", "attention", "analytics", "api"]
-classifiers = [
-  "Programming Language :: Python :: 3",
-  "License :: OSI Approved :: MIT License",
-  "Operating System :: OS Independent",
-  "Intended Audience :: Developers",
-]
-dependencies = ["httpx>=0.24"]
-
-[project.optional-dependencies]
-dev = ["pytest>=7", "pytest-asyncio>=0.23", "ruff>=0.4", "mypy>=1.8"]
-
-[project.urls]
-Homepage = "https://creacortex.ai"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/creacortex"]
-
-[tool.ruff]
-line-length = 100
-src = ["src", "tests"]
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
-
-[tool.mypy]
-strict = true
-files = ["src/creacortex"]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "creacortex"
+version = "0.3.0"
+description = "Python client for the Creacortex video-creative attention-analysis API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Creacortex" }]
+keywords = ["creacortex", "video", "advertising", "attention", "analytics", "api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.23", "ruff>=0.4", "mypy>=1.8"]
+
+[project.urls]
+Homepage = "https://creacortex.ai"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/creacortex"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+files = ["src/creacortex"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

{creacortex-0.2.0 → creacortex-0.3.0}/src/creacortex/__init__.py

@@ -1,39 +1,41 @@
-"""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.2.0"
-
-__all__ = [
-    "DEFAULT_BASE_URL",
-    "Client",
-    "AsyncClient",
-    "Run",
-    "RunListItem",
-    "Account",
-    "CreacortexError",
-    "ApiError",
-    "AuthError",
-    "InsufficientCreditsError",
-    "RateLimitError",
-    "NotFoundError",
-    "RunFailedError",
-    "WaitTimeout",
-]
+"""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, SegmentPair, Segments
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Client",
+    "AsyncClient",
+    "Run",
+    "RunListItem",
+    "SegmentPair",
+    "Segments",
+    "Account",
+    "CreacortexError",
+    "ApiError",
+    "AuthError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "NotFoundError",
+    "RunFailedError",
+    "WaitTimeout",
+]