intelligence 0.6.0 → 0.8.0

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

@@ -0,0 +1,234 @@
+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 ] = [ { function_declarations: tools_attributes } ] \
+          if tools_attributes&.any?
+
+        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 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_response_methods.rb

@@ -0,0 +1,236 @@
+require 'uri'
+
+module Intelligence
+  module Google
+    module ChatResponseMethods
+
+       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?
+        
+        result = {}
+        result[ :choices ] = []
+
+        response_json[ :candidates ]&.each do | response_choice |
+
+          end_reason = translate_finish_reason( response_choice[ :finishReason ] )
+          
+          role = nil 
+          contents = []
+
+          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
+
+          result_message = nil 
+          if role
+            result_message = { role: role }
+            result_message[ :contents ] = contents
+          end
+
+          result[ :choices ].push( { end_reason: end_reason, message: result_message } )
+        
+        end
+
+        metrics_json = response_json[ :usageMetadata ]
+        unless metrics_json.nil?
+
+          metrics = {}
+          metrics[ :input_tokens ] = metrics_json[ :promptTokenCount ] 
+          metrics[ :output_tokens ] = metrics_json[ :candidatesTokenCount ]
+          metrics = metrics.compact
+
+          result[ :metrics ] = metrics unless metrics.empty?
+
+        end
+
+        result
+      
+      end
+
+      def chat_result_error_attributes( response )
+
+        error_type, error_description = translate_error_response_status( response.status )
+        result = { error_type: error_type.to_s, error_description: error_description }
+
+        response_body = JSON.parse( response.body, symbolize_names: true ) rescue nil 
+        if response_body && response_body[ :error ]
+          error_details_reason = response_body[ :error ][ :details ]&.first&.[]( :reason )
+          # a special case for authentication 
+          error_type = :authentication_error if error_details_reason == 'API_KEY_INVALID'
+          result = {
+            error_type: error_type.to_s,
+            error: error_details_reason || response_body[ :error ][ :status ] || error_type,
+            error_description: response_body[ :error ][ :message ]
+          }
+        end
+        result
+
+      end
+
+      def stream_result_chunk_attributes( context, chunk )
+
+        context ||= {}
+        buffer = context[ :buffer ] || ''
+        metrics = context[ :metrics ] || {
+          input_tokens: 0,
+          output_tokens:  0
+        }
+        choices = context[ :choices ] || Array.new( 1 , { message: {} } )
+
+        choices.each do | choice |
+          choice[ :message ][ :contents ] = choice[ :message ][ :contents ]&.map do | content |
+            case content[ :type ] 
+              when :text 
+                content[ :text ] = ''
+              else 
+                content.clear 
+            end
+            content
+          end
+        end
+
+        buffer += chunk
+        while ( eol_index = buffer.index( "\n" ) )
+
+          line = buffer.slice!( 0..eol_index )        
+          line = line.strip 
+          next if line.empty? || !line.start_with?( 'data:' )
+          line = line[ 6..-1 ]
+
+          data = JSON.parse( line, symbolize_names: true )
+          if data.is_a?( Hash )
+            
+            data[ :candidates ]&.each do | data_candidate |
+
+              data_candidate_index = data_candidate[ :index ] || 0
+              data_candidate_content = data_candidate[ :content ]
+              data_candidate_finish_reason = data_candidate[ :finishReason ]
+              choices.fill( { message: { role: 'assistant' } }, choices.size, data_candidate_index + 1 ) \
+                if choices.size <= data_candidate_index 
+              contents = choices[ data_candidate_index ][ :message ][ :contents ] || []
+              last_content = contents&.last 
+              
+              if data_candidate_content&.include?( :parts ) 
+                data_candidate_content_parts = data_candidate_content[ :parts ]
+                data_candidate_content_parts&.each do | data_candidate_content_part |
+                  if data_candidate_content_part.key?( :text )
+                    if last_content.nil? || last_content[ :type ] != :text
+                      contents.push( { type: :text, text: data_candidate_content_part[ :text ] } )
+                    else 
+                      last_content[ :text ] = 
+                        ( last_content[ :text ] || '' ) + data_candidate_content_part[ :text ]
+                    end
+                  end
+                end
+              end
+              choices[ data_candidate_index ][ :message ][ :contents ] = contents
+              choices[ data_candidate_index ][ :end_reason ] = 
+                translate_finish_reason( data_candidate_finish_reason )
+            end
+  
+            if usage = data[ :usageMetadata ]
+              metrics[ :input_tokens ] = usage[ :promptTokenCount ]
+              metrics[ :output_tokens ] = usage[ :candidatesTokenCount ]
+            end 
+
+          end
+
+        end
+
+        context[ :buffer ] = buffer 
+        context[ :metrics ] = metrics
+        context[ :choices ] = choices
+
+        [ context, choices.empty? ? nil : { choices: choices.dup } ]
+
+      end
+
+      def stream_result_attributes( context )
+
+        choices = context[ :choices ]
+        metrics = context[ :metrics ]
+
+        choices = choices.map do | choice |
+          { end_reason: choice[ :end_reason ] }
+        end
+
+        { choices: choices, metrics: context[ :metrics ] }
+
+      end
+
+      alias_method :stream_result_error_attributes, :chat_result_error_attributes
+
+    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
+        end
+      end
+    
+      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
+      end
+
+    end
+
+  end
+
+end

