intelligence 0.5.0 → 0.7.1

data/lib/intelligence/adapters/google/adapter.rb

@@ -1,57 +1,55 @@
-require_relative 'chat_methods'
+require_relative 'chat_request_methods'
+require_relative 'chat_response_methods'
 
 module Intelligence
   module Google
     class Adapter < Adapter::Base
 
-      configuration do 
+      schema do 
 
         # normalized properties for all endpoints
-        parameter :key, String, required: true  
+        key               String  
 
-        group :chat_options, as: :generationConfig do
+        chat_options      as: :generationConfig do
 
           # normalized properties for google generative text endpoint
-          parameter :model, String, required: true
-          parameter :max_tokens, Integer, as: :maxOutputTokens
-          parameter :n, Integer, as: :candidateCount
-          parameter :temperature, Float
-          parameter :top_k, Integer, as: :topK
-          parameter :top_p, Float, as: :topP
-          parameter :seed, Integer
-          parameter :stop, String, array: true, as: :stopSequences
-          parameter :stream, [ TrueClass, FalseClass ]
-
-          parameter :frequency_penalty, Float, as: :frequencyPenalty
-          parameter :presence_penalty, Float, as: :presencePenalty
+          model           String
+          max_tokens      Integer,    as: :maxOutputTokens
+          n               Integer,    as: :candidateCount
+          temperature     Float
+          top_k           Integer,    as: :topK
+          top_p           Float,      as: :topP
+          seed            Integer
+          stop            String,     array: true, as: :stopSequences
+          stream          [ TrueClass, FalseClass ]
+
+          frequency_penalty Float,    as: :frequencyPenalty
+          presence_penalty Float,     as: :presencePenalty
 
           # google variant of normalized properties for google generative text endpoints
-          parameter :candidate_count, Integer, as: :candidateCount
-          parameter :max_output_tokens, Integer, as: :maxOutputTokens
-          parameter :stop_sequences, String, array: true, as: :stopSequences
+          candidate_count Integer,    as: :candidateCount
+          max_output_tokens Integer,  as: :maxOutputTokens
+          stop_sequences String,      array: true, as: :stopSequences
 
           # google specific properties for google generative text endpoints
-          parameter :response_mime_type, String, as: :responseMimeType
-          parameter :response_schema, as: :responseSchema
+          response_mime_type String,  as: :responseMimeType
+          response_schema             as: :responseSchema
 
-        end
+          # google specific tool configuration
+          tool_configuration          as: :tool_config do
+            function_calling          as: :function_calling_config do 
+              mode                    Symbol, in: [ :auto, :any, :none ]
+              allowed_function_names  String, array: true 
+            end
+          end 
 
-      end
 
-      attr_reader :key
-      attr_reader :model
-      attr_reader :stream
-      attr_reader :chat_options
-
-      def initialize( attributes = nil, &block )
-        configuration = self.class.configure( attributes, &block ).to_h 
-        @key = configuration.delete( :key )
-        @model = configuration[ :generationConfig ]&.delete( :model )
-        @stream = configuration[ :generationConfig ]&.delete( :stream ) || false
-        @chat_options = configuration[ :generationConfig ] || {}
+        end
+
       end
 
-      include ChatMethods
+      include ChatRequestMethods 
+      include ChatResponseMethods
 
     end 
 

data/lib/intelligence/adapters/google/chat_request_methods.rb

