comfy-sdk 0.1.0__py3-none-any.whl

comfy_low/__init__.py

@@ -0,0 +1,86 @@
+"""``comfy_low`` — generated + thin-transport protocol bindings for Comfy API v2.
+
+Two parts:
+
+* ``comfy_low.models`` — pydantic v2 models generated from ``spec/openapi.yaml``
+  (do not hand-edit; regenerate with ``scripts/gen_models.sh``).
+* ``comfy_low.transport`` — a hand-written thin ``httpx`` transport (sync +
+  async) with one function per ``operationId`` and the mandatory escape hatches
+  (raw response, streaming bodies, all headers, per-request timeout/abort).
+
+This layer is deliberately boring: no orchestration, retries, hashing, or SSE
+reconnection. Those live in ``comfy_sdk``.
+"""
+
+from __future__ import annotations
+
+from . import models
+from .errors import (
+    ApiError,
+    BlobNotFound,
+    Forbidden,
+    HashMismatch,
+    IdempotencyKeyReuse,
+    InsufficientCredits,
+    InvalidWorkflow,
+    MissingAsset,
+    NotFound,
+    QueueFull,
+    Unauthorized,
+    WorkflowFormatUi,
+    error_from_envelope,
+)
+from .sse import RawEvent, SSEDecoder
+from .transport import AsyncComfyLow, ComfyLow
+
+# The exact set of operationIds the transport must cover; the spec-coverage test
+# asserts this equals the set of operationIds in spec/openapi.yaml.
+OPERATION_IDS: frozenset[str] = frozenset(
+    {
+        "postAssets",
+        "assetFromHash",
+        "headAssetByHash",
+        "getAsset",
+        "getAssetContent",
+        "postJobs",
+        "getJob",
+        "getJobEvents",
+        "cancelJob",
+    }
+)
+
+# operationId -> transport method name (same mapping for sync and async).
+OPERATION_METHODS: dict[str, str] = {
+    "postAssets": "post_assets",
+    "assetFromHash": "asset_from_hash",
+    "headAssetByHash": "head_asset_by_hash",
+    "getAsset": "get_asset",
+    "getAssetContent": "get_asset_content",
+    "postJobs": "post_jobs",
+    "getJob": "get_job",
+    "getJobEvents": "get_job_events",
+    "cancelJob": "cancel_job",
+}
+
+__all__ = [
+    "models",
+    "ComfyLow",
+    "AsyncComfyLow",
+    "RawEvent",
+    "SSEDecoder",
+    "ApiError",
+    "InvalidWorkflow",
+    "WorkflowFormatUi",
+    "MissingAsset",
+    "HashMismatch",
+    "BlobNotFound",
+    "IdempotencyKeyReuse",
+    "QueueFull",
+    "InsufficientCredits",
+    "NotFound",
+    "Unauthorized",
+    "Forbidden",
+    "error_from_envelope",
+    "OPERATION_IDS",
+    "OPERATION_METHODS",
+]

comfy_low/_multipart.py

