zer0-image-generator 0.6.0 → 0.8.0

data/lib/zer0_image_generator/prompt.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "content"
+
+module Zer0ImageGenerator
+  # Prompt layer: turn a ContentFile plus resolved Settings into the text prompt
+  # the image model receives. Ported from the oracle
+  # (lib/zer0_image_generator/preview_generator.py). Wording is carried over
+  # verbatim from the original engine and must not drift — the committed showcase
+  # briefs were produced from these exact strings.
+  module Prompt
+    # Fallback used by build_enhance_prompt when settings.enhance_prompt is
+    # empty. Kept byte-identical to the oracle's DEFAULT_ENHANCE_PROMPT.
+    DEFAULT_ENHANCE_PROMPT =
+      "Improve this preview banner image: fix any misspelled, garbled, or " \
+      "incorrect text so it reads clearly and accurately. Sharpen visual details " \
+      "and improve composition while preserving the original art style, color " \
+      "palette, and theme. Ensure the image is clean and professional."
+
+    # Template prompt — wording carried over from the original engine.
+    def self.build_prompt(cf, settings)
+      parts = ["Create a blog preview banner image for an article titled '#{cf.title}'."]
+      parts << "The article is about: #{cf.description}." unless cf.description.empty?
+      parts << "Categories: #{cf.categories}." unless cf.categories.empty?
+      # First 500 characters, whitespace-collapsed — Content.collapse_whitespace
+      # reproduces CPython's `re.sub(r"\s+", " ", ...).strip()` exactly.
+      excerpt = Content.collapse_whitespace(cf.content[0, 500] || "")
+      parts << "Key themes from content: #{excerpt}" unless excerpt.empty?
+      parts << "Art style: #{settings.style}."
+      unless settings.style_modifiers.empty?
+        parts << "Additional style: #{settings.style_modifiers}."
+      end
+      parts << "The image should be suitable as a wide blog header/banner image with " \
+               "clean composition. No text or words in the image."
+      parts.join(" ")
+    end
+
+    def self.build_enhance_prompt(cf, settings)
+      prompt = settings.enhance_prompt.empty? ? DEFAULT_ENHANCE_PROMPT : settings.enhance_prompt
+      unless cf.title.empty?
+        prompt += " Context: This is a preview banner for an article titled '#{cf.title}'."
+      end
+      prompt += " Article topic: #{cf.description}." unless cf.description.empty?
+      prompt += " Maintain the #{settings.style} artistic style."
+      prompt
+    end
+  end
+end