@@ -0,0 +1,233 @@
+require 'uri'
+
+module Intelligence
+  module Google
+    module ChatRequestMethods
+
+      GENERATIVE_LANGUAGE_URI = "https://generativelanguage.googleapis.com/v1beta/models/"
+
+      SUPPORTED_BINARY_MEDIA_TYPES = %w[ text ]
+
+      SUPPORTED_BINARY_CONTENT_TYPES = %w[
+        image/png image/jpeg image/webp image/heic image/heif 
+        audio/aac audio/flac audio/mp3 audio/m4a audio/mpeg audio/mpga audio/mp4 audio/opus 
+        audio/pcm audio/wav audio/webm
+        application/pdf 
+      ]
+
+      SUPPORTED_FILE_MEDIA_TYPES = %w[ text ]
+
+      SUPPORTED_CONTENT_TYPES = %w[
+        image/png image/jpeg image/webp image/heic image/heif 
+        video/x-flv video/quicktime video/mpeg video/mpegps video/mpg video/mp4 video/webm 
+        video/wmv video/3gpp
+        audio/aac audio/flac audio/mp3 audio/m4a audio/mpeg audio/mpga audio/mp4 audio/opus 
+        audio/pcm audio/wav audio/webm
+        application/pdf 
+      ]
+
+      def chat_request_uri( options )
+        options = @options.merge( build_options( options ) )
+
+        key = options[ :key ] 
+        gc = options[ :generationConfig ] || {}
+        model = gc[ :model ]
+        stream = gc.key?( :stream ) ? gc[ :stream ] : false 
+      
+        raise ArgumentError.new( "A Google API key is required to build a Google chat request." ) \
+          if key.nil?
+        raise ArgumentError.new( "A Google model is required to build a Google chat request." ) \
+          if model.nil?
+        
+        uri = URI( GENERATIVE_LANGUAGE_URI )
+        path = File.join( uri.path, model )
+        path += stream ? ':streamGenerateContent' : ':generateContent'
+        uri.path = path
+        query = { key: key }
+        query[ :alt ] = 'sse' if stream
+        uri.query = URI.encode_www_form( query )
+
+        uri.to_s
+      end
+
+      def chat_request_headers( options = {} )
+        { 'Content-Type' => 'application/json' }
+      end
+
+      def chat_request_body( conversation, options = {} )
+        options = @options.merge( build_options( options ) )
+
+        gc = options[ :generationConfig ]
+        # discard properties not part of the google generationConfig schema
+        gc.delete( :model )
+        gc.delete( :stream )
+        
+        # googlify tool configuration 
+        if tool_config = gc.delete( :tool_config )
+          mode = tool_config[ :function_calling_config ]&.[]( :mode )
+          tool_config[ :function_calling_config ][ :mode ] = mode.to_s.upcase if mode 
+        end 
+      
+        result = {}
+        result[ :generationConfig ] = gc
+        result[ :tool_config ] = tool_config if tool_config
+
+        # construct the system prompt in the form of the google schema
+        system_instructions = to_google_system_message( conversation[ :system_message ] )
+        result[ :systemInstruction ] = system_instructions if system_instructions
+
+        result[ :contents ] = []
+        conversation[ :messages ]&.each do | message |
+
+          result_message = { role: message[ :role ] == :user ? 'user' : 'model' }
+          result_message_parts = []
+          
+          message[ :contents ]&.each do | content |
+            case content[ :type ]
+            when :text
+              result_message_parts << { text: content[ :text ] }
+            when :binary
+              content_type = content[ :content_type ]
+              bytes = content[ :bytes ]
+              if content_type && bytes
+                mime_type = MIME::Types[ content_type ].first
+                if SUPPORTED_BINARY_MEDIA_TYPES.include?( mime_type&.media_type ) || 
+                   SUPPORTED_BINARY_CONTENT_TYPES.include?( content_type )
+                  result_message_parts << {
+                    inline_data: {
+                      mime_type: content_type,
+                      data: Base64.strict_encode64( bytes )
+                    }
+                  }
+                else
+                  raise UnsupportedContentError.new( 
+                    :google, 
+                    "does not support #{content_type} content type"
+                  ) 
+                end
+              else 
+                raise UnsupportedContentError.new(
+                  :google, 
+                  'requires binary content to include content type and ( packed ) bytes'  
+                )
+              end 
+            when :file
+              content_type = content[ :content_type ]
+              uri = content[ :uri ]
+              if content_type && uri
+                mime_type = MIME::Types[ content_type ].first
+                if SUPPORTED_FILE_MEDIA_TYPES.include?( mime_type&.media_type ) || 
+                   SUPPORTED_FILE_CONTENT_TYPES.include?( content_type )
+                  result_message_parts << {
+                    file_data: {
+                      mime_type: content_type,
+                      file_uri: uri
+                    }
+                  }
+                else
+                  raise UnsupportedContentError.new( 
+                    :google, 
+                    "does not support #{content_type} content type"
+                  ) 
+                end
+              else 
+                raise UnsupportedContentError.new(
+                  :google, 
+                  'requires file content to include content type and uri'  
+                )
+              end 
+            when :tool_call
+              result_message_parts << { 
+                functionCall: {
+                  name: content[ :tool_name ],
+                  args: content[ :tool_parameters ]
+                }
+              }
+            when :tool_result 
+              result_message_parts << {
+                functionResponse: {
+                  name: content[ :tool_name ],
+                  response: {
+                    name: content[ :tool_name ],
+                    content: content[ :tool_result ]
+                  } 
+                }
+              }
+            else 
+              raise InvalidContentError.new( :google ) 
+            end 
+          end
+
+          result_message[ :parts ] = result_message_parts
+          result[ :contents ] << result_message
+
+        end 
+
+        tools_attributes = to_google_tools( conversation[ :tools ] )
+        result[ :tools ] = tools_attributes if tools_attributes && tools_attributes.length > 0
+  
+        JSON.generate( result )
+      end 
+
+    private 
+    
+      def to_google_system_message( system_message )
+        return nil if system_message.nil?
+
+        text = ''
+        system_message[ :contents ].each do | content |
+          text += content[ :text ] if content[ :type ] == :text 
+        end
+
+        return nil if text.empty?
+
+        {
+          role: 'user',
+          parts: [
+            { text: text }
+          ] 
+        }
+      end 
+
+      def to_google_tools( tools ) 
+        properties_array_to_object = lambda do | properties |
+          return nil unless properties&.any?  
+          object = {}
+          required = []
+          properties.each do | property | 
+            name = property.delete( :name ) 
+            required << name if property.delete( :required )
+            if property[ :properties ]&.any?  
+              property_properties, property_required = 
+                properties_array_to_object.call( property[ :properties ] ) 
+              property[ :properties ] = property_properties 
+              property[ :required ] = property_required if property_required.any?
+            end 
+            object[ name ] = property 
+          end 
+          [ object, required.compact  ]
+        end
+
+        return [ { function_declarations: tools&.map { | tool |
+          function = { 
+            name: tool[ :name ],
+            description: tool[ :description ],
+          }
+          if tool[ :properties ]&.any? 
+            properties_object, properties_required = 
+              properties_array_to_object.call( tool[ :properties ] ) 
+            function[ :parameters ] = {
+              type: 'object',
+              properties: properties_object 
+            }
+            function[ :parameters ][ :required ] = properties_required if properties_required.any?
+          end
+          function 
+        } } ]
+      end
+
+    end
+
+  end
+
+end

