deja 0.1.0

data/lib/deja/configuration.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Deja
+  # Holds everything host-specific so the gem itself stays ignorant of your app.
+  # You register at least one provider; cache_root has a sensible default, and the
+  # judge settings only matter if you use the `meet_requirements` matcher.
+  class Configuration
+    # Directory display in error messages is computed relative to this.
+    attr_reader :project_root, :adapters
+
+    # Default recorded-cache location, relative to project_root.
+    DEFAULT_CACHE_SUBPATH = "spec/support/deja_cache"
+
+    # Attrs that override the `meet_requirements` judge's defaults. Set
+    # provider-specific args here (model, temperature, …) without Deja having to
+    # name each one — different judge LLMs expose different args. The defaults
+    # themselves live with the judge code, not here, since they're specific to
+    # whatever LLM the judge speaks. `messages` and `output_config` are reserved
+    # by the matcher and can't be overridden.
+    attr_writer :judge_attrs
+
+    def initialize
+      @cache_root = nil
+      @project_root = Pathname.new(Dir.pwd)
+      @judge_attrs = {}
+      @judge_client = nil
+      @adapters = {}
+    end
+
+    def judge_attrs
+      @judge_attrs || {}
+    end
+
+    # Where recorded cache files live. Defaults to project_root/spec/support/deja_cache.
+    def cache_root
+      @cache_root || project_root.join(DEFAULT_CACHE_SUBPATH)
+    end
+
+    # Accepts a String or Pathname (e.g. Rails.root.join(...)).
+    def cache_root=(value)
+      @cache_root = value && Pathname.new(value.to_s)
+    end
+
+    def project_root=(value)
+      @project_root = Pathname.new(value.to_s)
+    end
+
+    # Register a provider adapter. `provider` is a built-in adapter name (today:
+    # `:anthropic`). `install` swaps your app's client for Deja's stub and runs in
+    # the example's context (RSpec's `allow` is available). `real_client` is an
+    # optional block building a live client; it defaults per provider. `as` names
+    # the registration when you want two of the same provider.
+    #
+    #   c.register :anthropic,
+    #     install: ->(client) { allow(AnthropicClient).to receive(:client).and_return(client) },
+    #     real_client: -> { Anthropic::Client.new(api_key: my_key) }
+    def register(provider, install:, real_client: nil, as: provider)
+      @adapters[as] = Deja::Adapters.build(provider, key: as, install:, real_client:)
+    end
+
+    # How to build the client used by the `meet_requirements` judge. Required if
+    # you use that matcher — there is no default, so the judge's auth/model is an
+    # explicit choice. The block returns a client.
+    #
+    #   c.judge_client { Anthropic::Client.new }
+    #
+    # Called with no block, returns the configured proc (raises if unset).
+    def judge_client(&block)
+      if block
+        @judge_client = block
+      else
+        @judge_client || raise(Deja::Error, <<~MSG)
+          Deja.configuration.judge_client is not set. The `meet_requirements`
+          matcher needs a client to judge values against requirements. Set one in
+          your Deja.configure block:
+
+            Deja.configure do |c|
+              c.judge_client { Anthropic::Client.new }
+            end
+        MSG
+      end
+    end
+  end
+end

data/lib/deja/judges/anthropic.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "deja/judges/base"
+
+module Deja
+  module Judges
+    # Judge backed by the Anthropic Ruby SDK. Use `::Anthropic` for the SDK
+    # constant — bare `Anthropic` would resolve to this class.
+    class Anthropic < Base
+      DEFAULTS = {
+        model: "claude-sonnet-4-5",
+        max_tokens: 512,
+        system: "You evaluate whether a candidate value meets a set of requirements. " \
+          "Use the structured output schema to return your verdict.",
+      }.freeze
+
+      def self.handles?(client)
+        defined?(::Anthropic::Client) && client.is_a?(::Anthropic::Client)
+      end
+
+      def self.client_description
+        "Anthropic::Client"
+      end
+
+      def defaults
+        DEFAULTS
+      end
+    end
+
+    register(Anthropic)
+  end
+end