@@ -0,0 +1,99 @@
+"""Streaming ``multipart/form-data`` body construction.
+
+OpenAPI codegen routinely buffers an entire upload into memory to build the
+request body; this module is the hand-written alternative the contract calls for.
+The body is produced as a generator of byte chunks that reads the file part
+lazily, and — when the file size is known — the exact Content-Length is computed
+up front so the request streams instead of buffering.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from typing import BinaryIO
+
+CHUNK_SIZE = 64 * 1024
+
+
+def _field_part(boundary: str, name: str, value: str) -> bytes:
+    return (
+        f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'
+    ).encode()
+
+
+def _file_header(boundary: str, name: str, filename: str, content_type: str) -> bytes:
+    return (
+        f"--{boundary}\r\n"
+        f'Content-Disposition: form-data; name="{name}"; filename="{filename}"\r\n'
+        f"Content-Type: {content_type}\r\n\r\n"
+    ).encode()
+
+
+def _closing(boundary: str) -> bytes:
+    return f"--{boundary}--\r\n".encode()
+
+
+def build_multipart(
+    boundary: str,
+    *,
+    fields: list[tuple[str, str]],
+    file_name: str,
+    file_obj: BinaryIO,
+    file_content_type: str,
+    file_size: int | None,
+    chunk_size: int = CHUNK_SIZE,
+) -> tuple[Iterator[bytes], int | None]:
+    """Return ``(body_iterator, content_length)``.
+
+    ``fields`` is a list of ``(name, value)`` pairs rather than a ``dict`` so a
+    repeatable field (e.g. ``tags``) can appear more than once — the standard
+    multipart/form-data convention for sending a list — without one value
+    clobbering another under the same key.
+
+    ``content_length`` is ``None`` when ``file_size`` is unknown (the caller then
+    lets the client fall back to chunked transfer encoding). The file object is
+    read in ``chunk_size`` slices — never with a size-less ``read()`` — so a
+    multi-GB file never lands in memory whole.
+    """
+    text_fields = b"".join(_field_part(boundary, name, value) for name, value in fields)
+    file_hdr = _file_header(boundary, "file", file_name, file_content_type)
+    closing = _closing(boundary)
+
+    content_length: int | None = None
+    if file_size is not None:
+        content_length = len(text_fields) + len(file_hdr) + file_size + len(b"\r\n") + len(closing)
+
+    def _iter() -> Iterator[bytes]:
+        yield text_fields
+        yield file_hdr
+        while True:
+            chunk = file_obj.read(chunk_size)
+            if not chunk:
+                break
+            yield chunk
+        yield b"\r\n"
+        yield closing
+
+    return _iter(), content_length
+
+
+def file_size_of(file_obj: BinaryIO) -> int | None:
+    """Best-effort size of a seekable file object, else ``None``."""
+    try:
+        fd = file_obj.fileno()
+    except (OSError, AttributeError):
+        fd = None
+    if fd is not None:
+        try:
+            return os.fstat(fd).st_size
+        except OSError:
+            pass
+    try:
+        cur = file_obj.tell()
+        file_obj.seek(0, os.SEEK_END)
+        end = file_obj.tell()
+        file_obj.seek(cur, os.SEEK_SET)
+        return end - cur
+    except (OSError, AttributeError):
+        return None

comfy_low/errors.py

@@ -0,0 +1,141 @@
+"""The shared error envelope mapped to a typed exception per ``code``.
+
+This is the ``comfy_low`` (protocol) view of errors: one class per documented
+error ``code``, plus a fallback. ``comfy_sdk`` re-raises these as its own
+idiomatic exceptions where it adds value (e.g. ``JobFailed`` carrying node
+details), but the protocol codes are defined here so the generated layer has a
+stable, typed error surface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ApiError(Exception):
+    """Base for every error carried by the API's error envelope."""
+
+    code: str = "error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        http_status: int,
+        details: dict[str, Any] | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        if code is not None:
+            self.code = code
+        self.http_status = http_status
+        self.details = details
+        self.retry_after = retry_after
+
+
+class InvalidWorkflow(ApiError):
+    code = "invalid_workflow"
+
+
+class WorkflowFormatUi(ApiError):
+    code = "workflow_format_ui"
+
+
+class MissingAsset(ApiError):
+    code = "missing_asset"
+
+
+class HashMismatch(ApiError):
+    code = "hash_mismatch"
+
+
+class BlobNotFound(ApiError):
+    code = "blob_not_found"
+
+
+class IdempotencyKeyReuse(ApiError):
+    code = "idempotency_key_reuse"
+
+
+class QueueFull(ApiError):
+    code = "queue_full"
+
+
+class InsufficientCredits(ApiError):
+    code = "insufficient_credits"
+
+
+class NotFound(ApiError):
+    code = "not_found"
+
+
+class Unauthorized(ApiError):
+    code = "unauthorized"
+
+
+class Forbidden(ApiError):
+    code = "forbidden"
+
+
+# code -> exception class. Anything unmapped becomes a bare ApiError.
+_BY_CODE: dict[str, type[ApiError]] = {
+    cls.code: cls
+    for cls in (
+        InvalidWorkflow,
+        WorkflowFormatUi,
+        MissingAsset,
+        HashMismatch,
+        BlobNotFound,
+        IdempotencyKeyReuse,
+        QueueFull,
+        InsufficientCredits,
+        NotFound,
+        Unauthorized,
+        Forbidden,
+    )
+}
+
+
+def error_from_envelope(
+    http_status: int,
+    body: dict[str, Any] | None,
+    *,
+    retry_after: int | None = None,
+) -> ApiError:
+    """Build the typed exception for an error response.
+
+    Falls back to a status-derived code when the body is missing or not a
+    well-formed envelope (so a bare ``401`` with no JSON still maps to
+    ``Unauthorized``).
+    """
+    err = (body or {}).get("error") if isinstance(body, dict) else None
+    code = (err or {}).get("code") if isinstance(err, dict) else None
+    message = (err or {}).get("message") if isinstance(err, dict) else None
+    details = (err or {}).get("details") if isinstance(err, dict) else None
+
+    if code is None:
+        code = _CODE_BY_STATUS.get(http_status, "error")
+    if not message:
+        message = f"HTTP {http_status}"
+
+    cls = _BY_CODE.get(code, ApiError)
+    return cls(
+        message,
+        code=code,
+        http_status=http_status,
+        details=details if isinstance(details, dict) else None,
+        retry_after=retry_after,
+    )
+
+
+_CODE_BY_STATUS: dict[int, str] = {
+    401: "unauthorized",
+    402: "insufficient_credits",
+    403: "forbidden",
+    404: "not_found",
+    409: "hash_mismatch",
+    422: "invalid_workflow",
+    429: "queue_full",
+}

