llm.rb 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8ce8caa7c769da9197528a864c153071f3c4aca15718efc985e543911c04ce2
-  data.tar.gz: 389ff41e9e2b35782b1484048b7597f5573bf2a86cf9eaff8cfd7c4cb2b19be3
+  metadata.gz: 3d8311b461c49095ba393be6d3456bf7c3032a07e4480f4fd3e4cd9133f2b6e7
+  data.tar.gz: 5f9ce812a4a27e0982ea5072bca3f0494317ee0274987e57df792cc0e0d2fcfc
 SHA512:
-  metadata.gz: 39c8f71eae878b5787ca839138de07ce06cba4fdee0bafb1bd75a71f3b3e59ee08fa05f5d9f280522ec751722c9a8a15430d1b999b05e14052d85c745bf9781c
-  data.tar.gz: fdb5268b0095f09b41481e6c7071a2dae66cf9a3fd21755834b76040e13a236bc18122dfe95230dd49a827e774487a1add1aa35c8976f284a03afad881321b46
+  metadata.gz: 1d860cabe75a0718e0c06d686127d6d24c65b4dc8967aaf490b892bfad10bf88268791e9138b26e2d1c646a22e2eda7e74ad48e1fa31e9cb68c42de7ec53ac12
+  data.tar.gz: 8c2e14a316e87560e5d5dc3cdb416d151172ae12e2244bb813ff1bba61c582474607bd6920f82fa5f080e628b2dac319dd20d4f74eff55940f9c88ab7544b327

data/README.md

@@ -110,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
@@ -326,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.
 

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

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/provider.rb

@@ -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: default_model, **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: default_model, **params)
-    LLM::Chat.new(self, **params.merge(model:)).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: default_model, **params)
-    LLM::Chat.new(self, **params.merge(model:)).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: default_model, **params)
-    LLM::Chat.new(self, **params.merge(model:)).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: default_model, **params)
-    LLM::Chat.new(self, **params.merge(model:)).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
 
   ##
@@ -191,6 +197,16 @@ class LLM::Provider
     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
 
   ##

data/lib/llm/providers/anthropic.rb

@@ -55,7 +55,6 @@ module LLM
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
       body = JSON.dump({messages: format(messages)}.merge!(params))
       set_body_stream(req, StringIO.new(body))
-
       res = request(@http, req)
       Response::Completion.new(res).extend(response_parser)
     end

data/lib/llm/providers/gemini.rb

@@ -67,20 +67,20 @@ module LLM
     # @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, **params)
+    def complete(prompt, role = :user, model: default_model, schema: nil, **params)
       model.respond_to?(:id) ? model.id : model
       path = ["/v1beta/models/#{model}", "generateContent?key=#{@secret}"].join(":")
       req  = Net::HTTP::Post.new(path, headers)
       messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
-      body = JSON.dump({contents: format(messages)})
+      body = JSON.dump({contents: format(messages)}.merge!(expand_schema(schema)))
       set_body_stream(req, StringIO.new(body))
-
       res = request(@http, req)
       Response::Completion.new(res).extend(response_parser)
     end
@@ -136,6 +136,16 @@ module LLM
       }
     end
 
+    def expand_schema(schema)
+      return {} unless schema
+      {
+        "generationConfig" => {
+          "response_mime_type" => "application/json",
+          "response_schema" => schema
+        }
+      }
+    end
+
     def response_parser
       LLM::Gemini::ResponseParser
     end

data/lib/llm/providers/ollama.rb

@@ -60,13 +60,15 @@ module LLM
     # @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, **params)
-      params = {model:, stream: false}.merge!(params)
+    def complete(prompt, role = :user, model: default_model, schema: nil, **params)
+      params = {model:, stream: false}
+                 .merge!(expand_schema(schema))
+                 .merge!(params)
+                 .compact
       req = Net::HTTP::Post.new("/api/chat", headers)
       messages = [*(params.delete(:messages) || []), LLM::Message.new(role, prompt)]
       body = JSON.dump({messages: format(messages)}.merge!(params))
       set_body_stream(req, StringIO.new(body))
-
       res = request(@http, req)
       Response::Completion.new(res).extend(response_parser)
     end
@@ -102,6 +104,11 @@ module LLM
       }
     end
 
+    def expand_schema(schema)
+      return {} unless schema
+      {format: schema}
+    end
+
     def response_parser
       LLM::Ollama::ResponseParser
     end

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

@@ -52,13 +52,15 @@ class LLM::OpenAI
     # @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, **params)
-      params = {model:}.merge!(params)
+    def create(prompt, role = :user, model: @provider.default_model, schema: nil, **params)
+      params = {model:}
+                 .merge!(expand_schema(schema))
+                 .merge!(params)
+                 .compact
       req = Net::HTTP::Post.new("/v1/responses", headers)
       messages = [*(params.delete(:input) || []), LLM::Message.new(role, prompt)]
       body = JSON.dump({input: format(messages, :response)}.merge!(params))
       set_body_stream(req, StringIO.new(body))
-
       res = request(http, req)
       LLM::Response::Output.new(res).extend(response_parser)
     end