data/lib/deja/judges/base.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Deja
+  # Judge adapters teach the `meet_requirements` matcher how to judge with a given
+  # LLM client. An adapter is selected by the *type* of the object your
+  # `judge_client` returns, so the right defaults follow from the provider you
+  # chose rather than being assumed globally.
+  #
+  # Today an adapter supplies the default request attrs (model, etc.). The matcher
+  # still builds the request and parses the response (both Anthropic-shaped); as
+  # more judge providers are added, that construction/parsing is meant to move
+  # onto the adapter too — which is why dispatch already happens here.
+  module Judges
+    @registered = []
+
+    class << self
+      # Built-in judge adapters register themselves. Newest-first, so a more
+      # specific adapter registered later can shadow a more general one.
+      def register(klass)
+        @registered.unshift(klass)
+      end
+
+      def registered
+        @registered
+      end
+
+      # The adapter for the client your `judge_client` returned. Raises a helpful
+      # error when no registered adapter handles it.
+      def for_client(client)
+        klass = @registered.find {|k| k.handles?(client) }
+        klass or raise Deja::Error, <<~MSG
+          No Deja judge adapter handles #{client.class} (the object your
+          judge_client returned). Deja can judge with: #{descriptions}.
+          Point judge_client at one of those, or add a Deja::Judges::Base
+          subclass that handles your client.
+        MSG
+        klass.new(client)
+      end
+
+      def descriptions
+        @registered.map(&:client_description).join(", ")
+      end
+    end
+
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Does this adapter handle the given judge-client instance?
+      def self.handles?(_client)
+        raise NotImplementedError, "#{name} must implement .handles?"
+      end
+
+      # Human-readable client name, used in error messages.
+      def self.client_description
+        name
+      end
+
+      # Default request attrs for this judge (model, etc.). The matcher merges the
+      # user's judge_attrs over these, then its own reserved keys over both.
+      def defaults
+        raise NotImplementedError, "#{self.class} must implement #defaults"
+      end
+    end
+  end
+end

data/lib/deja/requirements_cache.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "deja/cache"
+
+module Deja
+  # Cache layer behind the `meet_requirements` matcher (defined in deja/rspec.rb).
+  # Stores confirmed requirement/value pairs keyed by a hash of the requirements
+  # text. One file per test: `<cache_root>/meets_requirements/<suite>/<id>.yaml`.
+  #
+  #   test_suite: <derived from spec file path>
+  #   test_name:  <full RSpec description>
+  #   summary:    <human-readable counts: assertions / total confirmed values>
+  #   assertions:
+  #     - hash:         <12-char fingerprint of the requirements text — used for lookup>
+  #       requirements: <the requirements text — auditable from the file alone>
+  #       confirmed_values:
+  #         - <values previously approved by the LLM judge>
+  #
+  # Pruning mirrors Deja::Cache: at the end of a passing example (when
+  # ALLOW_LLM_CALL=1), assertions whose hash wasn't touched are dropped — so
+  # changing the requirements text blows away the now-stale confirmed values.
+  module RequirementsCache
+    module_function
+
+    def cache_dir
+      Deja.configuration.cache_root.join("meets_requirements")
+    end
+
+    def values_for(requirements)
+      record_touched(requirements)
+      assertion = load_assertion(requirements)
+      assertion ? assertion.fetch("confirmed_values") : []
+    end
+
+    def append!(requirements, value)
+      record_touched(requirements)
+      data = load_or_init
+      upsert_assertion(data, requirements, value)
+      data["summary"] = build_summary(data["assertions"])
+      cache_file.write(YAML.dump(Deja::Cache.stringify(data)))
+    end
+
+    def prune_untouched_in_current_example!
+      return unless cache_file.exist?
+
+      data = YAML.safe_load(cache_file.read)
+      touched = touched_hashes
+      fresh_assertions = data["assertions"].select {|a| touched.include?(a["hash"]) }
+      return if fresh_assertions.size == data["assertions"].size
+
+      if fresh_assertions.empty?
+        cache_file.delete
+      else
+        data["assertions"] = fresh_assertions
+        data["summary"] = build_summary(fresh_assertions)
+        cache_file.write(YAML.dump(Deja::Cache.stringify(data)))
+      end
+    end
+
+    def cache_file
+      cache_dir.join(Deja::Cache.test_suite, "#{Deja::Cache.current_id!}.yaml")
+    end
+
+    def requirements_hash(requirements)
+      Digest::SHA256.hexdigest(requirements.strip)[0, 12]
+    end
+
+    def load_assertion(requirements)
+      return nil unless cache_file.exist?
+
+      hash = requirements_hash(requirements)
+      YAML.safe_load(cache_file.read).fetch("assertions").find {|a| a["hash"] == hash }
+    end
+
+    def load_or_init
+      if cache_file.exist?
+        YAML.safe_load(cache_file.read)
+      else
+        FileUtils.mkdir_p(cache_file.dirname)
+        {
+          "test_suite" => Deja::Cache.test_suite,
+          "test_name" => Deja::Cache.current_test_name,
+          "summary" => "",
+          "assertions" => [],
+        }
+      end
+    end
+
+    def upsert_assertion(data, requirements, value)
+      hash = requirements_hash(requirements)
+      existing = data["assertions"].find {|a| a["hash"] == hash }
+      if existing
+        existing["confirmed_values"] = existing.fetch("confirmed_values") + [ value ]
+      else
+        data["assertions"] << {
+          "hash" => hash,
+          "requirements" => requirements.strip,
+          "confirmed_values" => [ value ],
+        }
+      end
+    end
+
+    def build_summary(assertions)
+      total_values = assertions.sum {|a| a["confirmed_values"].size }
+      "#{assertions.size} #{assertions.size == 1 ? 'assertion' : 'assertions'}, " \
+        "#{total_values} confirmed #{total_values == 1 ? 'value' : 'values'} total."
+    end
+
+    def record_touched(requirements)
+      touched_hashes << requirements_hash(requirements)
+    end
+
+    def touched_hashes
+      Deja::Cache.current_example!.metadata[:touched_meet_requirements_hashes] ||= Set.new
+    end
+  end
+end

