cuddler 0.1.0__tar.gz

cuddler-0.1.0/LICENSE

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

cuddler-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include tests/recovery-fixtures.json

cuddler-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: cuddler
+Version: 0.1.0
+Summary: Official Cuddler Platform client
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.28.1
+Dynamic: license-file
+
+# Cuddler Platform SDK
+
+Release candidate; npm/PyPI publication is pending registry authentication and release verification.
+Source is maintained in the private Cuddler repository; no public source repository is required.
+
+This client, intended to run in a developer's server environment, uses the native USD Platform API at `https://api.cuddler.ai/v1`.
+It supports video, images, speech, music, models, voices, balance, usage and the
+create/get/complete upload protocol. Media transfer is explicit: use the returned
+signed URL without an Authorization header. No provider key is required.
+
+## TypeScript / JavaScript
+
+```js
+import Cuddler from '@cuddler/platform';
+const client = new Cuddler({ apiKey: process.env.CUDDLER_API_KEY });
+const quote = await client.videos.estimate({
+  model: 'seedance-2.5', mode: 'text', variant: 'default',
+  duration: 4, resolution: '480p', aspect_ratio: '16:9', generate_audio: false,
+});
+const job = await client.videos.createAndWait({
+  model: 'seedance-2.5', mode: 'text', duration: 4, resolution: '480p',
+  aspect_ratio: '16:9', generate_audio: false,
+  prompt: 'An original blue clay robot waving.', max_usd: '1.00',
+}, { idempotencyKey: 'my-persisted-operation-001' });
+if (job.status !== 'succeeded') throw new Error(job.status);
+```
+
+`images`, `speech`, and `music` have the same create/retrieve/list/estimate/wait methods.
+Cancellation is available for videos, speech and music; images cannot be canceled.
+The server's current catalog and quotes determine available models and parameters.
+TypeScript request/response types come from the repository's generated OpenAPI contract.
+
+## Python
+
+```python
+from cuddler import Cuddler
+with Cuddler() as client:  # reads CUDDLER_API_KEY
+    models = client.models.list()
+    job = client.videos.retrieve('vid_REPLACE_WITH_YOUR_JOB_ID')
+```
+
+Python uses `create_and_wait`, `idempotency_key`, `timeout` and `poll_interval`.
+It is a synchronous httpx client; use a worker thread when calling it from an async app.
+
+## Recovery and spending
+
+- Every generation requires a positive decimal-string `max_usd`.
+- Each new create gets a fresh key. Persist and explicitly reuse a key and identical
+  request body for a durable business operation; otherwise another create is a new job.
+- POST calls are never retried automatically, including estimates and cancel calls.
+- On uncertain submission, `CuddlerError.idempotencyKey` (Python: `idempotency_key`)
+  carries the original key and `outcomeUnknown` / `outcome_unknown` is true.
+  Reconcile or replay that exact operation; do not create a new key blindly.
+- GET retries respect Retry-After (at most two retries by default). A delay over
+  60 seconds returns the error to the caller rather than retrying early.
+- Waiting returns terminal failed/canceled jobs as well as successes. A polling timeout
+  includes `jobId` / `job_id`; resume with retrieve/wait, never with a new create.
+  An in-flight HTTP read may finish after the polling deadline.
+- Keys remain server-side. The SDK does not write credentials, prompts or replay records
+  to disk. Applications are responsible for durable operation identity and recovery.
+
+## CLI
+
+Use `CUDDLER_API_KEY` in the environment; API keys are not accepted as command arguments.
+
+```sh
+npx @cuddler/platform models
+npx @cuddler/platform videos create --json request.json --idempotency-key episode-001 --wait
+```
+
+The CLI exits nonzero for failed/canceled jobs and emits safe recovery metadata on errors.
+
+The Python distribution also installs `cuddler-platform`; it does not require Node.js.
+For a local candidate wheel (PyPI installation becomes available after publication):
+
+```sh
+python -m pip install ./cuddler-0.1.0-py3-none-any.whl
+cuddler-platform --help
+python -m cuddler models
+python -m cuddler videos create --json request.json --idempotency-key episode-001 --wait
+```
+
+Both distributions use the same command name. Install Python into a virtual environment,
+or use `python -m cuddler` to select it explicitly. The commands, JSON result output and
+safe recovery error fields match the npm CLI. Use `--json` for private prompt content
+so it does not appear in shell history or process arguments. File transfer uses the
+returned signed URL without sending the API credential to the media host.
+
+## Build and release boundary
+
+The npm source package has a private workspace name because the platform web app already
+uses `@cuddler/platform` internally. `node scripts/build.mjs` produces a separate publishable
+`dist` manifest named `@cuddler/platform`, with only SDK code, contract types and docs.
+The Python source is in `packages/platform-sdk-python-public` and builds the package `cuddler`.
+The existing private adapter cores in Draft #5979 remain separate and unchanged.
+
+The SDK and CLI only implement API types, HTTP requests, queries, polling, error handling
+and recovery of the original operation. Model scheduling, server authorization, quota and
+settlement decisions, and provider credentials remain in the service. Published packages
+must run without access to this private repository and must not contain private backend
+implementation, runtime credentials or user data. JavaScript and Python client files in
+distributed packages remain inspectable; a private source repository does not hide them.
+
+### Distribution terms and publication status
+
+SDK and CLI packages are distributed under the MIT License. Keep the bundled LICENSE
+and copyright notice when copying or redistributing the software. The development
+repository remains private; this does not restrict the rights granted for the SDK
+files included in the packages. The license covers the distributed SDK, not private
+backend code, service access, account credentials or API usage charges.
+
+Both LICENSE files, the JavaScript source and generated package metadata, and Python
+pyproject.toml declare MIT. Before release, rebuild and inspect both archives and record
+their hashes against the private source commit. Public source hosting and npm provenance
+are not prerequisites for this phase. Installers need no private-repository access.
+
+Registry identities, package permissions and release authorization must be verified.
+After publication, verify clean installation of both SDKs and CLIs from the official npm
+and PyPI registries. Reuse matching live acceptance evidence; local builds are not proof
+of registry publication. Do not add paid generation tasks for these documentation changes.

