omniai 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89f3eb0b1c62e35bc437833ad64c2c48504ead7bab049b1fc13cbdde30f5c6fe
-  data.tar.gz: bd8f3e7692996e622e245bd82f4fccc86df703836062d9542d59ec8119e09fe7
+  metadata.gz: 6b8a243fb8313c7c1fe3a483cdac33892f1b764cac19c38465a880e3f8a790f0
+  data.tar.gz: b24f59696a3befee77cde24b8fd25b88331b3664a327e8e207d9f57a08abb524
 SHA512:
-  metadata.gz: eb4748a2dc375e1e36dc096605adacd9822e9f7217ffb5a5c0516bbd21f18228dfdcc329346308ccc9b7a114bc24ee2a5abf04e3c09e06ee50cceac72f8f6d09
-  data.tar.gz: 6c814845c8fed1e20a042abe94c9ba74227f671a00b9551c79b1b12faedac2a7a998e9a325c942e8b07bdc1ebe55f62ef13563eb982b07ef27b9046695b00295
+  metadata.gz: 985aafb6c64874122c77c172ba7dccc1a371a982855b33add51c3371d872db7008391a28382aa7442d640a2f76df1e3ca95426428fb7cd3b12a177d69ed3605e
+  data.tar.gz: 42edecdd416fdc53562ea82caf09b94886e761ea2858c28db76dc4e909dd4da87835fe152bbebf3cc87a64a72eded21706c60ba13beba2293fa5470f11e822bd

data/README.md

@@ -88,34 +88,62 @@ require 'omniai/google'
 
 client = OmniAI::Google::Client.new
 
-class Weather < OmniAI::Tool
-  description "Lookup the weather for a location"
+class WeatherTool < OmniAI::Tool
+  description "Lookup the weather for a lat / lng."
 
-  parameter :location, :string, description: "A location (e.g. 'Toronto, Canada')."
+  parameter :lat, :number, description: "The latitude of the location."
+  parameter :lng, :number, description: "The longitude of the location."
   parameter :unit, :string, enum: %w[Celsius Fahrenheit], description: "The unit of measurement."
+  required %i[lat lng]
+
+  # @param lat [Float]
+  # @param lng [Float]
+  # @param unit [String] "Celsius" or "Fahrenheit"
+  #
+  # @return [String] e.g. "20° Celsius at lat=43.7 lng=-79.4"
+  def execute(lat:, lng:, unit: "Celsius")
+    puts "[weather] lat=#{lat} lng=#{lng} unit=#{unit}"
+    "#{rand(20..50)}° #{unit} at lat=#{lat} lng=#{lng}"
+  end
+end
+
+class GeocodeTool < OmniAI::Tool
+  description "Lookup the latitude and longitude of a location."
+
+  parameter :location, :string, description: "The location to geocode."
   required %i[location]
 
-  # @param location [String] required
-  # @param unit [String] optional - "Celsius" or "Fahrenheit"
-  # @return [String]
-  def execute(location:, unit: "Celsius")
-    puts "[weather] location=#{location} unit=#{unit}"
-    "#{rand(20..50)}° #{unit} at #{location}"
+  # @param location [String] "Toronto, Canada"
+  #
+  # @return [Hash] { lat: Float, lng: Float, location: String }
+  def execute(location:)
+    puts "[geocode] location=#{location}"
+
+    {
+      lat: rand(-90.0..+90.0),
+      lng: rand(-180.0..+180.0),
+      location:,
+    }
   end
 end
 
-client.chat(stream: $stdout, tools: [Weather.new]) do |prompt|
+tools = [
+  WeatherTool.new,
+  GeocodeTool.new,
+]
+
+client.chat(stream: $stdout, tools:) do |prompt|
   prompt.system "You are an expert in weather."
   prompt.user 'What is the weather in "London" in Celsius and "Madrid" in Fahrenheit?'
 end
 ```
 
 ```
-[weather] location=London unit=Celsius
-[weather] location=Madrid unit=Fahrenheit
-```
+[geocode] location=London
+[weather] lat=... lng=... unit=Celsius
+[geocode] location=Madrid
+[weather] lat=... lng=... unit=Fahrenheit
 
-```
 The weather is 24° Celsius in London and 42° Fahrenheit in Madrid.
 ```
 
@@ -146,19 +174,57 @@ loop do
 end
 ```
 
