spectre_ai 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a1b57e957fd8d44c84db209bc46d0c86a7be77a37d5f0f9ca726c2f2622a539
-  data.tar.gz: b09d880f7f80e918c229caba2d5754e2dcf96ca9afeb1ca3091e7db0232420c1
+  metadata.gz: c7c3acf59b77ad62e0095fb7f91aa0491a50f25d197f94c788ad5ce2bbefbf6f
+  data.tar.gz: 48b4a9dcda9a013a6dde32ca5008a7dd33a49f4d4678952b8fcbf2089d2ccca6
 SHA512:
-  metadata.gz: 91d020445d05ca703d78b6f0fda842a9f92c55b4c67d8b201accdad8fe352ccec2e4e28e36b157ae2a82f86f574d0873ddf23ff4ebbf7c15f707a2c467c47532
-  data.tar.gz: 48eb3d8f6339d999ff7386e32de81cb01008ceb3245fb9fc2e150311845779e1f5c788198c35710d20584100085974035fd1730f1c093d8634202a45d9b3756f
+  metadata.gz: be7bf9f1570bad924509a8b8ad2a4671d019d20325696c4a2587e586f4a9314e395d822857cf9a277c84fd69e1d61e1231b356405266b5147187d6ec01d7dd33
+  data.tar.gz: f80dddebe6a99f7c946a8364f62f15112a974ad6cffe5a031baf5c1a9b151f39c12b870c60945277b8c57e78e51a0f0bb7147c620af11e4a59ed1ce485bfebab

data/CHANGELOG.md