@@ -96,7 +98,7 @@ class LLM::OpenAI
       @provider.instance_variable_get(:@http)
     end
 
-    [:response_parser, :headers, :request, :set_body_stream].each do |m|
+    [:response_parser, :headers, :request, :set_body_stream, :expand_schema].each do |m|
       define_method(m) { |*args, &b| @provider.send(m, *args, &b) }
     end
   end

data/lib/llm/providers/openai.rb

@@ -44,19 +44,22 @@ module LLM
     # @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, **params)
-      params = {model:}.merge!(params)
+    def complete(prompt, role = :user, model: default_model, schema: nil, **params)
+      params = {model:}
+                 .merge!(expand_schema(schema))
+                 .merge!(params)
+                 .compact
       req = Net::HTTP::Post.new("/v1/chat/completions", headers)
       messages = [*(params.delete(:messages) || []), Message.new(role, prompt)]
       body = JSON.dump({messages: format(messages, :complete)}.merge!(params))
       set_body_stream(req, StringIO.new(body))
-
       res = request(@http, req)
       Response::Completion.new(res).extend(response_parser)
     end
@@ -131,5 +134,15 @@ module LLM
     def error_handler
       LLM::OpenAI::ErrorHandler
     end
+
+    def expand_schema(schema)
+      return {} unless schema
+      {
+        response_format: {
+          type: "json_schema",
+          json_schema: {name: "JSONSchema", schema:}
+        }
+      }
+    end
   end
 end

data/lib/llm/version.rb

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

data/spec/llm/conversation_spec.rb

@@ -27,7 +27,7 @@ RSpec.describe "LLM::Chat: non-lazy" do
         bot = nil
         inputs.zip(outputs).each_with_index do |(input, output), index|
           expect(provider).to receive(:complete)
-                                .with(input.content, instance_of(Symbol), messages:, model: provider.default_model)
+                                .with(input.content, instance_of(Symbol), messages:, model: provider.default_model, schema: nil)
                                 .and_return(OpenStruct.new(choices: [output]))
           bot = index.zero? ? provider.chat!(input.content, :system) : bot.chat(input.content)
           messages.concat([input, output])
@@ -192,4 +192,70 @@ RSpec.describe "LLM::Chat: lazy" do
       end
     end
   end
+
+  context "when given a schema as JSON" do
+    context "with openai" do
+      let(:provider) { LLM.openai(token) }
+      let(:conversation) { described_class.new(provider, schema:).lazy }
+
+      context "when given a schema",
+              vcr: {cassette_name: "openai/lazy_conversation/completions/successful_response_schema_netbsd"} do
+        subject(:message) { conversation.recent_message.content! }
+        let(:schema) { provider.schema.object({os: provider.schema.string.enum("OpenBSD", "FreeBSD", "NetBSD")}) }
+
+        before do
+          conversation.chat "You secretly love NetBSD", :system
+          conversation.chat "What operating system is the best?", :user
+        end
+
+        it "formats the response" do
+          is_expected.to eq("os" => "NetBSD")
+        end
+      end
+    end
+
+    context "with gemini" do
+      let(:provider) { LLM.gemini(token) }
+      let(:conversation) { described_class.new(provider, schema:).lazy }
+
+      context "when given a schema",
+              vcr: {cassette_name: "gemini/lazy_conversation/completions/successful_response_schema_netbsd"} do
+        subject(:message) { conversation.recent_message.content! }
+        let(:schema) { provider.schema.object({os: provider.schema.string.enum("OpenBSD", "FreeBSD", "NetBSD")}) }
+
+        before do
+          conversation.chat "You secretly love NetBSD", :user
+          conversation.chat "What operating system is the best?", :user
+        end
+
+        it "formats the response" do
+          is_expected.to eq("os" => "NetBSD")
+        end
+      end
+    end
+
+    context "with ollama" do
+      let(:provider) { LLM.ollama(nil, host: "eel.home.network") }
+      let(:conversation) { described_class.new(provider, schema:).lazy }
+
+      context "when given a schema",
+              vcr: {cassette_name: "ollama/lazy_conversation/completions/successful_response_schema_netbsd"} do
+        subject(:message) { conversation.recent_message.content! }
+        let(:schema) do
+          provider.schema.object({
+            os: provider.schema.string.enum("OpenBSD", "FreeBSD", "NetBSD").required
+          })
+        end
+
+        before do
+          conversation.chat "You secretly love NetBSD", :system
+          conversation.chat "What operating system is the best?", :user
+        end
+
+        it "formats the response" do
+          is_expected.to eq("os" => "NetBSD")
+        end
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Antar Azri
@@ -148,6 +148,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- lib/json/schema.rb
+- lib/json/schema/array.rb
+- lib/json/schema/boolean.rb
+- lib/json/schema/integer.rb
+- lib/json/schema/leaf.rb
+- lib/json/schema/null.rb
+- lib/json/schema/number.rb
+- lib/json/schema/object.rb
+- lib/json/schema/string.rb
 - lib/llm.rb
 - lib/llm/buffer.rb
 - lib/llm/chat.rb