flux3_ai_prompt_tools 0.1.0

data/lib/flux3_ai_prompt_tools/cli.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+require_relative "../flux3_ai_prompt_tools"
+require_relative "errors"
+require_relative "layouts"
+require_relative "limits"
+require_relative "reader"
+
+module Flux3AiPromptTools
+  # Command-line entry point used by bin/flux3-prompt.
+  class CLI
+    def self.start(argv)
+      new(argv).start
+    end
+
+    def initialize(argv)
+      @argv = argv.map(&:dup)
+    end
+
+    def start
+      command = @argv.shift
+      case command
+      when nil
+        $stdout.write(self.class.help_text)
+        2
+      when "help", "-h", "--help"
+        $stdout.write(self.class.help_text)
+        0
+      when "version", "-v", "--version"
+        $stdout.puts(VERSION)
+        0
+      when "schema"
+        schema_command
+      when "presets"
+        presets_command
+      when "assemble"
+        assemble_command
+      when "validate"
+        validate_command
+      when "batch"
+        batch_command
+      else
+        raise UsageError, "unknown command #{command.inspect}. See `flux3-prompt help`."
+      end
+    end
+
+    def self.help_text
+      <<~HELP
+        flux3-prompt #{VERSION}
+
+        Validate structured prompt inputs and assemble text-to-image prompt
+        manifests on this machine. This command does not generate images and
+        does not contact a network service.
+
+        Usage:
+          flux3-prompt assemble --subject TEXT [options]
+          flux3-prompt validate FILE [options]
+          flux3-prompt batch FILE [-o PATH] [options]
+          flux3-prompt schema
+          flux3-prompt presets
+          flux3-prompt version
+          flux3-prompt help
+
+        Assemble options:
+          --subject TEXT            Required picture subject
+          --scene, --medium, --style, --lighting, --composition, --camera,
+          --palette, --mood TEXT    Optional art direction
+          --detail TEXT             Repeatable detail, weight 1
+          --negative TEXT           Repeatable negative phrase
+          --aspect-ratio RATIO      Stored metadata, for example 4:5
+          --seed N                  Stored integer metadata
+          --steps N                 Stored integer metadata from 1 through 150
+          --guidance N              Stored numeric metadata from 0 through 30
+          --note TEXT               Copied to the manifest, omitted from prompts
+          --preset NAME             Local writing template
+          --id ID                   Optional record id
+          --layout NAME             natural, tagged, or labeled (default natural)
+          --manifest                Print the JSON record instead of prompt text
+
+        Batch and validate options:
+          --input-format FORMAT     auto, json, or jsonl (default auto)
+          --format FORMAT           json or jsonl output for batch
+          --layout NAME             Default layout for records that do not set one
+          --keep-going              Write failed records with ok false instead of stopping
+          -o, --output PATH         Batch output file. Stdout is used when omitted
+          --max-prompt-chars N      Default #{Limits::DEFAULT_MAX_PROMPT_CHARS}
+          --max-negative-chars N    Default #{Limits::DEFAULT_MAX_NEGATIVE_CHARS}
+          --max-records N           Default #{Limits::DEFAULT_MAX_RECORDS}
+          --max-input-bytes N       Default #{Limits::DEFAULT_MAX_INPUT_BYTES}
+
+        Weighted details belong in JSON, as {"text":"wide rim","weight":1.2}.
+        FILE may be - when the document is piped to stdin.
+
+        Exit status is 0 for success, 1 for invalid input or records, and 2
+        for an invalid command line.
+
+        Homepage: https://flux3-ai.com/
+      HELP
+    end
+
+    private
+
+    def schema_command
+      raise UsageError, "schema does not take arguments" unless @argv.empty?
+
+      $stdout.write(JSON.pretty_generate(Schema.document) + "\n")
+      0
+    end
+
+    def presets_command
+      raise UsageError, "presets does not take arguments" unless @argv.empty?
+
+      $stdout.write(JSON.pretty_generate(Presets.list) + "\n")
+      0
+    end
+
+    def assemble_command
+      record = {}
+      options = { layout: Layouts::DEFAULT, manifest: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: flux3-prompt assemble --subject TEXT [options]"
+        opts.on("--id ID") { |value| record["id"] = value }
+        opts.on("--subject TEXT") { |value| record["subject"] = value }
+        opts.on("--scene TEXT") { |value| record["scene"] = value }
+        opts.on("--medium TEXT") { |value| record["medium"] = value }
+        opts.on("--style TEXT") { |value| record["style"] = value }
+        opts.on("--lighting TEXT") { |value| record["lighting"] = value }
+        opts.on("--composition TEXT") { |value| record["composition"] = value }
+        opts.on("--camera TEXT") { |value| record["camera"] = value }
+        opts.on("--palette TEXT") { |value| record["palette"] = value }
+        opts.on("--mood TEXT") { |value| record["mood"] = value }
+        opts.on("--detail TEXT") { |value| (record["details"] ||= []) << value }
+        opts.on("--negative TEXT") { |value| (record["negatives"] ||= []) << value }
+        opts.on("--aspect-ratio RATIO") { |value| record["aspect_ratio"] = value }
+        opts.on("--seed N", Integer) { |value| record["seed"] = value }
+        opts.on("--steps N", Integer) { |value| record["steps"] = value }
+        opts.on("--guidance N", Float) { |value| record["guidance"] = value }
+        opts.on("--note TEXT") { |value| record["note"] = value }
+        opts.on("--preset NAME") { |value| record["preset"] = value }
+        opts.on("--layout NAME") { |value| options[:layout] = value }
+        opts.on("--manifest", "Print the JSON record instead of the prompt text") { options[:manifest] = true }
+        add_text_budget_flags(opts, options)
+      end
+      parse!(parser)
+      raise UsageError, "assemble does not take positional arguments" unless @argv.empty?
+
+      check_layout!(options[:layout])
+      result = Flux3AiPromptTools.assemble(record, layout: options[:layout], limits: limits_from(options))
+      if options[:manifest]
+        $stdout.write(JSON.pretty_generate(result.to_h) + "\n")
+      else
+        text = result.prompt
+        text += "\n" unless text.end_with?("\n")
+        $stdout.write(text)
+      end
+      0
+    end
+
+    def validate_command
+      options = default_batch_options
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: flux3-prompt validate FILE [options]"
+        add_common_batch_flags(opts, options)
+      end
+      parse!(parser)
+      raise UsageError, "validate requires a FILE or -" unless @argv.length == 1
+
+      check_choices!(options)
+      records = read_records(@argv.fetch(0), options)
+      Flux3AiPromptTools.build_manifest(records, layout: options[:layout], limits: limits_from(options))
+      $stdout.puts("valid: #{records.length} record(s)")
+      0
+    end
+
+    def batch_command
+      options = default_batch_options
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: flux3-prompt batch FILE [-o PATH] [options]"
+        opts.on("-o", "--output PATH", "Write the manifest to PATH") { |value| options[:output] = value }
+        opts.on("--format FORMAT", "json or jsonl") { |value| options[:format] = value }
+        opts.on("--keep-going", "Write records that failed validation") { options[:keep_going] = true }
+        add_common_batch_flags(opts, options)
+      end
+      parse!(parser)
+      raise UsageError, "batch requires a FILE or -" unless @argv.length == 1
+
+      check_choices!(options)
+      format = resolve_format(options)
+      records = read_records(@argv.fetch(0), options)
+      manifest = Flux3AiPromptTools.build_manifest(
+        records,
+        layout: options[:layout],
+        limits: limits_from(options),
+        keep_going: options[:keep_going]
+      )
+      body = format == "json" ? manifest.to_json_document : manifest.to_jsonl
+      write_output(options[:output], body)
+      report_batch(manifest, options[:output])
+      manifest.ok? ? 0 : 1
+    end
+
+    def default_batch_options
+      {
+        layout: Layouts::DEFAULT,
+        input_format: "auto",
+        output: nil,
+        format: nil,
+        keep_going: false
+      }
+    end
+
+    def add_common_batch_flags(parser, options)
+      parser.on("--layout NAME", "natural, tagged, or labeled") { |value| options[:layout] = value }
+      parser.on("--input-format FORMAT", "auto, json, or jsonl") { |value| options[:input_format] = value }
+      add_text_budget_flags(parser, options)
+      add_input_budget_flags(parser, options)
+    end
+
+    def add_text_budget_flags(parser, options)
+      parser.on("--max-prompt-chars N", Integer, "Assembled prompt character limit") do |value|
+        raise UsageError, "max-prompt-chars must be a positive integer" unless value.positive?
+
+        options[:max_prompt_chars] = value
+      end
+      parser.on("--max-negative-chars N", Integer, "Assembled negative prompt character limit") do |value|
+        raise UsageError, "max-negative-chars must be a positive integer" unless value.positive?
+
+        options[:max_negative_chars] = value
+      end
+    end
+
+    def add_input_budget_flags(parser, options)
+      parser.on("--max-records N", Integer, "Maximum records in one batch") do |value|
+        raise UsageError, "max-records must be a positive integer" unless value.positive?
+
+        options[:max_records] = value
+      end
+      parser.on("--max-input-bytes N", Integer, "Maximum input size in bytes") do |value|
+        raise UsageError, "max-input-bytes must be a positive integer" unless value.positive?
+
+        options[:max_input_bytes] = value
+      end
+    end
+
+    def parse!(parser)
+      parser.parse!(@argv)
+    rescue OptionParser::ParseError => e
+      raise UsageError, e.message
+    end
+
+    def check_choices!(options)
+      check_layout!(options[:layout])
+      return if %w[auto json jsonl].include?(options[:input_format])
+
+      raise UsageError, "input format must be auto, json, or jsonl"
+    end
+
+    def check_layout!(layout)
+      return if Layouts::NAMES.include?(layout)
+
+      raise UsageError, "layout must be one of: #{Layouts::NAMES.join(', ')}"
+    end
+
+    def resolve_format(options)
+      format = options[:format]
+      if format
+        return format if %w[json jsonl].include?(format)
+
+        raise UsageError, "format must be json or jsonl"
+      end
+
+      path = options[:output]
+      return "jsonl" if path.nil?
+      return "jsonl" if path.match?(/\.jsonl\z/i)
+      return "json" if path.match?(/\.json\z/i)
+
+      "json"
+    end
+
+    def read_records(path, options)
+      limits = limits_from(options)
+      if path == "-"
+        Reader.load(read_stdin(limits), format: options[:input_format], limits: limits)
+      else
+        Reader.load_file(path, format: options[:input_format], limits: limits)
+      end
+    end
+
+    def read_stdin(limits)
+      data = $stdin.binmode.read(limits.max_input_bytes + 1)
+      data = "" if data.nil?
+      if data.bytesize > limits.max_input_bytes
+        raise InputError, "input is larger than #{limits.max_input_bytes} bytes"
+      end
+
+      data.force_encoding(Encoding::UTF_8)
+      raise InputError, "input is not valid UTF-8" unless data.valid_encoding?
+
+      data
+    end
+
+    def limits_from(options)
+      Limits.new(
+        max_prompt_chars: options.fetch(:max_prompt_chars, Limits::DEFAULT_MAX_PROMPT_CHARS),
+        max_negative_chars: options.fetch(:max_negative_chars, Limits::DEFAULT_MAX_NEGATIVE_CHARS),
+        max_records: options.fetch(:max_records, Limits::DEFAULT_MAX_RECORDS),
+        max_input_bytes: options.fetch(:max_input_bytes, Limits::DEFAULT_MAX_INPUT_BYTES)
+      )
+    end
+
+    def write_output(path, body)
+      if path.nil?
+        $stdout.write(body)
+        return
+      end
+      raise UsageError, "output path is a directory: #{path}" if File.directory?(path)
+
+      directory = File.dirname(path)
+      raise UsageError, "output directory does not exist: #{directory}" unless File.directory?(directory)
+
+      temporary = File.join(directory, ".#{File.basename(path)}.#{Process.pid}.tmp")
+      File.write(temporary, body, encoding: Encoding::UTF_8)
+      File.rename(temporary, path)
+    rescue StandardError
+      File.delete(temporary) if defined?(temporary) && temporary && File.exist?(temporary)
+      raise
+    end
+
+    def report_batch(manifest, path)
+      return if path.nil? && manifest.ok?
+
+      failed = manifest.records.count { |record| !record.ok }
+      if path
+        suffix = failed.zero? ? "" : " (#{failed} failed)"
+        warn "wrote #{manifest.records.length} record(s) to #{path}#{suffix}"
+      end
+      return if failed.zero?
+
+      manifest.records.each do |record|
+        record.errors.each do |issue|
+          warn "error: #{issue.path} #{issue.code}: #{issue.message}"
+        end
+      end
+    end
+  end
+end

data/lib/flux3_ai_prompt_tools/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Flux3AiPromptTools
+  # Base class for errors raised by this gem.
+  class Error < StandardError; end
+
+  # The command line itself is invalid. CLI exit status 2.
+  class UsageError < Error; end
+
+  # A file or document could not be read as JSON or JSONL. CLI exit status 1.
+  class InputError < Error
+    attr_reader :line
+
+    def initialize(message, line: nil)
+      @line = line
+      super(message)
+    end
+  end
+
+  # One validation problem on a record or on assembled text.
+  class Issue
+    attr_reader :path, :code, :message
+
+    def initialize(path, code, message)
+      @path = path
+      @code = code
+      @message = message
+      freeze
+    end
+
+    def to_h
+      { "path" => path, "code" => code, "message" => message }
+    end
+  end
+
+  # One or more field, budget, or batch-consistency problems.
+  class ValidationError < Error
+    attr_reader :issues
+
+    def initialize(issues)
+      unless issues.is_a?(Array) && issues.all? { |issue| issue.is_a?(Issue) }
+        raise ArgumentError, "issues must be an array of Issue"
+      end
+
+      @issues = issues.freeze
+      super(issues.map { |issue| "#{issue.path} #{issue.code}: #{issue.message}" }.join("\n"))
+    end
+  end
+end

data/lib/flux3_ai_prompt_tools/fields.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Flux3AiPromptTools
+  # Shared limits for the validator, the JSON description, and the CLI help text.
+  module Fields
+    NAMES = %w[
+      id subject scene medium style lighting composition camera palette mood
+      details negatives aspect_ratio seed steps guidance note layout preset
+    ].freeze
+
+    STRING_LIMITS = {
+      "subject" => 400,
+      "scene" => 400,
+      "medium" => 120,
+      "style" => 200,
+      "lighting" => 300,
+      "composition" => 300,
+      "camera" => 200,
+      "palette" => 200,
+      "mood" => 200,
+      "note" => 500
+    }.freeze
+
+    DETAIL_TEXT_LIMIT = 160
+    MAX_DETAILS = 32
+    MAX_NEGATIVES = 32
+    MIN_WEIGHT_HUNDREDTHS = 10
+    MAX_WEIGHT_HUNDREDTHS = 200
+    MIN_GUIDANCE_HUNDREDTHS = 0
+    MAX_GUIDANCE_HUNDREDTHS = 3_000
+    MIN_STEPS = 1
+    MAX_STEPS = 150
+    MAX_ASPECT_SIDE = 64
+    ID_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9._-]{0,63}\z/
+    ASPECT_PATTERN = /\A[1-9]\d?:[1-9]\d?\z/
+  end
+end

