comfyui-ruby 0.1.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 318858dd755608980d1b251b0d5271458646ee04aeba16167d4590e4293bf175
+  data.tar.gz: e23e068a97520ab5d5d7f3de2077071b9c817e5edbdd9a1bd0bdb2d32bf2badd
+SHA512:
+  metadata.gz: 25d9e51bc4582af348695f1b762c82a6e7a686b3dbe8ff908355c9c8e874a75526dd851d5853106e39f3cd18110f915345b1056828a3bb6e5823436f40aaf928
+  data.tar.gz: 0a32aba52fda57833fe399dd49cec55a81ab05f4e5b166e9455748a770c65d98bc402a293b58d2fdca6be51ef9b08ad38a7e55ac9ca31c17f21af2952c9e36e3

data/README.md

@@ -0,0 +1,35 @@
+# Comfyui::Ruby
+
+TODO: Delete this and the text below, and describe your gem
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/comfyui/ruby`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/comfyui-ruby.

data/lib/comfyui/client.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "securerandom"
+
+module ComfyUI
+  # Ruby client for the ComfyUI HTTP + WebSocket API.
+  #
+  # @example
+  #   client = ComfyUI::Client.new("http://localhost:8188")
+  #   client.system_stats
+  #   client.models
+  #   client.generate(prompt: "a cat in space")
+  #
+  class Client
+    attr_reader :url
+
+    # @param url [String] ComfyUI base URL
+    # @param timeout [Integer] HTTP timeout in seconds
+    def initialize(url = nil, timeout: 30)
+      @url = url || ENV.fetch("COMFYUI_URL", DEFAULT_URL)
+      @conn = Faraday.new(url: @url) do |f|
+        f.options.timeout = timeout
+        f.options.open_timeout = 10
+        f.request :json
+        f.response :json
+        f.response :raise_error
+      end
+      @raw_conn = Faraday.new(url: @url) do |f|
+        f.options.timeout = timeout
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Query endpoints
+    # ----------------------------------------------------------------
+
+    # Get system stats (GPU, RAM, etc.)
+    # @return [Hash]
+    def system_stats
+      get("/system_stats")
+    end
+
+    # Get queue status.
+    # @return [Hash] with queue_running and queue_pending
+    def queue_status
+      get("/queue")
+    end
+
+    # Clear the queue.
+    # @return [Boolean]
+    def clear_queue
+      post("/queue", {clear: true})
+      true
+    end
+
+    # Get available nodes and their configurations.
+    # @return [Hash]
+    def object_info
+      get("/object_info")
+    end
+
+    # Get available models grouped by type.
+    # @return [Hash{String => Array<String>}]
+    def models
+      info = object_info
+      result = {}
+
+      model_types = {
+        "checkpoints" => ["CheckpointLoaderSimple", "ckpt_name"],
+        "loras" => ["LoraLoader", "lora_name"],
+        "vae" => ["VAELoader", "vae_name"],
+        "clip" => ["CLIPLoader", "clip_name"],
+        "controlnet" => ["ControlNetLoader", "control_net_name"],
+        "upscale_models" => ["UpscaleModelLoader", "model_name"]
+      }
+
+      model_types.each do |type, (node_class, input_name)|
+        next unless info[node_class]
+
+        inputs = info.dig(node_class, "input", "required") || {}
+        next unless inputs[input_name]
+
+        input_def = inputs[input_name]
+        if input_def.is_a?(Array) && input_def[0].is_a?(Array)
+          result[type] = input_def[0]
+        end
+      end
+
+      result
+    end
+
+    # Get generation history.
+    # @param prompt_id [String, nil] specific prompt ID (nil = recent history)
+    # @param max_items [Integer] maximum items to return
+    # @return [Hash]
+    def history(prompt_id: nil, max_items: 100)
+      if prompt_id
+        get("/history/#{prompt_id}")
+      else
+        get("/history", max_items: max_items)
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Workflow execution
+    # ----------------------------------------------------------------
+
+    # Queue a workflow for execution.
+    # @param workflow [Hash] ComfyUI API format workflow
+    # @param client_id [String] client ID for WebSocket tracking
+    # @return [Hash] with prompt_id and number
+    def queue_prompt(workflow, client_id: nil)
+      client_id ||= SecureRandom.uuid
+      payload = {prompt: workflow, client_id: client_id}
+      result = post("/prompt", payload)
+
+      if result["error"]
+        raise APIError, "Workflow error: #{result["error"]}"
+      end
+
+      result
+    end
+
+    # Run a workflow and wait for completion via polling.
+    # @param workflow [Hash] ComfyUI API format workflow
+    # @param timeout [Float] max wait in seconds
+    # @param on_progress [Proc, nil] callback(step, total, message)
+    # @return [WorkflowResult]
+    def run_workflow(workflow, timeout: 600, on_progress: nil)
+      client_id = SecureRandom.uuid
+      result = queue_prompt(workflow, client_id: client_id)
+      prompt_id = result["prompt_id"]
+
+      poll_for_completion(prompt_id, timeout: timeout, on_progress: on_progress)
+    end
+
+    # Generate an image with a simple text-to-image workflow.
+    # @param prompt [String] positive prompt
+    # @param negative_prompt [String] negative prompt
+    # @param model [String, nil] checkpoint name (nil = first available)
+    # @param width [Integer] image width
+    # @param height [Integer] image height
+    # @param steps [Integer] sampling steps
+    # @param cfg [Float] CFG scale
+    # @param seed [Integer] seed (-1 = random)
+    # @param sampler [String] sampler name
+    # @param scheduler [String] scheduler name
+    # @param lora_name [String, nil] LoRA filename
+    # @param lora_strength [Float] LoRA strength
+    # @param batch_size [Integer] images per batch
+    # @param vae [String, nil] VAE filename
+    # @param timeout [Float] max wait in seconds
+    # @param on_progress [Proc, nil] callback(step, total, message)
+    # @return [GenerationResult]
+    def generate(
+      prompt:,
+      negative_prompt: "",
+      model: nil,
+      width: 1024,
+      height: 1024,
+      steps: 20,
+      cfg: 7.0,
+      seed: -1,
+      sampler: "euler",
+      scheduler: "normal",
+      lora_name: nil,
+      lora_strength: 1.0,
+      batch_size: 1,
+      vae: nil,
+      timeout: 600,
+      on_progress: nil
+    )
+      # Auto-select first checkpoint if none specified
+      unless model
+        available = models
+        model = available["checkpoints"]&.first
+        raise Error, "No checkpoints available" unless model
+      end
+
+      workflow = ComfyUI::Workflow.build(
+        prompt: prompt,
+        negative_prompt: negative_prompt,
+        model: model,
+        width: width,
+        height: height,
+        steps: steps,
+        cfg: cfg,
+        seed: seed,
+        sampler: sampler,
+        scheduler: scheduler,
+        lora_name: lora_name,
+        lora_strength: lora_strength,
+        batch_size: batch_size,
+        vae: vae
+      )
+
+      result = run_workflow(workflow, timeout: timeout, on_progress: on_progress)
+
+      images = result.outputs.each_with_object([]) do |(_node_id, output), acc|
+        next unless output["images"]
+
+        output["images"].each do |img_info|
+          filename = img_info["filename"]
+          subfolder = img_info["subfolder"] || ""
+          type = img_info["type"] || "output"
+          acc << {filename: filename, subfolder: subfolder, type: type} if type == "output"
+        end
+      end
+
+      GenerationResult.new(
+        prompt_id: result.prompt_id,
+        images: images,
+        node_errors: result.node_errors,
+        success: result.success
+      )
+    end
+
+    # Download a generated image.
+    # @param filename [String] image filename
+    # @param subfolder [String] subfolder
+    # @param folder_type [String] output, input, or temp
+    # @return [String] image bytes
+    def image(filename, subfolder: "", folder_type: "output")
+      response = @raw_conn.get("/view", {
+        filename: filename,
+        subfolder: subfolder,
+        type: folder_type
+      })
+      response.body
+    end
+
+    private
+
+    def get(path, params = {})
+      response = @conn.get(path, params)
+      response.body
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise ConnectionError, "Failed to connect to ComfyUI at #{@url}: #{e.message}"
+    rescue Faraday::ClientError, Faraday::ServerError => e
+      raise APIError, "ComfyUI API error: #{e.message}"
+    end
+
+    def post(path, body = {})
+      response = @conn.post(path) { |req| req.body = body }
+      response.body
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise ConnectionError, "Failed to connect to ComfyUI at #{@url}: #{e.message}"
+    rescue Faraday::ClientError, Faraday::ServerError => e
+      raise APIError, "ComfyUI API error: #{e.message}"
+    end
+
+    def poll_for_completion(prompt_id, timeout: 600, on_progress: nil)
+      start = Time.now
+      interval = 0.5
+
+      loop do
+        elapsed = Time.now - start
+        raise TimeoutError, "Workflow did not complete within #{timeout}s" if elapsed > timeout
+
+        hist = history(prompt_id: prompt_id)
+
+        if hist[prompt_id]
+          entry = hist[prompt_id]
+          outputs = entry["outputs"] || {}
+          status = entry.dig("status", "status_str")
+
+          if status == "error"
+            return WorkflowResult.new(
+              prompt_id: prompt_id,
+              outputs: outputs,
+              node_errors: entry.dig("status", "messages") || {},
+              success: false
+            )
+          end
+
+          return WorkflowResult.new(
+            prompt_id: prompt_id,
+            outputs: outputs,
+            success: true
+          )
+        end
+
+        on_progress&.call(0, 0, "Running...")
+        sleep interval
+      end
+    end
+  end
+end

data/lib/comfyui/result.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ComfyUI
+  GenerationResult = Data.define(:prompt_id, :images, :node_errors, :success) do
+    def initialize(prompt_id:, images: [], node_errors: {}, success: true)
+      super
+    end
+  end
+
+  WorkflowResult = Data.define(:prompt_id, :outputs, :node_errors, :success) do
+    def initialize(prompt_id:, outputs: {}, node_errors: {}, success: true)
+      super
+    end
+  end
+end

data/lib/comfyui/version.rb

@@ -0,0 +1,3 @@
+module ComfyUI
+  VERSION = "0.1.0.pre1"
+end

data/lib/comfyui/workflow.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module ComfyUI
+  # Default SDXL/Illustrious/Pony compatible workflow template.
+  # Uses separate VAE loader for better quality with modern models.
+  DEFAULT_WORKFLOW = {
+    "3" => {
+      "class_type" => "KSampler",
+      "inputs" => {
+        "seed" => 0,
+        "steps" => 20,
+        "cfg" => 7.0,
+        "sampler_name" => "euler",
+        "scheduler" => "normal",
+        "denoise" => 1.0,
+        "model" => ["4", 0],
+        "positive" => ["6", 0],
+        "negative" => ["7", 0],
+        "latent_image" => ["5", 0]
+      }
+    },
+    "4" => {
+      "class_type" => "CheckpointLoaderSimple",
+      "inputs" => {"ckpt_name" => ""}
+    },
+    "5" => {
+      "class_type" => "EmptyLatentImage",
+      "inputs" => {"width" => 1024, "height" => 1024, "batch_size" => 1}
+    },
+    "6" => {
+      "class_type" => "CLIPTextEncode",
+      "inputs" => {"text" => "", "clip" => ["4", 1]}
+    },
+    "7" => {
+      "class_type" => "CLIPTextEncode",
+      "inputs" => {"text" => "", "clip" => ["4", 1]}
+    },
+    "8" => {
+      "class_type" => "VAEDecode",
+      "inputs" => {"samples" => ["3", 0], "vae" => ["11", 0]}
+    },
+    "9" => {
+      "class_type" => "SaveImage",
+      "inputs" => {"filename_prefix" => "comfy", "images" => ["8", 0]}
+    },
+    "11" => {
+      "class_type" => "VAELoader",
+      "inputs" => {"vae_name" => "sdxl_vae.safetensors"}
+    }
+  }.freeze
+
+  LORA_LOADER_NODE = {
+    "class_type" => "LoraLoader",
+    "inputs" => {
+      "lora_name" => "",
+      "strength_model" => 1.0,
+      "strength_clip" => 1.0,
+      "model" => ["4", 0],
+      "clip" => ["4", 1]
+    }
+  }.freeze
+
+  DEFAULT_VAE = "sdxl_vae.safetensors"
+
+  module Workflow
+    module_function
+
+    # Build a text-to-image workflow from parameters.
+    #
+    # @param prompt [String] positive prompt
+    # @param negative_prompt [String] negative prompt
+    # @param model [String, nil] checkpoint filename
+    # @param width [Integer] image width
+    # @param height [Integer] image height
+    # @param steps [Integer] sampling steps
+    # @param cfg [Float] CFG scale
+    # @param seed [Integer] random seed (-1 for random)
+    # @param sampler [String] sampler name
+    # @param scheduler [String] scheduler name
+    # @param lora_name [String, nil] LoRA filename
+    # @param lora_strength [Float] LoRA strength
+    # @param batch_size [Integer] images per batch
+    # @param vae [String, nil] VAE filename (nil = use checkpoint's VAE)
+    # @return [Hash] ComfyUI API workflow
+    def build(
+      prompt:,
+      negative_prompt: "",
+      model: nil,
+      width: 1024,
+      height: 1024,
+      steps: 20,
+      cfg: 7.0,
+      seed: -1,
+      sampler: "euler",
+      scheduler: "normal",
+      lora_name: nil,
+      lora_strength: 1.0,
+      batch_size: 1,
+      vae: nil
+    )
+      wf = JSON.parse(JSON.generate(DEFAULT_WORKFLOW)) # deep copy
+
+      actual_seed = seed >= 0 ? seed : rand(2**32)
+
+      # KSampler
+      wf["3"]["inputs"].merge!(
+        "seed" => actual_seed,
+        "steps" => steps,
+        "cfg" => cfg,
+        "sampler_name" => sampler,
+        "scheduler" => scheduler
+      )
+
+      # Checkpoint
+      wf["4"]["inputs"]["ckpt_name"] = model if model
+
+      # Dimensions
+      wf["5"]["inputs"].merge!("width" => width, "height" => height, "batch_size" => batch_size)
+
+      # Prompts
+      wf["6"]["inputs"]["text"] = prompt
+      wf["7"]["inputs"]["text"] = negative_prompt
+
+      # VAE
+      if vae
+        wf["11"]["inputs"]["vae_name"] = vae
+      else
+        wf.delete("11")
+        wf["8"]["inputs"]["vae"] = ["4", 2]
+      end
+
+      # LoRA injection
+      if lora_name
+        lora = JSON.parse(JSON.generate(LORA_LOADER_NODE))
+        lora["inputs"].merge!(
+          "lora_name" => lora_name,
+          "strength_model" => lora_strength,
+          "strength_clip" => lora_strength,
+          "model" => ["4", 0],
+          "clip" => ["4", 1]
+        )
+        wf["10"] = lora
+
+        wf["3"]["inputs"]["model"] = ["10", 0]
+        wf["6"]["inputs"]["clip"] = ["10", 1]
+        wf["7"]["inputs"]["clip"] = ["10", 1]
+      end
+
+      wf
+    end
+  end
+end

data/lib/comfyui.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "comfyui/version"
+require_relative "comfyui/client"
+require_relative "comfyui/workflow"
+require_relative "comfyui/result"
+
+module ComfyUI
+  DEFAULT_URL = "http://127.0.0.1:8188"
+
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class APIError < Error; end
+  class TimeoutError < Error; end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: comfyui-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre1
+platform: ruby
+authors:
+- aladac
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faye-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+description: A Ruby client for ComfyUI — query models, queue workflows, generate images,
+  and track progress via WebSocket.
+email:
+- aladac@saiden.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/comfyui.rb
+- lib/comfyui/client.rb
+- lib/comfyui/result.rb
+- lib/comfyui/version.rb
+- lib/comfyui/workflow.rb
+homepage: https://github.com/aladac/comfyui-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aladac/comfyui-ruby
+  source_code_uri: https://github.com/aladac/comfyui-ruby
+  changelog_uri: https://github.com/aladac/comfyui-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the ComfyUI API
+test_files: []