cuddler 0.1.0__py3-none-any.whl

cuddler/__init__.py

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

cuddler/__main__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+cuddler/__init__.py,sha256=l6zzOJCo9xTGP8sin5e34QErZChTlaM9FY-OVXdq0LA,81
+cuddler/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+cuddler/cli.py,sha256=gKXQliJuHdzS_oYqfE5UrrfzUYPnTsTnZZJD4C2s6pg,3504
+cuddler/client.py,sha256=PMmuXH2QditFoHxvaVt8T7KIeUcq7J6dI4PMeE_GMN4,9758
+cuddler-0.1.0.dist-info/licenses/LICENSE,sha256=kxGEHMeUdQSuj4rDdM18R0JvCb3p-6aC23dF0OqToH0,1064
+cuddler-0.1.0.dist-info/METADATA,sha256=V-BPT7uoFMB6WzvFEacbcSN7gNm7bcm-ON1BcXFs0bI,6703
+cuddler-0.1.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
+cuddler-0.1.0.dist-info/entry_points.txt,sha256=h_3O0W1Ki0Tc4kBsISUvweMsMTMzuLF2KYT9RiMQOc8,54
+cuddler-0.1.0.dist-info/top_level.txt,sha256=vZy8-38jKGrfeAoj2ObmMdyaTIEoxTAIYz5x0gkXg4s,8
+cuddler-0.1.0.dist-info/RECORD,,

cuddler-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cuddler-0.1.0.dist-info/entry_points.txt

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

cuddler-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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