data/lib/flux3_ai_prompt_tools/layouts.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Flux3AiPromptTools
+  module Layouts
+    NAMES = %w[natural tagged labeled].freeze
+    DEFAULT = "natural"
+  end
+end

data/lib/flux3_ai_prompt_tools/limits.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Flux3AiPromptTools
+  # Budgets for assembled text and for a batch document.
+  class Limits
+    attr_reader :max_prompt_chars, :max_negative_chars, :max_records, :max_input_bytes
+
+    DEFAULT_MAX_PROMPT_CHARS = 2_000
+    DEFAULT_MAX_NEGATIVE_CHARS = 1_000
+    DEFAULT_MAX_RECORDS = 5_000
+    DEFAULT_MAX_INPUT_BYTES = 5_000_000
+
+    # Largest integer that every JSON consumer can round-trip as a number.
+    MAX_SEED = (2**53) - 1
+
+    def initialize(max_prompt_chars: DEFAULT_MAX_PROMPT_CHARS,
+                   max_negative_chars: DEFAULT_MAX_NEGATIVE_CHARS,
+                   max_records: DEFAULT_MAX_RECORDS,
+                   max_input_bytes: DEFAULT_MAX_INPUT_BYTES)
+      @max_prompt_chars = self.class.positive_integer!(max_prompt_chars, "max_prompt_chars")
+      @max_negative_chars = self.class.positive_integer!(max_negative_chars, "max_negative_chars")
+      @max_records = self.class.positive_integer!(max_records, "max_records")
+      @max_input_bytes = self.class.positive_integer!(max_input_bytes, "max_input_bytes")
+      freeze
+    end
+
+    def self.positive_integer!(value, name)
+      unless value.is_a?(Integer) && value.positive?
+        raise ArgumentError, "#{name} must be a positive integer"
+      end
+
+      value
+    end
+
+    DEFAULT = new
+  end
+end

