llm.rb 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e60be1fa699baabf9a1df129d0263d0c2b6fecc3ce2b818128eed319aa7bb18
-  data.tar.gz: a39d32cd9cfcfb7fa4152ba3e02960522b6ae4b5d6e22705b846f5b9dcd2972b
+  metadata.gz: fa682f0c6793298daeaac88092cb52f03652cbbbf28adfd6b62f94b8a263f3f3
+  data.tar.gz: 1fb08983372becef70d866bdc4ee79ee8d8bba55ace5d4be4637a69e91341747
 SHA512:
-  metadata.gz: 4d434afe1a6acaeef6036178c5914500e047450ee7d92999dedd80f66a6be22c73f4d788f86739842ee283c579b68476c0a114f50e25e7db7bbfa6e6cdf1a5bc
-  data.tar.gz: e818753b0b06cf4053652d11b2e3c79d7ef58de0b0acc5fb7fa147e55c693eee583f1c9e1f80b08096de95247c03644fad9e596f4511d57a99d2abd5339087c2
+  metadata.gz: 720e09be8b25a9fde7d92887636d572edcdbd39a1b3a23ae1f44baaddb9f881c95927f63f16248f3a3d22da1704973f69f51309c487e1c97195175b772499b0d
+  data.tar.gz: 8cf35f7829b4e66ef002652643779658cf9c8cf8726f8b563eb5ca59ebcfc3a71eeb9b4cc473dfc4556324448855b6733fe3d48a73fb6e70fb91102544eb7061

data/README.md

