spectre_ai 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a1b57e957fd8d44c84db209bc46d0c86a7be77a37d5f0f9ca726c2f2622a539
-  data.tar.gz: b09d880f7f80e918c229caba2d5754e2dcf96ca9afeb1ca3091e7db0232420c1
+  metadata.gz: 5cf3f5f31178a8456ccbb32bf9d68560efa5873751d3b3ca95c71921734b5da0
+  data.tar.gz: 9e96ac4a9eb3bb69dca886cff6570450f6380100c6df2df789f1c0bc0b7327f6
 SHA512:
-  metadata.gz: 91d020445d05ca703d78b6f0fda842a9f92c55b4c67d8b201accdad8fe352ccec2e4e28e36b157ae2a82f86f574d0873ddf23ff4ebbf7c15f707a2c467c47532
-  data.tar.gz: 48eb3d8f6339d999ff7386e32de81cb01008ceb3245fb9fc2e150311845779e1f5c788198c35710d20584100085974035fd1730f1c093d8634202a45d9b3756f
+  metadata.gz: 23dc62f85aa5d69faa16036349560dcf0a97f214f636598387921ba4fa63b48863a69db2e60518d05aeae383a1b27ba8a82ff03bf40ec9fa46b5c7fa059ce546
+  data.tar.gz: 12203cbdfc16fb9e4983362eee4a700f33ba220516ad75663f0bfafc57a2b503c164fb7e7efc90913f3cbb73c6f62d589c9a39b4fdeda0e22fa1decbfc14732c

data/CHANGELOG.md

@@ -24,4 +24,46 @@ user: |
 
 Before this change, queries or responses containing special characters might have caused YAML parsing errors. This update ensures that even complex strings are handled safely and returned in their original form.
 
-To upgrade, update your Gemfile to version 1.0.1 and run bundle install. Make sure your YAML/ERB templates do not manually escape special characters anymore, as the Prompt class will handle it automatically.
+To upgrade, update your Gemfile to version 1.0.1 and run bundle install. Make sure your YAML/ERB templates do not manually escape special characters anymore, as the Prompt class will handle it automatically.
+
+# Changelog for Version 1.1.0
+
+**Release Date:** [7th Oct 2024]
+
+**New Features:**
+
+* **Tool _(Function Calling)_ Integration:** Added support for tools parameter to enable function calling during completions. Now you can specify an array of tool definitions that the model can use to call specific functions.
+
+* **Enhanced Message Handling:** Replaced individual prompt parameters (user_prompt, system_prompt, assistant_prompt) with a single messages array parameter, which accepts a sequence of messages with their roles and contents. This provides more flexibility in managing conversations.
+
+* **Response Validation:** Introduced a handle_response method to handle different finish_reason cases more effectively, including content filtering and tool call handling.
+
+* **Improved Error Handling:**
+Added more specific error messages for cases like refusal (Refusal), incomplete response due to token limits (Incomplete response), and content filtering (Content filtered).
+Enhanced JSON parsing error handling with more descriptive messages.
+
+* **Request Validation:** Implemented message validation to ensure the messages parameter is not empty and follows the required format. Raises an error if validation fails.
+
+* **Support for Structured Output:** Integrated support for json_schema parameter in the request body to enforce structured output responses.
+
+* **Skip Request on Empty Messages:** The class will now skip sending a request if the messages parameter is empty or invalid, reducing unnecessary API calls.
+
+**Breaking Changes:**
+
+**Message Parameter Refactor**: The previous individual prompt parameters (user_prompt, system_prompt, assistant_prompt) have been consolidated into a single messages array. This may require updating any existing code using the old parameters.
+
+**Bug Fixes:**
+
+* **API Key Check:** Improved error handling for cases when the API key is not configured, providing a more specific exception.
+
+* **Error Messages:** Enhanced error messages for various edge cases, including content filtering and incomplete responses due to token limits.
+
+**Refinements:**
+
+Code Refactoring:
+* Moved message validation into a dedicated validate_messages! method for clarity and reusability.
+* Simplified the generate_body method to include the tools and json_schema parameters more effectively.
+
+**Documentation:** Updated class-level documentation and method comments for better clarity and understanding of the class’s functionality and usage.
+
+This version enhances the flexibility and robustness of the Completions class, enabling more complex interactions and better error handling for different types of API responses.

data/README.md