data/lib/deja/rspec.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "deja"
+require "json"
+
+# Require the RSpec libraries we actually use, not the "rspec" meta-gem — hosts
+# on rspec-rails have rspec-core/expectations/mocks but not the meta-gem.
+require "rspec/core"
+require "rspec/expectations"
+require "rspec/mocks"
+
+module Deja
+  # The test-facing DSL, mixed into every example by the RSpec.configure block
+  # below. Require "deja/rspec" from your spec setup to install it.
+  module Helpers
+    # Call from the top of an `it` block (per-test — the id should be distinct
+    # for each test) to install the caching client and set the cache id used for
+    # this example.
+    def use_llm_cache(id)
+      RSpec.current_example.metadata[:llm_cache_id] = id
+      Deja::Session.enable
+    end
+
+    # Assert the code path under test never reaches the LLM. Call from a `before`
+    # block or the top of an example.
+    def forbid_llm_calls
+      Deja::Session.forbid
+    end
+
+    # Assert exactly one LLM call happened (across all providers) and return its
+    # kwargs.
+    def expect_llm_called
+      Deja::Session.expect_called
+    end
+
+    # Read a value from a recorded cache YAML file by walking `path`. Each segment
+    # is a string key (for hashes) or an integer index (for arrays). Raises with
+    # the path traversed so far if any segment is missing — so a renamed key or
+    # shifted index fails loud rather than returning nil.
+    #
+    #   cached_llm_value("2026-04-30_17-03",
+    #     "calls", 0, "response", "tool_uses", 0, "input", "session_instructions")
+    def cached_llm_value(id, *path)
+      file = Deja::Cache.cache_dir.join(Deja::Cache.test_suite, "#{id}.yaml")
+      rel = Deja::Cache.display_path(file)
+      raise "No cached LLM file at #{rel}" unless file.exist?
+
+      current = YAML.safe_load(file.read)
+      path.each_with_index do |segment, i|
+        crumb = i.zero? ? "<root>" : path[0...i].map(&:inspect).join("/")
+        current = case current
+        when Hash
+          unless current.key?(segment)
+            raise "No key #{segment.inspect} at #{crumb} in #{rel}; available: #{current.keys.inspect}"
+          end
+          current[segment]
+        when Array
+          unless segment.is_a?(Integer)
+            raise "Expected integer index at #{crumb} in #{rel}, got #{segment.inspect}"
+          end
+          unless segment < current.size
+            raise "Index #{segment} out of range at #{crumb} (size #{current.size}) in #{rel}"
+          end
+          current[segment]
+        else
+          raise "Cannot traverse into #{current.class} at #{crumb} in #{rel}"
+        end
+      end
+      current
+    end
+  end
+end
+
+# `meet_requirements(requirements_text)` asserts that an LLM-generated value
+# satisfies a free-text description without pinning to a specific stringification.
+#
+# 1. Looks for the requirements_hash in the cache. If `actual` is already a
+#    confirmed value, passes — no LLM call.
+# 2. Otherwise, with ALLOW_LLM_CALL=1, asks the judge model whether `actual`
+#    meets the requirements (structured output). On "yes", caches and passes.
+# 3. Otherwise, fails telling you to re-record under ALLOW_LLM_CALL=1.
+RSpec::Matchers.define :meet_requirements do |requirements|
+  match do |actual|
+    @requirements = requirements
+
+    cached = Deja::RequirementsCache.values_for(requirements)
+    next true if cached.include?(actual)
+
+    unless ENV["ALLOW_LLM_CALL"]
+      file = Deja::Cache.display_path(Deja::RequirementsCache.cache_file)
+      @reason = "value is not in #{file} for the current requirements. " \
+        "Set ALLOW_LLM_CALL=1 to verify it against the requirements via LLM and add it to the cache."
+      next false
+    end
+
+    # Use the dedicated judge client — independent of whatever provider the spec
+    # is recording, and outside the Deja::Cache layer. The meet_requirements cache
+    # is the only cache that should track these calls.
+    config = Deja.configuration
+    judge_client = config.judge_client.call
+    # The judge adapter is chosen by the client's type, and supplies
+    # provider-appropriate defaults; judge_attrs override them. messages and
+    # output_config are reserved — they carry the requirements and the
+    # structured-output contract this matcher parses, so they're merged last and
+    # win over both.
+    judge = Deja::Judges.for_client(judge_client)
+    judge_args = judge.defaults.merge(config.judge_attrs).merge(
+      messages: [
+        {
+          role: "user",
+          content: "Requirements:\n#{requirements}\n\nCandidate value:\n#{actual}\n\n" \
+            "Does the candidate value meet the requirements?",
+        },
+      ],
+      output_config: {
+        format: {
+          type: :json_schema,
+          schema: {
+            "type" => "object",
+            "properties" => {
+              "meets_requirements" => {"type" => "boolean"},
+              "reason" => {"type" => "string"},
+            },
+            "required" => [ "meets_requirements", "reason" ],
+            "additionalProperties" => false,
+          },
+        },
+      },
+    )
+    response = judge_client.messages.create(**judge_args)
+
+    parsed = JSON.parse(response.content.first.text)
+    if parsed["meets_requirements"]
+      Deja::RequirementsCache.append!(requirements, actual)
+      true
+    else
+      @reason = "LLM judge rejected the value: #{parsed['reason']}"
+      false
+    end
+  end
+
+  failure_message do |actual|
+    "expected value to meet requirements\n#{@reason}\nGot: #{actual.inspect}"
+  end
+end
+
+RSpec.configure do |config|
+  config.include Deja::Helpers
+
+  # Prune stale entries (calls/assertions whose hash wasn't looked up this
+  # example) only when ALLOW_LLM_CALL=1 — the re-record path. Cache-only runs
+  # leave both files alone so a temporarily-disabled call/assertion doesn't lose
+  # its cached entry.
+  config.after(:each) do |example|
+    next if example.exception
+    next unless example.metadata[:llm_cache_id]
+    next unless ENV["ALLOW_LLM_CALL"]
+
+    Deja::Cache.prune_untouched_in_current_example!
+    Deja::RequirementsCache.prune_untouched_in_current_example!
+  end
+end