data/lib/intelligence/adapters/google/{chat_methods.rb → chat_response_methods.rb}

@@ -2,110 +2,14 @@ require 'uri'
 
 module Intelligence
   module Google
-    module ChatMethods
+    module ChatResponseMethods
 
-      GENERATIVE_LANGUAGE_URI = "https://generativelanguage.googleapis.com/v1beta/models/"
-
-      def chat_request_uri( options )
-
-        options = options.nil? || options.empty? ? {} : self.class.configure( options )
-
-        key = options[ :key ] || self.key
-        
-        gc = options[ :generationConfig ] || {}
-        model = gc[ :model ] || self.model
-        stream = gc.key?( :stream ) ? gc[ :stream ] : self.stream
-      
-        raise ArgumentError.new( "A Google API key is required to build a Google chat request." ) \
-          if self.key.nil?
-        raise ArgumentError.new( "A Google model is required to build a Google chat request." ) \
-          if model.nil?
-        
-        uri = URI( GENERATIVE_LANGUAGE_URI )
-        path = File.join( uri.path, model )
-        path += stream ? ':streamGenerateContent' : ':generateContent'
-        uri.path = path
-        query = { key: self.key }
-        query[ :alt ] = 'sse' if stream
-        uri.query = URI.encode_www_form( query )
-
-        uri.to_s
-      
-      end
-
-      def chat_request_headers( options = {} )
-        { 'Content-Type' => 'application/json' }
-      end
-
-      def chat_request_body( conversation, options = {} )
-
-        result = {}
-        result[ :generationConfig ] = self.chat_options
-
-        options = options.nil? || options.empty? ? {} : self.class.configure( options )
-        result = result.merge( options )
-
-        # discard properties not part of the google endpoint schema
-        result[ :generationConfig ].delete( :model )
-        result[ :generationConfig ].delete( :stream )
-
-        # construct the system prompt in the form of the google schema
-        system_instructions = translate_system_message( conversation[ :system_message ] )
-        result[ :systemInstruction ] = system_instructions if system_instructions
-
-        result[ :contents ] = []
-        conversation[ :messages ]&.each do | message |
-
-          result_message = { role: message[ :role ] == :user ? 'user' : 'model' }
-          result_message_parts = []
-          
-          message[ :contents ]&.each do | content |
-            case content[ :type ]
-            when :text
-              result_message_parts << { text: content[ :text ] }
-            when :binary
-              content_type = content[ :content_type ]
-              bytes = content[ :bytes ]
-              if content_type && bytes
-                unless MIME::Types[ content_type ].empty?
-                  # TODO: verify the specific google supported MIME types
-                  result_message_parts << {
-                    inline_data: {
-                      mime_type: content_type,
-                      data: Base64.strict_encode64( bytes )
-                    }
-                  }
-                else
-                  raise UnsupportedContentError.new( 
-                    :google, 
-                    'only support recognized mime types' 
-                  ) 
-                end
-              else 
-                raise UnsupportedContentError.new(
-                  :google, 
-                  'requires binary content to include content type and ( packed ) bytes'  
-                )
-              end
-            end 
-          end
-
-          result_message[ :parts ] = result_message_parts
-          result[ :contents ] << result_message
-
-        end
-
-        JSON.generate( result )
-
-      end 
-
-      def chat_result_attributes( response )
+       def chat_result_attributes( response )
 
         return nil unless response.success?
 
         response_json = JSON.parse( response.body, symbolize_names: true ) rescue nil
