Replaced Calculator example with Weather example.

Closes #25

Author: crmne

.rspec_status

@@ -17,19 +17,19 @@ example_id                                         | status | run_time        |
 ./spec/ruby_llm/chat_spec.rb[1:1:3:2]              | passed | 19.22 seconds   |
 ./spec/ruby_llm/chat_spec.rb[1:1:4:1]              | passed | 3.15 seconds    |
 ./spec/ruby_llm/chat_spec.rb[1:1:4:2]              | passed | 2.51 seconds    |
-./spec/ruby_llm/chat_streaming_spec.rb[1:1:1:1]    | passed | 0.91374 seconds |
-./spec/ruby_llm/chat_streaming_spec.rb[1:1:2:1]    | passed | 0.50088 seconds |
-./spec/ruby_llm/chat_streaming_spec.rb[1:1:3:1]    | passed | 5.69 seconds    |
-./spec/ruby_llm/chat_streaming_spec.rb[1:1:4:1]    | passed | 1.22 seconds    |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:1]          | passed | 4.26 seconds    |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:2]          | passed | 6.16 seconds    |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:3]          | passed | 11.15 seconds   |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:4]          | passed | 1.3 seconds     |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:5]          | passed | 2.71 seconds    |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:6]          | passed | 2.43 seconds    |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:7]          | passed | 2.71 seconds    |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:8]          | passed | 4 seconds       |
-./spec/ruby_llm/chat_tools_spec.rb[1:1:9]          | passed | 2.81 seconds    |
+./spec/ruby_llm/chat_streaming_spec.rb[1:1:1]      | passed | 0.65115 seconds |
+./spec/ruby_llm/chat_streaming_spec.rb[1:1:2]      | passed | 0.50907 seconds |
+./spec/ruby_llm/chat_streaming_spec.rb[1:1:3]      | passed | 6.69 seconds    |
+./spec/ruby_llm/chat_streaming_spec.rb[1:1:4]      | passed | 0.70777 seconds |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:1]          | passed | 4.23 seconds    |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:2]          | passed | 8.45 seconds    |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:3]          | passed | 8.22 seconds    |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:4]          | passed | 1.16 seconds    |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:5]          | passed | 2.73 seconds    |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:6]          | passed | 3.33 seconds    |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:7]          | passed | 1.76 seconds    |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:8]          | passed | 3 seconds       |
+./spec/ruby_llm/chat_tools_spec.rb[1:1:9]          | passed | 4.47 seconds    |
 ./spec/ruby_llm/embeddings_spec.rb[1:1:1:1]        | passed | 0.33357 seconds |
 ./spec/ruby_llm/embeddings_spec.rb[1:1:1:2]        | passed | 0.43632 seconds |
 ./spec/ruby_llm/embeddings_spec.rb[1:1:2:1]        | passed | 0.65614 seconds |

README.md

@@ -59,16 +59,22 @@ RubyLLM.paint "a sunset over mountains in watercolor style"
 RubyLLM.embed "Ruby is elegant and expressive"
 
 # Let AI use your code
-class Calculator < RubyLLM::Tool
-  description "Performs calculations"
-  param :expression, type: :string, desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+  param :latitude, desc: "Latitude (e.g., 52.5200)"
+  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 }
   end
 end
 
-chat.with_tool(Calculator).ask "What's 123 * 456?"
+chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
 ```
 
 ## Installation

docs/guides/error-handling.md

@@ -99,18 +99,18 @@ When using tools, errors can be handled within the tool or in the calling code:
 
 ```ruby
 # Error handling within tools
-class Calculator < RubyLLM::Tool
-  description "Performs calculations"
-
-  param :expression,
-    type: :string,
-    desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
-  rescue StandardError => e
-    # Return error as structured data
-    { error: "Calculation error: #{e.message}" }
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+  param :latitude, desc: "Latitude (e.g., 52.5200)"
+  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 }
   end
 end
 

docs/guides/rails.md

