ruby_llm-dagcache 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38c5ecebec52654cc6bcab8a52691c2d6aaa893911efaa1d053ca996c65ccdd1
+  data.tar.gz: bdd1dc7f7ceca174ca0b0976075876421b3048765e3b6ba8d4dc654950c1d03a
+SHA512:
+  metadata.gz: 6ee32b813383fc93cdcef9f38c97711ee38ffe9ca1b2c62dc7f575a2a611ac4d282f1a844a3dcdaa7ba636fcd3fa2c90a60f5af4aac5f5036923960963cdd796
+  data.tar.gz: 287796a0e8f2a84d415ad59d7760d7d3a6021944c590982420bd5a357c909d1345b05dc1a719a4d330bca99d17ff088af8a39356db783324285ce96dd8e76c60

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raj Mirpuri
+
+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,127 @@
+# 📼 ruby_llm-dagcache
+
+> **VCR cassettes for [RubyLLM](https://github.com/crmne/ruby_llm) agents** —
+> record what an agent did once, replay it the next time the same kind of
+> task comes in. The LLM only runs when something genuinely new happens.
+
+[![Ruby >= 3.1](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Built for RubyLLM](https://img.shields.io/badge/built%20for-RubyLLM-7048e8)](https://github.com/crmne/ruby_llm)
+[![Python sibling: dagcache](https://img.shields.io/badge/python%20sibling-dagcache-3776AB?logo=python&logoColor=white)](https://github.com/itstheraj/dag_cache)
+
+Same idea as the Python library
+**[`dagcache`](https://github.com/itstheraj/dag_cache)**, and the same
+record-and-replay philosophy as [VCR](https://github.com/vcr/vcr) — but for
+agent runs instead of HTTP calls.
+
+## 🎬 Demo
+
+![Terminal demo: record one run, replay the next with zero LLM planning](docs/demo.gif)
+
+Run it yourself — no API keys needed:
+
+```sh
+ruby examples/demo.rb
+```
+
+## 🚀 Usage
+
+```ruby
+require "ruby_llm"          # the real gem
+require "ruby_llm/dagcache"
+
+RubyLLM::DagCache.configure do |c|
+  c.store_path = ".dagcache"      # one YAML cassette per run
+  c.replay_mode = :verified       # or :frozen (VCR mode, nothing executes)
+end
+
+class Weather < RubyLLM::Tool
+  description "Get current weather"
+  def execute(latitude:, longitude:) = WeatherAPI.current(latitude, longitude)
+end
+
+class Refund < RubyLLM::Tool
+  def self.dagcache_effectful? = true   # has side effects: re-run on replay, keep order
+  def execute(order_id:) = Payment.refund(order_id)
+end
+
+agent = RubyLLM::DagCache.watch(MyAgent.new, key: ->(msg) { classify(msg) })
+agent.ask("refund order O-123")   # 1st call: live + record
+agent.ask("refund order O-456")   # 2nd call: replay, no LLM planning
+```
+
+**Good to know:**
+
+- 🔧 `RubyLLM::Tool` subclasses are picked up **automatically**. An
+  `inherited` hook adds the recorder to each tool class (a plain prepend on
+  `RubyLLM::Tool` wouldn't work — subclass `execute` methods would shadow it).
+- 👀 `watch` wraps anything with an `#ask` method (an Agent, a Chat, your own
+  class). Everything else passes through untouched.
+- 🗝️ `key:` tells runs apart — its return value goes into the cache key, so
+  "refund" tasks and "weather" tasks get separate caches. Without it, all
+  string prompts share one cache.
+
+Not using RubyLLM, or want more control? Use the DSL:
+
+```ruby
+search = RubyLLM::DagCache.tool("search_kb", pure: true) { |query:| KB.search(query) }
+plan   = RubyLLM::DagCache.llm("planner", planning: true) { |prompt| chat.ask(prompt).content }
+draft  = RubyLLM::DagCache.llm("draft") { |prompt| chat.ask(prompt).content }
+```
+
+## 🧠 How it works
+
+Same design as [the Python side](https://github.com/itstheraj/dag_cache):
+
+- **The cache key is the chain of calls, not the arguments.** Two runs match
+  when they make the same calls in the same shape — the actual values don't
+  matter.
+- **Arguments are slots that get re-filled at replay.** Each one is either an
+  `input` (from the request), a `node` output (from an earlier call), or a
+  `literal` (written by the LLM).
+- **Replay is verified, not blind.** Tools run again for real (fresh data,
+  real side effects), planning LLM calls are skipped, and output LLM calls
+  re-run with prompts updated to the fresh values. If anything doesn't line
+  up — shape changed, a value can't be resolved, a tool fails — the live
+  agent takes over automatically.
+- **Cassettes are plain YAML** in `.dagcache/`, one per run, meant to be
+  reviewed in git. They move `staging` → `approved` (the canonical path) →
+  `dead` (failed too often). If several paths fit one task, the one with the
+  most hits and recordings wins; an approved path always wins.
+
+## ⚙️ Configuration
+
+| Setting | Default | Env |
+|---|---|---|
+| `store_path` | `.dagcache` | `DAGCACHE_STORE` |
+| `replay_mode` | `:verified` | `DAGCACHE_REPLAY` |
+| `enabled` / `force_record` | on | `DAGCACHE_MODE=off\|record` |
+| `auto_replay` | `true` (staging replays too) | — |
+| `fallback_demote_threshold` | `3` | — |
+| `default_ttl_seconds` | `nil` | — |
+
+## ⚠️ Limitations
+
+Same honest list as [the Python library](https://github.com/itstheraj/dag_cache):
+matching is exact (fuzzy matching is dangerous with side-effecting tools),
+replay re-runs side effects, LLM-written literals can go stale, prompt
+patching is a heuristic, and the watched `ask` should return the result of
+its final LLM/tool call.
+
+## 🧪 Tests
+
+```sh
+ruby -Ilib -Itest test/test_end_to_end.rb   # or: rake test
+```
+
+The suite uses a fake `RubyLLM::Tool` — no API keys required.
+
+## 🔗 Related projects
+
+- [**dagcache**](https://github.com/itstheraj/dag_cache) — the Python original; same idea, same cassettes.
+- [**RubyLLM**](https://github.com/crmne/ruby_llm) — the Ruby LLM library this gem plugs into.
+- [**VCR**](https://github.com/vcr/vcr) — the record-and-replay HTTP library that inspired this.
+
+## 📄 License
+
+[MIT](LICENSE)

data/lib/ruby_llm/dagcache/agent.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module DagCache
+    # Watch any object responding to +#ask+ (a RubyLLM::Agent, a Chat, or
+    # your own wrapper). Returns a delegating wrapper; everything else
+    # passes through to the underlying agent.
+    #
+    #   agent = RubyLLM::DagCache.watch(SupportAgent.new, key: ->(msg) { classify(msg) })
+    #   agent.ask("refund my order O-123")
+    #
+    # +key:+ classifies messages into task kinds -- its return *value* is
+    # mixed into the fingerprint, keeping "refund" and "weather" requests
+    # (same shape!) in separate path caches.
+    module Agent
+      def self.watch(agent, kind: nil, key: nil)
+        Wrapper.new(agent, kind || agent.class.name, key)
+      end
+
+      # Delegating wrapper around an agent.
+      class Wrapper
+        def initialize(agent, kind, key_fn)
+          @agent = agent
+          @kind = kind
+          @key_fn = key_fn
+        end
+
+        def ask(message, **kwargs, &block)
+          extra = @key_fn&.call(message)
+          DagCache.run_cached(task_kind: @kind, inputs: { "message" => message }, key: extra) do
+            @agent.ask(message, **kwargs, &block)
+          end
+        end
+
+        def method_missing(name, ...)
+          @agent.send(name, ...)
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          @agent.respond_to?(name, include_private) || super
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/dagcache/bindings.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module DagCache
+    # Turn recorded literal arguments into re-bindable slots, and back.
+    #
+    # At record time we infer the *provenance* of every tool argument:
+    # straight from the agent's input? From an upstream tool's output? Or
+    # did the LLM make it up (literal)? At replay time bindings resolve
+    # against the *new* inputs and *fresh* upstream outputs -- which is how
+    # a cached path runs on data it has never seen.
+    module Bindings
+      class BindingError < StandardError; end
+
+      MAX_DEPTH = 12
+      MAX_MATCHES = 8
+
+      module_function
+
+      # Values too generic to safely provenance-match stay literal.
+      def worth_matching?(value)
+        case value
+        when NilClass, TrueClass, FalseClass then false
+        when Numeric then value.abs >= 100
+        when String then value.length >= 2
+        else true
+        end
+      end
+
+      def walk(root, path)
+        path.reduce(root) do |cur, seg|
+          case cur
+          when Hash
+            key = [seg, seg.to_s, (seg.to_sym if seg.respond_to?(:to_sym))].compact.find { |k| cur.key?(k) }
+            raise BindingError, "missing key #{seg.inspect} in #{cur.inspect}" if key.nil?
+
+            cur[key]
+          when Array
+            begin
+              cur[Integer(seg)]
+            rescue ArgumentError, TypeError
+              raise BindingError, "missing index #{seg.inspect}"
+            end
+          else
+            attr = seg.to_s
+            if cur.instance_variable_defined?(:"@#{attr}")
+              cur.instance_variable_get(:"@#{attr}")
+            elsif cur.respond_to?(attr)
+              cur.public_send(attr)
+            else
+              raise BindingError, "missing attribute #{attr.inspect} on #{cur.class}"
+            end
+          end
+        end
+      end
+
+      # Collect paths under +root+ whose value deep-equals +value+.
+      def find(value, root, base, out, depth = 0)
+        return if depth > MAX_DEPTH || out.size > MAX_MATCHES
+
+        if root.class == value.class && root == value
+          out << base
+          return
+        end
+        case root
+        when Hash
+          root.each { |k, v| find(value, v, base + [k.to_s], out, depth + 1) }
+        when Array
+          root.each_with_index { |v, i| find(value, v, base + [i], out, depth + 1) }
+        else
+          root.instance_variables.reject { |iv| iv.to_s.start_with?("@_") }.each do |iv|
+            find(value, root.instance_variable_get(iv), base + [iv.to_s.delete_prefix("@")], out, depth + 1)
+          end
+        end
+      end
+
+      # Infer where a recorded argument value came from. Inputs win over
+      # node outputs; earliest nodes win over later ones.
+      def infer_binding(value, inputs, prior)
+        return Binding.new(source: "literal", value: jsonable(value)) unless worth_matching?(value)
+
+        found = []
+        find(value, inputs, [], found)
+        return Binding.new(source: "input", path: found.min_by(&:size)) if found.any?
+
+        prior.each do |node_id, output|
+          found = []
+          find(value, output, [], found)
+          return Binding.new(source: "node", path: [node_id] + found.min_by(&:size)) if found.any?
+        end
+
+        Binding.new(source: "literal", value: jsonable(value))
+      end
+
+      # Resolve a binding against this call's inputs and fresh outputs.
+      def resolve(binding, inputs, outputs)
+        case binding.source
+        when "literal" then binding.value
+        when "input"
+          walk(inputs, binding.path)
+        when "node"
+          node_id = binding.path.first
+          raise BindingError, "node binding references unavailable node #{binding.path.inspect}" unless outputs.key?(node_id)
+
+          walk(outputs[node_id], binding.path[1..])
+        else
+          raise BindingError, "unknown binding source #{binding.source.inspect}"
+        end
+      rescue BindingError => e
+        raise BindingError, "#{binding.source} binding #{binding.path.inspect}: #{e.message}"
+      end
+
+      # Best-effort conversion to a YAML/JSON-serializable value.
+      def jsonable(value)
+        case value
+        when NilClass, TrueClass, FalseClass, Numeric, String then value
+        when Hash then value.to_h { |k, v| [k.to_s, jsonable(v)] }
+        when Array then value.map { |v| jsonable(v) }
+        else
+          ivars = value.instance_variables.reject { |iv| iv.to_s.start_with?("@_") }
+          if ivars.any?
+            { "__class__" => value.class.name }.merge(
+              ivars.to_h { |iv| [iv.to_s.delete_prefix("@"), jsonable(value.instance_variable_get(iv))] }
+            )
+          else
+            value.inspect
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/dagcache/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module DagCache
+    # Global configuration. Values mirror the Python library's policy.
+    class Configuration
+      attr_accessor :store_path, :enabled, :force_record, :replay_mode,
+                    :auto_replay, :fallback_demote_threshold, :default_ttl_seconds
+
+      def initialize
+        @store_path = ENV.fetch("DAGCACHE_STORE", ".dagcache")
+        @enabled = ENV["DAGCACHE_MODE"] != "off"
+        @force_record = ENV["DAGCACHE_MODE"] == "record"
+        @replay_mode = ENV.fetch("DAGCACHE_REPLAY", "verified").to_sym # :verified | :frozen
+        @auto_replay = true # replay staging DAGs, not only approved ones
+        @fallback_demote_threshold = 3
+        @default_ttl_seconds = nil
+      end
+
+      def replay_mode=(value)
+        value = value.to_sym
+        raise ArgumentError, "replay_mode must be :verified or :frozen" unless %i[verified frozen].include?(value)
+
+        @replay_mode = value
+      end
+    end
+  end
+end

data/lib/ruby_llm/dagcache/graph.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module DagCache
+    # How to obtain one argument value at replay time.
+    #   source "input":   walk the agent's call arguments along +path+
+    #   source "node":    walk a prior node's (fresh) output; path[0] is the
+    #                     upstream node id
+    #   source "literal": the LLM synthesized this; reuse recorded +value+
+    class Binding
+      attr_accessor :source, :path, :value
+
+      def initialize(source:, path: [], value: nil)
+        @source = source
+        @path = path
+        @value = value
+      end
+
+      def to_h
+        { "source" => @source, "path" => @path, "value" => @value }
+      end
+
+      def self.from_h(hash)
+        new(source: hash["source"], path: hash["path"] || [], value: hash["value"])
+      end
+    end
+
+    # One step of a recorded run. Luigi-flavored: +requires+ lists upstream
+    # node ids, +recorded_output+ is the Luigi "output" that lets frozen
+    # replay skip execution.
+    class Node
+      attr_accessor :id, :kind, :name, :purity, :args, :recorded_output,
+                    :output_shape, :requires, :duration_ms
+
+      def initialize(id:, kind:, name:, purity:, args: {}, recorded_output: nil,
+                     output_shape: nil, requires: [], duration_ms: 0.0)
+        @id = id
+        @kind = kind # "tool" | "llm_plan" | "llm_output"
+        @name = name
+        @purity = purity # "pure" | "effectful" | "llm"
+        @args = args # String name => Binding
+        @recorded_output = recorded_output
+        @output_shape = output_shape
+        @requires = requires
+        @duration_ms = duration_ms
+      end
+
+      def to_h
+        {
+          "id" => @id, "kind" => @kind, "name" => @name, "purity" => @purity,
+          "args" => @args.transform_values(&:to_h),
+          "recorded_output" => @recorded_output, "output_shape" => @output_shape,
+          "requires" => @requires, "duration_ms" => @duration_ms
+        }
+      end
+
+      def self.from_h(hash)
+        new(
+          id: hash["id"], kind: hash["kind"], name: hash["name"], purity: hash["purity"],
+          args: (hash["args"] || {}).transform_values { |v| Binding.from_h(v) },
+          recorded_output: hash["recorded_output"], output_shape: hash["output_shape"],
+          requires: hash["requires"] || [], duration_ms: hash["duration_ms"] || 0.0
+        )
+      end
+    end
+
+    # The cached artifact: an ordered DAG of nodes. +id+/+status+/stats are
+    # store-managed metadata, not part of the artifact.
+    class DAG
+      attr_accessor :task_kind, :fingerprint, :nodes, :id, :status,
+                    :recordings, :hits, :fallbacks, :created_at, :ttl_seconds
+
+      def initialize(task_kind:, fingerprint:, nodes: [])
+        @task_kind = task_kind
+        @fingerprint = fingerprint
+        @nodes = nodes
+        @id = nil
+        @status = "staging" # staging | approved | dead
+        @recordings = 1
+        @hits = 0
+        @fallbacks = 0
+      end
+
+      # The canonical tool chain -- this is what we cache *on*.
+      def path
+        @nodes.select { |n| n.kind == "tool" }.map(&:name)
+      end
+
+      def path_key
+        Keys.path_key(path)
+      end
+
+      def terminal
+        @nodes.last or raise "DAG has no nodes"
+      end
+
+      # Kahn's algorithm with original index as tiebreak (stable order).
+      def topo_order
+        index = @nodes.each_with_index.to_h { |n, i| [n.id, i] }
+        indegree = @nodes.to_h { |n| [n.id, 0] }
+        downstream = @nodes.to_h { |n| [n.id, []] }
+        @nodes.each do |n|
+          n.requires.each do |dep|
+            raise "node #{n.id} requires unknown node #{dep}" unless indegree.key?(dep)
+
+            indegree[n.id] += 1
+            downstream[dep] << n.id
+          end
+        end
+        ready = indegree.select { |_, d| d.zero? }.keys.sort_by { |id| index[id] }
+        by_id = @nodes.to_h { |n| [n.id, n] }
+        order = []
+        until ready.empty?
+          nid = ready.shift
+          order << by_id[nid]
+          downstream[nid].each do |nxt|
+            indegree[nxt] -= 1
+            ready << nxt if indegree[nxt].zero?
+          end
+          ready.sort_by! { |id| index[id] }
+        end
+        raise "DAG contains a cycle" if order.size != @nodes.size
+
+        order
+      end
+
+      def to_h
+        {
+          "task_kind" => @task_kind, "fingerprint" => @fingerprint,
+          "path" => path, "nodes" => @nodes.map(&:to_h)
+        }
+      end
+
+      def self.from_h(hash)
+        new(
+          task_kind: hash["task_kind"], fingerprint: hash["fingerprint"],
+          nodes: (hash["nodes"] || []).map { |n| Node.from_h(n) }
+        )
+      end
+    end
+  end
+end

data/lib/ruby_llm/dagcache/keys.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module RubyLLM
+  module DagCache
+    # Task identity: structural fingerprints and path keys.
+    #
+    # Cache matching is deliberately *not* about argument values. Two calls
+    # are "the same task" when they hit the same entrypoint with inputs of
+    # the same *shape* (types and keys, never values). A cached solution is
+    # identified by its chain of tool names -- the path.
+    module Keys
+      module_function
+
+      # Recursive structural fingerprint of a value: types + hash keys only.
+      def structure(value)
+        case value
+        when NilClass then "none"
+        when TrueClass, FalseClass then "bool"
+        when Integer then "int"
+        when Float then "float"
+        when String then "str"
+        when Hash
+          { "dict" => value.map { |k, v| [k.to_s, structure(v)] }.sort_by(&:first).to_h }
+        when Array
+          return { "list" => ["empty"] } if value.empty?
+
+          { "list" => value.map { |v| JSON.generate(structure(v)) }.uniq.sort }
+        else
+          ivars = value.instance_variables.reject { |v| v.to_s.start_with?("@_") }
+          if ivars.any?
+            attrs = ivars.sort.to_h { |iv| [iv.to_s.delete_prefix("@"), structure(value.instance_variable_get(iv))] }
+            { "obj" => value.class.name, "attrs" => attrs }
+          else
+            "other:#{value.class.name}"
+          end
+        end
+      end
+
+      # Stable hash of the *shape* of the call's arguments. +extra+ (from
+      # watch's key:) is mixed in by value to keep same-shaped but
+      # semantically different tasks apart.
+      def fingerprint(inputs, extra: nil)
+        shapes = inputs.map { |k, v| [k.to_s, structure(v)] }.sort_by(&:first).to_h
+        payload = JSON.generate({ "shapes" => shapes, "key" => extra })
+        Digest::SHA256.hexdigest(payload)[0, 16]
+      end
+
+      # Stable hash of a tool chain, e.g. "search_kb > fetch_order".
+      def path_key(tool_names)
+        Digest::SHA256.hexdigest(tool_names.join(">"))[0, 16]
+      end
+    end
+  end
+end

data/lib/ruby_llm/dagcache/recorder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module DagCache
+    # Accumulates nodes for one agent run. Thread-local, so concurrent
+    # agents each get their own recording; the observed code runs unmodified.
+    class Recorder
+      attr_reader :task_kind, :fingerprint, :inputs, :nodes
+
+      def initialize(task_kind:, fingerprint:, inputs:)
+        @task_kind = task_kind
+        @fingerprint = fingerprint
+        @inputs = inputs
+        @nodes = []
+        @live_outputs = {}
+      end
+
+      def self.current
+        Thread.current[:dagcache_recorder]
+      end
+
+      def record
+        Thread.current[:dagcache_recorder] = self
+        yield
+      ensure
+        Thread.current[:dagcache_recorder] = nil
+      end
+
+      def add_node(kind:, name:, purity:, args_live:, result_live:, duration_ms: 0.0)
+        nid = "n#{@nodes.size}"
+        recorded = Bindings.jsonable(result_live)
+        prior = @nodes.map { |n| [n.id, @live_outputs[n.id]] }
+        bindings = (args_live || {}).to_h do |k, v|
+          [k.to_s, Bindings.infer_binding(v, @inputs, prior)]
+        end
+        @nodes << Node.new(
+          id: nid, kind: kind, name: name, purity: purity,
+          args: bindings, recorded_output: recorded,
+          output_shape: Keys.structure(recorded), duration_ms: duration_ms
+        )
+        @live_outputs[nid] = result_live
+      end
+
+      # Compute Luigi-style +requires+ edges and return the DAG. Data deps
+      # come from node-output bindings; effectful and LLM nodes also depend
+      # on the previous node, preserving side-effect order.
+      def finalize
+        @nodes.each_with_index do |node, i|
+          deps = node.args.values.select { |b| b.source == "node" }.map { |b| b.path.first }.uniq
+          deps << @nodes[i - 1].id if i.positive? && node.purity != "pure"
+          node.requires = deps.sort_by { |d| d[1..].to_i }
+        end
+        DAG.new(task_kind: @task_kind, fingerprint: @fingerprint, nodes: @nodes)
+      end
+    end
+  end
+end

data/lib/ruby_llm/dagcache/replay.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyLLM
+  module DagCache
+    # The Luigi-style worker: execute a cached DAG against new inputs.
+    #
+    # :verified (default) -- re-execute every tool with freshly resolved
+    # arguments (real side effects, fresh data) and re-run output LLM calls.
+    # Planning LLM calls are never re-run: the DAG *is* the plan. Any drift
+    # raises Divergence and the caller falls back to the live agent.
+    #
+    # :frozen -- VCR mode. Nothing executes; recorded outputs are returned.
+    module Replay
+      class Divergence < StandardError; end
+
+      # Substitute fresh upstream outputs into recorded literal arguments
+      # (prompt patching): whole values, JSON forms, and changed leaves.
+      module Patching
+        module_function
+
+        def replacement_pairs(recorded, fresh)
+          pairs = []
+          pairs << [recorded, fresh] if recorded.is_a?(String) && fresh.is_a?(String)
+          begin
+            pairs << [JSON.generate(recorded), JSON.generate(fresh)]
+          rescue JSON::GeneratorError
+            # not JSON-able; skip the JSON form
+          end
+          pairs << [recorded.to_s, fresh.to_s]
+          leaf_pairs(recorded, fresh, pairs)
+          # Bounded (non-substring) replacement makes short values safe.
+          pairs.uniq.select { |old, new| old.length >= 2 && old != new }
+        end
+
+        # Pair up leaves at matching paths that changed between runs --
+        # strings, and numbers like prices/temps/quantities.
+        def leaf_pairs(recorded, fresh, out)
+          case recorded
+          when Hash
+            return unless fresh.is_a?(Hash)
+
+            recorded.each { |k, v| leaf_pairs(v, fresh[k], out) if fresh.key?(k) }
+          when Array
+            return unless fresh.is_a?(Array)
+
+            recorded.zip(fresh) { |a, b| leaf_pairs(a, b, out) }
+          when String
+            out << [recorded, fresh] if fresh.is_a?(String) && recorded != fresh
+          when Integer, Float
+            out << [recorded.to_s, fresh.to_s] if fresh.is_a?(recorded.class) && recorded != fresh
+          end
+        end
+
+        def patch(value, dag, outputs)
+          case value
+          when String
+            dag.nodes.reduce(value) do |text, node|
+              next text unless outputs.key?(node.id) && !node.recorded_output.nil?
+
+              replacement_pairs(node.recorded_output, outputs[node.id]).reduce(text) do |t, (old, new)|
+                t.gsub(/(?<!\w)#{Regexp.escape(old)}(?!\w)/, new)
+              end
+            end
+          when Array then value.map { |v| patch(v, dag, outputs) }
+          when Hash then value.to_h { |k, v| [k, patch(v, dag, outputs)] }
+          else value
+          end
+        end
+      end
+
+      class Executor
+        def initialize(mode = :verified)
+          mode = mode.to_sym
+          raise ArgumentError, "mode must be :verified or :frozen" unless %i[verified frozen].include?(mode)
+
+          @mode = mode
+        end
+
+        def run(dag, inputs)
+          outputs = {}
+          dag.topo_order.each do |node|
+            if node.kind == "llm_plan" || @mode == :frozen
+              # The plan is what's cached; frozen mode caches outputs too.
+              outputs[node.id] = node.recorded_output
+              next
+            end
+            callable, style = callable_for(node)
+            args = {}
+            node.args.each do |arg_name, binding|
+              args[arg_name.to_sym] =
+                begin
+                  Bindings.resolve(binding, inputs, outputs)
+                rescue Bindings::BindingError => e
+                  raise Divergence, "#{node.name}.#{arg_name}: #{e.message}"
+                end
+            end
+            args = Patching.patch(args, dag, outputs)
+            fresh =
+              begin
+                style == :kwargs ? callable.call(**args) : callable.call(*args.values)
+              rescue Divergence
+                raise
+              rescue StandardError => e
+                raise Divergence, "#{node.name} raised #{e.class}: #{e.message}"
+              end
+            unless Keys.structure(Bindings.jsonable(fresh)) == node.output_shape
+              raise Divergence, "#{node.name} output shape drifted"
+            end
+
+            outputs[node.id] = fresh
+          end
+          outputs[dag.terminal.id]
+        end
+
+        private
+
+        def callable_for(node)
+          entry =
+            case node.kind
+            when "tool" then DagCache.tools[node.name]
+            when "llm_output" then DagCache.llms[node.name]
+            end
+          raise Divergence, "no live callable registered for #{node.kind}:#{node.name}" if entry.nil?
+
+          [entry[:callable], entry[:style]]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/dagcache/store.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require "yaml"
+
+module RubyLLM
+  module DagCache
+    # Persistence: one YAML cassette per DAG in the store directory --
+    # VCR-gem style, diffable in code review. Rows are keyed by
+    # (task_kind, fingerprint, path_key): recording the same chain for the
+    # same task shape again just bumps +recordings+ -- repetition is how a
+    # path earns "canonical". Competing paths coexist and rank by stats.
+    class Store
+      def initialize(dir)
+        @dir = dir
+        FileUtils.mkdir_p(dir)
+      end
+
+      def save_dag(dag, ttl_seconds: nil)
+        existing = load_all.find do |d|
+          d.task_kind == dag.task_kind && d.fingerprint == dag.fingerprint && d.path_key == dag.path_key
+        end
+        if existing
+          existing.recordings += 1
+          existing.nodes = dag.nodes
+          persist(existing)
+          existing.id
+        else
+          dag.id = next_id
+          dag.status = "staging"
+          dag.created_at = Time.now.utc.iso8601
+          dag.ttl_seconds = ttl_seconds
+          persist(dag)
+          dag.id
+        end
+      end
+
+      def lookup(task_kind, fingerprint, auto_replay: true)
+        candidates = load_all.select do |d|
+          d.task_kind == task_kind && d.fingerprint == fingerprint &&
+            (d.status == "approved" || (auto_replay && d.status == "staging")) &&
+            !expired?(d)
+        end
+        candidates.min_by { |d| [d.status == "approved" ? 0 : 1, -(d.hits + d.recordings), d.id] }
+      end
+
+      def get(id)
+        load_all.find { |d| d.id == id }
+      end
+
+      def record_hit(id)
+        update(id) { |d| d.hits += 1 }
+      end
+
+      def record_fallback(id, demote_threshold: 3)
+        update(id) do |d|
+          d.fallbacks += 1
+          d.status = "dead" if d.status == "staging" && demote_threshold.positive? && d.fallbacks >= demote_threshold
+        end
+      end
+
+      def approve(id) = update(id) { |d| d.status = "approved" }
+      def demote(id) = update(id) { |d| d.status = "staging" }
+
+      def prune(status: nil)
+        dropped = load_all.select { |d| status.nil? || d.status == status }
+        dropped.each { |d| FileUtils.rm_f(file_for(d.id)) }
+        dropped.size
+      end
+
+      def load_all
+        Dir.glob(File.join(@dir, "*.yml")).sort.map do |file|
+          from_storage(YAML.safe_load_file(file))
+        end
+      end
+
+      private
+
+      def update(id)
+        dag = get(id)
+        return false unless dag
+
+        yield dag
+        persist(dag)
+        true
+      end
+
+      def persist(dag)
+        File.write(file_for(dag.id), YAML.dump(to_storage(dag)))
+      end
+
+      def file_for(id)
+        File.join(@dir, format("%<id>04d.yml", id: id))
+      end
+
+      def next_id
+        (load_all.map(&:id).max || 0) + 1
+      end
+
+      def expired?(dag)
+        return false if dag.ttl_seconds.nil? || dag.created_at.nil?
+
+        Time.now.utc > Time.iso8601(dag.created_at) + dag.ttl_seconds
+      end
+
+      def to_storage(dag)
+        {
+          "id" => dag.id, "task_kind" => dag.task_kind, "fingerprint" => dag.fingerprint,
+          "status" => dag.status, "recordings" => dag.recordings, "hits" => dag.hits,
+          "fallbacks" => dag.fallbacks, "created_at" => dag.created_at,
+          "ttl_seconds" => dag.ttl_seconds, "dag" => dag.to_h
+        }
+      end
+
+      def from_storage(hash)
+        dag = DAG.from_h(hash["dag"])
+        dag.id = hash["id"]
+        dag.status = hash["status"]
+        dag.recordings = hash["recordings"]
+        dag.hits = hash["hits"]
+        dag.fallbacks = hash["fallbacks"]
+        dag.created_at = hash["created_at"]
+        dag.ttl_seconds = hash["ttl_seconds"]
+        dag
+      end
+    end
+  end
+end

data/lib/ruby_llm/dagcache/tool_patch.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module DagCache
+    # Prepended onto each RubyLLM::Tool subclass: while a recording is
+    # active, every tool execution becomes a node in the DAG and the tool
+    # instance is registered so verified replay can re-execute it later.
+    #
+    # We prepend per-subclass (via an +inherited+ hook plus a sweep of
+    # already-defined subclasses) because a subclass's own #execute would
+    # shadow a module prepended to RubyLLM::Tool itself.
+    #
+    # Mark a tool as having side effects by defining +dagcache_effectful?+
+    # on the class:
+    #
+    #   class Refund < RubyLLM::Tool
+    #     def self.dagcache_effectful? = true
+    #     def execute(order_id:) = Payment.refund(order_id)
+    #   end
+    module ToolPatch
+      def execute(**args)
+        recorder = DagCache.recorder
+        return super if recorder.nil?
+
+        name = DagCache.tool_name_for(self)
+        DagCache.register_tool_instance(name, self)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = super
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000
+        recorder.add_node(
+          kind: "tool", name: name, purity: DagCache.purity_for(self),
+          args_live: args, result_live: result, duration_ms: duration_ms
+        )
+        result
+      end
+
+      # Intercepts subclasses defined after dagcache is loaded.
+      module InheritedHook
+        def inherited(subclass)
+          super
+          ToolPatch.apply(subclass)
+        end
+      end
+
+      def self.apply(tool_class)
+        tool_class.prepend(self) unless tool_class.ancestors.include?(self)
+      end
+
+      def self.install!
+        RubyLLM::Tool.singleton_class.prepend(InheritedHook)
+        RubyLLM::Tool.subclasses.each { |subclass| apply(subclass) }
+      end
+    end
+  end
+end
+
+RubyLLM::DagCache::ToolPatch.install! if defined?(RubyLLM::Tool)

data/lib/ruby_llm/dagcache/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module DagCache
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_llm/dagcache.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "dagcache/version"
+require_relative "dagcache/configuration"
+require_relative "dagcache/keys"
+require_relative "dagcache/graph"
+require_relative "dagcache/bindings"
+require_relative "dagcache/recorder"
+require_relative "dagcache/store"
+require_relative "dagcache/replay"
+require_relative "dagcache/agent"
+
+module RubyLLM
+  # DagCache: VCR cassettes for agent trajectories.
+  #
+  # Record agent runs as DAGs of tool/LLM calls, replay the canonical path
+  # on repeat tasks, and only pay for the LLM when the world diverges.
+  #
+  #   search = RubyLLM::DagCache.tool("search_kb", pure: true) { |query:| KB.search(query) }
+  #   draft  = RubyLLM::DagCache.llm("draft") { |prompt| RubyLLM.chat.ask(prompt).content }
+  #   agent  = RubyLLM::DagCache.watch(MyAgent.new, key: ->(msg) { classify(msg) })
+  #   agent.ask("where is my order O-123")   # 1st: live + record; 2nd: replay
+  module DagCache
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      def reset_configuration!
+        @configuration = nil
+      end
+
+      # -- registries ------------------------------------------------------
+
+      def tools
+        @tools ||= {}
+      end
+
+      def llms
+        @llms ||= {}
+      end
+
+      def register_tool_instance(name, instance)
+        tools[name] = { callable: ->(**a) { instance.execute(**a) }, style: :kwargs }
+      end
+
+      def tool_name_for(tool_instance)
+        klass = tool_instance.class
+        return klass.dagcache_name if klass.respond_to?(:dagcache_name)
+
+        klass.name
+      end
+
+      def purity_for(tool_instance)
+        klass = tool_instance.class
+        klass.respond_to?(:dagcache_effectful?) && klass.dagcache_effectful? ? "effectful" : "pure"
+      end
+
+      # -- DSL -------------------------------------------------------------
+
+      # Define a cacheable tool (keyword arguments, RubyLLM-style):
+      #   search = DagCache.tool("search_kb", pure: true) { |query:| ... }
+      #   search.call(query: "refunds")
+      def tool(name, pure: true, &block)
+        tools[name] = { callable: block, style: :kwargs }
+        purity = pure ? "pure" : "effectful"
+        lambda do |**args|
+          recorder = Recorder.current
+          return block.call(**args) if recorder.nil?
+
+          result = block.call(**args)
+          recorder.add_node(kind: "tool", name: name, purity: purity, args_live: args, result_live: result)
+          result
+        end
+      end
+
+      # Define an LLM call (positional arguments):
+      #   draft = DagCache.llm("draft") { |prompt| ... }
+      #   draft.call("write a reply about ...")
+      # planning: true => decision call, never re-executed at replay.
+      def llm(name, planning: false, &block)
+        llms[name] = { callable: block, style: :positional }
+        kind = planning ? "llm_plan" : "llm_output"
+        lambda do |*args|
+          recorder = Recorder.current
+          return block.call(*args) if recorder.nil?
+
+          args_live = args.each_with_index.to_h { |v, i| ["arg#{i}", v] }
+          result = block.call(*args)
+          recorder.add_node(kind: kind, name: name, purity: "llm", args_live: args_live, result_live: result)
+          result
+        end
+      end
+
+      # -- engine ----------------------------------------------------------
+
+      def recorder
+        Recorder.current
+      end
+
+      # Wrap any object responding to #ask (RubyLLM::Agent, Chat, or your
+      # own class) so calls are recorded/replayed. See DagCache::Agent.
+      def watch(agent, kind: nil, key: nil)
+        Agent.watch(agent, kind: kind, key: key)
+      end
+
+      # The @agent equivalent: lookup -> replay -> (divergence? fall back)
+      # -> run live while recording -> store candidate path.
+      def run_cached(task_kind:, inputs:, key: nil)
+        return yield unless configuration.enabled
+
+        fingerprint = Keys.fingerprint(inputs, extra: key)
+        store = Store.new(configuration.store_path)
+
+        unless configuration.force_record
+          dag = store.lookup(task_kind, fingerprint, auto_replay: configuration.auto_replay)
+          if dag
+            begin
+              result = Replay::Executor.new(configuration.replay_mode).run(dag, inputs)
+            rescue Replay::Divergence
+              store.record_fallback(dag.id, demote_threshold: configuration.fallback_demote_threshold)
+            else
+              store.record_hit(dag.id)
+              return result
+            end
+          end
+        end
+
+        recorder = Recorder.new(task_kind: task_kind, fingerprint: fingerprint, inputs: inputs)
+        result = recorder.record { yield }
+        store.save_dag(recorder.finalize, ttl_seconds: configuration.default_ttl_seconds) unless recorder.nodes.empty?
+        result
+      end
+    end
+  end
+end
+
+require_relative "dagcache/tool_patch"

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-dagcache
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dagcache contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Record RubyLLM agent runs as DAGs of tool/LLM calls, replay the canonical
+  path on repeat tasks, and only call the LLM for net-new paths. Same mental model
+  as the Python dagcache library.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ruby_llm/dagcache.rb
+- lib/ruby_llm/dagcache/agent.rb
+- lib/ruby_llm/dagcache/bindings.rb
+- lib/ruby_llm/dagcache/configuration.rb
+- lib/ruby_llm/dagcache/graph.rb
+- lib/ruby_llm/dagcache/keys.rb
+- lib/ruby_llm/dagcache/recorder.rb
+- lib/ruby_llm/dagcache/replay.rb
+- lib/ruby_llm/dagcache/store.rb
+- lib/ruby_llm/dagcache/tool_patch.rb
+- lib/ruby_llm/dagcache/version.rb
+homepage: https://github.com/itstheraj/ruby_llm-dagcache
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/itstheraj/ruby_llm-dagcache
+  bug_tracker_uri: https://github.com/itstheraj/ruby_llm-dagcache/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: VCR cassettes for RubyLLM agent trajectories
+test_files: []