data/lib/deja/session.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Deja
+  # The per-example runtime. Installs every registered adapter's caching stub (so
+  # a suite can mix providers — each test exercises whichever it actually calls),
+  # and aggregates the captured calls across adapters.
+  module Session
+    module_function
+
+    # Install all registered adapters' stubs and reset the captured call log.
+    def enable
+      Deja.reset_calls!
+      adapters = Deja.adapters
+      if adapters.empty?
+        raise Deja::Error, "No providers registered. Call `c.register :anthropic, ...` inside Deja.configure."
+      end
+
+      adapters.each {|adapter| install(adapter, adapter.build_mock_client) }
+    end
+
+    # Install a poison client for every adapter so any LLM access raises.
+    def forbid
+      Deja.adapters.each {|adapter| install(adapter, poison_client) }
+    end
+
+    # Runs an adapter's install block in the current example's context (so RSpec's
+    # `allow` is available), handing it the client to return.
+    def install(adapter, client)
+      example_instance!.instance_exec(client, &adapter.install_block)
+    end
+
+    # Assert exactly one call was captured across all adapters; return its kwargs.
+    def expect_called
+      instance = example_instance!
+      instance.instance_exec do
+        expect(Deja.calls.size).to eq(1)
+      end
+      Deja.calls.first[:kwargs]
+    end
+
+    def example_instance!
+      RSpec.current_example&.example_group_instance or
+        raise Deja::Error, "Deja must be used inside an RSpec example"
+    end
+
+    def poison_client
+      poison = Object.new
+      def poison.method_missing(*) = raise("LLM should not be called (deja forbid_llm_calls)")
+      def poison.respond_to_missing?(*) = true
+      poison
+    end
+  end
+end