@@ -175,25 +175,36 @@ Spectre provides an interface to create chat completions using your configured L
 To create a simple chat completion, use the `Spectre.provider_module::Completions.create` method. You can provide a user prompt and an optional system prompt to guide the response:
 
 ```ruby
+messages = [
+        { role: 'system', content: "You are a funny assistant." },
+        { role: 'user', content: "Tell me a joke." }
+]
+
 Spectre.provider_module::Completions.create(
-  user_prompt: "Tell me a joke.",
-  system_prompt: "You are a funny assistant."
+        messages: messages
 )
+
 ```
 
 This sends the request to the LLM provider’s API and returns the chat completion.
 
 **Customizing the Completion**
 
-You can customize the behavior by specifying additional parameters such as the model or an `assistant_prompt` to provide further context for the AI’s responses:
+You can customize the behavior by specifying additional parameters such as the model, maximum number of tokens, and any tools needed for function calls:
 
 ```ruby
+messages = [
+        { role: 'system', content: "You are a funny assistant." },
+        { role: 'user', content: "Tell me a joke." },
+        { role: 'assistant', content: "Sure, here's a joke!" }
+]
+
 Spectre.provider_module::Completions.create(
-  user_prompt: "Tell me a joke.",
-  system_prompt: "You are a funny assistant.",
-  assistant_prompt: "Sure, here's a joke!",
-  model: "gpt-4"
+        messages: messages,
+        model: "gpt-4",
+        max_tokens: 50
 )
+
 ```
 
 **Using a JSON Schema for Structured Output**
@@ -214,15 +225,100 @@ json_schema = {
   }
 }
 
+messages = [
+  { role: 'system', content: "You are a knowledgeable assistant." },
+  { role: 'user', content: "What is the capital of France?" }
+]
+
 Spectre.provider_module::Completions.create(
-  user_prompt: "What is the capital of France?",
-  system_prompt: "You are a knowledgeable assistant.",
+  messages: messages,
   json_schema: json_schema
 )
+
 ```
 
 This structured format guarantees that the response adheres to the schema you’ve provided, ensuring more predictable and controlled results.
 
+**Using Tools for Function Calling**
+
+You can incorporate tools (function calls) in your completion to handle more complex interactions such as fetching external information via API or performing calculations. Define tools using the function call format and include them in the request:
+
+```ruby
+tools = [
+  {
+    type: "function",
+    function: {
+      name: "get_delivery_date",
+      description: "Get the delivery date for a customer's order.",
+      parameters: {
+        type: "object",
+        properties: {
+          order_id: { type: "string", description: "The customer's order ID." }
+        },
+        required: ["order_id"],
+        additionalProperties: false
+      }
+    }
+  }
+]
+
+messages = [
+  { role: 'system', content: "You are a helpful customer support assistant." },
+  { role: 'user', content: "Can you tell me the delivery date for my order?" }
+]
+
+Spectre.provider_module::Completions.create(
+  messages: messages,
+  tools: tools
+)
+```
+
+This setup allows the model to call specific tools (or functions) based on the user's input. The model can then generate a tool call to get necessary information and integrate it into the conversation.
+
+**Handling Responses from Completions with Tools**
+
+When tools (function calls) are included in a completion request, the response might include `tool_calls` with relevant details for executing the function.
+
+Here’s an example of how the response might look when a tool call is made:
+
+```ruby
+response = Spectre.provider_module::Completions.create(
+  messages: messages,
+  tools: tools
+)
+
+# Sample response structure when a tool call is triggered:
+# {
+#   :tool_calls=>[{
+#     "id" => "call_gqvSz1JTDfUyky7ghqY1wMoy",
+#     "type" => "function",
+#     "function" => {
+#       "name" => "get_lead_count",
+#       "arguments" => "{\"account_id\":\"acc_12312\"}"
+#     }
+#   }],
+#   :content => nil
+# }
+
+if response[:tool_calls]
+  tool_call = response[:tool_calls].first
+
+  # You can now perform the function using the provided data
+  # For example, get the lead count by account_id
+  account_id = JSON.parse(tool_call['function']['arguments'])['account_id']
+  lead_count = get_lead_count(account_id) # Assuming you have a method for this
+
+  # Respond back with the function result
+  completion_response = Spectre.provider_module::Completions.create(
+    messages: [
+      { role: 'assistant', content: "There are #{lead_count} leads for account #{account_id}." }
+    ]
+  )
+else
+  puts "Model response: #{response[:content]}"
+end
+```
+
 ### 6. Creating Dynamic Prompts
 
 Spectre provides a system for creating dynamic prompts based on templates. You can define reusable prompt templates and render them with different parameters in your Rails app (think Ruby on Rails view partials).
@@ -287,9 +383,12 @@ You can also combine completions and prompts like so:
 
 ```ruby
 Spectre.provider_module::Completions.create(
-  user_prompt: Spectre::Prompt.render(template: 'rag/user', locals: { query: @query, user: @user }),
-  system_prompt: Spectre::Prompt.render(template: 'rag/system')
+  messages: [
+    { role: 'system', content: Spectre::Prompt.render(template: 'rag/system') },
+    { role: 'user', content: Spectre::Prompt.render(template: 'rag/user', locals: { query: @query, user: @user }) }
+  ]
 )
