llm.rb 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c55653b476d2fe6fe9457c89bc430c698668312ce89660a1d69abd8adf338eb
-  data.tar.gz: fe7d456bbb739eb091e82351839baef4c64d1d108a2c4cd7de3eb1b478982631
+  metadata.gz: 3d8311b461c49095ba393be6d3456bf7c3032a07e4480f4fd3e4cd9133f2b6e7
+  data.tar.gz: 5f9ce812a4a27e0982ea5072bca3f0494317ee0274987e57df792cc0e0d2fcfc
 SHA512:
-  metadata.gz: 8cd55bb28eb92fea745d8b11062b2442bf4b2de88ecfb0b7dc99cfefd293bd45113088dd13ccfe7e251d2e369459da700f15725bae51c3d31d4bf68e19953138
-  data.tar.gz: dab47021b94d00e51e7d0ca3f92e2966170b9fd8ce7138e0728d2be7fb83da03104ff93cd7c54b760acca62dd03adf16462069db9eb5c30185743c25259105aa
+  metadata.gz: 1d860cabe75a0718e0c06d686127d6d24c65b4dc8967aaf490b892bfad10bf88268791e9138b26e2d1c646a22e2eda7e74ad48e1fa31e9cb68c42de7ec53ac12
+  data.tar.gz: 8c2e14a316e87560e5d5dc3cdb416d151172ae12e2244bb813ff1bba61c582474607bd6920f82fa5f080e628b2dac319dd20d4f74eff55940f9c88ab7544b327

data/README.md

@@ -38,7 +38,9 @@ The following example enables lazy mode for a
 object by entering into a "lazy" conversation where messages are buffered and
 sent to the provider only when necessary.  Both lazy and non-lazy conversations
 maintain a message thread that can be reused as context throughout a conversation.
-The example uses the stateless chat completions API that all LLM providers support:
+The example captures the spirit of llm.rb by demonstrating how objects cooperate
+together through composition, and it uses the stateless chat completions API that
+all LLM providers support:
 
 ```ruby
 #!/usr/bin/env ruby
@@ -108,6 +110,46 @@ bot.messages.each { print "[#{_1.role}] ", _1.content, "\n" }
 #             The answer to ((5 + 15) * 2) / 10 is 4.
 ```
 