-```
-Type 'exit' or 'quit' to leave.
+### Example #6 [Chat w/ Schema](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_schema)
 
-> What is the capital of France?
-The capital of France is Paris.
-La capitale de la France est Paris.
+```ruby
+format = OmniAI::Schema.format(name: "Contact", schema: OmniAI::Schema.object(
+  description: "A contact with a name, relationship, and addresses.",
+  properties: {
+    name: OmniAI::Schema.string,
+    relationship: OmniAI::Schema.string(enum: %w[friend family]),
+    addresses: OmniAI::Schema.array(
+      items: OmniAI::Schema.object(
+        title: "Address",
+        description: "An address with street, city, state, and zip code.",
+        properties: {
+          street: OmniAI::Schema.string,
+          city: OmniAI::Schema.string,
+          state: OmniAI::Schema.string,
+          zip: OmniAI::Schema.string,
+        },
+        required: %i[street city state zip]
+      )
+    ),
+  },
+  required: %i[name]
+))
+
+response = client.chat(format:) do |prompt|
+  prompt.user <<~TEXT
+    Parse the following contact:
+
+    NAME: George Harrison
+    RELATIONSHIP: friend
+    HOME: 123 Main St, Springfield, IL, 12345
+    WORK: 456 Elm St, Springfield, IL, 12345
+  TEXT
+end
+
+puts format.parse(response.text)
+```
 
-> How many people live there?
-The population of Paris is approximately 2.1 million.
-La population de Paris est d’environ 2,1 million.
+```
+{
+  name: "George Harrison",
+  relationship: "friend",
+  addresses: [
+    { street: "123 Main St", city: "Springfield", state: "IL", zip: "12345" },
+    { street: "456 Elm St", city: "Springfield", state: "IL", zip: "12345" },
+  ]
+}
 ```
 
-### Example #6: [Chat w/ CLI](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_cli)
+### Example #7: [Chat w/ CLI](https://github.com/ksylvest/omniai/blob/main/examples/chat_with_cli)
 
 The `OmniAI` gem also ships with a CLI to simplify quick tests.
 
@@ -178,7 +244,7 @@ omniai chat --provider="google" --model="gemini-2.0-flash" "Who are you?"
 I am a large language model, trained by Google.
 ```
 
-### Example #7: [Text-to-Speech](https://github.com/ksylvest/omniai/blob/main/examples/text_to_speech)
+### Example #8: [Text-to-Speech](https://github.com/ksylvest/omniai/blob/main/examples/text_to_speech)
 
 This example demonstrates using `OmniAI` with **OpenAI** to convert text to speech and save it to a file.
 
@@ -194,7 +260,7 @@ File.open(File.join(__dir__, 'audio.wav'), 'wb') do |file|
 end
 ```
 
-### Example #8: [Speech-to-Text](https://github.com/ksylvest/omniai/blob/main/examples/speech_to_text)
+### Example #9: [Speech-to-Text](https://github.com/ksylvest/omniai/blob/main/examples/speech_to_text)
 
 This example demonstrates using `OmniAI` with **OpenAI** to convert speech to text.
 
@@ -209,7 +275,7 @@ File.open(File.join(__dir__, 'audio.wav'), 'rb') do |file|
 end
 ```
 
-### Example #9: [Embeddings](https://github.com/ksylvest/omniai/blob/main/examples/embeddings)
+### Example #10: [Embeddings](https://github.com/ksylvest/omniai/blob/main/examples/embeddings)
 
 This example demonstrates using `OmniAI` with **Mistral** to generate embeddings for a dataset. It defines a set of entries (e.g. "George is a teacher." or "Ringo is a doctor.") and then compares the embeddings generated from a query (e.g. "What does George do?" or "Who is a doctor?") to rank the entries by relevance.
 
@@ -426,19 +492,28 @@ client.chat('Tell me a story', stream: $stdout)
 A chat can also be initialized with tools:
 
 ```ruby
-tool = OmniAI::Tool.new(
-  proc { |location:, unit: 'Celsius'| "#{rand(20..50)}° #{unit} in #{location}" },
-  name: 'Weather',
-  description: 'Lookup the weather in a location',
-  parameters: OmniAI::Tool::Parameters.new(
-    properties: {
-      location: OmniAI::Tool::Property.string(description: 'e.g. Toronto'),
-      unit: OmniAI::Tool::Property.string(enum: %w[Celsius Fahrenheit]),
-    },
-    required: %i[location]
-  )
-)
-client.chat('What is the weather in "London" in Celsius and "Paris" in Fahrenheit?', tools: [tool])
+class WeatherTool
+  description "Lookup the weather at a location in either Celsius for 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]
+
+  # @param location [String]
+  # @param unit [String] "Celsius" or "Fahrenheit"
+  #
+  # @return [Hash]
+  def execute(location:, unit: "Celsius")
+    puts "[weather] location=#{locaiton} unit=#{unit}"
+
+    {
+      temperature: "#{rand(20..50)}°",
+      humidty: rand(0..100),
+    }
+  end
+end
+
+client.chat('What is the weather in "London" in Celsius and "Paris" in Fahrenheit?', tools: [WeatherTool.new])
 ```
 
 ### Transcribe

