token_reel 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d8ea0cf1ffd5db7548162763c7944b3005683791b0df22a9c56cc03200a2427a
+  data.tar.gz: ee2f2160151b7658ab65a13747b4dc84463ecc83b62bff1d659465a95ce99bce
+SHA512:
+  metadata.gz: f2835962949cc430260f3e37b620c2f0c4a9286c661ba64d895d4ea290ed2fc910d8adc7c1b20d3df17a28fbf06e9f3c3c917fbe32edd142d43388c9d53f7992
+  data.tar.gz: '087df605401c0cb00fdc2025cfd1d685e0c657ab167c2d31092b508b0136d8956ac650f9864a9209a1d405072e643cfcae8138000b47672289de7e8d9120e051'

data/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.0", "3.1", "3.2", "3.3"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ImageMagick
+        run: sudo apt-get update && sudo apt-get install -y imagemagick
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run specs
+        run: bundle exec rake spec
+
+      - name: Build gem
+        run: gem build token_reel.gemspec

data/.gitignore

@@ -0,0 +1,5 @@
+/pkg/
+*.gem
+*_frames/
+/spec/tmp/
+/Gemfile.lock

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,170 @@
+# TokenReel
+
+Render a terminal-style animated GIF of a prompt being answered by an
+LLM CLI -- prompt appears, there's a pause for **time to first token**,
+then the response streams in at a chosen **tokens/sec** rate. Useful
+for READMEs, blog posts, and talks that want a realistic-looking demo
+without a real model or a real screen recorder.
+
+Everything is driven by ImageMagick's `convert`/`magick` under the
+hood, so that needs to be installed and on `PATH`. Text is always
+rendered in a monospace font -- by default TokenReel auto-detects one
+from whatever ImageMagick has installed (DejaVu Sans Mono, Menlo,
+Consolas, Courier New, ...); pass `--font NAME` with an exact name from
+`magick -list font` to pick a specific one. This matters beyond looks:
+column wrapping, cursor placement, and code syntax highlighting all
+assume every glyph is the same width.
+
+## Install
+
+```bash
+gem install token_reel
+# or, in a Gemfile:
+gem "token_reel"
+```
+
+Requires ImageMagick (`brew install imagemagick` / `apt install imagemagick`).
+
+## CLI
+
+```bash
+token_reel \
+  --prompt "Refactor this method to be tail-recursive" \
+  --response $'Sure -- here\'s a tail-recursive version:\n\ndef sum(n, acc = 0)\n  return acc if n.zero?\n  sum(n - 1, acc + n)\nend' \
+  --tps 14 --ttft 0.8 --theme matrix -o demo.gif
+```
+
+Note the `$'...'` (ANSI-C) quoting -- plain `"..."` leaves `\n` as a literal
+backslash-n instead of a real newline.
+
+Read from files instead of inline strings:
+
+```bash
+token_reel -P prompt.txt -R response.md --tps 20 -o demo.gif
+```
+
+Or pipe both in, separated by a line of `---`:
+
+```bash
+cat <<'EOF' | token_reel --stdin -o demo.gif
+Explain time-to-first-token in one sentence.
+---
+Time to first token is the delay between sending a prompt and the
+model's first streamed token arriving -- it's latency, not throughput.
+EOF
+```
+
+Or write the whole exchange as one Markdown file and pass `-m`/`--markdown`.
+Get a starter file with `--init-markdown` (writes `exchange.md` by default,
+or pass a path -- it refuses to overwrite an existing file):
+
+```bash
+token_reel --init-markdown           # writes ./exchange.md
+token_reel --init-markdown demo.md   # writes ./demo.md
+```
+
+````markdown
+## Prompt
+
+Refactor this method to be tail-recursive.
+
+## Reasoning
+
+The recursive call isn't in tail position because of the addition
+after it returns -- an accumulator fixes that.
+
+## Output
+
+Sure -- here's a tail-recursive version:
+
+```ruby
+def sum(n, acc = 0)
+  return acc if n.zero?
+  sum(n - 1, acc + n)
+end
+```
+````
+
+```bash
+token_reel -m exchange.md --tps 14 --ttft 0.8 --theme matrix -o demo.gif
+```
+
+Headings are case-insensitive and also accept `User`/`Input`/`Question` for
+the prompt, `Thinking`/`Thought` for reasoning, and `Response`/`Answer`/
+`Assistant` for the output. A heading is only recognized outside of a
+fenced code block, so a `# Output`-style comment inside example code
+won't be mistaken for a section. The `## Reasoning` section is optional;
+when present it streams first (as if the model were thinking out loud)
+and is then replaced by the response once real output starts. Code
+fences (` ``` `) in any section -- from `-m`, `-r`/`-R`, or `--stdin` --
+are syntax-highlighted and rendered without the literal backtick lines.
+
+Run `token_reel --help` for the full flag list. The important ones:
+
+| flag | meaning | default |
+|---|---|---|
+| `--tps N` | response tokens/sec | `8` |
+| `--ttft N` | seconds of "thinking" before the first token | `0.6` |
+| `--prompt-tps N` | prompt typing speed, `0` = appears instantly | `0` |
+| `--reasoning-tps N` | reasoning typing speed, `0` = same as `--tps` | `0` |
+| `--unit word\|char` | stream whole words or single characters | `word` |
+| `--theme dark\|matrix\|light\|solarized` | color scheme | `dark` |
+| `--cols N` | console width, in characters | `80` |
+| `--rows N` | console height, in lines (scrolls once content grows past this) | `25` |
+| `--font NAME` | exact ImageMagick font name | auto-detected monospace |
+| `--fps N` | GIF frame rate | `12` |
+| `--hold N` | seconds to hold on the finished frame | `1.5` |
+| `-o, --out PATH` | output GIF path | `token_reel.gif` |
+
+## Ruby API
+
+```ruby
+require "token_reel"
+
+TokenReel.generate(
+  prompt:    "What's the airspeed velocity of an unladen swallow?",
+  reasoning: "This is the classic Monty Python bridgekeeper question.",
+  response:  "African or European swallow?",
+  tps:       10,
+  ttft:      0.4,
+  theme:     :dark,
+  out:       "swallow.gif"
+)
+```
+
+Or build a `TokenReel::Config` for more control and hand it to
+`TokenReel::Generator` directly:
+
+```ruby
+config = TokenReel::Config.new
+config.prompt   = File.read("prompt.txt")
+config.response = File.read("response.md")
+config.tps      = 16
+config.ttft     = 1.2
+config.theme    = :solarized
+config.out      = "demo.gif"
+
+TokenReel::Generator.new(config).generate!
+```
+
+## How timing works
+
+1. The prompt is shown -- instantly by default, or typed out at
+   `--prompt-tps` tokens/sec if you set it.
+2. Once the prompt is fully shown, `--ttft` seconds pass with a
+   blinking-cursor "thinking..." indicator -- this is your simulated
+   time to first token.
+3. If reasoning text was given, it streams in next at `--reasoning-tps`
+   tokens/sec (or `--tps` if that's unset), then disappears, replaced by
+   the response -- like a chat UI's collapsible thinking trace.
+4. The response then streams in one token (word or character,
+   per `--unit`) every `1 / --tps` seconds.
+5. The final frame holds for `--hold` seconds before the GIF loops.
+
+Frames are sampled at `--fps` and identical consecutive frames are
+collapsed into a single frame with a longer delay, so a long `--ttft`
+or a slow `--tps` doesn't blow up the frame count or file size.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+VERSION_FILE = File.expand_path("lib/token_reel/version.rb", __dir__)
+
+def current_version
+  File.read(VERSION_FILE).match(/VERSION = "(.*)"/)[1]
+end
+
+def write_version(new_version)
+  contents = File.read(VERSION_FILE)
+  updated = contents.sub(/VERSION = ".*"/, %(VERSION = "#{new_version}"))
+  File.write(VERSION_FILE, updated)
+end
+
+def bumped(part)
+  major, minor, patch = current_version.split(".").map(&:to_i)
+  case part
+  when :major then [major + 1, 0, 0]
+  when :minor then [major, minor + 1, 0]
+  when :patch then [major, minor, patch + 1]
+  end.join(".")
+end
+
+desc "Print the current version"
+task :version do
+  puts current_version
+end
+
+namespace :version do
+  desc "Bump major version (X.0.0) -- breaking changes"
+  task :major do
+    old_version = current_version
+    new_version = bumped(:major)
+    write_version(new_version)
+    puts "#{old_version} -> #{new_version} (lib/token_reel/version.rb updated, not committed)"
+  end
+
+  desc "Bump minor version (x.X.0) -- backwards-compatible features"
+  task :minor do
+    old_version = current_version
+    new_version = bumped(:minor)
+    write_version(new_version)
+    puts "#{old_version} -> #{new_version} (lib/token_reel/version.rb updated, not committed)"
+  end
+
+  desc "Bump patch version (x.x.X) -- backwards-compatible fixes"
+  task :patch do
+    old_version = current_version
+    new_version = bumped(:patch)
+    write_version(new_version)
+    puts "#{old_version} -> #{new_version} (lib/token_reel/version.rb updated, not committed)"
+  end
+end

data/exe/token_reel

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "token_reel"
+
+exit(TokenReel::CLI.run(ARGV))

data/lib/token_reel/cli.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module TokenReel
+  module CLI
+    # Parses ARGV into a Config. Returns nil if the parser already
+    # handled the request itself (e.g. --help, --version).
+    def self.parse(argv)
+      config = Config.new
+      prompt_file = nil
+      response_file = nil
+      reasoning_file = nil
+      markdown_file = nil
+      stdin_mode = false
+
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: token_reel [options]\n\n" \
+                    "Renders a terminal-style GIF of a prompt being answered, streamed\n" \
+                    "token-by-token at a chosen speed with a simulated time-to-first-token.\n\n"
+
+        o.on("-p", "--prompt TEXT", "Prompt text (shown as typed input)") { |v| config.prompt = v }
+        o.on("-P", "--prompt-file PATH", "Read the prompt from a file") { |v| prompt_file = v }
+        o.on("-r", "--response TEXT", "Response text (streamed as output)") { |v| config.response = v }
+        o.on("-R", "--response-file PATH", "Read the response from a file") { |v| response_file = v }
+        o.on("--reasoning TEXT", "Reasoning/thinking text, streamed then replaced by the response") { |v| config.reasoning = v }
+        o.on("--reasoning-file PATH", "Read the reasoning text from a file") { |v| reasoning_file = v }
+        o.on("-m", "--markdown PATH", "Read prompt/reasoning/response from one Markdown file " \
+                                       "(## Prompt / ## Reasoning / ## Output headings; overrides -p/-P/-r/-R/--reasoning[-file])") { |v| markdown_file = v }
+        o.on("--init-markdown [PATH]", "Write a starter Markdown template for -m/--markdown, then exit " \
+                                        "(default path: exchange.md)") do |v|
+          path = v || "exchange.md"
+          if File.exist?(path)
+            warn "token_reel: #{path} already exists, not overwriting"
+            exit(1)
+          end
+          File.write(path, Script.template)
+          puts "Wrote #{path}"
+          exit(0)
+        end
+        o.on("--stdin", "Read prompt and response from STDIN, separated by a line of '---'") { stdin_mode = true }
+
+        o.separator ""
+        o.separator "Timing:"
+        o.on("--tps N", Float, "Response tokens revealed per second (default: #{config.tps})") { |v| config.tps = v }
+        o.on("--ttft N", Float, "Time to first token, in seconds (default: #{config.ttft})") { |v| config.ttft = v }
+        o.on("--prompt-tps N", Float, "Prompt typing speed in tokens/sec, 0 = instant (default: #{config.prompt_tps})") { |v| config.prompt_tps = v }
+        o.on("--reasoning-tps N", Float, "Reasoning typing speed in tokens/sec, 0 = same as --tps (default: #{config.reasoning_tps})") { |v| config.reasoning_tps = v }
+        o.on("--unit UNIT", %w[word char], "Streaming unit: word or char (default: #{config.unit})") { |v| config.unit = v.to_sym }
+        o.on("--hold N", Float, "Seconds to hold the final frame (default: #{config.hold})") { |v| config.hold = v }
+        o.on("--fps N", Integer, "GIF frame rate (default: #{config.fps})") { |v| config.fps = v }
+        o.on("--loop N", Integer, "GIF loop count, 0 = forever (default: #{config.loop_count})") { |v| config.loop_count = v }
+
+        o.separator ""
+        o.separator "Look:"
+        o.on("--theme THEME", %w[dark matrix light solarized], "Color theme (default: #{config.theme})") { |v| config.theme = v.to_sym }
+        o.on("--cols N", Integer, "Console width, in characters (default: #{config.cols})") { |v| config.cols = v }
+        o.on("--rows N", Integer, "Console height, in lines; once content grows past this the window " \
+                                   "scrolls, like a real terminal (default: #{config.rows})") { |v| config.rows = v }
+        o.on("--font-size N", Integer, "Font point size (default: #{config.font_size})") { |v| config.font_size = v }
+        o.on("--font NAME", "ImageMagick font name (default: auto-detect a monospace font)") { |v| config.font = v }
+        o.on("--label STRING", "Prompt prefix (default: #{config.label.inspect})") { |v| config.label = v }
+        o.on("--title STRING", "Window title bar text (default: #{config.title.inspect})") { |v| config.title = v }
+        o.on("--cursor CHAR", "Cursor glyph (default: #{config.cursor_char.inspect})") { |v| config.cursor_char = v }
+
+        o.separator ""
+        o.separator "Output:"
+        o.on("-o", "--out PATH", "Output GIF path (default: #{config.out})") { |v| config.out = v }
+        o.on("--keep-frames", "Keep the intermediate PNG frames on disk") { config.keep_frames = true }
+
+        o.separator ""
+        o.on("-v", "--version", "Print the version and exit") do
+          puts TokenReel::VERSION
+          exit(0)
+        end
+        o.on("-h", "--help", "Print this help and exit") do
+          puts o
+          exit(0)
+        end
+      end
+
+      parser.parse!(argv)
+
+      config.prompt = File.read(prompt_file) if prompt_file
+      config.response = File.read(response_file) if response_file
+      config.reasoning = File.read(reasoning_file) if reasoning_file
+
+      if markdown_file
+        sections = Script.parse(File.read(markdown_file))
+        config.prompt = sections[:prompt] if sections.key?(:prompt)
+        config.reasoning = sections[:reasoning] if sections.key?(:reasoning)
+        config.response = sections[:response] if sections.key?(:response)
+      end
+
+      if stdin_mode
+        prompt, response = $stdin.read.split(/^---\s*$/, 2)
+        config.prompt = prompt.to_s.strip
+        config.response = response.to_s.strip
+      end
+
+      config
+    rescue OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument => e
+      warn "token_reel: #{e.message}"
+      warn parser
+      exit(1)
+    end
+
+    def self.run(argv)
+      config = parse(argv)
+      path = Generator.new(config).generate!
+      puts "Wrote #{path}"
+      0
+    rescue Error => e
+      warn "token_reel: #{e.message}"
+      1
+    end
+  end
+end

data/lib/token_reel/config.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module TokenReel
+  # All the knobs that control a render. Build one directly, or via
+  # TokenReel::CLI.parse(ARGV).
+  class Config
+    attr_accessor :prompt, :response, :reasoning,
+                  :tps, :ttft, :prompt_tps, :reasoning_tps, :unit,
+                  :cols, :rows, :font, :font_size, :fps,
+                  :theme, :hold, :loop_count,
+                  :label, :thinking_label, :title, :cursor_char,
+                  :out, :keep_frames
+
+    def initialize
+      @prompt         = ""
+      @response       = ""
+      @reasoning      = ""      # optional; shown streaming during the "thinking" pause, then replaced by the response
+      @tps            = 8.0     # response tokens revealed per second
+      @ttft           = 0.6     # seconds of "thinking" before first token
+      @prompt_tps     = 0       # 0 = prompt appears instantly, fully typed
+      @reasoning_tps  = 0       # 0 = same rate as tps
+      @unit           = :word   # :word or :char
+      @cols           = 80      # console width, in characters (classic terminal default: 80x25)
+      @rows           = 25      # console height, in lines -- once content grows past this, the
+                                 # window scrolls (oldest lines drop off the top), like a real terminal
+      @font           = nil     # nil = auto-detect an available monospace font, see Fonts
+      @font_size      = 20
+      @fps            = 12
+      @theme          = :dark
+      @hold           = 1.5     # seconds to hold the final frame
+      @loop_count     = 0       # 0 = loop forever
+      @label          = "\u276F " # "❯ "
+      @thinking_label = "thinking"
+      @title          = "assistant"
+      @cursor_char    = "\u258A" # "▊"
+      @out            = "token_reel.gif"
+      @keep_frames    = false
+    end
+
+    def validate!
+      raise ConfigError, "prompt can't be blank" if prompt.to_s.empty?
+      raise ConfigError, "response can't be blank" if response.to_s.empty?
+      raise ConfigError, "tps must be > 0" unless tps.to_f.positive?
+      raise ConfigError, "ttft can't be negative" if ttft.to_f.negative?
+      raise ConfigError, "prompt_tps can't be negative" if prompt_tps.to_f.negative?
+      raise ConfigError, "reasoning_tps can't be negative" if reasoning_tps.to_f.negative?
+      raise ConfigError, "cols must be >= 20" if cols.to_i < 20
+      raise ConfigError, "rows must be >= 3" if rows.to_i < 3
+      raise ConfigError, "fps must be between 1 and 50" unless (1..50).cover?(fps.to_i)
+      raise ConfigError, "font_size must be >= 8" if font_size.to_i < 8
+      raise ConfigError, "hold can't be negative" if hold.to_f.negative?
+
+      self
+    end
+  end
+end

data/lib/token_reel/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TokenReel
+  class Error < StandardError; end
+  class RenderError < Error; end
+  class ConfigError < Error; end
+end

data/lib/token_reel/fonts.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TokenReel
+  # Picks and validates the monospace font ImageMagick renders text
+  # with. This matters more than it sounds: the whole layout (column
+  # wrapping, cursor placement, and the per-span x-offsets syntax
+  # highlighting draws at) assumes every glyph is the same width, which
+  # is only true if the font actually resolves to a real monospace
+  # font. ImageMagick silently falls back to *some* default font (and
+  # only warns on stderr, without failing) when asked for a font name
+  # it doesn't know -- so guessing a hardcoded name and trusting it
+  # works is how you end up with misaligned, overlapping text.
+  module Fonts
+    # Common monospace font names, in priority order, as ImageMagick
+    # tends to expose them across Linux/macOS/Windows installs.
+    CANDIDATES = %w[
+      DejaVu-Sans-Mono Menlo-Regular Consolas Liberation-Mono
+      Courier-New Monaco Andale-Mono PT-Mono Noto-Sans-Mono
+      Ubuntu-Mono Cascadia-Mono JetBrains-Mono JetBrainsMono-Regular
+      Fira-Code FiraCode-Regular Hack-Regular Courier fixed
+    ].freeze
+
+    def self.available
+      @available ||= `#{Shellwords.escape(Renderer.convert_binary)} -list font 2>/dev/null`
+                     .scan(/^\s*Font:\s*(\S+)/).flatten
+    end
+
+    # name == nil means "pick one for me". A name the caller passed in
+    # explicitly is validated against what ImageMagick actually knows,
+    # rather than trusted -- see the module comment for why.
+    def self.resolve!(name)
+      return autodetect if name.nil?
+      return name if available.include?(name)
+
+      raise RenderError,
+            "font #{name.inspect} not found via `#{Renderer.convert_binary} -list font` " \
+            "(pass --font with an exact name from that list, or omit --font to auto-detect)"
+    end
+
+    def self.autodetect
+      CANDIDATES.find { |name| available.include?(name) } ||
+        raise(RenderError,
+              "no monospace font found on this system; install one of " \
+              "#{CANDIDATES.first(4).join(', ')}, etc., or pass --font NAME " \
+              "with an exact name from `#{Renderer.convert_binary} -list font`")
+    end
+  end
+end

data/lib/token_reel/generator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require "digest"
+
+module TokenReel
+  class Generator
+    def initialize(config)
+      @config = config.validate!
+      @timeline = Timeline.new(config)
+      @renderer = Renderer.new(config, @timeline)
+    end
+
+    # Returns the output path on success.
+    def generate!
+      workdir = @config.keep_frames ? make_persistent_workdir : nil
+      Dir.mktmpdir do |tmp|
+        dir = workdir || tmp
+        frames = sample_and_render(dir)
+        GifWriter.assemble(frames, @config.out, @config.loop_count)
+      end
+      @config.out
+    end
+
+    private
+
+    def make_persistent_workdir
+      base = File.basename(@config.out.to_s).sub(/\.gif\z/i, "")
+      base = "token_reel" if base.strip.empty?
+      dir = "#{base}_frames"
+      FileUtils.mkdir_p(dir)
+      dir
+    end
+
+    # Walks the timeline at a fixed frame rate. Consecutive samples
+    # that render to an identical frame (very common during the
+    # "thinking" pause, or whenever fps > tps) are collapsed into one
+    # frame with a longer delay instead of being rendered twice.
+    def sample_and_render(dir)
+      step = 1.0 / @config.fps
+      delay_cs = [(step * 100).round, 1].max
+      rendered = {} # signature -> path, so repeated (non-consecutive) states reuse a PNG
+
+      frames = []
+      t = 0.0
+      index = 0
+      loop do
+        state = @timeline.state_at(t)
+        sig = state.signature
+
+        if frames.any? && frames.last[:sig] == sig
+          frames.last[:delay_cs] += delay_cs
+        else
+          path = rendered[sig] ||= begin
+            p = File.join(dir, format("frame_%05d.png", index += 1))
+            @renderer.render(state, p)
+            p
+          end
+          frames << { sig: sig, path: path, delay_cs: delay_cs }
+        end
+
+        break if t >= @timeline.duration
+
+        t = [t + step, @timeline.duration].min
+      end
+
+      frames
+    end
+  end
+end

data/lib/token_reel/gif_writer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module TokenReel
+  module GifWriter
+    # frames: [{ path: "...", delay_cs: Integer }, ...] in playback order.
+    def self.assemble(frames, out_path, loop_count)
+      raise RenderError, "no frames to assemble" if frames.empty?
+
+      argv = [Renderer.convert_binary, "-loop", loop_count.to_s]
+      frames.each do |f|
+        argv += ["-delay", f[:delay_cs].to_s, "-dispose", "Background", f[:path]]
+      end
+      argv << out_path
+
+      _out, err, status = Open3.capture3(*argv)
+      raise RenderError, "ImageMagick failed to assemble GIF: #{err}" unless status.success?
+
+      out_path
+    end
+  end
+end