llm_mock 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76c3be4ff38f519d54043d67a1a91112c832e99bd320e9b887881576bbc4391e
+  data.tar.gz: cc1cab796fc5149bdf27a7dfc188a09868b6ff7e26b361a16e4e5b2a4afcbbcc
+SHA512:
+  metadata.gz: e33be7f603f386d41186f8f67a45c832194672164b5568b3648efefc9d40c0764b0ff5e84ca9dcf33f556c3a4b07b3dd94e01d559defbae990bca763fbb31645
+  data.tar.gz: de6b695425a8b983d188b9ec24f8d9c460d583f820fb94c22f5b1747abc07f04419aded7fcea0bdbd7d2311dcd31042812e2adb0b7bda59c5d78a9d844f3d746

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# 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: the `LlmMock::Provider` contract that provider mock gems
+  (e.g. `llm_mock_anthropic`) implement.

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,48 @@
+# llm_mock
+
+When you test code that calls an LLM API, one robust approach is to **stub the
+client and hand back a canned response object** — no network, no flakiness, no
+cost. But every provider's SDK returns differently-shaped objects (messages,
+content blocks, tool calls, streams), and constructing those by hand is fiddly.
+The `llm_mock` family solves that per provider: `llm_mock_anthropic`,
+`llm_mock_gemini`, and so on, each giving you ergonomic builders for that SDK's
+response objects.
+
+**`llm_mock` itself is just the shared foundation.** You almost never depend on
+it directly — you pick a provider gem. This gem exists so that:
+
+- every provider mock implements the **same contract**, and
+- tools that orchestrate testing (like [`deja`](https://github.com/nbrustein/deja),
+  which records and replays real LLM calls) can drive **any** provider through
+  one interface instead of special-casing each SDK.
+
+## Who depends on this
+
+```
+your test ──► llm_mock_anthropic ──► llm_mock   (the contract)
+deja ─────────► llm_mock_anthropic ──► llm_mock
+```
+
+You want **`llm_mock_anthropic`** (or another provider gem). It pulls in
+`llm_mock` for you.
+
+## The contract
+
+A provider gem subclasses `LlmMock::Provider` and implements the parts it
+supports:
+
+| Method | Purpose |
+| --- | --- |
+| `build_client(&responder)` | Return a stub client; each SDK method calls `responder.call(method, kwargs)`. |
+| `call_real(client, method, kwargs)` | Invoke the real SDK method on a live client. |
+| `serialize(method, response)` | SDK response object → plain Hash (for caching). |
+| `deserialize(method, data)` | Plain Hash → an object shaped like the SDK response. |
+| `prompt_for(kwargs)` | Optional readable prompt string for audit logs. |
+| `default_real_client` | Optional `-> { ... }` that builds a live SDK client. |
+
+That's the whole gem: a namespace and one abstract class. The interesting code
+lives in the provider gems.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/llm_mock/provider.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module LlmMock
+  # The contract every provider mock implements (llm_mock_anthropic, and more to
+  # come), so a consumer like the `deja` gem can drive any provider uniformly.
+  #
+  # A provider encapsulates one LLM SDK's *shape* for tests:
+  #   - how to build a stub client whose methods route through a responder,
+  #   - how to invoke the real SDK (when something isn't cached),
+  #   - how to serialize/deserialize that SDK's response objects to/from the plain
+  #     hashes a cache stores.
+  #
+  # Subclasses raise NotImplementedError for anything they don't provide.
+  class Provider
+    # Build a stub object shaped like the real SDK client. Every SDK method it
+    # exposes must call `responder.call(method_name, kwargs)` and return the
+    # result. The responder is supplied by the consumer (e.g. deja's cache layer),
+    # so the provider stays ignorant of caching.
+    def build_client(&responder)
+      raise NotImplementedError, "#{self.class} must implement #build_client"
+    end
+
+    # Invoke the real SDK method on a live client — used to make the actual call
+    # when there's no cached response. `method` is the symbol the stub captured.
+    def call_real(client, method, kwargs)
+      raise NotImplementedError, "#{self.class} must implement #call_real"
+    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 -> an object shaped like the SDK's response.
+    def deserialize(method, data)
+      raise NotImplementedError, "#{self.class} must implement #deserialize"
+    end
+
+    # A human-readable prompt string stored alongside cached calls for auditing.
+    # Optional — defaults to nil.
+    def prompt_for(_kwargs)
+      nil
+    end
+
+    # A callable (-> { ... }) that builds a live SDK client. Optional — consumers
+    # may supply their own instead.
+    def default_real_client
+      raise NotImplementedError, "#{self.class} must implement #default_real_client"
+    end
+  end
+end

data/lib/llm_mock/version.rb

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

data/lib/llm_mock.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "llm_mock/version"
+require "llm_mock/provider"
+
+# llm_mock is the shared foundation for a family of gems that fabricate LLM SDK
+# response objects in tests — `llm_mock_anthropic`, and more providers to come.
+#
+# You don't usually depend on this gem directly; you pick a provider gem. This
+# gem only defines the common contract (LlmMock::Provider) those providers
+# implement, so tools like `deja` can drive any provider the same way.
+module LlmMock
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: llm_mock
+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: 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: |
+  The shared foundation for a family of gems (llm_mock_anthropic, and more) that
+  build fake LLM SDK response objects for tests that stub the client directly.
+  This gem defines the common provider contract those gems implement so tools
+  like deja can drive any provider uniformly. You usually depend on a provider
+  gem, not this one.
+email:
+- nate@bidwrangler.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/llm_mock.rb
+- lib/llm_mock/provider.rb
+- lib/llm_mock/version.rb
+homepage: https://github.com/nbrustein/llm_mock
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nbrustein/llm_mock
+  source_code_uri: https://github.com/nbrustein/llm_mock
+  changelog_uri: https://github.com/nbrustein/llm_mock/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: Shared contract for gems that fabricate LLM SDK response objects in tests.
+test_files: []