cubic-sdk 0.3.2__tar.gz

cubic_sdk-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

cubic_sdk-0.3.2/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+# Publishes to PyPI via trusted publishing (OIDC) — no API token stored anywhere.
+# Triggered by pushing a version tag (git tag -a vX.Y.Z && git push --follow-tags).
+#
+# One-time setup on pypi.org before the first run:
+#   Account → Publishing → "Add a new pending publisher":
+#     project:     cubic-sdk
+#     owner:       cubic-zone
+#     repository:  cubic-python
+#     workflow:    publish.yml
+#     environment: pypi
+
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check tag matches package version
+        run: |
+          PKG_VERSION=$(python -c "exec(open('src/cubic/_version.py').read()); print(__version__)")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match package version $PKG_VERSION" >&2
+            exit 1
+          fi
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/cubic-sdk/
+    permissions:
+      id-token: write # OIDC token for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

cubic_sdk-0.3.2/.gitignore

@@ -0,0 +1,18 @@
+# Environments
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store

cubic_sdk-0.3.2/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.3.2 (2026-07-12)
+
+- First PyPI release: `pip install cubic-sdk`.
+- Repository moved to the `cubic-zone` GitHub organization; project URLs
+  updated. CI and trusted-publishing workflows added. No code changes.
+
+## 0.3.1 (2026-07-12)
+
+- The default `base_url` is now the hosted API (`https://api.cubic.zone`)
+  instead of the local dev server. Local development now requires an explicit
+  `base_url="http://localhost:8010"` or `CUBIC_BASE_URL`.
+
+## 0.3.0 (2026-07-11)
+
+- `client.models` resource: `list()` (public catalog, cached in-process for
+  1h, `provider=` filter, `force_refresh=`) and `retrieve(model_name)`
+  (client-side lookup with `provider=` disambiguation and did-you-mean
+  suggestions via `ModelNotFoundError`).
+- PyPI packaging prep: `py.typed` marker (PEP 561), trove classifiers,
+  project URLs, changelog.
+
+## 0.2.0 (2026-07-10)
+
+- `AsyncCubic`: the full client surface as coroutines, sharing retry and
+  parsing logic with the sync client.
+- `completions.wait(request_id)` and the `result.wait()` shortcut: poll for a
+  queued run's persisted record with backoff; raises `CompletionError` for
+  error records and `WaitTimeoutError` on deadline.
+- `cubic.webhooks`: `verify()` / `verify_signature()` / `parse()` for signed
+  callback deliveries (`X-Maxwell-Signature`, HMAC-SHA256 over the raw body),
+  plus `derive_project_secret()` for self-hosted deployments.
+
+## 0.1.0 (2026-07-09)
+
+- Initial release: `Cubic` client with `completions.create` /
+  `completions.retrieve` and `cubes.retrieve`.
+- Unified cube/polycube execution: one `create()` call for both kinds, typed
+  `CompletionResult` / `PolycubeResult` with a common `result.content`.
+- Typed exception hierarchy incl. pipeline errors surfaced from HTTP 200
+  bodies (`MissingVariableError`, `ProviderError`, `CubeNotFoundError`…).
+- Automatic idempotent retries via auto-generated `client_request_id`.

