regent 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd53327576ffc795ba61329d4ba018c378bf38acd790832c2d7735ea9a2af647
-  data.tar.gz: 7143f84225c50bb3489e44eaf9cd50b115b49203706130b30e74e5d89eefb861
+  metadata.gz: 9a728784fd3d7720bb7fd96bf2cd22a8d53e59eaed01c9b4240a2cb09023e261
+  data.tar.gz: 78ddbe87cf964ca94039f560ddfcb743a14757e551af0847363b0fa82228e4a7
 SHA512:
-  metadata.gz: 6f158ad85ad090a4676ba7db6c5a2326f16826ca2adfebbe0652f1fe987fa6733349a1623e31ef95740769d1f6ea4d0f34d04dba9c4f4913f2ee733ad6563686
-  data.tar.gz: c825330735acbb6e73169add11b399e810938807156e6b996c60652bebf073da141d66d20e1fd729f48570110813514dbb8b18bd7db12625657a0434a2c660bd
+  metadata.gz: c0306c99637469cff9e51a9b1b50424e646f38dd601dcb5b36d8eee417e2f280488b3e6c78747c242d78d8213fd6a9e004d3cd7065b692d7dc63a5900bf20e16
+  data.tar.gz: 68302a81b5062f54415a89e49513e2186afd0fb6d129dfa1111b33565ade932cbae9e657218d66b37cf2fd58b78103456da0dcc7c52c26948016134117cc4e42

data/README.md

@@ -1,19 +1,37 @@
-
 ![regent_light](https://github.com/user-attachments/assets/62564dac-b8d7-4dc0-9b63-64c6841b5872)
 
+<div align="center">
+
 # Regent
-**Regent** is library for building AI agents with Ruby.
+[![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)
+
+</div>
+
+**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]
 > 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.
 
+## Key Features
+
+- **ReAct Pattern Implementation**: Agents follow the Reasoning-Action pattern, making decisions through a clear thought process before taking actions
+- **Multi-LLM Support**: Seamlessly works with:
+  - OpenAI (GPT models)
+  - Anthropic (Claude models)
+  - Google (Gemini models)
+- **Extensible Tool System**: Create custom tools that agents can use to interact with external services, APIs, or perform specific tasks
+- **Built-in Tracing**: Every agent interaction is traced and can be replayed, making debugging and monitoring straightforward
+- **Clean Ruby Interface**: Designed to feel natural to Ruby developers while maintaining powerful capabilities
+
 ## Showcase
+
 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)
 
-
-## Install
+## Quick Start
 
 ```bash
 gem install regent
@@ -32,33 +50,40 @@ bundle install
 ```
 
 ## Usage