data/lib/omniai/chat/message.rb

@@ -103,7 +103,13 @@ module OmniAI
         serializer = context&.serializer(:message)
         return serializer.call(self, context:) if serializer
 
-        content = @content.is_a?(Array) ? @content.map { |content| content.serialize(context:) } : @content
+        content =
+          case @content
+          when Array then @content.map { |content| content.serialize(context:) }
+          when Content then @content.serialize(context:)
+          else @content
+          end
+
         tool_calls = @tool_call_list&.serialize(context:)
 
         { role: @role, content:, tool_calls: }.compact

data/lib/omniai/chat/response.rb

@@ -29,6 +29,8 @@ module OmniAI
 
       # @param data [Hash]
       # @param context [OmniAI::Context] optional
+      #
+      # @return [OmniAI::Chat::Response]
       def self.deserialize(data, context: nil)
         deserialize = context&.deserializer(:response)
         return deserialize.call(data, context:) if deserialize

data/lib/omniai/chat.rb

@@ -65,7 +65,7 @@ module OmniAI
     # @param temperature [Float, nil] optional
     # @param stream [Proc, IO, nil] optional
     # @param tools [Array<OmniAI::Tool>] optional
-    # @param format [Symbol, nil] optional - :json
+    # @param format [:json, :text, OmniAI::Schema::Object, nil] optional
     #
     # @yield [prompt] optional
     # @yieldparam prompt [OmniAI::Chat::Prompt]

data/lib/omniai/schema/array.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Schema
+    # @example
+    #    array = OmniAI::Tool::Array.deserialize({
+    #      description: "A list of people.",
+    #      items: {
+    #        properties: {
+    #          name: { type: "string" },
+    #        },
+    #        required: ["name"],
+    #      },
+    #      min_items: 1,
+    #      max_items: 5,
+    #    })
+    #    array.serialize # => { type: "array", items: { ... }, minItems: 1, maxItems: 5 }
+    #    array.parse([{ "name" => "Ringo Starr" }]) # => [{ name: "Ringo Star" }]
+    class Array
+      TYPE = "array"
+
+      # @!attribute [rw] items
+      #   @return [OmniAI::Schema::Object, OmniAI::Schema::Array, OmniAI::Schema::Scalar]
+      attr_accessor :items
+
+      # @!attribute [rw] max_items
+      #   @return [Integer, nil]
+      attr_accessor :max_items
+
+      # @!attribute [rw] min_items
+      #   @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 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()
+        @items = items
+        @min_items = min_items
+        @max_items = max_items
+        @description = description
+      end
+
+      # @example
+      #   array.serialize # => { type: "array", items: { type: "string" } }
+      #
+      # @return [Hash]
+      def serialize
+        {
+          type: TYPE,
+          description: @description,
+          items: @items.serialize,
+          maxItems: @max_items,
+          minItems: @min_items,
+        }.compact
+      end
+
+      # @example
+      #   array.parse(["1", "2", "3"]) # => [1, 2, 3]
+      #
+      # @param data [Array]
+      #
+      # @return [Array]
+      def parse(data)
+        data.map { |arg| @items.parse(arg) }
+      end
+    end
+  end
+end

data/lib/omniai/schema/format.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Schema
+    # @example
+    #   format = OmniAI::Schema::Format.deserialize({
+    #     name: "example",
+    #     schema: {
+    #       type: "object",
+    #       properties: {
+    #         name: { type: "string" },
+    #       },
+    #       required: ["name"],
+    #     }
+    #   })
+    #   format.serialize # => { name: "example", schema: { ... } }
+    class Format
+      # @!attribute [rw] name
+      #   @return [String]
+      attr_accessor :name
+
+      # @!attribute [rw] schema
+      #   @return [OmniAI::Schema::Object]
+      attr_accessor :schema
+
+      # @example
+      #   array = OmniAI::Schema::Format.deserialize({
+      #     name: "Contact",
+      #     schema: { ... },
+      #   }) # => OmniAI::Schema::Format
+      #
+      # @param data [Hash]
+      #
+      # @return [OmniAI::Schema::Format]
+      def self.deserialize(data)
+        name = data["name"] || data[:name]
+        schema = OmniAI::Schema.deserialize(data["schema"] || data[:schema])
+
+        new(name:, schema:)
+      end
+
+      # @param name [String]
+      # @param schema [OmniAI::Schema::Object]
+      def initialize(name:, schema:)
+        @name = name
+        @schema = schema
+      end
+
+      # @example
+      #   format.serialize # => { name: "...", schema: { ... } }
+      #
+      # @return [Hash]
+      def serialize
+        {
+          name:,
+          schema: schema.serialize,
+        }
+      end
+
+      # @example
+      #   format.parse("{ "name": "Ringo Starr" }"") # => { name: "Ringo Starr" }
+      #
+      # @param text [String]
+      #
+      # @return [Hash]
+      def parse(text)
+        schema.parse(JSON.parse(text))
+      end
+    end
+  end
+end

