rspec-llm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba3f15006a8aa1820dd8741a4788ad7cfe94f4b213bcabb1cc1ee75458a1b8d0
+  data.tar.gz: b27e3aeefc80e89d3e8209672a66ae8e021d95af73867a4260936af916153459
+SHA512:
+  metadata.gz: 2ae5b22b4148e8b04c4607d49d0b3a088b77405f8cac92a6db1b223ecc8aefd3b84471e5d8d42db86a1527f06f8d9330f4a3ec29f8abe29732d3e2a2c60c95a5
+  data.tar.gz: 352bc6061a08c5e8561286782b51c4690d79ef9939ed93498e657c37aa78623c4c35a927ad6a7abdacef82e3b6b925bd81881b4c30971b700d0ea3872791602d

data/.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

data/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,5 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+  </profile>
+</component>

data/.idea/jsLibraryMappings.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JavaScriptLibraryMappings">
+    <includedPredefinedLibrary name="Node.js Core" />
+  </component>
+</project>

data/.idea/misc.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JavaScriptSettings">
+    <option name="languageLevel" value="ES6" />
+  </component>
+  <component name="JsFlowSettings">
+    <service-enabled>true</service-enabled>
+    <exe-path />
+    <annotation-enable>false</annotation-enable>
+    <other-services-enabled>true</other-services-enabled>
+    <auto-save>true</auto-save>
+  </component>
+  <component name="ProjectDictionaryState">
+    <dictionary name="washu" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="rbenv: 2.4.2" project-jdk-type="RUBY_SDK" />
+</project>

data/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/rspec-llm.iml" filepath="$PROJECT_DIR$/.idea/rspec-llm.iml" />
+    </modules>
+  </component>
+</project>

