flux3_ai_prompt_tools 0.1.0

data/lib/flux3_ai_prompt_tools/validator.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "fields"
+require_relative "limits"
+require_relative "numbers"
+require_relative "presets"
+require_relative "layouts"
+
+module Flux3AiPromptTools
+  # Checks one prompt record and returns a clean hash when every field is usable.
+  class Validator
+    def initialize(limits = Limits::DEFAULT)
+      unless limits.is_a?(Limits)
+        raise ArgumentError, "limits must be a Flux3AiPromptTools::Limits"
+      end
+
+      @limits = limits
+    end
+
+    # Returns [clean_hash_or_nil, issues, explicit_id_or_nil].
+    # clean_hash is present only when issues is empty. explicit_id is the
+    # caller-supplied id when that field itself is valid.
+    def prepare(input, pointer:)
+      issues = []
+      base = pointer.to_s
+      unless input.is_a?(Hash)
+        issues << Issue.new(base.empty? ? "/" : base, "type", "record must be an object")
+        return [nil, issues, nil]
+      end
+
+      normalized = normalize_keys(input, base, issues)
+      normalized.each_key do |name|
+        next if Fields::NAMES.include?(name)
+
+        issues << Issue.new(field_path(base, name), "unknown_field", "unknown field #{name.inspect}")
+      end
+
+      coerced = {}
+      coerce_fields(normalized, coerced, issues, base)
+      explicit_id = coerced["id"]
+      return [nil, issues, explicit_id] unless issues.empty?
+
+      [merge_clean(normalized, coerced), issues, explicit_id]
+    end
+
+    private
+
+    def normalize_keys(input, pointer, issues)
+      normalized = {}
+      input.each do |key, value|
+        name = case key
+               when String then key
+               when Symbol then key.to_s
+               else
+                 issues << Issue.new(pointer.empty? ? "/" : pointer, "type", "field names must be strings")
+                 next
+               end
+        if normalized.key?(name)
+          issues << Issue.new(field_path(pointer, name), "duplicate_field", "field #{name} was given more than once")
+          next
+        end
+        normalized[name] = value
+      end
+      normalized
+    end
+
+    def coerce_fields(normalized, coerced, issues, pointer)
+      coerce_id(normalized, coerced, issues, pointer)
+      coerce_subject(normalized, coerced, issues, pointer)
+      Fields::STRING_LIMITS.each_key do |name|
+        next if name == "subject"
+
+        coerce_optional_string(normalized, coerced, issues, pointer, name)
+      end
+      coerce_preset(normalized, coerced, issues, pointer)
+      coerce_layout(normalized, coerced, issues, pointer)
+      coerce_details(normalized, coerced, issues, pointer)
+      coerce_negatives(normalized, coerced, issues, pointer)
+      coerce_aspect_ratio(normalized, coerced, issues, pointer)
+      coerce_seed(normalized, coerced, issues, pointer)
+      coerce_steps(normalized, coerced, issues, pointer)
+      coerce_guidance(normalized, coerced, issues, pointer)
+    end
+
+    def coerce_id(normalized, coerced, issues, pointer)
+      return unless normalized.key?("id") && !normalized["id"].nil?
+
+      value = normalized["id"]
+      path = field_path(pointer, "id")
+      unless value.is_a?(String)
+        issues << Issue.new(path, "type", "id must be a string")
+        return
+      end
+
+      stripped = value.strip
+      if stripped.match?(Fields::ID_PATTERN)
+        coerced["id"] = stripped
+      else
+        issues << Issue.new(path, "format", "id must start with a letter or digit and then use only letters, digits, dots, underscores, or hyphens (64 characters max)")
+      end
+    end
+
+    def coerce_subject(normalized, coerced, issues, pointer)
+      path = field_path(pointer, "subject")
+      if !normalized.key?("subject") || normalized["subject"].nil?
+        issues << Issue.new(path, "required", "subject is required")
+        return
+      end
+
+      text = coerce_text(normalized["subject"], path, issues, Fields::STRING_LIMITS.fetch("subject"))
+      coerced["subject"] = text unless text.nil?
+    end
+
+    def coerce_optional_string(normalized, coerced, issues, pointer, name)
+      return unless normalized.key?(name) && !normalized[name].nil?
+
+      text = coerce_text(normalized[name], field_path(pointer, name), issues, Fields::STRING_LIMITS.fetch(name))
+      coerced[name] = text unless text.nil?
+    end
+
+    def coerce_text(value, path, issues, limit)
+      unless value.is_a?(String)
+        issues << Issue.new(path, "type", "must be a string")
+        return nil
+      end
+
+      candidate = value.dup
+      candidate.force_encoding(Encoding::UTF_8) if candidate.encoding == Encoding::ASCII_8BIT
+      unless candidate.valid_encoding?
+        issues << Issue.new(path, "encoding", "must be valid UTF-8")
+        return nil
+      end
+      if candidate.match?(/[\u0000-\u001F\u007F\u2028\u2029]/)
+        issues << Issue.new(path, "control_character", "must not contain control characters or line separators")
+        return nil
+      end
+
+      stripped = candidate.strip
+      if stripped.empty?
+        issues << Issue.new(path, "blank", "must not be blank")
+        return nil
+      end
+      if stripped.length > limit
+        issues << Issue.new(path, "too_long", "is #{stripped.length} characters; limit is #{limit}")
+        return nil
+      end
+
+      stripped
+    end
+
+    def coerce_preset(normalized, coerced, issues, pointer)
+      return unless normalized.key?("preset") && !normalized["preset"].nil?
+
+      name = normalized["preset"]
+      if name.is_a?(String) && Presets::DATA.key?(name)
+        coerced["preset"] = name
+      else
+        issues << Issue.new(
+          field_path(pointer, "preset"),
+          "unknown_preset",
+          "preset must be one of: #{Presets::NAMES.join(', ')}"
+        )
+      end
+    end
+
+    def coerce_layout(normalized, coerced, issues, pointer)
+      return unless normalized.key?("layout") && !normalized["layout"].nil?
+
+      layout = normalized["layout"]
+      if layout.is_a?(String) && Layouts::NAMES.include?(layout)
+        coerced["layout"] = layout
+      else
+        issues << Issue.new(
+          field_path(pointer, "layout"),
+          "unknown_layout",
+          "layout must be one of: #{Layouts::NAMES.join(', ')}"
+        )
+      end
+    end
+
+    def coerce_details(normalized, coerced, issues, pointer)
+      return unless normalized.key?("details") && !normalized["details"].nil?
+
+      path = field_path(pointer, "details")
+      items = normalized["details"]
+      unless items.is_a?(Array)
+        issues << Issue.new(path, "type", "details must be an array")
+        return
+      end
+      if items.length > Fields::MAX_DETAILS
+        issues << Issue.new(path, "too_many", "details has #{items.length} items; limit is #{Fields::MAX_DETAILS}")
+      end
+
+      coerced_items = []
+      items.each_with_index do |item, index|
+        detail = coerce_detail(item, "#{path}/#{index}", issues)
+        coerced_items << detail unless detail.nil?
+      end
+      coerced["details"] = coerced_items if coerced_items.length == items.length
+    end
+
+    def coerce_detail(item, path, issues)
+      case item
+      when String
+        text = coerce_text(item, path, issues, Fields::DETAIL_TEXT_LIMIT)
+        return nil if text.nil?
+
+        { "text" => text, "hundredths" => 100 }
+      when Hash
+        coerce_detail_hash(item, path, issues)
+      else
+        issues << Issue.new(path, "type", "detail must be a string or an object with text and optional weight")
+        nil
+      end
+    end
+
+    def coerce_detail_hash(item, path, issues)
+      normalized = {}
+      item.each do |key, value|
+        name = case key
+               when String then key
+               when Symbol then key.to_s
+               else
+                 issues << Issue.new(path, "type", "detail field names must be strings")
+                 next
+               end
+        unless %w[text weight].include?(name)
+          issues << Issue.new("#{path}/#{name}", "unknown_field", "unknown detail field #{name.inspect}")
+          next
+        end
+        if normalized.key?(name)
+          issues << Issue.new("#{path}/#{name}", "duplicate_field", "detail field #{name} was given more than once")
+          next
+        end
+        normalized[name] = value
+      end
+
+      text = coerce_text(normalized["text"], "#{path}/text", issues, Fields::DETAIL_TEXT_LIMIT)
+      hundredths = 100
+      if normalized.key?("weight") && !normalized["weight"].nil?
+        hundredths = coerce_weight(normalized["weight"], "#{path}/weight", issues)
+      end
+      return nil if text.nil? || hundredths.nil?
+
+      { "text" => text, "hundredths" => hundredths }
+    end
+
+    def coerce_weight(value, path, issues)
+      hundredths = Numbers.hundredths(value)
+      if hundredths.nil? || hundredths < Fields::MIN_WEIGHT_HUNDREDTHS || hundredths > Fields::MAX_WEIGHT_HUNDREDTHS
+        issues << Issue.new(path, "range", "weight must be a number from 0.1 through 2.0 with at most two decimal places")
+        return nil
+      end
+
+      hundredths
+    end
+
+    def coerce_negatives(normalized, coerced, issues, pointer)
+      return unless normalized.key?("negatives") && !normalized["negatives"].nil?
+
+      path = field_path(pointer, "negatives")
+      items = normalized["negatives"]
+      unless items.is_a?(Array)
+        issues << Issue.new(path, "type", "negatives must be an array")
+        return
+      end
+      if items.length > Fields::MAX_NEGATIVES
+        issues << Issue.new(path, "too_many", "negatives has #{items.length} items; limit is #{Fields::MAX_NEGATIVES}")
+      end
+
+      coerced_items = []
+      items.each_with_index do |item, index|
+        text = coerce_text(item, "#{path}/#{index}", issues, Fields::DETAIL_TEXT_LIMIT)
+        coerced_items << text unless text.nil?
+      end
+      coerced["negatives"] = coerced_items if coerced_items.length == items.length
+    end
+
+    def coerce_aspect_ratio(normalized, coerced, issues, pointer)
+      return unless normalized.key?("aspect_ratio") && !normalized["aspect_ratio"].nil?
+
+      path = field_path(pointer, "aspect_ratio")
+      value = normalized["aspect_ratio"]
+      unless value.is_a?(String) && value.match?(Fields::ASPECT_PATTERN)
+        issues << Issue.new(path, "format", "aspect_ratio must look like 16:9 with each side from 1 through #{Fields::MAX_ASPECT_SIDE}")
+        return
+      end
+
+      width, height = value.split(":").map(&:to_i)
+      if width > Fields::MAX_ASPECT_SIDE || height > Fields::MAX_ASPECT_SIDE
+        issues << Issue.new(path, "range", "aspect_ratio sides must be from 1 through #{Fields::MAX_ASPECT_SIDE}")
+        return
+      end
+
+      coerced["aspect_ratio"] = value
+    end
+
+    def coerce_seed(normalized, coerced, issues, pointer)
+      return unless normalized.key?("seed") && !normalized["seed"].nil?
+
+      path = field_path(pointer, "seed")
+      value = normalized["seed"]
+      unless value.is_a?(Integer)
+        issues << Issue.new(path, "type", "seed must be an integer")
+        return
+      end
+      if value.negative? || value > Limits::MAX_SEED
+        issues << Issue.new(path, "range", "seed must be from 0 through #{Limits::MAX_SEED}")
+        return
+      end
+
+      coerced["seed"] = value
+    end
+
+    def coerce_steps(normalized, coerced, issues, pointer)
+      return unless normalized.key?("steps") && !normalized["steps"].nil?
+
+      path = field_path(pointer, "steps")
+      value = normalized["steps"]
+      unless value.is_a?(Integer)
+        issues << Issue.new(path, "type", "steps must be an integer")
+        return
+      end
+      unless value.between?(Fields::MIN_STEPS, Fields::MAX_STEPS)
+        issues << Issue.new(path, "range", "steps must be from #{Fields::MIN_STEPS} through #{Fields::MAX_STEPS}")
+        return
+      end
+
+      coerced["steps"] = value
+    end
+
+    def coerce_guidance(normalized, coerced, issues, pointer)
+      return unless normalized.key?("guidance") && !normalized["guidance"].nil?
+
+      path = field_path(pointer, "guidance")
+      hundredths = Numbers.hundredths(normalized["guidance"])
+      if hundredths.nil? || hundredths < Fields::MIN_GUIDANCE_HUNDREDTHS || hundredths > Fields::MAX_GUIDANCE_HUNDREDTHS
+        issues << Issue.new(path, "range", "guidance must be a number from 0 through 30 with at most two decimal places")
+        return
+      end
+
+      coerced["guidance"] = Numbers.from_hundredths(hundredths)
+    end
+
+    def merge_clean(normalized, coerced)
+      clean = {}
+      preset_name = coerced["preset"]
+      clean.merge!(Presets.copy(preset_name)) if preset_name
+
+      normalized.each_key do |name|
+        next if name == "preset"
+        if normalized[name].nil?
+          clean.delete(name)
+        else
+          clean[name] = coerced.fetch(name)
+        end
+      end
+      clean["details"] ||= []
+      clean["negatives"] ||= []
+      clean
+    end
+
+    def field_path(pointer, name)
+      "#{pointer}/#{name}"
+    end
+  end
+end