-In order to operate an agent needs access to LLM (large language model). Regent relies on the [Langchainrb](https://github.com/patterns-ai-core/langchainrb) library to interact with LLMs. Let's create an instance of OapnAI LLM:
-```ruby
-llm = Langchain::LLM::OpenAI(api_key: ENV["OPENAI_KEY"])
-```
 
-Agents are effective when they have tools that enable them to get new information:
+Create your first agent:
 
 ```ruby
+# Initialize the LLM
+llm = Regent::LLM.new("gpt-4o")
+
+# Create a custom tool
 class WeatherTool < Regent::Tool
   def call(location)
-    # implementation of a call to weather API
+    # Implement weather lookup logic
+    "Currently 72°F and sunny in #{location}"
   end
 end
 
-weather_tool = WeatherTool.new(name: "weather_tool", description: "Get the weather in a given location")
-```
-
-Next, let's instantiate an agent passing LLM and a set of tools:
-
-```ruby
-agent = Regent::Agent.new(llm: llm, tools: [weather_tool])
+# 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"
+  )]
+)
+
+# Execute a query
+result = agent.execute("What's the weather like in Tokyo?") # => "It is currently 72°F and sunny in Tokyo."
 ```
 
-Simply run an execute function, passing your query as an argument
-``` ruby
-agent.execute("What is the weather in London today?")
-```
+## 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
 
 ## Development
 

data/lib/regent/agent.rb

@@ -6,16 +6,17 @@ module Regent
 
     DEFAULT_MAX_ITERATIONS = 10
 
-    def initialize(llm:, tools: [], **options)
+    def initialize(context, llm:, tools: [], **options)
       super()
 
+      @context = context
       @llm = llm
       @sessions = []
       @tools = tools.is_a?(Toolchain) ? tools : Toolchain.new(Array(tools))
       @max_iterations = options[:max_iterations] || DEFAULT_MAX_ITERATIONS
     end
 
-    attr_reader :sessions, :llm, :tools
+    attr_reader :context, :sessions, :llm, :tools
 
     def execute(task)
       raise ArgumentError, "Task cannot be empty" if task.to_s.strip.empty?
@@ -47,7 +48,7 @@ module Regent
     end
 
     def react
-      Regent::Engine::React.new(llm, tools, session, @max_iterations)
+      Regent::Engine::React.new(context, llm, tools, session, @max_iterations)
     end
   end
 end

data/lib/regent/concerns/dependable.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Regent
+  module Concerns
+    module Dependable
+      class VersionError < StandardError; end
+
+      def self.included(base)
+        base.class_eval do
+          class << self
+            def depends_on(gem_name)
+              @dependency = gem_name
+            end
+
+            def dependency
+              @dependency
+            end
+          end
+        end
+      end
+
+      def initialize(**options)
+        @dependency = self.class.dependency
+        require_dynamic(dependency) if dependency
+
+        super()
+      rescue Gem::LoadError
+        warn_and_exit(dependency, options[:model])
+      end
+
+      def require_dynamic(*names)
+        names.each { |name| load_dependency(name) }
+      end
+
+      private
+
+      def load_dependency(name)
+        gem(name)
+
+        return true unless defined? Bundler
+
+        gem_spec = Gem::Specification.find_by_name(name)
+        gem_requirement = dependencies.find { |gem| gem.name == gem_spec.name }.requirement
+
+        unless gem_requirement.satisfied_by?(gem_spec.version)
+          raise VersionError, version_error(gem_spec, gem_requirement)
+        end
+
+        require_gem(gem_spec)
+      end
+
+      def version_error(gem_spec, gem_requirement)
+        "'#{gem_spec.name}' gem version is #{gem_spec.version}, but your Gemfile specified #{gem_requirement}."
+      end
+
+      def require_gem(gem_spec)
+        gem_spec.full_require_paths.each do |path|
+          Dir.glob("#{path}/*.rb").each { |file| require file }
+        end
+      end
+
+      def dependencies
+        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
+      end
+    end
+  end
+end

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

@@ -4,24 +4,27 @@ module Regent
   module Engine
     class React
       module PromptTemplate
-        def self.system_prompt(tool_names)
+        def self.system_prompt(context = "", tool_list = "")
           <<~PROMPT
-            You are assisstant reasoning step-by-step to solve complex problems.
-            Your reasoning process happens in a loop of Though, Action, Observation.
+            ## Instructions
+            #{context ? "Consider the following context: #{context}\n\n" : ""}
+            You are an AI agent reasoning step-by-step to solve complex problems.
+            Your reasoning process happens in a loop of Thought, Action, Observation.
             Thought - a description of your thoughts about the question.
-            Action - pick a an action from available tools. If there are no tools that can help return an Answer saying you are not able to help..
+            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.
 
             ## Available tools:
-            #{tool_names}
+            #{tool_list}
 
             ## Example session
             Question: What is the weather in London today?
-            Thought: I need to get the wether in London
-            Action: weather_tool | "London"
+            Thought: I need to get current weather in London
+            Action: weather_tool | London
             PAUSE
 
-            You will have a response with Observation:
+            You will have a response form a user with Observation:
             Observation: It is 32 degress and Sunny
 
             ... (this Thought/Action/Observation can repeat N times)

data/lib/regent/engine/react.rb

@@ -10,14 +10,15 @@ module Regent
         stop: "PAUSE"
       }.freeze
 