cuddler-0.1.0/README.md

@@ -0,0 +1,120 @@
+# Cuddler Platform SDK
+
+Release candidate; npm/PyPI publication is pending registry authentication and release verification.
+Source is maintained in the private Cuddler repository; no public source repository is required.
+
+This client, intended to run in a developer's server environment, uses the native USD Platform API at `https://api.cuddler.ai/v1`.
+It supports video, images, speech, music, models, voices, balance, usage and the
+create/get/complete upload protocol. Media transfer is explicit: use the returned
+signed URL without an Authorization header. No provider key is required.
+
+## TypeScript / JavaScript
+
+```js
+import Cuddler from '@cuddler/platform';
+const client = new Cuddler({ apiKey: process.env.CUDDLER_API_KEY });
+const quote = await client.videos.estimate({
+  model: 'seedance-2.5', mode: 'text', variant: 'default',
+  duration: 4, resolution: '480p', aspect_ratio: '16:9', generate_audio: false,
+});
+const job = await client.videos.createAndWait({
+  model: 'seedance-2.5', mode: 'text', duration: 4, resolution: '480p',
+  aspect_ratio: '16:9', generate_audio: false,
+  prompt: 'An original blue clay robot waving.', max_usd: '1.00',
+}, { idempotencyKey: 'my-persisted-operation-001' });
+if (job.status !== 'succeeded') throw new Error(job.status);
+```
+
+`images`, `speech`, and `music` have the same create/retrieve/list/estimate/wait methods.
+Cancellation is available for videos, speech and music; images cannot be canceled.
+The server's current catalog and quotes determine available models and parameters.
+TypeScript request/response types come from the repository's generated OpenAPI contract.
+
+## Python
+
+```python
+from cuddler import Cuddler
+with Cuddler() as client:  # reads CUDDLER_API_KEY
+    models = client.models.list()
+    job = client.videos.retrieve('vid_REPLACE_WITH_YOUR_JOB_ID')
+```
+
+Python uses `create_and_wait`, `idempotency_key`, `timeout` and `poll_interval`.
+It is a synchronous httpx client; use a worker thread when calling it from an async app.
+
+## Recovery and spending
+
+- Every generation requires a positive decimal-string `max_usd`.
+- Each new create gets a fresh key. Persist and explicitly reuse a key and identical
+  request body for a durable business operation; otherwise another create is a new job.
+- POST calls are never retried automatically, including estimates and cancel calls.
+- On uncertain submission, `CuddlerError.idempotencyKey` (Python: `idempotency_key`)
+  carries the original key and `outcomeUnknown` / `outcome_unknown` is true.
+  Reconcile or replay that exact operation; do not create a new key blindly.
+- GET retries respect Retry-After (at most two retries by default). A delay over
+  60 seconds returns the error to the caller rather than retrying early.
+- Waiting returns terminal failed/canceled jobs as well as successes. A polling timeout
+  includes `jobId` / `job_id`; resume with retrieve/wait, never with a new create.
+  An in-flight HTTP read may finish after the polling deadline.
+- Keys remain server-side. The SDK does not write credentials, prompts or replay records
+  to disk. Applications are responsible for durable operation identity and recovery.
+
+## CLI
+
+Use `CUDDLER_API_KEY` in the environment; API keys are not accepted as command arguments.
+
+```sh
+npx @cuddler/platform models
+npx @cuddler/platform videos create --json request.json --idempotency-key episode-001 --wait
+```
+
+The CLI exits nonzero for failed/canceled jobs and emits safe recovery metadata on errors.
+
+The Python distribution also installs `cuddler-platform`; it does not require Node.js.
+For a local candidate wheel (PyPI installation becomes available after publication):
+
+```sh
+python -m pip install ./cuddler-0.1.0-py3-none-any.whl
+cuddler-platform --help
+python -m cuddler models
+python -m cuddler videos create --json request.json --idempotency-key episode-001 --wait
+```
+
+Both distributions use the same command name. Install Python into a virtual environment,
+or use `python -m cuddler` to select it explicitly. The commands, JSON result output and
+safe recovery error fields match the npm CLI. Use `--json` for private prompt content
+so it does not appear in shell history or process arguments. File transfer uses the
+returned signed URL without sending the API credential to the media host.
+
+## Build and release boundary
+
+The npm source package has a private workspace name because the platform web app already
+uses `@cuddler/platform` internally. `node scripts/build.mjs` produces a separate publishable
+`dist` manifest named `@cuddler/platform`, with only SDK code, contract types and docs.
+The Python source is in `packages/platform-sdk-python-public` and builds the package `cuddler`.
+The existing private adapter cores in Draft #5979 remain separate and unchanged.
+
+The SDK and CLI only implement API types, HTTP requests, queries, polling, error handling
+and recovery of the original operation. Model scheduling, server authorization, quota and
+settlement decisions, and provider credentials remain in the service. Published packages
+must run without access to this private repository and must not contain private backend
+implementation, runtime credentials or user data. JavaScript and Python client files in
+distributed packages remain inspectable; a private source repository does not hide them.
+
+### Distribution terms and publication status
+
+SDK and CLI packages are distributed under the MIT License. Keep the bundled LICENSE
+and copyright notice when copying or redistributing the software. The development
+repository remains private; this does not restrict the rights granted for the SDK
+files included in the packages. The license covers the distributed SDK, not private
+backend code, service access, account credentials or API usage charges.
+
+Both LICENSE files, the JavaScript source and generated package metadata, and Python
+pyproject.toml declare MIT. Before release, rebuild and inspect both archives and record
+their hashes against the private source commit. Public source hosting and npm provenance
+are not prerequisites for this phase. Installers need no private-repository access.
+
+Registry identities, package permissions and release authorization must be verified.
+After publication, verify clean installation of both SDKs and CLIs from the official npm
+and PyPI registries. Reuse matching live acceptance evidence; local builds are not proof
+of registry publication. Do not add paid generation tasks for these documentation changes.