data/lib/zer0_image_generator/providers/base.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "base64"
+require "pathname"
+
+# Port of the provider-layer scaffolding from preview_generator.py
+# (ImageResult, EditUnsupported, Provider, RunContext, adapt_openai_size_quality,
+# and the shared _write_image_payload helper). The concrete providers live in
+# sibling files; this one carries only what they all share.
+#
+# Cross-slice dependencies are referenced by their natural names and resolved at
+# call time (never at load time), so this file loads even while the http/svg/
+# settings/logging slices are still landing:
+#   Zer0ImageGenerator::Http         — .json/.multipart/.download_to/.with_retries
+#   Zer0ImageGenerator::HttpStatusError#error_message
+#   Zer0ImageGenerator::Svg::Sanitizer.sanitize_svg / ::LocalRenderer.{seed_for,
+#     render_local_svg} / ::Rasterizer.rasterize_svg + Svg::SvgError
+#   Zer0ImageGenerator.effective_model(settings, provider)
+#   Zer0ImageGenerator::Logging.warn / .info / .debug
+module Zer0ImageGenerator
+  # Historical engine behavior: adapt shared size/quality settings per model
+  # family. The mapping MUST stay exact — gpt-image-* and dall-e-3 accept
+  # disjoint size/quality vocabularies, and a wrong value 400s the request.
+  def self.adapt_openai_size_quality(model, size, quality)
+    if model.start_with?("gpt-image-") && size == "1792x1024"
+      size = "1536x1024"
+    elsif model.start_with?("dall-e-") && quality == "auto"
+      quality = "standard"
+    end
+    [size, quality]
+  end
+
+  # Outcome of one generate/edit call. Positional (ok, kind, path) mirrors the
+  # Python dataclass construction order; `error` stays a keyword so the many
+  # `ImageResult(False, error=...)` call sites read the same in Ruby.
+  class ImageResult
+    attr_reader :ok, :kind, :path, :error
+
+    def initialize(ok, kind = "png", path = nil, error: nil)
+      @ok = ok
+      @kind = kind    # "png" | "svg"
+      @path = path
+      @error = error
+    end
+
+    # Runner (another slice) reads `.ok`; `.ok?` is the idiomatic Ruby alias.
+    def ok?
+      @ok
+    end
+  end
+
+  # Raised by Provider#edit for renderers with no image-edit capability; the
+  # runner catches it and falls back to OpenAI (the historical --enhance path).
+  class EditUnsupported < StandardError
+    attr_reader :provider
+
+    def initialize(provider)
+      @provider = provider
+      super("provider '#{provider}' has no image-edit capability")
+    end
+  end
+
+  class Provider
+    def name
+      "base"
+    end
+
+    def is_configured(_env)
+      raise NotImplementedError
+    end
+
+    def missing_hint(_env)
+      raise NotImplementedError
+    end
+
+    def default_model
+      raise NotImplementedError
+    end
+
+    # One line naming the credential this run will authenticate with, for the
+    # config banner. nil (the default) means "there is nothing interesting to
+    # say" — a provider with exactly one possible credential.
+    def auth_description(_env)
+      nil
+    end
+
+    def generate(_prompt, _settings, _out_base, _ctx)
+      raise NotImplementedError
+    end
+
+    # Enhance an existing image. Providers without an edit capability raise
+    # EditUnsupported; the runner then falls back to OpenAI.
+    def edit(_image_path, _prompt, _settings, _ctx, _out_path = nil)
+      raise EditUnsupported, name
+    end
+
+    private
+
+    # Persist one OpenAI-style data[0] entry (b64_json preferred, else url).
+    # nil/empty strings count as "absent" to match Python's truthiness on
+    # `entry.get(...)` — a present-but-empty value must not be treated as data.
+    def write_image_payload(entry, out_path)
+      b64 = entry["b64_json"]
+      if b64 && !b64.empty?
+        File.binwrite(out_path.to_s, Base64.decode64(b64))
+        return true
+      end
+      url = entry["url"]
+      if url && !url.empty?
+        Http.download_to(url, out_path)
+        return true
+      end
+      false
+    end
+  end
+
+  # Run-scoped services handed to providers. The per-file `slug` is why the
+  # runner hands each worker its OWN copy (see #copy_with): the local provider
+  # derives its deterministic seed from the slug, so a shared mutable slug would
+  # cross-contaminate concurrent renders.
+  class RunContext
+    attr_reader :project_root, :env
+    attr_accessor :anthropic, :slug, :article
+
+    def initialize(project_root:, env:, anthropic: nil, slug: "", article: nil)
+      @project_root = project_root
+      @env = env
+      @anthropic = anthropic
+      @slug = slug
+      # The page's own context (slug/section/title/categories/description/body),
+      # set per file by the runner. The local renderer derives BOTH composition
+      # and palette from it, which is what makes a banner about its article
+      # instead of about its filename.
+      @article = article
+    end
+
+    def claude
+      # Lazy, memoized — matches the Python `if self.anthropic is None`.
+      @anthropic ||= AnthropicClient.new(@env)
+    end
+
+    # Per-file copy carrying a fresh slug (the runner calls `ctx.with_slug(slug)`
+    # once per worker). project_root/env/anthropic are shared by reference on
+    # purpose: env is read-only and the AnthropicClient is stateless after init,
+    # so sharing them across workers is thread-safe; only the slug is per-file
+    # and therefore must not be shared.
+    def with_slug(slug, article: nil)
+      RunContext.new(project_root: @project_root, env: @env,
+                     anthropic: @anthropic, slug: slug, article: article)
+    end
+  end
+end

data/lib/zer0_image_generator/providers/gemini.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Zer0ImageGenerator
+  # Google Gemini generateContent. The image comes back as inline base64 nested
+  # under candidates[].content.parts[], keyed either `inlineData` (REST/JSON) or
+  # `inline_data` (proto) — accept both.
+  class GeminiProvider < Provider
+    def name
+      "gemini"
+    end
+
+    def is_configured(env)
+      key = env["GEMINI_API_KEY"]
+      !key.nil? && !key.empty?
+    end
+
+    def missing_hint(_env)
+      "GEMINI_API_KEY environment variable is required for the Gemini provider"
+    end
+
+    def default_model
+      "gemini-2.5-flash-image"
+    end
+
+    def generate(prompt, settings, out_base, ctx)
+      model = Zer0ImageGenerator.effective_model(settings, self)
+      out_path = out_base.sub_ext(".png")
+      url = "https://generativelanguage.googleapis.com/v1beta/models/" \
+            "#{model}:generateContent"
+      payload = { "contents" => [{ "parts" => [{ "text" => prompt }] }] }
+      begin
+        data = Http.with_retries("Gemini API") do
+          Http.json(url, payload,
+                    { "x-goog-api-key" => ctx.env.fetch("GEMINI_API_KEY") },
+                    timeout: 900)
+        end
+        (data["candidates"] || []).each do |candidate|
+          parts = ((candidate["content"] || {})["parts"]) || []
+          parts.each do |part|
+            inline = part["inlineData"] || part["inline_data"]
+            next unless inline
+
+            payload_b64 = inline["data"]
+            next if payload_b64.nil? || payload_b64.empty?
+
+            File.binwrite(out_path.to_s, Base64.decode64(payload_b64))
+            return ImageResult.new(true, "png", out_path)
+          end
+        end
+        ImageResult.new(false, error: "No inline image data in Gemini response")
+      rescue HttpStatusError => exc
+        ImageResult.new(false, error: "Gemini API error: #{exc.error_message}")
+      rescue StandardError => exc
+        ImageResult.new(false, error: exc.message)
+      end
+    end
+  end
+end