-      def initialize(llm, toolchain, session, max_iterations)
+      def initialize(context, llm, toolchain, session, max_iterations)
+        @context = context
         @llm = llm
         @toolchain = toolchain
         @session = session
         @max_iterations = max_iterations
       end
 
-      attr_reader :llm, :toolchain, :session, :max_iterations
+      attr_reader :context, :llm, :toolchain, :session, :max_iterations
 
       def reason(task)
         initialize_session(task)
@@ -41,18 +42,17 @@ module Regent
       private
 
       def initialize_session(task)
-        session.add_message({role: :system, content: Regent::Engine::React::PromptTemplate.system_prompt(toolchain.to_s)})
+        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, message: task) { 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.defaults[:chat_model], message: session.messages.last[:content]) do
-          result = llm.chat(messages: session.messages, params: { stop: [SEQUENCES[:stop]] })
+        session.exec(Span::Type::LLM_CALL, type: llm.model, message: session.messages.last[:content]) do
+          result = llm.invoke(session.messages, stop: [SEQUENCES[:stop]])
 
-          # Relying on Langchain Response interface to get token counts and chat completion
-          session.current_span.set_meta("#{result.prompt_tokens} → #{result.completion_tokens} tokens")
-          result.chat_completion
+          session.current_span.set_meta("#{result.usage.input_tokens} → #{result.usage.output_tokens} tokens")
+          result.content
         end
       end
 
@@ -83,11 +83,11 @@ module Regent
       end
 
       def success_answer(content)
-        session.exec(Span::Type::ANSWER, 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
 
       def error_answer(content)
-        session.exec(Span::Type::ANSWER, type: :failure, message: content, duration: session.duration.round(2)) { content }
+        session.exec(Span::Type::ANSWER, top_level: true, type: :failure, message: content, duration: session.duration.round(2)) { content }
       end
 
       def lookup_tool(content)
@@ -106,9 +106,9 @@ module Regent
         action = content.split(SEQUENCES[:action])[1]&.strip
         return [nil, nil] unless action
 
-        parts = action.split('|', 2).map(&:strip)
-        tool_name = parts[0]
-        argument = parts[1].gsub('"', '')
+        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?

data/lib/regent/llm/anthropic.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Regent
+  class LLM
+    class Anthropic < Base
+      MAX_TOKENS = 1000
+      ENV_KEY = "ANTHROPIC_API_KEY"
+
+      depends_on "anthropic"
+
+      def invoke(messages, **args)
+        response = client.messages(parameters: {
+          messages: format_messages(messages),
+          system: system_instruction(messages),
+          model: options[:model],
+          stop_sequences: args[:stop] ? args[:stop] : nil,
+          max_tokens: MAX_TOKENS
+        })
+        format_response(response)
+      end
+
+      private
+
+      def client
+        @client ||= ::Anthropic::Client.new(access_token: api_key)
+      end
+
+      def system_instruction(messages)
+        messages.find { |message| message[:role].to_s == "system" }&.dig(:content)
+      end
+
+      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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+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
+
+    class Base
+      include Concerns::Dependable
+
+      def initialize(**options)
+        @options = options
+        api_key.nil?
+
+        super()
+      end
+
+      def invoke(messages, **args)
+        provider.chat(messages: format_messages(messages), **args)
+      end
+
+      private
+
+      attr_reader :options, :dependency
+
+      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)
+        )
+      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."
+        end
+      end
+    end
+  end
+end