cuddler-0.1.0/cuddler/__init__.py

@@ -0,0 +1,3 @@
+from .client import Cuddler, CuddlerError
+
+__all__ = ["Cuddler", "CuddlerError"]

cuddler-0.1.0/cuddler/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

cuddler-0.1.0/cuddler/cli.py

@@ -0,0 +1,74 @@
+"""Command-line access to the public client; credentials stay in the environment."""
+import argparse
+import json
+import math
+from pathlib import Path
+import sys
+
+from .client import Cuddler, CuddlerError
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, _message):
+        # argparse's default error includes raw arguments, which may be sensitive.
+        raise ValueError("invalid_command_or_input")
+
+
+def main(argv=None):
+    parser = _Parser(prog="cuddler-platform", add_help=False, allow_abbrev=False)
+    parser.add_argument("command", nargs="*")
+    parser.add_argument("-h", "--help", action="store_true")
+    for name in ("json", "prompt", "model", "duration", "resolution", "max-usd", "idempotency-key"):
+        parser.add_argument("--" + name)
+    parser.add_argument("--wait", action="store_true")
+    try:
+        args = parser.parse_args(argv)
+        if args.help or not args.command:
+            print("CUDDLER_API_KEY must be set in the environment.\n"
+                  "cuddler-platform models\n"
+                  "cuddler-platform videos|images|speech|music create --json request.json [--wait]\n"
+                  "cuddler-platform videos|images|speech|music get ID\n"
+                  "Reuse --idempotency-key with exactly the same JSON after an uncertain create.")
+            return 0
+
+        command = args.command
+        body = None
+        if command != ["models"]:
+            if (command[0] not in ("videos", "images", "speech", "music") or
+                    not ((len(command) == 2 and command[1] == "create") or
+                         (len(command) == 3 and command[1] == "get"))):
+                raise CuddlerError("invalid_command")
+            if command[1] == "create":
+                body = json.loads(Path(args.json).read_text(encoding="utf-8")) if args.json else {}
+                if not isinstance(body, dict):
+                    raise ValueError("invalid_command_or_input")
+                for name in ("model", "prompt", "resolution", "max_usd"):
+                    value = getattr(args, name)
+                    if value is not None:
+                        body[name] = value
+                if args.duration is not None:
+                    duration = float(args.duration)
+                    if not math.isfinite(duration):
+                        raise ValueError("invalid_command_or_input")
+                    body["duration"] = int(duration) if duration.is_integer() else duration
+
+        with Cuddler() as client:
+            if command == ["models"]:
+                result = client.models.list()
+            elif command[1] == "get":
+                result = getattr(client, command[0]).retrieve(command[2])
+            else:
+                resource = getattr(client, command[0])
+                create = resource.create_and_wait if args.wait else resource.create
+                result = create(body, idempotency_key=args.idempotency_key)
+        print(json.dumps(result, indent=2))
+        return 1 if result.get("status") in ("failed", "canceled") else 0
+    except CuddlerError as error:
+        print(json.dumps({"code": error.code, "status": error.status,
+                          "idempotencyKey": error.idempotency_key,
+                          "outcomeUnknown": error.outcome_unknown,
+                          "jobId": error.job_id}), file=sys.stderr)
+        return 1
+    except (ValueError, TypeError, OSError):
+        print(json.dumps({"code": "invalid_command_or_input"}), file=sys.stderr)
+        return 1

cuddler-0.1.0/cuddler/client.py

