confyui 0.1.0__tar.gz

confyui-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.3
+Name: confyui
+Version: 0.1.0
+Summary: KpihX sovereign local image generation and editing daemon over ComfyUI (txt2img, img2img, inpaint; XPU-first)
+Author: KpihX
+Author-email: KpihX <kapoivha@gmail.com>
+Requires-Dist: fastapi>=0.159.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: huggingface-hub>=2.2.0
+Requires-Dist: pillow>=13.0.0
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: python-dotenv>=1.2.4
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.3
+Requires-Dist: uvicorn>=0.54.0
+Requires-Dist: torch>=2.8 ; extra == 'cpu'
+Requires-Dist: torchvision>=0.23 ; extra == 'cpu'
+Requires-Dist: torch>=2.8 ; extra == 'cuda'
+Requires-Dist: torchvision>=0.23 ; extra == 'cuda'
+Requires-Dist: transformers>=4.56 ; extra == 'cuda'
+Requires-Dist: accelerate>=1.10.1 ; extra == 'cuda'
+Requires-Dist: huggingface-hub>=0.34.4 ; extra == 'cuda'
+Requires-Dist: safetensors>=0.6.2 ; extra == 'cuda'
+Requires-Dist: torch>=2.8 ; extra == 'xpu'
+Requires-Dist: torchvision>=0.23 ; extra == 'xpu'
+Requires-Dist: transformers>=4.56 ; extra == 'xpu'
+Requires-Dist: accelerate>=1.10.1 ; extra == 'xpu'
+Requires-Dist: huggingface-hub>=0.34.4 ; extra == 'xpu'
+Requires-Dist: safetensors>=0.6.2 ; extra == 'xpu'
+Requires-Python: >=3.12
+Provides-Extra: cpu
+Provides-Extra: cuda
+Provides-Extra: xpu
+Description-Content-Type: text/markdown
+
+# confyui
+
+KπX sovereign local image generation and editing daemon over ComfyUI.
+
+Hardware-accelerated on Intel Arc (XPU) via PyTorch XPU wheels, with portable CPU and CUDA extras.
+
+## Philosophy
+
+- **0 Magic:** The CLI talks to ComfyUI's standard REST API via structured JSON graphs.
+- **0 Manual Start:** The first call (`generate`, `edit`, `inpaint`) automatically starts ComfyUI in the background.
+- **0 Wasted RAM:** An idle watchdog shuts ComfyUI down after `CONFYUI_IDLE_TIMEOUT` seconds of inactivity (default: 30 minutes).
+- **0 Hardcoding:** Paths expand `$HOME` at runtime and are 100% overridable via environment variables.
+
+---
+
+## Installation
+
+```bash
+# Clone or navigate to the repository
+cd ~/Labs/KpihX-Labs/AI/confyui
+
+# Intel Arc workstation (XPU)
+make sync-xpu
+# or: uv sync --extra xpu
+
+# Generic CPU fallback
+make sync-cpu
+
+# NVIDIA CUDA host
+make sync-cuda
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `CONFYUI_DIR` | `~/RAW/comfyui-local/ComfyUI` | Path to the ComfyUI checkout |
+| `CONFYUI_PYTHON` | `$CONFYUI_DIR/.venv/bin/python` | Python interpreter used to run ComfyUI |
+| `CONFYUI_HOST` | `127.0.0.1` | Bind address |
+| `CONFYUI_PORT` | `8188` | Port |
+| `CONFYUI_IDLE_TIMEOUT` | `1800` | Seconds of inactivity before auto-shutdown |
+| `CONFYUI_SPAWN_TIMEOUT` | `90` | Max seconds to wait for daemon readiness |
+| `CONFYUI_STATE_DIR` | `~/.cache/confyui` | Directory for PID, logs, and heartbeat |
+| `CONFYUI_DEFAULT_CKPT` | `Realistic_Vision_V5.1_noVAE.safetensors` | Default checkpoint for txt2img & img2img |
+| `CONFYUI_INPAINT_CKPT` | `Realistic_Vision_V5.1_fp16-no-ema-inpainting.safetensors` | Default inpainting checkpoint |
+
+---
+
+## Usage
+
+### 1. Text-to-Image (`generate`)
+
+```bash
+# Minimal
+uv run confyui generate "a red panda wearing a top hat on the moon, cinematic lighting"
+
+# Full options
+uv run confyui generate "a red panda wearing a top hat on the moon" \
+    --negative "blurry, low quality, artifacts" \
+    --width 512 \
+    --height 512 \
+    --steps 20 \
+    --cfg 7.0 \
+    --seed 42 \
+    --sampler euler \
+    --scheduler normal \
+    --model "Realistic_Vision_V5.1_noVAE.safetensors" \
+    --out panda_moon.png
+```
+
+### 2. Image-to-Image (`edit`)
+
+Modifies an existing image based on a prompt. The source image is kept and only altered proportionally to `--denoise` (0.0 = unchanged, 0.45-0.60 = balanced modification, 1.0 = total repaint):
+
+```bash
+uv run confyui edit panda_moon.png "make the red panda wear a golden astronaut suit" \
+    --denoise 0.50 \
+    --steps 20 \
+    --out panda_astronaut.png
+```
+
+### 3. Inpainting (`inpaint`)
+
+Repaints only the masked region (white pixels in the mask are regenerated, black pixels preserved):
+
+```bash
+uv run confyui inpaint portrait.png torso_mask.png "she wears a long red silk dress" \
+    --denoise 1.0 \
+    --steps 25 \
+    --out portrait_red_dress.png
+```
+
+### 4. Daemon Management
+
+```bash
+# Inspect status, uptime, PID, and idle time remaining
+uv run confyui status
+
+# List installed checkpoints
+uv run confyui models
+
+# Stop the daemon immediately to free RAM and VRAM
+uv run confyui stop
+```
+
+---
+
+## Development
+
+```bash
+make help     # Show available targets
+make check    # Lint (ruff), format check, compile, pyright, pytest
+make smoke    # Fast sanity check of CLI and imports
+make demo     # Run a real 12-step test generation
+```

confyui-0.1.0/README.md

@@ -0,0 +1,117 @@
+# confyui
+
+KπX sovereign local image generation and editing daemon over ComfyUI.
+
+Hardware-accelerated on Intel Arc (XPU) via PyTorch XPU wheels, with portable CPU and CUDA extras.
+
+## Philosophy
+
+- **0 Magic:** The CLI talks to ComfyUI's standard REST API via structured JSON graphs.
+- **0 Manual Start:** The first call (`generate`, `edit`, `inpaint`) automatically starts ComfyUI in the background.
+- **0 Wasted RAM:** An idle watchdog shuts ComfyUI down after `CONFYUI_IDLE_TIMEOUT` seconds of inactivity (default: 30 minutes).
+- **0 Hardcoding:** Paths expand `$HOME` at runtime and are 100% overridable via environment variables.
+
+---
+
+## Installation
+
+```bash
+# Clone or navigate to the repository
+cd ~/Labs/KpihX-Labs/AI/confyui
+
+# Intel Arc workstation (XPU)
+make sync-xpu
+# or: uv sync --extra xpu
+
+# Generic CPU fallback
+make sync-cpu
+
+# NVIDIA CUDA host
+make sync-cuda
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `CONFYUI_DIR` | `~/RAW/comfyui-local/ComfyUI` | Path to the ComfyUI checkout |
+| `CONFYUI_PYTHON` | `$CONFYUI_DIR/.venv/bin/python` | Python interpreter used to run ComfyUI |
+| `CONFYUI_HOST` | `127.0.0.1` | Bind address |
+| `CONFYUI_PORT` | `8188` | Port |
+| `CONFYUI_IDLE_TIMEOUT` | `1800` | Seconds of inactivity before auto-shutdown |
+| `CONFYUI_SPAWN_TIMEOUT` | `90` | Max seconds to wait for daemon readiness |
+| `CONFYUI_STATE_DIR` | `~/.cache/confyui` | Directory for PID, logs, and heartbeat |
+| `CONFYUI_DEFAULT_CKPT` | `Realistic_Vision_V5.1_noVAE.safetensors` | Default checkpoint for txt2img & img2img |
+| `CONFYUI_INPAINT_CKPT` | `Realistic_Vision_V5.1_fp16-no-ema-inpainting.safetensors` | Default inpainting checkpoint |
+
+---
+
+## Usage
+
+### 1. Text-to-Image (`generate`)
+
+```bash
+# Minimal
+uv run confyui generate "a red panda wearing a top hat on the moon, cinematic lighting"
+
+# Full options
+uv run confyui generate "a red panda wearing a top hat on the moon" \
+    --negative "blurry, low quality, artifacts" \
+    --width 512 \
+    --height 512 \
+    --steps 20 \
+    --cfg 7.0 \
+    --seed 42 \
+    --sampler euler \
+    --scheduler normal \
+    --model "Realistic_Vision_V5.1_noVAE.safetensors" \
+    --out panda_moon.png
+```
+
+### 2. Image-to-Image (`edit`)
+
+Modifies an existing image based on a prompt. The source image is kept and only altered proportionally to `--denoise` (0.0 = unchanged, 0.45-0.60 = balanced modification, 1.0 = total repaint):
+
+```bash
+uv run confyui edit panda_moon.png "make the red panda wear a golden astronaut suit" \
+    --denoise 0.50 \
+    --steps 20 \
+    --out panda_astronaut.png
+```
+
+### 3. Inpainting (`inpaint`)
+
+Repaints only the masked region (white pixels in the mask are regenerated, black pixels preserved):
+
+```bash
+uv run confyui inpaint portrait.png torso_mask.png "she wears a long red silk dress" \
+    --denoise 1.0 \
+    --steps 25 \
+    --out portrait_red_dress.png
+```
+
+### 4. Daemon Management
+
+```bash
+# Inspect status, uptime, PID, and idle time remaining
+uv run confyui status
+
+# List installed checkpoints
+uv run confyui models
+
+# Stop the daemon immediately to free RAM and VRAM
+uv run confyui stop
+```
+
+---
+
+## Development
+
+```bash
+make help     # Show available targets
+make check    # Lint (ruff), format check, compile, pyright, pytest
+make smoke    # Fast sanity check of CLI and imports
+make demo     # Run a real 12-step test generation
+```