data/lib/regent/llm/gemini.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Regent
+  class LLM
+    class Gemini < Base
+      ENV_KEY = "GEMINI_API_KEY"
+
+      depends_on "gemini-ai"
+
+      def invoke(messages, **args)
+        response = client.generate_content({ contents: format_messages(messages) })
+        format_response(response)
+      end
+
+      private
+
+      def client
+        @client ||= ::Gemini.new(
+          credentials: { service: 'generative-language-api', api_key: api_key },
+          options: { model: options[:model] }
+        )
+      end
+
+      def format_messages(messages)
+        messages.map do |message|
+          { 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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Regent
+  class LLM
+    class OpenAI < Base
+      ENV_KEY = "OPENAI_API_KEY"
+
+      depends_on "ruby-openai"
+
+      def invoke(messages, **args)
+        response = client.chat(parameters: {
+          messages: messages,
+          model: options[:model],
+          stop: args[:stop]
+        })
+        format_response(response)
+      end
+
+      private
+
+      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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Regent
+  class LLM
+    PROVIDER_PATTERNS = {
+      OpenAI: /^gpt-/,
+      Gemini: /^gemini-/,
+      Anthropic: /^claude-/
+    }.freeze
+
+    class ProviderNotFoundError < StandardError; end
+    class APIKeyNotFoundError < StandardError; end
+
+    def initialize(model, **options)
+      @model = model
+      @options = options
+      instantiate_provider
+    end
+
+    attr_reader :model, :options
+
+    def invoke(messages, **args)
+      provider.invoke(messages, **args)
+    end
+
+    private
+
+    attr_reader :provider
+
+    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)
+    end
+
+    def find_provider_class
+      PROVIDER_PATTERNS.find { |key, pattern| model.match?(pattern) }&.first
+    end
+
+    def create_provider(provider_class)
+      Regent::LLM.const_get(provider_class).new(**options.merge(model: model))
+    end
+  end
+end

data/lib/regent/logger.rb

@@ -4,10 +4,10 @@ module Regent
   class Logger
     COLORS = %i[dim green yellow red blue cyan clear].freeze
 
-    def initialize
+    def initialize(output: $stdout)
       @pastel = Pastel.new
-      @spinner = build_spinner(spinner_symbol)
-      @nested_spinner = build_spinner("#{dim(" ├──")}#{spinner_symbol}")
+      @spinner = build_spinner(spinner_symbol, output)
+      @nested_spinner = build_spinner("#{dim(" ├──")}#{spinner_symbol}", output)
     end
 
     attr_reader :spinner, :nested_spinner
@@ -50,8 +50,8 @@ module Regent
       "#{dim("[")}#{green(":spinner")}#{dim("]")}"
     end
 
-    def build_spinner(spinner_format)
-      TTY::Spinner.new("#{spinner_format} :title", format: :dots)
+    def build_spinner(spinner_format, output)
+      TTY::Spinner.new("#{spinner_format} :title", format: :dots, output: output)
     end
 
     COLORS.each do |color|

data/lib/regent/version.rb

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

data/lib/regent.rb

@@ -10,5 +10,7 @@ module Regent
   # Your code goes here...
 
   loader = Zeitwerk::Loader.for_gem
+  loader.inflector.inflect("llm" => "LLM")
+  loader.inflector.inflect("open_ai" => "OpenAI")
   loader.setup
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: regent
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Alex Chaplinsky
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-25 00:00:00.000000000 Z
+date: 2024-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -24,34 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
-- !ruby/object:Gem::Dependency
-  name: ruby-openai
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 7.3.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 7.3.1
-- !ruby/object:Gem::Dependency
-  name: langchainrb
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.19.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.19.2
 - !ruby/object:Gem::Dependency
   name: tty-spinner
   requirement: !ruby/object:Gem::Requirement
@@ -96,10 +68,16 @@ files:
 - Rakefile
 - lib/regent.rb
 - lib/regent/agent.rb
+- lib/regent/concerns/dependable.rb
 - lib/regent/concerns/durationable.rb
 - lib/regent/concerns/identifiable.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/open_ai.rb
 - lib/regent/logger.rb
 - lib/regent/session.rb
 - lib/regent/span.rb