data/lib/omniai/schema/object.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Schema
+    # @example
+    #    schema = OmniAI::Schema::Object.deserialize({
+    #      type: "object",
+    #      properties: {
+    #        name: { type: "string" }
+    #      },
+    #      required: ["name"],
+    #    })
+    #    schema.serialize #=> { type: "object", properties: { ... }, required: %i[name] }
+    #    schema.parse({ "name" => "John Doe" }) #=> { name: "John Doe" }
+    class Object
+      TYPE = "object"
+
+      # @!attribute [rw] properties
+      #   @return [Hash]
+      attr_accessor :properties
+
+      # @!attribute [rw] required
+      #   @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
+        @properties = properties
+        @required = required
+      end
+
+      # @return [Hash]
+      def serialize
+        {
+          type: TYPE,
+          title: @title,
+          description: @description,
+          properties: @properties.transform_values(&:serialize),
+          required: @required,
+        }.compact
+      end
+
+      # @param name [Symbol]
+      def property(name, ...)
+        @properties[name] = OmniAI::Schema::Scalar.build(...)
+      end
+
+      # @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
+      end
+    end
+  end
+end

data/lib/omniai/schema/scalar.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Schema
+    # @example
+    #   scalar = OmniAI::Schema::Scalar.deserialize({ type: "string" })
+    #   scalar.serialize #=> { type: "string" }
+    #   scalar.parse("Hello World") #=> "Hello World"
+    #
+    # @example
+    #   scalar = OmniAI::Schema::Scalar.deserialize({ type: "integer" })
+    #   scalar.serialize #=> { type: "integer" }
+    #   scalar.parse("123") #=> 123
+    #
+    # @example
+    #   scalar = OmniAI::Schema::Scalar.deserialize({ type: "number" })
+    #   scalar.serialize #=> { type: "number" }
+    #   scalar.parse("123.45") #=> 123.45
+    #
+    # @example
+    #  scalar = OmniAI::Schema::Scalar.deserialize({ type: "boolean" })
+    #  scalar.serialize #=> { type: "boolean" }
+    #  scalar.parse(true) #=> true
+    #  scalar.parse(false) #=> false
+    class Scalar
+      module Type
+        BOOLEAN = "boolean"
+        INTEGER = "integer"
+        STRING = "string"
+        NUMBER = "number"
+      end
+
+      # @!attribute [rw] type
+      #   @return [String]
+      attr_accessor :type
+
+      # @!attribute [rw] description
+      #   @return [String, nil]
+      attr_accessor :description
+
+      # @!attribute [rw] enum
+      #   @return [Array<String>, nil]
+      attr_accessor :enum
+
+      # @example
+      #   property = OmniAI::Schema::Scalar.deserialize({
+      #     type: "string",
+      #     description: "A predefined color.",
+      #     enum: %w[red organge yellow green blue indigo violet],
+      #   })
+      #
+      # @example
+      #   property = OmniAI::Schema::Scalar.deserialize({
+      #     type: "integer",
+      #   })
+      #
+      # @example
+      #   property = OmniAI::Schema::Scalar.deserialize({
+      #     type: "number",
+      #   })
+      #
+      # @example
+      #   property = OmniAI::Schema::Scalar.deserialize({
+      #     type: "boolean",
+      #   })
+      #
+      # @param data [Hash]
+      #
+      # @return [OmniAI::Schema::Scalar]
+      def self.deserialize(data)
+        type = data["type"] || data[:type] || Type::STRING
+        description = data["description"] || data[:description]
+        enum = data["enum"] || data[:enum]
+
+        new(type:, description:, enum:)
+      end
+
+      # @param type [String] required - the type of the property
+      # @param description [String] optional - a description of the property
+      # @param enum [Array] optional - the possible values of the property
+      #
+      # @return [OmniAI::Schema::Scalar]
+      def initialize(type:, description: nil, enum: nil)
+        super()
+        @type = type
+        @description = description
+        @enum = enum
+      end
+
+      # @example
+      #   property.serialize #=> { type: "string" }
+      #
+      # @return [Hash]
+      def serialize
+        {
+          type: @type,
+          description: @description,
+          enum: @enum,
+        }.compact
+      end
+
+      # @example
+      #   property.parse("123") #=> 123
+      #
+      # @param value [String, Integer, Float, Boolean, Object]
+      #
+      # @return [String, Integer, Float, Boolean, Object]
+      def parse(value)
+        case @type
+        when Type::INTEGER then Integer(value)
+        when Type::STRING then String(value)
+        when Type::NUMBER then Float(value)
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/omniai/schema.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module OmniAI
+  # @example
+  #   format = OmniAI::Schema.format(name: "Contact", schema: OmniAI::Schema.object(
+  #     description: "A contact with a name, relationship, and addresses.",
+  #     properties: {
+  #       name: OmniAI::Schema.string,
+  #       relationship: OmniAI::Schema.string(enum: %w[friend family]),
+  #       addresses: OmniAI::Schema.array(
+  #         items: OmniAI::Schema.object(
+  #           title: "Address",
+  #           description: "An address with street, city, state, and zip code.",
+  #           properties: {
+  #             street: OmniAI::Schema.string,
+  #             city: OmniAI::Schema.string,
+  #             state: OmniAI::Schema.string,
+  #             zip: OmniAI::Schema.string,
+  #           },
+  #           required: %i[street city state zip]
+  #         )
+  #       ),
+  #     },
+  #     required: %i[name]
+  #   ))
+  module Schema
+    # @example
+    #   OmniAI::Schema.deserialize({
+    #     type: 'object',
+    #     title: 'Person',
+    #     properties: { name: { type: 'string' } },
+    #     required: %i[name],
+    #   }) # => OmniAI::Schema::Object
+    #
+    # @example
+    #   OmniAI::Schema.deserialize({
+    #     type: 'array',
+    #     items: { type: 'string' },
+    #   }) # => OmniAI::Schema::Array
+    #
+    # @example
+    #   OmniAI::Schema.deserialize({
+    #     type: 'string',
+    #     description: '...',
+    #     enum: ['...', ],
+    #   }) # => OmniAI::Schema::Scalar
+    #
+    # @param data [OmniAI::Schema::Object, OmniAI::Schema::Array, OmniAI::Schema::Scalar]
+    def self.deserialize(data)
+      case data["type"] || data[: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)
+      end
+    end
+
+    # @param kind [Symbol]
+    #
+    # @return [OmniAI::Schema::Object, OmniAI::Schema::Array, OmniAI::Schema::Scalar]
+    def self.build(kind, **args)
+      case kind
+      when :array then array(**args)
+      when :object then object(**args)
+      when :boolean then boolean(**args)
+      when :integer then integer(**args)
+      when :number then number(**args)
+      when :string then string(**args)
+      end
+    end
+
+    # @example
+    #   property = OmniAI::Schema.array(
+    #     items: OmniAI::Schema.string(description: 'The name of the person.'),
+    #     description: 'A list of names.'
+    #     min_items: 1,
+    #     max_items: 5,
+    #   )
+    #
+    # @param items [OmniAI::Schema::Scalar] required - the items in the array
+    # @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
+    #
+    # @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:)
+    end
+
+    # @example
+    #   property = OmniAI::Schema.object(
+    #     properties: {
+    #       name: OmniAI::Schema.string(description: 'The name of the person.'),
+    #       age: OmniAI::Schema.integer(description: 'The age of the person.'),
+    #       employed: OmniAI::Schema.boolean(description: 'Is the person employed?'),
+    #     },
+    #     description: 'A person.'
+    #     required: %i[name]
+    #   )
+    #
+    # @param title [String] optional - the title of the object
+    # @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
+    #
+    # @return [OmniAI::Schema::Array]
+    def self.object(title: nil, properties: {}, required: [], description: nil)
+      OmniAI::Schema::Object.new(title:, properties:, required:, description:)
+    end
+
+    # @example
+    #   OmniAI::Schema.boolean(description: "Is the person employed?") #=> OmniAI::Schema::Scalar
+    #
+    # @param description [String] optional - a description of the property
+    # @param enum [Array<Boolean>] optional - the possible values of the property
+    #
+    # @return [OmniAI::Schema::Scalar]
+    def self.boolean(description: nil, enum: nil)
+      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::BOOLEAN, description:, enum:)
+    end
+
+    # @example
+    #   OmniAI::Schema.integer(description: "The age of the person") #=> OmniAI::Schema::Scalar
+    #
+    # @param description [String] optional - a description of the property
+    # @param enum [Array<Integer>] optinoal - the possible values of the property
+    #
+    # @return [OmniAI::Schema::Scalar]
+    def self.integer(description: nil, enum: nil)
+      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::INTEGER, description:, enum:)
+    end
+
+    # @example
+    #   OmniAI::Schema.string(description: "The name of the person.") #=> OmniAI::Schema::Scalar
+    #
+    # @param description [String] optional - a description of the property
+    # @param enum [Array<String>] optional - the possible values of the property
+    #
+    # @return [OmniAI::Schema::Scalar]
+    def self.string(description: nil, enum: nil)
+      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::STRING, description:, enum:)
+    end
+
+    # @example
+    #  OmniAI::Schema.number(description: "The current temperature.") #=> OmniAI::Schema::Scalar
+    #
+    # @param description [String] optional - a description of the property
+    # @param enum [Array<Number>] optional - the possible values of the property
+    #
+    # @return [OmniAI::Schema::Scalar]
+    def self.number(description: nil, enum: nil)
+      OmniAI::Schema::Scalar.new(type: OmniAI::Schema::Scalar::Type::NUMBER, description:, enum:)
+    end
+
+    # @example
+    #   OmniAI::Schema.format(name: "Contact", schema: OmniAI::Schema.object(...)) #=> OmniAI::Schema::Format
+    #
+    # @param name [String] required
+    # @param schema [OmniAI::Schema::Object] required
+    #
+    # @return [OmniAI::Schema::Format]
+    def self.format(name:, schema:)
+      OmniAI::Schema::Format.new(name:, schema:)
+    end
+  end
+end

