llm.rb 2.1.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8578f727c5a45b243d86f498cf1a3fcc594981f4056234d2376805744b7e7633
-  data.tar.gz: 03aefaa4ebdf15200e0d6999a8b7015e101dcc0d9afff4c205672a6fa94532c4
+  metadata.gz: fa682f0c6793298daeaac88092cb52f03652cbbbf28adfd6b62f94b8a263f3f3
+  data.tar.gz: 1fb08983372becef70d866bdc4ee79ee8d8bba55ace5d4be4637a69e91341747
 SHA512:
-  metadata.gz: 1b969f525f44192999bcb3ea45aec1e53283d6bb4347b6852bc0bfe9095ecf4d9a9d21a42f7b04e6c530329bf96deb0fa0508757b9e0c185b8944d1630da1648
-  data.tar.gz: 239ff739c3f9bfdfbe8f574a1045acac9ace3bbb0ddca3a92958fee9319e4834c2f057a61c9b0c418979111050ade4968a01ec73862f70278b75cbe7752c9815
+  metadata.gz: 720e09be8b25a9fde7d92887636d572edcdbd39a1b3a23ae1f44baaddb9f881c95927f63f16248f3a3d22da1704973f69f51309c487e1c97195175b772499b0d
+  data.tar.gz: 8cf35f7829b4e66ef002652643779658cf9c8cf8726f8b563eb5ca59ebcfc3a71eeb9b4cc473dfc4556324448855b6733fe3d48a73fb6e70fb91102544eb7061

data/README.md

@@ -1,3 +1,7 @@
+> **Minimal footprint** <br>
+> Zero dependencies outside Ruby’s standard library. <br>
+> Zero runtime dependencies.
+
 ## About
 
 llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
@@ -15,32 +19,38 @@ A simple chatbot that maintains a conversation and streams responses in real-tim
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV["KEY"])
+llm = LLM.openai(key: ENV.fetch("KEY"))
 bot = LLM::Bot.new(llm, stream: $stdout)
 loop do
   print "> "
-  bot.chat(gets)
-  print "\n"
+  bot.chat(STDIN.gets)
+  puts
 end
 ```
 
 #### Prompts
 
+> ℹ️  **Tip:** Some providers (such as OpenAI) support `system` and `developer`
+> roles, but the examples in this README stick to `user` roles since they are
+> supported across all providers.
+
 A prompt builder that produces a chain of messages that can be sent in one request:
 
 ```ruby
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV["KEY"])
+llm = LLM.openai(key: ENV.fetch("KEY"))
 bot = LLM::Bot.new(llm)
+
 prompt = bot.build_prompt do
-  it.system "Your task is to answer all user queries"
+  it.user "Answer concisely."
   it.user "Was 2024 a leap year?"
-  it.user "How many days in a year?"
+  it.user "How many days were in that year?"
 end
-bot.chat(prompt)
-bot.messages.each { print "[#{it.role}] ", it.content, "\n" }
+
+res = bot.chat(prompt)
+res.choices.each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 #### Schema
@@ -52,20 +62,20 @@ A bot that instructs the LLM to respond in JSON, and according to the given sche
 require "llm"
 
 class Estimation < LLM::Schema
-  property :age, Integer, "The age of a person in a photo", required: true
-  property :confidence, Number, "Model confidence (0.0 to 1.0)", required: true
-  property :notes, String, "Model notes or caveats", optional: true
+  property :age, Integer, "Estimated age", required: true
+  property :confidence, Number, "0.0–1.0", required: true
+  property :notes, String, "Short notes", optional: true
 end
 
-llm = LLM.openai(key: ENV["KEY"])
+llm = LLM.openai(key: ENV.fetch("KEY"))
 bot = LLM::Bot.new(llm, schema: Estimation)
 img = llm.images.create(prompt: "A man in his 30s")
-res = bot.chat bot.image_url(img.urls[0])
-estimation = res.choices.find(&:assistant?).content!
+res = bot.chat bot.image_url(img.urls.first)
+data = res.choices.find(&:assistant?).content!
 
