omniai 3.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ab654a67cbbe8a0fca968721a942c14a0e70a1bc0b0ca894c3b63c737e75bde
-  data.tar.gz: 7cea942027a5864ff5a62c7eeb9b53295fc8729d8b167360aff15b1c641ee8cb
+  metadata.gz: 5d80d0c802d1e6b92ece7abe8ef3f9fadf055d517e361f94a7560ac8919009d3
+  data.tar.gz: 7dd1f751f9285684211e1bb4045cc8fcc500b09bc2fe58fa7083e739dadb0083
 SHA512:
-  metadata.gz: 8053636d067f6c1a09d746a3fcaa4b4d1a873d89ed105149a7eb9fa5a370c21f13bece4b7edf83f0529f442aa7abaaef860bb2e81309d25313c53eef92fbb32e
-  data.tar.gz: 4d59606ebee19692a25f68b58542105260770dc73ff97b4b96bd6171758b1c3981533e8b6b8e114310f1cc2de1a91be2978a2a7bf39bf77a3d0986e8bb39da5f
+  metadata.gz: 3a42a1d89fdf659bce635c37e8a59072099a4595202fd8768a46310addfa46ca66ea030b791e8260c860b4dcf754bbe6e89beda84fe5582262252641a3b890ae
+  data.tar.gz: 3c44cde5d4b0d5d98b9f7b6cccfcb209ed695c8e69293e354ddc50dbaf4cb4c6d5be995cf596f55dd5c0fcbe2ccd629a41a20145a4fe472e977ea36188217dc1

data/README.md