data/lib/flux3_ai_prompt_tools/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Flux3AiPromptTools
+  VERSION = "0.1.0"
+end

data/lib/flux3_ai_prompt_tools.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "flux3_ai_prompt_tools/version"
+require_relative "flux3_ai_prompt_tools/errors"
+require_relative "flux3_ai_prompt_tools/fields"
+require_relative "flux3_ai_prompt_tools/limits"
+require_relative "flux3_ai_prompt_tools/numbers"
+require_relative "flux3_ai_prompt_tools/layouts"
+require_relative "flux3_ai_prompt_tools/presets"
+require_relative "flux3_ai_prompt_tools/validator"
+require_relative "flux3_ai_prompt_tools/specification"
+require_relative "flux3_ai_prompt_tools/assembler"
+require_relative "flux3_ai_prompt_tools/reader"
+require_relative "flux3_ai_prompt_tools/manifest"
+require_relative "flux3_ai_prompt_tools/schema"
+
+# Offline validation and assembly of text-to-image prompt manifests.
+module Flux3AiPromptTools
+  module_function
+
+  def assemble(input, layout: Layouts::DEFAULT, limits: Limits::DEFAULT)
+    spec = Specification.parse(input, limits: limits)
+    Assembler.assemble(spec, layout: layout, limits: limits, raise_on_error: true)
+  end
+
+  # Returns an array of Issue. An empty array means the record assembled cleanly.
+  def validate(input, layout: Layouts::DEFAULT, limits: Limits::DEFAULT)
+    clean, issues, explicit_id = Validator.new(limits).prepare(input, pointer: "")
+    return issues unless issues.empty?
+
+    spec = Specification.from_clean(clean, id: explicit_id)
+    result = Assembler.assemble(spec, layout: layout, limits: limits, raise_on_error: false)
+    result.errors
+  end
+
+  def build_manifest(inputs, layout: Layouts::DEFAULT, limits: Limits::DEFAULT, keep_going: false)
+    Manifest.build(inputs, layout: layout, limits: limits, keep_going: keep_going)
+  end
+
+  def load_file(path, format: "auto", limits: Limits::DEFAULT)
+    Reader.load_file(path, format: format, limits: limits)
+  end
+
+  def schema
+    Schema.document
+  end
+
+  def presets
+    Presets.list
+  end
+end