@@ -0,0 +1,213 @@
+"""Thin synchronous REST client with one-shot writes and explicit recovery keys."""
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+import json
+import math
+import os
+import re
+import time
+import uuid
+
+import httpx
+
+ORIGIN = "https://api.cuddler.ai/v1"
+TERMINAL = {"succeeded", "failed", "canceled"}
+RETRYABLE = {408, 429, 500, 502, 503, 504}
+CODES = {"invalid_request", "unauthorized", "forbidden", "not_found", "insufficient_balance",
+         "idempotency_conflict", "not_cancelable", "content_blocked", "rate_limited", "queue_full",
+         "daily_limit_reached", "model_not_enabled", "organization_suspended", "unavailable",
+         "upstream_error", "internal_error"}
+
+
+class CuddlerError(Exception):
+    """No raw response, prompt, credential or transport exception is retained."""
+    def __init__(self, code, *, status=None, idempotency_key=None, outcome_unknown=False, job_id=None):
+        super().__init__(code)
+        self.code, self.status = code, status
+        self.idempotency_key, self.outcome_unknown = idempotency_key, outcome_unknown
+        self.job_id = job_id
+
+
+def identity(value, prefix):
+    if not isinstance(value, str) or not re.fullmatch(prefix + r"_[A-Za-z0-9]{12,40}", value):
+        raise CuddlerError("invalid_resource_id")
+    return value
+
+
+def retry_delay(header, attempt):
+    if header:
+        try:
+            value = float(header) if re.fullmatch(r"\d+(?:\.\d+)?", header) else (
+                parsedate_to_datetime(header) - datetime.now(timezone.utc)).total_seconds()
+            if math.isfinite(value):
+                return max(0, value)
+        except (ValueError, TypeError, OverflowError):
+            pass
+    return 0.5 * 2 ** attempt
+
+
+def validate_wait(timeout, poll_interval):
+    if not math.isfinite(timeout) or timeout <= 0 or not math.isfinite(poll_interval) or poll_interval < 0.1:
+        raise CuddlerError("invalid_wait_options")
+
+
+class Resource:
+    def __init__(self, client, path, prefix):
+        self._client, self._path, self._prefix = client, path, prefix
+
+    def create(self, body, *, idempotency_key=None):
+        return self._client._create(self._path, body, idempotency_key, self._prefix)
+
+    def retrieve(self, job_id):
+        return self._client._call("GET", self._path + "/" + identity(job_id, self._prefix))
+
+    def estimate(self, body):
+        return self._client._call("POST", self._path + "/estimate", body=body)
+
+    def list(self, **query):
+        return self._client._call("GET", self._path, query=query)
+
+    def wait(self, job_id, *, timeout=1200, poll_interval=2):
+        identity(job_id, self._prefix)
+        validate_wait(timeout, poll_interval)
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            try:
+                job = self.retrieve(job_id)
+            except CuddlerError as error:
+                error.job_id = job_id
+                raise
+            if job.get("id") != job_id or job.get("status") not in TERMINAL | {"queued", "running"}:
+                raise CuddlerError("invalid_response", job_id=job_id)
+            if job["status"] in TERMINAL:
+                return job
+            self._client._sleep(min(poll_interval, max(0, deadline - time.monotonic())))
+        raise CuddlerError("wait_timeout", job_id=job_id)
+
+    def create_and_wait(self, body, *, idempotency_key=None, timeout=1200, poll_interval=2):
+        validate_wait(timeout, poll_interval)
+        job = self.create(body, idempotency_key=idempotency_key)
+        return self.wait(job["id"], timeout=timeout, poll_interval=poll_interval)
+
+
+class CancelableResource(Resource):
+    def cancel(self, job_id):
+        return self._client._call("POST", self._path + "/" + identity(job_id, self._prefix) + "/cancel")
+
+
+class ReadResource:
+    def __init__(self, client, path):
+        self._client, self._path = client, path
+
+    def list(self, **query):
+        return self._client._call("GET", self._path, query=query)
+
+
+class Balance:
+    def __init__(self, client):
+        self._client = client
+
+    def retrieve(self):
+        return self._client._call("GET", "/balance")
+
+
+class Uploads:
+    def __init__(self, client):
+        self._client = client
+
+    def create(self, body, *, idempotency_key=None):
+        return self._client._create("/uploads", body, idempotency_key, "upl", require_cap=False)
+
+    def retrieve(self, upload_id):
+        return self._client._call("GET", "/uploads/" + identity(upload_id, "upl"))
+
+    def complete(self, upload_id):
+        return self._client._call("POST", "/uploads/" + identity(upload_id, "upl") + "/complete")
+
+
+class Cuddler:
+    def __init__(self, api_key=None, *, timeout=30, max_retries=2, transport=None, sleep=time.sleep):
+        key = api_key if api_key is not None else os.environ.get("CUDDLER_API_KEY")
+        if not isinstance(key, str) or not re.fullmatch(r"cud_sk_(live|test)_[A-Za-z0-9_-]{12,200}", key):
+            raise CuddlerError("invalid_api_key")
+        if not math.isfinite(timeout) or not 0 < timeout <= 120 or type(max_retries) is not int or not 0 <= max_retries <= 5:
+            raise CuddlerError("invalid_client_options")
+        self.__key = key
+        self.__http = httpx.Client(timeout=timeout, follow_redirects=False, transport=transport, trust_env=False)
+        self.__retries, self._sleep = max_retries, sleep
+        self.videos = CancelableResource(self, "/videos", "vid")
+        self.images = Resource(self, "/images", "img")
+        self.speech = CancelableResource(self, "/speech", "aud")
+        self.music = CancelableResource(self, "/music", "mus")
+        self.models, self.voices = ReadResource(self, "/models"), ReadResource(self, "/voices")
+        self.usage, self.balance, self.uploads = ReadResource(self, "/usage"), Balance(self), Uploads(self)
+
+    def close(self):
+        self.__http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+    def _call(self, method, path, *, body=None, query=None, idempotency_key=None):
+        headers = {"Authorization": "Bearer " + self.__key, "Accept": "application/json"}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        try:
+            encoded = None if body is None else json.dumps(body, allow_nan=False).encode()
+        except (TypeError, ValueError):
+            raise CuddlerError("invalid_request", idempotency_key=idempotency_key) from None
+        if encoded is not None:
+            headers["Content-Type"] = "application/json"
+        for attempt in range(self.__retries + 1):
+            try:
+                with self.__http.stream(method, ORIGIN + path, headers=headers, content=encoded, params=query) as response:
+                    if method == "GET" and response.status_code in RETRYABLE and attempt < self.__retries:
+                        wait = retry_delay(response.headers.get("retry-after"), attempt)
+                        if wait <= 60:
+                            response.close()
+                            self._sleep(wait)
+                            continue
+                    chunks, size = [], 0
+                    for chunk in response.iter_bytes():
+                        size += len(chunk)
+                        if size > 2 * 1024 * 1024:
+                            raise CuddlerError("response_too_large", idempotency_key=idempotency_key,
+                                               outcome_unknown=method != "GET")
+                        chunks.append(chunk)
+                    try:
+                        data = json.loads(b"".join(chunks))
+                    except (ValueError, UnicodeError):
+                        raise CuddlerError("invalid_response", status=response.status_code,
+                                           idempotency_key=idempotency_key, outcome_unknown=method != "GET") from None
+                    if not isinstance(data, dict):
+                        raise CuddlerError("invalid_response", idempotency_key=idempotency_key,
+                                           outcome_unknown=method != "GET")
+                    if not response.is_success:
+                        code = data.get("code")
+                        raise CuddlerError(code if isinstance(code, str) and code in CODES else "http_error",
+                            status=response.status_code, idempotency_key=idempotency_key,
+                            outcome_unknown=method != "GET" and (response.status_code == 408 or response.status_code >= 500))
+                    return data
+            except httpx.HTTPError:
+                if method == "GET" and attempt < self.__retries:
+                    self._sleep(retry_delay(None, attempt))
+                    continue
+                raise CuddlerError("network_error", idempotency_key=idempotency_key,
+                                   outcome_unknown=method != "GET") from None
+
+    def _create(self, path, body, key, prefix, require_cap=True):
+        key = key if key is not None else "sdk-" + str(uuid.uuid4())
+        if not isinstance(key, str) or not re.fullmatch(r"[A-Za-z0-9._:-]{8,128}", key):
+            raise CuddlerError("invalid_idempotency_key")
+        cap = body.get("max_usd") if isinstance(body, dict) else None
+        if require_cap and (not isinstance(cap, str) or not re.fullmatch(r"(?:0|[1-9]\d{0,8})(?:\.\d{1,6})?", cap) or float(cap) <= 0):
+            raise CuddlerError("max_usd_required", idempotency_key=key)
+        result = self._call("POST", path, body=body, idempotency_key=key)
+        try:
+            identity(result.get("id"), prefix)
+        except CuddlerError:
+            raise CuddlerError("invalid_response", idempotency_key=key, outcome_unknown=True) from None
+        return result