@@ -235,26 +235,22 @@ In your views:
 Tools work seamlessly with Rails integration:
 
 ```ruby
-class Calculator < RubyLLM::Tool
-  description "Performs arithmetic calculations"
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+  param :location, desc: "City name or zip code"
 
-  param :expression,
-    type: :string,
-    desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
-  rescue StandardError => e
-    "Error: #{e.message}"
+  def execute(location:)
+    # Simulate weather lookup
+    "15°C and sunny in #{location}"
   end
 end
 
 # Add the tool to your chat
 chat = Chat.create!(model_id: 'gpt-4o-mini')
-chat.with_tool(Calculator)
+chat.with_tool(Weather)
 
 # Ask a question that requires calculation
-chat.ask "What's 123 * 456?"
+chat.ask "What's the weather in Berlin?"
 
 # Tool calls are persisted
 tool_call = chat.messages.find_by(role: 'assistant').tool_calls.first

docs/guides/tools.md

@@ -29,17 +29,18 @@ Common use cases include:
 Tools are defined as Ruby classes that inherit from `RubyLLM::Tool`:
 
 ```ruby
-class Calculator < RubyLLM::Tool
-  description "Performs arithmetic calculations"
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+  param :latitude, desc: "Latitude (e.g., 52.5200)"
+  param :longitude, desc: "Longitude (e.g., 13.4050)"
 
-  param :expression,
-    type: :string,
-    desc: "A mathematical expression to evaluate (e.g. '2 + 2')"
+  def execute(latitude:, longitude:)
+    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
 
-  def execute(expression:)
-    eval(expression).to_s
-  rescue StandardError => e
-    "Error: #{e.message}"
+    response = Faraday.get(url)
+    data = JSON.parse(response.body)
+  rescue => e
+    { error: e.message }
   end
 end
 ```
@@ -72,37 +73,40 @@ To use a tool, attach it to a chat:
 chat = RubyLLM.chat
 
 # Add a tool
-chat.with_tool(Calculator)
+chat.with_tool(Weather)
 
-# Now you can ask questions that might require calculation
-response = chat.ask "What's 123 * 456?"
-# => "Let me calculate that for you. 123 * 456 = 56088."
+# Now you can ask questions that might require weather data
+response = chat.ask "What's the weather in Berlin? (52.5200, 13.4050)?"
+# => "The current weather in Berlin is as follows:\n- **Temperature:** 4.6°C\n- **Wind Speed:** 6.6 km/h\n\nPlease note that the weather information is up to date as of March 15, 2025, at 20:15 GMT."
 ```
 
 ### Multiple Tools
 
 You can provide multiple tools to a single chat:
 
 ```ruby
-class Weather < RubyLLM::Tool
-  description "Gets current weather for a location"
-
-  param :location,
-    desc: "City name or zip code"
-
-  def execute(location:)
-    # Simulate weather lookup
-    "72°F and sunny in #{location}"
-  end
+require 'tzinfo'
+
+class TimeInfo < RubyLLM::Tool
+  description 'Gets the current time in various timezones'
+  param :timezone,
+        desc: "Timezone name (e.g., 'UTC', 'America/New_York')"
+
+  def execute(timezone:)
+    time = TZInfo::Timezone.get(timezone).now.strftime('%Y-%m-%d %H:%M:%S')
+    "Current time in #{timezone}: #{time}"
+   rescue StandardError => e
+      { error: e.message }
+   end
 end
 
 # Add multiple tools
 chat = RubyLLM.chat
-  .with_tools(Calculator, Weather)
+  .with_tools(Weather, TimeInfo)
 
 # Ask questions that might use either tool
-chat.ask "What's the temperature in New York City?"
-chat.ask "If it's 72°F in NYC and 54°F in Boston, what's the average?"
+chat.ask "What's the temperature in Rome?"
+chat.ask "What's the time in Tokyo?"
 ```
 
 ## Custom Initialization
@@ -150,13 +154,16 @@ Here's what happens when a tool is used:
 For example:
 
 ```ruby
-response = chat.ask "What's 123 squared plus 456?"
+response = chat.ask "What's the weather like in Paris? Coordinates are 48.8566, 2.3522. Also, what time is it there?"
 
 # Behind the scenes:
-# 1. Model decides it needs to calculate
-# 2. Model calls Calculator with expression: "123 * 123 + 456"
-# 3. Tool returns "15,585"
-# 4. Model incorporates this in its response
+# 1. Model decides it needs weather data
+# 2. Model calls Weather with coordinates for Paris
+# 3. Tool returns "Current weather: 22°C, Wind: 8 km/h"
+# 4. Model decides it needs time information
+# 5. Model calls TimeInfo with timezone "Europe/Paris"
+# 6. Tool returns "Current time in Europe/Paris: 2025-03-15 14:30:45 CET"
+# 7. Model incorporates both results in its response
 ```
 
 ## Debugging Tools