-puts "age: #{estimation["age"]}"
-puts "confidence: #{estimation["confidence"]}"
-puts "notes: #{estimation["notes"]}"
+puts "age: #{data["age"]}"
+puts "confidence: #{data["confidence"]}"
+puts "notes: #{data["notes"]}" if data["notes"]
 ```
 
 #### Tools
@@ -79,58 +89,57 @@ require "llm"
 class System < LLM::Tool
   name "system"
   description "Run a shell command"
-  param :command, String, "The command to execute", required: true
+  param :command, String, "Command to execute", required: true
 
   def call(command:)
     {success: system(command)}
   end
 end
 
-llm  = LLM.openai(key: ENV["KEY"])
+llm  = LLM.openai(key: ENV.fetch("KEY"))
 bot  = LLM::Bot.new(llm, tools: [System])
+
 prompt = bot.build_prompt do
-  it.system "Your task is to execute system commands"
-  it.user "mkdir /home/robert/projects"
+  it.user "You can run safe shell commands."
+  it.user "Run `date`."
 end
+
 bot.chat(prompt)
-bot.chat bot.functions.map(&:call)
-bot.messages.select(&:assistant?).each { print "[#{it.role}] ", it.content, "\n" }
+bot.chat(bot.functions.map(&:call))
+bot.messages.select(&:assistant?).each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 ## Features
 
 #### General
-- ✅ A single unified interface for multiple providers
-- 📦 Zero dependencies outside Ruby's standard library
-- 🚀 Simple, composable API
-- ♻️ Optional: per-provider, process-wide connection pool via net-http-persistent
+- ✅  Unified API across providers
+- 📦  Zero runtime deps (stdlib-only)
+- 🧩  Pluggable JSON adapters (JSON, Oj, Yajl, etc)
+- ♻️  Optional persistent HTTP pool (net-http-persistent)
 
 #### Chat, Agents
-- 🧠 Stateless and stateful chat via completions and responses API
-- 🤖 Tool calling and function execution
-- 🗂️ JSON Schema support for structured, validated responses
-- 📡 Streaming support for real-time response updates
+- 🧠  Stateless + stateful chat (completions + responses)
+- 🤖  Tool calling / function execution
+- 🗂️  JSON Schema structured output
+- 📡  Streaming responses
 
 #### Media
-- 🗣️ Text-to-speech, transcription, and translation
-- 🖼️ Image generation, editing, and variation support
-- 📎 File uploads and prompt-aware file interaction
-- 💡 Multimodal prompts (text, documents, audio, images, videos, URLs, etc)
+- 🗣️  TTS, transcription, translation
+- 🖼️  Image generation + editing
+- 📎  Files API + prompt-aware file inputs
+- 📦  Streaming multipart uploads (no full buffering)
+- 💡  Multimodal prompts (text, documents, audio, images, video, URLs)
 
 #### Embeddings
-- 🧮 Text embeddings and vector support
-- 🧱 Includes support for OpenAI's vector stores API
+- 🧮  Embeddings
+- 🧱  OpenAI vector stores (RAG)
 
 #### Miscellaneous
-- 📜 Model management and selection
-- 🔧 Includes support for OpenAI's responses, moderations, and vector stores APIs
+- 📜  Models API
+- 🔧  OpenAI responses + moderations
 
 ## Matrix
 
-While the Features section above gives you the high-level picture, the table below
-breaks things down by provider, so you can see exactly what’s supported where.
-
-
 | Feature / Provider                  | OpenAI | Anthropic | Gemini | DeepSeek | xAI (Grok) | zAI    | Ollama | LlamaCpp |
 |--------------------------------------|:------:|:---------:|:------:|:--------:|:----------:|:------:|:------:|:--------:|
 | **Chat Completions**                 | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅     | ✅       |
@@ -181,6 +190,27 @@ llm = LLM.ollama(key: nil)
 llm = LLM.llamacpp(key: nil)
 ```
 
