regent 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1c3bc1771d81f732f941e27dfc393ef56b6f6c42d6c448385202f065dfc5811
-  data.tar.gz: 8950e15664e538beffc54d5e0e92da76bc8390e7ddd20bc923914ad14d3613e3
+  metadata.gz: b507ccf9494ec028a77c396a80acd23bb686b4e1e15ba6b993430b479f495aeb
+  data.tar.gz: 8a00bcfaddae77f89b19ec72a9112c82e07086a2fee2713fc71fac5cbf0581b1
 SHA512:
-  metadata.gz: 3d6a447a3df128617b5ede55412752a331f6edcb556039ea09472357b258803889722331408baf1e7b8add8111c5addbf58016a6799b3d2d98d608a88b501e39
-  data.tar.gz: f496a6abdd8646342bb0d2fd34b59893d9770e74d7325d1fdf79d3d0d33751765b3dfd17a2dacf4636fd045edbc0c9661fadb143df24be206a281e6b7b2a356e
+  metadata.gz: e1249458a5fa9e035a9bc9c6dfb7102ec9efcdd6f1fbb71fe8638194e6181256ae09df6f7ec42ccb781bf641cdcae13c84c2104ec33e8543e5480868fe03bd77
+  data.tar.gz: be2357b3af64f96d69573bbc913c3322a11aa40434f84aba314e64ef066c78821ead732becb2f455c5f93251907f724ca7cd48109706108c66d3d57a9837b5b4

data/README.md

@@ -12,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
 
@@ -30,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
 
@@ -52,40 +54,191 @@ bundle install
 
 ## Usage
 
-Create your first agent:
+### Quick Example
+
+Create your first weather agent:
 
 ```ruby
-# Initialize the LLM
-model = 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",
-  model: model,
-  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
 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,6 +3,7 @@
 module Regent
   class Agent
     include Concerns::Identifiable
+    include Concerns::Toolable
 
     DEFAULT_MAX_ITERATIONS = 10
 
@@ -10,14 +11,14 @@ module Regent
       super()
 
       @context = context
-      @model = model
+      @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, :model, :tools
+    attr_reader :context, :sessions, :model, :tools, :inline_tools
 
     def run(task)
       raise ArgumentError, "Task cannot be empty" if task.to_s.strip.empty?
@@ -52,6 +53,18 @@ module Regent
       session&.complete if running?
     end
 
+    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

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

@@ -52,7 +52,7 @@ module Regent
 
       # 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 }
+        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

data/lib/regent/llm/anthropic.rb

@@ -9,14 +9,18 @@ module Regent
       depends_on "anthropic"
 
       def invoke(messages, **args)
-        response = client.messages(parameters: {
+        parameters = {
           messages: format_messages(messages),
-          system: system_instruction(messages),
           model: model,
           temperature: args[:temperature] || 0.0,
           stop_sequences: args[:stop] || [],
           max_tokens: MAX_TOKENS
-        })
+        }
+        if system_instruction = system_instruction(messages)
+          parameters[:system] = system_instruction
+        end
+
+        response = client.messages(parameters:)
 
         result(
           model: model,

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_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

@@ -14,19 +14,27 @@ module Regent
     class ApiError < StandardError; end
 
     def initialize(model, strict_mode: true, **options)
-      @model = model
       @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 => error
+    rescue Faraday::Error, ApiError => error
       if error.respond_to?(:retryable?) && error.retryable? && retries < DEFAULT_RETRY_COUNT
         sleep(exponential_backoff(retries))
         retry
@@ -42,7 +50,7 @@ module Regent
       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

data/lib/regent/span.rb

@@ -85,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/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.2"
+  VERSION = "0.3.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: regent
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Alex Chaplinsky
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-01-04 00:00:00.000000000 Z
+date: 2025-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -71,6 +71,7 @@ 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
@@ -78,7 +79,9 @@ files:
 - 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