+
 ```
 
 ## Contributing

data/lib/spectre/openai/completions.rb

@@ -10,21 +10,22 @@ module Spectre
       API_URL = 'https://api.openai.com/v1/chat/completions'
       DEFAULT_MODEL = 'gpt-4o-mini'
 
-      # Class method to generate a completion based on a user prompt
+      # Class method to generate a completion based on user messages and optional tools
       #
-      # @param user_prompt [String] the user's input to generate a completion for
-      # @param system_prompt [String] an optional system prompt to guide the AI's behavior
-      # @param assistant_prompt [String] an optional assistant prompt to provide context for the assistant's behavior
-      # @param model [String] the model to be used for generating completions, defaults to DEFAULT_MODEL
-      # @param json_schema [Hash, nil] an optional JSON schema to enforce structured output
-      # @param max_tokens [Integer] the maximum number of tokens for the completion (default: 50)
-      # @return [String] the generated completion text
-      # @raise [APIKeyNotConfiguredError] if the API key is not set
-      # @raise [RuntimeError] for general API errors or unexpected issues
-      def self.create(user_prompt:, system_prompt: "You are a helpful assistant.", assistant_prompt: nil, model: DEFAULT_MODEL, json_schema: nil, max_tokens: nil)
+      # @param messages [Array<Hash>] The conversation messages, each with a role and content
+      # @param model [String] The model to be used for generating completions, defaults to DEFAULT_MODEL
+      # @param json_schema [Hash, nil] An optional JSON schema to enforce structured output
+      # @param max_tokens [Integer] The maximum number of tokens for the completion (default: 50)
+      # @param tools [Array<Hash>, nil] An optional array of tool definitions for function calling
+      # @return [Hash] The parsed response including any function calls or content
+      # @raise [APIKeyNotConfiguredError] If the API key is not set
+      # @raise [RuntimeError] For general API errors or unexpected issues
+      def self.create(messages:, model: DEFAULT_MODEL, json_schema: nil, max_tokens: nil, tools: nil)
         api_key = Spectre.api_key
         raise APIKeyNotConfiguredError, "API key is not configured" unless api_key
 
+        validate_messages!(messages)
+
         uri = URI(API_URL)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = true
@@ -36,7 +37,7 @@ module Spectre
           'Authorization' => "Bearer #{api_key}"
         })
 
-        request.body = generate_body(user_prompt, system_prompt, assistant_prompt, model, json_schema, max_tokens).to_json
+        request.body = generate_body(messages, model, json_schema, max_tokens, tools).to_json
         response = http.request(request)
 
         unless response.is_a?(Net::HTTPSuccess)
@@ -45,18 +46,7 @@ module Spectre
 
         parsed_response = JSON.parse(response.body)
 
-        # Check if the response contains a refusal
-        if parsed_response.dig('choices', 0, 'message', 'refusal')
-          raise "Refusal: #{parsed_response.dig('choices', 0, 'message', 'refusal')}"
-        end
-
-        # Check if the finish reason is "length", indicating incomplete response
-        if parsed_response.dig('choices', 0, 'finish_reason') == "length"
-          raise "Incomplete response: The completion was cut off due to token limit."
-        end
-
-        # Return the structured output if it's included
-        parsed_response.dig('choices', 0, 'message', 'content')
+        handle_response(parsed_response)
       rescue JSON::ParserError => e
         raise "JSON Parse Error: #{e.message}"
       rescue Net::OpenTimeout, Net::ReadTimeout => e
@@ -65,40 +55,103 @@ module Spectre
 
       private
 
-      # Helper method to generate the request body
+      # Validate the structure and content of the messages array.
+      #
+      # @param messages [Array<Hash>] The array of message hashes to validate.
       #
-      # @param user_prompt [String] the user's input to generate a completion for
-      # @param system_prompt [String] an optional system prompt to guide the AI's behavior
-      # @param assistant_prompt [String] an optional assistant prompt to provide context for the assistant's behavior
-      # @param model [String] the model to be used for generating completions
-      # @param json_schema [Hash, nil] an optional JSON schema to enforce structured output
-      # @param max_tokens [Integer, nil] the maximum number of tokens for the completion
-      # @return [Hash] the body for the API request
-      def self.generate_body(user_prompt, system_prompt, assistant_prompt, model, json_schema, max_tokens)
-        messages = [
-          { role: 'system', content: system_prompt },
-          { role: 'user', content: user_prompt }
-        ]
-
-        # Add the assistant prompt if provided
-        messages << { role: 'assistant', content: assistant_prompt } if assistant_prompt
+      # @raise [ArgumentError] if the messages array is not in the expected format or contains invalid data.
+      def self.validate_messages!(messages)
+        # Check if messages is an array of hashes.
+        # This ensures that the input is in the correct format for message processing.
+        unless messages.is_a?(Array) && messages.all? { |msg| msg.is_a?(Hash) }
+          raise ArgumentError, "Messages must be an array of message hashes."
+        end
+
+        # Check if the array is empty.
+        # This prevents requests with no messages, which would be invalid.
+        if messages.empty?
+          raise ArgumentError, "Messages cannot be empty."
+        end
 
+        # Iterate through each message and perform detailed validation.
+        messages.each_with_index do |msg, index|
+          # Check if each message hash contains the required keys: :role and :content.
+          # These keys are necessary for defining the type of message and its content.
+          unless msg.key?(:role) && msg.key?(:content)
+            raise ArgumentError, "Message at index #{index} must contain both :role and :content keys."
+          end
+
+          # Check if the role is one of the allowed values: 'system', 'user', or 'assistant'.
+          # This ensures that each message has a valid role identifier.
+          unless %w[system user assistant].include?(msg[:role])
+            raise ArgumentError, "Invalid role '#{msg[:role]}' at index #{index}. Valid roles are 'system', 'user', 'assistant'."
+          end
+
+          # Check if the content is a non-empty string.
+          # This prevents empty or non-string content, which would be meaningless in a conversation.
+          unless msg[:content].is_a?(String) && !msg[:content].strip.empty?
+            raise ArgumentError, "Content for message at index #{index} must be a non-empty string."
+          end
+        end
+      end
+
+      # Helper method to generate the request body
+      #
+      # @param messages [Array<Hash>] The conversation messages, each with a role and content
+      # @param model [String] The model to be used for generating completions
+      # @param json_schema [Hash, nil] An optional JSON schema to enforce structured output
+      # @param max_tokens [Integer, nil] The maximum number of tokens for the completion
+      # @param tools [Array<Hash>, nil] An optional array of tool definitions for function calling
+      # @return [Hash] The body for the API request
+      def self.generate_body(messages, model, json_schema, max_tokens, tools)
         body = {
           model: model,
-          messages: messages,
+          messages: messages
         }
-        body['max_tokens'] = max_tokens if max_tokens
-
-        # Add the JSON schema as part of response_format if provided
-        if json_schema
-          body[:response_format] = {
-            type: 'json_schema',
-            json_schema: json_schema
-          }
-        end
+
+        body[:max_tokens] = max_tokens if max_tokens
+        body[:response_format] = { type: 'json_schema', json_schema: json_schema } if json_schema
+        body[:tools] = tools if tools # Add the tools to the request body if provided
 
         body
       end
+
+      # Handles the API response, raising errors for specific cases and returning structured content otherwise
+      #
+      # @param response [Hash] The parsed API response
+      # @return [Hash] The relevant data based on the finish reason
+      def self.handle_response(response)
+        message = response.dig('choices', 0, 'message')
+        finish_reason = response.dig('choices', 0, 'finish_reason')
+
+        # Check if the response contains a refusal
+        if message['refusal']
+          raise "Refusal: #{message['refusal']}"
+        end
+
+        # Check if the finish reason is "length", indicating incomplete response
+        if finish_reason == "length"
+          raise "Incomplete response: The completion was cut off due to token limit."
+        end
+
+        # Check if the finish reason is "content_filter", indicating policy violations
+        if finish_reason == "content_filter"
+          raise "Content filtered: The model's output was blocked due to policy violations."
+        end
+
+        # Check if the model made a function call
+        if finish_reason == "function_call" || finish_reason == "tool_calls"
+          return { tool_calls: message['tool_calls'], content: message['content'] }
+        end
+
+        # If the response finished normally, return the content
+        if finish_reason == "stop"
+          return { content: message['content'] }
+        end
+
+        # Handle unexpected finish reasons
+        raise "Unexpected finish_reason: #{finish_reason}"
+      end
     end
   end
 end

data/lib/spectre/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spectre # :nodoc:all
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spectre_ai
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Ilya Klapatok
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-09-19 00:00:00.000000000 Z
+date: 2024-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-rails