flux3_ai_prompt_tools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 458cf2f3b6fa96e5d615158ec3ebd732850b9e0ef1637ea9f94948072167a1ee
+  data.tar.gz: 2d5279558f4f02efe4f75d0812d5c7bcda6e39c7724ea6fe63d03d07a0408d85
+SHA512:
+  metadata.gz: 86572ec322850a4ebfe673cafaccdbeec4a4c3bb4eaa7bf9fe7f1b4d0689c2101f690f47dbebe3babfb024a0a31eec73169a7880be47515b47b69bc9173a1548
+  data.tar.gz: 438c501aea1204264bce8ff7348e0ff5718c9ca9993469cb0b85adfabc25e17d06e9ffc1230ada6d027b12e422bc2e24c3b0800484520ce53a38b2390ddfcc92

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+Initial release of the offline prompt assembler.
+
+- Validate structured text-to-image prompt records.
+- Assemble `natural`, `tagged`, and `labeled` prompt text.
+- Write JSON and JSONL batch manifests.
+- Provide the `flux3-prompt` executable and a Ruby library API.
+- Ship local writing presets, a JSON Schema description, examples, and tests.
+
+This version does not generate images and does not make network calls.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# flux3_ai_prompt_tools
+
+`flux3_ai_prompt_tools` is an offline Ruby library and command-line tool by Andy Wang. It turns structured prompt specifications into text-to-image prompt strings and batch manifests. The project homepage is [https://flux3-ai.com/](https://flux3-ai.com/).
+
+The gem checks the fields you provide, rejects malformed records, and writes a deterministic prompt plus a separate negative prompt. It can read one JSON object, a JSON array, or JSONL, and it can write a JSON document or JSONL. Nothing in this process contacts a model host. The package does not generate images, videos, or audio, and it does not contain an API client.
+
+This is an independent utility. It is not a Black Forest Labs product, it is not an official FLUX client, and it is not the `flux_3_org` gem.
+
+## What it does
+
+A record has a required `subject` and optional art-direction fields: `scene`, `medium`, `style`, `lighting`, `composition`, `camera`, `palette`, `mood`, `details`, and `negatives`. Optional manifest metadata is `aspect_ratio`, `seed`, `steps`, `guidance`, `id`, and `note`. A `preset` fills a few of the art-direction fields with a local writing template. Your own values replace the template. Set a field to `null` to clear a template value.
+
+Three layouts are built in.
+
+`natural` writes short sentences such as `Lighting: soft window light.` The assembler does not change your capitalization. If a sentence already ends with `.`, `!`, or `?`, it leaves that ending in place.
+
+`tagged` joins the same fields with commas. A weighted detail is rendered as `(phrase:1.2)`. Commas that you typed inside a field are not escaped, so the labeled layout is the safer choice when a field itself contains commas.
+
+`labeled` writes one `Label: value` line per filled field. Empty fields are skipped.
+
+Weights are accepted only on details, from 0.1 through 2.0, with at most two decimal places. A weight of 1 is unmarked. The negative list is not pasted into the positive prompt. It is returned in `negative_prompt`. The `note` field is copied into the manifest and is never inserted into either prompt. `seed`, `steps`, `guidance`, and `aspect_ratio` are stored under `parameters` for your own bookkeeping. This gem does not send them to a renderer and does not claim that any model will honor them.
+
+Batch mode assigns ids such as `item-0001` when you omit `id`. It rejects duplicate ids. It also rejects a later record that repeats the same prompt, negative prompt, layout, and parameters. Use a different seed, or change the wording, when you want more than one job from similar text. `--keep-going` still writes a manifest when some records are bad. Those records have `"ok": false`, a null prompt, and an `errors` array. Without that flag the command writes nothing and exits with an error. Record order is the input order.
+
+Validation covers types, blank strings, control characters, Unicode line separators, UTF-8, unknown fields, preset names, and aspect ratios whose sides are integers from 1 through 64. Seeds must be integers in the safe JSON range, 0 through 9007199254740991. Steps must be integers from 1 through 150. Guidance must be a number from 0 through 30 with at most two decimal places. Assembled text must fit the character budget. The defaults are 2000 characters for the prompt and 1000 for the negative prompt. Counts are Unicode characters, not model tokens. Input larger than 5,000,000 bytes, or a batch larger than 5000 records, is refused. Unknown JSON keys are errors, so a typo is not silently dropped and is not inserted into the prompt.
+
+The shipped presets are `product_still`, `portrait`, `environment`, and `graphic_poster`. They are short English writing templates stored in the gem. They are not model defaults and they are not account settings. `flux3-prompt schema` prints a JSON Schema description of one record. The validator in this gem is the authority if a document passes a looser third-party schema check. The schema is printed locally. The tool does not download it.
+
+## Install
+
+The library needs Ruby 3.1 or newer. Runtime code uses the standard library only. There are no runtime gem dependencies.
+
+From a local gem file:
+
+```bash
+gem install --user-install flux3_ai_prompt_tools-0.1.0.gem
+flux3-prompt version
+```
+
+After the owner publishes the package to RubyGems, the same gem can be installed with `gem install flux3_ai_prompt_tools`. Installing this repository does not publish the gem and does not create an account.
+
+From a checkout of the source, without installing:
+
+```bash
+ruby -Ilib bin/flux3-prompt version
+rake test
+gem build flux3_ai_prompt_tools.gemspec
+```
+
+## Library
+
+```ruby
+require "flux3_ai_prompt_tools"
+
+result = Flux3AiPromptTools.assemble(
+  {
+    "subject" => "a matte cream ceramic pour-over kettle",
+    "scene" => "on a walnut table",
+    "preset" => "product_still",
+    "negatives" => ["text", "watermark"],
+    "aspect_ratio" => "4:5",
+    "seed" => 1204
+  },
+  layout: "natural"
+)
+
+result.prompt
+result.negative_prompt
+result.to_h
+
+issues = Flux3AiPromptTools.validate({ "style" => "quiet" })
+manifest = Flux3AiPromptTools.build_manifest(
+  [
+    { "subject" => "a red bowl" },
+    { "subject" => "a blue cup", "layout" => "tagged" }
+  ]
+)
+File.write("prompts.jsonl", manifest.to_jsonl)
+```
+
+`assemble` raises `Flux3AiPromptTools::ValidationError` when the record is invalid or the assembled text exceeds its budget. `validate` returns an array of issues and does not raise. An empty array means the record is usable. `build_manifest` raises unless you pass `keep_going: true`. `load_file` reads a JSON or JSONL file into an array of hashes, which you can pass to `build_manifest`. Symbol keys are accepted from Ruby. A JSON null clears a preset field instead of failing the type check.
+
+## Command line
+
+Print one prompt:
+
+```bash
+flux3-prompt assemble \
+  --preset product_still \
+  --subject "a matte cream ceramic pour-over kettle" \
+  --scene "on a walnut table" \
+  --negative text \
+  --negative watermark \
+  --aspect-ratio 4:5 \
+  --seed 1204
+```
+
+Add `--manifest` to print the JSON record instead of the prompt text. Add `--layout tagged` or `--layout labeled` to change the wording. The plain command prints only the positive prompt, so a shell pipeline can capture it. Use `--manifest` when you also need the negative prompt, the parameters, and the character counts.
+
+Check a file, including the examples in this repository:
+
+```bash
+flux3-prompt validate examples/kettle.json
+flux3-prompt batch examples/batch.jsonl --format jsonl -o prompts.jsonl
+flux3-prompt schema
+flux3-prompt presets
+```
+
+`batch` accepts a JSON object, a JSON array, or JSONL. Use `-` to read stdin. `--input-format` may be `auto`, `json`, or `jsonl`. A file extension of `.json` or `.jsonl` selects the matching reader when the format is `auto`. A UTF-8 byte order mark at the start of the file is ignored. Blank lines in JSONL are ignored. A broken JSONL line stops the whole file, because a partial parse would drop the rest of the batch without telling you where the document became unreadable.
+
+`--format` chooses the output. A path ending in `.jsonl` or `.json` selects that format when `--format` is omitted. Output written to a file replaces that file through a temporary file in the same directory. Stdout defaults to JSONL, one record per line, and each line includes the generator name and version. The JSON document form adds a top-level `ok` flag and the default layout around the same records.
+
+Exit status is `0` for success, `1` when the input or a record is invalid, and `2` when the command line itself is invalid. In `--keep-going` mode a batch with any failed record is still written, and the exit status is `1`.
+
+## Tests
+
+The suite is Minitest. It does not need network access:
+
+```bash
+rake test
+```
+
+The packaged gem includes the library, the executable, the tests, the examples, this README, the changelog, and the MIT license.
+
+## Limitations
+
+The assembler is a formatter. It does not tokenize a prompt the way any particular model does, and a prompt that passes the character budget can still be too long, too vague, or rejected by a downstream service. Passing `aspect_ratio`, `seed`, `steps`, or `guidance` only stores those values in the manifest. It does not resize a canvas, set a random seed, or choose a sampler.
+
+Tagged output does not escape commas or parentheses inside a field. Very large weights and more than two decimal places are rejected rather than rounded silently. The same prompt with the same parameters is treated as a duplicate job so an accidental double paste is visible. That check is exact string equality after assembly, not a similarity score.
+
+The tool loads a whole batch into memory and writes the manifest in one pass. It is aimed at authoring batches of thousands of records, not at multi-gigabyte streams. Presets are English templates. The natural and labeled layouts do not translate text. There is no image upload, no preview, and no retry against a generator, because this package never opens a network connection and does not read credentials, tokens, or environment secrets. Publishing the gem, choosing a public source repository, and signing in to RubyGems are left to the owner.
+
+## License
+
+MIT. Copyright (c) 2026 Andy Wang.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "lib" << "test"
+  task.test_files = FileList["test/**/*_test.rb"]
+  task.warning = true
+end
+
+task default: :test

data/bin/flux3-prompt

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "flux3_ai_prompt_tools"
+require "flux3_ai_prompt_tools/cli"
+
+begin
+  exit Flux3AiPromptTools::CLI.start(ARGV)
+rescue Flux3AiPromptTools::UsageError => e
+  warn "error: #{e.message}"
+  exit 2
+rescue Flux3AiPromptTools::ValidationError => e
+  e.issues.each do |issue|
+    warn "error: #{issue.path} #{issue.code}: #{issue.message}"
+  end
+  exit 1
+rescue Flux3AiPromptTools::InputError => e
+  warn "error: #{e.message}"
+  exit 1
+rescue Flux3AiPromptTools::Error => e
+  warn "error: #{e.message}"
+  exit 1
+end

data/examples/batch.jsonl

@@ -0,0 +1,2 @@
+{"id":"kettle-01","preset":"product_still","subject":"a matte cream ceramic pour-over kettle","scene":"on a walnut table in a quiet kitchen","palette":"warm walnut and matte cream","negatives":["text","watermark"],"aspect_ratio":"4:5","seed":1204}
+{"id":"cup-02","preset":"portrait","subject":"a person holding a small blue cup","lighting":"north window light","negatives":["distorted hands"],"aspect_ratio":"3:4","seed":1205,"layout":"tagged"}

data/examples/kettle.json

@@ -0,0 +1,16 @@
+{
+  "id": "kettle-01",
+  "preset": "product_still",
+  "subject": "a matte cream ceramic pour-over kettle",
+  "scene": "on a walnut table in a quiet kitchen",
+  "style": "editorial product photography",
+  "palette": "warm walnut, matte cream, and muted sage",
+  "details": [
+    "steam rising from the spout",
+    {"text": "visible wood grain", "weight": 1.2}
+  ],
+  "negatives": ["text", "watermark", "extra handle"],
+  "aspect_ratio": "4:5",
+  "seed": 1204,
+  "note": "Local reminder only. This file is not sent anywhere."
+}

data/flux3_ai_prompt_tools.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/flux3_ai_prompt_tools/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "flux3_ai_prompt_tools"
+  spec.version = Flux3AiPromptTools::VERSION
+  spec.authors = ["Andy Wang"]
+  spec.summary = "Validate structured inputs and assemble offline text-to-image prompt manifests."
+  spec.description = <<~TEXT
+    Offline Ruby library and command-line tool that validates structured prompt
+    specifications and assembles text-to-image prompts into JSON and JSONL
+    manifests. It does not generate images, call a model API, or send data
+    over the network. It is an independent utility by Andy Wang and is not a
+    Black Forest Labs product, an official FLUX client, or the flux_3_org gem.
+  TEXT
+  spec.homepage = "https://flux3-ai.com/"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "lib/**/*.rb",
+      "bin/flux3-prompt",
+      "test/**/*.rb",
+      "examples/**/*",
+      "README.md",
+      "LICENSE",
+      "CHANGELOG.md",
+      "Rakefile",
+      "flux3_ai_prompt_tools.gemspec"
+    ].select { |path| File.file?(path) }
+  end
+  spec.bindir = "bin"
+  spec.executables = ["flux3-prompt"]
+  spec.require_paths = ["lib"]
+
+  spec.metadata = {
+    "homepage_uri" => "https://flux3-ai.com/",
+    "allowed_push_host" => "https://rubygems.org"
+  }
+end