cuddler-0.1.0/cuddler.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: cuddler
+Version: 0.1.0
+Summary: Official Cuddler Platform client
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.28.1
+Dynamic: license-file
+
+# Cuddler Platform SDK
+
+Release candidate; npm/PyPI publication is pending registry authentication and release verification.
+Source is maintained in the private Cuddler repository; no public source repository is required.
+
+This client, intended to run in a developer's server environment, uses the native USD Platform API at `https://api.cuddler.ai/v1`.
+It supports video, images, speech, music, models, voices, balance, usage and the
+create/get/complete upload protocol. Media transfer is explicit: use the returned
+signed URL without an Authorization header. No provider key is required.
+
+## TypeScript / JavaScript
+
+```js
+import Cuddler from '@cuddler/platform';
+const client = new Cuddler({ apiKey: process.env.CUDDLER_API_KEY });
+const quote = await client.videos.estimate({
+  model: 'seedance-2.5', mode: 'text', variant: 'default',
+  duration: 4, resolution: '480p', aspect_ratio: '16:9', generate_audio: false,
+});
+const job = await client.videos.createAndWait({
+  model: 'seedance-2.5', mode: 'text', duration: 4, resolution: '480p',
+  aspect_ratio: '16:9', generate_audio: false,
+  prompt: 'An original blue clay robot waving.', max_usd: '1.00',
+}, { idempotencyKey: 'my-persisted-operation-001' });
+if (job.status !== 'succeeded') throw new Error(job.status);
+```
+
+`images`, `speech`, and `music` have the same create/retrieve/list/estimate/wait methods.
+Cancellation is available for videos, speech and music; images cannot be canceled.
+The server's current catalog and quotes determine available models and parameters.
+TypeScript request/response types come from the repository's generated OpenAPI contract.
+
+## Python
+
+```python
+from cuddler import Cuddler
+with Cuddler() as client:  # reads CUDDLER_API_KEY
+    models = client.models.list()
+    job = client.videos.retrieve('vid_REPLACE_WITH_YOUR_JOB_ID')
+```
+
+Python uses `create_and_wait`, `idempotency_key`, `timeout` and `poll_interval`.
+It is a synchronous httpx client; use a worker thread when calling it from an async app.
+
+## Recovery and spending
+
+- Every generation requires a positive decimal-string `max_usd`.
+- Each new create gets a fresh key. Persist and explicitly reuse a key and identical
+  request body for a durable business operation; otherwise another create is a new job.
+- POST calls are never retried automatically, including estimates and cancel calls.
+- On uncertain submission, `CuddlerError.idempotencyKey` (Python: `idempotency_key`)
+  carries the original key and `outcomeUnknown` / `outcome_unknown` is true.
+  Reconcile or replay that exact operation; do not create a new key blindly.
+- GET retries respect Retry-After (at most two retries by default). A delay over
+  60 seconds returns the error to the caller rather than retrying early.
+- Waiting returns terminal failed/canceled jobs as well as successes. A polling timeout
+  includes `jobId` / `job_id`; resume with retrieve/wait, never with a new create.
+  An in-flight HTTP read may finish after the polling deadline.
+- Keys remain server-side. The SDK does not write credentials, prompts or replay records
+  to disk. Applications are responsible for durable operation identity and recovery.
+
+## CLI
+
+Use `CUDDLER_API_KEY` in the environment; API keys are not accepted as command arguments.
+
+```sh
+npx @cuddler/platform models
+npx @cuddler/platform videos create --json request.json --idempotency-key episode-001 --wait
+```
+
+The CLI exits nonzero for failed/canceled jobs and emits safe recovery metadata on errors.
+
+The Python distribution also installs `cuddler-platform`; it does not require Node.js.
+For a local candidate wheel (PyPI installation becomes available after publication):
+
+```sh
+python -m pip install ./cuddler-0.1.0-py3-none-any.whl
+cuddler-platform --help
+python -m cuddler models
+python -m cuddler videos create --json request.json --idempotency-key episode-001 --wait
+```
+
+Both distributions use the same command name. Install Python into a virtual environment,
+or use `python -m cuddler` to select it explicitly. The commands, JSON result output and
+safe recovery error fields match the npm CLI. Use `--json` for private prompt content
+so it does not appear in shell history or process arguments. File transfer uses the
+returned signed URL without sending the API credential to the media host.
+
+## Build and release boundary
+
+The npm source package has a private workspace name because the platform web app already
+uses `@cuddler/platform` internally. `node scripts/build.mjs` produces a separate publishable
+`dist` manifest named `@cuddler/platform`, with only SDK code, contract types and docs.
+The Python source is in `packages/platform-sdk-python-public` and builds the package `cuddler`.
+The existing private adapter cores in Draft #5979 remain separate and unchanged.
+
+The SDK and CLI only implement API types, HTTP requests, queries, polling, error handling
+and recovery of the original operation. Model scheduling, server authorization, quota and
+settlement decisions, and provider credentials remain in the service. Published packages
+must run without access to this private repository and must not contain private backend
+implementation, runtime credentials or user data. JavaScript and Python client files in
+distributed packages remain inspectable; a private source repository does not hide them.
+
+### Distribution terms and publication status
+
+SDK and CLI packages are distributed under the MIT License. Keep the bundled LICENSE
+and copyright notice when copying or redistributing the software. The development
+repository remains private; this does not restrict the rights granted for the SDK
+files included in the packages. The license covers the distributed SDK, not private
+backend code, service access, account credentials or API usage charges.
+
+Both LICENSE files, the JavaScript source and generated package metadata, and Python
+pyproject.toml declare MIT. Before release, rebuild and inspect both archives and record
+their hashes against the private source commit. Public source hosting and npm provenance
+are not prerequisites for this phase. Installers need no private-repository access.
+
+Registry identities, package permissions and release authorization must be verified.
+After publication, verify clean installation of both SDKs and CLIs from the official npm
+and PyPI registries. Reuse matching live acceptance evidence; local builds are not proof
+of registry publication. Do not add paid generation tasks for these documentation changes.