data/lib/intelligence/adapters/groq.rb

@@ -1,66 +1,46 @@
-require_relative 'legacy/adapter'
+require_relative 'generic/adapter'
 
 module Intelligence
   module Groq
 
-    class Adapter < Legacy::Adapter
+    class Adapter < Generic::Adapter
       
       chat_request_uri 'https://api.groq.com/openai/v1/chat/completions'
 
-      configuration do 
-        parameter :key, String
-        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
-        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'  
-          )
+          top_logprobs        Integer
+          top_p               Float
+          user                String
         end
       end
 

data/lib/intelligence/adapters/hyperbolic.rb

@@ -7,48 +7,22 @@ module Intelligence
 
       chat_request_uri "https://api.hyperbolic.xyz/v1/chat/completions"
       
-      configuration do 
-        parameter :key, String 
-        group :chat_options do 
-          parameter :model, String
-          parameter :temperature, Float
-          parameter :top_p, Float
-          parameter :n, Integer
-          parameter :max_tokens, Integer
-          parameter :stop, String, array: true
-          parameter :stream, [ TrueClass, FalseClass ]
-          parameter :frequency_penalty, Float
-          parameter :presence_penalty, Float
-          parameter :user, String
+      schema do 
+        key                 String 
+        chat_options do 
+          model             String
+          temperature       Float
+          top_p             Float
+          n                 Integer
+          max_tokens        Integer
+          stop              String, array: true
+          stream            [ TrueClass, FalseClass ]
+          frequency_penalty Float
+          presence_penalty  Float
+          user              String
         end
       end
 
-      def chat_result_error_attributes( response )
-
-        error_type, error_description = translate_error_response_status( response.status )
-        result = {
-          error_type: error_type.to_s,
-          error_description: error_description
-        }
-        parsed_body = JSON.parse( response.body, symbolize_names: true ) rescue nil 
-        if parsed_body && parsed_body.respond_to?( :include? )
-          if parsed_body.include?( :error )
-            result = {
-              error_type: error_type.to_s,
-              error: parsed_body[ :error ][ :code ] || error_type.to_s,
-              error_description: parsed_body[ :error ][ :message ] || error_description
-            }
-          elsif parsed_body.include?( :detail )
-            result[ :error_description ] = parsed_body[ :detail ]
-          elsif parsed_body[ :object ] == 'error'
-            result[ :error_description ] = parsed_body[ :message ]
-          end
-        end
-
-        result
-
-      end
-
     end
 
   end