data/lib/omniai/tool.rb

@@ -25,15 +25,15 @@ module OmniAI
         @description = description
       end
 
-      # @return [OmniAI::Tool::Parameters]
+      # @return [OmniAI::Schema::Object]
       def parameters
-        @parameters ||= Parameters.new
+        @parameters ||= OmniAI::Schema::Object.new
       end
 
       # @param name [Symbol]
       # @param kind [Symbol]
       def parameter(name, kind, **)
-        parameters.properties[name] = Property.build(kind, **)
+        parameters.properties[name] = OmniAI::Schema.build(kind, **)
       end
 
       # @param names [Array<Symbol>]
@@ -118,7 +118,7 @@ module OmniAI
         function: {
           name: @name,
           description: @description,
-          parameters: @parameters.is_a?(Tool::Parameters) ? @parameters.serialize : @parameters,
+          parameters: @parameters.is_a?(Schema::Object) ? @parameters.serialize : @parameters,
         }.compact,
       }
     end
@@ -134,7 +134,7 @@ module OmniAI
     # @param args [Hash]
     # @return [String]
     def call(args = {})
-      @function.call(**(@parameters.is_a?(Tool::Parameters) ? @parameters.parse(args) : args))
+      @function.call(**(@parameters.is_a?(Schema::Object) ? @parameters.parse(args) : args))
     end
   end
 end

