intelligence 0.5.0

data/lib/intelligence/adapters/open_ai/chat_methods.rb

@@ -0,0 +1,314 @@
+module Intelligence
+  module OpenAi
+    module ChatMethods
+
+      CHAT_REQUEST_URI = "https://api.openai.com/v1/chat/completions"
+
+      def chat_request_uri( options )
+        CHAT_REQUEST_URI
+      end
+
+      def chat_request_headers( options = {} )
+        result = {}
+
+        key = options[ :key ] || self.key
+        organization = options[ :organization ] || self.organization 
+        project = options[ :project ] || self.project 
+
+        raise ArgumentError.new( "An OpenAI key is required to build an OpenAI chat request." ) \
+          if key.nil?
+
+        result[ 'Content-Type' ] = 'application/json'
+        result[ 'Authorization' ] = "Bearer #{key}"
+        result[ 'OpenAI-Organization' ] = organization unless organization.nil?
+        result[ 'OpenAI-Project' ] = project unless project.nil?
+
+        result 
+      end
+
+      def chat_request_body( conversation, options = {} )
+        result = self.chat_options.merge( options ).compact
+        result[ :messages ] = []
+
+        system_message = translate_system_message( conversation[ :system_message ] )
+        result[ :messages ] << { role: 'system', content: system_message } if system_message
+
+        conversation[ :messages ]&.each do | message |
+
+          result_message = { role: message[ :role ] }
+          result_message_content = []
+          
+          message[ :contents ]&.each do | content |
+            case content[ :type ]
+            when :text
+              result_message_content << { type: 'text', 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 mime_type&.media_type == 'image'
+                  result_message_content << {
+                    type: 'image_url',
+                    image_url: {
+                      url: "data:#{content_type};base64,#{Base64.strict_encode64( bytes )}".freeze
+                    }
+                  }
+                else
+                  raise UnsupportedContentError.new( 
+                    :open_ai, 
+                    'only supports content of type image/*' 
+                  ) 
+                end
+              else 
+                raise UnsupportedContentError.new(
+                  :open_ai, 
+                  'requires binary content to include content type and ( packed ) bytes'  
+                )
+              end
+            end 
+          end
+
+          result_message[ :content ] = result_message_content
+          result[ :messages ] << result_message
+
+        end
+
+        JSON.generate( result )
+      end 
+
+      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[ :choices ].nil?
+        
+        result = {}
+        result[ :choices ] = []
+
+        ( response_json[ :choices ] || [] ).each do | json_choice |
+          json_message = json_choice[ :message ]
+          result[ :choices ].push(
+            { 
+              end_reason: translate_end_result( json_choice[ :finish_reason ] ), 
+              message: { 
+                role: json_message[ :role ],
+                contents: [ { type: 'text', text: json_message[ :content ] } ]
+              } 
+            }
+          )
+        end
+
+        metrics_json = response_json[ :usage ]
+        unless metrics_json.nil?
+
+          metrics = {}
+          metrics[ :input_tokens ] = metrics_json[ :prompt_tokens ] 
+          metrics[ :output_tokens ] = metrics_json[ :completion_tokens ]
+          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
+        }
+
+        parsed_body = JSON.parse( response.body, symbolize_names: true ) rescue nil 
+        if parsed_body && parsed_body.respond_to?( :include? ) && 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
+          }
+        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 ] = ''
+              when :tool_call 
+                content[ :tool_parameters ] = ''
+              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 ]
+
+          next if line.end_with?( '[DONE]' )
+          data = JSON.parse( line )
+
+          if data.is_a?( Hash )
+            
+            data[ 'choices' ]&.each do | data_choice |
+
+              data_choice_index = data_choice[ 'index' ]
+              data_choice_delta = data_choice[ 'delta' ]
+              data_choice_finish_reason = data_choice[ 'finish_reason' ]
+              
+              choices.fill( { message: {} }, choices.size, data_choice_index + 1 ) \
+                if choices.size <= data_choice_index 
+              contents = choices[ data_choice_index ][ :message ][ :contents ] || []
+              last_content = contents&.last 
+              
+              if data_choice_delta.include?( 'content' ) 
+                data_choice_content = data_choice_delta[ 'content' ] || ''
+                if last_content.nil? || last_content[ :type ] == :tool_call
+                  contents.push( { type: :text, text: data_choice_content } )
+                elsif last_content[ :type ].nil?
+                  last_content[ :type ] = :text 
+                  last_content[ :text ] = data_choice_content
+                elsif last_content[ :type ] == :text 
+                  last_content[ :text ] = ( last_content[ :text ] || '' ) + data_choice_content
+                end
+              elsif data_choice_delta.include?( 'function_call' )
+                data_choice_tool_call = data_choice_delta[ 'function_call' ] 
+                data_choice_tool_name = data_choice_tool_call[ 'name' ]
+                data_choice_tool_parameters = data_choice_tool_call[ 'arguments' ]
+                if last_content.nil? || last_content[ :type ] == :text
+                  contents.push( { 
+                    type: :tool_call, 
+                    tool_name: data_choice_tool_name,
+                    tool_parameters: data_choice_tool_parameters
+                  } )
+                elsif last_content[ :type ].nil?
+                  last_content[ :type ] = :tool_call 
+                  last_content[ :tool_name ] = data_choice_tool_name if data_choice_tool_name.present?
+                  last_content[ :tool_parameters ] = tool_parameters
+                elsif last_content[ :type ] == :tool_call 
+                  last_content[ :tool_parameters ] = 
+                    ( last_content[ :tool_parameters ] || '' ) + data_choice_tool_parameters
+                end
+              end
+              choices[ data_choice_index ][ :message ][ :contents ] = contents
+              choices[ data_choice_index ][ :end_reason ] = 
+                translate_end_result( data_choice_finish_reason )
+            end
+  
+            if usage = data[ 'usage' ]
+              metrics[ :input_tokens ] += usage[ 'prompt_tokens' ]
+              metrics[ :output_tokens ] += usage[ 'completion_tokens' ]
+            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_system_message( system_message )
+
+        return nil if system_message.nil?
+
+        result = ''
+        system_message[ :contents ].each do | content |
+          result += content[ :text ] if content[ :type ] == :text 
+        end
+
+        result.empty? ? nil : result 
+
+      end 
+
+      private; def translate_end_result( end_result )
+        case end_result
+          when 'stop'
+            :ended
+          when 'length'
+            :token_limit_exceeded
+          when 'function_call'
+            :tool_called
+          when 'content_filter'
+            :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 401
+            [ :authentication_error, 
+              "There's an issue with your API key." ]
+          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/open_ai.rb

