rubycanusellm 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8366062327382434c0f86c1cb30a0a2265b1d26e7e512b294884aeac93e09468
-  data.tar.gz: 510d3d9d0051a4cdcb63ecdf7e0d1f4e536e27701a64504cd57fb555868aba1d
+  metadata.gz: 6f4513f49c758f5522912c97932d445ed1e8b5f8a24b2d071c00d1ae16f8358d
+  data.tar.gz: ad06df07d319d315bcc7d6348a011bdc6314ba83d2725fa53e807655422f877b
 SHA512:
-  metadata.gz: 711b8791cc6a9aa49362aaeb1a1da4d03071ec0ab14709e2b3ab20ec418752ce48232cace46103337b58f3daab643efd03a4f08259f994c848bf8c41efb8f3a1
-  data.tar.gz: 6c3adfcaa2032802fdfbb8f861dea1d89e56d177be3fbf2f761c47457af573c7a7581cd5727ce736b31738f33649e1ea8b247c18bbc8bf1b7364824966aeaeb8
+  metadata.gz: 9722c932b922b4c45ca2c55039e3fd99bb2e0137093a57196f1be6af2b60a5a6a9fcbd800c18ae4fedb494385dcc23b099bc838aaf1d0f91b554ce5fd88e0638
+  data.tar.gz: b91410cb53eecb40f987ce2ec4d2df9f0605dba7c69a86fd88835bc5c8710ee7f69104dd77d2846bc006c0054355774a692d6293e4e73a1b798d7c4ab82893bc

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.6.0] - 2026-04-10
+
+### Added
+
+- Tool calling support for OpenAI, Anthropic, Mistral, and Ollama providers
+- `RubyCanUseLLM::ToolCall` object with `id`, `name`, and `arguments` (parsed Hash)
+- `Response#tool_calls` — array of `ToolCall` objects when the model requests a tool, `nil` otherwise
+- `Response#tool_call?` — convenience predicate
+- Unified tool definition format: `[{ name:, description:, parameters: }]` — providers handle format translation internally
+- Anthropic's `tool_use`/`tool_result` format handled transparently
+- Multi-turn tool use: send `role: :tool` messages with `tool_call_id:` and `content:` to continue the conversation
+
 ## [0.5.0] - 2026-04-03
 
 ### Added

data/README.md

@@ -197,6 +197,47 @@ rescue RubyCanUseLLM::ProviderError => e
 end
 ```
 
+### Tool Calling
+
+Define tools once, use them with any provider:
+
+```ruby
+tools = [
+  {
+    name: "get_weather",
+    description: "Get current weather for a city",
+    parameters: {
+      type: "object",
+      properties: {
+        location: { type: "string", description: "City name" }
+      },
+      required: ["location"]
+    }
+  }
+]
+
+messages = [{ role: :user, content: "What's the weather in Paris?" }]
+response = RubyCanUseLLM.chat(messages, tools: tools)
+
+if response.tool_call?
+  tc = response.tool_calls.first
+  # tc.id        => "call_abc123"
+  # tc.name      => "get_weather"
+  # tc.arguments => { "location" => "Paris" }
+
+  # Execute the tool and continue the conversation
+  weather = fetch_weather(tc.arguments["location"])
+
+  messages << { role: :assistant, content: response.content, tool_calls: response.tool_calls }
+  messages << { role: :tool, tool_call_id: tc.id, name: tc.name, content: weather }
+
+  final_response = RubyCanUseLLM.chat(messages, tools: tools)
+  puts final_response.content
+end
+```
+
+**Works the same across providers** — OpenAI, Anthropic, Mistral, and Ollama. Format differences (Anthropic uses `input_schema` and `tool_result` messages) are handled internally.
+
 ### Prompt Templates
 
 Keep prompts out of your Ruby code. Define them in YAML files with ERB for dynamic content:
@@ -261,7 +302,7 @@ ERB is supported in both cases — loops, conditionals, any Ruby expression.
 - [x] Ollama provider (chat + embeddings, local)
 - [x] `generate:embedding` command
 - [x] Prompt templates (ERB + YAML file-based)
-- [ ] Tool calling
+- [x] Tool calling
 
 ## Development
 ```bash

data/lib/rubycanusellm/providers/anthropic.rb

@@ -45,12 +45,38 @@ module RubyCanUseLLM
           max_tokens: options[:max_tokens] || 1024
         }
         body[:system] = system if system
+        body[:tools] = format_tools(options[:tools]) if options[:tools]
         body
       end
 
       def format_messages(messages)
         messages.map do |msg|