+#### LLM::Response
+
+All provider methods that perform requests return an
+[LLM::Response](https://0x1eef.github.io/x/llm.rb/LLM/Response.html).
+If the HTTP response is JSON (`content-type: application/json`),
+`response.body` is parsed into an
+[LLM::Object](https://0x1eef.github.io/x/llm.rb/LLM/Object.html) for
+dot-access. For non-JSON responses, `response.body` is a raw string.
+It is also possible to access top-level keys directly on the response
+(eg: `res.object` instead of `res.body.object`):
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+res = llm.models.all
+puts res.object
+puts res.data.first.id
+```
+
 #### Persistence
 
 The llm.rb library can maintain a process-wide connection pool
@@ -197,7 +227,7 @@ llm  = LLM.openai(key: ENV["KEY"], persistent: true)
 res1 = llm.responses.create "message 1"
 res2 = llm.responses.create "message 2", previous_response_id: res1.response_id
 res3 = llm.responses.create "message 3", previous_response_id: res2.response_id
-print res3.output_text, "\n"
+puts res3.output_text
 ```
 
 #### Thread Safety
@@ -230,15 +260,17 @@ require "llm"
 
 llm  = LLM.openai(key: ENV["KEY"])
 bot  = LLM::Bot.new(llm)
-url  = "https://upload.wikimedia.org/wikipedia/commons/c/c7/Lisc_lipy.jpg"
+image_url = "https://upload.wikimedia.org/wikipedia/commons/9/97/The_Earth_seen_from_Apollo_17.jpg"
+image_path = "/tmp/llm-logo.png"
+pdf_path = "/tmp/llm-handbook.pdf"
 
 prompt = bot.build_prompt do
-  it.system "Your task is to answer all user queries"
-  it.user ["Tell me about this URL", bot.image_url(url)]
-  it.user ["Tell me about this PDF", bot.local_file("handbook.pdf")]
+  it.user ["Tell me about this image", bot.image_url(image_url)]
+  it.user ["Tell me about this image", bot.local_file(image_path)]
+  it.user ["Tell me about this PDF", bot.local_file(pdf_path)]
 end
 bot.chat(prompt)
-bot.messages.each { print "[#{it.role}] ", it.content, "\n" }
+bot.messages.each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 #### Streaming
@@ -256,20 +288,20 @@ require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm, stream: $stdout)
-url = "https://upload.wikimedia.org/wikipedia/commons/c/c7/Lisc_lipy.jpg"
+image_url = "https://upload.wikimedia.org/wikipedia/commons/9/97/The_Earth_seen_from_Apollo_17.jpg"
+image_path = "/tmp/llm-logo.png"
+pdf_path = "/tmp/llm-handbook.pdf"
 
 prompt = bot.build_prompt do
-  it.system "Your task is to answer all user queries"
-  it.user ["Tell me about this URL", bot.image_url(url)]
-  it.user ["Tell me about the PDF", bot.local_file("handbook.pdf")]
+  it.user ["Tell me about this image", bot.image_url(image_url)]
+  it.user ["Tell me about this image", bot.local_file(image_path)]
+  it.user ["Tell me about the PDF", bot.local_file(pdf_path)]
 end
 bot.chat(prompt)
 ```
 
 ### Schema
 
-#### Object
-
 All LLM providers except Anthropic and DeepSeek allow a client to describe
 the structure of a response that a LLM emits according to a schema that is
 described by JSON. The schema lets a client describe what JSON object
@@ -280,56 +312,21 @@ its ability:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(key: ENV["KEY"])
-
-##
-# Objects
-schema = llm.schema.object(probability: llm.schema.number.required)
-bot = LLM::Bot.new(llm, schema:)
-bot.chat "Does the earth orbit the sun?", role: :user
-puts bot.messages.find(&:assistant?).content! # => {probability: 1.0}
-
-##
-# Enums
-schema = llm.schema.object(fruit: llm.schema.string.enum("Apple", "Orange", "Pineapple"))
-bot = LLM::Bot.new(llm, schema:) :system
-bot.chat "What fruit is your favorite?", role: :user
-puts bot.messages.find(&:assistant?).content! # => {fruit: "Pineapple"}
-
-##
-# Arrays
-schema = llm.schema.object(answers: llm.schema.array(llm.schema.integer.required))
-bot = LLM::Bot.new(llm, schema:)
-bot.chat "Tell me the answer to ((5 + 5) / 2) * 2 + 1", role: :user
-puts bot.messages.find(&:assistant?).content! # => {answers: [11]}
-```
-
-#### Class
-
-Other than the object form we saw in the previous example, a class form
-is also supported. Under the hood, it is implemented with the object form
-and the class form primarily exists to provide structure and organization
-that the object form lacks:
-
-```ruby
-#!/usr/bin/env ruby
-require "llm"
-
 class Player < LLM::Schema
   property :name, String, "The player's name", required: true
-  property :numbers, Array[Integer], "The player's favorite numbers", required: true
+  property :position, Array[Number], "The player's [x, y] position", required: true
 end
 
 llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm, schema: Player)
 prompt = bot.build_prompt do
-  it.system "The user's name is Robert and their favorite numbers are 7 and 12"
-  it.user "Tell me about myself"
+  it.user "The player's name is Sam and their position is (7, 12)."
+  it.user "Return the player's name and position"
 end
 
 player = bot.chat(prompt).content!
-puts "name: #{player.name}"
-puts "numbers: #{player.numbers}"
+puts "name: #{player['name']}"
+puts "position: #{player['position'].join(', ')}"
 ```
 
 ### Tools
@@ -377,7 +374,7 @@ tool = LLM.function(:system) do |fn|
 end
 
 bot = LLM::Bot.new(llm, tools: [tool])
-bot.chat "Your task is to run shell commands via a tool.", role: :system
+bot.chat "Your task is to run shell commands via a tool.", role: :user
 
 bot.chat "What is the current date?", role: :user
 bot.chat bot.functions.map(&:call) # report return value to the LLM
@@ -424,7 +421,7 @@ end
 
 llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm, tools: [System])