data/lib/flux3_ai_prompt_tools/assembler.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+require_relative "layouts"
+require_relative "numbers"
+require_relative "version"
+
+module Flux3AiPromptTools
+  # One assembled record, successful or withheld after a budget or batch error.
+  class Result
+    attr_reader :id, :ok, :prompt, :negative_prompt, :layout, :parameters, :counts, :note, :errors
+
+    def initialize(id:, ok:, prompt:, negative_prompt:, layout:, parameters:, counts:, note:, errors:)
+      @id = id
+      @ok = ok
+      @prompt = prompt
+      @negative_prompt = negative_prompt
+      @layout = layout
+      @parameters = parameters.dup.freeze
+      @counts = counts.dup.freeze
+      @note = note
+      @errors = errors.dup.freeze
+      freeze
+    end
+
+    def to_h
+      {
+        "generator" => "flux3_ai_prompt_tools/#{VERSION}",
+        "id" => id,
+        "ok" => ok,
+        "prompt" => prompt,
+        "negative_prompt" => negative_prompt,
+        "layout" => layout,
+        "parameters" => parameters,
+        "counts" => counts,
+        "note" => note,
+        "errors" => errors.map(&:to_h)
+      }
+    end
+  end
+
+  # Builds deterministic prompt text. It does not call a model.
+  class Assembler
+    def self.assemble(spec, layout:, limits:, raise_on_error: true)
+      unless spec.is_a?(Specification)
+        raise ArgumentError, "spec must be a Flux3AiPromptTools::Specification"
+      end
+      unless limits.is_a?(Limits)
+        raise ArgumentError, "limits must be a Flux3AiPromptTools::Limits"
+      end
+
+      chosen = spec.layout || layout
+      unless chosen.is_a?(String) && Layouts::NAMES.include?(chosen)
+        raise ArgumentError, "layout must be one of: #{Layouts::NAMES.join(', ')}"
+      end
+
+      prompt = render(spec, chosen)
+      negative = spec.negatives.join(", ")
+      issues = []
+      if prompt.length > limits.max_prompt_chars
+        issues << Issue.new(
+          "/prompt",
+          "too_long",
+          "assembled prompt is #{prompt.length} characters; limit is #{limits.max_prompt_chars}"
+        )
+      end
+      if negative.length > limits.max_negative_chars
+        issues << Issue.new(
+          "/negative_prompt",
+          "too_long",
+          "assembled negative prompt is #{negative.length} characters; limit is #{limits.max_negative_chars}"
+        )
+      end
+
+      result = Result.new(
+        id: spec.id,
+        ok: issues.empty?,
+        prompt: issues.empty? ? prompt : nil,
+        negative_prompt: issues.empty? ? negative : nil,
+        layout: chosen,
+        parameters: {
+          "aspect_ratio" => spec.aspect_ratio,
+          "seed" => spec.seed,
+          "steps" => spec.steps,
+          "guidance" => spec.guidance
+        },
+        counts: {
+          "prompt_chars" => prompt.length,
+          "negative_chars" => negative.length,
+          "details" => spec.details.length,
+          "negatives" => spec.negatives.length
+        },
+        note: spec.note,
+        errors: issues
+      )
+      raise ValidationError, result.errors if raise_on_error && !result.ok
+
+      result
+    end
+
+    def self.render(spec, layout)
+      case layout
+      when "natural" then render_natural(spec)
+      when "tagged" then render_tagged(spec)
+      when "labeled" then render_labeled(spec)
+      else
+        raise ArgumentError, "unknown layout #{layout.inspect}"
+      end
+    end
+    private_class_method :render
+
+    def self.render_natural(spec)
+      parts = []
+      opening = spec.scene ? "#{spec.subject}, #{spec.scene}" : spec.subject
+      parts << sentence(opening)
+
+      look = []
+      look << spec.medium if spec.medium
+      look << "#{spec.style} style" if spec.style
+      parts << sentence(look.join(", ")) if look.any?
+
+      [
+        ["Lighting", spec.lighting],
+        ["Composition", spec.composition],
+        ["Camera", spec.camera],
+        ["Palette", spec.palette],
+        ["Mood", spec.mood]
+      ].each do |label, value|
+        parts << sentence("#{label}: #{value}") if value
+      end
+
+      if spec.details.any?
+        rendered = spec.details.map { |detail| render_detail_words(detail) }
+        parts << sentence("Details: #{rendered.join('; ')}")
+      end
+      parts.join(" ")
+    end
+    private_class_method :render_natural
+
+    def self.render_tagged(spec)
+      tokens = []
+      tokens << spec.subject
+      tokens << spec.scene if spec.scene
+      tokens << spec.medium if spec.medium
+      tokens << spec.style if spec.style
+      tokens << spec.lighting if spec.lighting
+      tokens << spec.composition if spec.composition
+      tokens << spec.camera if spec.camera
+      tokens << spec.palette if spec.palette
+      tokens << spec.mood if spec.mood
+      spec.details.each do |detail|
+        tokens << (detail.neutral? ? detail.text : "(#{detail.text}:#{Numbers.format_hundredths(detail.hundredths)})")
+      end
+      tokens.join(", ")
+    end
+    private_class_method :render_tagged
+
+    def self.render_labeled(spec)
+      rows = [["Subject", spec.subject]]
+      rows << ["Scene", spec.scene]
+      rows << ["Medium", spec.medium]
+      rows << ["Style", spec.style]
+      rows << ["Lighting", spec.lighting]
+      rows << ["Composition", spec.composition]
+      rows << ["Camera", spec.camera]
+      rows << ["Palette", spec.palette]
+      rows << ["Mood", spec.mood]
+      if spec.details.any?
+        rows << ["Details", spec.details.map { |detail| render_detail_words(detail) }.join("; ")]
+      end
+      rows.select { |_label, value| value }.map { |label, value| "#{label}: #{value}" }.join("\n")
+    end
+    private_class_method :render_labeled
+
+    def self.render_detail_words(detail)
+      return detail.text if detail.neutral?
+
+      "#{detail.text} (emphasis #{Numbers.format_hundredths(detail.hundredths)})"
+    end
+    private_class_method :render_detail_words
+
+    def self.sentence(text)
+      stripped = text.strip
+      return stripped if stripped.match?(/[.!?]["']?\z/)
+
+      "#{stripped}."
+    end
+    private_class_method :sentence
+  end
+end