data/lib/zer0_image_generator/providers/local.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Zer0ImageGenerator
+  # Shared sanitize -> write -> rasterize tail for SVG-producing providers
+  # (local now; claude when that renderer lands). Mixed into a Provider.
+  module SvgProviderMixin
+    def finish_svg(svg_text, out_base, settings, ctx)
+      begin
+        clean, notes = Svg::Sanitizer.sanitize_svg(svg_text)
+      rescue Svg::SvgError => exc
+        return ImageResult.new(false, error: exc.message)
+      end
+      notes.each { |note| Logging.warn("SVG sanitizer: #{note}") }
+      svg_path = out_base.sub_ext(".svg")
+      png_path = out_base.sub_ext(".png")
+      File.write(svg_path.to_s, clean)
+      tool = Svg::Rasterizer.rasterize_svg(svg_path, png_path, ctx.project_root,
+                                           preference: settings.rasterizer)
+      if tool
+        # missing_ok: the rasterizer already consumed the SVG on some backends.
+        File.delete(svg_path.to_s) if File.exist?(svg_path.to_s)
+        return ImageResult.new(true, "png", png_path)
+      end
+      # `rasterizer: none` is a deliberate site policy (SVG-only), not a missing
+      # dependency — say so instead of nagging about librsvg.
+      if settings.rasterizer == "none"
+        Logging.info("SVG-only mode (rasterizer: none) — wrote #{File.basename(svg_path.to_s)}")
+      else
+        Logging.warn(
+          "No SVG rasterizer available — keeping the .svg preview. Social " \
+          "og:image works best as PNG: install librsvg (`brew install librsvg`) " \
+          "or Playwright (`npx playwright install chromium`), or set " \
+          "`preview_images.rasterizer: none` to make SVG-only the intent."
+        )
+      end
+      ImageResult.new(true, "svg", svg_path)
+    end
+  end
+
+  # Network-free, deterministic renderer: it renders the local SVG, sanitizes
+  # it, and rasterizes it. This is the path CI's integration job exercises.
+  class LocalProvider < Provider
+    include SvgProviderMixin
+
+    def name
+      "local"
+    end
+
+    def is_configured(_env)
+      true
+    end
+
+    def missing_hint(_env)
+      ""
+    end
+
+    def default_model
+      "template-svg"
+    end
+
+    def generate(_prompt, settings, out_base, ctx)
+      # `ctx.slug or out_base.stem`: an empty slug (Python-falsy) falls back to
+      # the output stem for the seed, but the raw slug — empty or not — is still
+      # what render_local_svg titles the banner with.
+      seed_key = ctx.slug.to_s.empty? ? stem_of(out_base) : ctx.slug
+      seed = Svg::LocalRenderer.seed_for(seed_key)
+      svg_text = Svg::LocalRenderer.render_local_svg(ctx.slug, seed, ctx.article)
+      finish_svg(svg_text, out_base, settings, ctx)
+    end
+
+    def edit(image_path, prompt, _settings, _ctx, _out_path = nil)
+      # Historical behavior: the local provider "enhances" by doing nothing (no
+      # API), so dry testing of --enhance needs no credentials.
+      Logging.warn("Local provider: No actual enhancement. Logging prompt...")
+      Logging.debug("Enhancement prompt: #{prompt[0, 400]}...")
+      Logging.info("Placeholder: would enhance #{image_path}")
+      ImageResult.new(true, "png", image_path)
+    end
+
+    private
+
+    # Pathname has no #stem; Path.stem is the basename minus its final suffix.
+    def stem_of(path)
+      s = path.to_s
+      File.basename(s, File.extname(s))
+    end
+  end
+end