data/lib/omniai/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Kevin Sylvestre
 bindir: exe
 cert_chain: []
-date: 2025-04-24 00:00:00.000000000 Z
+date: 2025-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -119,13 +119,14 @@ files:
 - lib/omniai/mcp/server.rb
 - lib/omniai/mcp/transport/base.rb
 - lib/omniai/mcp/transport/stdio.rb
+- lib/omniai/schema.rb
+- lib/omniai/schema/array.rb
+- lib/omniai/schema/format.rb
+- lib/omniai/schema/object.rb
+- lib/omniai/schema/scalar.rb
 - lib/omniai/speak.rb
 - lib/omniai/ssl_error.rb
 - lib/omniai/tool.rb
-- lib/omniai/tool/array.rb
-- lib/omniai/tool/object.rb
-- lib/omniai/tool/parameters.rb
-- lib/omniai/tool/property.rb
 - lib/omniai/transcribe.rb
 - lib/omniai/transcribe/transcription.rb
 - lib/omniai/version.rb

data/lib/omniai/tool/array.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module OmniAI
-  class Tool
-    # Represents a schema object.
-    #
-    # @example
-    #    array = OmniAI::Tool::Array.new(
-    #      description: 'A list of people.',
-    #      items: OmniAI::Tool::Object.new(
-    #        properties: {
-    #          name: OmniAI::Tool::Property.string(description: 'The name of the person.'),
-    #          age: OmniAI::Tool::Property.integer(description: 'The age of the person.'),
-    #        },
-    #        required: %i[name]
-    #      ),
-    #      min_items: 1,
-    #      max_items: 5,
-    #    })
-    class Array
-      TYPE = "array"
-
-      # @!attribute [rw] items
-      #   @return [OmniAI::Tool::Object, OmniAI::Tool::Array, OmniAI::Tool::Property]
-      attr_accessor :items
-
-      # @!attribute [rw] max_items
-      #   @return [Integer, nil]
-      attr_accessor :max_items
-
-      # @!attribute [rw] min_items
-      #   @return [Integer, nil]
-      attr_accessor :min_items
-
-      # @!attribute [rw] description
-      #   @return [String, nil]
-      attr_accessor :description
-
-      # @param items [OmniAI::Tool::Object, OmniAI::Tool::Array, OmniAI::Tool::Property] required
-      # @param max_items [Integer] optional
-      # @param min_items [Integer] optional
-      # @param description [String] optional
-      def initialize(items:, max_items: nil, min_items: nil, description: nil)
-        @items = items
-        @description = description
-        @max_items = max_items
-        @min_items = min_items
-      end
-
-      # @example
-      #   array.serialize # => { type: 'array', items: { type: 'string' } }
-      #
-      # @return [Hash]
-      def serialize
-        {
-          type: TYPE,
-          description: @description,
-          items: @items.serialize,
-          maxItems: @max_items,
-          minItems: @min_items,
-        }.compact
-      end
-
-      # @example
-      #   array.parse(['1', '2', '3']) # => [1, 2, 3]
-      # @param args [Array]
-      #
-      # @return [Array]
-      def parse(args)
-        args.map { |arg| @items.parse(arg) }
-      end
-    end
-  end
-end

