omniai 2.5.0 → 2.7.0

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.7.0"
 end

data/lib/omniai.rb

@@ -16,6 +16,68 @@ loader.inflector.inflect "http_error" => "HTTPError"
 loader.inflector.inflect "ssl_error" => "SSLError"
 loader.setup
 
+# @example
+#
+#   OmniAI.chat(...)
+#   OmniAI.transcribe(...)
+#   OmniAI.speak(...)
+#   OmniAI.embed(...)
 module OmniAI
   class Error < StandardError; end
+
+  # Discover a client by provider ('openai' then 'anthropic' then 'google' then 'mistral' then 'deepseek').
+  #
+  # @param provider [Symbol] the provider to use (e.g. :openai, :anthropic, :google, :mistral, :deepseek) - optional
+  #
+  # @raise [OmniAI::LoadError] if no providers are installed
+  #
+  # @return [OmniAI::Client]
+  def self.client(provider: nil, **)
+    provider ? OmniAI::Client.find(provider:, **) : OmniAI::Client.discover(**)
+  end
+
+  # @example
+  #   response = OmniAI.chat("What is the capital of Spain?")
+  #   puts response.text
+  #
+  # @example
+  #   OmniAI.chat(stream: $stdout) do |prompt|
+  #     prompt.system("Answer in both English and French.")
+  #     prompt.user("How many people live in Tokyo?")
+  #   end
+  #
+  # @see OmniAI::Client#chat
+  def self.chat(...)
+    client.chat(...)
+  end
+
+  # @example
+  #   File.open("audio.wav", "rb") do |file|
+  #     puts OmniAI.transcribe(file).text
+  #   end
+  #
+  # @see OmniAI::Client#transcribe
+  def self.transcribe(...)
+    client.transcribe(...)
+  end
+
+  # @example
+  #   File.open("audio.wav", "wb") do |file|
+  #     OmniAI.speak("Sally sells seashells by the seashore.") do |chunk|
+  #       file << chunk
+  #     end
+  #   end
+  #
+  # @see OmniAI::Client#speak
+  def self.speak(...)
+    client.speak(...)
+  end
+
+  # @example
+  #   embedding = OmniAI.embed("The quick brown fox jumps over the lazy dog.").embedding
+  #
+  # @see OmniAI::Client#embed
+  def self.embed(...)
+    client.embed(...)
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: omniai
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Kevin Sylvestre
 bindir: exe
 cert_chain: []
-date: 2025-04-24 00:00:00.000000000 Z
+date: 2025-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -112,6 +112,7 @@ files:
 - lib/omniai/files.rb
 - lib/omniai/http_error.rb
 - lib/omniai/instrumentation.rb
+- lib/omniai/load_error.rb
 - lib/omniai/mcp/jrpc.rb
 - lib/omniai/mcp/jrpc/error.rb
 - lib/omniai/mcp/jrpc/request.rb
@@ -119,13 +120,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