intelligence 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 910d4c8472c375a7a3759c474d62e71c01395136d895ccff9dd2f33012fd5a39
-  data.tar.gz: 86b51ac28f93a39556664c3707f341d40fe5aa4ec1cdc27a217586fd222c0c77
+  metadata.gz: 35084b4f3df27ee21c0a21a759b74bcca9c05c6b47e0311026d6e6587f8661a3
+  data.tar.gz: 76afc7ad3e1f2e3637c82e8613b492680be20962ca5daf263d3c457968512c04
 SHA512:
-  metadata.gz: 6d47d1f1d333cb1f0ffe8bdb06bf27ad9be4c675349c01460f97021cc733df2410ed7bc597324b3413d44d0ed081a7a0ae129f0173313f4df5400d9012ed37b9
-  data.tar.gz: 90f91d3efdf84c091252d4e16dbbcab41a7f27b39350974a62d80eee37d465f1dfc000b1efb836471d00d47d9a774050cf0f28c3ada96d6ba9947d8f54a6c209
+  metadata.gz: 643f9acfde921655b5861901f5ea11646d00e9673a852e8546ec112a275d9f4e695934c314c577ca5cf44684ee3ce86b57cb5da9100e67b5c016c3bd90672f14
+  data.tar.gz: 6a9bb70335d3cd9f5b5ef48f1029e8b7997d880a1ebed37168c6d5cae88ec4abb48c2c8ffb95ef63c5b4b82a0e5c00904b0320321c124d8cf24fabb1928e5453

data/README.md

@@ -1,15 +1,15 @@
 # Intelligence
 
 Intelligence is a lightweight yet powerful Ruby gem that provides a uniform interface for 
-interacting with large language and vision model APIs across multiple providers. It allows 
-you to seamlessly integrate with services from OpenAI, Anthropic, Google, Cerebras, Groq, 
-Hyperbolic, Samba Nova, Together AI, and others, while maintaining a consistent API across 
-all providers. 
+interacting with large language and vision model APIs across multiple vendors. It allows 
+you to seamlessly integrate with services from OpenAI, Anthropic, Google, Mistral, Cerebras, 
+Groq, Hyperbolic, Samba Nova, Together AI, and others, while maintaining a consistent API 
+across all providers. 
 
 The gem operates with minimal dependencies and doesn't require vendor SDK installation, 
 making it easy to switch between providers or work with multiple providers simultaneously.
 
-```
+```ruby
 require 'intelligence'
 
 adapter = Intelligence::Adapter.build :open_ai do 
@@ -61,10 +61,11 @@ $ gem install intelligence
 
 ## Usage
 
-### Minimal Chat Request
+### Fundamentals
 
 The core components of Intelligence are adapters, requests and responses. An adapter encapsulates
-the differences between different providers allowing you to use requests and responses uniformly.
+the differences between different API vendors, allowing you to use requests and responses 
+uniformly.
 
 You retrieve an adapter for a specific vendor, configure it with a key, model and associated  
 parameters and then make a request by calling either the `chat` or `stream` methods.
