Merge branch 'main' into generators

Author: kieranklaassen

.github/workflows/cicd.yml

@@ -74,24 +74,46 @@ jobs:
         ruby-version: '3.3'
         bundler-cache: true
 
-    - name: Check if version has changed
+    - name: Check if version needs publishing
       id: check_version
       run: |
-        VERSION=$(ruby -r ./lib/ruby_llm/version.rb -e "puts RubyLLM::VERSION")
-        echo "Current version: $VERSION"
+        VERSION_FILE="./lib/ruby_llm/version.rb"
+        VERSION=$(ruby -r $VERSION_FILE -e "puts RubyLLM::VERSION" 2>/dev/null)
 
-        # Fetch all versions including prereleases
-        ALL_VERSIONS=$(gem list ruby_llm -r --prerelease | grep -oE '[0-9a-zA-Z\.\-]+')
-        echo "Available versions: $ALL_VERSIONS"
+        if [ -z "$VERSION" ]; then
+          echo "Error: Could not extract VERSION from $VERSION_FILE" >&2
+          exit 1
+        fi
+        echo "Local version: $VERSION"
+
+        GEM_NAME="ruby_llm"
+        echo "Fetching published versions for '$GEM_NAME'..."
+
+        # Combine results from --all and --prerelease, extract, clean, unique sort
+        ALL_PUBLISHED_VERSIONS=$(( \
+          gem list ^${GEM_NAME}$ -r --all 2>/dev/null || true; \
+          gem list ^${GEM_NAME}$ -r --prerelease 2>/dev/null || true; \
+        ) | sed -n 's/.*(\(.*\)).*/\1/p' \
+          | tr ',' '\n' \
+          | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' \
+          | grep . \
+          | sort -u )
+
+        echo "Checking against published versions:"
+        if [ -n "$ALL_PUBLISHED_VERSIONS" ]; then
+            echo "$ALL_PUBLISHED_VERSIONS" | sed 's/^/  /' # Log found versions nicely
+        else
+            echo "  (none found)"
+        fi
 
-        # Check if current version is among published versions
-        if echo "$ALL_VERSIONS" | grep -Fxq "$VERSION"; then
-          echo "Version $VERSION already published, skipping publish"
+        if echo "$ALL_PUBLISHED_VERSIONS" | grep -Fxq "$VERSION"; then
+          echo "Verdict: Version $VERSION already published."
           echo "version_changed=false" >> $GITHUB_OUTPUT
         else
-          echo "Version $VERSION is new"
+          echo "Verdict: Version $VERSION is new."
           echo "version_changed=true" >> $GITHUB_OUTPUT
         fi
+      shell: bash
 
     - name: Test with real APIs before publishing
       if: steps.check_version.outputs.version_changed == 'true'

CONTRIBUTING.md

@@ -185,10 +185,6 @@ When adding new features, please include documentation updates:
 - Add inline documentation using YARD comments
 - Keep the README clean and focused on helping new users get started quickly
 
-## Philosophy
-
-RubyLLM follows certain design philosophies and conventions. Please refer to our [Philosophy Guide](https://rubyllm.com/philosophy) to ensure your contributions align with the project's vision.
-
 ## Discussions and Issues
 
 - For questions and discussions, please use [GitHub Discussions](https://github.com/crmne/ruby_llm/discussions)

README.md

@@ -135,7 +135,7 @@ chat.ask "Tell me a story about a Ruby programmer" do |chunk|
   print chunk.content
 end
 
-# Set personality or behavior with instructions (aka system prompts) - available from 1.1.0
+# Set personality or behavior with instructions (aka system prompts)
 chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
 
 # Understand content in multiple forms
@@ -197,7 +197,7 @@ end
 # In a background job
 chat = Chat.create! model_id: "gpt-4o-mini"
 
-# Set personality or behavior with instructions (aka system prompts) - they're persisted too! - available from 1.1.0
+# Set personality or behavior with instructions (aka system prompts) - they're persisted too!
 chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
 
 chat.ask("What's your favorite Ruby gem?") do |chunk|

docs/guides/chat.md

@@ -43,11 +43,6 @@ claude_chat = RubyLLM.chat(model: 'claude-3-5-sonnet-20241022')
 chat.with_model('gemini-2.0-flash')
 ```
 
-{: .warning-title }
-> Coming in v1.1.0
->
-> The following model aliases and provider selection features are available in the upcoming version.
-
 RubyLLM supports model aliases, so you don't need to remember specific version numbers:
 
 ```ruby
@@ -69,11 +64,6 @@ See [Working with Models]({% link guides/models.md %}) for more details on model
 
 ## Instructions (aka System Prompts)
 
-{: .warning-title }
-> Coming in v1.1.0
->
-> chat.with_instructions is coming in 1.1.0. 1.0.x users should use `add_message role: system, content: PROMPT`
-
 System prompts allow you to set specific instructions or context that guide the AI's behavior throughout the conversation. These prompts are not directly visible to the user but help shape the AI's responses:
 
 ```ruby
@@ -86,7 +76,7 @@ chat.with_instructions "You are a helpful Ruby programming assistant. Always inc
 # Now the AI will follow these instructions in all responses
 response = chat.ask "How do I handle file operations in Ruby?"
 
-# You can add multiple system messages or update them during the conversation - available from 1.1.0
+# You can add multiple system messages or update them during the conversation
 chat.with_instructions "Always format your code using proper Ruby style conventions and include comments."
 
 # System prompts are especially useful for:

docs/guides/error-handling.md

@@ -97,7 +97,7 @@ end
 
 ## Handling Tool Errors
 
-When using tools, errors can be handled within the tool or in the calling code:
+There are two kinds of errors when working with tools: those the LLM should know about and retry, and those that should bubble up to your application code. Let's handle them appropriately:
 
 ```ruby
 # Error handling within tools
@@ -110,13 +110,17 @@ class Weather < RubyLLM::Tool
     url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
 
     response = Faraday.get(url)
-    data = JSON.parse(response.body)
-  rescue => e
+    JSON.parse(response.body)
+  rescue Faraday::ClientError => e
+    # Return errors the LLM should know about and can retry
     { error: e.message }
   end
 end
+```
+
+Handle program-ending errors at the application level:
 
-# Error handling when using tools
+```ruby
 begin
   chat = RubyLLM.chat.with_tool(Calculator)
   chat.ask "What's 1/0?"
@@ -125,6 +129,8 @@ rescue RubyLLM::Error => e
 end
 ```
 
+Return errors to the LLM when it should try a different approach (like invalid parameters or temporary failures), but let serious problems bubble up to be handled by your application's error tracking. The LLM is smart enough to work with error messages and try alternative approaches, but it shouldn't have to deal with program-ending problems.
+
 ## Automatic Retries
 
 RubyLLM automatically retries on certain transient errors:

docs/guides/models.md

@@ -29,11 +29,6 @@ chat.with_model('claude-3-5-sonnet')
 
 ### Model Resolution
 
-{: .warning-title }
-> Coming in v1.1.0
->
-> Provider-Specific Match and Alias Resolution will be available in the next release.
-
 When you specify a model, RubyLLM follows these steps to find it:
 
 1. **Exact Match**: First tries to find an exact match for the model ID
@@ -66,21 +61,12 @@ chat = RubyLLM.chat(model: 'claude-3-5-sonnet', provider: 'bedrock')
 
 ### Model Aliases
 
-{: .warning-title }
-> Coming in v1.1.0
->
-> Alias Resolution will be available in the next release.
-
 RubyLLM provides convenient aliases for popular models, so you don't have to remember specific version numbers:
 
 ```ruby
 # These are equivalent
 chat = RubyLLM.chat(model: 'claude-3-5-sonnet')
 chat = RubyLLM.chat(model: 'claude-3-5-sonnet-20241022')
-
-# These are also equivalent
-chat = RubyLLM.chat(model: 'gpt-4o')
-chat = RubyLLM.chat(model: 'gpt-4o-2024-11-20')
 ```
 
 If you want to ensure you're always getting a specific version, use the full model ID:

docs/guides/rails.md

@@ -153,25 +153,20 @@ end
 
 ## Instructions (aka System Prompts)
 
-{: .warning-title }
-> Coming in v1.1.0
->
-> chat.with_instructions is coming in 1.1.0. 1.0.x users should use `chat.messages.create! role: system, content: PROMPT`
-
 Instructions help guide the AI's behavior throughout a conversation. With Rails integration, these messages are automatically persisted just like regular chat messages:
 
 ```ruby
 # Create a new chat
 chat = Chat.create!(model_id: 'gpt-4o-mini')
 
-# Add instructions (these are persisted) - available from 1.1.0
+# Add instructions (these are persisted)
 chat.with_instructions("You are a helpful Ruby programming assistant. Always include code examples in your responses and explain them line by line.")
 
 # Ask questions - the AI will follow the instructions
 response = chat.ask("How do I handle file operations in Ruby?")
 puts response.content  # Will include detailed code examples
 
-# Add additional instructions - available from 1.1.0
+# Add additional instructions
 chat.with_instructions("Always format your code using proper Ruby style conventions and include comments.")
 # Both instructions are now persisted and active
 

docs/guides/tools.md

@@ -184,7 +184,7 @@ chat.ask "What's the weather in New York? Coordinates are 40.7128, -74.0060"
 
 ## Error Handling
 
-Tools can handle errors gracefully:
+Tools should handle errors differently based on whether they're recoverable by the LLM or require application intervention:
 
 ```ruby
 class Weather < RubyLLM::Tool
@@ -193,20 +193,76 @@ class Weather < RubyLLM::Tool
   param :longitude, desc: "Longitude (e.g., 13.4050)"
 
   def execute(latitude:, longitude:)
-    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
-
-    response = Faraday.get(url)
-    data = JSON.parse(response.body)
-  rescue => e
-    { error: e.message }
+    validate_coordinates!(latitude, longitude)
+    response = Faraday.get(weather_api_url(latitude, longitude))
+
+    case response.status
+    when 429
+      # Return errors the LLM should know about and can retry
+      { error: "Rate limit exceeded. Please try again in 60 seconds." }
+    when 200
+      JSON.parse(response.body)
+    else
+      # Let serious problems bubble up
+      raise "Weather API error: #{response.status}"
+    end
   end
+
+  private
+    def validate_coordinates!(lat, long)
+      lat = lat.to_f
+      long = long.to_f
+
+      if lat.abs > 90 || long.abs > 180
+        # Return validation errors to the LLM
+        { error: "Invalid coordinates. Latitude must be between -90 and 90, longitude between -180 and 180." }
+      end
+    end
+
+    def weather_api_url(lat, long)
+      "https://api.open-meteo.com/v1/forecast?latitude=#{lat}&longitude=#{long}&current=temperature_2m"
+    end
 end
+```
+
+Handle application-level errors in your code:
 
-# When there's an error, the model will receive and explain it
-chat.ask "What's the weather at invalid coordinates 1000, 1000?"
-# => "The coordinates 1000, 1000 are not valid for any location on Earth, as latitude must be between -90 and 90, and longitude must be between -180 and 180. Please provide valid coordinates or a city name for weather information."
+```ruby
+begin
+  chat = RubyLLM.chat.with_tool(Weather)
+  response = chat.ask "What's the weather in Berlin?"
+rescue RubyLLM::Error => e
+  # Handle LLM-specific errors
+  Rails.logger.error "LLM error: #{e.message}"
+  raise
+rescue StandardError => e
+  # Handle other unexpected errors
+  Rails.logger.error "Tool execution failed: #{e.message}"
+  raise
+end
 ```
 
+### Error Handling Guidelines
+
+When implementing tools, follow these principles:
+
+1. **Return errors to the LLM when:**
+   - Input validation fails
+   - The operation can be retried (rate limits, temporary failures)
+   - Alternative approaches might work
+
+2. **Let errors bubble up when:**
+   - The tool encounters unexpected states
+   - System resources are unavailable
+   - Authentication or authorization fails
+   - Data integrity is compromised
+
+The LLM can handle returned errors intelligently by:
+- Retrying with different parameters
+- Suggesting alternative approaches
+- Explaining the issue to the user
+- Using different tools to accomplish the task
+
 ## Simple Tool Parameters
 
 RubyLLM currently only supports simple parameter types: strings, numbers, and booleans. Complex types like arrays and objects are not supported.

docs/index.md

@@ -21,11 +21,6 @@ A delightful Ruby way to work with AI through a unified interface to OpenAI, Ant
 
 ---
 
-{: .warning-title }
-> Coming in v1.1.0
->
-> Amazon Bedrock support is coming in v1.1.0
-
 <div style="display: flex; align-items: center; flex-wrap: wrap; gap: 1em; margin-bottom: 1em">
   <img src="https://upload.wikimedia.org/wikipedia/commons/4/4d/OpenAI_Logo.svg" alt="OpenAI" height="40" width="120">
   <img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Anthropic_logo.svg" alt="Anthropic" height="40" width="120">

lib/ruby_llm/active_record/acts_as.rb

@@ -25,13 +25,13 @@ def acts_as_chat(message_class: 'Message', tool_call_class: 'ToolCall')
                    to: :to_llm
         end
 
-        def acts_as_message(chat_class: 'Chat', tool_call_class: 'ToolCall') # rubocop:disable Metrics/MethodLength
+        def acts_as_message(chat_class: 'Chat', tool_call_class: 'ToolCall', touch_chat: false) # rubocop:disable Metrics/MethodLength
           include MessageMethods
 
           @chat_class = chat_class.to_s
           @tool_call_class = tool_call_class.to_s
 
-          belongs_to :chat, class_name: @chat_class, foreign_key: "#{@chat_class.underscore}_id"
+          belongs_to :chat, class_name: @chat_class, touch: touch_chat
           has_many :tool_calls, class_name: @tool_call_class, dependent: :destroy
 
           belongs_to :parent_tool_call,
@@ -209,4 +209,4 @@ def extract_content
       end
     end
   end
-end
+end