cubic_sdk-0.3.2/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: cubic-sdk
+Version: 0.3.2
+Summary: Official Python SDK for Cubic — run your Cubes and Polycubes from any application.
+Project-URL: Homepage, https://cubic.zone
+Project-URL: Documentation, https://cubic.zone/docs
+Project-URL: Repository, https://github.com/cubic-zone/cubic-python
+Project-URL: Changelog, https://github.com/cubic-zone/cubic-python/blob/main/CHANGELOG.md
+Author: Cubic
+License: MIT
+Keywords: cubic,llm,prompts,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cubic Python SDK
+
+Run your Cubes and Polycubes from any Python application with a single API key.
+
+```bash
+pip install cubic-sdk    # installs the `cubic` import package
+```
+
+## Quickstart
+
+```python
+from cubic import Cubic
+
+client = Cubic(api_key="mxk_...")  # or set CUBIC_API_KEY
+
+result = client.completions.create(
+    cube_id="cbe_a1B2c3D4e5F6g7",
+    variables={"customer_name": "Ada", "issue": "billing"},
+)
+print(result.content)
+```
+
+`cube_id` accepts any public Cube ID — plain cubes and Polycubes share one ID
+space (`cbe_…`, with legacy `prmt…`/`poly…` IDs still valid). You never need to
+know which kind an ID is: the same call runs either, and `result.content` is
+the delivered output for both.
+
+## Running a completion
+
+```python
+result = client.completions.create(
+    cube_id="cbe_a1B2c3D4e5F6g7",
+    variables={"customer_name": "Ada"},
+
+    # plain cubes only:
+    version=5,                                # pin a version (default: latest)
+    parameters={"temperature": 0.7},          # merged over the cube's parameters
+    models=[{"provider": "anthropic", "model_name": "claude-sonnet-4-5"}],
+    history=[{"role": "user", "content": "hi"}],
+
+    # both kinds:
+    test_mode=True,                           # no provider spend, no credit debit
+    metadata={"trace": "abc"},
+)
+
+result.content            # str | dict — the winning completion (or final node output)
+result.kind               # "cube" | "polycube"
+result.metrics            # tokens, cost, credits_charged, latency, cache hits
+result.request_id         # keep this for retrieval / support
+result.is_partial         # cube delivered content but some fallbacks failed
+result.segments           # polycube only: per-node outputs, metrics, errors
+```
+
+## Async client
+
+`AsyncCubic` has the identical surface with awaitable methods:
+
+```python
+from cubic import AsyncCubic
+
+async with AsyncCubic(api_key="mxk_...") as client:
+    result = await client.completions.create(cube_id="cbe_...", variables={...})
+```
+
+## Async execution (callbacks)
+
+If the cube defines a callback URL — or you pass `callback_url=` — the run is
+queued and delivered to your endpoint when done:
+
+```python
+job = client.completions.create(cube_id="cbe_...", variables={...},
+                                callback_url="https://you.example/hook")
+job.is_queued      # True
+job.request_id     # correlate with the X-Maxwell-Request-Id callback header
+
+record = job.wait(timeout=120)                       # poll until persisted
+record = client.completions.wait(job.request_id)     # same, by id
+record = client.completions.retrieve(job.request_id) # single poll
+```
+
+`wait()` backs off from 0.5s to 4s between polls (fix it with
+`poll_interval=`), raises `CompletionError` if the run finished with status
+`error`, and `WaitTimeoutError` if nothing was persisted in time (the run
+itself is unaffected). With `AsyncCubic`, `await job.wait()`.
+
+## Verifying callback deliveries
+
+Every delivery is signed. Verify and parse it in one step — always against the
+**raw request body bytes**:
+
+```python
+from cubic import webhooks
+
+@app.post("/hook")                        # any framework
+async def hook(request):
+    result = webhooks.verify(await request.body(), request.headers,
+                             secret=CUBIC_SIGNING_SECRET)
+    if result.status == "success":
+        handle(result.content)            # CompletionResult | PolycubeResult
+```
+
+A bad or missing `X-Maxwell-Signature` raises `WebhookSignatureError`. Unlike
+`create()`, an error-status delivery is returned (not raised) — it's an event
+you inspect. Retried deliveries reuse the same body and signature and carry an
+incrementing `X-Maxwell-Delivery-Attempt` header; deduplicate on
+`result.request_id` if your handler isn't idempotent.
+
+## Reading a cube's definition
+
+```python
+cube = client.cubes.retrieve("cbe_a1B2c3D4e5F6g7")          # latest
+cube = client.cubes.retrieve("cbe_a1B2c3D4e5F6g7", version=5)
+
+cube.system_instructions   # the cube's system prompt
+cube.user_prompt           # the user prompt template
+cube.variables             # input schema — handy for pre-flight checks
+cube.models                # the model stack (provider, model, rank, role)
+```
+
+Definitions are owner-only: marketplace cubes you subscribe to can be *run*
+but not read, and polycube definitions are not yet available on this endpoint.
+
+## The model catalog
+
+```python
+models = client.models.list()                        # cached in-process for 1h
+anthropic = client.models.list(provider="anthropic")
+
+m = client.models.retrieve("claude-3-5-haiku")       # ModelNotFoundError suggests
+m.context_window, m.input_per_1k, m.supports_tools   # close matches on typos
+```
+
+Useful for validating `models=` overrides before a run, populating model
+pickers, and estimating cost. Lookups are explicit — the SDK never
+auto-validates overrides against the cache; the server stays authoritative.
+
+## Error handling
+
+The SDK never returns a silent failure: pipeline errors that the API reports
+inside an HTTP 200 are raised as typed exceptions too.
+
+```python
+from cubic import (
+    AuthenticationError,       # bad/expired API key
+    CubeNotFoundError,         # unknown ID, or not yours
+    MissingVariableError,      # e.missing variable_name
+    InvalidRequestError,       # bad parameters / polycube-inapplicable fields
+    InsufficientCreditsError,  # e.required / e.balance / e.topup_allowed
+    RateLimitError,            # capacity (auto-retried first)
+    ProviderError,             # all model attempts failed; see e.attempt_errors
+    CompletionTimeoutError,    # server-side execution deadline exceeded
+)
+
+try:
+    result = client.completions.create(cube_id="cbe_...", variables={...})
+except MissingVariableError as e:
+    print(f"Provide the '{e.variable_name}' variable")
+except InsufficientCreditsError as e:
+    print(f"Need {e.required} credits, have {e.balance}")
+```
+
+Every exception carries `.error_code`, `.status_code`, `.request_id` (quote it
+in support requests), and — for pipeline failures — `.result` with the full
+parsed response.
+
+## Retries and idempotency
+
+Connection failures and capacity 429s are retried automatically with
+exponential backoff (`max_retries=2` by default). For plain cubes the SDK
+attaches a `client_request_id` idempotency key to every run, so retries can
+never double-charge or double-execute; ambiguous failures (timeouts, 5xx) are
+retried only when that key is present. Pass your own `client_request_id` to
+make retries idempotent across process restarts too.
+
+## Configuration
+
+```python
+client = Cubic(
+    api_key="mxk_...",                   # or CUBIC_API_KEY
+    base_url="http://localhost:8010",    # or CUBIC_BASE_URL (default: https://api.cubic.zone)
+    timeout=120.0,
+    max_retries=3,
+)
+```