comfy_low/models/__init__.py

@@ -0,0 +1,47 @@
+"""Generated pydantic v2 models for the Comfy API v2 contract.
+
+Everything here is emitted from ``spec/openapi.yaml`` by ``scripts/gen_models.sh``
+and re-exported for convenience. Do not hand-edit ``_generated.py``.
+
+Note on naming: request bodies in the canonical spec are inlined (not named
+schemas), so there are no ``*Request`` / ``*Form`` models — the transport builds
+those payloads by hand. The SSE event payloads are ``StatusEvent`` /
+``PreviewEvent`` / ``LogEvent`` (``progress`` and ``output`` events reuse the
+``Progress`` and ``Output`` schemas directly).
+"""
+
+from __future__ import annotations
+
+from ._generated import (
+    Asset,
+    AssetReference,
+    Error,
+    ErrorEnvelope,
+    Job,
+    JobError,
+    JobStatus,
+    JobUrls,
+    LogEvent,
+    Output,
+    OutputType,
+    PreviewEvent,
+    Progress,
+    StatusEvent,
+)
+
+__all__ = [
+    "Asset",
+    "AssetReference",
+    "Error",
+    "ErrorEnvelope",
+    "Job",
+    "JobError",
+    "JobStatus",
+    "JobUrls",
+    "LogEvent",
+    "Output",
+    "OutputType",
+    "PreviewEvent",
+    "Progress",
+    "StatusEvent",
+]

comfy_low/models/_generated.py