@@ -168,36 +175,36 @@ Enable debugging to see tool calls in action:
 ENV['RUBYLLM_DEBUG'] = 'true'
 
 # Make a request
-chat.ask "What's 15329 divided by 437?"
+chat.ask "What's the weather in New York? Coordinates are 40.7128, -74.0060"
 
 # Console output:
-# D, -- RubyLLM: Tool calculator called with: {"expression"=>"15329 / 437"}
-# D, -- RubyLLM: Tool calculator returned: "35.078719"
+# D, -- RubyLLM: Tool weather_api called with: {"latitude"=>"40.7128", "longitude"=>"-74.0060"}
+# D, -- RubyLLM: Tool weather_api returned: "Current weather: 18°C, Wind: 12 km/h"
 ```
 
 ## Error Handling
 
 Tools can handle errors gracefully:
 
 ```ruby
-class Calculator < RubyLLM::Tool
-  description "Performs arithmetic calculations"
-
-  param :expression,
-    type: :string,
-    desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
-  rescue StandardError => e
-    # Return error as a result
-    { error: "Error calculating #{expression}: #{e.message}" }
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+  param :latitude, desc: "Latitude (e.g., 52.5200)"
+  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 }
   end
 end
 
 # When there's an error, the model will receive and explain it
-chat.ask "What's 1/0?"
-# => "I tried to calculate 1/0, but there was an error: divided by 0"
+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."
 ```
 
 ## Advanced Tool Parameters
@@ -236,6 +243,14 @@ class DataAnalysis < RubyLLM::Tool
 end
 ```
 
+## Security Considerations
+
+When implementing tools that process user input (via the AI):
+
+* Avoid using `eval`, `system` or similar methods with unsanitized input
+* Remember that AI models might be tricked into producing dangerous inputs
+* Validate all inputs and use appropriate sanitization
+
 ## When to Use Tools
 
 Tools are best for:

docs/index.md

@@ -79,16 +79,22 @@ RubyLLM.paint "a sunset over mountains in watercolor style"
 RubyLLM.embed "Ruby is elegant and expressive"
 
 # Let AI use your code
-class Calculator < RubyLLM::Tool
-  description "Performs calculations"
-  param :expression, type: :string, desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+  param :latitude, desc: "Latitude (e.g., 52.5200)"
+  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 }
   end
 end
 
-chat.with_tool(Calculator).ask "What's 123 * 456?"
+chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
 ```
 
 ## Quick start

lib/ruby_llm/tool.rb

@@ -18,14 +18,19 @@ def initialize(name, type: 'string', desc: nil, required: true)
   # interface for defining parameters and implementing tool behavior.
   #
   # Example:
-  #   class Calculator < RubyLLM::Tool
-  #     description "Performs arithmetic calculations"
-  #     param :expression, type: :string, desc: "Math expression to evaluate"
+  #    require 'tzinfo'
   #
-  #     def execute(expression:)
-  #       eval(expression).to_s
-  #     end
-  #   end
+  #    class TimeInfo < RubyLLM::Tool
+  #      description 'Gets the current time in various timezones'
+  #      param :timezone, desc: "Timezone name (e.g., 'UTC', 'America/New_York')"
+  #
+  #      def execute(timezone:)
+  #        time = TZInfo::Timezone.get(timezone).now.strftime('%Y-%m-%d %H:%M:%S')
+  #        "Current time in #{timezone}: #{time}"
+  #       rescue StandardError => e
+  #          { error: e.message }
+  #       end
+  #    end
   class Tool
     class << self
       def description(text = nil)

spec/ruby_llm/chat_streaming_spec.rb

@@ -6,20 +6,6 @@
 RSpec.describe RubyLLM::Chat do
   include_context 'with configured RubyLLM'
 
-  class Calculator < RubyLLM::Tool # rubocop:disable Lint/ConstantDefinitionInBlock,RSpec/LeakyConstantDeclaration
-    description 'Performs basic arithmetic'
-
-    param :expression,
-          type: :string,
-          desc: 'Math expression to evaluate'
-
-    def execute(expression:)
-      eval(expression).to_s # rubocop:disable Security/Eval
-    rescue StandardError => e
-      "Error: #{e.message}"
-    end
-  end
-
   describe 'streaming responses' do
     [
       'claude-3-5-haiku-20241022',