docs: document from_json/from_str and kind-typed outputs in the README - #52
docs: document from_json/from_str and kind-typed outputs in the README#52mattmillerai wants to merge 1 commit into
Conversation
The README showed exactly one way to build a workflow (from_file) and only image-file outputs, so the in-memory constructors and the non-image/bytes paths were undiscoverable without reading SDK source. - Getting started gains a 'Constructing a workflow' subsection: a table of from_file / from_json / from_str, and a dict-built-graph example that runs set_input on it, submits, and pulls the result with to_bytes(). - Downloading outputs gains 'Outputs are kind-typed': output.type is the normalized kind (image, video, audio, text, file, latent) next to content_type/name/size_bytes, with an example branching on it across to_file, to_bytes and get_download_url. Docs only - no API or behavior change. Every documented name was checked against the published 0.1.8 release as well as this tree.
mattmillerai
added
agent-coded
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 12 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Comment |
2 participants
ELI-5
The README only ever showed one way to build a workflow — load
workflow_api.jsonoff disk — and only ever showed saving an image to a file. The SDK can do more than that: you can hand it a graph you built in code, and outputs tell you whether they're an image, a video, audio or text so you can pull them as raw bytes or as a link instead of a file. None of that was written down, so anyone integrating had to read the SDK source to find it. This writes it down. Docs only — no code changed.What changed
Getting started → new "Constructing a workflow" subsection. A three-row table covering
from_file(path)/from_json(graph)/from_str(text), a note that all three are local (no network I/O), and a worked example that builds a graph as adict, callsset_inputon it, submits withclient.run, and pulls the result withto_bytes()— the headless/cron shape with no filesystem round-trip. It also states thatfrom_jsonwraps the dict rather than copying it (sowf.jsonis your graph and stays freely mutable), and thatAsyncComfyexposes the same three constructors.Downloading outputs → new "Outputs are kind-typed" subsection.
output.typeis documented as the normalized kind, alongsidecontent_type/name/size_bytes, with an example that branches across kinds and uses a different retrieval path for each:to_filefor image,to_bytesfor audio,get_download_url()for video, and acase _fallback.to_bytes()andget_download_url()themselves were already documented (#50/#51); what was missing was the kind discriminator and any non-image example — before this, the README's only mentions of audio or video were zero.Verification
ruff check .,ruff format --check .,mypy src,pytest— all green (140 passed, 4 skipped; the skips are the pre-existing integration tests).Beyond the suite, every claim the new prose makes was exercised rather than asserted. I wrote a throwaway pytest module that runs the new snippets verbatim against the repo's own stub server and deleted it before committing (this is a docs-only PR, so it is not in the diff). It confirmed:
from_jsonwraps without copying (wf.json is graph),set_inputmutates that same dict,from_strround-trips the JSON text,to_bytes()returns the served bytes, and a job carrying four outputs typedimage/audio/video/textdispatches correctly through thematchin the example, includingget_download_url().url.The same names were then checked against the published 0.1.8 release (not just this tree), since the acceptance bar is that the examples work on the current published 0.1.x:
WorkflowFactoryhas all three constructors,Outputhasto_file/to_stream/to_bytes/get_download_url/type/content_type/name/size_bytes, andOutputTypeis the same six-value enum.Judgment calls
Six kinds, not four. The brief I worked from named the kinds as
image | video | audio | text. The source of truth — theOutputTypeenum generated fromspec/openapi.yaml— has six:image,video,audio,text,file,latent. I documented the six that exist. Thecase _fallback in the example is deliberate for the same reason: the README isn't covered by the codegen drift check, so a reader who copies the snippet still handles a kind added later.The example graph is abridged and says so. A genuinely runnable API-format graph is roughly seven nodes of checkpoint/CLIP/latent plumbing, which would bury the point of the snippet. It is labelled
(abridged); node9references a node8that isn't shown.Not covered by this PR
Output.to_stream()is still undocumented, deliberately. It has no async twin —AsyncOutput.to_streamdoes not exist on 0.1.8 or on this tree — and the outputs section closes with "AsyncOutputmirrors all of the above withawait", which documenting it there would make false. Writing it up properly means either adding the async method or carving out an exception, and both are outside a docs-only change.comfy_sdkclasses against the README says 6 of 41 distinct names go unmentioned after this change (aclose,as_reference,close,created_new,refresh, and theto_streamabove), down from 10 before it (content_type,from_json,from_strandsize_bytesare the four this PR adds). The sweep is coarse — it matches bare words, so a name liketypecounts as mentioned wherever the English word appears — but it is symmetric across both revisions.src/comfy_sdk/workflows.py,src/comfy_sdk/outputs.pyand the generatedOutputType— but they are named here rather than assumed away.