token_reel 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8ea0cf1ffd5db7548162763c7944b3005683791b0df22a9c56cc03200a2427a
-  data.tar.gz: ee2f2160151b7658ab65a13747b4dc84463ecc83b62bff1d659465a95ce99bce
+  metadata.gz: b8a6442883c40d8cc57ff6c4763fde5fbfa7b1c5b018a77023bc8a38f41de047
+  data.tar.gz: e98f5f9e2cfce2c6cfe9cb32888ef106a492ed4b6b671e9d80d0412dab1d8734
 SHA512:
-  metadata.gz: f2835962949cc430260f3e37b620c2f0c4a9286c661ba64d895d4ea290ed2fc910d8adc7c1b20d3df17a28fbf06e9f3c3c917fbe32edd142d43388c9d53f7992
-  data.tar.gz: '087df605401c0cb00fdc2025cfd1d685e0c657ab167c2d31092b508b0136d8956ac650f9864a9209a1d405072e643cfcae8138000b47672289de7e8d9120e051'
+  metadata.gz: 3d0f2bf7add9fd157f157e2c34f462b37bae1d0a8689adb30390b8bd4bfa3e944cdcda8852fb0437298bd3ee14926b52775d4abf8d98a3382230296ca4bf05bc
+  data.tar.gz: 5156c0c8b53610b545be54f43f2c66ee86b2eaa127347a8a9d84c2c8a93ab99ffa0132a5f194e5e6606f634d7a891de032ca09cb4959f77c4c2c318fbeca8085

data/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+# Publishes to RubyGems whenever a "v*" tag is pushed (see
+# .github/workflows/version-bump.yml, which creates that tag). Uses
+# RubyGems' Trusted Publishing (OIDC) -- no API key stored in this repo.
+# One-time setup required on rubygems.org: Settings > Trusted Publishers
+# on the token_reel gem, with owner "stringsn88keys", repository
+# "token_reel", workflow filename "release.yml", environment "release".
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Verify build
+    runs-on: ubuntu-latest
+    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: "3.3"
+          bundler-cache: true
+
+      - name: Run specs
+        run: bundle exec rake spec
+
+      - name: Build gem
+        run: gem build token_reel.gemspec
+
+  release:
+    name: Publish to RubyGems
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ruby
+
+      - uses: rubygems/release-gem@v1

data/.github/workflows/version-bump.yml

@@ -0,0 +1,62 @@
+name: Version Bump
+
+# Bumps the gem version when a PR is merged to main with a "major",
+# "minor", or "patch" label, then tags the resulting commit. Pushing
+# that tag triggers .github/workflows/release.yml, which publishes the
+# gem to RubyGems.
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  bump:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - name: Determine version bump from labels
+        id: bump
+        env:
+          LABELS_JSON: ${{ toJSON(github.event.pull_request.labels.*.name) }}
+        run: |
+          has_label() { echo "$LABELS_JSON" | jq -e --arg l "$1" 'index($l) != null' > /dev/null; }
+          if has_label major; then
+            part=major
+          elif has_label minor; then
+            part=minor
+          elif has_label patch; then
+            part=patch
+          else
+            part=""
+          fi
+          echo "part=$part" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v4
+        if: steps.bump.outputs.part != ''
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - uses: ruby/setup-ruby@v1
+        if: steps.bump.outputs.part != ''
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Bump version
+        if: steps.bump.outputs.part != ''
+        run: bundle exec rake "version:${{ steps.bump.outputs.part }}"
+
+      - name: Commit and tag
+        if: steps.bump.outputs.part != ''
+        run: |
+          new_version=$(ruby -e 'puts File.read("lib/token_reel/version.rb")[/VERSION = "(.*)"/, 1]')
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -am "Bump version to ${new_version}"
+          git tag "v${new_version}"
+          git push origin main "v${new_version}"

data/README.md

@@ -114,6 +114,8 @@ Run `token_reel --help` for the full flag list. The important ones:
 | `--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` |
+| `--variability` | jitter each token's delay +/-10/20/30% (normal distribution) for a more natural, less metronomic stream | off |
+| `--seed N` | RNG seed for `--variability`, for reproducible output | random |
 | `-o, --out PATH` | output GIF path | `token_reel.gif` |
 
 ## Ruby API
@@ -165,6 +167,45 @@ 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.
 
