intelligence 0.5.0 → 0.6.0

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

@@ -7,7 +7,7 @@ module Intelligence
       configuration do 
 
         # normalized properties for all endpoints
-        parameter :key, String, required: true
+        parameter :key, String
         
         # openai properties for all endpoints
         parameter :organization
@@ -17,7 +17,7 @@ module Intelligence
         group :chat_options do 
         
           # normalized properties for openai generative text endpoint
-          parameter :model, String, required: true
+          parameter :model, String
           parameter :n, Integer
           parameter :max_tokens, Integer, as: :max_completion_tokens
           parameter :temperature, Float
@@ -54,20 +54,6 @@ module Intelligence
 
       end
 
-      attr_reader :key
-      attr_reader :organization
-      attr_reader :project
-      attr_reader :chat_options
-
-
-      def initialize( attributes = nil, &block )
-        configuration = self.class.configure( attributes, &block ) 
-        @key = configuration[ :key ]
-        @organization = configuration[ :organization ]
-        @project = configuration[ :project ]
-        @chat_options = configuration[ :chat_options ] || {}
-      end
-
       include ChatMethods
 
     end 

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

@@ -4,16 +4,20 @@ module Intelligence
 
       CHAT_REQUEST_URI = "https://api.openai.com/v1/chat/completions"
 
+      SUPPORTED_CONTENT_TYPES = [ 'image/jpeg', 'image/png' ]
+
       def chat_request_uri( options )
         CHAT_REQUEST_URI
       end
 
       def chat_request_headers( options = {} )
+        options = options ? self.class.configure( options ) : {}
+        options = @options.merge( options )
         result = {}
 
-        key = options[ :key ] || self.key
-        organization = options[ :organization ] || self.organization 
-        project = options[ :project ] || self.project 
+        key = options[ :key ] 
+        organization = options[ :organization ] 
+        project = options[ :project ]  
 
         raise ArgumentError.new( "An OpenAI key is required to build an OpenAI chat request." ) \
           if key.nil?
@@ -27,7 +31,9 @@ module Intelligence
       end
 
       def chat_request_body( conversation, options = {} )
-        result = self.chat_options.merge( options ).compact
+        options = options ? self.class.configure( options ) : {}
+        options = @options.merge( options )
+        result = options[ :chat_options ]&.compact || {}
         result[ :messages ] = []
 
         system_message = translate_system_message( conversation[ :system_message ] )
@@ -46,8 +52,7 @@ module Intelligence
               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'
