flux3_ai_prompt_tools 0.1.0

data/lib/flux3_ai_prompt_tools/numbers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Flux3AiPromptTools
+  # Exact hundredth parsing so weights and guidance do not drift through binary floats.
+  module Numbers
+    module_function
+
+    def hundredths(value)
+      return nil unless value.is_a?(Integer) || value.is_a?(Float)
+      return nil unless value.finite?
+
+      text = value.to_s
+      return nil unless text.match?(/\A-?\d+(?:\.\d+)?\z/)
+
+      scaled = BigDecimal(text) * 100
+      return nil unless scaled.frac.zero?
+
+      scaled.to_i
+    end
+
+    def from_hundredths(hundredths)
+      whole, frac = hundredths.divmod(100)
+      return whole if frac.zero?
+
+      format("%d.%02d", whole, frac).sub(/0\z/, "").to_f
+    end
+
+    def format_hundredths(hundredths)
+      whole, frac = hundredths.divmod(100)
+      return whole.to_s if frac.zero?
+
+      format("%d.%02d", whole, frac).sub(/0\z/, "")
+    end
+  end
+end

data/lib/flux3_ai_prompt_tools/presets.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Flux3AiPromptTools
+  # Local writing templates. They fill empty art-direction fields and are not model settings.
+  module Presets
+    DATA = {
+      "product_still" => {
+        "medium" => "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" => "clear and uncluttered"
+      }.freeze,
+      "portrait" => {
+        "medium" => "photograph",
+        "lighting" => "soft directional light on the face",
+        "composition" => "head and shoulders, eyes in the upper third",
+        "camera" => "short telephoto lens, shallow depth of field",
+        "mood" => "calm and direct"
+      }.freeze,
+      "environment" => {
+        "medium" => "photograph",
+        "lighting" => "natural light consistent with the time of day",
+        "composition" => "wide view that shows foreground, subject, and background",
+        "camera" => "wide-angle lens, deep focus",
+        "mood" => "specific and grounded"
+      }.freeze,
+      "graphic_poster" => {
+        "medium" => "graphic poster",
+        "composition" => "bold hierarchy with room for a short headline",
+        "palette" => "limited palette with one accent color",
+        "mood" => "immediate and legible"
+      }.freeze
+    }.freeze
+
+    NAMES = DATA.keys.freeze
+
+    def self.list
+      DATA.map do |name, fields|
+        { "name" => name, "fields" => fields.dup }
+      end
+    end
+
+    def self.copy(name)
+      source = DATA[name]
+      return nil if source.nil?
+
+      source.each_with_object({}) do |(key, value), copy|
+        copy[key] = value.dup
+      end
+    end
+  end
+end