+By default every token in a stream lands at an exact, metronomic
+interval. Pass `--variability` to jitter each token's delay instead:
+per token, one of +/-10%, +/-20%, or +/-30% is picked at random and
+applied as a normally-distributed offset around the base interval, so
+some tokens land a little early and others a little late -- closer to
+how a real model streams. Pair it with `--seed N` to reproduce the
+exact same jittered timeline across runs.
+
+## Releasing
+
+Version bumps and RubyGems publishing are both automated, driven off
+PR labels:
+
+1. Label a PR `major`, `minor`, or `patch` (semver meaning, same as
+   the `rake version:*` tasks below) before merging it to `main`.
+2. On merge, [`version-bump.yml`](.github/workflows/version-bump.yml)
+   bumps `lib/token_reel/version.rb` accordingly, commits it to
+   `main`, and pushes a matching `vX.Y.Z` tag.
+3. That tag push triggers [`release.yml`](.github/workflows/release.yml),
+   which runs the test suite and then publishes the gem to RubyGems
+   using [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/)
+   (OIDC -- no API key stored in this repo).
+
+A PR merged without one of those labels doesn't bump the version or
+release anything.
+
+Trusted Publishing needs a one-time setup on rubygems.org, under the
+gem's *Trusted Publishers* settings: owner `stringsn88keys`, repository
+`token_reel`, workflow filename `release.yml`, environment `release`.
+
+The version can also be bumped locally without releasing:
+
+```bash
+rake version         # print the current version
+rake version:patch   # x.x.X -- backwards-compatible fixes
+rake version:minor   # x.X.0 -- backwards-compatible features
+rake version:major   # X.0.0 -- breaking changes
+```
+
 ## License
 
 MIT

data/Rakefile

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)

data/lib/token_reel/cli.rb

@@ -50,6 +50,8 @@ module TokenReel
         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.on("--variability", "Jitter each token's delay by a random +/-10/20/30% (normal distribution)") { config.variability = true }
+        o.on("--seed N", Integer, "RNG seed for --variability, for reproducible output (default: random)") { |v| config.seed = v }
 
         o.separator ""
         o.separator "Look:"

data/lib/token_reel/config.rb

@@ -9,7 +9,8 @@ module TokenReel
                   :cols, :rows, :font, :font_size, :fps,
                   :theme, :hold, :loop_count,
                   :label, :thinking_label, :title, :cursor_char,
-                  :out, :keep_frames
+                  :out, :keep_frames,
+                  :variability, :seed
 
     def initialize
       @prompt         = ""
@@ -35,6 +36,8 @@ module TokenReel
       @cursor_char    = "\u258A" # "▊"
       @out            = "token_reel.gif"
       @keep_frames    = false
+      @variability    = false   # jitter each token's delay by a random +/-10/20/30% (normal distribution)
+      @seed           = nil     # RNG seed for --variability; nil = a fresh random seed each run
     end
 
     def validate!

data/lib/token_reel/timeline.rb

@@ -20,6 +20,11 @@ module TokenReel
     BLINK_HZ = 2.0     # cursor toggles this many times per second
     DOT_INTERVAL = 0.35 # seconds between "thinking..." dot ticks
 
+    # When config.variability is on, each token's delay is independently
+    # jittered by a normally-distributed offset, bounded to +/- one of
+    # these percentages (picked at random per token) of its base interval.
+    JITTER_PCTS = [0.10, 0.20, 0.30].freeze
+
     attr_reader :prompt_tokens, :reasoning_tokens, :response_tokens,
                 :prompt_full, :reasoning_full, :response_full,
                 :prompt_done_t, :thinking_end_t, :reasoning_end_t, :stream_end_t, :duration
@@ -37,10 +42,20 @@ module TokenReel
       @reasoning_interval = config.reasoning_tps.to_f.positive? ? 1.0 / config.reasoning_tps : 1.0 / config.tps
       @response_interval = 1.0 / config.tps
 
-      @prompt_done_t = @prompt_interval * prompt_tokens.size
+      @rng = config.variability ? Random.new(config.seed || Random.new_seed) : nil
+
+      # Cumulative reveal times per token: offsets[n] is the moment the
+      # n-th token has fully appeared. With variability off this is just
+      # n * interval; with it on, each step is independently jittered,
+      # so the array can't be derived by a plain multiply anymore.
+      @prompt_offsets = cumulative_offsets(prompt_tokens.size, @prompt_interval)
+      @reasoning_offsets = cumulative_offsets(reasoning_tokens.size, @reasoning_interval)
+      @response_offsets = cumulative_offsets(response_tokens.size, @response_interval)
+
+      @prompt_done_t = @prompt_offsets.last
       @thinking_end_t = prompt_done_t + config.ttft.to_f