@@ -19,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
@@ -56,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
@@ -83,60 +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
-- 🧩 Choose your own JSON parser (JSON stdlib, Oj, Yajl, etc)
-- 🚀 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
-- 📦 Streams multipart uploads and avoids buffering large files in memory
-- 💡 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**                 | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅     | ✅       |
@@ -187,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
@@ -203,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
@@ -236,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
@@ -262,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
@@ -286,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
@@ -383,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
@@ -430,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
@@ -460,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
@@ -493,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
@@ -540,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
@@ -558,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
@@ -588,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
@@ -600,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
@@ -624,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
 ```
 
@@ -639,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
@@ -653,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
@@ -669,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
@@ -682,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
 
 ##
@@ -690,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/contract/completion.rb

@@ -29,6 +29,13 @@ module LLM::Contract
       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
@@ -43,6 +50,7 @@ module LLM::Contract
       LLM::Usage.new(
         input_tokens:,
         output_tokens:,
+        reasoning_tokens:,
         total_tokens:
       )
     end

data/lib/llm/message.rb

@@ -51,8 +51,9 @@ module LLM
     alias_method :eql?, :==
 
     ##
-    # Try to parse the content as JSON
+    # Try to parse JSON content
     # @return [Hash]
+    #  Returns the parsed content as a Hash
     def content!
       LLM.json.load(content)
     end

data/lib/llm/object/kernel.rb

@@ -20,17 +20,17 @@ class LLM::Object
       ::Kernel.instance_method(:method).bind(self).call(...)
     end
 
-    def kind_of?(...)
-      ::Kernel.instance_method(:kind_of?).bind(self).call(...)
+    def kind_of?(klass)
+      ::Kernel.instance_method(:kind_of?).bind(self).call(klass)
     end
     alias_method :is_a?, :kind_of?
 
     def respond_to?(m, include_private = false)
-      !!key(m) || self.class.method_defined?(m) || super
+      !!key(m) || self.class.method_defined?(m)
     end
 
     def respond_to_missing?(m, include_private = false)
-      !!key(m) || super
+      !!key(m)
     end
 
     def object_id

data/lib/llm/object.rb

@@ -68,16 +68,56 @@ class LLM::Object < BasicObject
     @h.transform_keys(&:to_sym)
   end
 
+  ##
+  # @return [Array<String>]
+  def keys
+    @h.keys
+  end
+
+  ##
+  # @return [Array]
+  def values
+    @h.values
+  end
+
+  ##
+  # @param [String, Symbol] k
+  # @return [Boolean]
+  def key?(k)
+    @h.key?(key(k))
+  end
+  alias_method :has_key?, :key?
+
+  ##
+  # @param [String, Symbol] k
+  # @return [Object]
+  def fetch(k, *args, &b)
+    @h.fetch(key(k), *args, &b)
+  end
+
+  ##
+  # @return [Integer]
+  def size
+    @h.size
+  end
+  alias_method :length, :size
+
+  ##
+  # @yieldparam [String, Object]
+  def each_pair(&)
+    @h.each(&)
+  end
+
   ##
   # @return [Object, nil]
   def dig(...)
-    to_h.dig(...)
+    @h.dig(...)
   end
 
   ##
   # @return [Hash]
   def slice(...)
-    to_h.slice(...)
+    @h.slice(...)
   end
 
   private

data/lib/llm/providers/anthropic/response_adapter/completion.rb

@@ -12,13 +12,19 @@ module LLM::Anthropic::ResponseAdapter
     ##
     # (see LLM::Contract::Completion#input_tokens)
     def input_tokens
-      body.usage["input_tokens"] || 0
+      body.usage&.input_tokens || 0
     end
 
     ##
     # (see LLM::Contract::Completion#output_tokens)
     def output_tokens
-      body.usage["output_tokens"] || 0
+      body.usage&.output_tokens || 0
+    end
+
+    ##
+    # (see LLM::Contract::Completion#reasoning_tokens)
+    def reasoning_tokens
+      0
     end
 
     ##

data/lib/llm/providers/anthropic/stream_parser.rb

@@ -40,11 +40,14 @@ class LLM::Anthropic
           if Hash === content["input"]
             content["input"] = chunk["delta"]["partial_json"]
           else
+            content["input"] ||= +""
             content["input"] << chunk["delta"]["partial_json"]
           end
         end
       elsif chunk["type"] == "message_delta"
-        merge_message!(chunk["delta"])
+        merge_message!(chunk["delta"]) if chunk["delta"]
+        extras = chunk.reject { |k, _| k == "type" || k == "delta" }
+        merge_message!(extras) unless extras.empty?
       elsif chunk["type"] == "content_block_stop"
         content = @body["content"][chunk["index"]]
         if content["input"]
@@ -54,11 +57,22 @@ class LLM::Anthropic
     end
 
     def merge_message!(message)
-      message.each do |key, value|
-        @body[key] = if value.respond_to?(:each_pair)
-          merge_message!(value)
+      message.each_pair do |key, value|
+        if value.respond_to?(:each_pair)
+          @body[key] ||= {}
+          deep_merge!(@body[key], value)
         else
-          value
+          @body[key] = value
+        end
+      end
+    end
+
+    def deep_merge!(target, source)
+      source.each_pair do |key, value|
+        if value.respond_to?(:each_pair) && target[key].respond_to?(:each_pair)
+          deep_merge!(target[key], value)
+        else
+          target[key] = value
         end
       end
     end

data/lib/llm/providers/anthropic.rb

@@ -41,16 +41,9 @@ module LLM
     #  When given an object a provider does not understand
     # @return (see LLM::Provider#complete)
     def complete(prompt, params = {})
-      params = {role: :user, model: default_model, max_tokens: 1024}.merge!(params)
-      tools  = resolve_tools(params.delete(:tools))
-      params = [params, adapt_tools(tools)].inject({}, &:merge!).compact
-      role, stream = params.delete(:role), params.delete(:stream)
-      params[:stream] = true if stream.respond_to?(:<<) || stream == true
-      req = Net::HTTP::Post.new("/v1/messages", headers)
-      messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
-      body = LLM.json.dump({messages: [adapt(messages)].flatten}.merge!(params))
-      set_body_stream(req, StringIO.new(body))
-      res = execute(request: req, stream:)
+      params, stream, tools, role = normalize_complete_params(params)
+      req = build_complete_request(prompt, params, role)
+      res = execute(request: req, stream: stream)
       ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
     end
@@ -131,5 +124,22 @@ module LLM
     def error_handler
       LLM::Anthropic::ErrorHandler
     end
+
+    def normalize_complete_params(params)
+      params = {role: :user, model: default_model, max_tokens: 1024}.merge!(params)
+      tools = resolve_tools(params.delete(:tools))
+      params = [params, adapt_tools(tools)].inject({}, &:merge!).compact
+      role, stream = params.delete(:role), params.delete(:stream)
+      params[:stream] = true if stream.respond_to?(:<<) || stream == true
+      [params, stream, tools, role]
+    end
+
+    def build_complete_request(prompt, params, role)
+      messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      body = LLM.json.dump({messages: [adapt(messages)].flatten}.merge!(params))
+      req = Net::HTTP::Post.new("/v1/messages", headers)
+      set_body_stream(req, StringIO.new(body))
+      req
+    end
   end
 end

data/lib/llm/providers/gemini/response_adapter/completion.rb

@@ -21,6 +21,12 @@ module LLM::Gemini::ResponseAdapter
       body.usageMetadata.candidatesTokenCount || 0
     end
 
+    ##
+    # (see LLM::Contract::Completion#reasoning_tokens)
+    def reasoning_tokens
+      body.usageMetadata.thoughtsTokenCount || 0
+    end
+
     ##
     # (see LLM::Contract::Completion#total_tokens)
     def total_tokens

data/lib/llm/providers/gemini/stream_parser.rb

@@ -104,6 +104,10 @@ class LLM::Gemini
       delta_call = delta["functionCall"]
       if last_call.is_a?(Hash) && delta_call.is_a?(Hash)
         last_existing_part["functionCall"] = last_call.merge(delta_call)
+        delta.each do |key, value|
+          next if key == "functionCall"
+          last_existing_part[key] = value
+        end
       else
         parts << delta
       end

data/lib/llm/providers/gemini.rb

@@ -64,18 +64,9 @@ module LLM
     #  When given an object a provider does not understand
     # @return [LLM::Response]
     def complete(prompt, params = {})
-      params = {role: :user, model: default_model}.merge!(params)
-      tools  = resolve_tools(params.delete(:tools))
-      params = [params, adapt_schema(params), adapt_tools(tools)].inject({}, &:merge!).compact
-      role, model, stream = [:role, :model, :stream].map { params.delete(_1) }
-      action = stream ? "streamGenerateContent?key=#{@key}&alt=sse" : "generateContent?key=#{@key}"
-      model.respond_to?(:id) ? model.id : model
-      path = ["/v1beta/models/#{model}", action].join(":")
-      req  = Net::HTTP::Post.new(path, headers)
-      messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
-      body = LLM.json.dump({contents: adapt(messages)}.merge!(params))
-      set_body_stream(req, StringIO.new(body))
-      res = execute(request: req, stream:)
+      params, stream, tools, role, model = normalize_complete_params(params)
+      req = build_complete_request(prompt, params, role, model, stream)
+      res = execute(request: req, stream: stream)
       ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
     end
@@ -165,5 +156,24 @@ module LLM
     def error_handler
       LLM::Gemini::ErrorHandler
     end
+
+    def normalize_complete_params(params)
+      params = {role: :user, model: default_model}.merge!(params)
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, adapt_schema(params), adapt_tools(tools)].inject({}, &:merge!).compact
+      role, model, stream = [:role, :model, :stream].map { params.delete(_1) }
+      [params, stream, tools, role, model]
+    end
+
+    def build_complete_request(prompt, params, role, model, stream)
+      action = stream ? "streamGenerateContent?key=#{@key}&alt=sse" : "generateContent?key=#{@key}"
+      model.respond_to?(:id) ? model.id : model
+      path = ["/v1beta/models/#{model}", action].join(":")
+      req  = Net::HTTP::Post.new(path, headers)
+      messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
+      body = LLM.json.dump({contents: adapt(messages)}.merge!(params))
+      set_body_stream(req, StringIO.new(body))
+      req
+    end
   end
 end

data/lib/llm/providers/ollama/response_adapter/completion.rb

@@ -21,6 +21,12 @@ module LLM::Ollama::ResponseAdapter
       body.eval_count || 0
     end
 
+    ##
+    # (see LLM::Contract::Completion#reasoning_tokens)
+    def reasoning_tokens
+      0
+    end
+
     ##
     # (see LLM::Contract::Completion#total_tokens)
     def total_tokens

data/lib/llm/providers/ollama.rb

@@ -58,16 +58,9 @@ module LLM
     #  When given an object a provider does not understand
     # @return [LLM::Response]
     def complete(prompt, params = {})
-      params = {role: :user, model: default_model, stream: true}.merge!(params)
-      tools  = resolve_tools(params.delete(:tools))
-      params = [params, {format: params[:schema]}, adapt_tools(tools)].inject({}, &:merge!).compact
-      role, stream = params.delete(:role), params.delete(:stream)
-      params[:stream] = true if stream.respond_to?(:<<) || stream == true
-      req = Net::HTTP::Post.new("/api/chat", headers)
-      messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
-      body = LLM.json.dump({messages: [adapt(messages)].flatten}.merge!(params))
-      set_body_stream(req, StringIO.new(body))
-      res = execute(request: req, stream:)
+      params, stream, tools, role = normalize_complete_params(params)
+      req = build_complete_request(prompt, params, role)
+      res = execute(request: req, stream: stream)
       ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
     end
@@ -110,5 +103,22 @@ module LLM
     def error_handler
       LLM::Ollama::ErrorHandler
     end
+
+    def normalize_complete_params(params)
+      params = {role: :user, model: default_model, stream: true}.merge!(params)
+      tools  = resolve_tools(params.delete(:tools))
+      params = [params, {format: params[:schema]}, adapt_tools(tools)].inject({}, &:merge!).compact
+      role, stream = params.delete(:role), params.delete(:stream)
+      params[:stream] = true if stream.respond_to?(:<<) || stream == true
+      [params, stream, tools, role]
+    end
+
+    def build_complete_request(prompt, params, role)
+      messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
+      body = LLM.json.dump({messages: [adapt(messages)].flatten}.merge!(params))
+      req = Net::HTTP::Post.new("/api/chat", headers)
+      set_body_stream(req, StringIO.new(body))
+      req
+    end
   end
 end

data/lib/llm/providers/openai/response_adapter/completion.rb

@@ -21,19 +21,28 @@ module LLM::OpenAI::ResponseAdapter
     ##
     # (see LLM::Contract::Completion#input_tokens)
     def input_tokens
-      body.usage["prompt_tokens"] || 0
+      body.usage&.prompt_tokens || 0
     end
 
     ##
     # (see LLM::Contract::Completion#output_tokens)
     def output_tokens
-      body.usage["completion_tokens"] || 0
+      body.usage&.completion_tokens || 0
+    end
+
+    ##
+    # (see LLM::Contract::Completion#reasoning_tokens)
+    def reasoning_tokens
+      body
+        .usage
+        &.completion_tokens_details
+        &.reasoning_tokens || 0
     end
 
     ##
     # (see LLM::Contract::Completion#total_tokens)
     def total_tokens
-      body.usage["total_tokens"] || 0
+      body.usage&.total_tokens || 0
     end
 
     ##

data/lib/llm/providers/openai/stream_parser.rb

@@ -71,7 +71,9 @@ class LLM::OpenAI
     def merge_tools!(target, tools)
       target["tool_calls"] ||= []
       tools.each.with_index do |toola, index|
-        toolb = target["tool_calls"][index]
+        tindex = toola["index"]
+        tindex = index unless Integer === tindex && tindex >= 0
+        toolb = target["tool_calls"][tindex]
         if toolb && toola["function"] && toolb["function"]
           # Append to existing function arguments
           toola["function"].each do |func_key, func_value|
@@ -79,7 +81,7 @@ class LLM::OpenAI
             toolb["function"][func_key] << func_value
           end
         else
-          target["tool_calls"][index] = toola
+          target["tool_calls"][tindex] = toola
         end
       end
     end

data/lib/llm/providers/openai.rb

@@ -62,17 +62,9 @@ module LLM
     #  When given an object a provider does not understand
     # @return (see LLM::Provider#complete)
     def complete(prompt, params = {})
-      params = {role: :user, model: default_model}.merge!(params)
-      tools  = resolve_tools(params.delete(:tools))
-      params = [params, adapt_schema(params), adapt_tools(tools)].inject({}, &:merge!).compact
-      role, stream = params.delete(:role), params.delete(:stream)
-      params[:stream] = true if stream.respond_to?(:<<) || stream == true
-      params[:stream_options] = {include_usage: true}.merge!(params[:stream_options] || {}) if params[:stream]
-      req = Net::HTTP::Post.new(completions_path, headers)
-      messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
-      body = LLM.json.dump({messages: adapt(messages, mode: :complete).flatten}.merge!(params))
-      set_body_stream(req, StringIO.new(body))
-      res = execute(request: req, stream:)
+      params, stream, tools, role = normalize_complete_params(params)
+      req = build_complete_request(prompt, params, role)
+      res = execute(request: req, stream: stream)
       ResponseAdapter.adapt(res, type: :completion)
         .extend(Module.new { define_method(:__tools__) { tools } })
     end
@@ -200,5 +192,25 @@ module LLM
     def error_handler
       LLM::OpenAI::ErrorHandler
     end
+
+    def normalize_complete_params(params)
+      params = {role: :user, model: default_model}.merge!(params)
+      tools = resolve_tools(params.delete(:tools))
+      params = [params, adapt_schema(params), adapt_tools(tools)].inject({}, &:merge!).compact
+      role, stream = params.delete(:role), params.delete(:stream)
+      params[:stream] = true if stream.respond_to?(:<<) || stream == true
+      if params[:stream]
+        params[:stream_options] = {include_usage: true}.merge!(params[:stream_options] || {})
+      end
+      [params, stream, tools, role]
+    end
+
+    def build_complete_request(prompt, params, role)
+      messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
+      body = LLM.json.dump({messages: adapt(messages, mode: :complete).flatten}.merge!(params))
+      req = Net::HTTP::Post.new(completions_path, headers)
+      set_body_stream(req, StringIO.new(body))
+      req
+    end
   end
 end

data/lib/llm/response.rb

@@ -26,6 +26,8 @@ module LLM
     ##
     # Returns the response body
     # @return [LLM::Object, String]
+    #  Returns an LLM::Object when the response body is JSON,
+    #  otherwise returns a raw string.
     def body
       @res.body
     end
@@ -54,11 +56,19 @@ module LLM
     private
 
     def method_missing(m, *args, **kwargs, &b)
-      body.respond_to?(m) ? body[m.to_s] : super
+      if LLM::Object === body
+        body.respond_to?(m) ? body[m.to_s] : super
+      else
+        super
+      end
     end
 
     def respond_to_missing?(m, include_private = false)
-      body.respond_to?(m) || super
+      if LLM::Object === body
+        body.respond_to?(m)
+      else
+        false
+      end
     end
   end
 end

data/lib/llm/usage.rb

@@ -4,7 +4,8 @@
 # The {LLM::Usage LLM::Usage} class represents token usage for
 # a given conversation or completion. As a conversation grows,
 # so does the number of tokens used. This class helps track
-# the number of input, output, and total tokens. It can also help
-# track usage of the context window (which may vary by model).
-class LLM::Usage < Struct.new(:input_tokens, :output_tokens, :total_tokens, keyword_init: true)
+# the number of input, output, reasoning and overall token count.
+# It can also help track usage of the context window (which may
+# vary by model).
+class LLM::Usage < Struct.new(:input_tokens, :output_tokens, :reasoning_tokens, :total_tokens, keyword_init: true)
 end

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "3.0.0"
+  VERSION = "3.1.0"
 end

data/lib/llm.rb

@@ -41,6 +41,9 @@ module LLM
 
   ##
   # Sets the JSON adapter used by the library
+  # @note
+  #  This should be set once from the main thread when your program starts.
+  #  Defaults to {LLM::JSONAdapter::JSON LLM::JSONAdapter::JSON}.
   # @param [Class, String, Symbol] adapter
   #  A JSON adapter class or its name
   # @return [void]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Antar Azri