@@ -0,0 +1,257 @@
+# GENERATED by scripts/gen_models.sh from spec/openapi.yaml — do not hand-edit.
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any
+
+from pydantic import AnyUrl, AwareDatetime, BaseModel, Field
+
+
+class Asset(BaseModel):
+    """
+    A user-owned record identified by a server-assigned UUID, backing an immutable blob whose content carries a server-computed blake3 hash. `hash` may be computed lazily: an asset record (and its retrievable bytes) can exist before its hash is filled in.
+    """
+
+    id: Annotated[str, Field(examples=['asset_01JZV8Q3M7K2W9X0Y1Z2A3B4C5'])]
+    hash: Annotated[
+        str | None,
+        Field(
+            description='`blake3:<hex>`; null while lazily computed.',
+            examples=['blake3:9f8a1c0d...'],
+        ),
+    ]
+    size_bytes: Annotated[int, Field(examples=[4816293])]
+    content_type: Annotated[str, Field(examples=['image/png'])]
+    file_path: Annotated[str | None, Field(examples=['photo.png'])] = None
+    created_new: Annotated[
+        bool | None,
+        Field(
+            description='On create responses: distinguishes a brand-new blob (true) from a dedup hit against bytes the platform already had (false).'
+        ),
+    ] = None
+    created_at: AwareDatetime
+    url: Annotated[
+        AnyUrl, Field(description='Short-lived content URL (signed, or proxy-served).')
+    ]
+    url_expires_at: AwareDatetime
+
+
+class JobStatus(Enum):
+    """
+    Lifecycle: queued → running → succeeded | failed | expired;
+    a cancel request moves running → canceling → canceled.
+    Terminal states: succeeded, canceled, failed, expired.
+
+    """
+
+    queued = 'queued'
+    running = 'running'
+    succeeded = 'succeeded'
+    canceling = 'canceling'
+    canceled = 'canceled'
+    failed = 'failed'
+    expired = 'expired'
+
+
+class JobUrls(BaseModel):
+    """
+    Embedded follow-up links — follow these, don't build URLs.
+    """
+
+    self: str
+    events: str
+    cancel: str
+
+
+class Progress(BaseModel):
+    """
+    Server-computed progress snapshot (node-count and sampler-step weighted). Complete per snapshot — one fully re-syncs a client.
+    """
+
+    value: Annotated[
+        float,
+        Field(
+            description='Overall fraction, server-computed.',
+            examples=[0.42],
+            ge=0.0,
+            le=1.0,
+        ),
+    ]
+    nodes_done: Annotated[int, Field(examples=[11])]
+    nodes_total: Annotated[int, Field(examples=[31])]
+    current_node: Annotated[str | None, Field(examples=['12'])] = None
+    current_node_class: Annotated[str | None, Field(examples=['KSampler'])] = None
+    step: Annotated[int | None, Field(examples=[21])] = None
+    steps: Annotated[int | None, Field(examples=[50])] = None
+    message: Annotated[str | None, Field(examples=['KSampler 21/50'])] = None
+
+
+class OutputType(Enum):
+    """
+    Normalized output kind — nothing silently dropped.
+    """
+
+    image = 'image'
+    video = 'video'
+    audio = 'audio'
+    text = 'text'
+    file = 'file'
+    latent = 'latent'
+
+
+class JobError(BaseModel):
+    """
+    Execution failure detail, carried in `job.error` (not an HTTP error).
+    """
+
+    code: Annotated[str, Field(examples=['node_execution_error'])]
+    message: str
+    node_id: str | None = None
+    class_type: str | None = None
+    traceback: str | None = None
+
+
+class Error(BaseModel):
+    code: Annotated[str, Field(examples=['invalid_workflow'])]
+    message: Annotated[
+        str,
+        Field(examples=["Node 12 (KSampler): required input 'model' is not connected"]),
+    ]
+    details: Annotated[
+        dict[str, Any] | None,
+        Field(
+            examples=[
+                {'node_errors': {'12': [{'field': 'model', 'reason': 'missing_input'}]}}
+            ]
+        ),
+    ] = None
+
+
+class ErrorEnvelope(BaseModel):
+    """
+    Shared error envelope with machine-readable codes. Core codes (v1):
+    `invalid_workflow` (422), `workflow_format_ui` (422),
+    `missing_asset` (422), `hash_mismatch` (409), `blob_not_found`
+    (404), `idempotency_key_reuse` (422),
+    `queue_full` (429 + Retry-After), `insufficient_credits` (402),
+    `not_found` (404), `unauthorized` (401), `forbidden` (403).
+
+    """
+
+    error: Error
+
+
+class StatusEvent(BaseModel):
+    """
+    SSE `status` event payload.
+    """
+
+    status: JobStatus
+    queue_position: int | None = None
+
+
+class PreviewEvent(BaseModel):
+    """
+    SSE `preview` event payload (JPEG, base64, throttled).
+    """
+
+    node_id: str
+    content_type: Annotated[str, Field(examples=['image/jpeg'])]
+    data_base64: str
+
+
+class LogEvent(BaseModel):
+    """
+    SSE `log` event payload. Best-effort diagnostics.
+    """
+
+    level: Annotated[str, Field(examples=['info'])]
+    message: str
+
+
+class FieldType(Enum):
+    core_ASSET = 'core/ASSET'
+
+
+class Info(BaseModel):
+    id: Annotated[str, Field(examples=['asset_01JZV8Q3M7K2W9X0Y1Z2A3B4C5'])]
+    hash: Annotated[str | None, Field(examples=['blake3:9f8a1c0d...'])] = None
+    file_path: Annotated[str | None, Field(examples=['photo.png'])] = None
+
+
+class AssetReference(BaseModel):
+    """
+    The typed asset-reference object placed inside workflow JSON where a
+    filename would normally go (documented here for tooling; it is not a
+    request/response body itself):
+
+        {"__type": "core/ASSET",
+         "info": {"id": "asset_...", "hash": "blake3:...",
+                  "file_path": "photo.png"}}
+
+    `info.id` (the asset UUID) is required in v1 and authoritative;
+    `hash` and `file_path` are optional staging/lookup hints and never
+    override a present `id`. A malformed reference or one that is not
+    resolvable/owned by the caller fails submission with 422
+    `missing_asset`.
+
+    """
+
+    field__type: Annotated[FieldType, Field(alias='__type')]
+    info: Info
+
+
+class Output(BaseModel):
+    """
+    A committed job output. Outputs are assets: `id` is the asset UUID, retrievable via GET /api/v2/assets/{id} for as long as the job is retained. `hash` is lazily computed and may be null on the retrieval hot path.
+    """
+
+    node_id: Annotated[str, Field(examples=['9'])]
+    name: Annotated[str, Field(examples=['ComfyUI_00001_.png'])]
+    type: OutputType
+    content_type: Annotated[str, Field(examples=['image/png'])]
+    size_bytes: Annotated[int, Field(examples=[1848320])]
+    id: Annotated[
+        str, Field(description='Asset UUID.', examples=['asset_01JZV9R4N8...'])
+    ]
+    hash: Annotated[
+        str | None, Field(description='`blake3:<hex>`; null until lazily computed.')
+    ]
+    url: AnyUrl
+    url_expires_at: AwareDatetime
+
+
+class Job(BaseModel):
+    """
+    One execution of a workflow. Durable from creation until `expires_at`; `outputs` populates incrementally during execution.
+    """
+
+    id: Annotated[str, Field(examples=['job_01JZTGXW9Q2M4R8V0B1N3P5D7F'])]
+    status: JobStatus
+    created_at: AwareDatetime
+    started_at: Annotated[AwareDatetime | None, Field(...)]
+    completed_at: Annotated[AwareDatetime | None, Field(...)]
+    expires_at: Annotated[
+        AwareDatetime,
+        Field(
+            description='Retention deadline — a platform property, not an API constant.'
+        ),
+    ]
+    queue_position: Annotated[int | None, Field(...)]
+    progress: Annotated[
+        Progress | None,
+        Field(
+            description='The latest progress snapshot; same data the SSE stream pushes.'
+        ),
+    ]
+    outputs: list[Output]
+    error: Annotated[JobError | None, Field(...)]
+    metrics: Annotated[
+        dict[str, int | None] | None,
+        Field(
+            description='Values are nullable (a metric not yet available — e.g. `execution_ms` before a job starts running — is `null`, not omitted); the example below is deliberately all-non-null purely to work around a Spectral/nimma lint-tooling crash on a literal `null` inside a schema `example` combined with `additionalProperties.nullable: true` — the schema itself is unchanged and still allows null values at runtime.',
+            examples=[{'queue_ms': 9000, 'execution_ms': 42000}],
+        ),
+    ] = None
+    urls: JobUrls