data/lib/deja/version.rb

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

data/lib/deja.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "deja/version"
+
+# Deja records a non-deterministic call (today: an Anthropic LLM call) the first
+# time it happens and replays the recorded response on every run after that, so
+# tests that exercise real model behavior stay fast, offline, and deterministic.
+#
+# Providers are pluggable via adapters (see Deja::Adapters) — a suite can mix
+# them, and each test exercises whichever it actually calls.
+#
+# It also ships `meet_requirements`, an RSpec matcher that asserts an LLM-produced
+# value satisfies a free-text description (judged once, then cached).
+#
+# See README.md for the full record/replay workflow and configuration.
+module Deja
+  class Error < StandardError; end
+
+  # Raised on a cache miss when ALLOW_LLM_CALL is not set — i.e. replay mode hit
+  # a request it has never recorded.
+  class MissingCacheError < Error; end
+
+  # Raised when an LLM call is made before `use_llm_cache(id)` set a cache id.
+  class MissingIdError < Error; end
+
+  class << self
+    # Configure the gem. Yields the Configuration; returns it.
+    #
+    #   Deja.configure do |c|
+    #     c.cache_root = Rails.root.join("spec/support/cache")
+    #     c.register :anthropic,
+    #       install: ->(client) { allow(AnthropicClient).to receive(:client).and_return(client) }
+    #   end
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Drops configuration and the captured call log — used between examples and by
+    # the gem's own suite.
+    def reset_configuration!
+      @configuration = Configuration.new
+      reset_calls!
+    end
+
+    # Register a provider adapter (delegates to the configuration). See
+    # Configuration#register.
+    def register(provider, **opts)
+      configuration.register(provider, **opts)
+    end
+
+    # The registered adapters, in registration order.
+    def adapters
+      configuration.adapters.values
+    end
+
+    # --- captured calls (reset per example by Session.enable) ---
+
+    def calls
+      @calls ||= []
+    end
+
+    def record_call(provider, method, kwargs)
+      calls << {provider:, method:, kwargs:}
+    end
+
+    def reset_calls!
+      @calls = []
+    end
+  end
+end
+
+require "deja/configuration"
+require "deja/cache"
+require "deja/requirements_cache"
+require "deja/adapters/base"
+require "deja/adapters/anthropic"
+require "deja/judges/base"
+require "deja/judges/anthropic"
+require "deja/session"