-bot.chat "Your task is to run shell commands via a tool.", role: :system
+bot.chat "Your task is to run shell commands via a tool.", role: :user
 
 bot.chat "What is the current date?", role: :user
 bot.chat bot.functions.map(&:call) # report return value to the LLM
@@ -454,9 +451,9 @@ require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm)
-file = llm.files.create(file: "/book.pdf")
+file = llm.files.create(file: "/tmp/llm-book.pdf")
 res = bot.chat ["Tell me about this file", file]
-res.choices.each { print "[#{it.role}] ", it.content, "\n" }
+res.choices.each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 ### Prompts
@@ -487,17 +484,19 @@ require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm)
-url = "https://upload.wikimedia.org/wikipedia/commons/c/c7/Lisc_lipy.jpg"
+image_url = "https://upload.wikimedia.org/wikipedia/commons/9/97/The_Earth_seen_from_Apollo_17.jpg"
+image_path = "/tmp/llm-logo.png"
+pdf_path = "/tmp/llm-book.pdf"
 
-res1 = bot.chat ["Tell me about this URL", bot.image_url(url)]
-res1.choices.each { print "[#{it.role}] ", it.content, "\n" }
+res1 = bot.chat ["Tell me about this image URL", bot.image_url(image_url)]
+res1.choices.each { |m| puts "[#{m.role}] #{m.content}" }
 
-file = llm.files.create(file: "/book.pdf")
+file = llm.files.create(file: pdf_path)
 res2 = bot.chat ["Tell me about this PDF", bot.remote_file(file)]
-res2.choices.each { print "[#{it.role}] ", it.content, "\n" }
+res2.choices.each { |m| puts "[#{m.role}] #{m.content}" }
 
-res3 = bot.chat ["Tell me about this image", bot.local_file("/puffy.png")]
-res3.choices.each { print "[#{it.role}] ", it.content, "\n" }
+res3 = bot.chat ["Tell me about this image", bot.local_file(image_path)]
+res3.choices.each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 ### Audio
@@ -534,7 +533,7 @@ llm = LLM.openai(key: ENV["KEY"])
 res = llm.audio.create_transcription(
   file: File.join(Dir.home, "hello.mp3")
 )
-print res.text, "\n" # => "Hello world."
+puts res.text # => "Hello world."
 ```
 
 #### Translate
@@ -552,7 +551,7 @@ llm = LLM.openai(key: ENV["KEY"])
 res = llm.audio.create_translation(
   file: File.join(Dir.home, "bomdia.mp3")
 )
-print res.text, "\n" # => "Good morning."
+puts res.text # => "Good morning."
 ```
 
 ### Images