+                if SUPPORTED_CONTENT_TYPES.include?( content_type )
                   result_message_content << {
                     type: 'image_url',
                     image_url: {
@@ -57,7 +62,7 @@ module Intelligence
                 else
                   raise UnsupportedContentError.new( 
                     :open_ai, 
-                    'only supports content of type image/*' 
+                    "only supports content of type #{SUPPORTED_CONTENT_TYPES.join( ', ' )}"
                   ) 
                 end
               else 
@@ -66,7 +71,33 @@ module Intelligence
                   'requires binary content to include content type and ( packed ) bytes'  
                 )
               end
-            end 
+            when :file 
+              content_type = content[ :content_type ]
+              uri = content[ :uri ]
+              if content_type && uri  
+                if SUPPORTED_CONTENT_TYPES.include?( content_type )
+                  result_message_content << {
+                    type: 'image_url',
+                    image_url: {
+                      url: uri 
+                    }
+                  }
+                else 
+                  raise UnsupportedContentError.new( 
+                    :open_ai, 
+                    "only supports content of type #{SUPPORTED_CONTENT_TYPES.join( ', ' )}" 
+                  ) 
+                end 
+              else 
+                raise UnsupportedContentError.new(
+                  :open_ai, 
+                  'requires file content to include content type and uri'  
+                )
+              end 
+            else 
+              raise InvalidContentError.new( :open_ai ) 
+            end
+
           end
 
           result_message[ :content ] = result_message_content

data/lib/intelligence/adapters/open_router.rb

@@ -0,0 +1,62 @@
+require_relative 'generic/adapter'
+
+module Intelligence
+  module OpenRouter
+
+    class Adapter < Generic::Adapter
+
+      chat_request_uri "https://openrouter.ai/api/v1/chat/completions"
+      
+      configuration do 
+        parameter :key, String 
+        group :chat_options do 
+          parameter :model, String
+          parameter :temperature, Float
+          parameter :top_k, Integer
+          parameter :top_p, Float
+          parameter :max_tokens, Integer
+          parameter :seed, Integer
+          parameter :stop, String, array: true
+          parameter :stream, [ TrueClass, FalseClass ]
+          parameter :frequency_penalty, Float
+          parameter :repetition_penalty, Float
+          parameter :presence_penalty, Float
+          
+          group :provider do 
+            parameter :order, String, array: true 
+            parameter :require_parameters, [ TrueClass, FalseClass ]
+            parameter :allow_fallbacks, [ 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? )
+      #     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
+end

data/lib/intelligence/adapters/samba_nova.rb

@@ -10,7 +10,7 @@ module Intelligence
       configuration do 
 
         # normalized properties for all endpoints
-        parameter :key, String, required: true
+        parameter :key, String
         
         # properties for generative text endpoints
         group :chat_options do 

data/lib/intelligence/adapters/together_ai.rb

@@ -8,7 +8,7 @@ module Intelligence
       chat_request_uri "https://api.together.xyz/v1/chat/completions"
       
       configuration do 
-        parameter :key, String, required: true 
+        parameter :key, String 
         group :chat_options do 
           parameter :model, String
           parameter :temperature, Float

data/lib/intelligence/chat_request.rb

@@ -1,7 +1,5 @@
 module Intelligence
 
-  #
-  # module. ChatRequestMethods
   #
   # The ChatRequestMethods module extends a Faraday request, adding the +receive_result+ method. 
   #
@@ -14,9 +12,7 @@ module Intelligence
   end
 
   #
-  # module. ChatResponseMethods
-  #
-  # The ChatResponseMethods module extends a Farada reponse, adding the +result+  method. 
+  # The ChatResponseMethods module extends a Faraday reponse, adding the +result+ method. 
   #
   module ChatResponseMethods
 
@@ -26,13 +22,38 @@ module Intelligence
 
   end
 
+  ##
+  # The +ChatRequest+ class encapsulates a request to an LLM. After creating a new +ChatRequest+ 
+  # instance you can make the actual request by calling the +chat+ or +stream+ methods. In order
+  # to construct a +ChatRequest+ you must first construct and configure an adapter.
+  #
+  # === example
+  # 
+  # adapter = Intelligence::Adapter.build( :open_ai ) do 
+  #   key ENV[ 'OPENAI_API_KEY' ]
+  #   chat_options do 
+  #     model 'gpt-4o'
+  #     max_tokens 512
+  #   end 
+  # end 
   #
-  # class. ChatRequest
+  # request = Intelligence::ChatRequest.new( adapter: adapter )
+  # response = request.chat( 'Hello!' )
   #
+  # if response.success?
+  #   puts response.result.text 
+  # else 
+  #   puts response.result.error_description 
+  # end 
+  # 
   class ChatRequest 
 
     DEFAULT_CONNECTION = Faraday.new { | builder | builder.adapter Faraday.default_adapter }
 
+    ##
+    # The +initialize+ method initializes the +ChatRequest+ instance. You MUST pass a previously 
+    # constructed and configured +adapter+ and optionally a (Faraday) +connection+.
+    #
     def initialize( connection: nil, adapter: , **options )
       @connection = connection || DEFAULT_CONNECTION
       @adapter = adapter
@@ -42,8 +63,25 @@ module Intelligence
         if @adapter.nil?
     end
 
+    ## 
+    # The +chat+ method leverages the adapter associated with this +ChatRequest+ instance to 
+    # construct and make an HTTP request - through Faraday - to an LLM service. The +chat+ method 
+    # always returns a +Faraday::Respose+ which is augmented with a +result+ method. 
+    #
+    # If the response is successful ( if +response.success?+ returns true ) the +result+ method 
+    # returns a +ChatResponse+ instance. If the response is not successful a +ChatErrorResult+ 
+    # instance is returned.
+    #
+    # === arguments 
+    # * +conversation+ - an instance of +Intelligence::Conversation+ or String; this encapsulates 
+    #                    the content to be sent to the LLM
+    # * +options+      - a Hash with options; these options overide any of the configuration 
+    #                    options used to configure the adapter; you can, for example, pass 
+    #                    +{ chat_options: { max_tokens: 1024 }+ to limit the response to 1024 
+    #                    tokens.
     def chat( conversation, options = {} )
 
+      conversation = build_quick_conversation( conversation ) if conversation.is_a?( String )
       options = @options.merge( options )
 
       uri = @adapter.chat_request_uri( options )
@@ -77,6 +115,7 @@ module Intelligence
 
     def stream( conversation, options = {} )
 
+      conversation = build_quick_conversation( conversation ) if conversation.is_a?( String )
       options = @options.merge( options )
 
       uri = @adapter.chat_request_uri( options )
@@ -112,6 +151,17 @@ module Intelligence
     
     end
 
+  private 
+
+    def build_quick_conversation( text )
+      conversation = Conversation.new() 
+      conversation.messages << Message.build! do 
+        role :user 
+        content text: text 
+      end 
+      conversation
+    end
+
   end
 
-end
+end

data/lib/intelligence/chat_result.rb

@@ -27,6 +27,10 @@ module Intelligence
       @choices.first.message
     end
 
+    def text 
+      return self.message&.text || ''
+    end
+
   end
 
 end

data/lib/intelligence/chat_result_choice.rb

@@ -13,7 +13,9 @@ module Intelligence
         if chat_choice_attributes[ :message ]
     end
 
-    private; def build_message( json_message )
+  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 )
@@ -23,4 +25,4 @@ module Intelligence
 
   end
 
