intelligence 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 694776aeafc7552879d8b9d5358907e62c90a6fc5a1219081ee1d1a4cb5ddeef
+  data.tar.gz: 380f5cd13200750f65938fd4e92c21218af8c2b57af0614bfe16f714ba296e68
+SHA512:
+  metadata.gz: f2ca65b2a4e3a202bc1b331f7965da9e76a8ccd2ec83f7c5c273c94137fb1e0131226ecf3bf2aed6d50e262933d26c0024b3a5052edda28c39768c766b508e29
+  data.tar.gz: c6694ffa62ddd9eb766f42fb9cc073195a01e11e0d34cd346588b3923266c14f794d1711e1766888369874e27ce4ac696de0513055af8e27149a778611ce0cb2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Endless International
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/intelligence.gemspec

@@ -0,0 +1,47 @@
+require_relative 'lib/intelligence/version'
+
+Gem::Specification.new do | spec |
+
+  spec.name          = 'intelligence'
+  spec.version       = Intelligence::VERSION
+  spec.authors       = [ 'Kristoph Cichocki-Romanov' ]
+  spec.email         = [ 'rubygems.org@kristoph.net' ]
+
+  spec.summary       = <<~TEXT.gsub( "\n", " " ).strip
+    A Ruby gem for seamlessly and uniformly interacting with large languge and vision model (LLM) 
+    API's served by numerous services, including those of OpenAI, Anthropic, Google and others. 
+  TEXT
+  spec.description   = <<~TEXT.gsub( "\n", " " ).strip
+    Intelligence is a lightweight yet powerful Ruby gem that allows you to seamlessly and uniformly 
+    interact with large language and vision models (LLM) API's of numerous vendors, including 
+    OpenAI, Anthropic, Google, Cerebras, Groq, Hyperbolic, Samba Nova and Together AI. It can be 
+    trivially expanded to other OpenAI conformant API providers as well as self hosted models.
+
+    Intelligence supports text models in streaming and non-streaming mode, vision models, and 
+    tool use.  
+
+    Intelligence has minimal dependencies and does not require the vendors ( often bloated )
+    SDK's. 
+  TEXT
+
+  spec.license       = 'MIT'
+  spec.homepage      = 'https://github.com/EndlessInternational/intelligence'
+  spec.metadata = {
+    'source_code_uri'   => 'https://github.com/EndlessInternational/intelligence',
+    'bug_tracker_uri'   => 'https://github.com/EndlessInternational/intelligence/issues',
+#    'documentation_uri' => 'https://github.com/EndlessInternational/intelligence/wiki'
+  }
+
+  spec.required_ruby_version = '>= 3.0'
+  spec.files         = Dir[ "lib/**/*.rb", "LICENSE", "README.md", "intelligence.gemspec" ]
+  spec.require_paths = [ "lib" ]
+
+  spec.add_runtime_dependency 'faraday', '~> 2.7'
+  spec.add_runtime_dependency 'adaptiveconfiguration', '~> 1.0.0.beta01'
+  spec.add_runtime_dependency 'mime-types', '~> 3.6'
+
+  spec.add_development_dependency 'rspec', '~> 3.4'
+  spec.add_development_dependency 'debug', '~> 1.9'
+  spec.add_development_dependency 'vcr', '~> 6.3'
+
+end

data/lib/intelligence/adapter/base.rb

@@ -0,0 +1,7 @@
+module Intelligence
+  module Adapter
+    class Base
+      extend AdaptiveConfiguration::Configurable
+    end 
+  end
+end

data/lib/intelligence/adapter/construction_methods.rb

@@ -0,0 +1,37 @@
+module Intelligence
+  module Adapter
+    module ConstructionMethods
+
+      def []( adapter_type )
+
+        raise ArgumentError.new( "An adapter type is required but nil was given." ) \
+          if adapter_type.nil?
+
+        class_name = adapter_type.to_s.split( '_' ).map( &:capitalize ).join
+        class_name += "::Adapter"
+
+        adapter_class = Intelligence.const_get( class_name ) rescue nil
+        if adapter_class.nil?
+          adapter_file = File.expand_path( "../../adapters/#{adapter_type}", __FILE__ )
+          unless require adapter_file
+            raise ArgumentError.new( 
+              "The Intelligence adapter file #{adapter_file} is missing or does not define #{class_name}." 
+            )
+          end
+          adapter_class = Intelligence.const_get( class_name ) rescue nil
+        end
+
+        raise ArgumentError.new( "An unknown Intelligence adapter #{adapter_type} was configured." ) \
+          if adapter_class.nil? 
+
+        adapter_class
+
+      end
+
+      def build( adapter_type, attributes, &block )
+        self.[]( adapter_type ).new( attributes, &block )
+      end
+
+    end
+  end
+end  