@@ -582,8 +581,8 @@ end
 #### Edit
 
 The following example is focused on editing a local image with the aid
-of a prompt. The image (`/images/cat.png`) is returned to us with the cat
-now wearing a hat. The image is then moved to `${HOME}/catwithhat.png` as
+of a prompt. The image (`/tmp/llm-logo.png`) is returned to us with a hat.
+The image is then moved to `${HOME}/logo-with-hat.png` as
 the final step:
 
 ```ruby
@@ -594,20 +593,20 @@ require "fileutils"
 
 llm = LLM.openai(key: ENV["KEY"])
 res = llm.images.edit(
-  image: "/images/cat.png",
-  prompt: "a cat with a hat",
+  image: "/tmp/llm-logo.png",
+  prompt: "add a hat to the logo",
 )
 res.urls.each do |url|
   FileUtils.mv OpenURI.open_uri(url).path,
-               File.join(Dir.home, "catwithhat.png")
+               File.join(Dir.home, "logo-with-hat.png")
 end
 ```
 
 #### Variations
 
 The following example is focused on creating variations of a local image.
-The image (`/images/cat.png`) is returned to us with five different variations.
-The images are then moved to `${HOME}/catvariation0.png`, `${HOME}/catvariation1.png`
+The image (`/tmp/llm-logo.png`) is returned to us with five different variations.
+The images are then moved to `${HOME}/logo-variation0.png`, `${HOME}/logo-variation1.png`
 and so on as the final step:
 
 ```ruby
@@ -618,12 +617,12 @@ require "fileutils"
 
 llm = LLM.openai(key: ENV["KEY"])
 res = llm.images.create_variation(
-  image: "/images/cat.png",
+  image: "/tmp/llm-logo.png",
   n: 5
 )
 res.urls.each.with_index do |url, index|
   FileUtils.mv OpenURI.open_uri(url).path,
-               File.join(Dir.home, "catvariation#{index}.png")
+               File.join(Dir.home, "logo-variation#{index}.png")
 end
 ```
 