-end
+end

data/lib/intelligence/conversation.rb

@@ -1,18 +1,40 @@
 module Intelligence
-
-  #
-  # class. Conversation
-  #
   class Conversation 
 
+    extend AdaptiveConfiguration::Configurable 
+
+    configuration do
+      group :system_message, default: { role: :system }, &Message::CONFIGURATION  
+      group :message, as: :messages, array: true, &Message::CONFIGURATION
+    end
+
+    def self.build( attributes = nil, &block )
+      configuration = self.configure( attributes, &block )
+      self.new( configuration.to_h )
+    end
+
     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 || [] 
+    def initialize( attributes = nil )
+ 
+      @messages = []
+      @tools = []
+      if attributes
+        if attributes[ :system_message ] 
+          system_message = Message.new( 
+            attributes[ :system_message ][ :role ],  
+            attributes[ :system_message ]
+          )
+          @system_message = system_message unless system_message.empty?
+        end
+
+        attributes[ :messages ]&.each do | message_attributes |
+          @messages << Message.new( message_attributes[ :role ], message_attributes )
+        end
+      end
+      
     end
 
     def has_system_message?
@@ -35,6 +57,13 @@ module Intelligence
       @system_message = message
     end
 
+    def append_message( *messages )
+      @messages.concat( messages.flatten )
+      self 
+    end
+
+    alias :<< :append_message
+
     def to_h
       result = {}
       result[ :system_message ] = @system_message.to_h if @system_message
@@ -44,5 +73,4 @@ module Intelligence
     end
 
   end
-
 end

data/lib/intelligence/message.rb

@@ -1,45 +1,101 @@
 module Intelligence
   class Message
 
+    extend AdaptiveConfiguration::Configurable 
+
     ROLES = [ :system, :user, :assistant ]
+    CONFIGURATION = Proc.new do
+      parameter :role, Symbol, required: true 
+      group :content, array: true, as: :contents do 
+        parameter :type, Symbol, default: :text 
+        parameter :text, String 
+        parameter :content_type, String
+        parameter :bytes, String 
+        parameter :uri, URI
+      end
+    end
+
+    configuration( &CONFIGURATION ) 
 
     attr_reader :role
     attr_reader :contents
 
-    def initialize( role, content_type = nil, content_attributes = nil )
+    ##
+    # The build! class method constructs and returns a new +Message+ instance. The build! method 
+    # accepts message +attributes+ and a block, which may be combined when constructing a Message.
+    # The +role+ is required, either as a paramter or in the block. If the role is not present, 
+    # an exception will be raised.
+    # 
+    # The block offers the +role+ method, as well as a +content+ method permiting the caller to 
+    # set the role and add content respectivelly. 
+    # 
+    # === examples
+    #
+    # message = Message.build!( role: :user ) 
+    #
+    # message = Message.build! do 
+    #   role :user 
+    #   content do 
+    #      type :text 
+    #      text 'this is a user message'
+    #   end 
+    # end 
+    #
+    # message = Message.build!( role: :user ) do 
+    #   content text: 'this is a user message'
+    # end 
+    #
+    # message = Message.build!( role: :user ) do 
+    #   content text: 'what do you see in this image?'
+    #   content type: :binary do
+    #     content_type 'image/png'
+    #     bytes File.binread( '99_red_balloons.png' )
+    #
+    def self.build!( attributes = nil, &block )
+      configuration = self.configure!( attributes, &block ).to_h
+      self.new( configuration[ :role ], configuration )
+    end
+
+    def initialize( role, attributes = nil )
       raise ArgumentError.new( "The role is invalid. It must be one of #{ROLES.join( ', ' )}." ) \
-        unless ROLES.include?( role.to_sym )
+        unless ROLES.include?( role&.to_sym )
 
-      @role = role.to_sym 
+          @role = role.to_sym 
       @contents = []   
 