data/lib/zer0_image_generator/providers/openai.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Zer0ImageGenerator
+  # OpenAI images/generations + images/edits (the --enhance path).
+  class OpenAIProvider < Provider
+    def name
+      "openai"
+    end
+
+    def is_configured(env)
+      key = env["OPENAI_API_KEY"]
+      !key.nil? && !key.empty?
+    end
+
+    def missing_hint(_env)
+      "OPENAI_API_KEY environment variable is required for the OpenAI provider"
+    end
+
+    def default_model
+      "gpt-image-2"
+    end
+
+    def generate(prompt, settings, out_base, ctx)
+      model = Zer0ImageGenerator.effective_model(settings, self)
+      size, quality = Zer0ImageGenerator.adapt_openai_size_quality(
+        model, settings.size, settings.quality
+      )
+      out_path = out_base.sub_ext(".png")
+      payload = { "model" => model, "prompt" => prompt, "n" => 1,
+                  "size" => size, "quality" => quality }
+      Logging.debug("OpenAI generate: model=#{model} size=#{size} quality=#{quality}")
+      begin
+        data = Http.with_retries("OpenAI API") do
+          Http.json("https://api.openai.com/v1/images/generations",
+                    payload, headers(ctx.env), timeout: 900)
+        end
+        entries = data["data"] || []
+        if entries.empty? || !write_image_payload(entries[0], out_path)
+          return ImageResult.new(false, error: "No image data in OpenAI response")
+        end
+
+        ImageResult.new(true, "png", out_path)
+      rescue HttpStatusError => exc
+        ImageResult.new(false, error: "OpenAI API error: #{exc.error_message}")
+      rescue StandardError => exc
+        ImageResult.new(false, error: exc.message)
+      end
+    end
+
+    def edit(image_path, prompt, settings, ctx, out_path = nil)
+      model = settings.enhance_model
+      fields = {
+        "prompt" => prompt,
+        "model" => model,
+        "n" => "1",
+        "size" => "auto",
+        "quality" => settings.enhance_quality,
+        "output_format" => settings.enhance_format,
+      }
+      # gpt-image-2 does not accept input_fidelity (historical behavior).
+      fields["input_fidelity"] = settings.enhance_fidelity if model != "gpt-image-2"
+      files = [["image[]", image_path.basename.to_s,
+                File.binread(image_path.to_s), "image/png"]]
+      out_path ||= image_path
+      Logging.debug(
+        "OpenAI edit: model=#{model} fidelity=" \
+        "#{fields.fetch('input_fidelity', '(omitted)')} format=#{settings.enhance_format}"
+      )
+      begin
+        data = Http.with_retries("OpenAI edits API") do
+          Http.multipart("https://api.openai.com/v1/images/edits",
+                         fields, files, headers(ctx.env), timeout: 900)
+        end
+        usage = data["usage"] || {}
+        # Python `if usage.get("total_tokens")` treats 0 as absent — mirror that
+        # so Ruby's truthy 0 doesn't emit a bogus "0 total" line.
+        total_tokens = usage["total_tokens"]
+        Logging.debug("Token usage: #{total_tokens} total") if total_tokens && total_tokens != 0
+        entries = data["data"] || []
+        if entries.empty? || !write_image_payload(entries[0], out_path)
+          return ImageResult.new(false, error: "No image data in enhance response")
+        end
+
+        revised = entries[0]["revised_prompt"]
+        Logging.debug("Revised prompt: #{revised[0, 200]}...") if revised && !revised.empty?
+        ImageResult.new(true, "png", out_path)
+      rescue HttpStatusError => exc
+        ImageResult.new(false, error: "OpenAI enhance API error: #{exc.error_message}")
+      rescue StandardError => exc
+        ImageResult.new(false, error: exc.message)
+      end
+    end
+
+    private
+
+    def headers(env)
+      { "Authorization" => "Bearer #{env.fetch('OPENAI_API_KEY')}" }
+    end
+  end
+end

