regent 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a728784fd3d7720bb7fd96bf2cd22a8d53e59eaed01c9b4240a2cb09023e261
-  data.tar.gz: 78ddbe87cf964ca94039f560ddfcb743a14757e551af0847363b0fa82228e4a7
+  metadata.gz: a1c3bc1771d81f732f941e27dfc393ef56b6f6c42d6c448385202f065dfc5811
+  data.tar.gz: 8950e15664e538beffc54d5e0e92da76bc8390e7ddd20bc923914ad14d3613e3
 SHA512:
-  metadata.gz: c0306c99637469cff9e51a9b1b50424e646f38dd601dcb5b36d8eee417e2f280488b3e6c78747c242d78d8213fd6a9e004d3cd7065b692d7dc63a5900bf20e16
-  data.tar.gz: 68302a81b5062f54415a89e49513e2186afd0fb6d129dfa1111b33565ade932cbae9e657218d66b37cf2fd58b78103456da0dcc7c52c26948016134117cc4e42
+  metadata.gz: 3d6a447a3df128617b5ede55412752a331f6edcb556039ea09472357b258803889722331408baf1e7b8add8111c5addbf58016a6799b3d2d98d608a88b501e39
+  data.tar.gz: f496a6abdd8646342bb0d2fd34b59893d9770e74d7325d1fdf79d3d0d33751765b3dfd17a2dacf4636fd045edbc0c9661fadb143df24be206a281e6b7b2a356e

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)
@@ -55,7 +56,7 @@ Create your first agent:
 
 ```ruby
 # Initialize the LLM
-llm = Regent::LLM.new("gpt-4o")
+model = Regent::LLM.new("gpt-4o")
 
 # Create a custom tool
 class WeatherTool < Regent::Tool
@@ -68,7 +69,7 @@ end
 # Create and configure the agent
 agent = Regent::Agent.new(
   "You are a helpful weather assistant",
-  llm: llm,
+  model: model,
   tools: [WeatherTool.new(
     name: "weather_tool",
     description: "Get current weather for a location"
@@ -76,10 +77,11 @@ agent = Regent::Agent.new(
 )
 
 # 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."
 ```
 
 ## 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

data/lib/regent/agent.rb

@@ -6,23 +6,24 @@ module Regent
 
     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
+      @engine = engine
       @sessions = []
       @tools = tools.is_a?(Toolchain) ? tools : Toolchain.new(Array(tools))
       @max_iterations = options[:max_iterations] || DEFAULT_MAX_ITERATIONS
     end
 
-    attr_reader :context, :sessions, :llm, :tools
+    attr_reader :context, :sessions, :model, :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 +38,10 @@ module Regent
 
     private
 
+    def reason(task)
+      engine.reason(task)
+    end
+
     def start_session
       complete_session
       @sessions << Session.new
@@ -47,8 +52,8 @@ module Regent
       session&.complete if running?
     end
 
-    def react
-      Regent::Engine::React.new(context, llm, tools, session, @max_iterations)
+    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/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

@@ -12,11 +12,18 @@ module Regent
         response = client.messages(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)
+
+        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 +39,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/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.rb

@@ -2,6 +2,7 @@
 
 module Regent
   class LLM
+    DEFAULT_RETRY_COUNT = 3
     PROVIDER_PATTERNS = {
       OpenAI: /^gpt-/,
       Gemini: /^gemini-/,
@@ -10,9 +11,11 @@ module Regent
 
     class ProviderNotFoundError < StandardError; end
     class APIKeyNotFoundError < StandardError; end
+    class ApiError < StandardError; end
 
-    def initialize(model, **options)
+    def initialize(model, strict_mode: true, **options)
       @model = model
+      @strict_mode = strict_mode
       @options = options
       instantiate_provider
     end
@@ -20,12 +23,20 @@ module Regent
     attr_reader :model, :options
 
     def invoke(messages, **args)
+      retries = 0
       provider.invoke(messages, **args)
+
+    rescue Faraday::Error => 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
@@ -41,5 +52,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

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Regent
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 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.2
 platform: ruby
 authors:
 - Alex Chaplinsky
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-29 00:00:00.000000000 Z
+date: 2025-01-04 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/engine/base.rb
 - lib/regent/engine/react.rb
 - lib/regent/engine/react/prompt_template.rb
 - lib/regent/llm.rb