+### Schema
+
+#### Structured
+
+All LLM providers except Anthropic 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 (or value) an LLM should emit,
+and the LLM will abide by the schema. See also: [JSON Schema website](https://json-schema.org/overview/what-is-jsonschema).
+
+True to the llm.rb spirit of doing one thing well, and solving problems through the
+composition of objects, the generation of a schema is delegated to another object
+who is responsible for and an expert in the generation of JSON schemas. We will use
+the
+[llmrb/json-schema](https://github.com/llmrb/json-schema)
+library  for the sake of the examples - it is an optional dependency that is loaded
+on-demand. At least for the time being it is not necessary to install it separately.
+The interface is designed so you could drop in any other library in its place:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+llm = LLM.openai(ENV["KEY"])
+schema = llm.schema.object({os: llm.schema.string.enum("OpenBSD", "FreeBSD", "NetBSD").required})
+bot = LLM::Chat.new(llm, schema:)
+bot.chat "You secretly love NetBSD", :system
+bot.chat "What operating system is the best?", :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.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.messages.find(&:assistant?).content! # => {probability: 1}
+```
+
 ### Audio
 
 #### Speech
@@ -126,8 +168,7 @@ require "llm"
 
 llm = LLM.openai(ENV["KEY"])
 res = llm.audio.create_speech(input: "Hello world")
-File.binwrite File.join(Dir.home, "hello.mp3"),
-	          res.audio.string
+IO.copy_stream res.audio, File.join(Dir.home, "hello.mp3")
 ```
 
 #### Transcribe
@@ -325,7 +366,7 @@ also understand URLs, and various file types (eg images, audio, video,
 etc). The llm.rb approach to multimodal prompts is to let you pass `URI`
 objects to describe links, `LLM::File` / `LLM::Response::File` objects
 to describe files, `String` objects to describe text blobs, or an array
-of the forementioned objects to describe multiple objects in a single
+of the aforementioned objects to describe multiple objects in a single
 prompt. Each object is a first class citizen that can be passed directly
 to a prompt.
 
@@ -388,6 +429,38 @@ print res.embeddings[0].size, "\n"
 # 1536
 ```
 
+### Models
+
+#### List
+
+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.
+True to the llm.rb spirit of small, composable objects that cooperate with
+each other, a
+[LLM::Model](https://0x1eef.github.io/x/llm.rb/LLM/Model.html)
+object can be used instead of a string that describes a model name (although
+either works). Let's take a look at an example:
+
+```ruby
+#!/usr/bin/env ruby
+require "llm"
+
+##
+# List all models
+llm = LLM.openai(ENV["KEY"])
+llm.models.all.each do |model|
+  print "model: ", model.id, "\n"
+end
+
+##
+# Select a model
+model = llm.models.all.find { |m| m.id == "gpt-3.5-turbo" }
+bot = LLM::Chat.new(llm, model:)
+bot.chat "Hello #{model.id} :)"
+bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
+```
+
 ### Memory
 
 #### Child process
@@ -410,7 +483,7 @@ llm = LLM.gemini(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")
-    File.binwrite "#{animal}.png", res.images[0].binary
+    IO.copy_stream res.images[0], "#{animal}.png"
   end
 end
 Process.wait
@@ -440,9 +513,9 @@ magic or complex metaprogramming.
 
 Every part of llm.rb is designed to be explicit, composable, memory-safe,
 and production-ready without compromise. No unnecessary abstractions,
-no global configuration, and no dependencies that aren't part of standard
-Ruby. It has been inspired in part by other languages such as Python, but
-it is not a port of any other library.
+no global configuration, no global state, and no dependencies that aren't
+part of standard Ruby. It has been inspired in part by other languages such
+as Python, but it is not a port of any other library.
 
 ## License
 

data/lib/json/schema/array.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class JSON::Schema
+  class Array < Leaf
+    def initialize(items, **rest)
+      @items = items
+      super(**rest)
+    end
+
+    def to_h
+      super.merge!({type: "array", items:})
+    end
+
+    def to_json(options = {})
+      to_h.to_json(options)
+    end
+
+    private
+
+    attr_reader :items
+  end
+end

data/lib/json/schema/boolean.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class JSON::Schema
+  class Booelean < Leaf
+    def to_h
+      super.merge!({type: "boolean"})
+    end
+  end
+end

data/lib/json/schema/integer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class JSON::Schema
+  class Integer < Leaf
+    def min(i)
+      tap { @minimum = i }
+    end
+
+    def max(i)
+      tap { @maximum = i }
+    end
+
+    def to_h
+      super.merge!({
+        type: "integer",
+        minimum: @minimum,
+        maximum: @maximum
+      }).compact
+    end
+  end
+end

data/lib/json/schema/leaf.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class JSON::Schema
+  class Leaf
+    def initialize
+      @description = nil
+      @default = nil
+      @enum = nil
+      @required = nil
+    end
+
+    def description(str)
+      tap { @description = str }
+    end
+
+    def default(value)
+      tap { @default = value }
+    end
+
+    def enum(*values)
+      tap { @enum = values }
+    end
+
+    def required
+      tap { @required = true }
+    end
+
+    def to_h
+      {description: @description, default: @default, enum: @enum}.compact
+    end
+
+    def to_json(options = {})
+      to_h.to_json(options)
+    end
+
+    def required?
+      @required
+    end
+  end
+end

data/lib/json/schema/null.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class JSON::Schema
+  class Null < Leaf
+    def to_h
+      super.merge!({type: "null"})
+    end
+  end
+end

data/lib/json/schema/number.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class JSON::Schema
+  class Number < Leaf
+    def min(i)
+      tap { @minimum = i }
+    end
+
+    def max(i)
+      tap { @maximum = i }
+    end
+
+    def to_h
+      super.merge!({
+        type: "number",
+        minimum: @minimum,
+        maximum: @maximum
+      }).compact
+    end
+  end
+end

data/lib/json/schema/object.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class JSON::Schema
+  class Object < Leaf
+    def initialize(properties, **rest)
+      @properties = properties
+      super(**rest)
+    end
+
+    def to_h
+      super.merge!({type: "object", properties:, required:})
+    end
+
+    def to_json(options = {})
+      to_h.to_json(options)
+    end
+
+    private
+
+    attr_reader :properties
+
+    def required
+      @properties.filter_map {  _2.required? ? _1 : nil }
+    end
+  end
+end

data/lib/json/schema/string.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class JSON::Schema
+  class String < Leaf
+    def to_h
+      super.merge!({type: "string"})
+    end
+  end
+end

data/lib/json/schema.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module JSON
+end unless defined?(JSON)
+
+class JSON::Schema
+  require_relative "schema/leaf"
+  require_relative "schema/object"
+  require_relative "schema/array"
+  require_relative "schema/string"
+  require_relative "schema/number"
+  require_relative "schema/integer"
+  require_relative "schema/boolean"
+  require_relative "schema/null"
+
+  ##
+  # Returns an object
+  # @param properties [Hash] A hash of properties
+  # @param rest [Hash] Any other options
+  # @return [JSON::Schema::Object]
+  def object(properties, **rest)
+    Object.new(properties, **rest)
+  end
+
+  ##
+  # Returns an array
+  # @param items [Array] An array of items
+  # @param rest [Hash] Any other options
+  # @return [JSON::Schema::Array]
+  def array(items, **rest)
+    Array.new(items, **rest)
+  end
+
+  ##
+  # Returns a string
+  # @param rest [Hash] Any other options
+  # @return [JSON::Schema::String]
+  def string(...)
+    String.new(...)
+  end
+
+  ##
+  # Returns a number
+  # @param rest [Hash] Any other options
+  # @return [JSON::Schema::Number] a number
+  def number(...)
+    Number.new(...)
+  end
+
+  ##
+  # Returns an integer
+  # @param rest [Hash] Any other options
+  # @return [JSON::Schema::Integer]
+  def integer(...)
+    Integer.new(...)
+  end
+
+  ##
+  # Returns a boolean
+  # @param rest [Hash] Any other options
+  # @return [JSON::Schema::Boolean]
+  def boolean(...)
+    Boolean.new(...)
+  end
+
+  ##
+  # Returns null
+  # @param rest [Hash] Any other options
+  # @return [JSON::Schema::Null]
+  def null(...)
+    Null.new(...)
+  end
+end

data/lib/llm/chat.rb

@@ -27,11 +27,15 @@ 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
-    #  The parameters to maintain throughout the conversation
-    def initialize(provider, params = {})
+    #  Other parameters to maintain throughout the conversation
+    def initialize(provider, model: provider.default_model, schema: nil, **params)
       @provider = provider
-      @params = params
+      @params = params.merge!(model:, schema:)
       @lazy = false
       @messages = []
     end

data/lib/llm/core_ext/ostruct.rb

@@ -18,7 +18,7 @@ class OpenStruct
       hash_obj.each do |key, value|
         visited_object[key] = walk(value)
       end
-      OpenStruct.new(visited_object)
+      new(visited_object)
     end
 
     private

data/lib/llm/file.rb

@@ -7,13 +7,20 @@
 class LLM::File
   ##
   # @return [String]
-  #  Returns the path to a file
+  #  Returns the path to the file
   attr_reader :path
 
   def initialize(path)
     @path = path
   end
 
+  ##
+  # @return [String]
+  #  Returns basename of the file
+  def basename
+    File.basename(path)
+  end
+
   ##
   # @return [String]
   #  Returns the MIME type of the file

data/lib/llm/message.rb

@@ -50,6 +50,13 @@ module LLM
     end
     alias_method :eql?, :==
 
+    ##
+    # Try to parse the content as JSON
+    # @return [Hash]
+    def content!
+      JSON.parse(content)
+    end
+
     ##
     # Returns true when the message is from the LLM
     # @return [Boolean]

data/lib/llm/model.rb

@@ -1,7 +1,32 @@
 # frozen_string_literal: true
 
-class LLM::Model < Struct.new(:name, :parameters, :description, :to_param, keyword_init: true)
+##
+# The {LLM::Model LLM::Model} class represents an LLM model that
+# is available to use. Its properties are delegated to the underlying
+# response body, and vary by provider.
+class LLM::Model < OpenStruct
+  ##
+  # Returns a subclass of {LLM::Provider LLM::Provider}
+  # @return [LLM::Provider]
+  attr_accessor :provider
+
+  ##
+  # Returns the model ID
+  # @return [String]
+  def id
+    case @provider.class.to_s
+    when "LLM::Ollama"
+      self["name"]
+    when "LLM::Gemini"
+      self["name"].sub(%r|\Amodels/|, "")
+    else
+      self["id"]
+    end
+  end
+
+  ##
+  # @return [String]
   def to_json(*)
-    to_param.to_json(*)
+    id.to_json(*)
   end
 end

data/lib/llm/provider.rb

@@ -44,7 +44,7 @@ class LLM::Provider
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Embedding]
-  def embed(input, model:, **params)
+  def embed(input, model: nil, **params)
     raise NotImplementedError
   end
 
@@ -64,12 +64,14 @@ class LLM::Provider
   #  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
   # @raise [NotImplementedError]
   #  When the method is not implemented by a subclass
   # @return [LLM::Response::Completion]
-  def complete(prompt, role = :user, model: nil, **params)
+  def complete(prompt, role = :user, model: default_model, schema: nil, **params)
     raise NotImplementedError
   end
 
@@ -81,12 +83,13 @@ class LLM::Provider
   # @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)
   # @return [LLM::Chat]
-  def chat(prompt, role = :user, model: nil, **params)
-    LLM::Chat.new(self, params).lazy.chat(prompt, role)
+  def chat(prompt, role = :user, model: default_model, schema: nil, **params)
+    LLM::Chat.new(self, **params.merge(model:, schema:)).lazy.chat(prompt, role)
   end
 
   ##
@@ -97,12 +100,13 @@ class LLM::Provider
   # @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)
   # @return [LLM::Chat]
-  def chat!(prompt, role = :user, model: nil, **params)
-    LLM::Chat.new(self, params).chat(prompt, role)
+  def chat!(prompt, role = :user, model: default_model, schema: nil, **params)
+    LLM::Chat.new(self, **params.merge(model:, schema:)).chat(prompt, role)
   end
 
   ##
@@ -113,12 +117,13 @@ class LLM::Provider
   # @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)
   # @return [LLM::Chat]
-  def respond(prompt, role = :user, model: nil, **params)
-    LLM::Chat.new(self, params).lazy.respond(prompt, role)
+  def respond(prompt, role = :user, model: default_model, schema: nil, **params)
+    LLM::Chat.new(self, **params.merge(model:, schema:)).lazy.respond(prompt, role)
   end
 
   ##
@@ -129,12 +134,13 @@ class LLM::Provider
   # @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)
   # @return [LLM::Chat]
-  def respond!(prompt, role = :user, model: nil, **params)
-    LLM::Chat.new(self, params).respond(prompt, role)
+  def respond!(prompt, role = :user, model: default_model, schema: nil, **params)
+    LLM::Chat.new(self, **params.merge(model:, schema:)).respond(prompt, role)
   end
 
   ##
@@ -169,6 +175,13 @@ class LLM::Provider
     raise NotImplementedError
   end
 
+  ##
+  # @return [LLM::OpenAI::Models]
+  #  Returns an interface to the models API
+  def models
+    raise NotImplementedError
+  end
+
   ##
   # @return [String]
   #  Returns the role of the assistant in the conversation.
@@ -178,12 +191,22 @@ class LLM::Provider
   end
 
   ##
-  # @return [Hash<String, LLM::Model>]
-  #  Returns a hash of available models
-  def models
+  # @return [String]
+  #  Returns the default model for chat completions
+  def default_model
     raise NotImplementedError
   end
 
+  ##
+  # Returns an object that can generate a JSON schema
+  # @return [JSON::Schema]
+  def schema
+    @schema ||= begin
+      require_relative "../json/schema"
+      JSON::Schema.new
+    end
+  end
+
   private
 
   ##
@@ -228,8 +251,6 @@ class LLM::Provider
   #  When the rate limit is exceeded
   # @raise [LLM::Error::ResponseError]
   #  When any other unsuccessful status code is returned
-  # @raise [LLM::Error::PromptError]
-  #  When given an object a provider does not understand
   # @raise [SystemCallError]
   #  When there is a network error at the operating system level
   def request(http, req, &b)
@@ -250,17 +271,4 @@ class LLM::Provider
     req.body_stream = io
     req["transfer-encoding"] = "chunked" unless req["content-length"]
   end
-
-  ##
-  # @param [String] provider
-  #  The name of the provider
-  # @return [Hash<String, Hash>]
-  def load_models!(provider)
-    require "yaml" unless defined?(YAML)
-    rootdir  = File.realpath File.join(__dir__, "..", "..")
-    sharedir = File.join(rootdir, "share", "llm")
-    provider = provider.gsub(/[^a-z0-9]/i, "")
-    yaml     = File.join(sharedir, "models", "#{provider}.yml")
-    YAML.safe_load_file(yaml).transform_values { LLM::Model.new(_1) }
-  end
 end

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

@@ -26,13 +26,26 @@ class LLM::Anthropic
     # @return [String, Hash]
     #  The formatted content
     def format_content(content)
-      if URI === content
-        [{
-          type: :image,
-          source: {type: :base64, media_type: LLM::File(content.to_s).mime_type, data: [content.to_s].pack("m0")}
-        }]
+      case content
+      when Array
+        content.flat_map { format_content(_1) }
+      when URI
+        [{type: :image, source: {type: "url", url: content.to_s}}]
+      when LLM::File
+        if content.image?
+          [{type: :image, source: {type: "base64", media_type: content.mime_type, data: content.to_b64}}]
+        else
+          raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                          "is not an image, and therefore not supported by the " \
+                                          "Anthropic API"
+        end
+      when String
+        [{type: :text, text: content}]
+      when LLM::Message
+        format_content(content.content)
       else
-        content
+        raise LLM::Error::PromptError, "The given object (an instance of #{content.class}) " \
+                                       "is not supported by the Anthropic API"
       end
     end
   end