comfy_low/sse.py

@@ -0,0 +1,70 @@
+"""Sans-IO Server-Sent-Events decoding.
+
+The decoder is pure and line-driven: feed it decoded text lines one at a time and
+it yields complete events. Both the sync and async transports drive the same
+decoder, so the wire-format parsing lives in exactly one place (the IO — reading
+lines off a sync or async body — is the only thing that differs).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class RawEvent:
+    """One decoded SSE frame. ``event`` defaults to ``message`` per the spec."""
+
+    event: str
+    data: dict[str, Any]
+
+
+class SSEDecoder:
+    """Incremental SSE parser. Call :meth:`push` per line; it returns any
+    completed events (usually zero or one). A blank line dispatches the buffer.
+    """
+
+    def __init__(self) -> None:
+        self._event: str | None = None
+        self._data: list[str] = []
+
+    def push(self, line: str) -> list[RawEvent]:
+        # Strip a single trailing newline; callers may or may not have kept it.
+        line = line.rstrip("\r\n")
+
+        if line == "":
+            return self._dispatch()
+        if line.startswith(":"):
+            # Comment / keep-alive heartbeat — ignore.
+            return []
+
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+
+        if field == "event":
+            self._event = value
+        elif field == "data":
+            self._data.append(value)
+        # `id` and `retry` are intentionally ignored: this stream carries no
+        # cursor (no Last-Event-ID resume), by contract.
+        return []
+
+    def _dispatch(self) -> list[RawEvent]:
+        if not self._data and self._event is None:
+            return []
+        raw = "\n".join(self._data)
+        event = self._event or "message"
+        self._event = None
+        self._data = []
+        if raw == "":
+            return []
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            data = {"raw": raw}
+        if not isinstance(data, dict):
+            data = {"value": data}
+        return [RawEvent(event=event, data=data)]