-        return nil \
-          if response_json.nil? || response_json[ :candidates ].nil?
+        return nil if response_json.nil? || response_json[ :candidates ].nil?
         
         result = {}
         result[ :choices ] = []
@@ -120,13 +24,21 @@ module Intelligence
           response_content = response_choice[ :content ]
           if response_content
             role = ( response_content[ :role ] == 'model' ) ? 'assistant' : 'user'
-
             contents = []
             response_content[ :parts ]&.each do | response_content_part |
               if response_content_part.key?( :text )              
                 contents.push( {
                   type: 'text', text: response_content_part[ :text ]
                 } )
+              elsif function_call = response_content_part[ :functionCall ]                
+                contents.push( {
+                  type: :tool_call, 
+                  tool_name: function_call[ :name ],
+                  tool_parameters: function_call[ :args ]
+                } )
+                # google does not indicate there is tool call in the stop reason so 
+                # we will synthesize this end reason
+                end_reason = :tool_called if end_reason == :ended
               end
             end
           end
@@ -178,7 +90,6 @@ module Intelligence
       end
 
       def stream_result_chunk_attributes( context, chunk )
-      #---------------------------------------------------
 
         context ||= {}
         buffer = context[ :buffer ] || ''
@@ -257,7 +168,6 @@ module Intelligence
       end
 
       def stream_result_attributes( context )
-      #--------------------------------------
 
         choices = context[ :choices ]
         metrics = context[ :metrics ]
@@ -272,71 +182,51 @@ module Intelligence
 
       alias_method :stream_result_error_attributes, :chat_result_error_attributes
 
-      private; def translate_system_message( system_message )
-      # -----------------------------------------------------
-
-        return nil if system_message.nil?
-
-        text = ''
-        system_message[ :contents ].each do | content |
-          text += content[ :text ] if content[ :type ] == :text 
-        end
-
-        return nil if text.empty?
-
-        {
-          role: 'user',
-          parts: [
-            { text: text }
-          ] 
-        }
-
-      end 
-
-      private; def translate_finish_reason( finish_reason )
-      # ---------------------------------------------------
+    private 
+    
+      def translate_finish_reason( finish_reason )
         case finish_reason
-          when 'STOP'
-            :ended
-          when 'MAX_TOKENS'
-            :token_limit_exceeded
-          when 'SAFETY', 'RECITATION', 'BLOCKLIST', 'PROHIBITED_CONTENT', 'SPII'
-            :filtered
-          else
-            nil
+        when 'STOP'
+          :ended
+        when 'MAX_TOKENS'
+          :token_limit_exceeded
+        when 'SAFETY', 'RECITATION', 'BLOCKLIST', 'PROHIBITED_CONTENT', 'SPII'
+          :filtered
+        else
+          nil
         end
       end
     
-      private; def translate_error_response_status( status )
+      def translate_error_response_status( status )
         case status
