regent 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a728784fd3d7720bb7fd96bf2cd22a8d53e59eaed01c9b4240a2cb09023e261
-  data.tar.gz: 78ddbe87cf964ca94039f560ddfcb743a14757e551af0847363b0fa82228e4a7
+  metadata.gz: b507ccf9494ec028a77c396a80acd23bb686b4e1e15ba6b993430b479f495aeb
+  data.tar.gz: 8a00bcfaddae77f89b19ec72a9112c82e07086a2fee2713fc71fac5cbf0581b1
 SHA512:
-  metadata.gz: c0306c99637469cff9e51a9b1b50424e646f38dd601dcb5b36d8eee417e2f280488b3e6c78747c242d78d8213fd6a9e004d3cd7065b692d7dc63a5900bf20e16
-  data.tar.gz: 68302a81b5062f54415a89e49513e2186afd0fb6d129dfa1111b33565ade932cbae9e657218d66b37cf2fd58b78103456da0dcc7c52c26948016134117cc4e42
+  metadata.gz: e1249458a5fa9e035a9bc9c6dfb7102ec9efcdd6f1fbb71fe8638194e6181256ae09df6f7ec42ccb781bf641cdcae13c84c2104ec33e8543e5480868fe03bd77
+  data.tar.gz: be2357b3af64f96d69573bbc913c3322a11aa40434f84aba314e64ef066c78821ead732becb2f455c5f93251907f724ca7cd48109706108c66d3d57a9837b5b4

data/README.md

@@ -3,6 +3,7 @@
 <div align="center">
 
 # Regent
