llm_cassette 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bcde9366222cf40c75db3288557afc756c0e8d36f9a98fa2d8c538a57351f734
+  data.tar.gz: ffcba7b15bf3c5dc5e358def22da27bdf2985593120c1f92897f6057295d5e96
+SHA512:
+  metadata.gz: d7dad527e4d7f8084f0c98a8d0ef5db8d406d6f7b972223d2cf61a5af8b2c628697c2ce05be2e4c9a4754267bc55210e66dbe1f41f4b3fcb87b0711bc48e9596
+  data.tar.gz: 6b7b76e152aecfdd2659390b60907863727b6b2f78c9db2aa61da428bdd90e6489c8b690682eb900b001c29dd6766add168322f10f73c6a8f77825b89bd7e28a

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,91 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  Exclude:
+    - "bin/**/*"
+    - "vendor/**/*"
+    - "pkg/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - "spec/**/*"
+
+Metrics/ClassLength:
+  Max: 150
+
+Style/Documentation:
+  Enabled: false
+
+Naming/MethodParameterName:
+  MinNameLength: 1
+
+Naming/PredicateMethod:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/IdenticalEqualityAssertion:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+Style/OpenStructUse:
+  Exclude:
+    - "spec/**/*"
+
+Lint/FloatComparison:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 35
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+Metrics/ParameterLists:
+  Max: 7
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/llm_cassette/rspec_helpers_spec.rb"
+
+RSpec/MultipleDescribes:
+  Exclude:
+    - "spec/llm_cassette/rspec_helpers_spec.rb"
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+Lint/EmptyBlock:
+  Exclude:
+    - "spec/**/*"

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-09
+
+### Added
+
+- `LlmCassette::Middleware` Faraday middleware — intercepts LLM HTTP requests, routes to recorder or replayer based on active cassette and record mode.
+- `LlmCassette::Cassette` — loads and saves `.yml` cassette files. Sequential interaction replay via internal index pointer. Creates intermediate directories on save.
+- `LlmCassette::Interaction` — value object for a single request+response pair. Handles streaming (SSE chunk array + offsets) and non-streaming (raw body) response shapes.
+- `LlmCassette::Recorder` — wraps Faraday's `on_data` callback to capture SSE chunks with wall-clock offsets. Falls back to capturing response body for non-streaming calls.
+- `LlmCassette::Replayer` — replays non-streaming responses as a fake `Faraday::Response`. For streaming, emits recorded chunks via the caller's `on_data` proc. Optional timing replay via `replay_timing` config flag.
+- `LlmCassette::RequestSignature` — normalizes request method, URI, and JSON body (sorted keys) for cassette storage and debugging.
+- Record modes: `:none` (replay only — raises `CassetteNotFoundError` if cassette missing) and `:all` (always re-record, hits real API).
+- Token usage extraction — best-effort parsing from response body (non-streaming) or last SSE chunk containing `usage` (streaming). Stored per interaction under `response.usage`.
+- `LlmCassette.use_cassette("name") { }` block API — sets and clears thread-local cassette, ensures `eject!` even on exception.
+- `LlmCassette::RSpec::Helpers` — `use_llm_cassette "name"` class macro wraps every example in the group via `around`. Auto-derives cassette name from example description when called without arguments.
+- RSpec metadata form — `it "...", llm_cassette: "name"` and `it "...", llm_cassette: true` (auto-name). Enabled via `require "llm_cassette/rspec"`.
+- `LlmCassette::CassetteNotFoundError` — raised when cassette file is missing in `:none` mode.
+- `LlmCassette::NoMoreInteractionsError` — raised when a cassette is exhausted and another request is made.
+- Works with OpenAI and Anthropic out of the box — provider-agnostic at the Faraday layer; usage extraction handles both `prompt_tokens`/`completion_tokens` (OpenAI) and `input_tokens`/`output_tokens` (Anthropic) field names.

data/README.md