cubic_sdk-0.3.2/README.md

@@ -0,0 +1,184 @@
+# Cubic Python SDK
+
+Run your Cubes and Polycubes from any Python application with a single API key.
+
+```bash
+pip install cubic-sdk    # installs the `cubic` import package
+```
+
+## Quickstart
+
+```python
+from cubic import Cubic
+
+client = Cubic(api_key="mxk_...")  # or set CUBIC_API_KEY
+
+result = client.completions.create(
+    cube_id="cbe_a1B2c3D4e5F6g7",
+    variables={"customer_name": "Ada", "issue": "billing"},
+)
+print(result.content)
+```
+
+`cube_id` accepts any public Cube ID — plain cubes and Polycubes share one ID
+space (`cbe_…`, with legacy `prmt…`/`poly…` IDs still valid). You never need to
+know which kind an ID is: the same call runs either, and `result.content` is
+the delivered output for both.
+
+## Running a completion
+
+```python
+result = client.completions.create(
+    cube_id="cbe_a1B2c3D4e5F6g7",
+    variables={"customer_name": "Ada"},
+
+    # plain cubes only:
+    version=5,                                # pin a version (default: latest)
+    parameters={"temperature": 0.7},          # merged over the cube's parameters
+    models=[{"provider": "anthropic", "model_name": "claude-sonnet-4-5"}],
+    history=[{"role": "user", "content": "hi"}],
+
+    # both kinds:
+    test_mode=True,                           # no provider spend, no credit debit
+    metadata={"trace": "abc"},
+)
+
+result.content            # str | dict — the winning completion (or final node output)
+result.kind               # "cube" | "polycube"
+result.metrics            # tokens, cost, credits_charged, latency, cache hits
+result.request_id         # keep this for retrieval / support
+result.is_partial         # cube delivered content but some fallbacks failed
+result.segments           # polycube only: per-node outputs, metrics, errors
+```
+
+## Async client
+
+`AsyncCubic` has the identical surface with awaitable methods:
+
+```python
+from cubic import AsyncCubic
+
+async with AsyncCubic(api_key="mxk_...") as client:
+    result = await client.completions.create(cube_id="cbe_...", variables={...})
+```
+
+## Async execution (callbacks)
+
+If the cube defines a callback URL — or you pass `callback_url=` — the run is
+queued and delivered to your endpoint when done:
+
+```python
+job = client.completions.create(cube_id="cbe_...", variables={...},
+                                callback_url="https://you.example/hook")
+job.is_queued      # True
+job.request_id     # correlate with the X-Maxwell-Request-Id callback header
+
+record = job.wait(timeout=120)                       # poll until persisted
+record = client.completions.wait(job.request_id)     # same, by id
+record = client.completions.retrieve(job.request_id) # single poll
+```
+
+`wait()` backs off from 0.5s to 4s between polls (fix it with
+`poll_interval=`), raises `CompletionError` if the run finished with status
+`error`, and `WaitTimeoutError` if nothing was persisted in time (the run
+itself is unaffected). With `AsyncCubic`, `await job.wait()`.
+
+## Verifying callback deliveries
+
+Every delivery is signed. Verify and parse it in one step — always against the
+**raw request body bytes**:
+
+```python
+from cubic import webhooks
+
+@app.post("/hook")                        # any framework
+async def hook(request):
+    result = webhooks.verify(await request.body(), request.headers,
+                             secret=CUBIC_SIGNING_SECRET)
+    if result.status == "success":
+        handle(result.content)            # CompletionResult | PolycubeResult
+```
+
+A bad or missing `X-Maxwell-Signature` raises `WebhookSignatureError`. Unlike
+`create()`, an error-status delivery is returned (not raised) — it's an event
+you inspect. Retried deliveries reuse the same body and signature and carry an
+incrementing `X-Maxwell-Delivery-Attempt` header; deduplicate on
+`result.request_id` if your handler isn't idempotent.
+
+## Reading a cube's definition
+
+```python
+cube = client.cubes.retrieve("cbe_a1B2c3D4e5F6g7")          # latest
+cube = client.cubes.retrieve("cbe_a1B2c3D4e5F6g7", version=5)
+
+cube.system_instructions   # the cube's system prompt
+cube.user_prompt           # the user prompt template
+cube.variables             # input schema — handy for pre-flight checks
+cube.models                # the model stack (provider, model, rank, role)
+```
+
+Definitions are owner-only: marketplace cubes you subscribe to can be *run*
+but not read, and polycube definitions are not yet available on this endpoint.
+
+## The model catalog
+
+```python
+models = client.models.list()                        # cached in-process for 1h
+anthropic = client.models.list(provider="anthropic")
+
+m = client.models.retrieve("claude-3-5-haiku")       # ModelNotFoundError suggests
+m.context_window, m.input_per_1k, m.supports_tools   # close matches on typos
+```
+
+Useful for validating `models=` overrides before a run, populating model
+pickers, and estimating cost. Lookups are explicit — the SDK never
+auto-validates overrides against the cache; the server stays authoritative.
+
+## Error handling
+
+The SDK never returns a silent failure: pipeline errors that the API reports
+inside an HTTP 200 are raised as typed exceptions too.
+
+```python
+from cubic import (
+    AuthenticationError,       # bad/expired API key
+    CubeNotFoundError,         # unknown ID, or not yours
+    MissingVariableError,      # e.missing variable_name
+    InvalidRequestError,       # bad parameters / polycube-inapplicable fields
+    InsufficientCreditsError,  # e.required / e.balance / e.topup_allowed
+    RateLimitError,            # capacity (auto-retried first)
+    ProviderError,             # all model attempts failed; see e.attempt_errors
+    CompletionTimeoutError,    # server-side execution deadline exceeded
+)
+
+try:
+    result = client.completions.create(cube_id="cbe_...", variables={...})
+except MissingVariableError as e:
+    print(f"Provide the '{e.variable_name}' variable")
+except InsufficientCreditsError as e:
+    print(f"Need {e.required} credits, have {e.balance}")
+```
+
+Every exception carries `.error_code`, `.status_code`, `.request_id` (quote it
+in support requests), and — for pipeline failures — `.result` with the full
+parsed response.
+
+## Retries and idempotency
+
+Connection failures and capacity 429s are retried automatically with
+exponential backoff (`max_retries=2` by default). For plain cubes the SDK
+attaches a `client_request_id` idempotency key to every run, so retries can
+never double-charge or double-execute; ambiguous failures (timeouts, 5xx) are
+retried only when that key is present. Pass your own `client_request_id` to
+make retries idempotent across process restarts too.
+
+## Configuration
+
+```python
+client = Cubic(
+    api_key="mxk_...",                   # or CUBIC_API_KEY
+    base_url="http://localhost:8010",    # or CUBIC_BASE_URL (default: https://api.cubic.zone)
+    timeout=120.0,
+    max_retries=3,
+)
+```