+
 [![Gem Version](https://badge.fury.io/rb/regent.svg)](https://badge.fury.io/rb/regent)
 [![Build](https://github.com/alchaplinsky/regent/actions/workflows/main.yml/badge.svg)](https://github.com/alchaplinsky/regent/actions/workflows/main.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -11,8 +12,10 @@
 
 **Regent** is a small and elegant Ruby framework for building AI agents that can think, reason, and take actions through tools. It provides a clean, intuitive interface for creating agents that can solve complex problems by breaking them down into logical steps.
 
-> [!WARNING]
+> [!NOTE]
 > Regent is currently an experiment intended to explore patterns for building easily traceable and debuggable AI agents of different architectures. It is not yet intended to be used in production and is currently in development.
+> 
+> Read more about Regent in a Medium article: [Building AI Agent from scratch with Ruby](https://medium.com/towards-artificial-intelligence/building-ai-agent-from-scratch-with-ruby-c6260dad45b7)
 
 ## Key Features
 
@@ -29,7 +32,7 @@
 
 A basic Regnt Agent extended with a `price_tool` that allows for retrieving cryptocurrency prices from coingecko.com.
 
-![screencast 2024-12-25 21-53-47](https://github.com/user-attachments/assets/4e65b731-bbd7-4732-b157-b705d35a7824)
+![Screen_gif](https://github.com/user-attachments/assets/63c8c923-0c1e-48db-99f6-33758411623f)
 
 ## Quick Start
 
@@ -51,39 +54,191 @@ bundle install
 
 ## Usage
 
-Create your first agent:
+### Quick Example
+
+Create your first weather agent:
 
 ```ruby
-# Initialize the LLM
-llm = Regent::LLM.new("gpt-4o")
+# Define agent class
+class WeatherAgent < Regent::Agent
+  tool(:weather_tool, "Get current weather for a location")
 
-# Create a custom tool
-class WeatherTool < Regent::Tool
-  def call(location)
-    # Implement weather lookup logic
+  def weather_tool(location)
     "Currently 72°F and sunny in #{location}"
   end
 end
 
-# Create and configure the agent
-agent = Regent::Agent.new(
-  "You are a helpful weather assistant",
-  llm: llm,
-  tools: [WeatherTool.new(
-    name: "weather_tool",
-    description: "Get current weather for a location"
-  )]
-)
+# Instantiate an agent
+agent = WeatherAgent.new("You are a helpful weather assistant", model: "gpt-4o")
 
 # Execute a query
-result = agent.execute("What's the weather like in Tokyo?") # => "It is currently 72°F and sunny in Tokyo."
+agent.run("What's the weather like in Tokyo?") # => "It is currently 72°F and sunny in Tokyo."
+```
+
+### LLMs
+Regent provides an interface for invoking an LLM through an instance of `Regent::LLM` class. Even though Agent initializer allows you to pass a modal name as a string, sometimes it is useful to create a model instance if you want to tune model params before passing it to the agent. Or if you need to invoke a model directly without passing it to an Agent you can do that by creating an instance of LLM class:
+
+```ruby
+model = Regent::LLM.new("gemini-1.5-flash")
+# or with options
+model = Regent::LLM.new("gemini-1.5-flash", temperature: 0.5) # supports options that are supported by the model
+```
+
+#### API keys
+By default, **Regent** will try to fetch API keys for corresponding models from environment variables. Make sure that the following ENV variables are set depending on your model choice:
+
+| Model series | ENV variable name   |
+|--------------|---------------------|
+| `gpt-`       | `OPENAI_API_KEY`    |
+| `gemini-`    | `GEMINI_API_KEY`    |
+| `claude-`    | `ANTHROPIC_API_KEY` |
+
+But you can also pass an `api_key` option to the` Regent::LLM` constructor should you need to override this behavior:
+
+```ruby
+model = Regent::LLM.new("gemini-1.5-flash", api_key: "AIza...")
+```
+
+> [!NOTE]
+> Currently **Regent** supports only `gpt-`, `gemini-` and `claude-` models series and local **ollama** models. But you can build, your custom model classes that conform to the Regent's interface and pass those instances to the Agent.
+
+#### Calling LLM
+Once your model is instantiated you can call the `invoke` method:
+
+```ruby
+model.invoke("Hello!") 
+```
+
+Alternatively, you can pass message history to the `invoke` method. Messages need to follow OpenAI's message format (eg. `{role: "user", content: "..."}`)
+
+```ruby
+model.invoke([
+  {role: "system", content: "You are a helpful assistant"},
+  {role: "user", content: "Hello!"}
+])
 ```
 
+This method returns an instance of the `Regent::LLM::Result` class, giving access to the content or error and token usage stats.
+
+```ruby
+result = model.invoke("Hello!")
+
+result.content # => Hello there! How can I help you today?
+result.input_tokens # => 2
+result.output_tokens # => 11
+result.error # => nil
+```
+
+### Tools
+
+There are multiple ways how you can give agents tools for performing actions and retrieving additional information. First of all you can define a **function tool** directly on the agent class:
+
+```ruby
+class MyAgent < Regent::Agent
+  # define the tool by giving a unique name and description
+  tool :search_web, "Search for information on the web" 
+
+  def search_web(query)
+    # Implement tool logic within the method with the same name
+  end
+end
+```
+
+For more complex tools we can define a dedicated class with a `call` method that will get called. And then pass an instance of this tool to an agent:
+
+```ruby
+class SearchTool < Regent::Tool
+  def call(query)
+    # Implement tool logic
+  end
+end
+
+agent = Regent::Agent.new("Find information and answer any question", {
+  model: "gpt-4o",
+  tools: [SearchTool.new]
+})
+
+```
+
+### Agent
+
+**Agent** class is the core of the library. To crate an agent, you can use `Regent::Agent` class directly if you don't need to add any business logic. Or you can create your own class inheriting from `Regent::Agent`. To instantiate an agent you need to pass a **purpose** of an agent and a model it should use.
+
+```ruby
+agent = Regent::Agent.new("You are a helpful assistant", model: "gpt-4o-mini")
+```
+
+Additionally, you can pass a list of Tools to extend the agent's capabilities. Those should be instances of classes that inherit from `Regent::Tool` class:
+
+```ruby
+class SearchTool < Regent::Tool
+  def call
+    # make a call to search API
+  end
+end
+
+class CalculatorTool < Regent::Tool
+  def call
+    # perform calculations
+  end
+end
+
+tools = [SearchTool.new, CalculatorTool.new]
+
+agent = Regent::Agent.new("You are a helpful assistant", model: "gpt-4o-mini", tools: tools)
+```
+
+Each agent run creates a **session** that contains every operation that is performed by the agent while working on a task. Sessions can be replayed and drilled down into while debugging.
+```ruby
+agent.sessions # => Returns all sessions performed by the agent
+agent.session # => Returns last session performed by the agent
+agent.session.result # => Returns result of latest agent run
+```
+
+While running agent logs all session spans (all operations) to the console with all sorts of useful information, that helps to understand what the agent was doing and why it took a certain path.
+```ruby
+weather_agent.run("What is the weather in San Francisco?")
+```
+
+Outputs:
+```console
+[✔] [INPUT][0.0s]: What is the weather in San Francisco?
+ ├──[✔] [LLM ❯ gpt-4o-mini][242 → 30 tokens][0.02s]: What is the weather in San Francisco?
+ ├──[✔] [TOOL ❯ get_weather][0.0s]: ["San Francisco"] → The weather in San Francisco is 70 degrees and sunny.
+ ├──[✔] [LLM ❯ gpt-4o-mini][294 → 26 tokens][0.01s]: Observation: The weather in San Francisco is 70 degrees and sunny.
+[✔] [ANSWER ❯ success][0.03s]: It is 70 degrees and sunny in San Francisco.
+```
+
+### Engine
+By default, Regent uses ReAct agent architecture. You can see the [details of its implementation](https://github.com/alchaplinsky/regent/blob/main/lib/regent/engine/react.rb). However, Agent constructor accepts an `engine` option that allows you to swap agent engine when instantiating an Agent. This way you can implement your own agent architecture that can be plugged in and user within Regent framework.
+
+```ruby
+agent = CustomAgent.new("You are a self-correcting assistant", model: "gpt-4o", engine: CustomEngine)
+```
+
+In order to implement your own engine you need to define a class that inherits from `Regent::Engine::Base` class and implements `reason` method:
+
+```ruby
+class CustomEngine < Regent::Engine::Base
+  def reason(task)
+    # Your implementation of an Agent lifecycle
+  end
+end
+```
+
+Note that Base class already handles `max_iteration` check, so you won't end up in an infinite loop. Also, it allows you to use `llm_call_response` and `tool_call_response` methods for agent reasoning as well as `success_answer` and `error_answer` for the final result.
+
+For any other operation that happens in your agent architecture that you want to track separately call it within the `session.exec` block. See examples in `Regent::Engine::Base` class.
+
+
+---
 ## Why Regent?
+
 - **Transparent Decision Making**: Watch your agent's thought process as it reasons through problems
 - **Flexible Architecture**: Easy to extend with custom tools and adapt to different use cases
-- **Production Ready**: Built with tracing, error handling, and clean abstractions
 - **Ruby-First Design**: Takes advantage of Ruby's elegant syntax and conventions
+- **Transparent Execution**: Built with tracing, error handling, and clean abstractions
+
 
 ## Development
 

data/lib/regent/agent.rb

@@ -3,26 +3,28 @@
 module Regent
   class Agent
     include Concerns::Identifiable
+    include Concerns::Toolable
 
     DEFAULT_MAX_ITERATIONS = 10
 
-    def initialize(context, llm:, tools: [], **options)
+    def initialize(context, model:, tools: [], engine: Regent::Engine::React, **options)
       super()
 
       @context = context
-      @llm = llm
+      @model = model.is_a?(String) ? Regent::LLM.new(model) : model
+      @engine = engine
       @sessions = []
-      @tools = tools.is_a?(Toolchain) ? tools : Toolchain.new(Array(tools))
+      @tools = build_toolchain(tools)
       @max_iterations = options[:max_iterations] || DEFAULT_MAX_ITERATIONS
     end
 
-    attr_reader :context, :sessions, :llm, :tools
+    attr_reader :context, :sessions, :model, :tools, :inline_tools
 
-    def execute(task)
+    def run(task)
       raise ArgumentError, "Task cannot be empty" if task.to_s.strip.empty?
 
       start_session
-      react.reason(task)
+      reason(task)
     ensure
       complete_session
     end
@@ -37,6 +39,10 @@ module Regent
 
     private
 
+    def reason(task)
+      engine.reason(task)
+    end
+
     def start_session
       complete_session
       @sessions << Session.new
@@ -47,8 +53,20 @@ module Regent
       session&.complete if running?
     end
 
-    def react
-      Regent::Engine::React.new(context, llm, tools, session, @max_iterations)
+    def build_toolchain(tools)
+      context = self
+
+      toolchain = Toolchain.new(Array(tools))
+
+      self.class.function_tools.each do |entry|
+        toolchain.add(entry, context)
+      end
+
+      toolchain
+    end
+
+    def engine
+      @engine.new(context, model, tools, session, @max_iterations)
     end
   end
 end

data/lib/regent/concerns/dependable.rb

@@ -25,7 +25,7 @@ module Regent
 
         super()
       rescue Gem::LoadError
-        warn_and_exit(dependency, options[:model])
+        Regent::Logger.warn_and_exit dependency_warning(dependency, model)
       end
 
       def require_dynamic(*names)
@@ -34,6 +34,8 @@ module Regent
 
       private
 
+      attr_reader :dependency
+
       def load_dependency(name)
         gem(name)
 
@@ -63,9 +65,8 @@ module Regent
         Bundler.load.dependencies
       end
 
-      def warn_and_exit(name, model)
-        warn "\n\e[33mIn order to use \e[33;1m#{model}\e[0m\e[33m model you need to install \e[33;1m#{name}\e[0m\e[33m gem. Please add \e[33;1mgem \"#{name}\"\e[0m\e[33m to your Gemfile.\e[0m"
-        exit 1
+      def dependency_warning(dependency, model)
+        "\n\e[33mIn order to use \e[33;1m#{model}\e[0m\e[33m model you need to install \e[33;1m#{dependency}\e[0m\e[33m gem. Please add \e[33;1mgem \"#{dependency}\"\e[0m\e[33m to your Gemfile.\e[0m"
       end
     end
   end

data/lib/regent/concerns/toolable.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Regent
+  module Concerns
+    module Toolable
+      def self.included(base)
+        base.class_eval do
+          class << self
+            def tool(name, description)
+              @function_tools ||= []
+              @function_tools << { name: name, description: description }
+            end
+
+            def function_tools
+              @function_tools || []
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/regent/engine/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Regent
+  module Engine
+    class Base
+      def initialize(context, llm, toolchain, session, max_iterations)
+        @context = context
+        @llm = llm
+        @toolchain = toolchain
+        @session = session
+        @max_iterations = max_iterations
+      end
+
+      attr_reader :context, :llm, :toolchain, :session, :max_iterations
+
+      private
+
+      # Run reasoning block within this method to ensure that it
+      # will not run more than max_iterations times.
+      def with_max_iterations
+        max_iterations.times do
+          yield
+        end
+
+        error_answer("Max iterations reached without finding an answer.")
+      end
+
+      # Make a call to LLM and return the response.
+      def llm_call_response(args)
+        session.exec(Span::Type::LLM_CALL, type: llm.model, message: session.messages.last[:content]) do
+          result = llm.invoke(session.messages, **args)
+
+          session.current_span.set_meta("#{result.input_tokens} → #{result.output_tokens} tokens")
+          result.content
+        end
+      end
+
+      # Make a call to a tool and return the response.
+      def tool_call_response(tool, arguments)
+        session.exec(Span::Type::TOOL_EXECUTION, { type: tool.name, message: arguments }) do
+          tool.execute(*arguments)
+        end
+      end
+
+      # Find a tool in the toolchain by name and return it.
+      def find_tool(tool_name)
+        tool = toolchain.find(tool_name)
+        return tool if tool
+
+        session.exec(Span::Type::ANSWER, type: :failure, message: "No matching tool found for: #{tool_name}")
+      end
+
+      # Complete a session with a success answer
+      def success_answer(content)
+        session.exec(Span::Type::ANSWER, top_level: true, type: :success, message: content, duration: session.duration.round(2)) { content }
+      end
+
+      # Complete a session with an error answer
+      def error_answer(content)
+        session.exec(Span::Type::ANSWER, top_level: true, type: :failure, message: content, duration: session.duration.round(2)) { content }
+      end
+    end
+  end
+end

data/lib/regent/engine/react/prompt_template.rb

@@ -13,7 +13,7 @@ module Regent
             Thought - a description of your thoughts about the question.
             Action - pick a an action from available tools if required. If there are no tools that can help return an Answer saying you are not able to help.
             Observation - is the result of running a tool.
-            PAUSE - is always present after an Action.
+            PAUSE - a stop sequence that will always be present after an Action.
 
             ## Available tools:
             #{tool_list}
@@ -21,7 +21,7 @@ module Regent
             ## Example session
             Question: What is the weather in London today?
             Thought: I need to get current weather in London
-            Action: weather_tool | London
+            Action: {"tool": "weather_tool", "args": ["London"]}
             PAUSE
 
             You will have a response form a user with Observation:

data/lib/regent/engine/react.rb

@@ -2,7 +2,7 @@
 
 module Regent
   module Engine
-    class React
+    class React < Base
       SEQUENCES = {
         answer: "Answer:",
         action: "Action:",
@@ -10,70 +10,29 @@ module Regent
         stop: "PAUSE"
       }.freeze
 
-      def initialize(context, llm, toolchain, session, max_iterations)
-        @context = context
-        @llm = llm
-        @toolchain = toolchain
-        @session = session
-        @max_iterations = max_iterations
-      end
-
-      attr_reader :context, :llm, :toolchain, :session, :max_iterations
-
       def reason(task)
-        initialize_session(task)
+        session.exec(Span::Type::INPUT, top_level: true, message: task) { task }
+        session.add_message({role: :system, content: Regent::Engine::React::PromptTemplate.system_prompt(context, toolchain.to_s)})
+        session.add_message({role: :user, content: task})
 
-        max_iterations.times do |i|
-          content = get_llm_response
+        with_max_iterations do
+          content = llm_call_response(stop: [SEQUENCES[:stop]])
           session.add_message({role: :assistant, content: content })
+
           return extract_answer(content) if answer_present?(content)
 
           if action_present?(content)
-            tool, argument = parse_action(content)
+            tool_name, arguments = parse_tool_signature(content)
+            tool = find_tool(tool_name)
             return unless tool
-
-            process_tool_execution(tool, argument)
+            result = tool_call_response(tool, arguments)
+            session.add_message({ role: :user, content: "#{SEQUENCES[:observation]} #{result}" })
           end
         end
-
-        error_answer("Max iterations reached without finding an answer.")
       end
 
       private
 
-      def initialize_session(task)
-        session.add_message({role: :system, content: Regent::Engine::React::PromptTemplate.system_prompt(context, toolchain.to_s)})
-        session.add_message({role: :user, content: task})
-        session.exec(Span::Type::INPUT, top_level: true, message: task) { task }
-      end
-
-      def get_llm_response
-        session.exec(Span::Type::LLM_CALL, type: llm.model, message: session.messages.last[:content]) do
-          result = llm.invoke(session.messages, stop: [SEQUENCES[:stop]])
-
-          session.current_span.set_meta("#{result.usage.input_tokens} → #{result.usage.output_tokens} tokens")
-          result.content
-        end
-      end
-
-      def extract_answer(content)
-        answer = content.split(SEQUENCES[:answer])[1]&.strip
-        success_answer(answer)
-      end
-
-      def parse_action(content)
-        sanitized_content = content.gsub(SEQUENCES[:stop], "")
-        lookup_tool(sanitized_content)
-      end
-
-      def process_tool_execution(tool, argument)
-        result = session.exec(Span::Type::TOOL_EXECUTION, { type: tool.name, message: argument }) do
-          tool.call(argument)
-        end
-
-        session.add_message({ role: :user, content: "#{SEQUENCES[:observation]} #{result}" })
-      end
-
       def answer_present?(content)
         content.include?(SEQUENCES[:answer])
       end
@@ -82,39 +41,17 @@ module Regent
         content.include?(SEQUENCES[:action])
       end
 
-      def success_answer(content)
-        session.exec(Span::Type::ANSWER, top_level: true,type: :success, message: content, duration: session.duration.round(2)) { content }
-      end
-
-      def error_answer(content)
-        session.exec(Span::Type::ANSWER, top_level: true, type: :failure, message: content, duration: session.duration.round(2)) { content }
-      end
-
-      def lookup_tool(content)
-        tool_name, argument = parse_tool_signature(content)
-        tool = toolchain.find(tool_name)
-
-        unless tool
-          session.exec(Span::Type::ANSWER, type: :failure, message: "No matching tool found for: #{tool_name}")
-          return [nil, nil]
-        end
-
-        [tool, argument]
+      def extract_answer(content)
+        success_answer content.split(SEQUENCES[:answer])[1]&.strip
       end
 
       def parse_tool_signature(content)
-        action = content.split(SEQUENCES[:action])[1]&.strip
-        return [nil, nil] unless action
-
-        parts = action.split('|').map(&:strip)
-        tool_name = parts[0].gsub(/["`']/, '')
-        argument = parts[1].gsub(/["`']/, '')
-
-        # Handle cases where argument is nil, empty, or only whitespace
-        argument = nil if argument.nil? || argument.empty?
+        return [nil, nil] unless match = content.match(/Action:.*?\{.*"tool".*\}/m)
 
-        [tool_name, argument]
-      rescue
+        # Extract just the JSON part using a second regex
+        json = JSON.parse(match[0].match(/\{.*\}/m)[0])
+        [json["tool"], json["args"] || []]
+      rescue JSON::ParserError
         [nil, nil]
       end
     end

data/lib/regent/llm/anthropic.rb

@@ -9,14 +9,25 @@ module Regent
       depends_on "anthropic"
 
       def invoke(messages, **args)
-        response = client.messages(parameters: {
+        parameters = {
           messages: format_messages(messages),
-          system: system_instruction(messages),
-          model: options[:model],
-          stop_sequences: args[:stop] ? args[:stop] : nil,
+          model: model,
+          temperature: args[:temperature] || 0.0,
+          stop_sequences: args[:stop] || [],
           max_tokens: MAX_TOKENS
-        })
-        format_response(response)
+        }
+        if system_instruction = system_instruction(messages)
+          parameters[:system] = system_instruction
+        end
+
+        response = client.messages(parameters:)
+
+        result(
+          model: model,
+          content: response.dig("content", 0, "text"),
+          input_tokens: response.dig("usage", "input_tokens"),
+          output_tokens: response.dig("usage", "output_tokens")
+        )
       end
 
       private
@@ -32,17 +43,6 @@ module Regent
       def format_messages(messages)
         messages.reject { |message| message[:role].to_s == "system" }
       end
-
-      def format_response(response)
-        Response.new(
-          content: response.dig("content", 0, "text"),
-          model: options[:model],
-          usage: Usage.new(
-            input_tokens: response.dig("usage", "input_tokens"),
-            output_tokens: response.dig("usage", "output_tokens")
-          )
-        )
-      end
     end
   end
 end

data/lib/regent/llm/base.rb

@@ -2,55 +2,36 @@
 
 module Regent
   class LLM
-    class Response
-      def initialize(content:, usage:, model:)
-        @content = content
-        @usage = usage
-        @model = model
-      end
-
-      attr_reader :content, :usage, :model
-    end
-
-    class Usage
-      def initialize(input_tokens:, output_tokens:)
-        @input_tokens = input_tokens
-        @output_tokens = output_tokens
-      end
-
-      attr_reader :input_tokens, :output_tokens
-    end
+    Result = Struct.new(:model, :content, :input_tokens, :output_tokens, keyword_init: true)
 
     class Base
       include Concerns::Dependable
 
-      def initialize(**options)
+      def initialize(model:, api_key: nil, **options)
+        @model = model
+        @api_key = api_key || api_key_from_env
         @options = options
-        api_key.nil?
 
         super()
       end
 
-      def invoke(messages, **args)
-        provider.chat(messages: format_messages(messages), **args)
+      def parse_error(error)
+        error.response.dig(:body, "error", "message")
       end
 
       private
 
-      attr_reader :options, :dependency
+      attr_reader :model, :api_key, :options
 
-      def format_response(response)
-        Response.new(
-          content: response.chat_completion,
-          model: options[:model],
-          usage: Usage.new(input_tokens: response.prompt_tokens, output_tokens: response.completion_tokens)
+      def result(model:, content:, input_tokens:, output_tokens:)
+        Result.new(
+          model: model,
+          content: content,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens
         )
       end
 
-      def api_key
-        @api_key ||= options[:api_key] || api_key_from_env
-      end
-
       def api_key_from_env
         ENV.fetch(self.class::ENV_KEY) do
           raise APIKeyNotFoundError, "API key not found. Make sure to set #{self.class::ENV_KEY} environment variable."

data/lib/regent/llm/gemini.rb

@@ -4,20 +4,37 @@ module Regent
   class LLM
     class Gemini < Base
       ENV_KEY = "GEMINI_API_KEY"
+      SERVICE = "generative-language-api"
 
       depends_on "gemini-ai"
 
       def invoke(messages, **args)
-        response = client.generate_content({ contents: format_messages(messages) })
-        format_response(response)
+        response = client.generate_content({
+          contents: format_messages(messages),
+          generation_config: {
+            temperature: args[:temperature] || 0.0,
+            stop_sequences: args[:stop] || []
+          }
+        })
+
+        result(
+          model: model,
+          content: response.dig("candidates", 0, "content", "parts", 0, "text").strip,
+          input_tokens: response.dig("usageMetadata", "promptTokenCount"),
+          output_tokens: response.dig("usageMetadata", "candidatesTokenCount")
+        )
+      end
+
+      def parse_error(error)
+        JSON.parse(error.response.dig(:body)).dig("error", "message")
       end
 
       private
 
       def client
         @client ||= ::Gemini.new(
-          credentials: { service: 'generative-language-api', api_key: api_key },
-          options: { model: options[:model] }
+          credentials: { service: SERVICE, api_key: api_key },
+          options: { model: model }
         )
       end
 
@@ -26,17 +43,6 @@ module Regent
           { role: message[:role].to_s == "system" ? "user" : message[:role], parts: [{ text: message[:content] }] }
         end
       end
-
-      def format_response(response)
-       Response.new(
-          content: response.dig("candidates", 0, "content", "parts", 0, "text").strip,
-          model: options[:model],
-          usage: Usage.new(
-            input_tokens: response.dig("usageMetadata", "promptTokenCount"),
-            output_tokens: response.dig("usageMetadata", "candidatesTokenCount")
-          )
-        )
-      end
     end
   end
 end

data/lib/regent/llm/ollama.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Regent
+  class LLM
+    class Ollama < Base
+      # Default host for Ollama API.
+      DEFAULT_HOST = "http://localhost:11434"
+
+      def initialize(model:, host: nil, **options)
+        @model = model
+        @host = host || DEFAULT_HOST
+        @options = options
+      end
+
+      attr_reader :model
+
+      def invoke(messages, **args)
+        response = client.post("/api/chat", {
+          model: model,
+          messages: messages,
+          stream: false
+        })
+
+        if response.status == 200
+          result(
+            model: response.body.dig("model"),
+            content: response.body.dig("message", "content").strip,
+            input_tokens: nil,
+            output_tokens: nil
+          )
+        else
+          raise ApiError, response.body.dig("error")
+        end
+      end
+
+      def parse_error(error)
+        error.message
+      end
+
+      private
+
+      attr_reader :host
+
+      def client
+        @client ||= Faraday.new(host) do |f|
+          f.request :json
+          f.response :json
+          f.adapter :net_http
+        end
+      end
+
+      def api_key_from_env
+        nil
+      end
+    end
+  end
+end

data/lib/regent/llm/open_ai.rb

@@ -10,10 +10,17 @@ module Regent
       def invoke(messages, **args)
         response = client.chat(parameters: {
           messages: messages,
-          model: options[:model],
-          stop: args[:stop]
+          model: model,
+          temperature: args[:temperature] || 0.0,
+          stop: args[:stop] || []
         })
-        format_response(response)
+
+        result(
+          model: model,
+          content: response.dig("choices", 0, "message", "content"),
+          input_tokens: response.dig("usage", "prompt_tokens"),
+          output_tokens: response.dig("usage", "completion_tokens")
+        )
       end
 
       private
@@ -21,17 +28,6 @@ module Regent
       def client
         @client ||= ::OpenAI::Client.new(access_token: api_key)
       end
-
-      def format_response(response)
-        Response.new(
-          content: response.dig("choices", 0, "message", "content"),
-          model: options[:model],
-          usage: Usage.new(
-            input_tokens: response.dig("usage", "prompt_tokens"),
-            output_tokens: response.dig("usage", "completion_tokens")
-          )
-        )
-      end
     end
   end
 end

data/lib/regent/llm/open_router.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Regent
+  class LLM
+    class OpenRouter < Base
+      ENV_KEY = "OPEN_ROUTER_API_KEY"
+
+      depends_on "open_router"
+
+      def invoke(messages, **args)
+        response = client.complete(
+          messages,
+          model: model,
+          extras: {
+            temperature: args[:temperature] || 0.0,
+            stop: args[:stop] || [],
+            **args
+          }
+        )
+        result(
+          model: model,
+          content: response.dig("choices", 0, "message", "content"),
+          input_tokens: response.dig("usage", "prompt_tokens"),
+          output_tokens: response.dig("usage", "completion_tokens")
+        )
+      end
+
+      private
+
+      def client
+        @client ||= ::OpenRouter::Client.new access_token: api_key
+      end
+    end
+  end
+end

data/lib/regent/llm.rb

@@ -2,6 +2,7 @@
 
 module Regent
   class LLM
+    DEFAULT_RETRY_COUNT = 3
     PROVIDER_PATTERNS = {
       OpenAI: /^gpt-/,
       Gemini: /^gemini-/,
@@ -10,28 +11,46 @@ module Regent
 
     class ProviderNotFoundError < StandardError; end
     class APIKeyNotFoundError < StandardError; end
+    class ApiError < StandardError; end
 
-    def initialize(model, **options)
-      @model = model
+    def initialize(model, strict_mode: true, **options)
+      @strict_mode = strict_mode
       @options = options
-      instantiate_provider
+      if model.class.ancestors.include?(Regent::LLM::Base)
+        @model = model.model
+        @provider = model
+      else
+        @model = model
+        @provider = instantiate_provider
+      end
     end
 
     attr_reader :model, :options
 
     def invoke(messages, **args)
+      retries = 0
+
+      messages = [{ role: "user", content: messages }] if messages.is_a?(String)
+
       provider.invoke(messages, **args)
+
+    rescue Faraday::Error, ApiError => error
+      if error.respond_to?(:retryable?) && error.retryable? && retries < DEFAULT_RETRY_COUNT
+        sleep(exponential_backoff(retries))
+        retry
+      end
+      handle_error(error)
     end
 
     private
 
-    attr_reader :provider
+    attr_reader :provider, :strict_mode
 
     def instantiate_provider
       provider_class = find_provider_class
       raise ProviderNotFoundError, "Provider for #{model} is not found" if provider_class.nil?
 
-      @provider ||= create_provider(provider_class)
+      create_provider(provider_class)
     end
 
     def find_provider_class
@@ -41,5 +60,16 @@ module Regent
     def create_provider(provider_class)
       Regent::LLM.const_get(provider_class).new(**options.merge(model: model))
     end
+
+    def handle_error(error)
+      message = provider.parse_error(error) || error.message
+      raise ApiError, message if strict_mode
+      Result.new(model: model, content: message, input_tokens: nil, output_tokens: nil)
+    end
+
+    def exponential_backoff(retry_count)
+      # Exponential backoff with jitter: 2^n * 100ms + random jitter
+      (2**retry_count * 0.1) + rand(0.1)
+    end
   end
 end

data/lib/regent/logger.rb

@@ -2,7 +2,14 @@
 
 module Regent
   class Logger
-    COLORS = %i[dim green yellow red blue cyan clear].freeze
+    COLORS = %i[dim white green yellow red blue cyan clear].freeze
+
+    class << self
+      def warn_and_exit(message)
+        warn message
+        exit 1
+      end
+    end
 
     def initialize(output: $stdout)
       @pastel = Pastel.new
@@ -14,7 +21,6 @@ module Regent
 
     def info(label:, message:, duration: nil, type: nil, meta: nil, top_level: false)
       current_spinner = top_level ? spinner : nested_spinner
-
       current_spinner.update(title: format_message(label, message, duration, type, meta))
       current_spinner
     end
@@ -47,7 +53,7 @@ module Regent
     end
 
     def spinner_symbol
-      "#{dim("[")}#{green(":spinner")}#{dim("]")}"
+      "#{dim("[")}#{white(":spinner")}#{dim("]")}"
     end
 
     def build_spinner(spinner_format, output)

data/lib/regent/span.rb

@@ -43,7 +43,8 @@ module Regent
     def run
       @output = log_operation do
         yield
-      rescue StandardError => e
+
+      rescue StandardError, ToolError => e
         logger.error(label: type, message: e.message, **arguments)
         raise
       end
@@ -84,9 +85,13 @@ module Regent
       result = yield
 
       @end_time = live ? Time.now.freeze : @end_time
+      update_message_with_result(result) if type == Type::TOOL_EXECUTION
       logger.success(label: type, **({ duration: duration.round(2), meta: meta }.merge(arguments)))
-
       result
     end
+
+    def update_message_with_result(message)
+      arguments[:message] = "#{arguments[:message]} → #{message}"
+    end
   end
 end

data/lib/regent/tool.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Regent
+  class ToolError < StandardError; end
+
   class Tool
     def initialize(name:, description:)
       @name = name
@@ -13,6 +15,12 @@ module Regent
       raise NotImplementedError, "Tool #{name} has not implemented the execute method"
     end
 
+    def execute(*arguments)
+      call(*arguments)
+    rescue NotImplementedError, StandardError => e
+      raise ToolError, e.message
+    end
+
     def to_s
       "#{name} - #{description}"
     end

data/lib/regent/toolchain.rb

@@ -12,8 +12,23 @@ module Regent
       tools.find { |tool| tool.name.downcase == name.downcase }
     end
 
+    def add(tool, context)
+      @tools << Regent::Tool.new(name: tool[:name].to_s, description: tool[:description]).instance_eval do
+        raise "A tool method '#{tool[:name]}' is missing in the #{context.class.name}" unless context.respond_to?(tool[:name])
+
+        define_singleton_method(:call){ |*args| context.send(tool[:name], *args) }
+        self
+      end
+    end
+
     def to_s
       tools.map(&:to_s).join("\n")
     end
+
+    private
+
+    def tool_missing_error(tool_name, context_name)
+      "A tool method '#{tool_name}' is missing in the #{context_name}"
+    end
   end
 end

data/lib/regent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Regent
-  VERSION = "0.3.1"
+  VERSION = "0.3.3"
 end

data/lib/regent.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require 'faraday'
+require 'json'
 require 'pastel'
 require 'tty-spinner'
 require 'zeitwerk'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: regent
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - Alex Chaplinsky
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-29 00:00:00.000000000 Z
+date: 2025-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -71,13 +71,17 @@ files:
 - lib/regent/concerns/dependable.rb
 - lib/regent/concerns/durationable.rb
 - lib/regent/concerns/identifiable.rb
+- lib/regent/concerns/toolable.rb
+- lib/regent/engine/base.rb
 - lib/regent/engine/react.rb
 - lib/regent/engine/react/prompt_template.rb
 - lib/regent/llm.rb
 - lib/regent/llm/anthropic.rb
 - lib/regent/llm/base.rb
 - lib/regent/llm/gemini.rb
+- lib/regent/llm/ollama.rb
 - lib/regent/llm/open_ai.rb
+- lib/regent/llm/open_router.rb
 - lib/regent/logger.rb
 - lib/regent/session.rb
 - lib/regent/span.rb