@@ -94,25 +95,25 @@ else
 end
 ```
 
-The `response` object is a Faraday response with an added method: `result`. If a response is 
+The `response` object is a `Faraday` response with an added method: `result`. If a response is 
 successful `result` returns a `ChatResult`. If it is not successful it returns a 
-`ChatErrorResult`. 
+`ChatErrorResult`. You can use the `Faraday` method `success?` to determine if the response is 
+successful.
 
-### Understanding Results
+### Results
 
 When you make a request using Intelligence, the response includes a `result` that provides 
 structured access to the model's output. 
 
 - A `ChatResult` contains one or more `choices` (alternate responses from the model). The 
-  `choices` method returns an array of `ChatResultChoice` instances. It also includes 
-  a `metrics` methods which provides information about token usage for the request.
-  optional `metrics` about token usage
+  `choices` method returns an array of `ChatResultChoice` instances. `ChatResult` also 
+  includes a `metrics` methods which provides information about token usage for the request.
 - A `ChatResultChoice` contains a `message` from the assistant and an `end_result` which
-  indicates how the response ended;
+  indicates how the response ended:
   - `:ended` means the model completed its response normally
   - `:token_limit_exceeded` means the response hit the token limit ( `max_tokens` )
   - `:end_sequence_encountered` means the response hit a stop sequence
-  - `:filtered` means the content was filtered by safety settings
+  - `:filtered` means the content was filtered by the vendors safety settings or protocols 
   - `:tool_called` means the model is requesting to use a tool
 - The `Message` in each choice contains one or more content items, typically text but 
   potentially tool calls or other content types.
@@ -157,7 +158,7 @@ if response.success?
     puts "Total tokens: #{result.metrics.total_tokens}"
   end
 else
-  # or alternativelly handle the end result 
+  # or alternativelly handle the error result 
   puts "Error: #{response.result.error_description}"
 end
 ```
@@ -165,32 +166,26 @@ end
 The `ChatResult`, `ChatResultChoice` and `Message` all provide the `text` convenience 
 method which return the text. 
 
-A response might end for various reasons, indicated by the `end_reason` in each choice:
-- `:ended` means the model completed its response normally
-- `:token_limit_exceeded` means the response hit the token limit
-- `:end_sequence_encountered` means the response hit a stop sequence
-- `:filtered` means the content was filtered by safety settings
-- `:tool_called` means the model is requesting to use a tool
-
-### Understanding Conversations, Messages, and Content
+### Conversations, Messages, and Content
 
 Intelligence organizes interactions with models using three main components:
 
 - **Conversations** are collections of messages that represent a complete interaction with a 
-  model. A conversation can include an optional system message that sets the context, and a 
-  series of back-and-forth messages between the user and assistant.
+  model. A conversation can include an optional system message that sets the context, a series
+  of back-and-forth messages between the user and assistant and any tools the model may call.
 
 - **Messages** are individual communications within a conversation. Each message has a role 
   (`:system`, `:user`, or `:assistant`) that identifies its sender and can contain multiple 
   pieces of content.
 
 - **Content** represents the actual data within a message. This can be text 
-  (`MessageContent::Text`), binary data like images (`MessageContent::Binary`), or references 
-  to files (`MessageContent::File`).
+  ( `MessageContent::Text` ), binary data like images ( `MessageContent::Binary` ), references 
+  to files ( `MessageContent::File` ) or tool calls or tool results ( `MessageContent::ToolCall`
+  or `MessageContent::ToolResult` respectivelly ).
 
 In the previous examples we used a simple string as an argument to `chat`. As a convenience,
-the `chat` methods builds a coversation for you but, typically, you will construct a coversation 
-instance (`Coversation`) and pass that to the chat or stream methods. 
+the `chat` methods builds a coversation for you from a String but, typically, you will construct
+a coversation instance ( `Coversation` ) and pass that to the chat or stream methods. 
 
 The following example expands the minimal example, building a conversation, messages and content:
 
@@ -289,7 +284,7 @@ This pattern allows you to maintain context across multiple interactions with th
 request includes the full conversation history, helping the model provide more contextually 
 relevant responses.
 
-### Using Builders
+### Builders
 
 For more readable configuration, Intelligence provides builder syntax for both adapters and 
 conversations.
@@ -454,12 +449,15 @@ own descriptions and requirements. Once defined, tools are added to conversation
 used by the model during its response. 
 
 Note that not all providers support tools, and the specific tool capabilities may vary between 
-providers. Check your provider's documentation for details on tool support and requirements.
+providers. Today, OpenAI, Anthropic, Google, Mistral, and Together AI support tools. In general
+all these providers support tools in an identical manner but as of this writing Google does not
+support 'complex' tools which take object parameters.
 
 ## Streaming Responses
 