@@ -456,23 +456,23 @@ client = OmniAI::OpenAI::Client.new(timeout: {
 
 ### 💬 Chat
 
-Clients that support chat (e.g. Anthropic w/ "Claude", Google w/ "Gemini", Mistral w/ "LeChat", OpenAI w/ "ChatGPT", etc) generate completions using the following calls:
+Clients that support chat (e.g. Anthropic w/ "Claude", Google w/ "Gemini", Mistral w/ "LeChat", OpenAI w/ "ChatGPT", etc) generate text using the following calls:
 
-#### Completions using a Simple Prompt
+#### Using a Basic Prompt
 
-Generating a completion is as simple as sending in the text:
+A chat response can be generated using a string for a prompt:
 
 ```ruby
-completion = client.chat('Tell me a joke.')
-completion.text # 'Why don't scientists trust atoms? They make up everything!'
+response = client.chat('Tell me a joke.')
+response.text # 'Why don't scientists trust atoms? They make up everything!'
 ```
 
-#### Completions using a Complex Prompt
+#### Using a Complex Prompt
 
-More complex completions are generated using a block w/ various system / user messages:
+A chat response can be generated using a combination of messages and parts for a prompt:
 
 ```ruby
-completion = client.chat do |prompt|
+response = client.chat do |prompt|
   prompt.system 'You are a helpful assistant with an expertise in animals.'
   prompt.user do |message|
     message.text 'What animals are in the attached photos?'
@@ -481,12 +481,12 @@ completion = client.chat do |prompt|
     message.file('./hamster.jpeg', "image/jpeg")
   end
 end
-completion.text  # 'They are photos of a cat, a cat, and a hamster.'
+response.text  # 'They are photos of a cat, a cat, and a hamster.'
 ```
 
-#### Completions using Streaming via Proc
+#### Streaming via Proc
 
-A real-time stream of messages can be generated by passing in a proc:
+A chat real-time stream of chunks can be generated with a proc:
 
 ```ruby
 stream = proc do |chunk|
@@ -495,25 +495,25 @@ end
 client.chat('Tell me a joke.', stream:)
 ```
 
-#### Completion using Streaming via IO
+#### Streaming via IO
 
-The above code can also be supplied with any IO object (e.g., `File`, `$stdout`, `$stdin`, etc.):
+A chat real-time stream of chunks can also work with any IO object (e.g., `File`, `$stdout`, `$stdin`, etc.):
 
 ```ruby
 client.chat('Tell me a story', stream: $stdout)
 ```
 
-#### Completion with Tools
+#### Using Tools
 
-A chat can also be initialized using tools:
+The chat API can be provided with a set of tools to be invoked:
 
 ```ruby
 class WeatherTool
   description "Lookup the weather at a location in either Celsius or Fahrenheit."
 
-  parameter :location, :string, description: "The location to find the weather."
-  parameter :unit, :string, enum: %w[Celsius Fahrenheit], description: "The unit of measurement."
-  required %i[location]
+  parameter :location, :string, description: "The location to find the weather.", nullable: false
+  parameter :unit, :string, enum: %w[Celsius Fahrenheit], description: "The unit of measurement.", nullable: true
+  required %i[location unit]
 
   # @param location [String]
   # @param unit [String] "Celsius" or "Fahrenheit"

data/lib/omniai/schema/array.rb

@@ -16,7 +16,7 @@ module OmniAI
     #    })
     #    array.serialize # => { type: "array", items: { ... }, minItems: 1, maxItems: 5 }
     #    array.parse([{ "name" => "Ringo Starr" }]) # => [{ name: "Ringo Star" }]
-    class Array
+    class Array < Base
       TYPE = "array"
 
       # @!attribute [rw] items
@@ -31,41 +31,29 @@ module OmniAI
       #   @return [Integer, nil]
       attr_accessor :min_items
 
-      # @!attribute [rw] description
-      #   @return [String, nil]
-      attr_accessor :description
-
-      # @example
-      #   array = OmniAI::Schema::Array.deserialize({
-      #     type: "array",
-      #     items: { type: "string" },
-      #     minItems: 1,
-      #     maxItems: 5,
-      #     description: "A list of strings."
-      #   }) # => OmniAI::Schema::Array
-      #
-      # @param data [Hash]
-      #
-      # @return [OmniAI::Schema::Array]
-      def self.deserialize(data)
-        new(
-          items: OmniAI::Schema.deserialize(data["items"] || data[:items]),
-          max_items: data[:maxItems] || data["maxItems"],
-          min_items: data[:minItems] || data["minItems"],
-          description: data[:description] || data["description"]
-        )
-      end
-
       # @param items [OmniAI::Schema::Object, OmniAI::Schema::Array, OmniAI::Schema::Scalar] required
+      # @param title [String] optional
+      # @param description [String] optional
+      # @param nullable [Boolean] optional
       # @param min_items [Integer] optional
       # @param max_items [Integer] optional
-      # @param description [String] optional
-      def initialize(items:, min_items: nil, max_items: nil, description: nil)
-        super()
+      def initialize(items:, title: nil, description: nil, min_items: nil, max_items: nil, nullable: nil)
+        super(title:, description:, nullable:)
         @items = items
         @min_items = min_items
         @max_items = max_items
-        @description = description
+      end
+
+      # @example
+      #   array.parse(["1", "2", "3"]) # => [1, 2, 3]
+      #
+      # @param data [Array]
+      #
+      # @return [Array]
+      def parse(data)
+        return data if data.nil? && nullable?
+
+        data.map { |arg| @items.parse(arg) }
       end
 
       # @example
@@ -76,7 +64,7 @@ module OmniAI
       # @return [Hash]
       def serialize(additional_properties: false)
         {
-          type: TYPE,
+          type: nullify(TYPE),
           description: @description,
           items: @items.serialize(additional_properties:),
           maxItems: @max_items,
@@ -85,13 +73,27 @@ module OmniAI
       end
 
       # @example
-      #   array.parse(["1", "2", "3"]) # => [1, 2, 3]
+      #   array = OmniAI::Schema::Array.deserialize({
+      #     type: "array",
+      #     items: { type: "string" },
+      #     minItems: 1,
+      #     maxItems: 5,
+      #     description: "A list of strings."
+      #   }) # => OmniAI::Schema::Array
       #
-      # @param data [Array]
+      # @param data [Hash]
       #
-      # @return [Array]
-      def parse(data)
-        data.map { |arg| @items.parse(arg) }
+      # @return [OmniAI::Schema::Array]
+      def self.deserialize(data)
+        nullable = Array(data[:type] || data["type"]).include?("null")
+
+        new(
+          items: OmniAI::Schema.deserialize(data["items"] || data[:items]),
+          max_items: data[:maxItems] || data["maxItems"],
+          min_items: data[:minItems] || data["minItems"],
+          description: data[:description] || data["description"],
+          nullable:
+        )
       end
     end
   end

data/lib/omniai/schema/base.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Schema
+    # @example
+    #    object = OmniAI::Tool::Base.deserialize({ ... })
+    #    object.serialize # => { ... }
+    #    object.parse(...]
+    class Base
+      # @!attribute [rw] title
+      #   @return [String, nil]
+      attr_accessor :title
+
+      # @!attribute [rw] description
+      #   @return [String, nil]
+      attr_accessor :description
+
+      # @param title [String] optional
+      # @param description [String] optional
+      # @param nullable [Boolean] optional
+      def initialize(title: nil, description: nil, nullable: nil)
+        super()
+        @title = title
+        @description = description
+        @nullable = nullable
+      end
+
+      # @param value [Object]
+      # @return Object
+      def parse(value)
+        raise NotImplementedError, "#parse undefined"
+      end
+
+      # @param additional_properties [Boolean]
+      #
+      # @return [Hash]
+      def serialize(additional_properties: false)
+        raise NotImplementedError, "#serialize undefined"
+      end
+
+      # @param data [Hash]
+      #
+      # @return [OmniAI::Schema::Base]
+      def self.deserialize(data)
+        raise NotImplementedError, ".deserialize undefined"
+      end
+
+      # @return [Boolean]
+      def nullable?
+        !!@nullable
+      end
+
+      # @return [OmniAI::Schema::Base]
+      def nullable
+        dup.tap do |object|
+          object.nullable = true
+        end
+      end
+
+      def nonnullable
+        dup.tap do |object|
+          object.nullable = false
+        end
+      end
+
+    protected
+
+      def nullify(type)
+        nullable? ? ["null", type] : type
+      end
+    end
+  end
+end

data/lib/omniai/schema/object.rb

@@ -12,7 +12,7 @@ module OmniAI
     #    })
     #    schema.serialize #=> { type: "object", properties: { ... }, required: %i[name] }
     #    schema.parse({ "name" => "John Doe" }) #=> { name: "John Doe" }
-    class Object
+    class Object < Base
       TYPE = "object"
 
       # @!attribute [rw] properties
@@ -23,43 +23,13 @@ module OmniAI
       #   @return [Array<String>]
       attr_accessor :required
 
-      # @!attribute [rw] title
-      #   @return [String, nil]
-      attr_accessor :title
-
-      # @!attribute [rw] description
-      #   @return [String, nil]
-      attr_accessor :description
-
-      # @example
-      #    OmniAI::Schema::Object.deserialize({
-      #      type: "object",
-      #      properties: {
-      #        name: { type: "string" }
-      #      },
-      #      required: ["name"],
-      #    }) # => OmniAI::Schema::Object
-      #
-      # @param data [Hash]
-      #
-      # @return [OmniAI::Schema::Object]
-      def self.deserialize(data)
-        title = data["title"] || data[:title]
-        description = data["description"] || data[:description]
-        properties = (data["properties"] || data[:properties]).transform_values { |i| OmniAI::Schema.deserialize(i) }
-        required = data["required"] || data[:required] || []
-
-        new(title:, description:, properties:, required:)
-      end
-
       # @param title [String] optional
       # @param description [String] optional
       # @param properties [Hash] optional
       # @param required [Array<String>] optional
-      def initialize(title: nil, description: nil, properties: {}, required: [])
-        super()
-        @title = title
-        @description = description
+      # @param nulable [Boolean] optional
+      def initialize(title: nil, description: nil, properties: {}, required: [], nullable: nil)
+        super(title:, description:, nullable:)
         @properties = properties
         @required = required
       end
@@ -70,16 +40,32 @@ module OmniAI
           title: @title,
           description: @description,
           properties: @properties.dup,
-          required: @required.dup
+          required: @required.dup,
+          nullable: @nullable
         )
       end
 
+      # @param data [Hash]
+      #
+      # @return [Hash]
+      def parse(data)
+        return if data.nil? && nullable?
+
+        result = {}
+        @properties.each do |name, property|
+          value = data[String(name)]
+          result[name.intern] = property.parse(value) unless value.nil?
+        end
+        result
+      end
+
       # @param additional_properties [Boolean, nil] optional
+      # @param require_all [Boolean, nil] optional
       #
       # @return [Hash]
       def serialize(additional_properties: false)
         {
-          type: TYPE,
+          type: nullify(TYPE),
           title: @title,
           description: @description,
           properties: @properties.transform_values { |value| value.serialize(additional_properties:) },
@@ -88,21 +74,26 @@ module OmniAI
         }.compact
       end
 
-      # @param name [Symbol]
-      def property(name, ...)
-        @properties[name] = OmniAI::Schema::Scalar.build(...)
-      end
-
+      # @example
+      #    OmniAI::Schema::Object.deserialize({
+      #      type: "object",
+      #      properties: {
+      #        name: { type: "string" }
+      #      },
+      #      required: ["name"],
+      #    }) # => OmniAI::Schema::Object
+      #
       # @param data [Hash]
       #
-      # @return [Hash]
-      def parse(data)
-        result = {}
-        @properties.each do |name, property|
-          value = data[String(name)]
-          result[name.intern] = property.parse(value) unless value.nil?
-        end
-        result
+      # @return [OmniAI::Schema::Object]
+      def self.deserialize(data)
+        nullable = Array(data["type"] || data[:type]).include?("null")
+        title = data["title"] || data[:title]
+        description = data["description"] || data[:description]
+        properties = (data["properties"] || data[:properties]).transform_values { |i| OmniAI::Schema.deserialize(i) }
+        required = data["required"] || data[:required] || []
+
+        new(title:, description:, properties:, required:, nullable:)
       end
     end
   end

data/lib/omniai/schema/scalar.rb

@@ -22,7 +22,7 @@ module OmniAI
     #  scalar.serialize #=> { type: "boolean" }
     #  scalar.parse(true) #=> true
     #  scalar.parse(false) #=> false
-    class Scalar
+    class Scalar < Base
       module Type
         BOOLEAN = "boolean"
         INTEGER = "integer"
@@ -34,14 +34,14 @@ module OmniAI
       #   @return [String]
       attr_accessor :type
 
-      # @!attribute [rw] description
-      #   @return [String, nil]
-      attr_accessor :description
-
       # @!attribute [rw] enum
       #   @return [Array<String>, nil]
       attr_accessor :enum
 
+      # @!attribute [rw] nullable
+      #   @return [Boolean, nil]
+      attr_accessor :nullable
+
       # @example
       #   property = OmniAI::Schema::Scalar.deserialize({
       #     type: "string",
@@ -68,32 +68,39 @@ module OmniAI
       #
       # @return [OmniAI::Schema::Scalar]
       def self.deserialize(data)
-        type = data["type"] || data[:type] || Type::STRING
+        types = Array(data["type"] || data[:type] || Type::STRING)
+        type = types.find { |type| !type.eql?("null") }
+        title = data["title"] || data[:title]
         description = data["description"] || data[:description]
         enum = data["enum"] || data[:enum]
 
-        new(type:, description:, enum:)
+        new(type:, title:, description:, enum:, nullable: types.include?("null"))
       end
 
       # @param type [String] required - the type of the property
+      # @param title [String] optional - a title of the property
       # @param description [String] optional - a description of the property
       # @param enum [Array] optional - the possible values of the property
+      # @param nullable [Boolean] optional - if the property may be null
       #
       # @return [OmniAI::Schema::Scalar]
-      def initialize(type:, description: nil, enum: nil)
-        super()
+      def initialize(type:, title: nil, description: nil, enum: nil, nullable: nil)
+        super(title:, description:, nullable:)
         @type = type
-        @description = description
         @enum = enum
       end
 
       # @example
       #   property.serialize #=> { type: "string" }
       #
+      # @example
+      #   property.serialize #=> { type: ["strig", "null"] }
+      #
       # @return [Hash]
       def serialize(*)
         {
-          type: @type,
+          type: nullify(@type),
+          title: @title,
           description: @description,
           enum: @enum,
         }.compact
@@ -106,6 +113,8 @@ module OmniAI
       #
       # @return [String, Integer, Float, Boolean, Object]
       def parse(value)
+        return if value.nil? && nullable?
+
         case @type
         when Type::INTEGER then Integer(value)
         when Type::STRING then String(value)

data/lib/omniai/schema.rb

@@ -47,7 +47,9 @@ module OmniAI
     #
     # @param data [OmniAI::Schema::Object, OmniAI::Schema::Array, OmniAI::Schema::Scalar]
     def self.deserialize(data)
-      case data["type"] || data[:type]
+      type = Array(data["type"] || data[:type]).find { |type| !type.eql?("null") }
+
+      case type
       when OmniAI::Schema::Array::TYPE then OmniAI::Schema::Array.deserialize(data)
       when OmniAI::Schema::Object::TYPE then OmniAI::Schema::Object.deserialize(data)
       else OmniAI::Schema::Scalar.deserialize(data)
@@ -80,10 +82,11 @@ module OmniAI
     # @param min_items [Integer] optional - the minimum number of items
     # @param max_items [Integer] optional - the maximum number of items
     # @param description [String] optional - a description of the array
+    # @param nullable [Boolean] optional - if the array may be null
     #
     # @return [OmniAI::Schema::Array]
-    def self.array(items:, min_items: nil, max_items: nil, description: nil)
-      OmniAI::Schema::Array.new(items:, description:, min_items:, max_items:)
+    def self.array(items:, min_items: nil, max_items: nil, description: nil, nullable: nil)
+      OmniAI::Schema::Array.new(items:, description:, min_items:, max_items:, nullable:)
     end
 
     # @example
@@ -101,54 +104,63 @@ module OmniAI
     # @param properties [Hash<String, OmniAI::Schema::Scalar>] required - the properties of the object
     # @param required [Array<Symbol>] optional - the required properties
     # @param description [String] optional - a description of the object
+    # @param nullable [Boolean] optional - if the object may be null
     #
     # @return [OmniAI::Schema::Array]
-    def self.object(title: nil, properties: {}, required: [], description: nil)
-      OmniAI::Schema::Object.new(title:, properties:, required:, description:)
+    def self.object(title: nil, properties: {}, required: [], description: nil, nullable: nil)
+      OmniAI::Schema::Object.new(title:, properties:, required:, description:, nullable:)
     end
 
     # @example
     #   OmniAI::Schema.boolean(description: "Is the person employed?") #=> OmniAI::Schema::Scalar
     #
+    # @param title [String] optional - the title of the property
     # @param description [String] optional - a description of the property
     # @param enum [Array<Boolean>] optional - the possible values of the property
+    # @param nullable [Boolean] optional - if the property may be null
     #
     # @return [OmniAI::Schema::Scalar]
-    def self.boolean(description: nil, enum: nil)
-      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::BOOLEAN, description:, enum:)
+    def self.boolean(title: nil, description: nil, enum: nil, nullable: nil)
+      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::BOOLEAN, title:, description:, enum:, nullable:)
     end
 
     # @example
     #   OmniAI::Schema.integer(description: "The age of the person") #=> OmniAI::Schema::Scalar
     #
+    # @param title [String] optional - the title of the property
     # @param description [String] optional - a description of the property
-    # @param enum [Array<Integer>] optinoal - the possible values of the property
+    # @param enum [Array<Integer>] optional - the possible values of the property
+    # @param nullable [Boolean] optional - if the property may be null
     #
     # @return [OmniAI::Schema::Scalar]
-    def self.integer(description: nil, enum: nil)
-      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::INTEGER, description:, enum:)
+    def self.integer(title: nil, description: nil, enum: nil, nullable: nil)
+      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::INTEGER, title:, description:, enum:, nullable:)
     end
 
     # @example
     #   OmniAI::Schema.string(description: "The name of the person.") #=> OmniAI::Schema::Scalar
     #
+    # @param title [String] optional - the title of the property
     # @param description [String] optional - a description of the property
     # @param enum [Array<String>] optional - the possible values of the property
+    # @param nullable [Boolean] optional - if the property may be null
     #
     # @return [OmniAI::Schema::Scalar]
-    def self.string(description: nil, enum: nil)
-      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::STRING, description:, enum:)
+    def self.string(title: nil, description: nil, enum: nil, nullable: nil)
+      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::STRING, title:, description:, enum:, nullable:)
     end
 
     # @example
     #  OmniAI::Schema.number(description: "The current temperature.") #=> OmniAI::Schema::Scalar
     #
+    # @param title [String] optional - the title of the property
     # @param description [String] optional - a description of the property
     # @param enum [Array<Number>] optional - the possible values of the property
+    # @param nullable [Boolean] optional - if the property may be null
     #
     # @return [OmniAI::Schema::Scalar]
-    def self.number(description: nil, enum: nil)
-      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::NUMBER, description:, enum:)
+    def self.number(title: nil, description: nil, enum: nil, nullable: nil)
+      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::NUMBER, title:, description:, enum:, nullable:)
     end
 
     # @example
@@ -156,6 +168,7 @@ module OmniAI
     #
     # @param name [String] required
     # @param schema [OmniAI::Schema::Object] required
+    # @param nullable [Boolean] optional
     #
     # @return [OmniAI::Schema::Format]
     def self.format(name:, schema:)

data/lib/omniai/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Kevin Sylvestre
@@ -139,6 +139,7 @@ files:
 - lib/omniai/parse_error.rb
 - lib/omniai/schema.rb
 - lib/omniai/schema/array.rb
+- lib/omniai/schema/base.rb
 - lib/omniai/schema/format.rb
 - lib/omniai/schema/object.rb
 - lib/omniai/schema/scalar.rb