llm_mock_anthropic 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cad30c8947173278ddcf0167d6544e1809fd5608ce62efb574fcf3b5785de14e
+  data.tar.gz: 2fc3bad0730ff740b0766617f7f9a63dc3bf93c75fea026aaa6765b6fef38d24
+SHA512:
+  metadata.gz: 79899f2e1ea007f85fa611774894a5c6b9c2095c78124121a8fb3034ae102ee94e2586a1d4db6f564ae2c290cd4ae6dd34bb2b2253a5e9cfd7d1a38e79c01077
+  data.tar.gz: d7860e8a06ea7a8cbdbd031bcc43216ac9df081c80bde477bdd7cab64eabf7ada8749196882c53c93a382b49a72f0d055448dd09fe26c707bbcd2e4b07b11d2c

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# 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 release, extracted from the `deja` gem.
+- `LlmMock::Anthropic` response structs (`Message`, `Stream`, `TextBlock`,
+  `ToolUseBlock`) and `.text` / `.tool_use` / `.message` / `.stream` builders.
+- `LlmMock::Anthropic::Provider` implementing the `llm_mock` contract
+  (build_client, call_real, serialize, deserialize, prompt_for).

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,116 @@
+# llm_mock_anthropic
+
+When you test Ruby code that calls the Anthropic API, you usually don't want it
+hitting the network. One clean way to avoid that is to **stub your Anthropic
+client and return a canned response object** — but that runs into a wall:
+constructing a realistic Anthropic SDK response by hand is genuinely painful.
+A real `Anthropic::Message` needs `id`, `model`, `role`, `type`, `usage`,
+`stop_reason`, and typed content blocks; tool calls are nested; and **streaming
+responses have no simple object to fake at all**.
+
+`llm_mock_anthropic` gives you small, ergonomic stand-ins for exactly those
+response shapes — messages, text blocks, tool_use blocks, and streams — so your
+stub can return something your code happily consumes:
+
+```ruby
+allow(client.messages).to receive(:create).and_return(
+  LlmMock::Anthropic.message([
+    LlmMock::Anthropic.tool_use(id: "tu_1", name: "save_summary", input: {"text" => "…"}),
+  ])
+)
+```
+
+## Why object-level (and when not to)
+
+The common community approach is to stub at the **HTTP layer** (VCR/WebMock):
+record real HTTP and let the SDK deserialize it. That's a great fit when you can
+make a real call once. Stub at the **object layer** — what this gem is for — when
+that's awkward, most often because:
+
+- **Streaming.** Replaying SSE streams through VCR is fiddly; returning a
+  `Stream` double is trivial.
+- **You want to script the model's behavior** deterministically (e.g. "this turn
+  calls the `complete` tool") without recording anything.
+
+If you want to *record real calls once and replay them* rather than hand-script
+responses, see [`deja`](https://github.com/nbrustein/deja) — it builds on this
+gem.
+
+## Installation
+
+```ruby
+# Gemfile
+group :test do
+  gem "llm_mock_anthropic"
+end
+```
+
+## What you get
+
+Response value objects (duck-typed to the SDK's response surface — `.content`,
+block fields, `.text`, `.accumulated_message`):
+
+| Builder | Returns | Shape |
+| --- | --- | --- |
+| `LlmMock::Anthropic.text(str)` | `TextBlock` | `.type`, `.text` |
+| `LlmMock::Anthropic.tool_use(id:, name:, input:)` | `ToolUseBlock` | `.type`, `.id`, `.name`, `.input` |
+| `LlmMock::Anthropic.message(blocks)` | `Message` | `.content` |
+| `LlmMock::Anthropic.stream(text_chunks:, message:)` | `Stream` | `.text`, `.accumulated_message` |
+
+The structs are also available directly (`LlmMock::Anthropic::Message.new(...)`)
+if you prefer.
+
+### Example: a streamed tutor turn that ends by calling a tool
+
+Say the code under test streams a reply and finishes when the model calls a
+`complete` tool — it calls `messages.stream`, renders the incremental text, then
+inspects the final message:
+
+```ruby
+class TutorTurn
+  def run(client, conversation)
+    stream = client.messages.stream(
+      model: "claude-sonnet-4-5",
+      max_tokens: 1024,
+      messages: conversation,
+      tools: [ complete_tool ],
+    )
+
+    stream.text.each {|chunk| broadcast(chunk) } # render text as it arrives
+
+    stream.accumulated_message.content.each do |block|
+      finish! if block.type == :tool_use && block.name == "complete"
+    end
+  end
+end
+```
+
+In a test, return a fake stream so that code runs without the network — one text
+chunk plus a final message that includes the `complete` tool call:
+
+```ruby
+fake = LlmMock::Anthropic.stream(
+  text_chunks: [ "Here's the core idea. " ],
+  message: LlmMock::Anthropic.message([
+    LlmMock::Anthropic.text("Here's the core idea. "),
+    LlmMock::Anthropic.tool_use(id: "tu_done", name: "complete", input: {}),
+  ]),
+)
+allow(client.messages).to receive(:stream).and_return(fake)
+```
+
+`stream.text` yields the chunks and `stream.accumulated_message.content` is the
+final block list — exactly the surface `TutorTurn#run` reads from a real stream.
+
+## For tool authors
+
+`LlmMock::Anthropic::Provider` implements the
+[`llm_mock`](https://github.com/nbrustein/llm_mock) contract — it builds a stub
+client routed through a responder, invokes the real client, and
+serializes/deserializes responses to/from plain hashes. That's how `deja` uses
+this gem to record and replay Anthropic calls. You don't need any of that to use
+the builders above.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/llm_mock_anthropic/version.rb

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

data/lib/llm_mock_anthropic.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "llm_mock"
+require "llm_mock_anthropic/version"
+
+module LlmMock
+  # Fabricates Anthropic Ruby SDK response objects for tests, and serializes them
+  # to/from the plain hashes a cache stores.
+  #
+  # `LlmMock::Anthropic` is the namespace: the response structs and the builder
+  # helpers live here, and `LlmMock::Anthropic::Provider` is the object a
+  # consumer (e.g. deja) drives. Use `::Anthropic` for the SDK constant — bare
+  # `Anthropic` inside this module would resolve to here.
+  module Anthropic
+    # Value objects shaped like what the SDK returns. App code reads `.content`
+    # on a message, the block fields on each block, and `.text` /
+    # `.accumulated_message` on a stream — these provide exactly that surface.
+    TextBlock = Struct.new(:type, :text)
+    ToolUseBlock = Struct.new(:type, :id, :name, :input)
+    Message = Struct.new(:content)
+    Stream = Struct.new(:text, :accumulated_message)
+
+    # Ergonomic builders for canned responses — handy in specs that stub the
+    # client directly and return a scripted response.
+    #
+    #   LlmMock::Anthropic.message([
+    #     LlmMock::Anthropic.text("Here's the idea."),
+    #     LlmMock::Anthropic.tool_use(id: "tu_1", name: "do_thing", input: {"x" => 1}),
+    #   ])
+    def self.text(text)
+      TextBlock.new(:text, text)
+    end
+
+    def self.tool_use(id:, name:, input:)
+      ToolUseBlock.new(:tool_use, id, name, input)
+    end
+
+    def self.message(blocks)
+      Message.new(blocks)
+    end
+
+    def self.stream(text_chunks:, message:)
+      Stream.new(text_chunks, message)
+    end
+
+    # Drives the Anthropic SDK shape for a consumer like deja: builds the stub
+    # client, invokes the real client, and (de)serializes responses.
+    class Provider < LlmMock::Provider
+      def build_client(&responder)
+        messages = Object.new
+        messages.define_singleton_method(:create) {|**kwargs| responder.call(:create, kwargs) }
+        messages.define_singleton_method(:stream) {|**kwargs| responder.call(:stream, kwargs) }
+
+        client = Object.new
+        client.define_singleton_method(:messages) { messages }
+        client
+      end
+
+      def call_real(client, method, kwargs)
+        client.messages.public_send(method, **kwargs)
+      end
+
+      def default_real_client
+        -> { ::Anthropic::Client.new }
+      end
+
+      def prompt_for(kwargs)
+        kwargs[:system].to_s
+      end
+
+      def serialize(method, response)
+        method == :stream ? serialize_stream(response) : serialize_message(response)
+      end
+
+      def deserialize(method, data)
+        method == :stream ? deserialize_stream(data) : deserialize_message(data)
+      end
+
+      private
+
+      def serialize_message(message)
+        build_response(message.content.map {|block| serialize_block(block) })
+      end
+
+      def serialize_stream(stream)
+        build_response(
+          stream.accumulated_message.content.map {|block| serialize_block(block) },
+          text_chunks: stream.text.to_a,
+        )
+      end
+
+      # The recorded `response` hash. `content` is what deserialize replays; the
+      # `text_response`/`tool_uses` fields (and any consumer's summary) are
+      # readable conveniences derived from it.
+      def build_response(blocks, text_chunks: nil)
+        text_blocks = blocks.select {|b| b["type"] == "text" }
+        tool_use_blocks = blocks.select {|b| b["type"] == "tool_use" }
+
+        response = {}
+        response["text_response"] = text_blocks.map {|b| b["text"] }.join("\n") unless text_blocks.empty?
+        unless tool_use_blocks.empty?
+          response["tool_uses"] = tool_use_blocks.map do |b|
+            {"id" => b["id"], "name" => b["name"], "input" => b["input"]}
+          end
+        end
+        response["content"] = blocks
+        response["text_chunks"] = text_chunks if text_chunks
+        response
+      end
+
+      def serialize_block(block)
+        case block.type.to_s
+        when "tool_use"
+          {"type" => "tool_use", "id" => block.id, "name" => block.name, "input" => block.input}
+        else
+          {"type" => block.type.to_s, "text" => block.text}
+        end
+      end
+
+      def deserialize_message(data)
+        Message.new(data["content"].map {|b| deserialize_block(b) })
+      end
+
+      def deserialize_block(data)
+        case data["type"]
+        when "tool_use"
+          ToolUseBlock.new(:tool_use, data["id"], data["name"], data["input"])
+        else
+          TextBlock.new(data["type"].to_sym, data["text"])
+        end
+      end
+
+      def deserialize_stream(data)
+        blocks = (data["content"] || [ {"type" => "text", "text" => data["text_chunks"].join} ])
+          .map {|b| deserialize_block(b) }
+        Stream.new(data["text_chunks"].dup, Message.new(blocks))
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: llm_mock_anthropic
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nate Brustein
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: llm_mock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  Fabricate Anthropic Ruby SDK response objects — messages, content blocks,
+  tool_use blocks, and streams — for tests that stub the client directly and
+  return canned responses, without hitting the network or wrestling the real
+  SDK's typed models. Also serializes those objects to/from plain hashes, which
+  is how the deja gem records and replays them. Part of the llm_mock family.
+email:
+- nate@bidwrangler.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/llm_mock_anthropic.rb
+- lib/llm_mock_anthropic/version.rb
+homepage: https://github.com/nbrustein/llm_mock_anthropic
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nbrustein/llm_mock_anthropic
+  source_code_uri: https://github.com/nbrustein/llm_mock_anthropic
+  changelog_uri: https://github.com/nbrustein/llm_mock_anthropic/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Build and (de)serialize Anthropic SDK response objects in tests.
+test_files: []