-          { role: msg[:role].to_s, content: msg[:content] }
+          case msg[:role].to_s
+          when "tool"
+            {
+              role: "user",
+              content: [{ type: "tool_result", tool_use_id: msg[:tool_call_id], content: msg[:content].to_s }]
+            }
+          when "assistant"
+            content = []
+            content << { type: "text", text: msg[:content] } if msg[:content]
+            if msg[:tool_calls]
+              msg[:tool_calls].each do |tc|
+                content << { type: "tool_use", id: tc.id, name: tc.name, input: tc.arguments }
+              end
+            end
+            content.size == 1 && content.first[:type] == "text" ?
+              { role: "assistant", content: content.first[:text] } :
+              { role: "assistant", content: content }
+          else
+            { role: msg[:role].to_s, content: msg[:content] }
+          end
+        end
+      end
+
+      def format_tools(tools)
+        tools.map do |t|
+          { name: t[:name], description: t[:description], input_schema: t[:parameters] }
         end
       end
 
@@ -130,14 +156,27 @@ module RubyCanUseLLM
       end
 
       def parse_response(data)
-        content = data.dig("content", 0, "text")
+        text_content = nil
+        tool_calls = nil
+
+        data["content"].each do |block|
+          case block["type"]
+          when "text"
+            text_content = block["text"]
+          when "tool_use"
+            tool_calls ||= []
+            tool_calls << ToolCall.new(id: block["id"], name: block["name"], arguments: block["input"])
+          end
+        end
+
         usage = data["usage"]
 
         Response.new(
-          content: content,
+          content: text_content,
           model: data["model"],
           input_tokens: usage["input_tokens"],
           output_tokens: usage["output_tokens"],
+          tool_calls: tool_calls,
           raw: data
         )
       end

data/lib/rubycanusellm/providers/mistral.rb

@@ -33,16 +33,40 @@ module RubyCanUseLLM
       private
 
       def build_body(messages, options)