-          when 400
-            [ :invalid_request_error, 
-              "There was an issue with the format or content of your request." ]
-          when 403
-            [ :permission_error, 
-              "Your API key does not have permission to use the specified resource." ]
-          when 404
-            [ :not_found_error, 
-              "The requested resource was not found." ]
-          when 413
-            [ :request_too_large, 
-              "Request exceeds the maximum allowed number of bytes." ]
-          when 422
-            [ :invalid_request_error, 
-              "There was an issue with the format or content of your request." ]
-          when 429
-            [ :rate_limit_error, 
-              "Your account has hit a rate limit." ]
-          when 500, 502, 503
-            [ :api_error, 
-              "An unexpected error has occurred internal to the providers systems." ]
-          when 529
-            [ :overloaded_error, 
-              "The providers server is temporarily overloaded." ]
-          else
-            [ :unknown_error, "
-              An unknown error occurred." ]
-          end
+        when 400
+          [ :invalid_request_error, 
+            "There was an issue with the format or content of your request." ]
+        when 403
+          [ :permission_error, 
+            "Your API key does not have permission to use the specified resource." ]
+        when 404
+          [ :not_found_error, 
+            "The requested resource was not found." ]
+        when 413
+          [ :request_too_large, 
+            "Request exceeds the maximum allowed number of bytes." ]
+        when 422
+          [ :invalid_request_error, 
+            "There was an issue with the format or content of your request." ]
+        when 429
+          [ :rate_limit_error, 
+            "Your account has hit a rate limit." ]
+        when 500, 502, 503
+          [ :api_error, 
+            "An unexpected error has occurred internal to the providers systems." ]
+        when 529
+          [ :overloaded_error, 
+            "The providers server is temporarily overloaded." ]
+        else
+          [ :unknown_error, "
+            An unknown error occurred." ]
+        end
       end
 
     end

data/lib/intelligence/adapters/groq.rb

@@ -7,41 +7,59 @@ module Intelligence
       
       chat_request_uri 'https://api.groq.com/openai/v1/chat/completions'
 
-      configuration do 
-        parameter :key, String, required: true
-        group :chat_options do 
-          parameter :frequency_penalty, Float
-          parameter :logit_bias
-          parameter :logprobs, [ TrueClass, FalseClass ]
-          parameter :max_tokens, Integer
-          parameter :model, String
-          parameter :n, Integer
-            # the parallel_tool_calls parameter is only allowed when 'tools' are specified
-          parameter :parallel_tool_calls, [ TrueClass, FalseClass ]
-          parameter :presence_penalty, Float
-          group :response_format do 
+      schema do 
+        key                   String
+        chat_options do 
+          frequency_penalty   Float
+          logit_bias
+          logprobs            [ TrueClass, FalseClass ]
+          max_tokens          Integer
+          model               String
+          # the parallel_tool_calls is only allowed when 'tools' are specified
+          parallel_tool_calls [ TrueClass, FalseClass ]
+          presence_penalty    Float
+          response_format do 
             # 'text' and 'json_object' are the only supported types; you must also instruct 
             # the model to output json
-            parameter :type, String
+            type              Symbol, in: [ :text, :json_object ]
           end
-          parameter :seed, Integer
-          parameter :stop, String, array: true
-          parameter :stream, [ TrueClass, FalseClass ]
-          group :stream_options do
-            parameter :include_usage, [ TrueClass, FalseClass ]
+          seed                Integer
+          stop                String, array: true
+          stream              [ TrueClass, FalseClass ]
+          stream_options do
+            include_usage     [ TrueClass, FalseClass ]
           end
-          parameter :temperature, Float
-          group :tool_choice do 
+          temperature         Float
+          tool_choice do 
             # one of 'auto', 'none' or 'function'
-            parameter :type, String 
-            # the function group is required if you specify a type of 'function' 
-            group :function do 
-              parameter :name, String 
+            type              Symbol, in: [ :auto, :none, :function ]
+            # the function parameters is required if you specify a type of 'function' 
+            function do 
+              name            String 
             end
           end
-          parameter :top_logprobs, Integer
-          parameter :top_p, Float
-          parameter :user, String
+          top_logprobs        Integer
+          top_p               Float
+          user                String
+        end
+      end
+
+      alias chat_request_generic_message_attributes chat_request_message_attributes 
+      
+      # groq models only support the legacy Open AI message schema for the assistant 
+      # messages while supporting the modern message schema for user messages 
+      def chat_request_message_attributes( message )
+        role = message[ :role ]&.to_sym 
+        case role 
+        when :user 
+          chat_request_generic_message_attributes( message )
+        when :assistant 
+          chat_request_legacy_message_attributes( message )
+        else 
+          raise UnsupportedContentError.new(
+            :mistral, 
+            'only supports user and assistant message roles'  
+          )
         end
       end