intelligence 0.6.0 → 0.8.0

data/lib/intelligence/adapters/samba_nova.rb

@@ -1,33 +1,33 @@
-require_relative 'legacy/adapter'
+require_relative 'generic/adapter'
 
 module Intelligence
   module SambaNova
 
-    class Adapter < Legacy::Adapter
+    class Adapter < Generic::Adapter
 
       chat_request_uri "https://api.sambanova.ai/v1/chat/completions"
       
-      configuration do 
+      schema do 
 
         # normalized properties for all endpoints
-        parameter :key, String
+        key                   String
         
         # properties for generative text endpoints
-        group :chat_options do 
+        chat_options do 
         
           # normalized properties for samba nova generative text endpoint
-          parameter :model, String
-          parameter :max_tokens, Integer
-          parameter :temperature, Float
-          parameter :top_p, Float
-          parameter :top_k, Float
-          parameter :stop, String, array: true
-          parameter :stream, [ TrueClass, FalseClass ]
+          model               String
+          max_tokens          Integer
+          temperature         Float
+          top_p               Float
+          top_k               Float
+          stop                String, array: true
+          stream              [ TrueClass, FalseClass ]
 
           # samba nova properties for samba nova generative text endpoint
-          parameter :repetition_penalty, Float
-          group :stream_options do
-            parameter :include_usage, [ TrueClass, FalseClass ]
+          repetition_penalty  Float
+          stream_options do
+            include_usage     [ TrueClass, FalseClass ]
           end
 
         end
@@ -35,8 +35,7 @@ module Intelligence
       end
 
       def chat_result_error_attributes( response )