data/.idea/rspec-llm.iml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="ModuleRunConfigurationManager">
+    <shared />
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/features" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/spec" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/test" isTestSource="true" />
+    </content>
+    <orderEntry type="jdk" jdkName="rbenv: 3.4.9" jdkType="RUBY_SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="addressable (v2.9.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ast (v2.4.3, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="baran (v0.1.12, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="base64 (v0.3.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bigdecimal (v4.1.2, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v2.5.23, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="crack (v1.0.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="csv (v3.3.5, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.6.2, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="event_stream_parser (v1.0.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday (v2.14.2, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-multipart (v1.2.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-net_http (v3.4.4, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-retry (v2.4.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="hashdiff (v1.2.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="json (v2.19.8, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="json-schema (v4.3.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="TEST" name="langchainrb (v0.19.5, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="language_server-protocol (v3.17.0.5, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="lint_roller (v1.1.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="logger (v1.7.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="marcel (v1.2.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="matrix (v0.4.3, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="multipart-post (v2.4.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="net-http (v0.9.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parallel (v2.1.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parser (v3.3.11.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="pragmatic_segmenter (v0.3.24, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="prism (v1.9.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="public_suffix (v7.0.5, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="racc (v1.8.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rainbow (v3.1.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rake (v13.4.2, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="regexp_parser (v2.12.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rexml (v3.4.4, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec (v3.13.2, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-core (v3.13.6, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-expectations (v3.13.5, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-mocks (v3.13.8, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-support (v3.13.7, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="TEST" name="rubocop (v1.87.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop-ast (v1.49.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ruby-progressbar (v1.13.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="TEST" name="ruby_llm (v1.15.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ruby_llm-schema (v0.4.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="unicode-display_width (v3.2.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="unicode-emoji (v4.2.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="uri (v1.1.1, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="TEST" name="vcr (v6.4.0, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="TEST" name="webmock (v3.26.2, rbenv: 3.4.9) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="zeitwerk (v2.8.2, rbenv: 3.4.9) [gem]" level="application" />
+  </component>
+</module>

data/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,33 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: disable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Layout/LineLength:
+  Max: 130

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-04
+
+### Added
+- Initial release.
+- `RSpec::LLM.configure` for setting a default client, judge model, and embedder.
+- Adapters for the `ruby_llm` and `langchainrb` gems, plus a programmable in-memory `Fake` adapter for hermetic specs.
+- Matchers: `pass_llm_judge`, `match_llm_intent`, `match_json_schema`, `be_semantically_similar_to`.
+- `describe_llm` / `evaluate` DSL for batch evaluations.
+- Helpers `llm`, `stub_llm`, `stub_llm_judge` mixed into all example groups.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sal Scotto
+
+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,194 @@
+# rspec-llm
+
+[![CI](https://github.com/salscotto/rspec-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/salscotto/rspec-llm/actions/workflows/ci.yml)
+
+RSpec matchers, helpers, and a thin DSL for testing LLM-backed code in Ruby.
+
+`rspec-llm` provides:
+
+- **Custom matchers** for asserting on LLM outputs:
+  - `pass_llm_judge("criterion")` — LLM-as-judge boolean evaluation
+  - `match_llm_intent("the response is a polite apology")` — judge framed as intent matching
+  - `match_json_schema(schema)` — JSON Schema validation
+  - `be_semantically_similar_to("reference text")` — cosine similarity over embeddings
+- **Adapters** for the [`ruby_llm`](https://github.com/crmne/ruby_llm) and [`langchainrb`](https://github.com/patterns-ai-core/langchainrb) gems, plus a programmable in-memory **fake** for hermetic unit specs.
+- A `describe_llm` / `evaluate` **DSL** for running batches of prompt → expectation pairs.
+- VCR-friendly: deterministic playback is delegated to your existing VCR config (see [VCR pattern](#vcr-pattern)).
+
+## Installation
+
+```bash
+bundle add rspec-llm
+```
+
+You only need to install one of `ruby_llm` or `langchainrb` (or both) depending on which adapter you intend to use. `rspec-llm` doesn't pull either in as a hard dependency.
+
+```bash
+bundle add ruby_llm        # if you use ruby_llm
+bundle add langchainrb     # if you use langchainrb
+```
+
+## Configuration
+
+Configure once in `spec/spec_helper.rb`:
+
+```ruby
+require "rspec/llm"
+require "ruby_llm"
+
+RSpec::LLM.configure do |c|
+  c.client   = RubyLLM.chat(model: "claude-sonnet-4-6")
+  c.judge    = RubyLLM.chat(model: "claude-haiku-4-5")
+  c.embedder = ->(text) { RubyLLM.embed(text).vectors }
+  c.similarity_threshold = 0.8
+end
+```
+
+With `langchainrb` it looks like:
+
+```ruby
+require "rspec/llm"
+require "langchain"
+
+llm = Langchain::LLM::OpenAI.new(api_key: ENV.fetch("OPENAI_API_KEY"))
+
+RSpec::LLM.configure do |c|
+  c.client   = llm
+  c.judge    = llm
+  c.embedder = ->(text) { llm.embed(text: text).embedding }
+end
+```
+
+## Matchers
+
+```ruby
+RSpec.describe "Summarizer" do
+  let(:response) { MyApp.summarize(article) }
+
+  it { expect(response).to pass_llm_judge("contains a single-sentence summary") }
+  it { expect(response).to match_llm_intent("a summary of the article") }
+  it { expect(response).to match_json_schema(MyApp::SUMMARY_SCHEMA) }
+  it { expect(response).to be_semantically_similar_to(expected_gist).within(0.85) }
+end
+```
+
+### `pass_llm_judge`
+
+Sends the response and a criterion to the configured judge model and parses a YES/NO verdict from the first token of the reply. The judge's reasoning is surfaced in the failure message.
+
+```ruby
+expect(reply).to pass_llm_judge("is polite and apologetic")
+```
+
+To use a different judge for a single matcher, chain `.using(some_client)`.
+
+### `match_llm_intent`
+
+Same machinery as `pass_llm_judge`, framed as intent matching — useful when the "criterion" is naturally a description of what the response should say.
+
+```ruby
+expect(reply).to match_llm_intent("a refund confirmation for order #12345")
+```
+
+### `match_json_schema`
+
+Parses the actual value as JSON (or accepts a Hash/Array directly) and validates against the given JSON Schema via the `json-schema` gem.
+
+```ruby
+schema = {
+  "type" => "object",
+  "required" => ["summary"],
+  "properties" => { "summary" => { "type" => "string" } }
+}
+expect(response).to match_json_schema(schema)
+```
+
+### `be_semantically_similar_to`
+
+Embeds both sides via the configured `embedder`, computes cosine similarity, and compares to the threshold. Override the threshold per-matcher with `.within(0.9)`.
+
+```ruby
+expect(response).to be_semantically_similar_to("the cat sat on the mat").within(0.9)
+```
+
+## Fake adapter
+
+For fast, hermetic unit tests, stub the client with the built-in fake:
+
+```ruby
+RSpec.describe "Greeter" do
+  it "returns the canned greeting" do
+    stub_llm do |fake|
+      fake.respond_to("Say hi to Alice").with("Hi, Alice!")
+      fake.respond_to_pattern(/^Say hi to/).with { |prompt| "Hi! (from #{prompt})" }
+      fake.default("…")
+    end
+
+    expect(MyApp.greet("Alice")).to eq("Hi, Alice!")
+  end
+end
+```
+
+Use `stub_llm_judge` to stub the judge model separately — handy when testing your own code that wraps `pass_llm_judge`:
+
+```ruby
+stub_llm_judge do |fake|
+  fake.default("YES\nLooks good to me.")
+end
+```
+
+## DSL
+
+`describe_llm` is a thin wrapper around `RSpec.describe` that adds an `evaluate` group helper:
+
+```ruby
+RSpec.describe_llm "Summarizer evals" do
+  evaluate "single sentence",
+    prompt: "Summarize: #{ARTICLE}",
+    expect: [
+      pass_llm_judge("is one sentence"),
+      match_llm_intent("a summary of the article")
+    ]
+end
+```
+
+Each `evaluate` call defines one RSpec example: it calls the configured client with the prompt and applies every matcher in `expect:`.
+
+## VCR pattern
+
+For integration tests against real APIs, record once and replay deterministically using [VCR](https://github.com/vcr/vcr) + [WebMock](https://github.com/bblimke/webmock):
+
+```ruby
+# spec/spec_helper.rb
+require "vcr"
+
+VCR.configure do |c|
+  c.cassette_library_dir = "spec/cassettes"
+  c.hook_into :webmock
+  c.filter_sensitive_data("<OPENAI_API_KEY>") { ENV["OPENAI_API_KEY"] }
+  c.configure_rspec_metadata!
+end
+
+RSpec.describe "Summarizer", vcr: true do
+  it "summarizes" do
+    expect(MyApp.summarize(article)).to pass_llm_judge("is concise")
+  end
+end
+```
+
+## Development
+
+```bash
+bin/setup            # install deps
+bundle exec rspec    # run tests
+bundle exec rubocop  # lint
+bin/console          # interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests welcome on GitHub at https://github.com/salscotto/rspec-llm.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/build_release.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+set -e
+
+# Extract version from version.rb
+VERSION=$(ruby -r ./lib/rspec/llm/version.rb -e "puts RSpec::LLM::VERSION")
+
+echo "Building gem version ${VERSION}..."
+gem build rspec-llm.gemspec
+
+echo "Pushing to RubyGems..."
+gem push rspec-llm-${VERSION}.gem
+
+echo "Done!"

data/lib/rspec/llm/adapters/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RSpec
+  module LLM
+    module Adapters
+      # Abstract adapter. Subclasses normalize ruby_llm / langchainrb / fake
+      # clients to a common minimal surface: #chat(messages) -> String,
+      # and optionally #embed(text) -> Array<Float>.
+      class Base
+        class UnsupportedClientError < ArgumentError; end
+
+        # Wrap an arbitrary client object in the right adapter. Uses class-name
+        # string matching so that ruby_llm / langchainrb aren't hard required.
+        def self.wrap(obj)
+          return obj if obj.is_a?(Base)
+
+          class_name = obj.class.name.to_s
+          case class_name
+          when /\ARubyLLM::Chat/, "RubyLLM"
+            RubyLLM.new(obj)
+          when /\ALangchain::LLM::/
+            Langchain.new(obj)
+          else
+            raise UnsupportedClientError,
+                  "Unsupported LLM client: #{class_name.empty? ? obj.inspect : class_name}. " \
+                  "Wrap it in a subclass of RSpec::LLM::Adapters::Base."
+          end
+        end
+
+        def initialize(client)
+          @client = client
+        end
+
+        attr_reader :client
+
+        # Send a chat. `messages` may be a String (treated as a single user
+        # message) or an Array of { role:, content: } hashes. Returns the
+        # assistant's text content as a String.
+        def chat(_messages)
+          raise NotImplementedError
+        end
+
+        # Embed text. Returns Array<Float>. Optional — adapters may raise
+        # NotImplementedError if the underlying client doesn't support it.
+        def embed(_text)
+          raise NotImplementedError
+        end
+
+        protected
+
+        def normalize_messages(messages)
+          case messages
+          when String
+            [{ role: "user", content: messages }]
+          when Array
+            messages.map { |m| { role: m[:role] || m["role"] || "user", content: m[:content] || m["content"] } }
+          else
+            raise ArgumentError, "messages must be a String or Array of hashes, got #{messages.class}"
+          end
+        end
+      end
+    end
+  end
+end