-      @reasoning_end_t = thinking_end_t + @reasoning_interval * reasoning_tokens.size
-      @stream_end_t = reasoning_end_t + @response_interval * response_tokens.size
+      @reasoning_end_t = thinking_end_t + @reasoning_offsets.last
+      @stream_end_t = reasoning_end_t + @response_offsets.last
       @duration = stream_end_t + config.hold.to_f
     end
 
@@ -48,7 +63,7 @@ module TokenReel
       t = t.clamp(0, duration)
 
       if t < prompt_done_t
-        n = @prompt_interval.positive? ? (t / @prompt_interval).floor : prompt_tokens.size
+        n = @prompt_interval.positive? ? tokens_shown(@prompt_offsets, t) : prompt_tokens.size
         State.new(
           phase: :typing_prompt,
           prompt_text: prompt_tokens[0...n].join,
@@ -69,7 +84,7 @@ module TokenReel
         )
       elsif t < reasoning_end_t
         elapsed = t - thinking_end_t
-        n = @reasoning_interval.positive? ? (elapsed / @reasoning_interval).floor : reasoning_tokens.size
+        n = @reasoning_interval.positive? ? tokens_shown(@reasoning_offsets, elapsed) : reasoning_tokens.size
         n = n.clamp(0, reasoning_tokens.size)
         State.new(
           phase: :reasoning,
@@ -81,7 +96,7 @@ module TokenReel
         )
       else
         elapsed = t - reasoning_end_t
-        n = @response_interval.positive? ? (elapsed / @response_interval).floor : response_tokens.size
+        n = @response_interval.positive? ? tokens_shown(@response_offsets, elapsed) : response_tokens.size
         n = n.clamp(0, response_tokens.size)
         done = n >= response_tokens.size
         State.new(
@@ -113,6 +128,39 @@ module TokenReel
 
     private
 
+    # Builds the cumulative reveal-time array for `count` tokens spaced
+    # `interval` seconds apart: offsets[0] == 0, offsets[count] == the
+    # total time to reveal them all. With no RNG (variability off) each
+    # step is exactly `interval`, matching the un-jittered timeline
+    # exactly; with one, each step is independently perturbed.
+    def cumulative_offsets(count, interval)
+      offsets = [0.0]
+      count.times { offsets << offsets.last + jittered_delay(interval) }
+      offsets
+    end
+
+    def jittered_delay(interval)
+      return interval unless @rng
+
+      pct = JITTER_PCTS.sample(random: @rng)
+      z = normal_sample.clamp(-1.0, 1.0) # keep the (rare) normal-curve tail within the chosen bound
+      [interval * (1.0 + z * pct), 0.0].max
+    end
+
+    # Standard normal sample (mean 0, stddev 1) via the Box-Muller transform.
+    def normal_sample
+      u1 = 1.0 - @rng.rand # (0, 1], avoids log(0)
+      u2 = @rng.rand
+      Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2 * Math::PI * u2)
+    end
+
+    # Number of tokens fully revealed by `elapsed`, given their
+    # cumulative reveal-time array (size == token count + 1).
+    def tokens_shown(offsets, elapsed)
+      idx = offsets.bsearch_index { |offset| offset > elapsed }
+      idx.nil? ? offsets.size - 1 : idx - 1
+    end
+
     def blink_on?(t)
       (t * (2 * BLINK_HZ)).to_i.even?
     end

data/lib/token_reel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TokenReel
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: token_reel
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Thomas Powell
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -53,6 +52,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
+- ".github/workflows/version-bump.yml"
 - ".gitignore"
 - Gemfile
 - README.md
@@ -79,7 +80,6 @@ licenses:
 metadata:
   homepage_uri: https://github.com/stringsn88keys/token_reel
   source_code_uri: https://github.com/stringsn88keys/token_reel
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -94,8 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Render terminal-style GIFs of an LLM prompt/response, streamed at a chosen
   tokens/sec and time-to-first-token