-      @contents << MessageContent.build( content_type, content_attributes ) unless content_type.nil?
-    end
-
-    def append_content( content )
-      @contents.push( content ) unless content.nil?
-      self 
-    end
-
-    def build_and_append_content( content_type = nil, content_attributes = nil )
-      append_content(
-        MessageContent.build( content_type, content_attributes )
-      )
-      self 
-    end
-
-    alias :<< :append_content
-   
-    def each_content( &block )
-      @contents.each( &block )
+      if attributes && attributes[ :contents ]
+        attributes[ :contents ].each do | content |
+          @contents << MessageContent.build!( content[ :type ], content )
+        end 
+      end
     end
 
+    ##
+    # The empty? method return true if the message has no content.
+    #
     def empty?
       @contents.empty?
     end
 
+    ## 
+    # The valid? method returns true if the message has a valid role, has content, and the content 
+    # is valid.
+    # 
     def valid?
-      !@role.nil? && @contents.all?{ | contents | contents.valid? }
+      ROLES.include?( @role ) && !@contents.empty? && @contents.all?{ | contents | contents.valid? }
+    end
+
+    ##
+    # The text method is a convenience that returns all text content in the message joined with 
+    # a newline. Any non-text content is skipped. If there is no text content an empty string is
+    # returned.
+    #
+    def text  
+      result = []
+      each_content do | content |
+        result << content.text if content.is_a?( MessageContent::Text )
+      end
+      result.join( "\n" ) 
     end
 
     def to_h
@@ -49,5 +105,16 @@ module Intelligence
       }
     end
 
+    def each_content( &block )
+      @contents.each( &block )
+    end
+
+    def append_content( content )
+      @contents.push( content ) unless content.nil?
+      self 
+    end
+
+    alias :<< :append_content
+
   end
 end

data/lib/intelligence/message_content/base.rb

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

data/lib/intelligence/message_content/binary.rb

@@ -2,6 +2,12 @@ module Intelligence
   module MessageContent 
 
     class Binary < Base
+  
+      configuration do 
+        parameter :content_type, String, required: true 
+        parameter :bytes, String, required: true 
+      end
+
       attr_reader :content_type 
       attr_reader :bytes
       

data/lib/intelligence/message_content/file.rb

@@ -0,0 +1,35 @@
+module Intelligence   
+  module MessageContent 
+
+    class File < Base
+  
+      configuration do 
+        parameter :content_type, String 
+        parameter :uri, URI, required: true 
+      end
+
+      def initialize( attributes )
+        @uri = URI( attributes[ :uri ] ) if attributes[ :uri ]
+        @content_type = attributes[ :content_type ]
+      end
+
+      def content_type 
+        @content_type ||= valid_uri? ? MIME::Types.type_for( @uri.path )&.first&.content_type : nil
+      end
+
+      def valid_uri?( schemes = [ 'http', 'https' ] )
+        !!( @uri && schemes.include?( @uri.scheme ) && @uri.path && !@uri.path.empty? )      
+      end
+
+      def valid?
+        valid_uri? && !MIME::Types[ content_type ].empty?
+      end
+
+      def to_h
+        { type: :file, content_type: content_type, uri: @uri.to_s }
+      end
+
+    end 
+
+  end
+end

data/lib/intelligence/message_content/text.rb

@@ -2,6 +2,11 @@ module Intelligence
   module MessageContent 
 
     class Text < Base
+        
+      configuration do 
+        parameter :text, String, required: true
+      end
+
       attr_reader :text 
       
       def valid?

data/lib/intelligence/message_content/tool_call.rb

@@ -2,6 +2,13 @@ module Intelligence
   module MessageContent 
 
     class ToolCall < Base
+      
+      configuration do 
+        parameter :tool_call_id, String 
+        parameter :tool_name, String, required: true 
+        parameter :tool_parameters, String, array: true
+      end 
+
       attr_reader :tool_call_id 
       attr_reader :tool_name
       attr_reader :tool_parameters
@@ -17,4 +24,4 @@ module Intelligence
     end 
 
   end
-end
+end

data/lib/intelligence/message_content/tool_result.rb

@@ -2,6 +2,13 @@ module Intelligence
   module MessageContent 
 
     class ToolResult < Base
+
+      configuration do 
+        parameter :tool_call_id
+        parameter :tool_name, String, required: true 
+        parameter :tool_result, String, required: true 
+      end 
+
       attr_reader :tool_call_id 
       attr_reader :tool_name
       attr_reader :tool_result
@@ -17,4 +24,4 @@ module Intelligence
     end 
 
   end
-end
+end