@@ -0,0 +1,267 @@
+# llm_cassette
+
+**VCR for LLMs — streaming-aware. Record once, replay fast, never hit the API in CI.**
+
+[![CI](https://github.com/jibranusman95/llm_cassette/actions/workflows/ci.yml/badge.svg)](https://github.com/jibranusman95/llm_cassette/actions)
+[![Gem Version](https://badge.fury.io/rb/llm_cassette.svg)](https://badge.fury.io/rb/llm_cassette)
+[![Downloads](https://img.shields.io/gem/dt/llm_cassette)](https://rubygems.org/gems/llm_cassette)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+Every Ruby team shipping LLM features ends up with the same problem:
+
+```ruby
+# spec/services/chat_service_spec.rb
+it "returns a greeting" do
+  # VCR records raw bytes — replays the entire SSE response as one blob.
+  # Incremental stream processing breaks. Token counts are lost.
+  # Cassettes bust on every prompt tweak.
+  VCR.use_cassette("greeting") do
+    result = ChatService.call("say hello")
+    expect(result).to include("Hello")
+  end
+end
+```
+
+VCR records raw HTTP bytes. For SSE streaming it replays them all at once — your `on_data` callback fires once instead of chunk-by-chunk. Incremental stream rendering breaks. Token costs vanish. Cassettes bust on any prompt change.
+
+Here's the same test with llm_cassette:
+
+```ruby
+it "returns a greeting" do
+  LlmCassette.use_cassette("greeting") do
+    result = ChatService.call("say hello")
+    expect(result).to include("Hello")
+  end
+end
+```
+
+Chunks replay in order via `on_data`. Token usage is stored per cassette. Cassettes are human-readable YAML. Works with OpenAI, Anthropic, or any Faraday-based LLM client.
+
+---
+
+## What you get
+
+**Streaming-aware replay** — records SSE chunks as an ordered sequence with wall-clock offsets. Replays them via `on_data` exactly as the real API would, so incremental stream processing works correctly in tests.
+
+**Works without configuration** — hooks into Faraday, which both [ruby_llm](https://github.com/crmne/ruby_llm) and [llm.rb](https://github.com/kieranklaassen/llm.rb) use internally. One middleware insert and you're done.
+
+**Token usage stored per interaction** — `response.usage.prompt_tokens`, `completion_tokens`, `total_tokens` stored in every cassette. Supports both OpenAI and Anthropic field names.
+
+**Human-readable cassettes** — plain YAML files you can read, edit, and commit. One file per cassette, multiple interactions per file.
+
+**RSpec helpers** — class-level `use_llm_cassette`, inline block form, and RSpec metadata — three ergonomic styles for three different situations.
+
+---
+
+## Install
+
+```ruby
+# Gemfile
+gem "llm_cassette"
+```
+
+Add the middleware to your Faraday connection:
+
+```ruby
+# config/initializers/faraday.rb  (or wherever you build your connection)
+Faraday.default_connection_options.builder_middlewares.unshift(LlmCassette::Middleware)
+
+# Or on a specific connection:
+conn = Faraday.new do |f|
+  f.use LlmCassette::Middleware
+  f.adapter Faraday.default_adapter
+end
+```
+
+---
+
+## Configuration
+
+```ruby
+# spec/support/llm_cassette.rb
+require "llm_cassette/rspec"
+
+LlmCassette.configure do |config|
+  config.cassette_directory = Rails.root.join("spec/llm_cassettes").to_s
+
+  # :none  — replay only. Raises CassetteNotFoundError if cassette missing (default, good for CI).
+  # :all   — always hit the real API and re-record.
+  config.record = ENV["LLM_RECORD"] ? :all : :none
+
+  # Replay chunks with the original timing delays (default: false — fast CI).
+  config.replay_timing = false
+end
+```
+
+---
+
+## Usage
+
+### Block form
+
+```ruby
+LlmCassette.use_cassette("chat_greeting") do
+  response = client.chat(messages: [{ role: "user", content: "say hello" }])
+  expect(response.content).to include("Hello")
+end
+```
+
+### Class-level helper (wraps every example in the group)
+
+```ruby
+RSpec.describe ChatService do
+  use_llm_cassette "chat_service"
+
+  it "returns a greeting" do
+    expect(ChatService.call("say hello")).to include("Hello")
+  end
+
+  it "handles follow-ups" do
+    # same cassette, second interaction consumed sequentially
+    expect(ChatService.call("now say goodbye")).to include("Goodbye")
+  end
+end
+```
+
+Omit the name to auto-derive it from the example group description:
+
+```ruby
+RSpec.describe ChatService do
+  use_llm_cassette  # cassette name: "chatservice"
+
+  it "..." { ... }
+end
+```
+
+### RSpec metadata
+
+```ruby
+it "greets the user", llm_cassette: "greeting" do
+  expect(ChatService.call("hi")).to include("Hello")
+end
+
+# Auto-name from example description:
+it "greets the user", llm_cassette: true do
+  expect(ChatService.call("hi")).to include("Hello")
+end
+```
+
+---
+
+## Recording cassettes
+
+Set `record: :all` to hit the real API and write cassette files:
+
+```bash
+LLM_RECORD=1 bundle exec rspec spec/services/chat_service_spec.rb
+```
+
+Then commit the cassette files and run with `record: :none` in CI.
+
+To re-record a single cassette, delete its file and run with `LLM_RECORD=1` again.
+
+---
+
+## Cassette format
+
+Cassettes are plain YAML — readable, diffable, and editable by hand:
+
+```yaml
+---
+llm_cassette_version: "1"
+recorded_at: "2026-06-09T12:00:00Z"
+interactions:
+  - request:
+      method: post
+      uri: "https://api.openai.com/v1/chat/completions"
+      body: '{"messages":[{"role":"user","content":"say hello"}],"model":"gpt-4o","stream":true}'
+    response:
+      status: 200
+      headers:
+        content-type: "text/event-stream; charset=utf-8"
+      streaming: true
+      chunks:
+        - data: "data: {\"choices\":[{\"delta\":{\"content\":\"Hello\"}}]}\n\n"
+          offset: 0.0
+        - data: "data: {\"choices\":[{\"delta\":{\"content\":\" world!\"}}],\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":2,\"total_tokens\":12}}\n\n"
+          offset: 0.134
+        - data: "data: [DONE]\n\n"
+          offset: 0.187
+      usage:
+        prompt_tokens: 10
+        completion_tokens: 2
+        total_tokens: 12
+```
+
+Multiple interactions in one cassette are replayed sequentially — first request gets `interactions[0]`, second gets `interactions[1]`, and so on.
+
+---
+
+## How streaming replay works
+
+VCR captures raw HTTP bytes and writes them to a cassette. When it replays a streaming response, it returns the entire body at once — your `on_data` callback fires once with all the bytes. Any code that renders output incrementally as chunks arrive breaks silently.
+
+llm_cassette records each SSE chunk separately as it arrives from `on_data`, along with its wall-clock offset from the start of the request. On replay, it calls your `on_data` proc with each chunk in sequence. The stream arrives the same way it would from the real API.
+
+```
+Real API:     on_data("data: Hello\n\n")  →  on_data("data:  world\n\n")  →  on_data("data: [DONE]\n\n")
+VCR replay:   on_data("data: Hello\n\ndata:  world\n\ndata: [DONE]\n\n")   ← one call, breaks incremental rendering
+llm_cassette: on_data("data: Hello\n\n")  →  on_data("data:  world\n\n")  →  on_data("data: [DONE]\n\n")
+```
+
+Enable `replay_timing: true` to also replay the inter-chunk delays for timing-sensitive tests.
+
+---
+
+## Why not VCR?
+
+[vcr](https://github.com/vcr/vcr) is excellent for REST APIs — 156M downloads and well-maintained. For LLM calls specifically:
+
+| | VCR | llm_cassette |
+|---|---|---|
+| SSE streaming replay | Blob — one `on_data` call | Sequential chunks via `on_data` |
+| Token usage | Not captured | Stored per interaction |
+| Cassette format | Marshal / YAML of raw bytes | Human-readable YAML |
+| Provider knowledge | None | Extracts usage from OpenAI + Anthropic chunk formats |
+
+If you're not using streaming and don't need token tracking, VCR works fine. llm_cassette is for teams where streaming is the default.
+
+---
+
+## Requirements
+
+- Ruby >= 3.2
+- Faraday >= 1.0
+
+No Rails dependency. Works with any Ruby HTTP stack that uses Faraday.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/jibranusman95/llm_cassette
+cd llm_cassette
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+---
+
+## From the same author
+
+| Gem | What it does |
+|-----|-------------|
+| [webhook_inbox](https://github.com/jibranusman95/webhook_inbox) | Transactional inbox for Rails webhook receivers — dedup, async processing, replay, dashboard |
+| [turbo_presence](https://github.com/jibranusman95/turbo_presence) | Figma-style live cursors, avatar stacks, and typing indicators for Rails — one line |
+| [promptscrub](https://github.com/jibranusman95/promptscrub) | PII redaction middleware for LLM calls |
+| [http_decoy](https://github.com/jibranusman95/http_decoy) | A real Rack server that runs inside your RSpec tests — test HTTP contracts, not stubs |
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/llm_cassette/cassette.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "time"
+
+module LlmCassette
+  class Cassette
+    attr_reader :name
+
+    def initialize(name, record: nil)
+      @name = name.to_s
+      @record_mode = (record || LlmCassette.configuration.record).to_sym
+      @interactions = []
+      @replay_index = 0
+
+      return if record?
+      unless file_exists?
+        raise CassetteNotFoundError, "Cassette '#{name}' not found at #{path}. " \
+                                     "Re-run with record: :all to record it."
+      end
+      load!
+    end
+
+    def record?
+      @record_mode == :all
+    end
+
+    def next_interaction
+      interaction = @interactions[@replay_index]
+      @replay_index += 1
+
+      unless interaction
+        raise NoMoreInteractionsError,
+              "No more interactions in cassette '#{name}'. " \
+              "Expected interaction ##{@replay_index} but cassette has #{@interactions.size}."
+      end
+
+      interaction
+    end
+
+    def record_interaction(interaction)
+      @interactions << interaction
+    end
+
+    def eject!
+      save! if record?
+    end
+
+    def size
+      @interactions.size
+    end
+
+    private
+
+    def path
+      dir = LlmCassette.configuration.cassette_directory
+      File.join(dir, "#{name}.yml")
+    end
+
+    def file_exists?
+      File.exist?(path)
+    end
+
+    def load!
+      data = YAML.safe_load_file(path, permitted_classes: [Symbol])
+      @interactions = (data["interactions"] || []).map { |i| Interaction.from_hash(i) }
+    end
+
+    def save!
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, YAML.dump(to_h))
+    end
+
+    def to_h
+      {
+        "llm_cassette_version" => "1",
+        "recorded_at" => Time.now.utc.iso8601,
+        "interactions" => @interactions.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/llm_cassette/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module LlmCassette
+  class Configuration
+    RECORD_MODES = %i[none all].freeze
+
+    attr_reader :record
+    attr_accessor :cassette_directory, :replay_timing
+
+    def initialize
+      @cassette_directory = "spec/llm_cassettes"
+      @record = :none
+      @replay_timing = false
+    end
+
+    def record=(mode)
+      unless RECORD_MODES.include?(mode.to_sym)
+        raise ArgumentError, "Invalid record mode: #{mode}. Must be one of: #{RECORD_MODES.join(', ')}"
+      end
+
+      @record = mode.to_sym
+    end
+  end
+end

data/lib/llm_cassette/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LlmCassette
+  class Error < StandardError; end
+  class CassetteNotFoundError < Error; end
+  class NoMoreInteractionsError < Error; end
+end

data/lib/llm_cassette/interaction.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LlmCassette
+  class Interaction
+    attr_reader :request, :response
+
+    def initialize(request:, response:)
+      @request = request
+      @response = response
+    end
+
+    def self.from_recording(env:, response:, streaming:, chunks:, request_body:)
+      req = {
+        "method" => env.method.to_s.downcase,
+        "uri" => env.url.to_s,
+        "body" => request_body
+      }
+
+      res = build_response_hash(response, streaming, chunks)
+
+      new(request: req, response: res)
+    end
+
+    def self.from_hash(hash)
+      new(request: hash["request"], response: hash["response"])
+    end
+
+    def to_h
+      { "request" => request, "response" => response }
+    end
+
+    def streaming?
+      response["streaming"] == true
+    end
+
+    class << self
+      private
+
+      def build_response_hash(response, streaming, chunks)
+        res = {
+          "status" => response.status,
+          "headers" => normalize_headers(response.headers),
+          "streaming" => streaming
+        }
+
+        if streaming
+          serialized = chunks.map { |c| { "data" => c[:data], "offset" => c[:offset] } }
+          res["chunks"] = serialized
+          res["usage"] = extract_usage_from_chunks(chunks)
+        else
+          res["body"] = response.body.to_s
+          res["usage"] = extract_usage_from_body(response.body)
+        end
+
+        res
+      end
+
+      def normalize_headers(headers)
+        return {} unless headers
+
+        headers.each_with_object({}) { |(k, v), h| h[k.to_s.downcase] = v }
+      end
+
+      def extract_usage_from_body(body)
+        return nil unless body&.length&.positive?
+
+        parsed = JSON.parse(body)
+        usage = parsed["usage"]
+        return nil unless usage
+
+        build_usage_hash(usage)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def extract_usage_from_chunks(chunks)
+        chunks.reverse_each do |chunk|
+          data = chunk[:data].to_s
+          next unless data.start_with?("data: ")
+
+          json_str = data.sub(/\Adata: /, "").strip
+          next if json_str == "[DONE]"
+
+          parsed = JSON.parse(json_str)
+          usage = parsed["usage"]
+          next unless usage
+
+          return build_usage_hash(usage)
+        rescue JSON::ParserError
+          next
+        end
+        nil
+      end
+
+      def build_usage_hash(usage)
+        {
+          "prompt_tokens" => usage["prompt_tokens"] || usage["input_tokens"],
+          "completion_tokens" => usage["completion_tokens"] || usage["output_tokens"],
+          "total_tokens" => usage["total_tokens"]
+        }.compact
+      end
+    end
+  end
+end

data/lib/llm_cassette/middleware.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module LlmCassette
+  class Middleware < Faraday::Middleware
+    def call(env)
+      cassette = LlmCassette.current_cassette
+      return app.call(env) unless cassette
+
+      if cassette.record?
+        Recorder.new(env, app, cassette).call
+      else
+        interaction = cassette.next_interaction
+        Replayer.new(env, interaction).call
+      end
+    end
+  end
+end

data/lib/llm_cassette/recorder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module LlmCassette
+  class Recorder
+    def initialize(env, app, cassette)
+      @env = env
+      @app = app
+      @cassette = cassette
+    end
+
+    def call
+      request_body = @env.body.dup.to_s
+      streaming = !@env.request.on_data.nil?
+      chunks = intercept_streaming([], streaming)
+      response = @app.call(@env)
+      record(request_body, streaming, chunks, response)
+      response
+    end
+
+    private
+
+    def intercept_streaming(chunks, streaming)
+      return chunks unless streaming
+
+      original = @env.request.on_data
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @env.request.on_data = proc do |chunk, bytes|
+        offset = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start).round(4)
+        chunks << { data: chunk, offset: offset }
+        original.call(chunk, bytes)
+      end
+      chunks
+    end
+
+    def record(request_body, streaming, chunks, response)
+      interaction = Interaction.from_recording(
+        env: @env,
+        response: response,
+        streaming: streaming,
+        chunks: chunks,
+        request_body: request_body
+      )
+      @cassette.record_interaction(interaction)
+    end
+  end
+end

data/lib/llm_cassette/replayer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module LlmCassette
+  class Replayer
+    def initialize(env, interaction)
+      @env = env
+      @interaction = interaction
+    end
+
+    def call
+      if @interaction.streaming?
+        replay_streaming
+      else
+        replay_non_streaming
+      end
+    end
+
+    private
+
+    def replay_streaming
+      on_data = @env.request.on_data
+      chunks = @interaction.response["chunks"] || []
+
+      chunks.each do |chunk|
+        data = chunk["data"].to_s
+        sleep(chunk["offset"].to_f) if LlmCassette.configuration.replay_timing && chunk["offset"].to_f.positive?
+        on_data&.call(data, data.bytesize)
+      end
+
+      build_response(
+        status: @interaction.response["status"],
+        headers: @interaction.response["headers"],
+        body: chunks.map { |c| c["data"].to_s }.join
+      )
+    end
+
+    def replay_non_streaming
+      build_response(
+        status: @interaction.response["status"],
+        headers: @interaction.response["headers"],
+        body: @interaction.response["body"].to_s
+      )
+    end
+
+    def build_response(status:, headers:, body:)
+      env = @env.dup
+      env.status = status.to_i
+      env.response_headers = Faraday::Utils::Headers.new(headers || {})
+      env.body = body
+      Faraday::Response.new(env)
+    end
+  end
+end

data/lib/llm_cassette/request_signature.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LlmCassette
+  class RequestSignature
+    attr_reader :method, :uri, :body
+
+    def initialize(env)
+      @method = env.method.to_s.downcase
+      @uri = env.url.to_s
+      @body = normalize_body(env.body)
+    end
+
+    private
+
+    def normalize_body(body)
+      return nil unless body&.length&.positive?
+
+      parsed = JSON.parse(body)
+      JSON.generate(sort_hash(parsed))
+    rescue JSON::ParserError
+      body.to_s
+    end
+
+    def sort_hash(obj)
+      case obj
+      when Hash then obj.sort.to_h.transform_values { |v| sort_hash(v) }
+      when Array then obj.map { |v| sort_hash(v) }
+      else obj
+      end
+    end
+  end
+end

data/lib/llm_cassette/rspec/helpers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module LlmCassette
+  module RSpec
+    module Helpers
+      # Class-level helper — wraps every example in the group with a cassette.
+      #
+      #   describe MyService do
+      #     use_llm_cassette "my_service"
+      #     it "..." { ... }
+      #   end
+      #
+      # Omit the name to auto-derive it from the example group description.
+      def use_llm_cassette(name = nil, **options)
+        around do |example|
+          cassette_name = name || example.metadata[:full_description]
+                                         .gsub(%r{[^a-zA-Z0-9_\-/]}, "_")
+                                         .squeeze("_")
+                                         .downcase
+          LlmCassette.use_cassette(cassette_name, **options) { example.run }
+        end
+      end
+    end
+  end
+end

data/lib/llm_cassette/rspec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "llm_cassette"
+require "llm_cassette/rspec/helpers"
+
+RSpec.configure do |config|
+  config.extend LlmCassette::RSpec::Helpers
+
+  # Metadata form:
+  #   it "...", llm_cassette: "name" do ... end
+  #   it "...", llm_cassette: true do ... end  # auto-name
+  config.around(:each, :llm_cassette) do |example|
+    raw = example.metadata[:llm_cassette]
+    name = if raw == true
+             example.metadata[:full_description]
+                    .gsub(%r{[^a-zA-Z0-9_\-/]}, "_")
+                    .squeeze("_")
+                    .downcase
+           else
+             raw.to_s
+           end
+    LlmCassette.use_cassette(name) { example.run }
+  end
+end

data/lib/llm_cassette/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LlmCassette
+  VERSION = "0.1.0"
+end

data/lib/llm_cassette.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "llm_cassette/version"
+require_relative "llm_cassette/errors"
+require_relative "llm_cassette/configuration"
+require_relative "llm_cassette/interaction"
+require_relative "llm_cassette/request_signature"
+require_relative "llm_cassette/cassette"
+require_relative "llm_cassette/recorder"
+require_relative "llm_cassette/replayer"
+require_relative "llm_cassette/middleware"
+
+module LlmCassette
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset!
+      @configuration = nil
+    end
+
+    def current_cassette
+      Thread.current[:llm_cassette_current]
+    end
+
+    # Block form — wraps a block with an active cassette.
+    #
+    #   LlmCassette.use_cassette("greeting") do
+    #     response = client.chat("say hello")
+    #   end
+    #
+    # Options:
+    #   record: :none (default) — replay only, raise if cassette missing
+    #   record: :all            — always record (hits real API)
+    def use_cassette(name, record: nil, &block)
+      cassette = Cassette.new(name, record: record)
+      Thread.current[:llm_cassette_current] = cassette
+      begin
+        block.call(cassette)
+      ensure
+        cassette.eject!
+        Thread.current[:llm_cassette_current] = nil
+      end
+    end
+  end
+end

data/sig/llm_cassette.rbs

@@ -0,0 +1,79 @@
+module LlmCassette
+  VERSION: String
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+  def self.reset!: () -> nil
+  def self.current_cassette: () -> Cassette?
+  def self.use_cassette: (String name, ?record: Symbol?) { (Cassette) -> void } -> void
+
+  class Error < StandardError
+  end
+
+  class CassetteNotFoundError < Error
+  end
+
+  class NoMoreInteractionsError < Error
+  end
+
+  class Configuration
+    RECORD_MODES: Array[Symbol]
+
+    attr_accessor cassette_directory: String
+    attr_reader record: Symbol
+    attr_accessor replay_timing: bool
+
+    def initialize: () -> void
+    def record=: (Symbol | String mode) -> Symbol
+  end
+
+  class Interaction
+    attr_reader request: Hash[String, untyped]
+    attr_reader response: Hash[String, untyped]
+
+    def initialize: (request: Hash[String, untyped], response: Hash[String, untyped]) -> void
+    def self.from_recording: (env: untyped, response: untyped, streaming: bool, chunks: Array[Hash[Symbol, untyped]], request_body: String?) -> Interaction
+    def self.from_hash: (Hash[String, untyped] hash) -> Interaction
+    def to_h: () -> Hash[String, untyped]
+    def streaming?: () -> bool
+  end
+
+  class RequestSignature
+    attr_reader method: String
+    attr_reader uri: String
+    attr_reader body: String?
+
+    def initialize: (untyped env) -> void
+  end
+
+  class Cassette
+    attr_reader name: String
+
+    def initialize: (String name, ?record: Symbol?) -> void
+    def record?: () -> bool
+    def next_interaction: () -> Interaction
+    def record_interaction: (Interaction interaction) -> void
+    def eject!: () -> void
+    def size: () -> Integer
+  end
+
+  class Recorder
+    def initialize: (untyped env, untyped app, Cassette cassette) -> void
+    def call: () -> untyped
+  end
+
+  class Replayer
+    def initialize: (untyped env, Interaction interaction) -> void
+    def call: () -> untyped
+  end
+
+  class Middleware < Faraday::Middleware
+    def call: (untyped env) -> untyped
+  end
+
+  module RSpec
+    module Helpers
+      def use_llm_cassette: (?String? name, **untyped options) -> void
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: llm_cassette
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jibran Usman
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |-
+  VCR for LLMs. Hooks into Faraday (used by ruby_llm, llm.rb, and most OpenAI/Anthropic clients),
+  records SSE chunks with timing, and replays them correctly. Exact-match cassettes, RSpec helpers,
+  token usage stored per interaction. Works with OpenAI and Anthropic out of the box.
+email:
+- jibran.usman@eunasolutions.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/llm_cassette.rb
+- lib/llm_cassette/cassette.rb
+- lib/llm_cassette/configuration.rb
+- lib/llm_cassette/errors.rb
+- lib/llm_cassette/interaction.rb
+- lib/llm_cassette/middleware.rb
+- lib/llm_cassette/recorder.rb
+- lib/llm_cassette/replayer.rb
+- lib/llm_cassette/request_signature.rb
+- lib/llm_cassette/rspec.rb
+- lib/llm_cassette/rspec/helpers.rb
+- lib/llm_cassette/version.rb
+- sig/llm_cassette.rbs
+homepage: https://github.com/jibranusman95/llm_cassette
+licenses: []
+metadata:
+  homepage_uri: https://github.com/jibranusman95/llm_cassette
+  source_code_uri: https://github.com/jibranusman95/llm_cassette
+  changelog_uri: https://github.com/jibranusman95/llm_cassette/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Streaming-aware cassette recorder for LLM calls — record once, replay fast,
+  never hit the API in CI.
+test_files: []