comfy-sdk 0.1.0__tar.gz

comfy_sdk-0.1.0/.coderabbit.yaml

@@ -0,0 +1,62 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: "en-US"
+early_access: false
+tone_instructions: |
+  This is a public Python SDK (ComfyPythonSDK). CI already runs
+  `ruff check`, `ruff format --check`, and `mypy` on every PR — do not repeat
+  their findings or nitpick style/formatting. Focus on public API stability
+  (this SDK is consumed by external users, so flag breaking changes to
+  public method signatures or types), correct error handling for network
+  calls, and clear type hints on the public surface. Only comment on issues
+  introduced by this PR's changes; do not flag pre-existing problems in
+  moved, re-indented, or reformatted code.
+
+reviews:
+  profile: "assertive"
+  request_changes_workflow: true
+  high_level_summary: true
+  poem: false
+  review_status: true
+  commit_status: true
+  collapse_walkthrough: true
+
+  auto_review:
+    enabled: true
+    auto_incremental_review: true
+    drafts: false
+    ignore_title_keywords:
+      - "WIP"
+      - "DO NOT MERGE"
+
+  path_filters:
+    - "!**/__pycache__/**"
+    - "!**/*.pyc"
+    - "!**/*.egg-info/**"
+    - "!.venv/**"
+
+  path_instructions:
+    - path: "src/comfy_sdk/**"
+      instructions: |
+        Public SDK surface. Focus on:
+        - Backward compatibility of public classes/functions (this is a
+          published SDK; breaking a signature breaks every consumer)
+        - Correct error handling and clear exceptions for network/API failures
+        - Type hints kept accurate and exported where part of the public API
+    - path: "tests/**"
+      instructions: |
+        Verify tests exercise the described behavior rather than just
+        asserting current output (no change-detector tests).
+
+  tools:
+    ruff:
+      enabled: false
+    gitleaks:
+      enabled: true
+    github-checks:
+      enabled: true
+      timeout_ms: 90000
+    ast-grep:
+      essential_rules: true
+
+chat:
+  auto_reply: true