cubic_sdk-0.3.2/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# PyPI distribution name ("cubic" is taken by an unrelated bioimaging package);
+# the import package remains `cubic`.
+name = "cubic-sdk"
+version = "0.3.2"
+description = "Official Python SDK for Cubic — run your Cubes and Polycubes from any application."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Cubic" }]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+keywords = ["cubic", "llm", "prompts", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://cubic.zone"
+Documentation = "https://cubic.zone/docs"
+Repository = "https://github.com/cubic-zone/cubic-python"
+Changelog = "https://github.com/cubic-zone/cubic-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cubic"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

cubic_sdk-0.3.2/src/cubic/__init__.py

@@ -0,0 +1,91 @@
+"""Cubic Python SDK.
+
+Quickstart::
+
+    from cubic import Cubic
+
+    client = Cubic(api_key="mxk_...")
+    result = client.completions.create(
+        cube_id="cbe_a1B2c3D4e5F6g7",
+        variables={"customer_name": "Ada"},
+    )
+    print(result.content)
+"""
+
+from . import webhooks
+from ._async_client import AsyncCubic
+from ._client import Cubic
+from ._exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    CompletionError,
+    CompletionNotFoundError,
+    CompletionTimeoutError,
+    CubeNotFoundError,
+    CubicError,
+    InsufficientCreditsError,
+    InternalServerError,
+    InvalidRequestError,
+    MissingVariableError,
+    ModelNotFoundError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProviderError,
+    RateLimitError,
+    VersionNotFoundError,
+    WaitTimeoutError,
+    WebhookSignatureError,
+)
+from ._version import __version__
+from .types import (
+    AttemptError,
+    CompletionRecord,
+    CompletionResult,
+    Cube,
+    CubeModel,
+    Metrics,
+    Model,
+    PolycubeResult,
+    Segment,
+    SingleCompletion,
+)
+
+__all__ = [
+    "Cubic",
+    "AsyncCubic",
+    "webhooks",
+    "__version__",
+    # exceptions
+    "CubicError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ModelNotFoundError",
+    "CubeNotFoundError",
+    "VersionNotFoundError",
+    "CompletionNotFoundError",
+    "InvalidRequestError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "CompletionTimeoutError",
+    "InternalServerError",
+    "CompletionError",
+    "MissingVariableError",
+    "ProviderError",
+    "WaitTimeoutError",
+    "WebhookSignatureError",
+    # types
+    "AttemptError",
+    "Metrics",
+    "SingleCompletion",
+    "CompletionResult",
+    "PolycubeResult",
+    "Segment",
+    "CompletionRecord",
+    "Cube",
+    "CubeModel",
+    "Model",
+]