data/lib/intelligence/adapter.rb

@@ -0,0 +1,8 @@
+require_relative 'adapter/construction_methods'
+require_relative 'adapter/base'
+
+module Intelligence
+  module Adapter
+    extend ConstructionMethods
+  end
+end

data/lib/intelligence/adapter_error.rb

@@ -0,0 +1,8 @@
+module Intelligence 
+  class AdapterError < Error;
+    def initialize( adapter_type, text )
+      adapter_class_name = adapter_type.to_s.split( '_' ).map( &:capitalize ).join
+      super( "The #{adapter_class_name} #{text}." )
+    end
+  end 
+end

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

@@ -0,0 +1,59 @@
+require_relative 'chat_methods'
+
+module Intelligence
+  module Anthropic
+    class Adapter < Adapter::Base
+
+      configuration do 
+
+        # normalized properties for all endpoints
+        parameter :key, required: true 
+
+        # anthropic specific properties for all endpoints
+        parameter :version, String, required: true, default: '2023-06-01'
+ 
+        group :chat_options do 
+  
+          # normalized properties for anthropic generative text endpoint
+          parameter :model, String, required: true
+          parameter :max_tokens, Integer, required: true
+          parameter :temperature, Float
+          parameter :top_k, Integer
+          parameter :top_p, Float
+          parameter :stop, String, array: true, as: :stop_sequences
+          parameter :stream, [ TrueClass, FalseClass ]
+
+          # anthropic variant of normalized properties for anthropic generative text endpoints
+          parameter :stop_sequences, String, array: true
+
+          # anthropic specific properties for anthropic generative text endpoints
+          parameter :tool_choice do 
+            parameter :type, String  
+            # the name parameter should only be set if type = 'tool'
+            parameter :name, String
+          end
+          group :metadata do
+            parameter :user_id, String
+          end 
+          
+        end
+        
+      end
+
+      attr_reader :key
+      attr_reader :version
+      attr_reader :chat_options
+
+      def initialize( attributes = nil, &block )
+        configuration = self.class.configure( attributes, &block ) 
+        @key = configuration[ :key ]
+        @version = configuration[ :version ]
+        @chat_options = configuration[ :chat_options ] || {}
+      end
+
+      include ChatMethods
+
+    end 
+  end
+end
+

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

