llm.rb 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50bc0de3950bfbc8dd1a9ff3b211915fff5ae510f6fd0f0fc277e5cbf689e5ea
-  data.tar.gz: 3e48e23abefeb652429cb145be5fa1166e78cb24f3ddfb7440daff2e4a461c5d
+  metadata.gz: 3452ff48dff867c48be888eb5ae2fff97624b8e51029cd13a26844d67a7824cf
+  data.tar.gz: 51a65baeff8b026c6ea9fdda2063d14a7961dd902f94cccd34c7591f606a586f
 SHA512:
-  metadata.gz: 8b6ad1955541753ba991a0f9b55e261cb4cc32a3a85470cee7312359cafce7d4689757a2f5efe2f641c9813dca5b7722b47ff8dc12d90f8a600eff1e3c7b5b4d
-  data.tar.gz: b807543c44e12d4a251370a84cda59714a9b62cf3bf031203d723a8740167aab5a4f9348ae29856b6324384f2042d1851c05c272ba3a6510b33d99d6fddf4fdc
+  metadata.gz: a548f97a9019529146f0e6f7414239aaee5b0b6695c924f28f602de7a1ef2f390e1b0053545dab2ee6725f7dabd7a2c83e3b9181027a492630f12dda77870637
+  data.tar.gz: f71fbd16d3fb22a0ad37d59e93fc7b9e6093fc2b77ebf0e6b7eeca69cb227fd84867ab02c594c4b608ea9017eb6cc40d3fa5c2ff76ffb09fbc1a1b573823a84b

data/README.md

@@ -42,11 +42,11 @@ using an API key (if required) and an optional set of configuration options via
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai("yourapikey")
-llm = LLM.gemini("yourapikey")
-llm = LLM.anthropic("yourapikey")
-llm = LLM.ollama(nil)
-llm = LLM.voyageai("yourapikey")
+llm = LLM.openai(key: "yourapikey")
+llm = LLM.gemini(key: "yourapikey")
+llm = LLM.anthropic(key: "yourapikey")
+llm = LLM.ollama(key: nil)
+llm = LLM.voyageai(key: "yourapikey")
 ```
 
 ### Conversations
@@ -66,12 +66,12 @@ all LLM providers support:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Chat.new(llm).lazy
-bot.chat File.read("./share/llm/prompts/system.txt"), :system
-bot.chat "Tell me the answer to 5 + 15", :user
-bot.chat "Tell me the answer to (5 + 15) * 2", :user
-bot.chat "Tell me the answer to ((5 + 15) * 2) / 10", :user
+bot.chat File.read("./share/llm/prompts/system.txt"), role: :system
+bot.chat "Tell me the answer to 5 + 15", role: :user
+bot.chat "Tell me the answer to (5 + 15) * 2", role: :user
+bot.chat "Tell me the answer to ((5 + 15) * 2) / 10", role: :user
 bot.messages.each { print "[#{_1.role}] ", _1.content, "\n" }
 
 ##
@@ -106,12 +106,12 @@ for the OpenAI provider:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Chat.new(llm).lazy
-bot.respond File.read("./share/llm/prompts/system.txt"), :developer
-bot.respond "Tell me the answer to 5 + 15", :user
-bot.respond "Tell me the answer to (5 + 15) * 2", :user
-bot.respond "Tell me the answer to ((5 + 15) * 2) / 10", :user
+bot.respond File.read("./share/llm/prompts/system.txt"), role: :developer
+bot.respond "Tell me the answer to 5 + 15", role: :user
+bot.respond "Tell me the answer to (5 + 15) * 2", role: :user
+bot.respond "Tell me the answer to ((5 + 15) * 2) / 10", role: :user
 bot.messages.each { print "[#{_1.role}] ", _1.content, "\n" }
 
 ##
@@ -152,21 +152,21 @@ The interface is designed so you could drop in any other library in its place:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 schema = llm.schema.object({os: llm.schema.string.enum("OpenBSD", "FreeBSD", "NetBSD")})
 bot = LLM::Chat.new(llm, schema:)
-bot.chat "You secretly love NetBSD", :system
-bot.chat "What operating system is the best?", :user
+bot.chat "You secretly love NetBSD", role: :system
+bot.chat "What operating system is the best?", role: :user
 bot.messages.find(&:assistant?).content! # => {os: "NetBSD"}
 
 schema = llm.schema.object({answer: llm.schema.integer.required})
 bot = LLM::Chat.new(llm, schema:)
-bot.chat "Tell me the answer to ((5 + 5) / 2)", :user
+bot.chat "Tell me the answer to ((5 + 5) / 2)", role: :user
 bot.messages.find(&:assistant?).content! # => {answer: 5}
 
 schema = llm.schema.object({probability: llm.schema.number.required})
 bot = LLM::Chat.new(llm, schema:)
-bot.chat "Does the earth orbit the sun?", :user
+bot.chat "Does the earth orbit the sun?", role: :user
 bot.messages.find(&:assistant?).content! # => {probability: 1}
 ```
 
@@ -195,7 +195,7 @@ arbitrary commands from a LLM without sanitizing the input first :) Without furt
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 tool = LLM.function(:system) do |fn|
   fn.description "Run a shell command"
   fn.params do |schema|
@@ -207,12 +207,12 @@ tool = LLM.function(:system) do |fn|
 end
 
 bot = LLM::Chat.new(llm, tools: [tool]).lazy
-bot.chat "Your task is to run shell commands via a tool.", :system
+bot.chat "Your task is to run shell commands via a tool.", role: :system
 
