deja 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c773af63e95adbc7d09f0cd1f3df714e567da9c4abb03803e58d4ae008f9c7f1
+  data.tar.gz: '089eccd51f378482ffdd83c97b53e7d2a45712aadf7f42385d03045256a2484f'
+SHA512:
+  metadata.gz: 1e91bb15c14bcad87e0ddf77b32c6e77a6cae4313f31b2b212c9669f6c7b3fe626a852beac89f723d4ea0e67ef2e2fe79c5c22960dd9fb2e261077d214d32912
+  data.tar.gz: d110bdee9a51d74de91ccef37be10ea86de0863ce0d68b66bc2b1f30d332e3534b5288a47647066192721f7de1026de6c95dd188acbc70f04fde01029cf66c01

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-06-19
+
+### Added
+- Initial extraction from the Forge test suite.
+- `use_llm_cache(id)` — record/replay Anthropic `messages.create` and
+  `messages.stream` calls to a per-test YAML file.
+- `expect_llm_called` and `forbid_calls` helpers.
+- `cached_llm_value(id, *path)` reader.
+- `meet_requirements(text)` matcher — judge a value against free-text
+  requirements once, then cache the verdict.
+- Pluggable provider adapters (`Deja::Adapters::Base`), so a suite can mix
+  providers. Ships `:anthropic`. `use_llm_cache` installs every registered
+  adapter; cache entries are tagged with `provider:`.
+- `Deja.configure` with `cache_root`, `register(provider, install:, real_client:)`,
+  a dedicated `judge_client`, and judge model/prompt settings.
+- Anthropic SDK response structs + serialize/deserialize extracted into the
+  `llm_mock_anthropic` gem (on the shared `llm_mock` contract); the Anthropic
+  adapter now delegates to it. `Deja::Anthropic::*` is removed — use
+  `LlmMock::Anthropic::*` for canned responses.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate Brustein
+
+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,226 @@
+# Deja
+
+Deja is a testing toolkit for code that calls LLM apis. Your tests make real calls to real LLMs, so you can confirm the model actually gives the results you expect — you're checking genuine model behavior, not a stub you wrote. To keep that fast and repeatable, Deja records each real call once and replays it from a cache on every later run, so your suite stays deterministic and free to run in CI.
+
+## Overview
+
+### What Deja allows
+
+Deja allows you to add the following coverage to your test.
+
+  * I have application code that generates arguments for an LLM api. I want to assert on the arguments that were provided to the LLM api.
+  * When I pass certain arguments (i.e. a certain prompt) to an LLM, the result is non-deterministic. Even so, I have certain requirements
+    as to what the result should be. I want to assert that the LLM's response meets those requirements.
+
+With this functionality, you can do the following.
+
+  * I want to change my code and be sure that the changes I made did not affect the arguments passed to the LLM api.
+  * I want to iterate on my application code in ways that will change a prompt sent to an LLM until the response meets certain requirements.
+  * I want to change my code in a way that will change a prompt sent to an LLM and be sure that the response still meets existing requirements.
+  * I want to upgrade to a new model and be sure that all of my existing calls still meet existing requirements.
+
+### How Deja works
+
+  1. You run a test locally with ALLOW_LLM_CALL=1.
+    * When your test hits application code that triggers a call to an LLM api, the call is actually made via http.
+    * You assert on the arguments that were sent to the LLM api
+    * You assert in a fuzzy way on the response, like "The response should say that..."
+    * Deja caches the response, keyed off of the exact set of arguments. The cached response is stored in a generated file, which
+      you store in version control.
+  2. You run the test again
+    * When the LLM api call is triggered, the test finds the response in the cache, skipping the http call to the LLM api
+    * Your assertions ensure that your code still sent the expected arguments
+  3. You push your code and tests run on CI
+    * Since the cached response is stored in version control, CI has access to it and runs the test without making any
+      actual LLM calls
+  4. You update code and re-run the test locally with ALLOW_LLM_CALL=1.
+    * The updated code can change the prompt, the LLM model, or anything else that will change the arguments sent to the LLM api.
+    * Since there is no cached response for the new arguments, the call to the LLM api is actually made via http.
+    * The new response is cached, replacing the old one
+    * Your fuzzy assertion ensures that the new response still matches your requirements.
+
+### LLM support
+
+Today Deja targets the [Anthropic](https://github.com/anthropics/anthropic-sdk-ruby) SDK. Support for other SDKs is coming.
+
+The Anthropic-specific bits — the response value objects and the
+serialize/deserialize that backs the cache — live in a separate gem,
+[`llm_mock_anthropic`](https://github.com/nbrustein/llm_mock_anthropic) (built on
+the shared [`llm_mock`](https://github.com/nbrustein/llm_mock) contract). Deja
+pulls it in automatically. If a test stubs the Anthropic client directly (rather
+than recording/replaying), use that gem's builders — e.g.
+`LlmMock::Anthropic.message([...])` — to construct canned responses.
+
+## Usage
+
+### Installation
+
+```ruby
+# Gemfile
+group :test do
+  gem "deja"
+end
+```
+
+### Setup
+
+Require the RSpec integration, point Deja at a cache directory, and register a
+provider — telling it how to swap your app's client for Deja's caching stub:
+
+```ruby
+# spec/support/deja.rb (or spec/rails_helper.rb)
+require "deja/rspec"
+
+Deja.configure do |c|
+  # Whatever your app calls to get an Anthropic client. Deja hands you its
+  # caching stub; you return it from that accessor for the duration of the test.
+  c.register :anthropic,
+    install: ->(mock_anthropic_client) { allow(AnthropicClient).to receive(:client).and_return(mock_anthropic_client) }
+
+  # Required only if you use the `meet_requirements` matcher: the client Deja
+  # uses to judge a value against its requirements. Deja picks provider-specific
+  # defaults from the client's type (Anthropic is built in).
+  c.judge_client { Anthropic::Client.new }
+
+  # Optional: override the judge's defaults (model, max_tokens, system prompt) or
+  # pass provider-specific args. These are merged into the judge's
+  # messages.create call over its built-in defaults.
+  c.judge_attrs = { model: "claude-sonnet-4-5" }
+end
+```
+
+Recorded cache files go under `spec/support/deja_cache` by default. To put them
+somewhere else, set `cache_root` (a String or Pathname, resolved under your
+project root):
+
+```ruby
+Deja.configure { |c| c.cache_root = Rails.root.join("spec/support/cache") }
+```
+
+That assumes your app funnels LLM access through a single seam. e.g., In this example,
+Deja will mock out calls to `AnthropicClient.client`:
+
+```ruby
+class AnthropicClient
+  def self.client
+    Anthropic::Client.new
+  end
+end
+```
+
+
+**Optional:** Deja doesn't require WebMock — it intercepts calls at the client
+seam, not at the HTTP layer. But if your suite already uses WebMock, allow the
+Anthropic host so recording can reach it (and keep the allowlist tight so a
+forgotten stub surfaces as a blocked request rather than a silent live call):
+
+```ruby
+WebMock.disable_net_connect!(allow_localhost: true, allow: ["api.anthropic.com"])
+```
+
+## Assert on LLM api arguments and response
+
+```ruby
+it "summarizes an article" do
+  use_llm_cache("2026-04-30_17-03") # one cache file for this test
+
+  summary = ArticleSummarizer.new(article).call # makes LLM calls — routed through Deja
+
+  kwargs = expect_llm_called          # exactly one call happened
+  expect(kwargs[:system]).to include("You are a summarization assistant")
+
+  expect(summary).to meet_requirements(<<~REQ)
+    A single sentence under 200 characters that indicates that the article is about The Hitchhiker's Guide to the Galaxy
+  REQ
+end
+```
+
+Run it three ways:
+
+```bash
+# 1. First run — nothing cached yet:
+bundle exec rspec spec/integration/article_summarizer_spec.rb
+#    => Deja::MissingCacheError: "Set ALLOW_LLM_CALL=1 to make the call and record it."
+
+# 2. Record — makes the real calls and writes YAML fixtures:
+ALLOW_LLM_CALL=1 bundle exec rspec spec/integration/article_summarizer_spec.rb
+
+# 3. Every run after — replays from cache, no network:
+bundle exec rspec spec/integration/article_summarizer_spec.rb
+```
+
+Commit the YAML files under `cache_root`. They're the recorded fixtures; CI
+replays them with no API key.
+
+## Use LLM response in a subsequent assertion
+
+When your code *acts on* what the model returned, you'll often want to assert it
+used that output correctly. But the output is non-deterministic, so you can't
+hardcode it. `cached_llm_value` reads the actual recorded response out of the
+cache file by walking keys and array indices — so your assertion and the
+recording stay in sync every time you re-record.
+
+```ruby
+it "stores the topics the model extracted" do
+  use_llm_cache("2026-05-01_09-15")
+
+  # Asks the model to extract topics via a tool call, then saves them.
+  ArticleTagger.new(article).call
+
+  # Read what the model actually returned (a tool_use input) from the cache and
+  # assert your code persisted exactly that — no hardcoded expectation.
+  topics = cached_llm_value("2026-05-01_09-15",
+    "calls", 0, "response", "tool_uses", 0, "input", "topics")
+
+  expect(Article.last.topics).to eq(topics)
+end
+```
+
+The path mirrors the recorded YAML (see [How it caches](#how-it-caches)):
+`calls` → the first call → its `response` → the first `tool_uses` entry → that
+tool call's `input` → the `topics` key.
+
+## DSL reference
+
+| Helper | What it does |
+| --- | --- |
+| `use_llm_cache(id)` | Installs the caching stub and sets the per-test cache id. Call once at the top of an example. |
+| `expect_llm_called` | Asserts exactly one LLM call happened; returns its kwargs. Currently only useful where there is a single llm call in a test. |
+| `forbid_llm_calls` | Installs a client that raises on any access — proves a code path never reaches the LLM. |
+| `cached_llm_value(id, *path)` | Reads a value out of a recorded YAML file by walking keys/indices. |
+| `meet_requirements(text)` | Matcher: asserts a value satisfies free-text requirements (judged once, cached). |
+
+## How it caches
+
+One YAML file per test, keyed by the id you pass to `use_llm_cache`:
+
+```
+<cache_root>/cached_calls/<spec/path>/<id>.yaml        # recorded responses
+<cache_root>/meets_requirements/<spec/path>/<id>.yaml  # confirmed meet_requirements values
+```
+
+Each request is fingerprinted with a 12-char hash of its canonicalized kwargs.
+On replay, a miss prints a unified diff against the closest recorded request so
+you can see exactly what drifted. Re-recording (`ALLOW_LLM_CALL=1`) prunes any
+cached entry the test no longer reaches.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `ALLOW_LLM_CALL=1` | Make real calls and record/update the cache. Your real client must be able to authenticate (the Anthropic SDK reads `ANTHROPIC_API_KEY` by default). |
+| `DISABLE_LLM_CACHE=1` | Bypass the cache entirely and always call live (debugging). |
+
+## Configuration
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `cache_root` | `spec/support/deja_cache` | Directory for recorded YAML (under `project_root`). |
+| `register(provider, install:, real_client:, as:)` | — (≥1 required) | Register a provider. `install` swaps your app's client for Deja's stub; `real_client` (optional) builds a live client for recording. |
+| `project_root` | `Dir.pwd` | Base for relative paths in error messages. |
+| `judge_client { ... }` | — (required for `meet_requirements`) | Live client used by the `meet_requirements` judge. No default. |
+| `judge_attrs = { ... }` | `{}` | Attrs merged into the `meet_requirements` judge's `messages.create` call, overriding the judge's own defaults (model, token limit, system prompt). `messages` and `output_config` are reserved by the matcher. |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/deja/adapters/anthropic.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "deja/adapters/base"
+require "llm_mock_anthropic"
+
+module Deja
+  module Adapters
+    # Wires the Anthropic provider from llm_mock_anthropic into Deja's cache.
+    # All Anthropic-SDK shape knowledge — the stub client, the response structs,
+    # and serialize/deserialize — lives in LlmMock::Anthropic; this adapter just
+    # routes its calls through Deja::Cache (via Base#cached_call).
+    class Anthropic < Base
+      def provider
+        @provider ||= LlmMock::Anthropic::Provider.new
+      end
+
+      def build_mock_client
+        adapter = self
+        provider.build_client do |method, kwargs|
+          adapter.cached_call(method, kwargs) do
+            adapter.provider.call_real(adapter.real_client, method, kwargs)
+          end
+        end
+      end
+
+      def default_real_client
+        provider.default_real_client
+      end
+
+      def prompt_for(kwargs)
+        provider.prompt_for(kwargs)
+      end
+
+      def serialize(method, response)
+        provider.serialize(method, response)
+      end
+
+      def deserialize(method, data)
+        provider.deserialize(method, data)
+      end
+    end
+
+    register_type(:anthropic, Anthropic)
+  end
+end

data/lib/deja/adapters/base.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Deja
+  # Adapters teach Deja how to talk to one LLM provider: the stub client's shape,
+  # how to (de)serialize a response, and how to build a real client. The cache,
+  # hashing, and matcher are all provider-agnostic and live elsewhere.
+  module Adapters
+    @registered = {}
+
+    class << self
+      # Built-in adapter classes register themselves by provider name, so
+      # `c.register :anthropic, ...` knows which class to build. A new provider is
+      # purely additive: a new Base subclass + one register_type call.
+      def register_type(name, klass)
+        @registered[name] = klass
+      end
+
+      def build(provider, key:, install:, real_client:)
+        klass = @registered.fetch(provider) do
+          raise Deja::Error, "Unknown provider #{provider.inspect}. Registered: #{@registered.keys.inspect}"
+        end
+        klass.new(key:, install:, real_client:)
+      end
+    end
+
+    class Base
+      attr_reader :key, :install_block
+
+      # key          — how this registration is named (usually the provider symbol)
+      # install      — block run in the example's context to swap the app's client
+      #                for the one Deja hands it
+      # real_client  — optional block building a live client; falls back to the
+      #                subclass default
+      def initialize(key:, install:, real_client: nil)
+        @key = key
+        @install_block = install
+        @real_client_override = real_client
+      end
+
+      def real_client
+        (@real_client_override || default_real_client).call
+      end
+
+      # Wraps a single call: records it (for expect_llm_called), routes through the
+      # cache, and (de)serializes via the subclass. `real_call` performs the live
+      # provider call when recording.
+      def cached_call(method, kwargs, &real_call)
+        Deja.record_call(key, method, kwargs)
+        data = Deja::Cache.fetch(method, kwargs, provider: key, prompt: prompt_for(kwargs)) do
+          serialize(method, real_call.call)
+        end
+        deserialize(method, data)
+      end
+
+      # --- subclass hooks ---
+
+      # The stub client object the app receives. Its methods call `cached_call`.
+      def build_mock_client
+        raise NotImplementedError, "#{self.class} must implement #build_mock_client"
+      end
+
+      # Provider response object -> plain Hash (must round-trip through deserialize).
+      def serialize(_method, _response)
+        raise NotImplementedError, "#{self.class} must implement #serialize"
+      end
+
+      # Plain Hash (from the cache) -> object shaped like the provider's response.
+      def deserialize(_method, _data)
+        raise NotImplementedError, "#{self.class} must implement #deserialize"
+      end
+
+      def default_real_client
+        raise NotImplementedError, "#{self.class} must implement #default_real_client"
+      end
+
+      # A human-readable prompt string stored on the cache entry (purely for
+      # auditing the YAML). Optional.
+      def prompt_for(_kwargs)
+        nil
+      end
+    end
+  end
+end

data/lib/deja/cache.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require "diff/lcs"
+require "diff/lcs/hunk"
+require "digest"
+require "fileutils"
+require "set"
+require "yaml"
+
+module Deja
+  # File-based cache for Anthropic responses, keyed by an id chosen per-test (see
+  # `use_llm_cache(id)`). One file per test: `<cache_root>/cached_calls/<suite>/<id>.yaml`.
+  # All calls a test makes land in that one file under `calls:`, each tagged with a
+  # `hash` of the kwargs so we can look up the right cached response on replay.
+  #
+  # YAML shape:
+  #   test_suite:    <derived from the spec file path>
+  #   test_name:     <full RSpec description>
+  #   summary:       <human-readable counts: total / tool_use / message-only>
+  #   calls:
+  #     - provider:      <which registered adapter produced this — e.g. anthropic>
+  #       hash:          <12-char fingerprint of kwargs — used for lookup>
+  #       prompt:        <adapter-supplied readable prompt, when present>
+  #       payload:       <full canonicalized kwargs — for a precise diff on miss>
+  #       response:      <adapter-serialized response hash; the adapter replays it>
+  #
+  # Behavior:
+  #   DISABLE_LLM_CACHE=1     → bypass cache entirely
+  #   cache hit               → return cached response
+  #   miss + ALLOW_LLM_CALL=1 → call live, append to the test's file
+  #   miss + no ALLOW_LLM_CALL → raise Deja::MissingCacheError
+  module Cache
+    module_function
+
+    def cache_dir
+      Deja.configuration.cache_root.join("cached_calls")
+    end
+
+    def fetch(method, kwargs, provider:, prompt: nil)
+      return yield if ENV["DISABLE_LLM_CACHE"]
+
+      hash = call_hash(method, kwargs)
+      record_touched(hash)
+      entry = load_call(hash)
+
+      if entry
+        response_from_entry(entry)
+      elsif ENV["ALLOW_LLM_CALL"]
+        response = yield
+        append_call!(provider, hash, kwargs, prompt, response)
+        response
+      else
+        raise Deja::MissingCacheError, build_miss_message(hash, kwargs)
+      end
+    end
+
+    # Builds the MissingCacheError body. When there's a cached entry whose
+    # canonicalized payload is similar to the current request, we show a
+    # unified diff against the cached payload so the test author can see
+    # exactly what drifted between record and replay. The cache stores the
+    # full canonicalized payload on each entry, so this covers `system`,
+    # `messages`, `tools`, `tool_choice`, etc. — anything the hash is computed
+    # over.
+    def build_miss_message(hash, kwargs)
+      base = "No cached LLM response with hash #{hash} in #{display_path(cache_file)}.\n" \
+             "Set ALLOW_LLM_CALL=1 to make the call and record it."
+      current_payload = JSON.pretty_generate(cache_affecting_args(kwargs))
+      closest = closest_cached_entry(current_payload)
+      return base unless closest
+
+      cached_payload = JSON.pretty_generate(closest["payload"]) if closest["payload"]
+      cached_payload ||= closest["prompt"].to_s # legacy entries: only prompt was stored
+      diff = unified_diff(cached_payload, current_payload, context: 3)
+      if diff.empty?
+        return "#{base}\n\nClosest cached entry: #{closest['hash']} " \
+          "(prompts differ outside the captured payload)"
+      end
+
+      "#{base}\n\n" \
+        "Closest cached entry: #{closest['hash']}\n" \
+        "--- cached payload (#{closest['hash']})\n" \
+        "+++ current payload (#{hash})\n" \
+        "#{diff}"
+    end
+
+    # Picks the cached entry whose stored payload (or, for legacy entries that
+    # only stored `prompt`, system text) has the largest LCS overlap with the
+    # current request. Returns nil when the cache file is empty.
+    def closest_cached_entry(current_text)
+      return nil unless cache_file.exist?
+
+      data = YAML.safe_load(cache_file.read, permitted_classes: [], aliases: false)
+      calls = data["calls"]
+      return nil if calls.nil? || calls.empty?
+
+      current_lines = current_text.lines
+      calls.max_by do |c|
+        cached_text = c["payload"] ? JSON.pretty_generate(c["payload"]) : c["prompt"].to_s
+        Diff::LCS.lcs(cached_text.lines, current_lines).size
+      end
+    end
+
+    # Returns a unified diff (with `context` lines of context) between two
+    # strings, or an empty string when they're identical.
+    def unified_diff(old_text, new_text, context: 2)
+      old_lines = old_text.lines
+      new_lines = new_text.lines
+      return "" if old_lines == new_lines
+
+      diffs = Diff::LCS.diff(old_lines, new_lines)
+      return "" if diffs.empty?
+
+      out = +""
+      file_length_difference = 0
+      diffs.each do |piece|
+        hunk = Diff::LCS::Hunk.new(old_lines, new_lines, piece, context, file_length_difference)
+        file_length_difference = hunk.file_length_difference
+        out << hunk.diff(:unified).to_s
+        out << "\n"
+      end
+      out
+    end
+
+    # Drops any call entry from the test's file whose hash wasn't looked up during
+    # the example — covers the case where a kwarg edit (or a deleted call) leaves
+    # an old entry unreachable. Only runs when ALLOW_LLM_CALL=1 (re-record mode);
+    # cache-only runs leave the file untouched so a temporarily-disabled call
+    # doesn't lose its cached response.
+    def prune_untouched_in_current_example!
+      return unless cache_file.exist?
+
+      data = YAML.safe_load(cache_file.read)
+      touched = touched_hashes
+      fresh_calls = data["calls"].select {|c| touched.include?(c["hash"]) }
+      return if fresh_calls.size == data["calls"].size
+
+      if fresh_calls.empty?
+        cache_file.delete
+      else
+        data["calls"] = fresh_calls
+        data["summary"] = build_summary(fresh_calls)
+        cache_file.write(YAML.dump(stringify(data)))
+      end
+    end
+
+    def record_touched(hash)
+      touched_hashes << hash
+    end
+
+    def touched_hashes
+      current_example!.metadata[:touched_llm_cache_hashes] ||= Set.new
+    end
+
+    def cache_file
+      cache_dir.join(test_suite, "#{current_id!}.yaml")
+    end
+
+    def call_hash(method, kwargs)
+      payload = canonicalize({method: method.to_s, args: cache_affecting_args(kwargs)})
+      Digest::SHA256.hexdigest(JSON.generate(payload))[0, 12]
+    end
+
+    def cache_affecting_args(kwargs)
+      canonicalize(kwargs.except(:request_options))
+    end
+
+    def canonicalize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) {|(k, v), h| h[k.to_s] = canonicalize(v) }.sort.to_h
+      when Array
+        obj.map {|v| canonicalize(v) }
+      when Symbol
+        obj.to_s
+      else
+        obj
+      end
+    end
+
+    def load_call(hash)
+      return nil unless cache_file.exist?
+
+      data = YAML.safe_load(cache_file.read, permitted_classes: [], aliases: false)
+      data["calls"].find {|c| c["hash"] == hash }
+    end
+
+    # The recorded response hash, handed back to the adapter to deserialize.
+    def response_from_entry(entry)
+      entry.fetch("response")
+    end
+
+    def append_call!(provider, hash, kwargs, prompt, response)
+      FileUtils.mkdir_p(cache_file.dirname)
+      data = cache_file.exist? ? YAML.safe_load(cache_file.read) : new_file_data
+      data["calls"] << build_call_entry(provider, hash, kwargs, prompt, response)
+      data["summary"] = build_summary(data["calls"])
+      cache_file.write(YAML.dump(stringify(data)))
+    end
+
+    def new_file_data
+      {
+        "test_suite" => test_suite,
+        "test_name" => current_test_name,
+        "summary" => "",
+        "calls" => [],
+      }
+    end
+
+    # Provider-agnostic: the adapter already serialized `response` (including any
+    # readable conveniences like text_response/tool_uses). We tag the entry with
+    # the provider and store the canonicalized payload so a cache miss can report
+    # a precise diff.
+    def build_call_entry(provider, hash, kwargs, prompt, response)
+      entry = {"provider" => provider.to_s, "hash" => hash}
+      entry["prompt"] = prompt unless prompt.nil?
+      entry["payload"] = cache_affecting_args(kwargs)
+      entry["response"] = response
+      entry
+    end
+
+    def build_summary(calls)
+      tool_use_count = calls.count {|c| c["response"]["tool_uses"] }
+      text_only_count = calls.count {|c| c["response"]["text_response"] && !c["response"]["tool_uses"] }
+
+      parts = [ "#{calls.size} LLM #{calls.size == 1 ? 'call' : 'calls'} made." ]
+      if tool_use_count > 0
+        parts << "#{tool_use_count} #{tool_use_count == 1 ? 'call' : 'calls'} returned tool use responses."
+      end
+      if text_only_count > 0
+        parts << "#{text_only_count} #{text_only_count == 1 ? 'call' : 'calls'} returned a message response."
+      end
+      parts.join("\n")
+    end
+
+    # Like canonicalize but preserves insertion order so the readable header
+    # (test_suite/test_name/summary/calls) stays at the top of the YAML file.
+    def stringify(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) {|(k, v), h| h[k.to_s] = stringify(v) }
+      when Array
+        obj.map {|v| stringify(v) }
+      when Symbol
+        obj.to_s
+      else
+        obj
+      end
+    end
+
+    # Derived from the spec file path. Purely organizational — moving a test to a
+    # different suite means moving its cache file, but the suite name itself has
+    # no behavioral effect beyond placement.
+    def test_suite
+      file_path = current_example!.metadata.fetch(:file_path)
+      file_path.sub(%r{^\./spec/}, "").sub(/\.rb$/, "")
+    end
+
+    def current_test_name
+      current_example!.metadata.fetch(:full_description)
+    end
+
+    def current_id!
+      id = current_example!.metadata[:llm_cache_id]
+      raise Deja::MissingIdError, "No id set on the current example. Call use_llm_cache(id) before making LLM calls." if id.nil?
+
+      id
+    end
+
+    def current_example!
+      RSpec.current_example or raise Deja::Error, "Deja must be used inside an RSpec example"
+    end
+
+    # Renders `path` relative to the configured project_root for friendlier error
+    # messages, falling back to the absolute path when it's outside the root.
+    def display_path(path)
+      path.relative_path_from(Deja.configuration.project_root)
+    rescue ArgumentError
+      path
+    end
+  end
+end