-        {
+        body = {
           model: options[:model] || config.model || "mistral-small-latest",
           messages: format_messages(messages),
           temperature: options[:temperature] || 0.7
         }
+        if options[:tools]
+          body[:tools] = format_tools(options[:tools])
+          body[:tool_choice] = options[:tool_choice] || "auto"
+        end
+        body
       end
 
       def format_messages(messages)
         messages.map do |msg|
-          { role: msg[:role].to_s, content: msg[:content] }
+          case msg[:role].to_s
+          when "tool"
+            { role: "tool", tool_call_id: msg[:tool_call_id], content: msg[:content].to_s }
+          when "assistant"
+            m = { role: "assistant", content: msg[:content] }
+            if msg[:tool_calls]
+              m[:tool_calls] = msg[:tool_calls].map do |tc|
+                { id: tc.id, type: "function", function: { name: tc.name, arguments: tc.arguments.to_json } }
+              end
+            end
+            m
+          else
+            { role: msg[:role].to_s, content: msg[:content] }
+          end
+        end
+      end
+
+      def format_tools(tools)
+        tools.map do |t|
+          { type: "function", function: { name: t[:name], description: t[:description], parameters: t[:parameters] } }
         end
       end
 
@@ -120,11 +144,23 @@ module RubyCanUseLLM
         choice = data.dig("choices", 0, "message")
         usage = data["usage"]
 
+        tool_calls = nil
+        if choice["tool_calls"]
+          tool_calls = choice["tool_calls"].map do |tc|
+            ToolCall.new(
+              id: tc["id"],
+              name: tc.dig("function", "name"),
+              arguments: JSON.parse(tc.dig("function", "arguments"))
+            )
+          end
+        end
+
         Response.new(
           content: choice["content"],
           model: data["model"],
           input_tokens: usage["prompt_tokens"],
           output_tokens: usage["completion_tokens"],
+          tool_calls: tool_calls,
           raw: data
         )
       end

data/lib/rubycanusellm/providers/ollama.rb

@@ -36,16 +36,37 @@ module RubyCanUseLLM
       end
 
       def build_body(messages, options)
-        {
+        body = {
           model: options[:model] || config.model || "llama3.2",
           messages: format_messages(messages),
           temperature: options[:temperature] || 0.7
         }
+        body[:tools] = format_tools(options[:tools]) if options[:tools]
+        body
       end
 
       def format_messages(messages)
         messages.map do |msg|
-          { role: msg[:role].to_s, content: msg[:content] }
+          case msg[:role].to_s
+          when "tool"
+            { role: "tool", content: msg[:content].to_s }
+          when "assistant"
+            m = { role: "assistant", content: msg[:content] || "" }
+            if msg[:tool_calls]
+              m[:tool_calls] = msg[:tool_calls].map do |tc|
+                { function: { name: tc.name, arguments: tc.arguments } }
+              end
+            end
+            m
+          else
+            { role: msg[:role].to_s, content: msg[:content] }
+          end
+        end
+      end
+
+      def format_tools(tools)
+        tools.map do |t|
+          { type: "function", function: { name: t[:name], description: t[:description], parameters: t[:parameters] } }
         end
       end
 
@@ -104,11 +125,24 @@ module RubyCanUseLLM
 
       def parse_response(data)
         message = data["message"]
+
+        tool_calls = nil
+        if message["tool_calls"]
+          tool_calls = message["tool_calls"].each_with_index.map do |tc, i|
+            ToolCall.new(
+              id: "call_#{i}",
+              name: tc.dig("function", "name"),
+              arguments: tc.dig("function", "arguments") || {}
+            )
+          end
+        end
+
         Response.new(
           content: message["content"],
           model: data["model"],
           input_tokens: data["prompt_eval_count"] || 0,
           output_tokens: data["eval_count"] || 0,
+          tool_calls: tool_calls,
           raw: data
         )
       end

data/lib/rubycanusellm/providers/openai.rb

@@ -32,16 +32,40 @@ module RubyCanUseLLM
       private
 
       def build_body(messages, options)
-        {
+        body = {
           model: options[:model] || config.model || "gpt-4o-mini",
           messages: format_messages(messages),
           temperature: options[:temperature] || 0.7
         }
+        if options[:tools]
+          body[:tools] = format_tools(options[:tools])
+          body[:tool_choice] = options[:tool_choice] || "auto"
+        end
+        body
       end
 
       def format_messages(messages)
         messages.map do |msg|
-          { role: msg[:role].to_s, content: msg[:content] }
+          case msg[:role].to_s
+          when "tool"
+            { role: "tool", tool_call_id: msg[:tool_call_id], content: msg[:content].to_s }
+          when "assistant"
+            m = { role: "assistant", content: msg[:content] }
+            if msg[:tool_calls]
+              m[:tool_calls] = msg[:tool_calls].map do |tc|
+                { id: tc.id, type: "function", function: { name: tc.name, arguments: tc.arguments.to_json } }
+              end
+            end
+            m
+          else
+            { role: msg[:role].to_s, content: msg[:content] }
+          end
+        end
+      end
+
+      def format_tools(tools)
+        tools.map do |t|
+          { type: "function", function: { name: t[:name], description: t[:description], parameters: t[:parameters] } }
         end
       end
 
@@ -119,11 +143,23 @@ module RubyCanUseLLM
         choice = data.dig("choices", 0, "message")
         usage = data["usage"]
 
+        tool_calls = nil
+        if choice["tool_calls"]
+          tool_calls = choice["tool_calls"].map do |tc|
+            ToolCall.new(
+              id: tc["id"],
+              name: tc.dig("function", "name"),
+              arguments: JSON.parse(tc.dig("function", "arguments"))
+            )
+          end
+        end
+
         Response.new(
           content: choice["content"],
           model: data["model"],
           input_tokens: usage["prompt_tokens"],
           output_tokens: usage["completion_tokens"],
+          tool_calls: tool_calls,
           raw: data
         )
       end

data/lib/rubycanusellm/response.rb

@@ -2,16 +2,21 @@
 
 module RubyCanUseLLM
   class Response
-    attr_reader :content, :model, :input_tokens, :output_tokens, :raw
+    attr_reader :content, :model, :input_tokens, :output_tokens, :tool_calls, :raw
 
-    def initialize(content:, model:, input_tokens:, output_tokens:, raw:)
+    def initialize(content:, model:, input_tokens:, output_tokens:, raw:, tool_calls: nil)
       @content = content
       @model = model
       @input_tokens = input_tokens
       @output_tokens = output_tokens
+      @tool_calls = tool_calls
       @raw = raw
     end
 
+    def tool_call?
+      !tool_calls.nil? && !tool_calls.empty?
+    end
+
     def total_tokens
       input_tokens + output_tokens
     end

data/lib/rubycanusellm/tool_call.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyCanUseLLM
+  class ToolCall
+    attr_reader :id, :name, :arguments
+
+    def initialize(id:, name:, arguments:)
+      @id = id
+      @name = name
+      @arguments = arguments
+    end
+  end
+end

data/lib/rubycanusellm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubycanusellm
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/rubycanusellm.rb

@@ -12,6 +12,7 @@ require_relative "rubycanusellm/providers/voyage"
 require_relative "rubycanusellm/providers/mistral"
 require_relative "rubycanusellm/providers/ollama"
 require_relative "rubycanusellm/embedding_response"
+require_relative "rubycanusellm/tool_call"
 require_relative "rubycanusellm/prompt"
 
 module RubyCanUseLLM

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubycanusellm
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Juan Manuel Guzman Nava
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-04-10 00:00:00.000000000 Z
 dependencies: []
 description: One interface, every LLM. Rubycanusellm provides a unified client for
   OpenAI, Anthropic, and more, plus generators that scaffold the boilerplate so you
@@ -44,6 +44,7 @@ files:
 - lib/rubycanusellm/templates/completion.rb.tt
 - lib/rubycanusellm/templates/config.rb.tt
 - lib/rubycanusellm/templates/embedding.rb.tt
+- lib/rubycanusellm/tool_call.rb
 - lib/rubycanusellm/version.rb
 - sig/rubycanusellm.rbs
 homepage: https://github.com/mgznv/rubycanusellm