-Once you're familiar with basic requests, you might want to use streaming for real-time 
-responses. Streaming delivers the model's response in chunks as it's generated:
+The `chat` method, while straightforward in implementation, can be time consuming ( especially 
+when using modern 'reasoning' models like OpenAI O1 ). The alternative is to use the `stream` 
+method which will receive results as these are generated by the model. 
 
 ```ruby
 adapter = Intelligence::Adapter.build! :anthropic do
@@ -473,45 +471,68 @@ end
 
 request = Intelligence::ChatRequest.new(adapter: adapter)
 
-response = request.stream("Tell me a story about a robot.") do |request|
-  request.receive_result do |result|
+response = request.stream( "Tell me a story about a robot." ) do | request |
+  request.receive_result do | result |
     # result is a ChatResult object with partial content
-    print result.text
+    print result.text 
     print "\n" if result.choices.first.end_reason
   end
 end
 ```
 
-Streaming also works with complex conversations and binary content:
+Notice that in this approach you will receive multiple results ( `ChatResult` instances )
+each with a fragment of the generation. The result always includes a `message` and will 
+include `contents` as soon as any content is received. The `contents` is always positionally 
+consitent, meaning that if a model is, for example, generating text followed by several 
+tool calls you may receive a single text content initially, then the text content and a tool, 
+and then subsequent tools, even after the text has been completely generated. 
+
+Remember that every `result` contains only a fragment of content and it is possible that 
+any given fragment is completely blank ( that is, it is possible for the content to be 
+present in the result but all of it's fields are nil ). 
+
+While you will likelly want to immediatelly output any generated text but, as practical matter, 
+tool calls are not useful until full generated. To assemble tool calls ( or the text ) from
+the text fragments you may use the content items `merge` method. 
 
 ```ruby
-conversation = Intelligence::Conversation.build do
-  system_message do
-    content text: "You are an image analysis expert."
-  end
-  
-  message do
-    role :user
-    content text: "Describe this image in detail"
-    content do
-      type :binary
-      content_type 'image/jpeg'
-      bytes File.binread('path/to/image.jpg')
-    end
-  end
-end
+request = Intelligence::ChatRequest.new( adapter: adapter )
 
-response = request.stream(conversation) do |request|
-  request.receive_result do |result|
-    result.choices.each do |choice|
-      choice.message.each_content do |content|
-        print content.text if content.is_a?(Intelligence::MessageContent::Text)
-      end
+contents = []
+response = request.stream( "Tell me a story about a robot." ) do | request |
+  request.receive_result do | result |
+    choice = result.choices.first
+    contents_fragments = choice.message.contents 
+    contents.fill( nil, contents.length..(contents_fragments.length - 1) )
+
+    contents_fragments.each_with_index do | contents_fragment, index |
+      if contents_fragment.is_a?( Intelligence::MessageContent::Text )
+        # here we need the `|| ''` because the text of the fragment may be nil 
+        print contents_fragment.text 
+      else 
+        contents[ index ] = contents[ index ].nil? ? 
+          contents_fragment : 
+          contents[ index ].merge( contents_fragment )
+      end 
     end
+
   end
 end
 ```
 
+In the above example we construct an array to receive the content. As the content fragments 
+are streamed we will immediatelly output generated text but other types of content ( today 
+it could only be instances of `Intelligence::MessageContent::ToolCall' ) are individualy 
+combined in the `contents` array. You can simply iterate though the array and then retrieve 
+and take action for any of the tool calls. 
+
+Note also that the `result` will only include a non-nil `end_reason` as the last ( or one 
+of the last, `result` instances to be received ).
+
+Finally note that the streamed `result` is always a `ChatResult`, never a `ChatErrorResult`. 
+If an error occurs, the request itself will fail and you will receive this as part of 
+`response.result`. 
+
 ## Provider Switching
 
 One of Intelligence's most powerful features is the ability to easily switch between providers:

data/intelligence.gemspec

@@ -39,6 +39,7 @@ Gem::Specification.new do | spec |
   spec.add_runtime_dependency 'faraday', '~> 2.7'
   spec.add_runtime_dependency 'dynamicschema', '~> 1.0.0.beta03'
   spec.add_runtime_dependency 'mime-types', '~> 3.6'
+  spec.add_runtime_dependency 'json-repair', '~> 0.2'
 
   spec.add_development_dependency 'rspec', '~> 3.4'
   spec.add_development_dependency 'debug', '~> 1.9'

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

@@ -89,15 +89,8 @@ module Intelligence
           output_tokens:  0
         }
 
-        contents.each do | content |
-          case content[ :type ] 
-            when :text 
-              content[ :text ] = ''
-            when :tool_call 
-              content[ :tool_parameters ] = ''
-            else 
-              content.clear 
-          end
+        contents.map! do | content |
+          { type: content[ :type ] }
         end
 
         buffer += chunk
@@ -116,7 +109,7 @@ module Intelligence
               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
+              contents.fill( {}, contents.size..index ) if contents.size <= index
               if content_block = data[ 'content_block' ]
                 if content_block[ 'type' ] == 'text'
                   contents[ index ] = {
@@ -134,7 +127,7 @@ module Intelligence
               end
             when 'content_block_delta'
               index = data[ 'index' ]
-              contents.fill( {}, contents.size, index + 1 ) if contents.size <= index
+              contents.fill( {}, contents.size..index ) if contents.size <= index
               if delta = data[ 'delta' ]
                 if delta[ 'type' ] == 'text_delta'
                   contents[ index ][ :type ] = :text 
@@ -142,7 +135,7 @@ module Intelligence
                 elsif delta[ 'type' ] == 'input_json_delta'
                   contents[ index ][ :type ] = :tool_call 
                   contents[ index ][ :tool_parameters ] = 
-                    ( contents[ index ][ :tool_parameters ] || '' ) + delta[ 'input_json_delta' ]                
+                    ( contents[ index ][ :tool_parameters ] || '' ) + delta[ 'partial_json' ]                
                 end
               end
             when 'message_delta'

data/lib/intelligence/adapters/cerebras.rb

@@ -1,9 +1,9 @@
-require_relative 'legacy/adapter'
+require_relative 'generic/adapter'
 
 module Intelligence
   module Cerebras
 
-    class Adapter < Legacy::Adapter
+    class Adapter < Generic::Adapter
 
       chat_request_uri "https://api.cerebras.ai/v1/chat/completions"
       

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

@@ -1,10 +1,12 @@
 require_relative '../../adapter'
-require_relative 'chat_methods'
+require_relative 'chat_request_methods'
+require_relative 'chat_response_methods'
 
 module Intelligence
   module Generic
     class Adapter < Adapter::Base
-      include ChatMethods
+      include ChatRequestMethods
+      include ChatResponseMethods
     end 
   end
 end

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

@@ -0,0 +1,221 @@
+module Intelligence
+  module Generic
+    module ChatRequestMethods
+
+      module ClassMethods
+        def chat_request_uri( uri = nil )
+          if uri
+            @chat_request_uri = uri
+          else
+            @chat_request_uri
+          end
+        end
+      end
+
+      def self.included( base )
+        base.extend( ClassMethods )
+      end
+
+      def chat_request_uri( options )
+        self.class.chat_request_uri
+      end
+
+      def chat_request_headers( options = nil )
+        options = @options.merge( build_options( options ) )
+        result = {}
+
+        key = options[ :key ]
+
+        raise ArgumentError.new( "An API key is required to build a chat request." ) \
+          if key.nil?
+
+        result[ 'Content-Type' ] = 'application/json'
+        result[ 'Authorization' ] = "Bearer #{key}"
+
+        result 
+      end
+
+      def chat_request_body( conversation, options = nil )
+        options = @options.merge( build_options( options ) )
+        
+        result = options[ :chat_options ]
+        result[ :messages ] = []
+
+        system_message = chat_request_system_message_attributes( conversation[ :system_message ] )
+        result[ :messages ] << system_message if system_message
+
+        conversation[ :messages ]&.each do | message |
+          return nil unless message[ :contents ]&.any?
+
+          result_message = { role: message[ :role ] }
+          result_message_content = []
+
+          message_contents = message[ :contents ]
+
+          # tool calls in the open ai api are not content
+          tool_calls, message_contents = message_contents.partition do | content | 
+            content[ :type ] == :tool_call 
+          end 
+
+          # tool results in the open ai api are not content
+          tool_results, message_contents = message_contents.partition do | content |
+            content[ :type ] == :tool_result 
+          end 
+
+          # many vendor api's, especially when hosting text only models, will only accept a single 
+          # text content item; if the content is only text this will coalece multiple text content 
+          # items into a single content item
+          unless message_contents.any? { | c | c[ :type ] != :text }
+            result_message_content = message_contents.map { | c | c[ :text ] || '' }.join( "\n" )
+          else  
+            message_contents&.each do | content |
+              result_message_content << chat_request_message_content_attributes( content )
+            end
+          end
+
+          if tool_calls.any?
+            result_message[ :tool_calls ] = tool_calls.map { | tool_call |
+              {
+                id: tool_call[ :tool_call_id ],
+                type: 'function',
+                function: {
+                  name: tool_call[ :tool_name ],
+                  arguments: JSON.generate( tool_call[ :tool_parameters ] || {} )
+                }
+              }
+            }
+          end 
+
+          result_message[ :content ] = result_message_content 
+          unless result_message_content.empty? && tool_calls.empty? 
+           result[ :messages ] << result_message 
+          end 
+
+          if tool_results.any? 
+            result[ :messages ].concat( tool_results.map { | tool_result |
+              {
+                role: :tool, 
+                tool_call_id: tool_result[ :tool_call_id ],
+                content: tool_result[ :tool_result ]
+              }
+            } )
+          end 
+        end 
+
+        tools_attributes = chat_request_tools_attributes( conversation[ :tools ] )
+        result[ :tools ] = tools_attributes if tools_attributes && tools_attributes.length > 0
+
+        JSON.generate( result )
+      end 
+
+      def chat_request_message_content_attributes( content )
+        case content[ :type ]
+        when :text
+          { 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'
+              {
+                type: 'image_url',
+                image_url: {
+                  url: "data:#{content_type};base64,#{Base64.strict_encode64( bytes )}".freeze
+                }
+              }
+            else
+              raise UnsupportedContentError.new( 
+                :generic, 
+                'only support content of type image/*' 
+              ) 
+            end
+          else 
+            raise UnsupportedContentError.new(
+              :generic, 
+              '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 mime_type&.media_type == 'image'
+              {
+                type: 'image_url',
+                image_url: { url: uri }
+              }
+            else
+              raise UnsupportedContentError.new( 
+                :generic, 
+                'only support content of type image/*' 
+              ) 
+            end
+          else 
+            raise UnsupportedContentError.new(
+              :generic, 
+              'requires binary content to include content type and ( packed ) bytes'  
+            )
+          end
+        end
+      end
+
+      def chat_request_system_message_attributes( 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 : { role: 'system', content: result } if system_message  
+      end 
+
+      def chat_request_tools_attributes( 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
+
+        tools&.map do | tool |
+          function = { 
+            type: 'function',
+            function: {
+              name: tool[ :name ],
+              description: tool[ :description ],
+            }
+          }
+      
+          if tool[ :properties ]&.any? 
+            properties_object, properties_required = 
+              properties_array_to_object.call( tool[ :properties ] ) 
+            function[ :function ][ :parameters ] = {
+              type: 'object',
+              properties: properties_object 
+            }
+            function[ :function ][ :parameters ][ :required ] = properties_required \
+              if properties_required.any?
+          else
+            function[ :function ][ :parameters ] = {}
+          end
+          function 
+        end
+      end
+    
+    end
+  end
+end