intelligence 0.5.0 → 0.7.1

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"
+      
+      schema do 
+        key                     String 
+        chat_options do 
+          model                 String
+          temperature           Float
+          top_k                 Integer
+          top_p                 Float
+          max_tokens            Integer
+          seed                  Integer
+          stop                  String, array: true
+          stream                [ TrueClass, FalseClass ]
+          frequency_penalty     Float
+          repetition_penalty    Float
+          presence_penalty      Float
+          
+          provider do 
+            order               String, array: true 
+            require_parameters  [ TrueClass, FalseClass ]
+            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

@@ -7,27 +7,27 @@ module Intelligence
 
       chat_request_uri "https://api.sambanova.ai/v1/chat/completions"
       
-      configuration do 
+      schema do 
 
         # normalized properties for all endpoints
-        parameter :key, String, required: true
+        key                   String
         
         # properties for generative text endpoints
-        group :chat_options do 
+        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 ]
+          model               String
+          max_tokens          Integer
+          temperature         Float
+          top_p               Float
+          top_k               Float
+          stop                String, array: true
+          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 ]
+          repetition_penalty  Float
+          stream_options do
+            include_usage     [ TrueClass, FalseClass ]
           end
 
         end

data/lib/intelligence/adapters/together_ai.rb

@@ -7,32 +7,34 @@ module Intelligence
 
       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
+      schema do 
+        key                       String 
+        chat_options do 
+          model                   String
+          temperature             Float
+          top_p                   Float
+          top_k                   Integer
+          n                       Integer
+          max_tokens              Float
+          stop                    String, array: true
+          stream                  [ TrueClass, FalseClass ]
+          frequency_penalty       Float
+          presence_penalty        Float
+          repetition_penalty      Float
+          user                    String
         end
       end
 
       def translate_end_result( end_result )
         case end_result
-          when 'eos'
+          when 'eos', 'stop'
             :ended
-          when 'length'
+          # unfortunatelly eos seems to only work with certain models while others always return
+          # stop so for now tomorrow ai will not support :end_sequence_encountered
+          # when 'stop'
+          #   :end_sequence_encountered
+         when 'length'
             :token_limit_exceeded
-          when 'stop'
-            :end_sequence_encountered
           when 'function_call'
             :tool_called
           else

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,36 @@
 module Intelligence
-
-  #
-  # class. Conversation
-  #
   class Conversation 
 
+    include DynamicSchema::Definable 
+    include DynamicSchema::Buildable 
+
+    schema do
+      system_message    default: { role: :system }, &Message.schema  
+      message           as: :messages, array: true, &Message.schema
+    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 ]&.any? 
+          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 +53,18 @@ module Intelligence
       @system_message = message
     end
 
+    def append_message( *messages )
+      @messages.concat( messages.flatten )
+      self 
+    end
+
+    alias :<< :append_message
+
+    def append_tool( *tools )
+      @tools.concat( tools.flatten )
+      self 
+    end
+
     def to_h
       result = {}
       result[ :system_message ] = @system_message.to_h if @system_message
@@ -44,5 +74,4 @@ module Intelligence
     end
 
   end
-
 end

data/lib/intelligence/message.rb

@@ -1,46 +1,129 @@
 module Intelligence
   class Message
 
+    include DynamicSchema::Definable
+
     ROLES = [ :system, :user, :assistant ]
+    schema do
+      role              Symbol, required: true 
+      content           array: true, as: :contents do 
+        type            Symbol, default: :text
+
+        # note: we replicate these schema elements of the individual content types here to 
+        # provide more semantic flexibility when building a message; we don't delegate to the 
+        # individual content type schemas because, unlike for a specific content type, not all 
+        # attributes are required
+
+        # text 
+        text            String 
+        # binary and file 
+        content_type    String
+        bytes           String 
+        uri             URI
+        # tool call and tool result 
+        tool_call_id    String 
+        tool_name       String 
+        tool_parameters [ Hash, String ]
+        tool_result     [ Hash, String ]
+      end
+    end
 
     attr_reader :role
     attr_reader :contents
 
-    def initialize( role, content_type = nil, content_attributes = nil )
-      raise ArgumentError.new( "The role is invalid. It must be one of #{ROLES.join( ', ' )}." ) \
-        unless ROLES.include?( role.to_sym )
+    ##
+    # 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 an attribute 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. 
+    #
+    # Note that there is no corresponding +build+ method because a +Message+ strictly requires a 
+    # +role+. It cannot be constructed without one.
+    # 
+    # === 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' )
+    #   end
+    # end
+    #
+    def self.build!( attributes = nil, &block )
+      attributes = self.builder.build!( attributes, &block )
+      self.new( attributes[ :role ], attributes )
+    end
 