data/lib/flux3_ai_prompt_tools/reader.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+require_relative "limits"
+
+module Flux3AiPromptTools
+  # Loads a JSON object, a JSON array, or JSONL into an array of hashes.
+  class Reader
+    def self.load_file(path, format: "auto", limits: Limits::DEFAULT)
+      raise InputError, "file does not exist: #{path}" unless File.file?(path)
+
+      size = File.size(path)
+      if size > limits.max_input_bytes
+        raise InputError, "file is #{size} bytes; limit is #{limits.max_input_bytes}"
+      end
+
+      text = File.binread(path)
+      text.force_encoding(Encoding::UTF_8)
+      unless text.valid_encoding?
+        raise InputError, "file is not valid UTF-8: #{path}"
+      end
+
+      load(text, format: format, filename: path, limits: limits)
+    end
+
+    def self.load(text, format:, filename: nil, limits: Limits::DEFAULT)
+      raise InputError, "input is empty" if text.nil? || text.strip.empty?
+      if text.bytesize > limits.max_input_bytes
+        raise InputError, "input is #{text.bytesize} bytes; limit is #{limits.max_input_bytes}"
+      end
+
+      document = text.dup
+      document.force_encoding(Encoding::UTF_8)
+      unless document.valid_encoding?
+        raise InputError, "input is not valid UTF-8"
+      end
+      document = document.sub(/\A\uFEFF/, "")
+
+      chosen = format.to_s
+      chosen = detect(document, filename) if chosen == "auto"
+      case chosen
+      when "json" then parse_json(document, filename)
+      when "jsonl" then parse_jsonl(document, filename)
+      else
+        raise UsageError, "input format must be auto, json, or jsonl"
+      end
+    end
+
+    def self.detect(text, filename)
+      if filename&.match?(/\.jsonl\z/i)
+        "jsonl"
+      elsif filename&.match?(/\.json\z/i)
+        "json"
+      else
+        begin
+          JSON.parse(text)
+          "json"
+        rescue JSON::ParserError
+          "jsonl"
+        end
+      end
+    end
+    private_class_method :detect
+
+    def self.parse_json(text, filename)
+      value = JSON.parse(text)
+    rescue JSON::ParserError => e
+      where = filename ? " in #{filename}" : ""
+      raise InputError, "invalid JSON#{where}: #{e.message}"
+    else
+      records = case value
+                when Hash then [value]
+                when Array then value
+                else
+                  raise InputError, "JSON input must be an object or an array of objects"
+                end
+      raise InputError, "batch has no records" if records.empty?
+
+      records.each_with_index do |item, index|
+        raise InputError, "JSON item #{index} must be an object" unless item.is_a?(Hash)
+      end
+      records
+    end
+    private_class_method :parse_json
+
+    def self.parse_jsonl(text, filename)
+      records = []
+      text.each_line.with_index(1) do |line, number|
+        next if line.strip.empty?
+
+        begin
+          value = JSON.parse(line)
+        rescue JSON::ParserError => e
+          location = filename ? "#{filename}:#{number}" : "line #{number}"
+          raise InputError.new("invalid JSONL at #{location}: #{e.message}", line: number)
+        end
+        unless value.is_a?(Hash)
+          location = filename ? "#{filename}:#{number}" : "line #{number}"
+          raise InputError.new("JSONL #{location} must be an object", line: number)
+        end
+        records << value
+      end
+      raise InputError, "input is empty" if records.empty?
+
+      records
+    end
+    private_class_method :parse_jsonl
+  end
+end

data/lib/flux3_ai_prompt_tools/schema.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "fields"
+require_relative "layouts"
+require_relative "limits"
+require_relative "presets"
+
+module Flux3AiPromptTools
+  # A JSON Schema document for one prompt record. It is data, not a hosted endpoint.
+  module Schema
+    module_function
+
+    def document
+      {
+        "$schema" => "https://json-schema.org/draft/2020-12/schema",
+        "title" => "Text-to-image prompt record",
+        "description" => "Input record for flux3_ai_prompt_tools. The assembler reads this document locally and does not submit it to a generator.",
+        "type" => "object",
+        "additionalProperties" => false,
+        "required" => ["subject"],
+        "properties" => properties
+      }
+    end
+
+    def properties
+      strings = Fields::STRING_LIMITS.each_with_object({}) do |(name, limit), props|
+        props[name] = {
+          "type" => "string",
+          "minLength" => 1,
+          "maxLength" => limit,
+          "description" => string_description(name)
+        }
+      end
+      strings.merge(
+        "id" => {
+          "type" => "string",
+          "pattern" => "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+          "description" => "Optional stable id. Batch mode assigns item-0001 style ids when this is omitted."
+        },
+        "details" => {
+          "type" => "array",
+          "maxItems" => Fields::MAX_DETAILS,
+          "items" => {
+            "anyOf" => [
+              { "type" => "string", "minLength" => 1, "maxLength" => Fields::DETAIL_TEXT_LIMIT },
+              {
+                "type" => "object",
+                "additionalProperties" => false,
+                "required" => ["text"],
+                "properties" => {
+                  "text" => { "type" => "string", "minLength" => 1, "maxLength" => Fields::DETAIL_TEXT_LIMIT },
+                  "weight" => { "type" => "number", "minimum" => 0.1, "maximum" => 2.0 }
+                }
+              }
+            ]
+          }
+        },
+        "negatives" => {
+          "type" => "array",
+          "maxItems" => Fields::MAX_NEGATIVES,
+          "items" => { "type" => "string", "minLength" => 1, "maxLength" => Fields::DETAIL_TEXT_LIMIT },
+          "description" => "Phrases to keep in negative_prompt. They are not copied into the positive prompt."
+        },
+        "aspect_ratio" => {
+          "type" => "string",
+          "pattern" => "^[1-9][0-9]?:[1-9][0-9]?$",
+          "description" => "Stored manifest metadata such as 4:5. Each side must be from 1 through #{Fields::MAX_ASPECT_SIDE}."
+        },
+        "seed" => {
+          "type" => "integer",
+          "minimum" => 0,
+          "maximum" => Limits::MAX_SEED,
+          "description" => "Stored manifest metadata. It is not sent to a renderer by this gem."
+        },
+        "steps" => {
+          "type" => "integer",
+          "minimum" => Fields::MIN_STEPS,
+          "maximum" => Fields::MAX_STEPS,
+          "description" => "Stored manifest metadata. It is not sent to a renderer by this gem."
+        },
+        "guidance" => {
+          "type" => "number",
+          "minimum" => 0,
+          "maximum" => 30,
+          "description" => "Stored manifest metadata. It is not sent to a renderer by this gem."
+        },
+        "layout" => {
+          "type" => "string",
+          "enum" => Layouts::NAMES,
+          "description" => "Optional per-record layout override."
+        },
+        "preset" => {
+          "type" => "string",
+          "enum" => Presets::NAMES,
+          "description" => "Local writing template. Explicit fields replace template fields."
+        }
+      )
+    end
+
+    def string_description(name)
+      case name
+      when "subject" then "Required subject of the picture."
+      when "note" then "Reminder copied into the manifest and omitted from both prompts."
+      else "Optional art-direction text. Leading and trailing whitespace is removed."
+      end
+    end
+  end
+end