confyui-0.1.0/pyproject.toml

@@ -0,0 +1,126 @@
+[project]
+name = "confyui"
+version = "0.1.0"
+description = "KpihX sovereign local image generation and editing daemon over ComfyUI (txt2img, img2img, inpaint; XPU-first)"
+readme = "README.md"
+authors = [
+    { name = "KpihX", email = "kapoivha@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.159.1",
+    "httpx>=0.28.1",
+    "huggingface-hub>=2.2.0",
+    "pillow>=13.0.0",
+    "psutil>=7.2.2",
+    "python-dotenv>=1.2.4",
+    "rich>=15.0.0",
+    "typer>=0.27.3",
+    "uvicorn>=0.54.0",
+]
+
+# ── Hardware extras (mutually exclusive) ─────────────────────────────────────
+# Usage: bare sync = client only, plus exactly one accelerator backend.
+#   uv sync                       client only (remote-style, no torch)
+#   uv sync --extra cpu           + CPU torch
+#   uv sync --extra xpu           + Intel Arc (XPU) torch
+#   uv sync --extra cuda          + NVIDIA CUDA torch
+[project.optional-dependencies]
+cpu = [
+    "torch>=2.8",
+    "torchvision>=0.23",
+]
+xpu = [
+    "torch>=2.8",
+    "torchvision>=0.23",
+    "transformers>=4.56",
+    "accelerate>=1.10.1",
+    "huggingface_hub>=0.34.4",
+    "safetensors>=0.6.2",
+]
+cuda = [
+    "torch>=2.8",
+    "torchvision>=0.23",
+    "transformers>=4.56",
+    "accelerate>=1.10.1",
+    "huggingface_hub>=0.34.4",
+    "safetensors>=0.6.2",
+]
+
+[project.scripts]
+confyui = "confyui.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.10.3,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "confyui"
+
+# ── Resolution ───────────────────────────────────────────────────────────────
+# On Intel Arc, unsafe-best-match makes the XPU wheels rank correctly against
+# PyPI during resolution. Removing it is how PyTorch silently resolves to a
+# CUDA build and the model ends up on the CPU. Rationale and full doctrine:
+# k-ai/references/pyproject-hardware.md, template: AI/nobg/pyproject.toml.
+[tool.uv]
+package = true
+index-strategy = "unsafe-best-match"
+# One accelerator backend per environment, never a mixture.
+conflicts = [
+    [{ extra = "cpu" }, { extra = "xpu" }, { extra = "cuda" }],
+]
+
+# ── PyTorch indexes ──────────────────────────────────────────────────────────
+# `explicit = true` keeps an index out of general resolution so the base
+# client-only sync is unaffected; the XPU index is left non-explicit on
+# purpose — that combination is the one measured working on this machine.
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.index]]
+name = "pytorch-xpu"
+url = "https://download.pytorch.org/whl/xpu"
+
+[[tool.uv.index]]
+name = "pytorch-cuda"
+url = "https://download.pytorch.org/whl/cu130"
+explicit = true
+
+[tool.uv.sources]
+# This binding is what actually selects the accelerator.
+torch = [
+    { index = "pytorch-cpu", extra = "cpu" },
+    { index = "pytorch-xpu", extra = "xpu" },
+    { index = "pytorch-cuda", extra = "cuda" },
+]
+torchvision = [
+    { index = "pytorch-cpu", extra = "cpu" },
+    { index = "pytorch-xpu", extra = "xpu" },
+    { index = "pytorch-cuda", extra = "cuda" },
+]
+
+# ── Development ──────────────────────────────────────────────────────────────
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint.flake8-bugbear]
+# `typer.Argument(...)` and `typer.Option(...)` are immutable factories, not mutable
+# default values, so B008's concern does not apply to them. Declared once here instead of
+# a `# noqa: B008` on every parameter that typer requires inline in the signature.
+extend-immutable-calls = ["typer.Argument", "typer.Option"]
+
+[tool.pyright]
+typeCheckingMode = "basic"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