cuddler-0.1.0/cuddler.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+cuddler/__init__.py
+cuddler/__main__.py
+cuddler/cli.py
+cuddler/client.py
+cuddler.egg-info/PKG-INFO
+cuddler.egg-info/SOURCES.txt
+cuddler.egg-info/dependency_links.txt
+cuddler.egg-info/entry_points.txt
+cuddler.egg-info/requires.txt
+cuddler.egg-info/top_level.txt
+tests/recovery-fixtures.json
+tests/test_client.py

cuddler-0.1.0/cuddler.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cuddler-0.1.0/cuddler.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cuddler-platform = cuddler.cli:main

cuddler-0.1.0/cuddler.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx<0.29,>=0.28.1

cuddler-0.1.0/cuddler.egg-info/top_level.txt

@@ -0,0 +1 @@
+cuddler

cuddler-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cuddler"
+version = "0.1.0"
+description = "Official Cuddler Platform client"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.28.1,<0.29"]
+
+[project.scripts]
+cuddler-platform = "cuddler.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["cuddler*"]

cuddler-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cuddler-0.1.0/tests/recovery-fixtures.json

@@ -0,0 +1,54 @@
+{
+  "cases": [
+    {
+      "kind": "videos",
+      "id": "vid_SYNTHETIC000000000000",
+      "body": {
+        "model": "fixture-model",
+        "prompt": "synthetic fixture",
+        "max_usd": "0.50"
+      },
+      "idempotencyKey": "fixture-videos-001"
+    },
+    {
+      "kind": "images",
+      "id": "img_SYNTHETIC000000000000",
+      "body": {
+        "model": "fixture-model",
+        "prompt": "synthetic fixture",
+        "max_usd": "0.50"
+      },
+      "idempotencyKey": "fixture-images-001"
+    },
+    {
+      "kind": "speech",
+      "id": "aud_SYNTHETIC000000000000",
+      "body": {
+        "model": "fixture-model",
+        "prompt": "synthetic fixture",
+        "max_usd": "0.50"
+      },
+      "idempotencyKey": "fixture-speech-001"
+    },
+    {
+      "kind": "music",
+      "id": "mus_SYNTHETIC000000000000",
+      "body": {
+        "model": "fixture-model",
+        "prompt": "synthetic fixture",
+        "max_usd": "0.50"
+      },
+      "idempotencyKey": "fixture-music-001"
+    }
+  ],
+  "errors": [
+    {
+      "status": 401,
+      "code": "unauthorized"
+    },
+    {
+      "status": 409,
+      "code": "idempotency_conflict"
+    }
+  ]
+}

cuddler-0.1.0/tests/test_client.py