-bot.chat "What is the current date?", :user
+bot.chat "What is the current date?", role: :user
 bot.chat bot.functions.map(&:call) # report return value to the LLM
 
-bot.chat "What operating system am I running? (short version please!)", :user
+bot.chat "What operating system am I running? (short version please!)", role: :user
 bot.chat bot.functions.map(&:call) # report return value to the LLM
 
 ##
@@ -235,7 +235,7 @@ documentation for more information on how to use the audio generation API:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 res = llm.audio.create_speech(input: "Hello world")
 IO.copy_stream res.audio, File.join(Dir.home, "hello.mp3")
 ```
@@ -252,7 +252,7 @@ documentation for more information on how to use the audio transcription API:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 res = llm.audio.create_transcription(
   file: File.join(Dir.home, "hello.mp3")
 )
@@ -272,7 +272,7 @@ the audio translation API:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 res = llm.audio.create_translation(
   file: File.join(Dir.home, "bomdia.mp3")
 )
@@ -295,7 +295,7 @@ require "llm"
 require "open-uri"
 require "fileutils"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 res = llm.images.create(prompt: "a dog on a rocket to the moon")
 res.urls.each do |url|
   FileUtils.mv OpenURI.open_uri(url).path,
@@ -320,7 +320,7 @@ require "llm"
 require "open-uri"
 require "fileutils"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 res = llm.images.edit(
   image: "/images/cat.png",
   prompt: "a cat with a hat",
@@ -345,7 +345,7 @@ require "llm"
 require "open-uri"
 require "fileutils"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 res = llm.images.create_variation(
   image: "/images/cat.png",
   n: 5
@@ -373,7 +373,7 @@ can be given to the chat method:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Chat.new(llm).lazy
 file = llm.files.create(file: "/documents/openbsd_is_awesome.pdf")
 bot.chat(file)
@@ -404,7 +404,7 @@ to a prompt:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Chat.new(llm).lazy
 
 bot.chat [URI("https://example.com/path/to/image.png"), "Describe the image in the link"]
@@ -439,7 +439,7 @@ which will go on to generate a response:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.openai(ENV["KEY"])
+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"
@@ -470,7 +470,7 @@ require "llm"
 
 ##
 # List all models
-llm = LLM.openai(ENV["KEY"])
+llm = LLM.openai(key: ENV["KEY"])
 llm.models.all.each do |model|
   print "model: ", model.id, "\n"
 end
@@ -501,7 +501,7 @@ demonstrates how that might look like in practice:
 #!/usr/bin/env ruby
 require "llm"
 
-llm = LLM.gemini(ENV["KEY"])
+llm = LLM.gemini(key: ENV["KEY"])
 fork do
   %w[dog cat sheep goat capybara].each do |animal|
     res = llm.images.create(prompt: "a #{animal} on a rocket to the moon")
@@ -545,6 +545,16 @@ llm.rb can be installed via rubygems.org:
 
 	gem install llm.rb
 
+## See also
+
+**[llmrb/llm-shell](https://github.com/llmrb/llm-shell)**
+
+An extensible, developer-oriented command line utility that is powered by
+llm.rb and serves as a demonstration of the library's capabilities. The
+[demo](https://github.com/llmrb/llm-shell#demos) section has a number of GIF
+previews might be especially interesting!
+
+
 ## Philosophy
 
 llm.rb provides a clean, dependency-free interface to Large Language Models,

data/lib/llm/buffer.rb

@@ -77,10 +77,10 @@ module LLM
     def complete!(message, params)
       pendings = @pending.map { _1[0] }
       messages = [*@completed, *pendings]
+      role = message.role
       completion = @provider.complete(
         message.content,
-        message.role,
-        **params.merge(messages:)
+        params.merge(role:, messages:)
       )
       @completed.concat([*pendings, message, completion.choices[0]])
       @pending.clear
@@ -89,11 +89,12 @@ module LLM
     def respond!(message, params)
       pendings = @pending.map { _1[0] }
       input = [*pendings]
+      role = message.role
       params = [
         params.merge(input:),
         @response ? {previous_response_id: @response.id} : {}
       ].inject({}, &:merge!)
-      @response = @provider.responses.create(message.content, message.role, **params)
+      @response = @provider.responses.create(message.content, params.merge(role:))
       @completed.concat([*pendings, message, @response.outputs[0]])
       @pending.clear
     end

data/lib/llm/chat.rb

@@ -13,11 +13,10 @@ module LLM
   #
   #   llm = LLM.openai(ENV["KEY"])
   #   bot = LLM::Chat.new(llm).lazy
-  #   bot.chat("Your task is to answer all of my questions", :system)
-  #   bot.chat("Your answers should be short and concise", :system)
-  #   bot.chat("What is 5 + 7 ?", :user)
-  #   bot.chat("Why is the sky blue ?", :user)
-  #   bot.chat("Why did the chicken cross the road ?", :user)
+  #   bot.chat("Provide short and concise answers", role: :system)
+  #   bot.chat("What is 5 + 7 ?", role: :user)
+  #   bot.chat("Why is the sky blue ?", role: :user)
+  #   bot.chat("Why did the chicken cross the road ?", role: :user)
   #   bot.messages.map { print "[#{_1.role}]", _1.content, "\n" }
   class Chat
     ##
@@ -27,31 +26,34 @@ module LLM
     ##
     # @param [LLM::Provider] provider
     #  A provider
-    # @param [to_json] schema
-    #  The JSON schema to maintain throughout the conversation
-    # @param [String] model
-    #  The model to maintain throughout the conversation
     # @param [Hash] params
-    #  Other parameters to maintain throughout the conversation
-    def initialize(provider, model: provider.default_model, schema: nil, **params)
+    #  The parameters to maintain throughout the conversation.
+    #  Any parameter the provider supports can be included and
+    #  not only those listed here.
+    # @option params [String] :model Defaults to the provider's default model
+    # @option params [#to_json, nil] :schema Defaults to nil
+    # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
+    def initialize(provider, params = {})
       @provider = provider
-      @params = params.merge!(model:, schema:)
+      @params = {model: provider.default_model, schema: nil}.compact.merge!(params)
       @lazy = false
       @messages = [].extend(Array)
     end
 
     ##
     # Maintain a conversation via the chat completions API
-    # @param prompt (see LLM::Provider#prompt)
-    # @param role (see LLM::Provider#prompt)
-    # @param params (see LLM::Provider#prompt)
+    # @param prompt (see LLM::Provider#complete)
+    # @param params (see LLM::Provider#complete)
     # @return [LLM::Chat]
-    def chat(prompt, role = :user, **params)
+    def chat(prompt, params = {})
+      params = {role: :user}.merge!(params)
       if lazy?
+        role = params.delete(:role)
         @messages << [LLM::Message.new(role, prompt), @params.merge(params), :complete]
         self
       else
-        completion = complete!(prompt, role, params)
+        role = params[:role]
+        completion = complete!(prompt, params)
         @messages.concat [Message.new(role, prompt), completion.choices[0]]
         self
       end
@@ -60,16 +62,18 @@ module LLM
     ##
     # Maintain a conversation via the responses API
     # @note Not all LLM providers support this API
-    # @param prompt (see LLM::Provider#prompt)
-    # @param role (see LLM::Provider#prompt)
-    # @param params (see LLM::Provider#prompt)
+    # @param prompt (see LLM::Provider#complete)
+    # @param params (see LLM::Provider#complete)
     # @return [LLM::Chat]
-    def respond(prompt, role = :user, **params)
+    def respond(prompt, params = {})
+      params = {role: :user}.merge!(params)
       if lazy?
+        role = params.delete(:role)
         @messages << [LLM::Message.new(role, prompt), @params.merge(params), :respond]
         self
       else
-        @response = respond!(prompt, role, params)
+        role = params[:role]
+        @response = respond!(prompt, params)
         @messages.concat [Message.new(role, prompt), @response.outputs[0]]
         self
       end
@@ -141,19 +145,17 @@ module LLM
     end
     private_constant :Array
 
-    def respond!(prompt, role, params)
+    def respond!(prompt, params)
       @provider.responses.create(
         prompt,
-        role,
-        **@params.merge(params.merge(@response ? {previous_response_id: @response.id} : {}))
+        @params.merge(params.merge(@response ? {previous_response_id: @response.id} : {}))
       )
     end
 
-    def complete!(prompt, role, params)
+    def complete!(prompt, params)
       @provider.complete(
         prompt,
-        role,
-        **@params.merge(params.merge(messages:))
+        @params.merge(params.merge(messages:))
       )
     end
   end

data/lib/llm/function.rb

@@ -4,6 +4,11 @@ class LLM::Function
   class Return < Struct.new(:id, :value)
   end
 
+  ##
+  # Returns the function name
+  # @return [String]
+  attr_reader :name
+
   ##
   # Returns function arguments
   # @return [Array, nil]

data/lib/llm/message.rb

@@ -57,13 +57,6 @@ module LLM
       JSON.parse(content)
     end
 
-    ##
-    # Returns true when the message is from the LLM
-    # @return [Boolean]
-    def assistant?
-      role == "assistant" || role == "model"
-    end
-
     ##
     # @return [Array<LLM::Function>]
     def functions
@@ -75,10 +68,24 @@ module LLM
     end
 
     ##
+    # Marks the message as read
+    # @return [void]
+    def read!
+      @read = true
+    end
+
+    ##
+    # Returns true when the message has been read
     # @return [Boolean]
-    #  Returns true when the message requests a function call
-    def tool_call?
-      tool_calls.any?
+    def read?
+      @read
+    end
+
+    ##
+    # Returns true when the message is an assistant message
+    # @return [Boolean]
+    def assistant?
+      role == "assistant" || role == "model"
     end
 
     ##
@@ -89,17 +96,17 @@ module LLM
     end
 
     ##
-    # Marks the message as read
-    # @return [void]
-    def read!
-      @read = true
+    # Returns true when the message is a user message
+    # @return [Boolean]
+    def user?
+      role == "user"
     end
 
     ##
-    # Returns true when the message has been read
     # @return [Boolean]
-    def read?
-      @read
+    #  Returns true when the message requests a function call
+    def tool_call?
+      tool_calls.any?
     end
 
     ##

data/lib/llm/provider.rb

@@ -9,7 +9,7 @@ class LLM::Provider
   require "net/http"
 
   ##
-  # @param [String] secret
+  # @param [String, nil] key
   #  The secret key for authentication
   # @param [String] host
   #  The host address of the LLM provider
@@ -17,8 +17,10 @@ class LLM::Provider
   #  The port number
   # @param [Integer] timeout
   #  The number of seconds to wait for a response
-  def initialize(secret, host:, port: 443, timeout: 60, ssl: true)
-    @secret = secret
+  # @param [Boolean] ssl
+  #  Whether to use SSL for the connection
+  def initialize(key:, host:, port: 443, timeout: 60, ssl: true)
+    @key = key
     @http = Net::HTTP.new(host, port).tap do |http|
       http.use_ssl = ssl
       http.read_timeout = timeout
@@ -30,7 +32,7 @@ class LLM::Provider
   # @return [String]
   # @note The secret key is redacted in inspect for security reasons
   def inspect
-    "#<#{self.class.name}:0x#{object_id.to_s(16)} @secret=[REDACTED] @http=#{@http.inspect}>"
+    "#<#{self.class.name}:0x#{object_id.to_s(16)} @key=[REDACTED] @http=#{@http.inspect}>"
   end
 
   ##
@@ -52,26 +54,23 @@ class LLM::Provider
   # Provides an interface to the chat completions API
   # @example
   #   llm = LLM.openai(ENV["KEY"])
-  #   messages = [
-  #     {role: "system", content: "Your task is to answer all of my questions"},
-  #     {role: "system", content: "Your answers should be short and concise"},
-  #   ]
-  #   res = llm.complete("Hello. What is the answer to 5 + 2 ?", :user, messages:)
+  #   messages = [{role: "system", content: "Your task is to answer all of my questions"}]
+  #   res = llm.complete("5 + 2 ?", messages:)
   #   print "[#{res.choices[0].role}]", res.choices[0].content, "\n"
   # @param [String] prompt
   #  The input prompt to be completed
-  # @param [Symbol] role
-  #  The role of the prompt (e.g. :user, :system)
-  # @param [String] model
-  #  The model to use for the completion
-  # @param [#to_json, nil] schema
-  #  The schema that describes the expected response format
   # @param [Hash] params
-  #  Other completion parameters
+  #  The parameters to maintain throughout the conversation.
+  #  Any parameter the provider supports can be included and
+  #  not only those listed here.
+  # @option params [Symbol] :role Defaults to the provider's default role
+  # @option params [String] :model Defaults to the provider's default model
+  # @option params [#to_json, nil] :schema Defaults to nil
+  # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Completion]
-  def complete(prompt, role = :user, model: default_model, schema: nil, **params)
+  def complete(prompt, params = {})
     raise NotImplementedError
   end
 
@@ -81,15 +80,11 @@ class LLM::Provider
   #  This method creates a lazy version of a
   #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
-  # @param role (see LLM::Provider#complete)
-  # @param model (see LLM::Provider#complete)
-  # @param schema (see LLM::Provider#complete)
-  # @param [Hash] params
-  #  Other completion parameters to maintain throughout a chat
-  # @raise (see LLM::Provider#complete)
+  # @param params (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def chat(prompt, role = :user, model: default_model, schema: nil, **params)
-    LLM::Chat.new(self, **params.merge(model:, schema:)).lazy.chat(prompt, role)
+  def chat(prompt, params = {})
+    role = params.delete(:role)
+    LLM::Chat.new(self, params).lazy.chat(prompt, role:)
   end
 
   ##
@@ -98,15 +93,12 @@ class LLM::Provider
   #  This method creates a non-lazy version of a
   #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
-  # @param role (see LLM::Provider#complete)
-  # @param model (see LLM::Provider#complete)
-  # @param schema (see LLM::Provider#complete)
-  # @param [Hash] params
-  #  Other completion parameters to maintain throughout a chat
+  # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def chat!(prompt, role = :user, model: default_model, schema: nil, **params)
-    LLM::Chat.new(self, **params.merge(model:, schema:)).chat(prompt, role)
+  def chat!(prompt, params = {})
+    role = params.delete(:role)
+    LLM::Chat.new(self, params).chat(prompt, role:)
   end
 
   ##
@@ -115,15 +107,12 @@ class LLM::Provider
   #  This method creates a lazy variant of a
   #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
-  # @param role (see LLM::Provider#complete)
-  # @param model (see LLM::Provider#complete)
-  # @param schema (see LLM::Provider#complete)
-  # @param [Hash] params
-  #  Other completion parameters to maintain throughout a chat
+  # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def respond(prompt, role = :user, model: default_model, schema: nil, **params)
-    LLM::Chat.new(self, **params.merge(model:, schema:)).lazy.respond(prompt, role)
+  def respond(prompt, params = {})
+    role = params.delete(:role)
+    LLM::Chat.new(self, params).lazy.respond(prompt, role:)
   end
 
   ##
@@ -132,15 +121,12 @@ class LLM::Provider
   #  This method creates a non-lazy variant of a
   #  {LLM::Chat LLM::Chat} object.
   # @param prompt (see LLM::Provider#complete)
-  # @param role (see LLM::Provider#complete)
-  # @param model (see LLM::Provider#complete)
-  # @param schema (see LLM::Provider#complete)
-  # @param [Hash] params
-  #  Other completion parameters to maintain throughout a chat
+  # @param params (see LLM::Provider#complete)
   # @raise (see LLM::Provider#complete)
   # @return [LLM::Chat]
-  def respond!(prompt, role = :user, model: default_model, schema: nil, **params)
-    LLM::Chat.new(self, **params.merge(model:, schema:)).respond(prompt, role)
+  def respond!(prompt, params = {})
+    role = params.delete(:role)
+    LLM::Chat.new(self, params).respond(prompt, role:)
   end
 
   ##

data/lib/llm/providers/anthropic/format/completion_format.rb

@@ -60,7 +60,7 @@ module LLM::Anthropic::Format
       when LLM::Message
         format_content(content.content)
       when LLM::Function::Return
-        {type: "tool_result", tool_use_id: content.id, content: content.value}
+        [{type: "tool_result", tool_use_id: content.id, content: [{type: :text, text: JSON.dump(content.value)}]}]
       else
         raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
                                        "is not supported by the Anthropic API"

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

@@ -18,8 +18,9 @@ class LLM::Anthropic
 
     private
 
-    def format_tools(tools)
-      return {} unless tools
+    def format_tools(params)
+      return {} unless params and params[:tools]&.any?
+      tools = params[:tools]
       {tools: tools.map { _1.format(self) }}
     end
   end

data/lib/llm/providers/anthropic.rb

@@ -15,25 +15,25 @@ module LLM
     HOST = "api.anthropic.com"
 
     ##
-    # @param secret (see LLM::Provider#initialize)
-    def initialize(secret, **)
-      super(secret, host: HOST, **)
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, **)
     end
 
     ##
     # Provides an embedding via VoyageAI per
     # [Anthropic's recommendation](https://docs.anthropic.com/en/docs/build-with-claude/embeddings)
     # @param input (see LLM::Provider#embed)
-    # @param [String] token
-    #  Valid token for the VoyageAI API
+    # @param [String] key
+    #  Valid key for the VoyageAI API
     # @param [String] model
     #  The embedding model to use
     # @param [Hash] params
     #  Other embedding parameters
     # @raise (see LLM::Provider#request)
     # @return (see LLM::Provider#embed)
-    def embed(input, token:, model: "voyage-2", **params)
-      llm = LLM.voyageai(token)
+    def embed(input, key:, model: "voyage-2", **params)
+      llm = LLM.voyageai(key:)
       llm.embed(input, **params.merge(model:))
     end
 
@@ -41,17 +41,16 @@ module LLM
     # Provides an interface to the chat completions API
     # @see https://docs.anthropic.com/en/api/messages Anthropic docs
     # @param prompt (see LLM::Provider#complete)
-    # @param role (see LLM::Provider#complete)
-    # @param model (see LLM::Provider#complete)
-    # @param max_tokens The maximum number of tokens to generate
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
     # @raise (see LLM::Provider#request)
     # @raise [LLM::Error::PromptError]
     #  When given an object a provider does not understand
     # @return (see LLM::Provider#complete)
-    def complete(prompt, role = :user, model: default_model, max_tokens: 1024, tools: nil, **params)
-      params = [{max_tokens:, model:}, format_tools(tools), params].inject({}, &:merge!).compact
+    def complete(prompt, params = {})
+      params = {role: :user, model: default_model, max_tokens: 1024}.merge!(params)
+      params = [params, format_tools(params)].inject({}, &:merge!).compact
+      role = params.delete(:role)
       req = Net::HTTP::Post.new("/v1/messages", headers)
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
       body = JSON.dump({messages: [format(messages)].flatten}.merge!(params))
@@ -87,7 +86,7 @@ module LLM
     def headers
       {
         "Content-Type" => "application/json",
-        "x-api-key" => @secret,
+        "x-api-key" => @key,
         "anthropic-version" => "2023-06-01"
       }
     end

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

@@ -9,7 +9,7 @@ class LLM::Gemini
   #   require "llm"
   #
   #   llm = LLM.gemini(ENV["KEY"])
-  #   res = llm.audio.create_transcription(input: LLM::File("/rocket.mp3"))
+  #   res = llm.audio.create_transcription(input: "/audio/rocket.mp3")
   #   res.text # => "A dog on a rocket to the moon"
   class Audio
     ##
@@ -31,7 +31,7 @@ class LLM::Gemini
     # Create an audio transcription
     # @example
     #   llm = LLM.gemini(ENV["KEY"])
-    #   res = llm.audio.create_transcription(file: LLM::File("/rocket.mp3"))
+    #   res = llm.audio.create_transcription(file: "/audio/rocket.mp3")
     #   res.text # => "A dog on a rocket to the moon"
     # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs
     # @param [String, LLM::File, LLM::Response::File] file The input audio
@@ -44,7 +44,7 @@ class LLM::Gemini
         "Your task is to transcribe the contents of an audio file",
         "Your response should include the transcription, and nothing else",
         LLM.File(file)
-      ], :user, model:, **params
+      ], params.merge(role: :user, model:)
       LLM::Response::AudioTranscription
         .new(res)
         .tap { _1.text = res.choices[0].content }
@@ -55,7 +55,7 @@ class LLM::Gemini
     # @example
     #   # Arabic => English
     #   llm = LLM.gemini(ENV["KEY"])
-    #   res = llm.audio.create_translation(file: LLM::File("/bismillah.mp3"))
+    #   res = llm.audio.create_translation(file: "/audio/bismillah.mp3")
     #   res.text # => "In the name of Allah, the Beneficent, the Merciful."
     # @see https://ai.google.dev/gemini-api/docs/audio Gemini docs
     # @param [String, LLM::File, LLM::Response::File] file The input audio
@@ -68,7 +68,7 @@ class LLM::Gemini
         "Your task is to translate the contents of an audio file into English",
         "Your response should include the translation, and nothing else",
         LLM.File(file)
-      ], :user, model:, **params
+      ], params.merge(role: :user, model:)
       LLM::Response::AudioTranslation
         .new(res)
         .tap { _1.text = res.choices[0].content }

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

@@ -55,7 +55,7 @@ class LLM::Gemini
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response::FileList]
     def all(**params)
-      query = URI.encode_www_form(params.merge!(key: secret))
+      query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/files?#{query}", headers)
       res = request(http, req)
       LLM::Response::FileList.new(res).tap { |filelist|
@@ -103,7 +103,7 @@ class LLM::Gemini
     # @return [LLM::Response::File]
     def get(file:, **params)
       file_id = file.respond_to?(:name) ? file.name : file.to_s
-      query = URI.encode_www_form(params.merge!(key: secret))
+      query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/#{file_id}?#{query}", headers)
       res = request(http, req)
       LLM::Response::File.new(res)
@@ -121,7 +121,7 @@ class LLM::Gemini
     # @return [LLM::Response::File]
     def delete(file:, **params)
       file_id = file.respond_to?(:name) ? file.name : file.to_s
-      query = URI.encode_www_form(params.merge!(key: secret))
+      query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Delete.new("/v1beta/#{file_id}?#{query}", headers)
       request(http, req)
     end
@@ -138,7 +138,7 @@ class LLM::Gemini
     include LLM::Utils
 
     def request_upload_url(file:)
-      req = Net::HTTP::Post.new("/upload/v1beta/files?key=#{secret}", headers)
+      req = Net::HTTP::Post.new("/upload/v1beta/files?key=#{key}", headers)
       req["X-Goog-Upload-Protocol"] = "resumable"
       req["X-Goog-Upload-Command"] = "start"
       req["X-Goog-Upload-Header-Content-Length"] = file.bytesize
@@ -152,8 +152,8 @@ class LLM::Gemini
       @provider.instance_variable_get(:@http)
     end
 
-    def secret
-      @provider.instance_variable_get(:@secret)
+    def key
+      @provider.instance_variable_get(:@key)
     end
 
     [:headers, :request, :set_body_stream].each do |m|

data/lib/llm/providers/gemini/format/completion_format.rb

@@ -41,7 +41,7 @@ module LLM::Gemini::Format
       when LLM::Message
         format_content(content.content)
       when LLM::Function::Return
-        [{text: content.value}]
+        [{text: JSON.dump(content.value)}]
       else
         raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
                                        "is not supported by the Gemini API"

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

@@ -22,28 +22,20 @@ class LLM::Gemini
     # @param [JSON::Schema] schema
     #  The schema to format
     # @return [Hash]
-    def format_schema(schema)
-      return {} unless schema
-      {
-        "generationConfig" => {
-          "response_mime_type" => "application/json",
-          "response_schema" => schema
-        }
-      }
+    def format_schema(params)
+      return {} unless params and params[:schema]
+      schema = params.delete(:schema)
+      {generationConfig: {response_mime_type: "application/json", response_schema: schema}}
     end
 
     ##
     # @param [Array<LLM::Function>] tools
     #  The tools to format
     # @return [Hash]
-    def format_tools(tools)
-      return {} unless tools
-      functions = tools.grep(LLM::Function)
-      {
-        "tools" => {
-          "functionDeclarations" => functions.map { _1.format(self) }
-        }
-      }
+    def format_tools(params)
+      return {} unless params and params[:tools]&.any?
+      functions = params.delete(:tools).grep(LLM::Function)
+      {tools: {functionDeclarations: functions.map { _1.format(self) }}}
     end
   end
 end

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

@@ -41,7 +41,7 @@ class LLM::Gemini
     #  Gemini implements image generation under the hood.
     # @return [LLM::Response::Image]
     def create(prompt:, model: "gemini-2.0-flash-exp-image-generation", **params)
-      req  = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{secret}", headers)
+      req  = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
       body = JSON.dump({
         contents: [{parts: {text: prompt}}],
         generationConfig: {responseModalities: ["TEXT", "IMAGE"]}
@@ -65,7 +65,7 @@ class LLM::Gemini
     # @note (see LLM::Gemini::Images#create)
     # @return [LLM::Response::Image]
     def edit(image:, prompt:, model: "gemini-2.0-flash-exp-image-generation", **params)
-      req   = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{secret}", headers)
+      req   = Net::HTTP::Post.new("/v1beta/models/#{model}:generateContent?key=#{key}", headers)
       image = LLM.File(image)
       body  = JSON.dump({
         contents: [{parts: [{text: prompt}, format.format_content(image)]}],
@@ -89,8 +89,8 @@ class LLM::Gemini
       @format ||= CompletionFormat.new(nil)
     end
 
-    def secret
-      @provider.instance_variable_get(:@secret)
+    def key
+      @provider.instance_variable_get(:@key)
     end
 
     def http

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

@@ -40,7 +40,7 @@ class LLM::Gemini
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response::ModelList]
     def all(**params)
-      query = URI.encode_www_form(params.merge!(key: secret))
+      query = URI.encode_www_form(params.merge!(key: key))
       req = Net::HTTP::Get.new("/v1beta/models?#{query}", headers)
       res = request(http, req)
       LLM::Response::ModelList.new(res).tap { |modellist|
@@ -58,8 +58,8 @@ class LLM::Gemini
       @provider.instance_variable_get(:@http)
     end
 
-    def secret
-      @provider.instance_variable_get(:@secret)
+    def key
+      @provider.instance_variable_get(:@key)
     end
 
     [:headers, :request].each do |m|

data/lib/llm/providers/gemini.rb

@@ -40,9 +40,9 @@ module LLM
     HOST = "generativelanguage.googleapis.com"
 
     ##
-    # @param secret (see LLM::Provider#initialize)
-    def initialize(secret, **)
-      super(secret, host: HOST, **)
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, **)
     end
 
     ##
@@ -54,7 +54,7 @@ module LLM
     # @return (see LLM::Provider#embed)
     def embed(input, model: "text-embedding-004", **params)
       model = model.respond_to?(:id) ? model.id : model
-      path = ["/v1beta/models/#{model}", "embedContent?key=#{@secret}"].join(":")
+      path = ["/v1beta/models/#{model}", "embedContent?key=#{@key}"].join(":")
       req = Net::HTTP::Post.new(path, headers)
       req.body = JSON.dump({content: {parts: [{text: input}]}})
       res = request(@http, req)
@@ -65,19 +65,18 @@ module LLM
     # Provides an interface to the chat completions API
     # @see https://ai.google.dev/api/generate-content#v1beta.models.generateContent Gemini docs
     # @param prompt (see LLM::Provider#complete)
-    # @param role (see LLM::Provider#complete)
-    # @param model (see LLM::Provider#complete)
-    # @param schema (see LLM::Provider#complete)
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
     # @raise (see LLM::Provider#request)
     # @raise [LLM::Error::PromptError]
     #  When given an object a provider does not understand
     # @return (see LLM::Provider#complete)
-    def complete(prompt, role = :user, model: default_model, schema: nil, tools: nil, **params)
-      params = [format_schema(schema), format_tools(tools), params].inject({}, &:merge!).compact
+    def complete(prompt, params = {})
+      params = {role: :user, model: default_model}.merge!(params)
+      params = [params, format_schema(params), format_tools(params)].inject({}, &:merge!).compact
+      role, model = [:role, :model].map { params.delete(_1) }
       model.respond_to?(:id) ? model.id : model
-      path = ["/v1beta/models/#{model}", "generateContent?key=#{@secret}"].join(":")
+      path = ["/v1beta/models/#{model}", "generateContent?key=#{@key}"].join(":")
       req  = Net::HTTP::Post.new(path, headers)
       messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
       body = JSON.dump({contents: format(messages)}.merge!(params))

data/lib/llm/providers/ollama/format.rb

@@ -22,8 +22,9 @@ class LLM::Ollama
     # @param [Array<LLM::Function>] tools
     #  The tools to format
     # @return [Hash]
-    def format_tools(tools)
-      return {} unless tools
+    def format_tools(params)
+      return {} unless params and params[:tools]&.any?
+      tools = params[:tools]
       {tools: tools.map { _1.format(self) }}
     end
   end

data/lib/llm/providers/ollama.rb

@@ -28,9 +28,9 @@ module LLM
     HOST = "localhost"
 
     ##
-    # @param secret (see LLM::Provider#initialize)
-    def initialize(secret, **)
-      super(secret, host: HOST, port: 11434, ssl: false, **)
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, port: 11434, ssl: false, **)
     end
 
     ##
@@ -52,16 +52,16 @@ module LLM
     # Provides an interface to the chat completions API
     # @see https://github.com/ollama/ollama/blob/main/docs/api.md#generate-a-chat-completion Ollama docs
     # @param prompt (see LLM::Provider#complete)
-    # @param role (see LLM::Provider#complete)
-    # @param model (see LLM::Provider#complete)
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
     # @raise (see LLM::Provider#request)
     # @raise [LLM::Error::PromptError]
     #  When given an object a provider does not understand
     # @return (see LLM::Provider#complete)
-    def complete(prompt, role = :user, model: default_model, schema: nil, tools: nil, **params)
-      params = [{model:, stream: false, format: schema}, format_tools(tools), params].inject({}, &:merge!).compact
+    def complete(prompt, params = {})
+      params = {role: :user, model: default_model, stream: false}.merge!(params)
+      params = [params, {format: params[:schema]}, format_tools(params)].inject({}, &:merge!).compact
+      role = params.delete(:role)
       req = Net::HTTP::Post.new("/api/chat", headers)
       messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
       body = JSON.dump({messages: [format(messages)].flatten}.merge!(params))
@@ -97,7 +97,7 @@ module LLM
     def headers
       {
         "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{@secret}"
+        "Authorization" => "Bearer #{@key}"
       }
     end
 

data/lib/llm/providers/openai/format/completion_format.rb

@@ -40,6 +40,8 @@ module LLM::OpenAI::Format
         [{type: :text, text: content.to_s}]
       when LLM::Message
         format_content(content.content)
+      when LLM::Function::Return
+        throw(:abort, {role: "tool", tool_call_id: content.id, content: JSON.dump(content.value)})
       else
         raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
                                        "is not supported by the OpenAI chat completions API"

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

@@ -29,8 +29,9 @@ class LLM::OpenAI
     # @param [JSON::Schema] schema
     #  The schema to format
     # @return [Hash]
-    def format_schema(schema)
-      return {} unless schema
+    def format_schema(params)
+      return {} unless params and params[:schema]
+      schema = params.delete(:schema)
       {
         response_format: {
           type: "json_schema",
@@ -43,8 +44,9 @@ class LLM::OpenAI
     # @param [Array<LLM::Function>] tools
     #  The tools to format
     # @return [Hash]
-    def format_tools(tools)
-      return {} unless tools
+    def format_tools(params)
+      return {} unless params and params[:tools]&.any?
+      tools = params[:tools]
       {tools: tools.map { _1.format(self) }}
     end
   end

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

@@ -45,15 +45,15 @@ class LLM::OpenAI
     # Create a response
     # @see https://platform.openai.com/docs/api-reference/responses/create OpenAI docs
     # @param prompt (see LLM::Provider#complete)
-    # @param role (see LLM::Provider#complete)
-    # @param model (see LLM::Provider#complete)
-    # @param [Hash] params Response params
+    # @param params (see LLM::Provider#complete)
     # @raise (see LLM::Provider#request)
     # @raise [LLM::Error::PromptError]
     #  When given an object a provider does not understand
     # @return [LLM::Response::Output]
-    def create(prompt, role = :user, model: @provider.default_model, schema: nil, tools: nil, **params)
-      params = [{model:}, format_schema(schema), format_tools(tools), params].inject({}, &:merge!).compact
+    def create(prompt, params = {})
+      params = {role: :user, model: @provider.default_model}.merge!(params)
+      params = [params, format_schema(params), format_tools(params)].inject({}, &:merge!).compact
+      role = params.delete(:role)
       req = Net::HTTP::Post.new("/v1/responses", headers)
       messages = [*(params.delete(:input) || []), LLM::Message.new(role, prompt)]
       body = JSON.dump({input: [format(messages, :response)].flatten}.merge!(params))

data/lib/llm/providers/openai.rb

@@ -20,9 +20,9 @@ module LLM
     HOST = "api.openai.com"
 
     ##
-    # @param secret (see LLM::Provider#initialize)
-    def initialize(secret, **)
-      super(secret, host: HOST, **)
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, **)
     end
 
     ##
@@ -44,17 +44,16 @@ module LLM
     # Provides an interface to the chat completions API
     # @see https://platform.openai.com/docs/api-reference/chat/create OpenAI docs
     # @param prompt (see LLM::Provider#complete)
-    # @param role (see LLM::Provider#complete)
-    # @param model (see LLM::Provider#complete)
-    # @param schema (see LLM::Provider#complete)
     # @param params (see LLM::Provider#complete)
     # @example (see LLM::Provider#complete)
     # @raise (see LLM::Provider#request)
     # @raise [LLM::Error::PromptError]
     #  When given an object a provider does not understand
     # @return (see LLM::Provider#complete)
-    def complete(prompt, role = :user, model: default_model, schema: nil, tools: nil, **params)
-      params = [{model:}, format_schema(schema), format_tools(tools), params].inject({}, &:merge!).compact
+    def complete(prompt, params = {})
+      params = {role: :user, model: default_model}.merge!(params)
+      params = [params, format_schema(params), format_tools(params)].inject({}, &:merge!).compact
+      role = params.delete(:role)
       req = Net::HTTP::Post.new("/v1/chat/completions", headers)
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
       body = JSON.dump({messages: format(messages, :complete).flatten}.merge!(params))
@@ -122,7 +121,7 @@ module LLM
     def headers
       {
         "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{@secret}"
+        "Authorization" => "Bearer #{@key}"
       }
     end
 

data/lib/llm/providers/voyageai.rb

@@ -7,9 +7,9 @@ module LLM
     HOST = "api.voyageai.com"
 
     ##
-    # @param secret (see LLM::Provider#initialize)
-    def initialize(secret, **)
-      super(secret, host: HOST, **)
+    # @param key (see LLM::Provider#initialize)
+    def initialize(**)
+      super(host: HOST, **)
     end
 
     ##
@@ -29,7 +29,7 @@ module LLM
     def headers
       {
         "Content-Type" => "application/json",
-        "Authorization" => "Bearer #{@secret}"
+        "Authorization" => "Bearer #{@key}"
       }
     end
 

data/lib/llm/version.rb

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

data/lib/llm.rb

@@ -23,42 +23,42 @@ module LLM
   ##
   # @param secret (see LLM::Anthropic#initialize)
   # @return (see LLM::Anthropic#initialize)
-  def anthropic(secret, options = {})
+  def anthropic(**)
     require_relative "llm/providers/anthropic" unless defined?(LLM::Anthropic)
     require_relative "llm/providers/voyageai" unless defined?(LLM::VoyageAI)
-    LLM::Anthropic.new(secret, **options)
+    LLM::Anthropic.new(**)
   end
 
   ##
   # @param secret (see LLM::VoyageAI#initialize)
   # @return (see LLM::VoyageAI#initialize)
-  def voyageai(secret, options = {})
+  def voyageai(**)
     require_relative "llm/providers/voyageai" unless defined?(LLM::VoyageAI)
-    LLM::VoyageAI.new(secret, **options)
+    LLM::VoyageAI.new(**)
   end
 
   ##
   # @param secret (see LLM::Gemini#initialize)
   # @return (see LLM::Gemini#initialize)
-  def gemini(secret, options = {})
+  def gemini(**)
     require_relative "llm/providers/gemini" unless defined?(LLM::Gemini)
-    LLM::Gemini.new(secret, **options)
+    LLM::Gemini.new(**)
   end
 
   ##
   # @param host (see LLM::Ollama#initialize)
   # @return (see LLM::Ollama#initialize)
-  def ollama(secret, options = {})
+  def ollama(key: nil, **)
     require_relative "llm/providers/ollama" unless defined?(LLM::Ollama)
-    LLM::Ollama.new(secret, **options)
+    LLM::Ollama.new(key:, **)
   end
 
   ##
   # @param secret (see LLM::OpenAI#initialize)
   # @return (see LLM::OpenAI#initialize)
-  def openai(secret, options = {})
+  def openai(**)
     require_relative "llm/providers/openai" unless defined?(LLM::OpenAI)
-    LLM::OpenAI.new(secret, **options)
+    LLM::OpenAI.new(**)
   end
 
   ##

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Antar Azri
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-04 00:00:00.000000000 Z
+date: 2025-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: webmock