confyui-0.1.0/src/confyui/__init__.py

@@ -0,0 +1,10 @@
+"""KπX sovereign local image generation & editing daemon over ComfyUI."""
+
+# Note: per sovereign standard, package version is defined exclusively in
+# pyproject.toml to eliminate desynchronization risks. Do NOT add __version__ here.
+
+from confyui.client import ComfyClient
+from confyui.config import Config
+from confyui.server import ServerManager
+
+__all__ = ["ComfyClient", "Config", "ServerManager"]

confyui-0.1.0/src/confyui/cli.py

@@ -0,0 +1,203 @@
+"""confyui CLI — Typer-based interface to the sovereign ComfyUI daemon.
+
+Provides `generate` (txt2img), `edit` (img2img), `inpaint`, `status`, `stop`, and `models`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from confyui.client import ComfyClient
+from confyui.config import Config
+from confyui.server import ServerManager
+
+app = typer.Typer(
+    name="confyui",
+    help="KπX sovereign local image generation & editing daemon over ComfyUI (XPU-first).",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def generate(
+    prompt: str = typer.Argument(..., help="Text prompt to generate"),
+    negative: str = typer.Option("", "--negative", "-n", help="Negative prompt"),
+    width: int = typer.Option(512, "--width", "-w", help="Image width in pixels"),
+    height: int = typer.Option(512, "--height", "-h", help="Image height in pixels"),
+    steps: int = typer.Option(20, "--steps", "-s", help="Sampling steps"),
+    cfg: float = typer.Option(7.0, "--cfg", help="Classifier-free guidance scale"),
+    seed: int | None = typer.Option(None, "--seed", help="Random seed for reproducibility"),
+    sampler: str = typer.Option("euler", "--sampler", help="Sampler name (euler, dpmpp_2m, etc.)"),
+    scheduler: str = typer.Option("normal", "--scheduler", help="Scheduler name (normal, karras, etc.)"),
+    model: str | None = typer.Option(None, "--model", "-m", help="Checkpoint filename"),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Destination path for output image"),
+    timeout: float = typer.Option(300.0, "--timeout", help="Max seconds to wait"),
+) -> None:
+    """Generate an image from text (txt2img)."""
+    client = ComfyClient()
+    with console.status("[bold green]Generating image..."):
+        dest = client.generate(
+            prompt=prompt,
+            negative_prompt=negative,
+            width=width,
+            height=height,
+            steps=steps,
+            cfg=cfg,
+            seed=seed,
+            sampler_name=sampler,
+            scheduler=scheduler,
+            model=model,
+            out=out,
+            timeout=timeout,
+        )
+    console.print(f"[bold green]✓[/bold green] Saved: [cyan]{dest}[/cyan] ({dest.stat().st_size:,} bytes)")
+
+
+@app.command()
+def edit(
+    source: Path = typer.Argument(..., help="Path to source image to modify"),
+    prompt: str = typer.Argument(..., help="Text prompt describing the desired modification"),
+    negative: str = typer.Option("", "--negative", "-n", help="Negative prompt"),
+    denoise: float = typer.Option(
+        0.55, "--denoise", "-d", help="Denoising strength (0.0 = untouched, 1.0 = full rewrite)"
+    ),
+    steps: int = typer.Option(20, "--steps", "-s", help="Sampling steps"),
+    cfg: float = typer.Option(7.0, "--cfg", help="Classifier-free guidance scale"),
+    seed: int | None = typer.Option(None, "--seed", help="Random seed for reproducibility"),
+    sampler: str = typer.Option("euler", "--sampler", help="Sampler name"),
+    scheduler: str = typer.Option("normal", "--scheduler", help="Scheduler name"),
+    model: str | None = typer.Option(None, "--model", "-m", help="Checkpoint filename"),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Destination path"),
+    timeout: float = typer.Option(300.0, "--timeout", help="Max seconds to wait"),
+) -> None:
+    """Edit an existing image with a text prompt (img2img)."""
+    client = ComfyClient()
+    with console.status(f"[bold green]Editing {source.name} (denoise={denoise})..."):
+        dest = client.edit(
+            source=source,
+            prompt=prompt,
+            negative_prompt=negative,
+            denoise=denoise,
+            steps=steps,
+            cfg=cfg,
+            seed=seed,
+            sampler_name=sampler,
+            scheduler=scheduler,
+            model=model,
+            out=out,
+            timeout=timeout,
+        )
+    console.print(f"[bold green]✓[/bold green] Saved: [cyan]{dest}[/cyan] ({dest.stat().st_size:,} bytes)")
+
+
+@app.command()
+def inpaint(
+    source: Path = typer.Argument(..., help="Path to source image"),
+    mask: Path = typer.Argument(..., help="Path to binary mask (white = regenerate, black = preserve)"),
+    prompt: str = typer.Argument(..., help="Text prompt for the masked region"),
+    negative: str = typer.Option("", "--negative", "-n", help="Negative prompt"),
+    denoise: float = typer.Option(1.0, "--denoise", "-d", help="Denoising strength for masked region"),
+    steps: int = typer.Option(25, "--steps", "-s", help="Sampling steps"),
+    cfg: float = typer.Option(7.0, "--cfg", help="Classifier-free guidance scale"),
+    seed: int | None = typer.Option(None, "--seed", help="Random seed"),
+    sampler: str = typer.Option("euler", "--sampler", help="Sampler name"),
+    scheduler: str = typer.Option("normal", "--scheduler", help="Scheduler name"),
+    model: str | None = typer.Option(None, "--model", "-m", help="Inpainting checkpoint filename"),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Destination path"),
+    timeout: float = typer.Option(300.0, "--timeout", help="Max seconds to wait"),
+) -> None:
+    """Inpaint a region defined by a mask."""
+    client = ComfyClient()
+    with console.status(f"[bold green]Inpainting {source.name}..."):
+        dest = client.inpaint(
+            source=source,
+            mask=mask,
+            prompt=prompt,
+            negative_prompt=negative,
+            denoise=denoise,
+            steps=steps,
+            cfg=cfg,
+            seed=seed,
+            sampler_name=sampler,
+            scheduler=scheduler,
+            model=model,
+            out=out,
+            timeout=timeout,
+        )
+    console.print(f"[bold green]✓[/bold green] Saved: [cyan]{dest}[/cyan] ({dest.stat().st_size:,} bytes)")
+
+
+@app.command()
+def status() -> None:
+    """Show the status of the ComfyUI background daemon."""
+    mgr = ServerManager()
+    st = mgr.status()
+
+    table = Table(title="confyui Daemon Status")
+    table.add_column("Property", style="bold cyan")
+    table.add_column("Value")
+
+    table.add_row("HTTP Server", "[green]UP[/green]" if st["http_up"] else "[red]DOWN[/red]")
+    table.add_row("Supervisor Process", "[green]ALIVE[/green]" if st["running"] else "[dim]STOPPED[/dim]")
+    table.add_row("PID", str(st["pid"]) if st["pid"] else "—")
+    table.add_row("Base URL", st["base_url"])
+    table.add_row("Idle Timeout", f"{st['idle_timeout_sec']}s")
+
+    rem = st["idle_remaining_sec"]
+    if rem is not None:
+        table.add_row("Idle Remaining", f"{rem}s before auto-shutdown")
+    else:
+        table.add_row("Idle Remaining", "—")
+
+    table.add_row("ComfyUI Dir", st["comfyui_dir"])
+    table.add_row("Log File", st["log_file"])
+
+    console.print(table)
+
+
+@app.command()
+def stop() -> None:
+    """Stop the running ComfyUI daemon and free RAM/VRAM immediately."""
+    mgr = ServerManager()
+    if mgr.stop():
+        console.print("[bold yellow]✓[/bold yellow] ComfyUI daemon stopped.")
+    else:
+        console.print("[dim]ComfyUI daemon is not running.[/dim]")
+
+
+@app.command()
+def models() -> None:
+    """List available checkpoint models in ComfyUI."""
+    client = ComfyClient()
+    ckpts = client.list_checkpoints()
+    if not ckpts:
+        console.print("[yellow]No checkpoints found in ComfyUI checkpoints directory.[/yellow]")
+        return
+
+    table = Table(title="Available Checkpoints")
+    table.add_column("#", style="dim")
+    table.add_column("Model Checkpoint", style="cyan")
+
+    cfg = Config.from_env()
+    for idx, c in enumerate(ckpts, 1):
+        suffix = ""
+        if c == cfg.default_ckpt:
+            suffix = " [bold green](default)[/bold green]"
+        elif c == cfg.default_inpaint_ckpt:
+            suffix = " [bold blue](default inpaint)[/bold blue]"
+        table.add_row(str(idx), c + suffix)
+
+    console.print(table)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()