data/lib/flux3_ai_prompt_tools/manifest.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "assembler"
+require_relative "errors"
+require_relative "layouts"
+require_relative "limits"
+require_relative "specification"
+require_relative "validator"
+require_relative "version"
+
+module Flux3AiPromptTools
+  # A batch of assembled records in input order.
+  class Manifest
+    attr_reader :records, :layout
+
+    def initialize(records, layout:)
+      @records = records.dup.freeze
+      @layout = layout
+      freeze
+    end
+
+    def ok?
+      records.all?(&:ok)
+    end
+
+    def to_h
+      {
+        "generator" => "flux3_ai_prompt_tools/#{VERSION}",
+        "layout" => layout,
+        "ok" => ok?,
+        "records" => records.map(&:to_h)
+      }
+    end
+
+    def to_json_document
+      JSON.pretty_generate(to_h) + "\n"
+    end
+
+    def to_jsonl
+      records.map { |record| JSON.generate(record.to_h) }.join("\n") + (records.empty? ? "" : "\n")
+    end
+
+    def self.build(inputs, layout: Layouts::DEFAULT, limits: Limits::DEFAULT, keep_going: false)
+      unless inputs.is_a?(Array)
+        raise ArgumentError, "inputs must be an array of records"
+      end
+      unless layout.is_a?(String) && Layouts::NAMES.include?(layout)
+        raise ArgumentError, "layout must be one of: #{Layouts::NAMES.join(', ')}"
+      end
+      unless limits.is_a?(Limits)
+        raise ArgumentError, "limits must be a Flux3AiPromptTools::Limits"
+      end
+      raise InputError, "batch has no records" if inputs.empty?
+      if inputs.length > limits.max_records
+        raise InputError, "batch has #{inputs.length} records; limit is #{limits.max_records}"
+      end
+
+      validator = Validator.new(limits)
+      rows = inputs.each_with_index.map do |input, index|
+        pointer = "/records/#{index}"
+        clean, issues, explicit_id = validator.prepare(input, pointer: pointer)
+        { index: index, clean: clean, issues: issues, explicit_id: explicit_id, assigned_id: nil }
+      end
+
+      assign_ids!(rows)
+      all_issues = rows.flat_map { |row| row[:issues] }
+      results = []
+      fingerprints = {}
+
+      rows.each do |row|
+        if row[:issues].any?
+          results << failure_result(row, layout)
+          next
+        end
+
+        spec = Specification.from_clean(row[:clean], id: row[:explicit_id] || row[:assigned_id])
+        result = Assembler.assemble(spec, layout: layout, limits: limits, raise_on_error: false)
+        unless result.ok
+          prefixed = result.errors.map { |issue| prefix_issue(issue, row[:index]) }
+          all_issues.concat(prefixed)
+          results << replace_errors(result, prefixed)
+          next
+        end
+
+        fingerprint = fingerprint_for(result)
+        if fingerprints.key?(fingerprint)
+          issue = Issue.new(
+            "/records/#{row[:index]}",
+            "duplicate_job",
+            "this record repeats the prompt, negative prompt, layout, and parameters of /records/#{fingerprints[fingerprint]}"
+          )
+          all_issues << issue
+          results << replace_errors(result, [issue])
+        else
+          fingerprints[fingerprint] = row[:index]
+          results << result
+        end
+      end
+
+      raise ValidationError, all_issues if !keep_going && all_issues.any?
+
+      new(results, layout: layout)
+    end
+
+    def self.assign_ids!(rows)
+      used = {}
+      rows.each do |row|
+        id = row[:explicit_id]
+        next if id.nil?
+
+        if used.key?(id)
+          row[:issues] << Issue.new(
+            "/records/#{row[:index]}/id",
+            "duplicate_id",
+            "id #{id.inspect} is already used by /records/#{used[id]}"
+          )
+        else
+          used[id] = row[:index]
+        end
+      end
+
+      rows.each do |row|
+        next unless row[:explicit_id].nil?
+
+        row[:assigned_id] = next_id(used, row[:index])
+      end
+    end
+    private_class_method :assign_ids!
+
+    def self.next_id(used, index)
+      number = 1
+      loop do
+        candidate = format("item-%04d", number)
+        unless used.key?(candidate)
+          used[candidate] = index
+          return candidate
+        end
+        number += 1
+        raise InputError, "could not assign a unique id" if number > 100_000
+      end
+    end
+    private_class_method :next_id
+
+    def self.failure_result(row, layout)
+      Result.new(
+        id: row[:explicit_id] || row[:assigned_id],
+        ok: false,
+        prompt: nil,
+        negative_prompt: nil,
+        layout: layout,
+        parameters: {
+          "aspect_ratio" => nil,
+          "seed" => nil,
+          "steps" => nil,
+          "guidance" => nil
+        },
+        counts: {
+          "prompt_chars" => nil,
+          "negative_chars" => nil,
+          "details" => nil,
+          "negatives" => nil
+        },
+        note: nil,
+        errors: row[:issues]
+      )
+    end
+    private_class_method :failure_result
+
+    def self.prefix_issue(issue, index)
+      Issue.new("/records/#{index}#{issue.path}", issue.code, issue.message)
+    end
+    private_class_method :prefix_issue
+
+    def self.replace_errors(result, errors)
+      Result.new(
+        id: result.id,
+        ok: false,
+        prompt: nil,
+        negative_prompt: nil,
+        layout: result.layout,
+        parameters: result.parameters,
+        counts: result.counts,
+        note: result.note,
+        errors: errors
+      )
+    end
+    private_class_method :replace_errors
+
+    def self.fingerprint_for(result)
+      [
+        result.prompt,
+        result.negative_prompt,
+        result.layout,
+        result.parameters["aspect_ratio"],
+        result.parameters["seed"],
+        result.parameters["steps"],
+        result.parameters["guidance"]
+      ].map { |value| value.nil? ? "" : value.to_s }.join("\u001f")
+    end
+    private_class_method :fingerprint_for
+  end
+end