@@ -0,0 +1,2 @@
+require_relative '../adapter'
+require_relative 'open_ai/adapter'

data/lib/intelligence/adapters/samba_nova.rb

@@ -0,0 +1,64 @@
+require_relative 'legacy/adapter'
+
+module Intelligence
+  module SambaNova
+
+    class Adapter < Legacy::Adapter
+
+      chat_request_uri "https://api.sambanova.ai/v1/chat/completions"
+      
+      configuration do 
+
+        # normalized properties for all endpoints
+        parameter :key, String, required: true
+        
+        # properties for generative text endpoints
+        group :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 ]
+
+          # samba nova properties for samba nova generative text endpoint
+          parameter :repetition_penalty, Float
+          group :stream_options do
+            parameter :include_usage, [ TrueClass, FalseClass ]
+          end
+
+        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? ) && 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 response.headers[ 'content-type' ].start_with?( 'text/plain' ) &&
+              response.body && response.body.length > 0
+          result[ :error_description ] = response.body
+        end
+
+        result
+
+      end
+
+    end
+
+  end
+end

data/lib/intelligence/adapters/together_ai.rb

@@ -0,0 +1,46 @@
+require_relative 'legacy/adapter'
+
+module Intelligence
+  module TogetherAi
+
+    class Adapter < Legacy::Adapter
+
+      chat_request_uri "https://api.together.xyz/v1/chat/completions"
+      
+      configuration do 
+        parameter :key, String, required: true 
+        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
+        end
+      end
+
+      def translate_end_result( end_result )
+        case end_result
+          when 'eos'
+            :ended
+          when 'length'
+            :token_limit_exceeded
+          when 'stop'
+            :end_sequence_encountered
+          when 'function_call'
+            :tool_called
+          else
+            nil
+        end
+      end
+
+    end
+
+  end
+end