data/lib/flux3_ai_prompt_tools/specification.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "validator"
+
+module Flux3AiPromptTools
+  # One weighted detail phrase.
+  class Detail
+    attr_reader :text, :hundredths
+
+    def initialize(text:, hundredths:)
+      @text = text
+      @hundredths = hundredths
+      freeze
+    end
+
+    def weight
+      Numbers.from_hundredths(hundredths)
+    end
+
+    def neutral?
+      hundredths == 100
+    end
+  end
+
+  # A record that has already passed validation.
+  class Specification
+    attr_reader :id, :subject, :scene, :medium, :style, :lighting, :composition,
+                :camera, :palette, :mood, :details, :negatives, :aspect_ratio,
+                :seed, :steps, :guidance, :note, :layout
+
+    def initialize(id:, subject:, scene:, medium:, style:, lighting:, composition:,
+                   camera:, palette:, mood:, details:, negatives:, aspect_ratio:,
+                   seed:, steps:, guidance:, note:, layout:)
+      @id = id
+      @subject = subject
+      @scene = scene
+      @medium = medium
+      @style = style
+      @lighting = lighting
+      @composition = composition
+      @camera = camera
+      @palette = palette
+      @mood = mood
+      @details = details.dup.freeze
+      @negatives = negatives.dup.freeze
+      @aspect_ratio = aspect_ratio
+      @seed = seed
+      @steps = steps
+      @guidance = guidance
+      @note = note
+      @layout = layout
+      freeze
+    end
+
+    def self.parse(input, limits: Limits::DEFAULT)
+      clean, issues, _explicit_id = Validator.new(limits).prepare(input, pointer: "")
+      raise ValidationError, issues unless issues.empty?
+
+      from_clean(clean, id: clean["id"])
+    end
+
+    def self.from_clean(clean, id:)
+      details = clean.fetch("details", []).map do |item|
+        Detail.new(text: item["text"], hundredths: item["hundredths"])
+      end
+      new(
+        id: id,
+        subject: clean["subject"],
+        scene: clean["scene"],
+        medium: clean["medium"],
+        style: clean["style"],
+        lighting: clean["lighting"],
+        composition: clean["composition"],
+        camera: clean["camera"],
+        palette: clean["palette"],
+        mood: clean["mood"],
+        details: details,
+        negatives: Array(clean["negatives"]),
+        aspect_ratio: clean["aspect_ratio"],
+        seed: clean["seed"],
+        steps: clean["steps"],
+        guidance: clean["guidance"],
+        note: clean["note"],
+        layout: clean["layout"]
+      )
+    end
+  end
+end