@@ -0,0 +1,246 @@
+import json
+import io
+import os
+import subprocess
+import sys
+import sysconfig
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+from unittest.mock import patch
+import httpx
+from cuddler import Cuddler, CuddlerError
+from cuddler.cli import main
+
+KEY = "cud_sk_live_SYNTHETIC0000000000000000"
+JOB = "vid_SYNTHETIC000000000000"
+BODY = {"model": "seedance-2.5", "prompt": "synthetic", "duration": 4, "max_usd": "1"}
+
+
+class ClientTests(unittest.TestCase):
+    def client(self, handler, **kwargs):
+        client = Cuddler(KEY, transport=httpx.MockTransport(handler), **kwargs)
+        self.addCleanup(client.close)
+        return client
+
+    def test_four_resources_and_recovery_identity(self):
+        requests = []
+        def handle(request):
+            requests.append(request)
+            prefix = {"videos": "vid", "images": "img", "speech": "aud", "music": "mus"}[request.url.path.split("/")[-1]]
+            return httpx.Response(200, json={"id": prefix + "_SYNTHETIC000000000000", "status": "queued"})
+        client = self.client(handle)
+        for kind in ("videos", "images", "speech", "music"):
+            getattr(client, kind).create(BODY)
+        self.assertEqual(len({r.headers["idempotency-key"] for r in requests}), 4)
+        for _ in range(2):
+            client.videos.create(BODY, idempotency_key="operation-123")
+        self.assertEqual(requests[-1].headers["idempotency-key"], requests[-2].headers["idempotency-key"])
+        self.assertTrue(all(r.url.host == "api.cuddler.ai" for r in requests))
+        self.assertFalse(hasattr(client.images, "cancel"))
+
+    def test_lost_response_never_resubmits(self):
+        requests = []
+        def handle(request):
+            requests.append(request)
+            raise httpx.ReadTimeout(KEY)
+        with self.assertRaises(CuddlerError) as caught:
+            self.client(handle).videos.create(BODY)
+        self.assertEqual(len(requests), 1)
+        error = caught.exception
+        self.assertTrue(error.outcome_unknown)
+        self.assertTrue(error.idempotency_key.startswith("sdk-"))
+        self.assertNotIn(KEY, str(error))
+        self.assertNotIn(KEY, json.dumps(vars(error)))
+
+    def test_read_retries_obey_retry_after(self):
+        requests, sleeps = [], []
+        def handle(request):
+            requests.append(request)
+            return httpx.Response(429, json={"code": "rate_limited"}, headers={"Retry-After": "3"}) if len(requests) == 1 else httpx.Response(200, json={"data": []})
+        self.client(handle, sleep=sleeps.append).models.list()
+        self.assertEqual(sleeps, [3])
+        self.assertEqual(len(requests), 2)
+
+    def test_terminal_failure_and_wait_only_get(self):
+        methods = []
+        def handle(request):
+            methods.append(request.method)
+            return httpx.Response(200, json={"id": JOB, "status": "failed" if len(methods) == 3 else "running"})
+        job = self.client(handle, sleep=lambda _: None).videos.create_and_wait(BODY)
+        self.assertEqual(job["status"], "failed")
+        self.assertEqual(methods, ["POST", "GET", "GET"])
+
+    def test_caps_and_ids_fail_before_http(self):
+        def handle(_):
+            self.fail("unexpected request")
+        client = self.client(handle)
+        for cap in (None, 1, "0", "-1", "1.0000001"):
+            with self.assertRaises(CuddlerError):
+                client.images.create(BODY | {"max_usd": cap})
+        with self.assertRaises(CuddlerError):
+            client.videos.retrieve("../balance")
+
+    def test_redirect_is_not_followed_and_errors_do_not_include_server_prose(self):
+        requests = []
+        def handle(request):
+            requests.append(request)
+            return httpx.Response(302, json={"code": KEY, "message": BODY["prompt"]}, headers={"Location": "https://example.org"})
+        with self.assertRaises(CuddlerError) as caught:
+            self.client(handle).models.list()
+        self.assertEqual(len(requests), 1)
+        self.assertEqual(caught.exception.code, "http_error")
+
+    def test_invalid_wait_options_and_interrupted_poll_recovery(self):
+        methods = []
+        def handle(request):
+            methods.append(request.method)
+            if request.method == "POST":
+                return httpx.Response(200, json={"id": JOB, "status": "queued"})
+            raise httpx.ReadTimeout("interrupted")
+        client = self.client(handle, max_retries=0)
+        with self.assertRaises(CuddlerError):
+            client.videos.create_and_wait(BODY, timeout=0)
+        self.assertEqual(methods, [])
+        with self.assertRaises(CuddlerError) as caught:
+            client.videos.create_and_wait(BODY)
+        self.assertEqual(caught.exception.job_id, JOB)
+        self.assertFalse(caught.exception.outcome_unknown)
+        self.assertEqual(methods, ["POST", "GET"])
+
+
+    def test_shared_media_recovery_fixtures(self):
+        fixture_path = Path(__file__).with_name("recovery-fixtures.json")
+        fixtures = json.loads(fixture_path.read_text())
+        for fixture in fixtures["cases"]:
+            with self.subTest(kind=fixture["kind"]):
+                calls = []
+                def handle(request):
+                    calls.append(request.method)
+                    suffix = "/" + fixture["id"] if request.method == "GET" else ""
+                    self.assertEqual(request.url.path, "/v1/" + fixture["kind"] + suffix)
+                    if request.method == "POST":
+                        self.assertEqual(request.headers["Idempotency-Key"], fixture["idempotencyKey"])
+                        self.assertEqual(json.loads(request.content), fixture["body"])
+                        if len(calls) == 1:
+                            raise httpx.ReadError("synthetic lost response")
+                    return httpx.Response(200, json={"id": fixture["id"], "status": "queued" if request.method == "POST" else "failed"})
+                resource = getattr(self.client(handle), fixture["kind"])
+                with self.assertRaises(CuddlerError) as caught:
+                    resource.create(fixture["body"], idempotency_key=fixture["idempotencyKey"])
+                self.assertEqual(caught.exception.code, "network_error")
+                self.assertTrue(caught.exception.outcome_unknown)
+                self.assertEqual(caught.exception.idempotency_key, fixture["idempotencyKey"])
+                self.assertEqual(len(calls), 1)
+                self.assertEqual(resource.create(fixture["body"], idempotency_key=fixture["idempotencyKey"])["id"], fixture["id"])
+                self.assertEqual(resource.wait(fixture["id"])["status"], "failed")
+                self.assertEqual(calls, ["POST", "POST", "GET"])
+        for fixture in fixtures["errors"]:
+            with self.subTest(status=fixture["status"]):
+                calls = []
+                def handle(request):
+                    calls.append(request.method)
+                    return httpx.Response(fixture["status"], json={"code": fixture["code"]})
+                with self.assertRaises(CuddlerError) as caught:
+                    self.client(handle).videos.create(BODY, idempotency_key="operation-123")
+                self.assertEqual(caught.exception.code, fixture["code"])
+                self.assertEqual(caught.exception.status, fixture["status"])
+                self.assertFalse(caught.exception.outcome_unknown)
+                self.assertEqual(calls, ["POST"])
+
+
+class CliTests(unittest.TestCase):
+    def invoke(self, args, handler=None):
+        def unexpected(_request):
+            self.fail("unexpected HTTP request")
+        client = Cuddler(KEY, transport=httpx.MockTransport(handler or unexpected),
+                         sleep=lambda _: None, max_retries=0)
+        stdout, stderr = io.StringIO(), io.StringIO()
+        with patch("cuddler.cli.Cuddler", return_value=client), redirect_stdout(stdout), redirect_stderr(stderr):
+            try:
+                code = main(args)
+            finally:
+                client.close()
+        return code, stdout.getvalue(), stderr.getvalue()
+
+    def test_installed_console_and_module_help_without_credentials(self):
+        script = Path(sysconfig.get_path("scripts")) / ("cuddler-platform.exe" if os.name == "nt" else "cuddler-platform")
+        env = {k: v for k, v in os.environ.items() if k != "CUDDLER_API_KEY"}
+        for command in ([str(script), "--help"], [sys.executable, "-m", "cuddler", "--help"]):
+            with self.subTest(command=command):
+                result = subprocess.run(command, capture_output=True, text=True, env=env, timeout=10)
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertIn("--idempotency-key", result.stdout)
+                self.assertEqual(result.stderr, "")
+
+    def test_models_and_original_job_reads(self):
+        paths = []
+        def handle(request):
+            paths.append(request.url.path)
+            self.assertEqual(request.method, "GET")
+            return httpx.Response(200, json={"data": []} if request.url.path.endswith("models") else {"id": JOB, "status": "succeeded"})
+        for args in (["models"], ["videos", "get", JOB]):
+            code, stdout, stderr = self.invoke(args, handle)
+            self.assertEqual(code, 0)
+            self.assertIsInstance(json.loads(stdout), dict)
+            self.assertEqual(stderr, "")
+        self.assertEqual(paths, ["/v1/models", "/v1/videos/" + JOB])
+
+    def test_shared_four_media_create_and_wait(self):
+        fixtures = json.loads(Path(__file__).with_name("recovery-fixtures.json").read_text())
+        with tempfile.TemporaryDirectory() as directory:
+            request_file = Path(directory) / "request.json"
+            for fixture in fixtures["cases"]:
+                with self.subTest(kind=fixture["kind"]):
+                    request_file.write_text(json.dumps(fixture["body"]))
+                    methods = []
+                    def handle(request):
+                        methods.append(request.method)
+                        if request.method == "POST":
+                            self.assertEqual(json.loads(request.content), fixture["body"])
+                            self.assertEqual(request.headers["Idempotency-Key"], fixture["idempotencyKey"])
+                        return httpx.Response(200, json={"id": fixture["id"], "status": "queued" if request.method == "POST" else "failed"})
+                    code, stdout, stderr = self.invoke([fixture["kind"], "create", "--json", str(request_file),
+                        "--idempotency-key", fixture["idempotencyKey"], "--wait"], handle)
+                    self.assertEqual(code, 1)
+                    self.assertEqual(json.loads(stdout)["id"], fixture["id"])
+                    self.assertEqual(stderr, "")
+                    self.assertEqual(methods, ["POST", "GET"])
+
+    def test_uncertain_create_is_once_and_emits_only_recovery_metadata(self):
+        requests = []
+        def handle(request):
+            requests.append(request)
+            raise httpx.ReadTimeout(KEY + BODY["prompt"])
+        code, stdout, stderr = self.invoke(["videos", "create", "--model", BODY["model"],
+            "--prompt", BODY["prompt"], "--duration", "4", "--max-usd", "1",
+            "--idempotency-key", "operation-123"], handle)
+        self.assertEqual(len(requests), 1)
+        self.assertEqual(json.loads(requests[0].content), BODY)
+        self.assertEqual(code, 1)
+        self.assertEqual(stdout, "")
+        self.assertEqual(json.loads(stderr), {"code": "network_error", "status": None,
+            "idempotencyKey": "operation-123", "outcomeUnknown": True, "jobId": None})
+        self.assertNotIn(KEY, stderr)
+        self.assertNotIn(BODY["prompt"], stderr)
+
+    def test_invalid_input_never_calls_api_or_echoes_secrets(self):
+        with tempfile.TemporaryDirectory() as directory:
+            request_file = Path(directory) / "request.json"
+            request_file.write_text('{"prompt": "' + KEY)
+            cases = [["models", "--api-key", KEY], ["videos", "create", "--json", str(request_file)],
+                     ["videos", "create", "--duration", "NaN"], ["videos", "get", "../balance"],
+                     ["videos", "create", "--max-usd", "0"], ["videos", "create", "extra"]]
+            for args in cases:
+                with self.subTest(args=args):
+                    code, stdout, stderr = self.invoke(args)
+                    self.assertEqual(code, 1)
+                    self.assertEqual(stdout, "")
+                    self.assertNotIn(KEY, stderr)
+                    self.assertNotIn(str(request_file), stderr)
+                    self.assertIn("code", json.loads(stderr))
+
+
+if __name__ == "__main__":
+    unittest.main()