-      @role = role.to_sym 
+    def initialize( role, attributes = nil )
+      @role = role&.to_sym 
       @contents = []   
 
-      @contents << MessageContent.build( content_type, content_attributes ) unless content_type.nil?
+      raise ArgumentError.new( "The role is invalid. It must be one of #{ROLES.join( ', ' )}." ) \
+        unless ROLES.include?( @role )
+
+      if attributes && attributes[ :contents ]
+        attributes[ :contents ].each do | content |
+          @contents << MessageContent.build!( content[ :type ], content )
+        end 
+      end
     end
 
-    def append_content( content )
-      @contents.push( content ) unless content.nil?
-      self 
+    ##
+    # The empty? method return true if the message has no content.
+    #
+    def empty?
+      @contents.empty?
     end
 
-    def build_and_append_content( content_type = nil, content_attributes = nil )
-      append_content(
-        MessageContent.build( content_type, content_attributes )
-      )
-      self 
+    ## 
+    # The valid? method returns true if the message has a valid role, has content, and the content 
+    # is valid.
+    # 
+    def 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
 
-    alias :<< :append_content
-   
     def each_content( &block )
       @contents.each( &block )
     end
 
-    def empty?
-      @contents.empty?
+    def append_content( content )
+      @contents.push( content ) unless content.nil?
+      self 
     end
 
-    def valid?
-      !@role.nil? && @contents.all?{ | contents | contents.valid? }
-    end
+    alias :<< :append_content
 
     def to_h
       { 

data/lib/intelligence/message_content/base.rb

@@ -2,6 +2,9 @@ module Intelligence
   module MessageContent 
 
     class Base
+      include DynamicSchema::Definable 
+      include DynamicSchema::Buildable 
+
       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
+  
+      schema do 
+        content_type    String, required: true 
+        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
+  
+      schema do 
+        content_type    String  
+        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
+        
+      schema do 
+        text            String, required: true
+      end
+
       attr_reader :text 
       
       def valid?

data/lib/intelligence/message_content/tool_call.rb

@@ -2,10 +2,21 @@ module Intelligence
   module MessageContent 
 
     class ToolCall < Base
+      
+      schema do 
+        tool_call_id    String 
+        tool_name       String, required: true 
+        tool_parameters [ Hash, String ]
+      end 
+
       attr_reader :tool_call_id 
       attr_reader :tool_name
       attr_reader :tool_parameters
 
+      def valid?
+        tool_name && !tool_name.empty?
+      end
+
       def to_h
         { 
           type:             :tool_call, 
@@ -17,4 +28,4 @@ module Intelligence
     end 
 
   end
-end
+end

data/lib/intelligence/message_content/tool_result.rb

@@ -2,19 +2,31 @@ module Intelligence
   module MessageContent 
 
     class ToolResult < Base
+
+      schema do 
+        tool_call_id
+        tool_name       String, required: true 
+        tool_result     [ Hash, String ]
+      end 
+
       attr_reader :tool_call_id 
       attr_reader :tool_name
       attr_reader :tool_result
 
+      def valid?
+        tool_call_id && !tool_call_id.empty? &&
+        tool_name && !tool_name.empty?
+      end
+
       def to_h
         { 
-          type:             :tool_call, 
+          type:             :tool_result, 
           tool_call_id:     tool_call_id, 
           tool_name:        tool_name, 
-          tool_parameters:  tool_result 
+          tool_result:      tool_result 
         }.compact
       end
     end 
 
   end
-end
+end

data/lib/intelligence/message_content.rb

@@ -4,11 +4,20 @@ end
 
 module Intelligence   
   module MessageContent 
-    
-    def self.build( type, attributes )
+   
+    def self.[]( type ) 
       type_name = type.to_s.split( '_' ).map { | word | word.capitalize }.join
       klass = Intelligence.const_get( "MessageContent::#{type_name}" ) rescue nil
-      klass.nil? ? nil : klass.new( attributes )
+      raise TypeError, "An unknown content type '#{type}' was given." unless klass
+      klass
+    end
+
+    def self.build!( type, attributes = nil, &block )
+      self[ type ].build!( attributes, &block )
+    end
+    
+    def self.build( type, attributes = nil, &block )
+      self[ type ].build( attributes, &block )
     end
 
   end