comfy-diffusion 2.0.0__tar.gz → 2.1.0__tar.gz

{comfy_diffusion-2.0.0 → comfy_diffusion-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comfy-diffusion
-Version: 2.0.0
+Version: 2.1.0
 Summary: ComfyUI inference engine as a standalone Python library (no server, no UI).
 Author: Alejandro Quintero
 License: GPL-3.0-only
@@ -178,6 +178,69 @@ image.save("output.png")
 
 `comfy_diffusion.pipelines` remains available as an optional helper namespace for explicit ready-made flows, but the main interface is the modular Python API above.
 
+## Experimental Raw Node Access
+
+Advanced implementers can inspect and execute raw ComfyUI nodes that are not covered by the curated wrapper modules:
+
+```python
+from comfy_diffusion.nodes import get_node_info, list_nodes, run_node
+
+nodes = list_nodes()
+print(nodes["VAEDecode"])
+
+info = get_node_info("KSampler")
+result = run_node("SomeUtilityNode", value=123)
+```
+
+This is an experimental escape hatch. Prefer the explicit `models`, `conditioning`, `sampling`, `vae`, `image`, `mask`, `audio`, `video`, and `pipelines` modules for stable application code.
+
+By default, raw node discovery loads ComfyUI core nodes and built-in extra nodes only. API nodes are opt-in because they may require provider credentials, network access, and additional ComfyUI API-node runtime configuration:
+
+```python
+api_nodes = list_nodes(include_api=True)
+```
+
+ComfyUI API nodes use the Comfy.org proxy (`https://api.comfy.org`) and Comfy.org credentials. They do not use direct provider keys such as `OPENAI_API_KEY`, `KLING_API_KEY`, or `LUMA_API_KEY`.
+
+```python
+from comfy_diffusion.nodes import ApiNodeAuth, run_node
+
+result = run_node(
+    "OpenAIChatNode",
+    include_api=True,
+    api_auth=ApiNodeAuth(api_key="your-comfy-org-api-key"),
+    prompt="Describe this package in one sentence.",
+    model="gpt-4.1",
+)
+```
+
+For headless apps, environment variables are also supported:
+
+```bash
+export COMFY_ORG_API_KEY=your-comfy-org-api-key
+export COMFY_API_BASE=https://api.comfy.org
+```
+
+Browser login, OAuth token refresh, and ComfyUI Cloud session management are intentionally out of scope for this package. Use a Comfy.org API key for Python execution. The CLI can discover API nodes with `nodes list --include-api`, but API node execution is Python-only.
+
+External custom nodes are trusted Python code and are not sandboxed. They are never loaded by scanning ComfyUI's default `custom_nodes` folder; pass explicit paths instead:
+
+```python
+nodes = list_nodes(custom_node_paths=["~/.cache/comfy-diffusion/custom_nodes/example-node"])
+```
+
+The CLI can install trusted custom node repositories into the comfy-diffusion cache:
+
+```bash
+uv run comfy-diffusion nodes install https://github.com/example/example-node.git
+uv run comfy-diffusion nodes install https://github.com/example/example-node.git --ref v1.2.3
+uv run comfy-diffusion nodes install https://github.com/example/example-node.git --install-deps
+uv run comfy-diffusion nodes installed
+uv run comfy-diffusion nodes list --custom-node ~/.cache/comfy-diffusion/custom_nodes/example-node
+```
+
+If a custom node repository has `requirements.txt`, dependencies are installed only with `--install-deps`; otherwise the CLI reports the command to run.
+
 ## CLI
 
 The first-party CLI is named `comfy-diffusion` and provides operational package tools only.
@@ -187,6 +250,11 @@ uv run comfy-diffusion runtime check --json
 uv run comfy-diffusion runtime paths
 uv run comfy-diffusion models list --models-dir /path/to/models
 uv run comfy-diffusion models download --manifest models.json --models-dir /path/to/models
+uv run comfy-diffusion nodes list --json
+uv run comfy-diffusion nodes show VAEDecode --json
+uv run comfy-diffusion nodes list --include-api
+uv run comfy-diffusion nodes install https://github.com/example/example-node.git
+uv run comfy-diffusion nodes installed --json
 ```
 
 Model manifest shape:

{comfy_diffusion-2.0.0 → comfy_diffusion-2.1.0}/README.md

@@ -100,6 +100,69 @@ image.save("output.png")
 
 `comfy_diffusion.pipelines` remains available as an optional helper namespace for explicit ready-made flows, but the main interface is the modular Python API above.
 
+## Experimental Raw Node Access
+
+Advanced implementers can inspect and execute raw ComfyUI nodes that are not covered by the curated wrapper modules:
+
+```python
+from comfy_diffusion.nodes import get_node_info, list_nodes, run_node
+
+nodes = list_nodes()
+print(nodes["VAEDecode"])
+
+info = get_node_info("KSampler")
+result = run_node("SomeUtilityNode", value=123)
+```
+
+This is an experimental escape hatch. Prefer the explicit `models`, `conditioning`, `sampling`, `vae`, `image`, `mask`, `audio`, `video`, and `pipelines` modules for stable application code.
+
+By default, raw node discovery loads ComfyUI core nodes and built-in extra nodes only. API nodes are opt-in because they may require provider credentials, network access, and additional ComfyUI API-node runtime configuration:
+
+```python
+api_nodes = list_nodes(include_api=True)
+```
+
+ComfyUI API nodes use the Comfy.org proxy (`https://api.comfy.org`) and Comfy.org credentials. They do not use direct provider keys such as `OPENAI_API_KEY`, `KLING_API_KEY`, or `LUMA_API_KEY`.
+
+```python
+from comfy_diffusion.nodes import ApiNodeAuth, run_node
+
+result = run_node(
+    "OpenAIChatNode",
+    include_api=True,
+    api_auth=ApiNodeAuth(api_key="your-comfy-org-api-key"),
+    prompt="Describe this package in one sentence.",
+    model="gpt-4.1",
+)
+```
+
+For headless apps, environment variables are also supported:
+
+```bash
+export COMFY_ORG_API_KEY=your-comfy-org-api-key
+export COMFY_API_BASE=https://api.comfy.org
+```
+
+Browser login, OAuth token refresh, and ComfyUI Cloud session management are intentionally out of scope for this package. Use a Comfy.org API key for Python execution. The CLI can discover API nodes with `nodes list --include-api`, but API node execution is Python-only.
+
+External custom nodes are trusted Python code and are not sandboxed. They are never loaded by scanning ComfyUI's default `custom_nodes` folder; pass explicit paths instead:
+
+```python
+nodes = list_nodes(custom_node_paths=["~/.cache/comfy-diffusion/custom_nodes/example-node"])
+```
+
+The CLI can install trusted custom node repositories into the comfy-diffusion cache:
+
+```bash
+uv run comfy-diffusion nodes install https://github.com/example/example-node.git
+uv run comfy-diffusion nodes install https://github.com/example/example-node.git --ref v1.2.3
+uv run comfy-diffusion nodes install https://github.com/example/example-node.git --install-deps
+uv run comfy-diffusion nodes installed
+uv run comfy-diffusion nodes list --custom-node ~/.cache/comfy-diffusion/custom_nodes/example-node
+```
+
+If a custom node repository has `requirements.txt`, dependencies are installed only with `--install-deps`; otherwise the CLI reports the command to run.
+
 ## CLI
 
 The first-party CLI is named `comfy-diffusion` and provides operational package tools only.
@@ -109,6 +172,11 @@ uv run comfy-diffusion runtime check --json
 uv run comfy-diffusion runtime paths
 uv run comfy-diffusion models list --models-dir /path/to/models
 uv run comfy-diffusion models download --manifest models.json --models-dir /path/to/models
+uv run comfy-diffusion nodes list --json
+uv run comfy-diffusion nodes show VAEDecode --json
+uv run comfy-diffusion nodes list --include-api
+uv run comfy-diffusion nodes install https://github.com/example/example-node.git
+uv run comfy-diffusion nodes installed --json
 ```
 
 Model manifest shape:

{comfy_diffusion-2.0.0 → comfy_diffusion-2.1.0}/comfy_diffusion/cli/main.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 import json
+from dataclasses import asdict, is_dataclass
 from pathlib import Path
 from typing import Annotated, Any
 
+import click
 import typer
 
 from comfy_diffusion._runtime import COMFYUI_PINNED_TAG, _comfyui_root
@@ -25,9 +27,11 @@ app = typer.Typer(
 )
 runtime_app = typer.Typer(help="Inspect the local ComfyUI runtime.", no_args_is_help=True)
 models_app = typer.Typer(help="Inspect and download model files.", no_args_is_help=True)
+nodes_app = typer.Typer(help="Inspect raw ComfyUI nodes.", no_args_is_help=True)
 
 app.add_typer(runtime_app, name="runtime")
 app.add_typer(models_app, name="models")
+app.add_typer(nodes_app, name="nodes")
 
 _MODEL_DIRS = (
     "checkpoints",
@@ -50,6 +54,20 @@ def _echo_json(payload: Any) -> None:
     typer.echo(json.dumps(payload, indent=2, sort_keys=True))
 
 
+def _jsonable(value: Any) -> Any:
+    if is_dataclass(value) and not isinstance(value, type):
+        return _jsonable(asdict(value))
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return repr(value)
+
+
 def _package_root() -> Path:
     return Path(__file__).resolve().parents[1]
 
@@ -58,6 +76,10 @@ def _default_models_dir() -> Path:
     return Path.home() / ".cache" / "comfy-diffusion" / "models"
 
 
+def _custom_node_paths(custom_node: list[Path] | None) -> list[Path]:
+    return custom_node or []
+
+
 @runtime_app.command("check")
 def runtime_check(
     json_output: Annotated[
@@ -235,6 +257,173 @@ def models_list(
             typer.echo(f"  {file_path}")
 
 
+@nodes_app.command("list")
+def nodes_list(
+    include_api: Annotated[
+        bool,
+        typer.Option("--include-api", help="Include built-in ComfyUI API nodes."),
+    ] = False,
+    custom_node: Annotated[
+        list[Path] | None,
+        typer.Option(
+            "--custom-node",
+            help="Explicit custom node .py file or package directory to load.",
+        ),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """List raw ComfyUI nodes, optionally including explicit custom node paths."""
+    from comfy_diffusion.nodes import list_nodes
+
+    try:
+        nodes = list_nodes(
+            include_api=include_api,
+            custom_node_paths=_custom_node_paths(custom_node),
+        )
+    except (RuntimeError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    if json_output:
+        _echo_json(
+            {
+                "include_api": include_api,
+                "custom_nodes": [str(path) for path in _custom_node_paths(custom_node)],
+                "nodes": {node_id: _jsonable(info) for node_id, info in nodes.items()},
+            }
+        )
+        return
+
+    for node_id, info in nodes.items():
+        suffix = " [api]" if info.is_api_node else ""
+        if info.is_custom_node:
+            suffix += " [custom]"
+        typer.echo(f"{node_id}{suffix}: {info.class_name}")
+
+
+@nodes_app.command("show")
+def nodes_show(
+    node_id: Annotated[str, typer.Argument(help="ComfyUI node id to inspect.")],
+    include_api: Annotated[
+        bool,
+        typer.Option("--include-api", help="Include built-in ComfyUI API nodes."),
+    ] = False,
+    custom_node: Annotated[
+        list[Path] | None,
+        typer.Option(
+            "--custom-node",
+            help="Explicit custom node .py file or package directory to load.",
+        ),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Show metadata for one raw ComfyUI node."""
+    from comfy_diffusion.nodes import get_node_info
+
+    try:
+        info = get_node_info(
+            node_id,
+            include_api=include_api,
+            custom_node_paths=_custom_node_paths(custom_node),
+        )
+    except KeyError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    except (RuntimeError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    payload = _jsonable(info)
+    if json_output:
+        _echo_json(payload)
+        return
+
+    for key, value in payload.items():
+        typer.echo(f"{key}: {value}")
+
+
+@nodes_app.command("install")
+def nodes_install(
+    repo_url: Annotated[str, typer.Argument(help="Git repository URL to install.")],
+    ref: Annotated[
+        str | None,
+        typer.Option("--ref", help="Branch, tag, or commit to checkout after fetching."),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option("--name", help="Install directory name. Defaults to repo name."),
+    ] = None,
+    custom_nodes_dir: Annotated[
+        Path | None,
+        typer.Option("--custom-nodes-dir", help="Directory for installed custom nodes."),
+    ] = None,
+    install_deps: Annotated[
+        bool,
+        typer.Option("--install-deps", help="Install requirements.txt with uv pip."),
+    ] = False,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """Install or update a trusted custom node Git repository."""
+    from comfy_diffusion.custom_nodes import install_custom_node
+
+    try:
+        result = install_custom_node(
+            repo_url,
+            ref=ref,
+            name=name,
+            custom_nodes_dir=custom_nodes_dir,
+            install_deps=install_deps,
+        )
+    except (RuntimeError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    payload = _jsonable(result)
+    if json_output:
+        _echo_json(payload)
+        return
+
+    typer.echo(f"name: {result.name}")
+    typer.echo(f"path: {result.path}")
+    typer.echo(f"commit: {result.commit}")
+    typer.echo(f"installed: {result.installed}")
+    typer.echo(f"updated: {result.updated}")
+    if result.requirements_path is not None:
+        typer.echo(f"requirements: {result.requirements_path}")
+        if result.dependencies_installed:
+            typer.echo("dependencies: installed")
+        elif result.dependency_command is not None:
+            typer.echo(f"dependencies: run {' '.join(result.dependency_command)}")
+
+
+@nodes_app.command("installed")
+def nodes_installed(
+    custom_nodes_dir: Annotated[
+        Path | None,
+        typer.Option("--custom-nodes-dir", help="Directory for installed custom nodes."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+) -> None:
+    """List custom node repositories installed by comfy-diffusion."""
+    from comfy_diffusion.custom_nodes import list_installed_custom_nodes
+
+    installed = list_installed_custom_nodes(custom_nodes_dir=custom_nodes_dir)
+    if json_output:
+        _echo_json({"custom_nodes": [_jsonable(item) for item in installed]})
+        return
+
+    for item in installed:
+        suffix = " [requirements]" if item.has_requirements else ""
+        typer.echo(f"{item.name}{suffix}: {item.path}")
+
+
 def main() -> None:
     app()
 

comfy_diffusion-2.1.0/comfy_diffusion/custom_nodes.py

@@ -0,0 +1,170 @@
+"""Install and inspect trusted ComfyUI custom node repositories."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CustomNodeInstallResult:
+    """Result from installing or updating a custom node repository."""
+
+    repo_url: str
+    name: str
+    path: Path
+    ref: str | None
+    commit: str
+    installed: bool
+    updated: bool
+    requirements_path: Path | None
+    dependencies_installed: bool
+    dependency_command: tuple[str, ...] | None
+
+
+@dataclass(frozen=True)
+class CustomNodeInstallInfo:
+    """A custom node repository installed in the comfy-diffusion cache."""
+
+    name: str
+    path: Path
+    has_requirements: bool
+
+
+def default_custom_nodes_dir() -> Path:
+    """Return the default custom node install directory."""
+    return Path.home() / ".cache" / "comfy-diffusion" / "custom_nodes"
+
+
+def _derive_repo_name(repo_url: str) -> str:
+    normalized = repo_url.rstrip("/")
+    name = normalized.rsplit("/", 1)[-1]
+    if name.endswith(".git"):
+        name = name[:-4]
+    if not name:
+        raise ValueError("Could not derive custom node name from repo URL.")
+    return name
+
+
+def _validate_install_name(name: str) -> str:
+    path = Path(name)
+    if path.is_absolute() or path.name != name or name in {"", ".", ".."}:
+        raise ValueError(f"Invalid custom node install name: {name}")
+    return name
+
+
+def _resolve_custom_nodes_dir(custom_nodes_dir: str | Path | None) -> Path:
+    directory = (
+        Path(custom_nodes_dir)
+        if custom_nodes_dir is not None
+        else default_custom_nodes_dir()
+    )
+    return directory.expanduser().resolve()
+
+
+def _run_command(args: list[str], *, cwd: Path | None = None) -> str:
+    try:
+        completed = subprocess.run(
+            args,
+            cwd=cwd,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError(f"Required command not found: {args[0]}") from exc
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.strip()
+        stdout = exc.stdout.strip()
+        detail = stderr or stdout or f"exit code {exc.returncode}"
+        raise RuntimeError(f"Command failed: {' '.join(args)}. {detail}") from exc
+    return completed.stdout.strip()
+
+
+def _ensure_clean_git_tree(target: Path) -> None:
+    status = _run_command(["git", "status", "--porcelain"], cwd=target)
+    if status:
+        raise RuntimeError(f"Custom node repository has local changes: {target}")
+
+
+def _current_commit(target: Path) -> str:
+    return _run_command(["git", "rev-parse", "HEAD"], cwd=target)
+
+
+def install_custom_node(
+    repo_url: str,
+    *,
+    ref: str | None = None,
+    name: str | None = None,
+    custom_nodes_dir: str | Path | None = None,
+    install_deps: bool = False,
+) -> CustomNodeInstallResult:
+    """Clone or update a trusted ComfyUI custom node repository."""
+    install_root = _resolve_custom_nodes_dir(custom_nodes_dir)
+    install_name = _validate_install_name(name or _derive_repo_name(repo_url))
+    target = install_root / install_name
+
+    installed = False
+    updated = False
+    if target.exists():
+        if not (target / ".git").is_dir():
+            raise RuntimeError(f"Custom node target exists but is not a git repository: {target}")
+        _ensure_clean_git_tree(target)
+        _run_command(["git", "fetch", "--all", "--tags"], cwd=target)
+        if ref is not None:
+            _run_command(["git", "checkout", ref], cwd=target)
+        else:
+            _run_command(["git", "pull", "--ff-only"], cwd=target)
+        updated = True
+    else:
+        install_root.mkdir(parents=True, exist_ok=True)
+        _run_command(["git", "clone", repo_url, str(target)])
+        if ref is not None:
+            _run_command(["git", "checkout", ref], cwd=target)
+        installed = True
+
+    requirements_path = target / "requirements.txt"
+    has_requirements = requirements_path.is_file()
+    dependency_command: tuple[str, ...] | None = None
+    dependencies_installed = False
+    if has_requirements:
+        dependency_command = ("uv", "pip", "install", "-r", str(requirements_path))
+        if install_deps:
+            _run_command(list(dependency_command), cwd=target)
+            dependencies_installed = True
+
+    return CustomNodeInstallResult(
+        repo_url=repo_url,
+        name=install_name,
+        path=target,
+        ref=ref,
+        commit=_current_commit(target),
+        installed=installed,
+        updated=updated,
+        requirements_path=requirements_path if has_requirements else None,
+        dependencies_installed=dependencies_installed,
+        dependency_command=dependency_command,
+    )
+
+
+def list_installed_custom_nodes(
+    custom_nodes_dir: str | Path | None = None,
+) -> list[CustomNodeInstallInfo]:
+    """List custom node repositories installed in the configured directory."""
+    install_root = _resolve_custom_nodes_dir(custom_nodes_dir)
+    if not install_root.is_dir():
+        return []
+
+    installed: list[CustomNodeInstallInfo] = []
+    for path in sorted(install_root.iterdir(), key=lambda item: item.name):
+        if not path.is_dir():
+            continue
+        installed.append(
+            CustomNodeInstallInfo(
+                name=path.name,
+                path=path,
+                has_requirements=(path / "requirements.txt").is_file(),
+            )
+        )
+    return installed