data/lib/intelligence/chat_error_result.rb

@@ -0,0 +1,11 @@
+module Intelligence
+
+	#
+	# class. ChatErrorResult
+	#
+	# The ChatErrorResult class encapsulates error result from a chat request. 
+	#
+	class ChatErrorResult < ErrorResult 
+	end
+
+end

data/lib/intelligence/chat_metrics.rb

@@ -0,0 +1,32 @@
+module Intelligence
+
+  #
+  # class. ChatMetrics
+  #
+  # The ChatMetrics class encapsulates metrics information. These metrics include the number of
+  # input tokens consumed, the number of output tokens generated, the total number of tokens,
+  # and the duration of the request in milliseconds.
+  #
+  class ChatMetrics 
+  # ---------------
+    
+    attr_reader   :duration
+
+    attr_reader   :input_tokens
+    attr_reader   :output_tokens
+
+    def initialize( attributes )
+      attributes.each do | key, value |
+        instance_variable_set( "@#{key}", value ) if self.respond_to?( "#{key}" )
+      end
+    end
+
+    def total_tokens
+      @total_tokens = @input_tokens + @output_tokens \
+        if @total_tokens.nil? && @input_tokens && @output_tokens 
+      @total_tokens
+    end
+
+  end
+
+end

data/lib/intelligence/chat_request.rb

@@ -0,0 +1,117 @@
+module Intelligence
+
+  #
+  # module. ChatRequestMethods
+  #
+  # The ChatRequestMethods module extends a Faraday request, adding the +receive_result+ method. 
+  #
+  module ChatRequestMethods
+
+    def receive_result( &block )
+       @_intelligence_result_callback = block
+    end 
+
+  end
+
+  #
+  # module. ChatResponseMethods
+  #
+  # The ChatResponseMethods module extends a Farada reponse, adding the +result+  method. 
+  #
+  module ChatResponseMethods
+
+    def result
+      @_intelligence_result
+    end 
+
+  end
+
+  #
+  # class. ChatRequest
+  #
+  class ChatRequest 
+
+    DEFAULT_CONNECTION = Faraday.new { | builder | builder.adapter Faraday.default_adapter }
+
+    def initialize( connection: nil, adapter: , **options )
+      @connection = connection || DEFAULT_CONNECTION
+      @adapter = adapter
+      @options = options || {}
+
+      raise ArgumentError.new( 'An adapter must be configured before a request is constructed.' ) \
+        if @adapter.nil?
+    end
+
+    def chat( conversation, options = {} )
+
+      options = @options.merge( options )
+
+      uri = @adapter.chat_request_uri( options )
+      headers = @adapter.chat_request_headers( @options.merge( options ) )
+      payload = @adapter.chat_request_body( 
+        conversation.to_h, 
+        options 
+      )
+
+      result_callback = nil 
+      response = @connection.post( uri ) do | request |
+        headers.each { | key, value | request.headers[ key ] = value }
+        request.body = payload          
+        yield request.extend( ChatRequestMethods ) if block_given?
+        result_callback = request.instance_variable_get( "@_intelligence_result_callback" )
+      end
+
+      result = nil 
+      if response.success?  
+        chat_result_attributes = @adapter.chat_result_attributes( response )
+        result = ChatResult.new( chat_result_attributes )
+      else 
+        error_result_attributes = @adapter.chat_result_error_attributes( response )
+        result = ChatErrorResult.new( error_result_attributes )
+      end
+      
+      response.instance_variable_set( "@_intelligence_result", result )
+      response.extend( ChatResponseMethods ) 
+    
+    end
+
+    def stream( conversation, options = {} )
+
+      options = @options.merge( options )
+
+      uri = @adapter.chat_request_uri( options )
+      headers = @adapter.chat_request_headers( @options.merge( options ) )
+      payload = @adapter.chat_request_body( conversation.to_h, options )
+
+      context = nil
+      response = @connection.post( uri ) do | request |
+
+        headers.each { | key, value | request.headers[ key ] = value }
+        request.body = payload
+        yield request.extend( ChatRequestMethods ) 
+
+        result_callback = request.instance_variable_get( "@_intelligence_result_callback" )
+        request.options.on_data = Proc.new do | chunk, received_bytes |
+          context, attributes = @adapter.stream_result_chunk_attributes( context, chunk )
+          result_callback.call( ChatResult.new( attributes ) ) unless attributes.nil?
+        end 
+
+      end
+
+      result = nil 
+      if response.success?  
+        stream_result_attributes = @adapter.stream_result_attributes( context )
+        result = ChatResult.new( stream_result_attributes )
+      else 
+        error_result_attributes = @adapter.stream_result_error_attributes( response )
+        result = ChatErrorResult.new( error_result_attributes )
+      end
+      
+      response.instance_variable_set( "@_intelligence_result", result )
+      response.extend( ChatResponseMethods )
+    
+    end
+
+  end
+
+end