@@ -0,0 +1,358 @@
+require 'base64'
+
+module Intelligence
+  module Anthropic
+    module ChatMethods
+
+      CHAT_REQUEST_URI = "https://api.anthropic.com/v1/messages"
+
+      def chat_request_uri( options )
+        CHAT_REQUEST_URI
+      end
+
+      def chat_request_headers( options = {} )
+        result = {}
+
+        key = options[ :key ] || self.key
+        version = options[ :version ] || self.version || "2023-06-01" 
+
+        raise ArgumentError.new( 
+          "An Anthropic key is required to build an Anthropic chat request." 
+        ) if key.nil?
+
+        result[ 'content-type' ] = 'application/json'
+        result[ 'x-api-key' ] = "#{key}"
+        result[ 'anthropic-version' ] = version unless version.nil?
+
+        result 
+      end
+
+      def chat_request_body( conversation, options = {} )
+        options = self.class.configure( options ) unless options.empty?
+        result = self.chat_options.merge( options ).compact
+
+        system_message = translate_system_message( conversation[ :system_message ] )
+        result[ :system ] = system_message unless system_message.nil?
+        result[ :messages ] = []
+
+        messages = conversation[ :messages ] 
+        length = messages&.length || 0
+        index = 0; while index < length 
+          
+          message = messages[ index ]
+          unless message.nil?
+
+            # The Anthropic API will not accept a sequence of messages where the role of two 
+            # sequentian messages is the same.
+            #
+            # The purpose of this code is to identify such occurences and coalece them such 
+            # that the first message in the sequence aggregates the contents of all subsequent
+            # messages with the same role.
+            look_ahead_index = index + 1; while look_ahead_index < length
+              ahead_message = messages[ look_ahead_index ]
+              unless ahead_message.nil?
+                if ahead_message[ :role ] == message[ :role ]
+                  message[ :contents ] = 
+                    ( message[ :contents ] || [] ) + 
+                    ( ahead_message[ :contents ] || [] )
+                  messages[ look_ahead_index ] = nil 
+                  look_ahead_index += 1
+                else 
+                  break
+                end
+              end
+            end
+
+            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',
+                      source: {
+                        type: 'base64',
+                        media_type: content_type,
+                        data: Base64.strict_encode64( bytes )
+                      }
+                    }
+                  else
+                    raise UnsupportedContentError.new( 
+                      :anthropic, 
+                      'only support content of type image/*' 
+                    ) 
+                  end
+                else 
+                  raise InvalidContentError.new( :anthropic ) 
+                end
+              end 
+            end
+            
+            result_message[ :content ] = result_message_content
+            result[ :messages ] << result_message
+          
+          end
+        
+          index += 1
+        
+        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? 
+
+        result = {}
+        
+        result_choice = { 
+          end_reason: translate_end_result( response_json[ :stop_reason ] ),
+          end_sequence: response_json[ :stop_sequence ], 
+        }
+
+        if response_json[ :content ] && 
+           response_json[ :content ].is_a?( Array ) &&
+           !response_json[ :content ].empty?
+
+          result_content = []
+          response_json[ :content ].each do | content |
+            if content[ :type ] == 'text'
+              result_content.push( { type: 'text', text: content[ :text ] } )
+            end
+          end
+
+          unless result_content.empty?
+            result_choice[ :message ] = {
+              role: response_json[ :role ] || 'assistant',
+              contents: result_content
+            }
+          end
+
+        end
+
+        result[ :choices ] = [ result_choice ]
+
+        metrics_json = response_json[ :usage ]
+        unless metrics_json.nil?
+
+          result_metrics = {}
+          result_metrics[ :input_tokens ] = metrics_json[ :input_tokens ] 
+          result_metrics[ :output_tokens ] = metrics_json[ :output_tokens ]
+          result_metrics = result_metrics.compact
+
+          result[ :metrics ] = result_metrics unless result_metrics.empty?
+
+        end
+
+        result 
+      end
+
+      def chat_result_error_attributes( response )
+        error_type, error_description = translate_response_status( response.status )
+        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 ][ :type ],
+            error_description: parsed_body[ :error ][ :message ] || error_description
+          }
+        elsif 
+          result = {
+            error_type: error_type.to_s,
+            error_description: error_description
+          } 
+        end
+        result 
+      end
+
+      def stream_result_chunk_attributes( context, chunk )
+        context ||= {}
+
+        buffer = context[ :buffer ] || ''
+        contents = context[ :contents ] || []    
+        end_reason = context[ :end_reason ]
+        end_sequence = context[ :end_sequence ]
+        metrics = context[ :metrics ] || {
+          input_tokens: 0,
+          output_tokens:  0
+        }
+
+        contents.each do | content |
+          case content[ :type ] 
+            when :text 
+              content[ :text ] = ''
+            when :tool_call 
+              content[ :tool_parameters ] = ''
+            else 
+              content.clear 
+          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 )
+          
+          case data[ 'type' ]
+            when 'message_start'
+              metrics[ :input_tokens ] += data[ 'message' ]&.[]( 'usage' )&.[]( 'input_tokens' ) || 0
+              metrics[ :output_tokens ] += data[ 'message' ]&.[]( 'usage' )&.[]( 'output_tokens' ) || 0
+            when 'content_block_start'
+              index = data[ 'index' ]
+              contents.fill( {}, contents.size, index + 1 ) if contents.size <= index
+              if content_block = data[ 'content_block' ]
+                if content_block[ 'type' ] == 'text'
+                  contents[ index ] = {
+                    type: :text,
+                    text: content_block[ 'text' ] || '' 
+                  }
+                elsif content_block[ 'type' ] == 'tool_use'
+                  contents[ index ] = {
+                    type: :tool_call,
+                    tool_name: content_block[ 'name' ],
+                    tool_call_id: content_block[ 'id' ],
+                    tool_parameters: ''
+                  }
+                end
+              end
+            when 'content_block_delta'
+              index = data[ 'index' ]
+              contents.fill( {}, contents.size, index + 1 ) if contents.size <= index
+              if delta = data[ 'delta' ]
+                if delta[ 'type' ] == 'text_delta'
+                  contents[ index ][ :type ] = :text 
+                  contents[ index ][ :text ] = ( contents[ index ][ :text ] || '' ) + delta[ 'text' ]
+                elsif delta[ 'type' ] == 'input_json_delta'
+                  contents[ index ][ :type ] = :tool_call 
+                  contents[ index ][ :tool_parameters ] = 
+                    ( contents[ index ][ :tool_parameters ] || '' ) + delta[ 'input_json_delta' ]                
+                end
+              end
+            when 'message_delta'
+              if delta = data[ 'delta' ]
+                end_reason = delta[ 'stop_reason' ]
+                end_sequence = delta[ 'stop_sequence' ]
+              end
+              metrics[ :output_tokens ] += data[ 'usage' ]&.[]( 'output_tokens' ) || 0
+            when 'message_stop'
+              
+          end 
+        end
+
+        context = {
+          buffer: buffer,
+          contents: contents,
+          end_reason: end_reason,
+          end_sequence: end_sequence,
+          metrics: metrics
+        }
+        choices = [ {
+            end_reason: translate_end_result( end_reason ),
+            end_sequence: end_sequence,
+            message: {
+              contents: contents.dup
+            }
+          }
+        ]
+
+        [ context, ( choices.empty? ? nil : { choices: choices } ) ]
+      end
+
+      def stream_result_attributes( context )
+        {
+          choices: [ { 
+            end_reason: translate_end_result( context[ :end_reason ] ),
+            end_sequence: context[ :end_sequence ], 
+          } ],
+          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?
+
+        # note: the current version of the anthropic api simply takes a string as the 
+        #       system message but the beta version requires an array of objects akin
+        #       to message contents.
+
+        result = ''
+        system_message[ :contents ].each do | content |
+          result += content[ :text ] if content[ :type ] == :text 
+        end
+
+        result.empty? ? nil : result 
+
+      end 
+
+      def translate_end_result( end_result )
+        case end_result
+          when 'end_turn'
+            :ended
+          when 'max_tokens'
+            :token_limit_exceeded
+          when 'stop_sequence'
+            :end_sequence_encountered
+          when 'tool_use'
+            :tool_called
+          else
+            # if the result has already been translated, this simply returns it
+            end_result
+        end
+      end
+
+      def translate_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 429
+            [ :rate_limit_error, 
+              "Your account has hit a rate limit." ]
+          when 500
+            [ :api_error, 
+              "An unexpected error has occurred internal to Anthropic's systems." ]
+          when 529
+            [ :overloaded_error, 
+              "Anthropic's API is temporarily overloaded." ]
+          else
+            [ :unknown_error, "
+              An unknown error occurred." ]
+          end
+      end
+    
+    end
+  end
+end

data/lib/intelligence/adapters/anthropic.rb

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

data/lib/intelligence/adapters/cerebras.rb

@@ -0,0 +1,35 @@
+require_relative 'legacy/adapter'
+
+module Intelligence
+  module Cerebras
+
+    class Adapter < Legacy::Adapter
+
+      chat_request_uri "https://api.cerebras.ai/v1/chat/completions"
+      
+      configuration do 
+        parameter :key, required: true 
+        group :chat_options do 
+          parameter :model, String, required: true
+          parameter :max_tokens, Integer, required: true
+          parameter :response_format do 
+            parameter :type, String, default: 'json_schema'
+            parameter :json_schema
+          end
+          parameter :seed, Integer
+          parameter :stop, array: true
+          parameter :stream, [ TrueClass, FalseClass ]
+          parameter :temperature, Float
+          parameter :top_p, Float
+          parameter :tool_choice do 
+            parameter :type, String 
+            parameter :mame, String
+          end
+          parameter :user
+        end
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,21 @@
+require_relative '../../adapter'
+require_relative 'chat_methods'
+
+module Intelligence
+  module Generic
+    class Adapter < Adapter::Base
+
+      attr_reader :key
+      attr_reader :chat_options
+
+      def initialize( attributes = nil, &block )
+        configuration = self.class.configure( attributes, &block ) 
+        @key = configuration[ :key ]
+        @chat_options = configuration[ :chat_options ] || {}
+      end
+
+      include ChatMethods
+    
+    end 
+  end
+end