data/lib/zer0_image_generator/providers/stability.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Zer0ImageGenerator
+  # Stability AI SDXL v1 text-to-image. Returns base64 under `artifacts`, not the
+  # OpenAI-style `data` envelope, so it decodes inline rather than via
+  # write_image_payload.
+  class StabilityProvider < Provider
+    def name
+      "stability"
+    end
+
+    def is_configured(env)
+      key = env["STABILITY_API_KEY"]
+      !key.nil? && !key.empty?
+    end
+
+    def missing_hint(_env)
+      "STABILITY_API_KEY environment variable is required for the Stability AI provider"
+    end
+
+    def default_model
+      "stable-diffusion-xl-1024-v1-0"
+    end
+
+    def generate(prompt, _settings, out_base, ctx)
+      out_path = out_base.sub_ext(".png")
+      payload = {
+        "text_prompts" => [{ "text" => prompt }],
+        "cfg_scale" => 7,
+        # SDXL v1 endpoint accepts fixed dimension sets; 1024x1024 preserved
+        # from the original engine.
+        "height" => 1024,
+        "width" => 1024,
+        "samples" => 1,
+        "steps" => 30,
+      }
+      begin
+        data = Http.with_retries("Stability API") do
+          Http.json(
+            "https://api.stability.ai/v1/generation/" \
+            "stable-diffusion-xl-1024-v1-0/text-to-image",
+            payload,
+            { "Authorization" => "Bearer #{ctx.env.fetch('STABILITY_API_KEY')}" },
+            timeout: 900
+          )
+        end
+        artifacts = data["artifacts"] || []
+        first_b64 = artifacts.empty? ? nil : artifacts[0]["base64"]
+        if artifacts.empty? || first_b64.nil? || first_b64.empty?
+          return ImageResult.new(false, error: "No image data in Stability response")
+        end
+
+        File.binwrite(out_path.to_s, Base64.decode64(first_b64))
+        ImageResult.new(true, "png", out_path)
+      rescue HttpStatusError => exc
+        ImageResult.new(false, error: "Stability API error: #{exc.error_message}")
+      rescue StandardError => exc
+        ImageResult.new(false, error: exc.message)
+      end
+    end
+  end
+end

data/lib/zer0_image_generator/providers/xai.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "xai_auth"
+
+module Zer0ImageGenerator
+  # xAI (Grok) images/generations.
+  #
+  # Two ways in, tried in order (XAIAuth owns the resolution): a Grok OAuth
+  # access token, then the XAI_API_KEY. Both are Bearer credentials on the same
+  # endpoint, so the fallback is genuinely a retry with a different token — an
+  # OAuth token that has gone stale between runs costs one rejected request and
+  # then rides the API key instead of failing the page.
+  class XAIProvider < Provider
+    # Statuses that mean "this credential is no good" rather than "this request
+    # is no good" — the only ones worth re-trying on the next rung.
+    AUTH_FAILURE_STATUSES = [401, 403].freeze
+
+    # xAI caps the prompt; the original engine slices the first 1000 chars.
+    PROMPT_LIMIT = 1000
+
+    def name
+      "xai"
+    end
+
+    def is_configured(env)
+      !XAIAuth.chain(env).empty?
+    end
+
+    def missing_hint(_env)
+      XAIAuth::MISSING_HINT
+    end
+
+    def auth_description(env)
+      XAIAuth.describe(env)
+    end
+
+    def default_model
+      "grok-2-image"
+    end
+
+    def generate(prompt, settings, out_base, ctx)
+      credentials = XAIAuth.chain(ctx.env)
+      return ImageResult.new(false, error: XAIAuth::MISSING_HINT) if credentials.empty?
+
+      model = Zer0ImageGenerator.effective_model(settings, self)
+      out_path = out_base.sub_ext(".png")
+      payload = { "model" => model, "prompt" => prompt[0, PROMPT_LIMIT], "n" => 1 }
+      url = "#{XAIAuth.base_url(ctx.env)}/images/generations"
+
+      credentials.each_with_index do |credential, index|
+        Logging.debug("xAI generate: model=#{model} auth=#{credential.source}")
+        begin
+          data = Http.with_retries("xAI API") do
+            Http.json(url, payload, credential.headers, timeout: 900)
+          end
+          entries = data["data"] || []
+          if entries.empty? || !write_image_payload(entries[0], out_path)
+            return ImageResult.new(false, error: "No image data in xAI response")
+          end
+
+          return ImageResult.new(true, "png", out_path)
+        rescue HttpStatusError => exc
+          fallback = credentials[index + 1]
+          if AUTH_FAILURE_STATUSES.include?(exc.status) && fallback
+            Logging.warn("xAI rejected the #{credential.source} (HTTP #{exc.status}) — " \
+                         "retrying with #{fallback.source}")
+            next
+          end
+
+          return ImageResult.new(false, error: "xAI API error: #{exc.error_message}")
+        rescue StandardError => exc
+          return ImageResult.new(false, error: exc.message)
+        end
+      end
+
+      # Unreachable: the last rung has no fallback and always returns above.
+      ImageResult.new(false, error: "No usable xAI credential")
+    end
+  end
+end