data/lib/intelligence/chat_result.rb

@@ -0,0 +1,32 @@
+module Intelligence
+
+  #
+  # class. ChatResult
+  #
+  # The ChatResult class encapsulates a successful result to a chat or stream request. A result 
+  # includes an array of choices ( it is an array even if there is a single choice ) and the 
+  # metrics associated with the generation of all result choices.
+  #
+  class ChatResult
+
+    attr_reader :choices
+    attr_reader :metrics
+
+    def initialize( chat_attributes )
+
+      @choices = []
+      chat_attributes[ :choices ]&.each do | json_choice |
+        @choices.push( ChatResultChoice.new( json_choice ) )
+      end
+      @metrics = ChatMetrics.new( chat_attributes[ :metrics ] ) \
+        if chat_attributes.key?( :metrics )
+    end
+
+    def message 
+      return nil if @choices.empty?
+      @choices.first.message
+    end
+
+  end
+
+end

data/lib/intelligence/chat_result_choice.rb

@@ -0,0 +1,26 @@
+module Intelligence
+
+  class ChatResultChoice 
+
+    attr_reader :message
+    attr_reader :end_reason
+    attr_reader :end_sequence
+
+    def initialize( chat_choice_attributes )
+      @end_reason = chat_choice_attributes[ :end_reason ]
+      @end_sequence = chat_choice_attributes[ :end_sequence ]
+      @message = build_message( chat_choice_attributes[ :message ] ) \
+        if chat_choice_attributes[ :message ]
+    end
+
+    private; def build_message( json_message )
+      message = Message.new( json_message[ :role ]&.to_sym || :assistant )
+      json_message[ :contents ]&.each do | json_content |
+        message << MessageContent.build( json_content[ :type ], json_content )
+      end
+      message 
+    end
+
+  end
+
+end

data/lib/intelligence/conversation.rb

@@ -0,0 +1,48 @@
+module Intelligence
+
+  #
+  # class. Conversation
+  #
+  class Conversation 
+
+    attr_reader   :system_message
+    attr_reader   :messages
+    attr_reader   :tools
+
+    def initialize( attributes = {} )
+      @system_message = attributes[ :system_message ]&.dup
+      @messages = attributes[ :messages ]&.dup || []
+      @tools = attributes[ :tools ]&.dup || [] 
+    end
+
+    def has_system_message?
+      ( @system_message || false ) && !@system_message.empty?
+    end
+
+    def has_messages?
+      !@messages.empty?
+    end
+
+    def has_tools?
+      !@tools.empty?
+    end
+
+    def system_message=( message )
+      raise ArgumentError, "The system message must be a Intelligence::Message." \
+        unless message.is_a?( Intelligence::Message )
+      raise ArgumentError, "The system message MUST have a role of 'system'." \
+        unless message.role == :system
+      @system_message = message
+    end
+
+    def to_h
+      result = {}
+      result[ :system_message ] = @system_message.to_h if @system_message
+      result[ :messages ] = @messages.map { | m | m.to_h } 
+      result[ :tools ] = @tools.map { | t | t.to_h } 
+      result
+    end
+
+  end
+
+end