-
-        error_type, error_description = translate_error_response_status( response.status )
+        error_type, error_description = to_error_response( response.status )
         result = {
           error_type: error_type.to_s,
           error_description: error_description
@@ -55,7 +54,6 @@ module Intelligence
         end
 
         result
-
       end
 
     end

data/lib/intelligence/adapters/together_ai.rb

@@ -1,39 +1,41 @@
-require_relative 'legacy/adapter'
+require_relative 'generic/adapter'
 
 module Intelligence
   module TogetherAi
 
-    class Adapter < Legacy::Adapter
+    class Adapter < Generic::Adapter
 
       chat_request_uri "https://api.together.xyz/v1/chat/completions"
       
-      configuration do 
-        parameter :key, String 
-        group :chat_options do 
-          parameter :model, String
-          parameter :temperature, Float
-          parameter :top_p, Float
-          parameter :top_k, Integer
-          parameter :n, Integer
-          parameter :max_tokens, Float
-          parameter :stop, String, array: true
-          parameter :stream, [ TrueClass, FalseClass ]
-          parameter :frequency_penalty, Float
-          parameter :presence_penalty, Float
-          parameter :repetition_penalty, Float
-          parameter :user, String
+      schema do 
+        key                       String 
+        chat_options do 
+          model                   String
+          temperature             Float
+          top_p                   Float
+          top_k                   Integer
+          n                       Integer
+          max_tokens              Float
+          stop                    String, array: true
+          stream                  [ TrueClass, FalseClass ]
+          frequency_penalty       Float
+          presence_penalty        Float
+          repetition_penalty      Float
+          user                    String
         end
       end
 
-      def translate_end_result( end_result )
+      def to_end_reason( end_result )
         case end_result
-          when 'eos'
+          when 'eos', 'stop'
             :ended
-          when 'length'
+          # unfortunatelly eos seems to only work with certain models while others always return
+          # stop so for now tomorrow ai will not support :end_sequence_encountered
+          # when 'stop'
+          #   :end_sequence_encountered
+         when 'length'
             :token_limit_exceeded
-          when 'stop'
-            :end_sequence_encountered
-          when 'function_call'
+          when 'tool_calls'
             :tool_called
           else
             nil

data/lib/intelligence/conversation.rb

@@ -1,16 +1,12 @@
 module Intelligence
   class Conversation 
 
-    extend AdaptiveConfiguration::Configurable 
+    include DynamicSchema::Definable 
+    include DynamicSchema::Buildable 
 
-    configuration do
-      group :system_message, default: { role: :system }, &Message::CONFIGURATION  
-      group :message, as: :messages, array: true, &Message::CONFIGURATION
-    end
-
-    def self.build( attributes = nil, &block )
-      configuration = self.configure( attributes, &block )
-      self.new( configuration.to_h )
+    schema do
+      system_message    default: { role: :system }, &Message.schema  
+      message           as: :messages, array: true, &Message.schema
     end
 
     attr_reader   :system_message
@@ -22,7 +18,7 @@ module Intelligence
       @messages = []
       @tools = []
       if attributes
-        if attributes[ :system_message ] 
+        if attributes[ :system_message ]&.any? 
           system_message = Message.new( 
             attributes[ :system_message ][ :role ],  
             attributes[ :system_message ]
@@ -64,6 +60,11 @@ module Intelligence
 
     alias :<< :append_message
 
+    def append_tool( *tools )
+      @tools.concat( tools.flatten )
+      self 
+    end
+
     def to_h
       result = {}
       result[ :system_message ] = @system_message.to_h if @system_message

data/lib/intelligence/message.rb

@@ -1,33 +1,47 @@
 module Intelligence
   class Message
 
-    extend AdaptiveConfiguration::Configurable 
+    include DynamicSchema::Definable
 
     ROLES = [ :system, :user, :assistant ]
-    CONFIGURATION = Proc.new do
-      parameter :role, Symbol, required: true 
-      group :content, array: true, as: :contents do 
-        parameter :type, Symbol, default: :text 
-        parameter :text, String 
-        parameter :content_type, String
-        parameter :bytes, String 
-        parameter :uri, URI
+    schema do
+      role              Symbol, required: true 
+      content           array: true, as: :contents do 
+        type            Symbol, default: :text
+
+        # note: we replicate these schema elements of the individual content types here to 
+        # provide more semantic flexibility when building a message; we don't delegate to the 
+        # individual content type schemas because, unlike for a specific content type, not all 
+        # attributes are required
+
+        # text 
+        text            String 
+        # binary and file 
+        content_type    String
+        bytes           String 
+        uri             URI
+        # tool call and tool result 
+        tool_call_id    String 
+        tool_name       String 
+        tool_parameters [ Hash, String ]
+        tool_result     [ Hash, String ]
       end
     end
 
-    configuration( &CONFIGURATION ) 
-
     attr_reader :role
     attr_reader :contents
 
     ##
-    # The build! class method constructs and returns a new +Message+ instance. The build! method 
-    # accepts message +attributes+ and a block, which may be combined when constructing a Message.
-    # The +role+ is required, either as a paramter or in the block. If the role is not present, 
-    # an exception will be raised.
+    # The +build!+ class method constructs and returns a new +Message+ instance. The +build!+ 
+    # method accepts message +attributes+ and a block, which may be combined when constructing 
+    # a +Message+. The +role+ is required, either as an attribute or in the block. If the +role+ 
+    # is not present, an exception will be raised.
     # 
     # The block offers the +role+ method, as well as a +content+ method permiting the caller to 
     # set the role and add content respectivelly. 
+    #
+    # Note that there is no corresponding +build+ method because a +Message+ strictly requires a 
+    # +role+. It cannot be constructed without one.
     # 
     # === examples
     #
@@ -50,19 +64,21 @@ module Intelligence
     #   content type: :binary do
     #     content_type 'image/png'
     #     bytes File.binread( '99_red_balloons.png' )
+    #   end
+    # end
     #
     def self.build!( attributes = nil, &block )
-      configuration = self.configure!( attributes, &block ).to_h
-      self.new( configuration[ :role ], configuration )
+      attributes = self.builder.build!( attributes, &block )
+      self.new( attributes[ :role ], attributes )
     end
 
     def initialize( role, attributes = nil )
-      raise ArgumentError.new( "The role is invalid. It must be one of #{ROLES.join( ', ' )}." ) \
-        unless ROLES.include?( role&.to_sym )
-
-          @role = role.to_sym 
+      @role = role&.to_sym 
       @contents = []   
 
+      raise ArgumentError.new( "The role is invalid. It must be one of #{ROLES.join( ', ' )}." ) \
+        unless ROLES.include?( @role )
+
       if attributes && attributes[ :contents ]
         attributes[ :contents ].each do | content |
           @contents << MessageContent.build!( content[ :type ], content )
@@ -93,18 +109,11 @@ module Intelligence
     def text  
       result = []
       each_content do | content |
-        result << content.text if content.is_a?( MessageContent::Text )
+        result << content.text if content.is_a?( MessageContent::Text ) && content.text
       end
       result.join( "\n" ) 
     end
 
-    def to_h
-      { 
-        role: @role,
-        contents: @contents.map { | c | c.to_h }
-      }
-    end
-
     def each_content( &block )
       @contents.each( &block )
     end
@@ -116,5 +125,12 @@ module Intelligence
 
     alias :<< :append_content
 
+    def to_h
+      { 
+        role: @role,
+        contents: @contents.map { | c | c.to_h }
+      }
+    end
+
   end
 end

data/lib/intelligence/message_content/base.rb

@@ -2,16 +2,9 @@ module Intelligence
   module MessageContent 
 
     class Base
-      extend AdaptiveConfiguration::Configurable
+      include DynamicSchema::Definable 
+      include DynamicSchema::Buildable 
 
-      def self.build( attributes = nil, &block ) 
-        self.new( self.configure( attributes, &block ) )
-      end 
-      
-      def self.build!( attributes = nil, &block ) 
-        self.new( self.configure!( attributes, &block ) )
-      end 
-      
       def initialize( attributes = {} )
         attributes.each do | key, value |
           instance_variable_set( "@#{key}", value.freeze ) if self.respond_to?( "#{key}" )

data/lib/intelligence/message_content/binary.rb

@@ -3,9 +3,9 @@ module Intelligence
 
     class Binary < Base
   
-      configuration do 
-        parameter :content_type, String, required: true 
-        parameter :bytes, String, required: true 
+      schema do 
+        content_type    String, required: true 
+        bytes           String, required: true 
       end
 
       attr_reader :content_type 

data/lib/intelligence/message_content/file.rb

@@ -3,9 +3,9 @@ module Intelligence
 
     class File < Base
   
-      configuration do 
-        parameter :content_type, String 
-        parameter :uri, URI, required: true 
+      schema do 
+        content_type    String  
+        uri             URI, required: true 
       end
 
       def initialize( attributes )

data/lib/intelligence/message_content/text.rb

@@ -3,8 +3,8 @@ module Intelligence
 
     class Text < Base
         
-      configuration do 
-        parameter :text, String, required: true
+      schema do 
+        text            String, required: true
       end
 
       attr_reader :text 
@@ -13,6 +13,14 @@ module Intelligence
         ( text || false ) && text.respond_to?( :empty? ) && !text.empty? 
       end
 
+      def merge( other )
+        other_text = other.text
+        text = @text 
+        text = ( @text || '' ) + other_text if other_text
+
+        self.class.new( text: text )
+      end
+
       def to_h
         { type: :text, text: text }
       end

data/lib/intelligence/message_content/tool_call.rb

@@ -3,15 +3,71 @@ module Intelligence
 
     class ToolCall < Base
       
-      configuration do 
-        parameter :tool_call_id, String 
-        parameter :tool_name, String, required: true 
-        parameter :tool_parameters, String, array: true
+      schema do 
+        tool_call_id    String 
+        tool_name       String, required: true 
+        tool_parameters [ Hash, String ]
       end 
 
       attr_reader :tool_call_id 
       attr_reader :tool_name
-      attr_reader :tool_parameters
+
+      def tool_parameters( options = nil )
+        return @tool_parameters if @tool_parameters.nil? || @tool_parameters.is_a?( Hash )
+        
+        options = options || {}
+        parse = options.key?( :parse ) ? options[ :parse ] : true 
+
+        return @parsed_tool_parameters if @parsed_tool_parameters && parse 
+        
+        tool_parameters = ( options.key?( :repair ) ? options[ :repair ] : true ) ? 
+            JSON.repair( @tool_parameters ) : @tool_parameters 
+
+        if parse 
+          @parsed_tool_parameters = tool_parameters = 
+            JSON.parse( 
+              tool_parameters, 
+              parse.is_a?( Hash ) ? parse : { symbolize_names: true } 
+            ) 
+        end
+
+        tool_parameters 
+      end
+
+      def valid?
+        tool_name && !tool_name.empty?
+      end
+
+      def merge( other_tool_call ) 
+        other_tool_call_id = other_tool_call.tool_call_id 
+        other_tool_name = other_tool_call.tool_name 
+        other_tool_parameters = other_tool_call.tool_parameters( repair: false, parse: false )
+        
+        raise ArgumentError, 
+              "The given tool call parameters are incompative with this tool's parameters." \
+          unless @tool_parameters.nil? || other_tool_parameters.nil? || 
+                 @tool_parameters.is_a?( other_tool_parameters.class )
+        
+        tool_call_id = other_tool_call_id.nil? ? 
+          @tool_call_id : @tool_call_id || '' + other_tool_call_id 
+        tool_name = other_tool_name.nil? ? 
+          @tool_name : @tool_name || '' + other_tool_name
+        tool_parameters = @tool_parameters 
+
+        unless other_tool_parameters.nil?
+          if other_tool_parameters.is_a?( Hash )
+            tool_parameters = ( tool_parameters || {} ).merge( other_tool_parameters )
+          else 
+            tool_parameters = ( tool_parameters || '' ) + other_tool_parameters 
+          end 
+        end
+
+        self.class.new( 
+          tool_call_id: tool_call_id, 
+          tool_name: tool_name, 
+          tool_parameters: tool_parameters 
+        )
+      end
 
       def to_h
         { 

data/lib/intelligence/message_content/tool_result.rb

@@ -3,22 +3,27 @@ module Intelligence
 
     class ToolResult < Base
 
-      configuration do 
-        parameter :tool_call_id
-        parameter :tool_name, String, required: true 
-        parameter :tool_result, String, required: true 
+      schema do 
+        tool_call_id
+        tool_name       String, required: true 
+        tool_result     [ Hash, String ]
       end 
 
       attr_reader :tool_call_id 
       attr_reader :tool_name
       attr_reader :tool_result
 
+      def valid?
+        tool_call_id && !tool_call_id.empty? &&
+        tool_name && !tool_name.empty?
+      end
+
       def to_h
         { 
-          type:             :tool_call, 
+          type:             :tool_result, 
           tool_call_id:     tool_call_id, 
           tool_name:        tool_name, 
-          tool_parameters:  tool_result 
+          tool_result:      tool_result 
         }.compact
       end
     end 

data/lib/intelligence/tool.rb

@@ -0,0 +1,139 @@
+module Intelligence
+  ##
+  # The +Tool+ class instance encpasulates a definition of a tool that may be executed by a 
+  # model. The properies of a tool include a unique name, a comprehensive description of what 
+  # the tool does and a set of properies that describe the arguments the tool accepts, each 
+  # with its own type and validation rules.
+  #
+  # A +Tool+ instance does not implement the tool, only the defintion of the tool, which is 
+  # presented to the model to allow it to make a tool call.
+  #
+  # == Configuration 
+  #
+  # A tool MUST include the +name+ and +description+ and may include any number of 
+  # +arguments+ as well as a +required+ attribute with a list of the required arguments. 
+  # Each argument must include a +name+ and may include +description+, +type+, a list of 
+  # acceptable values through +enum+ and a +minimum+ and +maximum+ for numerical 
+  # arguments. 
+  #
+  # === Tool Attributes   
+  #
+  # - +name+: A +String+ representing the unique name of the tool. *required*
+  # - +description+: A +String+ describing it's purpose and functionality. *required*
+  #
+  # === Argument Attributes
+  #
+  # An argument is defined through the +argument+ block. The block MUST include the +name+,
+  # while all other attributes, including the +description+ and +type+ are all optional.
+  #
+  # - +type+: 
+  #   A +String+ indicating the data type of the property. Accepted values include +string+, 
+  #   +number+, +integer+, +array+, +boolean+, +object+. 
+  # - +name+: A +String+ representing the name of the property. *required*
+  # - +description+: A +String+ that describes the property and its purpose. *required*
+  # - +minimum+: An +Integer+ or +Float+ specifying the minimum value for numerical properties.
+  # - +maximum+: An +Integer+ or +Float+ specifying the maximum value for numerical properties.
+  # - +enum+: 
+  #   An +Array+ of acceptable values for the property. Note that ( as per the JSON schema 
+  #   specification ) an enum could be composed of mixed types but this is discouraged. 
+  # - +required: 
+  #   A boolean ( +TrueClass+, +FalseClass+ ) that specifying if the argument is required.
+  #
+  # === Examples
+  #
+  # weather_tool = Tool.build! do 
+  #   name :get_weather_by_locality
+  #   description \ 
+  #     "The get_weather_by_locality tool will return the current weather in a given locality " \
+  #     "( city, state or province, and country )."
+  #   argument name: 'city', type: 'string', required: true do 
+  #     description "The city or town for which the current weather should be returned."
+  #   end 
+  #   argument name: 'state', type: 'string' do 
+  #     description \
+  #       "The state or province for which the current weather should be returned. If this is " \
+  #       "not provided the largest or most prominent city with the given name, in the given " \
+  #       "country, will be assumed."
+  #   end  
+  #   argument name: 'country', type: 'string', required: true do 
+  #     description "The city or town for which the current weather should be returned."
+  #   end 
+  # end
+  #
+  # web_browser_tool = Tool.build! 
+  #   name :get_web_page
+  #   description "The get_web_page tool will return the content of a web page, given a page url."
+  #   argument name: :url, type: 'string', required: true do 
+  #     description \
+  #       "The url of the page including the scheme.\n"
+  #       "Examples:\n"
+  #       "  https://example.com\n"
+  #       "  https://www.iana.org/help/example-domains\n"
+  #   end 
+  #   argument name: :format do
+  #     description \
+  #       "The format of the returned content. By default you will receive 'markdown'. You " \
+  #       "should specify 'html' only if it is specifically required to fullfill the user " \
+  #       "request." 
+  #     enum [ 'html', 'markdown' ] 
+  #   end 
+  #   argument name: :content do
+  #     description \
+  #       "The content of the page to be returned. By default you will receive only the 'main' " \
+  #       "content, excluding header, footer, menu, advertising and other miscelanous elements. " \
+  #       "You should request 'full' only if absolutely neccessry to fullfill the user request. " \
+  #     enum [ 'main', 'full' ]
+  #   end 
+  #   argument name: :include_tags do
+  #     description "If content is set to html some tags will."
+  #   end 
+  # end 
+  # 
+  class Tool
+    include DynamicSchema::Definable
+    include DynamicSchema::Buildable
+
+    ARGUMENT_TYPES = [ 'string', 'number', 'integer', 'array', 'boolean', 'object' ]
+
+    ARGUMENT_SCHEMA = proc do
+      type            String, in: ARGUMENT_TYPES
+      name            String, required: true
+      description     String, required: true 
+      required        [ TrueClass, FalseClass ]
+      # note that an enum does not require a type as it implicitly restricts the argument 
+      # to specific values
+      enum            array: true 
+      # for arguments of type number and integer
+      minimum         [ Integer, Float ]
+      maximum         [ Integer, Float ]
+      # for arguments of type array 
+      maximum_items   Integer, as: :maxItems
+      minimum_items   Integer, as: :minItems 
+      unique_items    [ TrueClass, FalseClass ]
+      items           do
+        type          in: ARGUMENT_TYPES
+        property      array: true, as: :properties, &ARGUMENT_SCHEMA 
+      end
+      # for arguments of type object 
+      property        array: true, as: :properties, &ARGUMENT_SCHEMA
+    end
+
+    schema            do 
+      name            String, required: true 
+      description     String, required: true 
+      argument        array: true, as: :properties do 
+        self.instance_eval( &ARGUMENT_SCHEMA )
+      end 
+    end  
+    
+    def initialize( attributes = nil )
+      @properies = attributes
+    end 
+
+    def to_h
+      @properies.to_h
+    end 
+
+  end
+end
+

data/lib/intelligence/version.rb

@@ -1,3 +1,3 @@
 module Intelligence
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/intelligence.rb

@@ -2,8 +2,9 @@ require 'json'
 require 'base64'
 
 require 'faraday'
-require 'adaptive_configuration'
+require 'dynamic_schema'
 require 'mime-types'
+require 'json/repair'
 
 require 'intelligence/version'
 
@@ -14,6 +15,7 @@ require 'intelligence/unsupported_content_error'
 require 'intelligence/error_result'
 require 'intelligence/chat_error_result'
 
+require 'intelligence/tool'
 require 'intelligence/message_content'
 require 'intelligence/message'
 require 'intelligence/conversation'