data/test/assembler_test.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "helper"
+
+class AssemblerTest < Flux3Test
+  def setup
+    @record = {
+      "subject" => "a ceramic pour-over kettle",
+      "scene" => "morning light",
+      "medium" => "photograph",
+      "style" => "editorial",
+      "lighting" => "soft window light",
+      "composition" => "three-quarter view",
+      "camera" => "85mm lens",
+      "palette" => "cream and walnut",
+      "mood" => "quiet",
+      "details" => [
+        "steam above the spout",
+        { "text" => "wood grain", "weight" => 1.25 }
+      ],
+      "negatives" => ["text", "watermark"]
+    }
+  end
+
+  def test_natural_layout_is_deterministic
+    expected = "a ceramic pour-over kettle, morning light. photograph, editorial style. " \
+               "Lighting: soft window light. Composition: three-quarter view. Camera: 85mm lens. " \
+               "Palette: cream and walnut. Mood: quiet. " \
+               "Details: steam above the spout; wood grain (emphasis 1.25)."
+    first = Flux3AiPromptTools.assemble(@record, layout: "natural")
+    second = Flux3AiPromptTools.assemble(@record, layout: "natural")
+    assert_equal expected, first.prompt
+    assert_equal expected, second.prompt
+    assert_equal "text, watermark", first.negative_prompt
+    assert_equal expected.length, first.counts["prompt_chars"]
+    assert_equal 2, first.counts["details"]
+    assert_equal 2, first.counts["negatives"]
+  end
+
+  def test_tagged_layout_renders_weight_syntax
+    result = Flux3AiPromptTools.assemble(@record, layout: "tagged")
+    assert_equal(
+      "a ceramic pour-over kettle, morning light, photograph, editorial, soft window light, " \
+      "three-quarter view, 85mm lens, cream and walnut, quiet, steam above the spout, (wood grain:1.25)",
+      result.prompt
+    )
+    assert_equal "tagged", result.layout
+  end
+
+  def test_labeled_layout_uses_lines_and_skips_nothing_that_was_set
+    result = Flux3AiPromptTools.assemble(@record, layout: "labeled")
+    assert_equal <<~PROMPT.chomp, result.prompt
+      Subject: a ceramic pour-over kettle
+      Scene: morning light
+      Medium: photograph
+      Style: editorial
+      Lighting: soft window light
+      Composition: three-quarter view
+      Camera: 85mm lens
+      Palette: cream and walnut
+      Mood: quiet
+      Details: steam above the spout; wood grain (emphasis 1.25)
+    PROMPT
+    refute_includes result.prompt, "watermark"
+  end
+
+  def test_record_layout_overrides_the_call
+    record = @record.merge("layout" => "labeled")
+    result = Flux3AiPromptTools.assemble(record, layout: "natural")
+    assert_equal "labeled", result.layout
+    assert_includes result.prompt, "Subject: a ceramic pour-over kettle"
+  end
+
+  def test_preset_product_still_fills_only_missing_fields
+    result = Flux3AiPromptTools.assemble(
+      { "preset" => "product_still", "subject" => "a ceramic pour-over kettle", "mood" => "precise" }
+    )
+    assert_equal(
+      "a ceramic pour-over kettle. photograph. " \
+      "Lighting: soft diffused light with a gentle shadow under the subject. " \
+      "Composition: centered subject with clean negative space. " \
+      "Camera: standard product lens, sharp focus on the subject. Mood: precise.",
+      result.prompt
+    )
+  end
+
+  def test_character_budget_withholds_the_prompt
+    error = assert_raises(Flux3AiPromptTools::ValidationError) do
+      Flux3AiPromptTools.assemble(
+        { "subject" => "a bowl", "negatives" => ["logo"] },
+        limits: Flux3AiPromptTools::Limits.new(max_prompt_chars: 4, max_negative_chars: 2)
+      )
+    end
+    assert_equal %w[too_long too_long], error.issues.map(&:code)
+    assert_equal ["/prompt", "/negative_prompt"], error.issues.map(&:path)
+  end
+
+  def test_validate_reports_budget_without_raising
+    issues = Flux3AiPromptTools.validate(
+      { "subject" => "a bowl" },
+      limits: Flux3AiPromptTools::Limits.new(max_prompt_chars: 3)
+    )
+    assert_equal ["too_long"], codes(issues)
+  end
+
+  def test_generator_metadata_has_no_network_client_fields
+    payload = Flux3AiPromptTools.assemble({ "subject" => "a bowl", "id" => "bowl-1" }).to_h
+    assert_equal "flux3_ai_prompt_tools/#{Flux3AiPromptTools::VERSION}", payload["generator"]
+    assert_equal "bowl-1", payload["id"]
+    assert_equal true, payload["ok"]
+    assert_empty payload["errors"]
+    refute payload.key?("endpoint")
+    refute payload.key?("api_key")
+  end
+end