data/lib/omniai/tool/object.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module OmniAI
-  class Tool
-    # Represents a schema object.
-    #
-    # @example
-    #    object = OmniAI::Tool::Object.new(
-    #      properties: {
-    #        name: OmniAI::Tool::Property.string(description: 'The name of the person.'),
-    #        age: OmniAI::Tool::Property.integer(description: 'The age of the person.'),
-    #      },
-    #      required: %i[name]
-    #    })
-    class Object
-      TYPE = "object"
-
-      # @!attribute [rw] properties
-      #   @return [Hash]
-      attr_accessor :properties
-
-      # @!attribute [rw] required
-      #   @return [Array<String>]
-      attr_accessor :required
-
-      # @!attribute [rw] description
-      #   @return [String, nil]
-      attr_accessor :description
-
-      # @param properties [Hash]
-      # @param required [Array<String>]
-      # @return [OmniAI::Tool::Parameters]
-      def initialize(properties: {}, required: [], description: nil)
-        @properties = properties
-        @required = required
-        @description = description
-      end
-
-      # @return [Hash]
-      def serialize
-        {
-          type: TYPE,
-          description: @description,
-          properties: @properties.transform_values(&:serialize),
-          required: @required,
-        }.compact
-      end
-
-      # @param args [Hash]
-      #
-      # @return [Hash]
-      def parse(args)
-        result = {}
-        @properties.each do |name, property|
-          value = args[String(name)]
-          result[name.intern] = property.parse(value) unless value.nil?
-        end
-        result
-      end
-    end
-  end
-end

data/lib/omniai/tool/parameters.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module OmniAI
-  class Tool
-    # Parameters are used to define the arguments for a tool.
-    #
-    # @example
-    #    parameters = OmniAI::Tool::Parameters.new(properties: {
-    #      people: OmniAI::Tool::Parameters.array(
-    #        items: OmniAI::Tool::Parameters.object(
-    #          properties: {
-    #            name: OmniAI::Tool::Parameters.string(description: 'The name of the person.'),
-    #            age: OmniAI::Tool::Parameters.integer(description: 'The age of the person.'),
-    #            employed: OmniAI::Tool::Parameters.boolean(description: 'Is the person employed?'),
-    #          }
-    #      n: OmniAI::Tool::Parameters.integer(description: 'The nth number to calculate.')
-    #      required: %i[n]
-    #    })
-    #    tool = OmniAI::Tool.new(fibonacci, parameters: parameters)
-    class Parameters < Object
-    end
-  end
-end

data/lib/omniai/tool/property.rb