@@ -24,4 +24,60 @@ 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.
+
+# Changelog for Version 1.1.1
+
+**Release Date:** [11th Oct 2024]
+
+**New Features:**
+
+* **Nested Template Support in Prompts**
+  * You can now organize your prompt files in nested directories and render them using the `Spectre::Prompt.render` method.
+  * **Example**: To render a template from a nested folder:
+    ```ruby
+    Spectre::Prompt.render(template: 'classification/intent/user', locals: { query: 'What is AI?' })
+    ```
+  * This feature allows for better organization and scalability when dealing with multiple prompt categories and complex scenarios.

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).
@@ -281,15 +377,49 @@ Spectre::Prompt.render(
 - **`template`:** The path to the prompt template file (e.g., `rag/system`).
 - **`locals`:** A hash of variables to be used inside the ERB template.
 
+**Using Nested Templates for Prompts**
+
+Spectre's `Prompt` class now supports rendering templates from nested directories. This allows you to better organize your prompt files in a structured folder hierarchy.
+
+You can organize your prompt templates in subfolders. For instance, you can have the following structure:
+
+```
+app/
+  spectre/
+    prompts/
+      rag/
+        system.yml.erb
+        user.yml.erb
+      classification/
+        intent/
+          system.yml.erb
+          user.yml.erb
+        entity/
+          system.yml.erb
+          user.yml.erb
+```
+
+To render a prompt from a nested folder, simply pass the full path to the `template` argument:
+
+```ruby
+# Rendering from a nested folder
+Spectre::Prompt.render(template: 'classification/intent/user', locals: { query: 'What is AI?' })
+```
+
+This allows for more flexibility when organizing your prompt files, particularly when dealing with complex scenarios or multiple prompt categories.
+
 **Combining Completions with Prompts**
 
 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/prompt.rb

@@ -5,107 +5,119 @@ require 'yaml'
 
 module Spectre
   class Prompt
-    PROMPTS_PATH = File.join(Dir.pwd, 'app', 'spectre', 'prompts')
-
-    # Render a prompt by reading and rendering the YAML template
-    #
-    # @param template [String] The path to the template file, formatted as 'type/prompt' (e.g., 'rag/system')
-    # @param locals [Hash] Variables to be passed to the template for rendering
-    #
-    # @return [String] Rendered prompt
-    def self.render(template:, locals: {})
-      type, prompt = split_template(template)
-      file_path = prompt_file_path(type, prompt)
-
-      raise "Prompt file not found: #{file_path}" unless File.exist?(file_path)
-
-      # Preprocess the locals before rendering the YAML file
-      preprocessed_locals = preprocess_locals(locals)
-
-      template_content = File.read(file_path)
-      erb_template = ERB.new(template_content)
-
-      context = Context.new(preprocessed_locals)
-      rendered_prompt = erb_template.result(context.get_binding)
-
-      # YAML.safe_load returns a hash, so fetch the correct part based on the prompt
-      parsed_yaml = YAML.safe_load(rendered_prompt)[prompt]
-
-      # Convert special characters back after YAML processing
-      convert_special_chars_back(parsed_yaml)
-    rescue Errno::ENOENT
-      raise "Template file not found at path: #{file_path}"
-    rescue Psych::SyntaxError => e
-      raise "YAML Syntax Error in file #{file_path}: #{e.message}"
-    rescue StandardError => e
-      raise "Error rendering prompt for template '#{template}': #{e.message}"
-    end
+    class << self
+      attr_reader :prompts_path
 
-    private
+      def prompts_path
+        @prompts_path ||= detect_prompts_path
+      end
 
-    # Split the template parameter into type and prompt
-    #
-    # @param template [String] Template path in the format 'type/prompt' (e.g., 'rag/system')
-    # @return [Array<String, String>] An array containing the type and prompt
-    def self.split_template(template)
-      template.split('/')
-    end
+      # Render a prompt by reading and rendering the YAML template
+      #
+      # @param template [String] The path to the template file, formatted as 'folder1/folder2/prompt'
+      # @param locals [Hash] Variables to be passed to the template for rendering
+      #
+      # @return [String] Rendered prompt
+      def render(template:, locals: {})
+        path, prompt = split_template(template)
+        file_path = prompt_file_path(path, prompt)
+
+        raise "Prompt file not found: #{file_path}" unless File.exist?(file_path)
+
+        # Preprocess the locals before rendering the YAML file
+        preprocessed_locals = preprocess_locals(locals)
+
+        template_content = File.read(file_path)
+        erb_template = ERB.new(template_content)
+
+        context = Context.new(preprocessed_locals)
+        rendered_prompt = erb_template.result(context.get_binding)
+
+        # YAML.safe_load returns a hash, so fetch the correct part based on the prompt
+        parsed_yaml = YAML.safe_load(rendered_prompt)[prompt]
+
+        # Convert special characters back after YAML processing
+        convert_special_chars_back(parsed_yaml)
+      rescue Errno::ENOENT
+        raise "Template file not found at path: #{file_path}"
+      rescue Psych::SyntaxError => e
+        raise "YAML Syntax Error in file #{file_path}: #{e.message}"
+      rescue StandardError => e
+        raise "Error rendering prompt for template '#{template}': #{e.message}"
+      end
 
-    # Build the path to the desired prompt file
-    #
-    # @param type [String] Name of the prompt folder
-    # @param prompt [String] Type of prompt (e.g., 'system', 'user')
-    #
-    # @return [String] Full path to the template file
-    def self.prompt_file_path(type, prompt)
-      "#{PROMPTS_PATH}/#{type}/#{prompt}.yml.erb"
-    end
+      private
 
-    # Preprocess locals recursively to escape special characters in strings
-    #
-    # @param value [Object] The value to process (string, array, hash, etc.)
-    # @return [Object] Processed value with special characters escaped
-    def self.preprocess_locals(value)
-      case value
-      when String
-        escape_special_chars(value)
-      when Hash
-        value.transform_values { |v| preprocess_locals(v) } # Recurse into hash values
-      when Array
-        value.map { |item| preprocess_locals(item) } # Recurse into array items
-      else
-        value
+      # Detects the appropriate path for prompt templates
+      def detect_prompts_path
+        File.join(Dir.pwd, 'app', 'spectre', 'prompts')
       end
-    end
 
-    # Escape special characters in strings to avoid YAML parsing issues
-    #
-    # @param value [String] The string to process
-    # @return [String] The processed string with special characters escaped
-    def self.escape_special_chars(value)
-      value.gsub('&', '&amp;')
-           .gsub('<', '&lt;')
-           .gsub('>', '&gt;')
-           .gsub('"', '&quot;')
-           .gsub("'", '&#39;')
-           .gsub("\n", '\\n')
-           .gsub("\r", '\\r')
-           .gsub("\t", '\\t')
-    end
+      # Split the template parameter into path and prompt
+      #
+      # @param template [String] Template path in the format 'folder1/folder2/prompt'
+      # @return [Array<String, String>] An array containing the folder path and the prompt name
+      def split_template(template)
+        *path_parts, prompt = template.split('/')
+        [File.join(path_parts), prompt]
+      end
 
-    # Convert special characters back to their original form after YAML processing
-    #
-    # @param value [String] The string to process
-    # @return [String] The processed string with original special characters restored
-    def self.convert_special_chars_back(value)
-      value.gsub('&amp;', '&')
-           .gsub('&lt;', '<')
-           .gsub('&gt;', '>')
-           .gsub('&quot;', '"')
-           .gsub('&#39;', "'")
-           .gsub('\\n', "\n")
-           .gsub('\\r', "\r")
-           .gsub('\\t', "\t")
+      # Build the path to the desired prompt file
+      #
+      # @param path [String] Path to the prompt folder(s)
+      # @param prompt [String] Name of the prompt file (e.g., 'system', 'user')
+      #
+      # @return [String] Full path to the template file
+      def prompt_file_path(path, prompt)
+        File.join(prompts_path, path, "#{prompt}.yml.erb")
+      end
+
+      # Preprocess locals recursively to escape special characters in strings
+      #
+      # @param value [Object] The value to process (string, array, hash, etc.)
+      # @return [Object] Processed value with special characters escaped
+      def preprocess_locals(value)
+        case value
+        when String
+          escape_special_chars(value)
+        when Hash
+          value.transform_values { |v| preprocess_locals(v) } # Recurse into hash values
+        when Array
+          value.map { |item| preprocess_locals(item) } # Recurse into array items
+        else
+          value
+        end
+      end
+
+      # Escape special characters in strings to avoid YAML parsing issues
+      #
+      # @param value [String] The string to process
+      # @return [String] The processed string with special characters escaped
+      def escape_special_chars(value)
+        value.gsub('&', '&amp;')
+             .gsub('<', '&lt;')
+             .gsub('>', '&gt;')
+             .gsub('"', '&quot;')
+             .gsub("'", '&#39;')
+             .gsub("\n", '\\n')
+             .gsub("\r", '\\r')
+             .gsub("\t", '\\t')
+      end
+
+      # Convert special characters back to their original form after YAML processing
+      #
+      # @param value [String] The string to process
+      # @return [String] The processed string with original special characters restored
+      def convert_special_chars_back(value)
+        value.gsub('&amp;', '&')
+             .gsub('&lt;', '<')
+             .gsub('&gt;', '>')
+             .gsub('&quot;', '"')
+             .gsub('&#39;', "'")
+             .gsub('\\n', "\n")
+             .gsub('\\r', "\r")
+             .gsub('\\t', "\t")
+      end
     end
 
     # Helper class to handle the binding for ERB template rendering

data/lib/spectre/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spectre # :nodoc:all
-  VERSION = "1.0.1"
+  VERSION = "1.1.1"
 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.1
 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-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-rails