comfy_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package with dev dependencies
+        run: pip install -e .[dev]
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Check formatting with ruff
+        run: ruff format --check .
+
+      - name: Type check with mypy
+        run: mypy src
+
+      - name: Run tests
+        run: pytest -v
+
+  codegen-drift:
+    name: comfy_low codegen drift
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: pyproject.toml
+
+      - name: Install codegen dependencies
+        run: pip install -e .[codegen]
+
+      - name: Regenerate models and fail on drift
+        run: python scripts/check_drift.py
+
+  # NEW -- publish dry run: catches a broken sdist/wheel in PR CI instead of
+  # at actual release time. publish.yml itself stays disabled (if: false);
+  # this job only builds and inspects the artifact, it never uploads it.
+  build-check:
+    name: build-check (publish dry run)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build tooling
+        run: pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify distribution metadata (publish dry run)
+        run: twine check dist/*
+
+  # NEW -- regression guard for the internal-reference leak this repo already
+  # had once (see scripts/check_public_repo_hygiene.py for what it looks for
+  # and why). Public repo, so this stays a permanent gate, not a one-time fix.
+  public-repo-hygiene:
+    name: public-repo-hygiene
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+
+      - name: Scan for internal-only references
+        run: python3 scripts/check_public_repo_hygiene.py

comfy_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,157 @@
+# Publishes `comfy-sdk` to PyPI.
+#
+# Tag-driven versioning: the release tag (vX.Y.Z) is the single source of truth
+# for the published version. It is injected into pyproject.toml at build time,
+# so the committed version there is just a placeholder — to release a version,
+# create a GitHub Release with the tag you want; no version-bump commit needed.
+#
+# Trigger: a GitHub Release being published (tag vX.Y.Z). That's the only
+# path that reaches the `publish` job below. `workflow_dispatch` is a dry
+# run only — it exercises `build` (compile + `twine check`) but never
+# reaches `publish`, so it's safe to run against any branch to sanity-check
+# the pipeline before cutting a real release.
+#
+# Auth: PyPI Trusted Publishing (OIDC) — no PYPI_TOKEN / API token secret is
+# stored in this repo. See "Maintainer setup" in the PR description / repo
+# docs for the one-time PyPI-side configuration this depends on.
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Git ref to build for a dry run (build + twine check only — this input never reaches the publish job)'
+        required: false
+        type: string
+        default: ''
+      publish_to_testpypi:
+        description: 'Also upload the built dist to TestPyPI (requires the optional "testpypi" environment + Trusted Publisher — see Maintainer setup)'
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.workflow }}-${{ github.event.release.tag_name || github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  # Runs for every trigger. Builds the exact sdist/wheel that `publish` will
+  # upload and validates it with twine. This IS the workflow_dispatch dry
+  # run: trigger this workflow manually via the Actions tab and you get this
+  # job (and nothing else, since `publish` requires a `release` event).
+  build:
+    name: Build and check distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ github.event.inputs.ref || github.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+
+      - name: Install build tooling
+        run: pip install build twine
+
+      # Tag-driven versioning: the release tag (vX.Y.Z) is the source of truth.
+      # Inject it into pyproject.toml before building so the published artifact
+      # carries the tag's version. (On a workflow_dispatch dry run there is no
+      # release tag; the committed placeholder version is built as-is.)
+      - name: Set version from release tag
+        if: github.event_name == 'release'
+        shell: bash
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          VERSION="${TAG#v}"
+          # Full SemVer 2.0: X.Y.Z, with an optional -prerelease and an
+          # optional +build-metadata segment (both may be present together).
+          if ! printf '%s' "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$'; then
+            echo "::error::Release tag '${TAG}' is not a valid version (expected vX.Y.Z)."
+            exit 1
+          fi
+          python3 - "$VERSION" <<'PY'
+          import re, sys
+          version = sys.argv[1]
+          p = "pyproject.toml"
+          s = open(p, encoding="utf-8").read()
+          s2, n = re.subn(r'(?m)^version = "[^"]+"$', f'version = "{version}"', s, count=1)
+          if n != 1:
+              raise SystemExit('could not find a top-level version = "..." line in pyproject.toml')
+          open(p, "w", encoding="utf-8").write(s2)
+          print(f"Set pyproject.toml version = {version}")
+          PY
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify distribution metadata (twine check)
+        run: twine check dist/*
+
+      - name: Upload built distribution
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: pypi-dist
+          path: dist/
+          retention-days: 7
+
+  publish:
+    name: Publish to PyPI
+    needs: [build]
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    # Manual approval gate: create this environment in
+    # Settings -> Environments with required reviewers, so every publish
+    # needs a human click even though the trigger (release published) is
+    # automatic. See "Maintainer setup" for the one-time steps.
+    environment: pypi
+    permissions:
+      id-token: write # OIDC for PyPI Trusted Publishing — no API token secret
+      contents: read
+    steps:
+      - name: Download built distribution
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        with:
+          packages-dir: dist/
+          skip-existing: true # idempotent re-runs: no-op instead of erroring if this version is already up
+
+  # Nice-to-have: exercise the full OIDC publish path against TestPyPI
+  # without touching real PyPI. Opt-in via workflow_dispatch input; needs
+  # its own Trusted Publisher + "testpypi" environment (see Maintainer setup).
+  publish-testpypi:
+    name: Publish to TestPyPI (dry run)
+    needs: [build]
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.publish_to_testpypi == 'true'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download built distribution
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        with:
+          packages-dir: dist/
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true

comfy_sdk-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/

comfy_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: comfy-sdk
+Version: 0.1.0
+Summary: Python SDK for running ComfyUI workflows via the Comfy API v2 (self-hosted, Comfy Cloud, serverless).
+Requires-Python: >=3.10
+Requires-Dist: blake3>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: codegen
+Requires-Dist: datamodel-code-generator~=0.68.1; extra == 'codegen'
+Requires-Dist: pyyaml>=6; extra == 'codegen'
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator~=0.68.1; extra == 'dev'
+Requires-Dist: mypy~=2.3.0; extra == 'dev'
+Requires-Dist: pillow>=10; extra == 'dev'
+Requires-Dist: pytest-asyncio~=1.4.0; extra == 'dev'
+Requires-Dist: pytest~=9.1.1; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff~=0.15.22; extra == 'dev'
+Provides-Extra: pil
+Requires-Dist: pillow>=10; extra == 'pil'
+Description-Content-Type: text/markdown
+
+# comfy-sdk (Python)
+
+Python SDK for running ComfyUI workflows via the **Comfy API v2**. The same
+code runs against a self-hosted ComfyUI, Comfy Cloud, or a serverless
+deployment — only the base URL and an optional API key change.
+
+```python
+from comfy_sdk import Comfy
+
+client = Comfy("http://127.0.0.1:8189")                          # self-hosted, no key
+# client = Comfy("https://api.comfy.org", api_key="ck_...")        # Comfy Cloud
+
+wf = client.workflows.from_file("workflow_api.json")
+
+# Lazy asset handle: hashed locally with blake3, deduped against the server's
+# fast-path (mint over existing bytes), or streamed-uploaded on a miss — then
+# substituted into the graph as a core/ASSET reference.
+asset = client.assets.from_file("photo.png")
+wf.set_input("10", "image", asset)
+
+job = client.run(wf)                 # submit, then poll to a terminal state
+job.get_outputs("13")[0].to_file("out.png")
+```
+
+## Requirements and install
+
+Requires **Python 3.10+**. Dependencies: `httpx`, `blake3`, `pydantic` (v2).
+
+```bash
+pip install comfy-sdk
+```
+
+Releases are published to PyPI from a GitHub Release (tag `vX.Y.Z`) by
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml), using
+PyPI's Trusted Publishing (OIDC) — no API token is stored in this repo.
+
+To install from source instead (for local development, or to track an
+unreleased commit):
+
+```bash
+git clone https://github.com/Comfy-Org/ComfyPythonSDK
+cd ComfyPythonSDK
+pip install -e .
+# with everything needed to lint/type-check/test locally:
+pip install -e ".[dev]"
+```
+
+`Preview.to_pil()` (decoding an in-progress SSE preview frame to a `PIL.Image`)
+needs the optional `pil` extra: `pip install -e ".[pil]"`.
+
+## Authentication — one client, per-surface key
+
+| Surface | Example base URL | `api_key` |
+|---|---|---|
+| Self-hosted ComfyUI (behind the API proxy) | `http://127.0.0.1:8189` | Omit — no key is sent, even implicitly |
+| Comfy Cloud | `https://api.comfy.org` | Required |
+| Serverless deployment | `https://<deployment>.comfy.org` | Required |
+
+```python
+client = Comfy("http://127.0.0.1:8189")                       # self-hosted
+client = Comfy("https://api.comfy.org", api_key="ck_...")     # Comfy Cloud / serverless
+```
+
+`AsyncComfy` takes the same two arguments. A key is only ever attached to
+requests aimed at the configured `base_url`'s own origin — a server-returned
+follow-up link (`job.urls.self`/`cancel`/`events`, or a redirected asset
+download) pointing anywhere else never receives it.
+
+## Assets and `core/ASSET`
+
+`client.assets.from_file(...)` / `from_bytes(...)` / `from_stream(...)` /
+`from_url(...)` return a **lazy** asset handle immediately — no network call
+yet. Embed it directly into the workflow graph:
+
+```python
+asset = client.assets.from_file("photo.png")
+wf.set_input("10", "image", asset)
+```
+
+On first use (submitting the workflow, or an explicit `asset.commit()`), the
+SDK:
+
+1. hashes the bytes locally with blake3;
+2. probes the server's dedup fast-path — a `HEAD` existence check by hash,
+   then a cheap `from-hash` mint if the server already has those bytes;
+3. only streams a full multipart upload on a miss.
+
+At submit time, every asset handle found anywhere in the graph is replaced by
+a `core/ASSET` reference object (`{"__type": "core/ASSET", "info": {"id":
+..., "hash": ..., "file_path": ...}}`), which the server resolves back to the
+uploaded asset when it runs the workflow.
+
+## Live progress
+
+```python
+job = client.submit(wf)
+for event in job.events():          # SSE; live, auto-reconnecting (no replay)
+    match event:
+        case Progress() as p:       print(f"{p.value:.0%} {p.message}")
+        case Preview() as pv:       show(pv.to_pil())
+        case OutputReady() as o:    o.output.to_file(f"partial/{o.output.name}")
+        case StatusChange(status="succeeded"): break
+result = job.result()               # raises JobFailed with node details on failure
+```
+
+`job.events()` reconnects automatically if the stream drops, but never
+replays a frame you've already seen (the stream carries no cursor). That's
+why polling stays authoritative: `job.wait()` / `job.result()` (and
+`client.run()`, which is `submit()` + `result()`) always fall back to
+`GET /jobs/{id}` to decide when a job is really done — use `events()` for
+live UI feedback, and `wait()`/`result()`/`run()` for the definitive answer.
+`job.status` is the current status string; `job.outputs` is the full list of
+output handles regardless of which node produced them (`job.get_outputs(node_id)`
+filters to one node, as in the quickstart above).
+
+## Sync and async
+
+`Comfy` and `AsyncComfy` expose the identical surface — swap the import and
+add `await` / `async for`:
+
+```python
+from comfy_sdk import AsyncComfy
+
+async def main() -> None:
+    async with AsyncComfy("http://127.0.0.1:8189") as client:
+        wf = client.workflows.from_file("workflow_api.json")
+        job = await client.run(wf)
+        await job.outputs[0].to_file("out.png")
+```
+
+## Typed errors
+
+`comfy_sdk` translates the API's error envelope into a small set of
+exceptions, all importable from the top-level package and all subclasses of
+`ComfyError`:
+
+- `Unauthorized`, `Forbidden`, `NotFound` — auth and lookup failures.
+- `InvalidWorkflow`, `WorkflowFormatUi` — the graph itself was rejected;
+  `WorkflowFormatUi` specifically means a UI-export (`nodes`/`links`/
+  `last_node_id`) was submitted instead of the API-format graph — the SDK
+  catches this locally before it ever reaches the server.
+- `MissingAsset` — a `core/ASSET` reference could not be resolved.
+- `HashMismatch`, `BlobNotFound` — asset upload/dedup failures.
+- `IdempotencyKeyReuse` — the `Idempotency-Key` was reused. `submit()` (and
+  `run()`) attach a fresh key to every call, so an accidental exact resend never
+  runs the workflow twice. Keys are single-use — reject-on-duplicate, there is
+  no replay — so if you pass your own `idempotency_key=` and reuse it, the second
+  call raises this. After an ambiguous failure (e.g. a timeout where you don't
+  know if the job was created), poll or list your jobs rather than resubmitting
+  with the same key.
+- `InsufficientCredits` — the account can't afford the job.
+- `QueueFull` — backpressure; carries `.retry_after` seconds. `client.submit`
+  already retries this automatically for a bounded budget before giving up
+  and raising it.
+- `JobFailed` — a job reached a non-`succeeded` terminal state; `.error`
+  carries node-level detail when the platform provided one.
+
+```python
+from comfy_sdk import JobFailed, QueueFull, Unauthorized
+
+try:
+    result = client.run(wf)
+except JobFailed as e:
+    print(e.error)
+except Unauthorized:
+    print("check your api_key")
+```
+
+## Architecture — two layers
+
+* **`comfy_low`** — generated protocol bindings. Pydantic v2 models generated
+  from `spec/openapi.yaml` (`src/comfy_low/models/_generated.py`, committed;
+  regenerate with `scripts/gen_models.sh`, CI fails on drift) plus a thin
+  hand-written `httpx` transport (sync + async), one function per `operationId`,
+  with the mandatory escape hatches: raw response access, unbuffered/streaming
+  bodies, all headers, and per-request timeout/abort. Boring and replaceable.
+
+* **`comfy_sdk`** — the idiomatic layer integrators import. This is where the
+  value lives: blake3 content-addressed dedup-upload, `core/ASSET`
+  substitution, idempotent submit, live SSE with reconnect, poll-authoritative
+  `run()`, range-aware downloads, and typed exceptions mapping the error
+  envelope.
+
+`spec/openapi.yaml` is a one-way vendored copy of the canonical Comfy API v2
+contract — do not hand-edit it (see `spec/README.md`). It's synced
+periodically from that canonical contract, stripped of anything tagged
+`internal`, and pinned by `spec/VERSION`.
+
+## Related projects
+
+Part of the same SDK family: a TypeScript client with the equivalent surface
+for JS/Node integrators, and the local API proxy that fronts a self-hosted
+ComfyUI instance with this same v2 contract (`comfy-api-proxy` in the
+`servers` list of `spec/openapi.yaml`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+mypy src
+pytest -v
+```
+
+Regenerating and checking the vendored protocol layer (a separate CI job):
+
+```bash
+pip install -e ".[codegen]"
+python scripts/gen_models.sh     # regenerate comfy_low models from spec/openapi.yaml
+python scripts/check_drift.py    # same check CI runs; fails if committed models drifted
+```