@@ -1,151 +0,0 @@
-# frozen_string_literal: true
-
-module OmniAI
-  class Tool
-    # A property used for a tool parameter.
-    #
-    # @example
-    #   OmniAI::Tool::Property.array(description: '...', items: ...)
-    #   OmniAI::Tool::Property.object(description: '...', properties: { ... }, required: %i[...])
-    #   OmniAI::Tool::Property.string(description: '...')
-    #   OmniAI::Tool::Property.integer(description: '...')
-    #   OmniAI::Tool::Property.number(description: '...')
-    #   OmniAI::Tool::Property.boolean(description: '...')
-    class Property
-      module Type
-        BOOLEAN = "boolean"
-        INTEGER = "integer"
-        STRING = "string"
-        NUMBER = "number"
-      end
-
-      # @return [String]
-      attr_reader :type
-
-      # @return [String, nil]
-      attr_reader :description
-
-      # @return [Array<String>, nil]
-      attr_reader :enum
-
-      # @param kind [Symbol]
-      # @return [OmniAI::Tool::Property]
-      def self.build(kind, **args)
-        case kind
-        when :array then array(**args)
-        when :object then object(**args)
-        when :boolean then boolean(**args)
-        when :integer then integer(**args)
-        when :string then string(**args)
-        when :number then number(**args)
-        end
-      end
-
-      # @example
-      #   property = OmniAI::Tool::Property.array(
-      #     items: OmniAI::Tool::Property.string(description: 'The name of the person.'),
-      #     description: 'A list of names.'
-      #     min_items: 1,
-      #     max_items: 5,
-      #   )
-      #
-      # @param items [OmniAI::Tool::Property] required - the items in the array
-      # @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
-      #
-      # @return [OmniAI::Tool::Array]
-      def self.array(items:, min_items: nil, max_items: nil, description: nil)
-        OmniAI::Tool::Array.new(items:, description:, min_items:, max_items:)
-      end
-
-      # @example
-      #   property = OmniAI::Tool::Property.object(
-      #     properties: {
-      #       name: OmniAI::Tool::Property.string(description: 'The name of the person.'),
-      #       age: OmniAI::Tool::Property.integer(description: 'The age of the person.'),
-      #       employed: OmniAI::Tool::Property.boolean(description: 'Is the person employed?'),
-      #     },
-      #     description: 'A person.'
-      #     required: %i[name]
-      #   )
-      #
-      # @param properties [Hash<String, OmniAI::Tool::Property>] required - the properties of the object
-      # @param required [Array<Symbol>] optional - the required properties
-      # @param description [String] optional - a description of the object
-      #
-      # @return [OmniAI::Tool::Array]
-      def self.object(properties: {}, required: [], description: nil)
-        OmniAI::Tool::Object.new(properties:, required:, description:)
-      end
-
-      # @param description [String] optional - a description of the property
-      # @param enum [Array<Boolean>] optional - the possible values of the property
-      #
-      # @return [OmniAI::Tool::Property]
-      def self.boolean(description: nil, enum: nil)
-        new(type: Type::BOOLEAN, description:, enum:)
-      end
-
-      # @param description [String] optional - a description of the property
-      # @param enum [Array<Integer>] optinoal - the possible values of the property
-      #
-      # @return [OmniAI::Tool::Property]
-      def self.integer(description: nil, enum: nil)
-        new(type: Type::INTEGER, description:, enum:)
-      end
-
-      # @param description [String] optional - a description of the property
-      # @param enum [Array<String>] optional - the possible values of the property
-      #
-      # @return [OmniAI::Tool::Property]
-      def self.string(description: nil, enum: nil)
-        new(type: Type::STRING, description:, enum:)
-      end
-
-      # @param description [String] optional - a description of the property
-      # @param enum [Array<Number>] optional - the possible values of the property
-      #
-      # @return [OmniAI::Tool::Property]
-      def self.number(description: nil, enum: nil)
-        new(type: Type::NUMBER, description:, enum:)
-      end
-
-      # @param type [String] required - the type of the property
-      # @param description [String] optional - a description of the property
-      # @param enum [Array] optional - the possible values of the property
-      #
-      # @return [OmniAI::Tool::Property]
-      def initialize(type:, description: nil, enum: nil)
-        @type = type
-        @description = description
-        @enum = enum
-      end
-
-      # @example
-      #   property.serialize #=> { type: 'string' }
-      #
-      # @return [Hash]
-      def serialize
-        {
-          type: @type,
-          description: @description,
-          enum: @enum,
-        }.compact
-      end
-
-      # @example
-      #   property.parse('123') #=> 123
-      #
-      # @return [String, Integer, Float, Boolean, Object]
-      def parse(value)
-        case @type
-        when Type::INTEGER then Integer(value)
-        when Type::STRING then String(value)
-        when Type::NUMBER then Float(value)
-        else value
-        end
-      end
-    end
-  end
-end