@@ -633,13 +632,8 @@ end
 
 The
 [`LLM::Provider#embed`](https://0x1eef.github.io/x/llm.rb/LLM/Provider.html#embed-instance_method)
-method generates a vector representation of one or more chunks
-of text. Embeddings capture the semantic meaning of text &ndash;
-a common use-case for them is to store chunks of text in a
-vector database, and then to query the database for *semantically
-similar* text. These chunks of similar text can then support the
-generation of a prompt that is used to query a large language model,
-which will go on to generate a response:
+method returns vector embeddings for one or more text inputs. A common
+use is semantic search (store vectors, then query for similar text):
 
 ```ruby
 #!/usr/bin/env ruby
@@ -647,9 +641,9 @@ require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
 res = llm.embed(["programming is fun", "ruby is a programming language", "sushi is art"])
-print res.class, "\n"
-print res.embeddings.size, "\n"
-print res.embeddings[0].size, "\n"
+puts res.class
+puts res.embeddings.size
+puts res.embeddings[0].size
 
 ##
 # LLM::Response
@@ -663,10 +657,8 @@ print res.embeddings[0].size, "\n"
 
 Almost all LLM providers provide a models endpoint that allows a client to
 query the list of models that are available to use. The list is dynamic,
-maintained by LLM providers, and it is independent of a specific llm.rb release.
-[LLM::Model](https://0x1eef.github.io/x/llm.rb/LLM/Model.html)
-objects can be used instead of a string that describes a model name (although
-either works). Let's take a look at an example:
+maintained by LLM providers, and it is independent of a specific llm.rb
+release:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -676,7 +668,7 @@ require "llm"
 # List all models
 llm = LLM.openai(key: ENV["KEY"])
 llm.models.all.each do |model|
-  print "model: ", model.id, "\n"
+  puts "model: #{model.id}"
 end
 
 ##
@@ -684,7 +676,7 @@ end
 model = llm.models.all.find { |m| m.id == "gpt-3.5-turbo" }
 bot = LLM::Bot.new(llm, model: model.id)
 res = bot.chat "Hello #{model.id} :)"
-res.choices.each { print "[#{it.role}] ", it.content, "\n" }
+res.choices.each { |m| puts "[#{m.role}] #{m.content}" }
 ```
 
 ## Install

data/lib/llm/bot.rb

@@ -119,7 +119,7 @@ module LLM
     # if there are no assistant messages
     # @return [LLM::Object]
     def usage
-      @messages.find(&:assistant?)&.usage || LLM::Object.from_hash({})
+      @messages.find(&:assistant?)&.usage || LLM::Object.from({})
     end
 
     ##
@@ -141,7 +141,7 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def image_url(url)
-      LLM::Object.from_hash(value: url, kind: :image_url)
+      LLM::Object.from(value: url, kind: :image_url)
     end
 
     ##
@@ -151,7 +151,7 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def local_file(path)
-      LLM::Object.from_hash(value: LLM.File(path), kind: :local_file)
+      LLM::Object.from(value: LLM.File(path), kind: :local_file)
     end
 
     ##
@@ -161,7 +161,7 @@ module LLM
     # @return [LLM::Object]
     #  Returns a tagged object
     def remote_file(res)
-      LLM::Object.from_hash(value: res, kind: :remote_file)
+      LLM::Object.from(value: res, kind: :remote_file)
     end
 
     private

data/lib/llm/buffer.rb

@@ -35,15 +35,6 @@ module LLM
       end
     end
 
-    ##
-    # Returns an array of unread messages
-    # @see LLM::Message#read?
-    # @see LLM::Message#read!
-    # @return [Array<LLM::Message>]
-    def unread
-      reject(&:read?)
-    end
-
     ##
     # Find a message (in descending order)
     # @return [LLM::Message, nil]

data/lib/llm/contract/completion.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module LLM::Contract
+  ##
+  # Defines the interface all completion responses must implement
+  # @abstract
+  module Completion
+    extend LLM::Contract
+
+    ##
+    # @return [Array<LLM::Messsage>]
+    #  Returns one or more messages
+    def messages
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+    alias_method :choices, :messages
+
+    ##
+    # @return [Integer]
+    #  Returns the number of input tokens
+    def input_tokens
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # @return [Integer]
+    #  Returns the number of output tokens
+    def output_tokens
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # @return [Integer]
+    # Returns the number of reasoning tokens
+    def reasoning_tokens
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # @return [Integer]
+    #  Returns the total number of tokens
+    def total_tokens
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+
+    ##
+    # @return [LLM::Usage]
+    #  Returns usage information
+    def usage
+      LLM::Usage.new(
+        input_tokens:,
+        output_tokens:,
+        reasoning_tokens:,
+        total_tokens:
+      )
+    end
+
+    ##
+    # @return [String]
+    #  Returns the model name
+    def model
+      raise NotImplementedError, "#{self.class} does not implement '#{__method__}'"
+    end
+  end
+end

data/lib/llm/contract.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # The `LLM::Contract` module provides the ability for modules
+  # who are extended by it to implement contracts which must be
+  # implemented by other modules who include a given contract.
+  #
+  # @example
+  #   module LLM::Contract
+  #      # ..
+  #   end
+  #
+  #   module LLM::Contract
+  #     module Completion
+  #       extend LLM::Contract
+  #       # inheriting modules must implement these methods
+  #       # otherwise an error is raised on include
+  #       def foo = nil
+  #       def bar = nil
+  #     end
+  #   end
+  #
+  #   module LLM::OpenAI::ResponseAdapter
+  #     module Completion
+  #       def foo = nil
+  #       def bar = nil
+  #       include LLM::Contract::Completion
+  #     end
+  #   end
+  module Contract
+    ContractError = Class.new(LLM::Error)
+    require_relative "contract/completion"
+
+    ##
+    # @api private
+    def included(mod)
+      meths = mod.instance_methods(false)
+      if meths.empty?
+        raise ContractError, "#{mod} does not implement any methods required by #{self}"
+      end
+      missing = instance_methods - meths
+      if missing.any?
+        raise ContractError, "#{mod} does not implement methods (#{missing.join(", ")}) required by #{self}"
+      end
+    end
+  end
+end