Metadata-Version: 2.4
Name: comfyhelper
Version: 0.1.0
Summary: Edit and submit ComfyUI workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: requests>=2.31.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# ComfyHelper

Edit ComfyUI API-format workflow JSON from Python or the command line, then submit it to a running ComfyUI instance.

ComfyHelper is intentionally focused on value overrides: prompts, seeds, sampler settings, dimensions, loaders, LoRAs, and output naming. It does not try to build arbitrary ComfyUI graphs from scratch.

## Install

```bash
pip install -e ".[dev]"
```

The package requires Python 3.12 or newer.

## Workflow Format

Use ComfyUI's API-format workflow JSON, not the full visual editor workflow format. In ComfyUI, enable developer/API workflow export and save the API JSON.

## CLI Usage

Run a workflow and save returned images:

```bash
comfyhelper run basic_api.json \
  --positive "a red apple on a white table, photorealistic" \
  --negative "blurry, low quality" \
  --seed 42 \
  --steps 30 \
  --cfg 7.5 \
  --sampler euler \
  --scheduler simple \
  --width 1024 \
  --height 1024 \
  --image input.png \
  --filename-prefix apple_test \
  --output-dir ./output
```

Submit without waiting:

```bash
comfyhelper run basic_api.json --positive "a cat" --no-wait
```

Use multiple LoRAs. The final workflow will contain exactly these LoRAs, chained in order:

```bash
comfyhelper run basic_api.json \
  --lora detail.safetensors \
  --lora style.safetensors \
  --lora-strength 0.8 \
  --lora-strength 0.6
```

For split-loader workflows:

```bash
comfyhelper run workflow.json \
  --diffusion-model flux1-dev.safetensors \
  --clip clip_l.safetensors \
  --clip t5xxl_fp16.safetensors \
  --vae ae.safetensors
```

## Python Usage

```python
from comfyhelper import ComfyClient, Workflow

workflow = Workflow.from_file("basic_api.json")
workflow.set_positive_prompt("a red apple on a white table")
workflow.set_negative_prompt("blurry, low quality")
workflow.set_seed(42)
workflow.set_steps(30)
workflow.set_dimensions(1024, 1024)
workflow.set_loras([
    ("detail.safetensors", 0.8),
    ("style.safetensors", 0.6),
])

client = ComfyClient(host="localhost", port=8188)
result = client.run(workflow)
images = result.download(client)
```

## Supported Setters

General workflow edits:

- `set_positive_prompt(text, sampler_id=None)`
- `set_negative_prompt(text, sampler_id=None)`
- `set_prompt_node(node_id, text)`
- `set_node_input(class_type, field, value)`
- `set_node_input_by_id(node_id, field, value)`
- `set_seed(seed)`
- `set_steps(steps)`
- `set_cfg(cfg)`
- `set_sampler(sampler_name)`
- `set_scheduler(scheduler)`
- `set_denoise(denoise)`
- `set_dimensions(width, height)`
- `set_batch_size(batch_size)`
- `set_filename_prefix(prefix)`
- `get_load_image_count()`
- `set_load_image(image)`
- `set_load_images(images)`

Loader edits:

- `set_checkpoint(name)` for `CheckpointLoaderSimple.ckpt_name`
- `set_diffusion_model(name)` for `UNETLoader.unet_name`
- `set_clip(name)` for `CLIPLoader.clip_name`
- `set_clips(names)` for `CLIPLoader`, `DualCLIPLoader`, `TripleCLIPLoader`, and `QuadrupleCLIPLoader`
- `set_vae(name)` for `VAELoader.vae_name`
- `set_lora(name, strength=1.0)`
- `set_loras([(name, strength), ...])`

## Validation

Use `workflow.validate()` to get a list of obvious structural issues, or `workflow.validate_or_raise()` to raise a `ValueError`. `ComfyClient.submit()` validates before sending the workflow to ComfyUI.

Validation checks are intentionally lightweight. ComfyUI remains the source of truth for node-specific compatibility.

## Notes and Limits

- The first `KSampler` is the default target for prompt and sampler setters.
- Workflows with multiple samplers can use `sampler_id` for prompt setters or `set_node_input_by_id()` for explicit edits.
- `set_loras()` replaces existing `LoraLoader` nodes and creates a fresh chain.
- The CLI saves images into ComfyUI subfolders when provided and avoids overwriting existing files by adding numeric suffixes.
- Custom extension nodes can still be edited with `set_node_input_by_id()`.
