regent 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feb467916a88bf9123800575b64736a5d91c6f5b7c85180cac9a221d5da74cb7
-  data.tar.gz: f5de9f6dbab7639d2eb66e77ce612eb5d7e60882ceea0277ece05768a04d81d8
+  metadata.gz: 2a6ab1feb1aafc91509881b72df5b6e7212a9588345ae39576afee47bfb1c614
+  data.tar.gz: 8a4275e5a82653c736539ef8c5650e1a7e11ac1c231be7561470fafd9943e54c
 SHA512:
-  metadata.gz: d6e665134c70908195e3e666427e7ade9349ee39a92c245c6c6ee8afa12e7c1a0347d621cad6f11cacf93f499546fe549f674a0f4c6adb20c1370230660fa81d
-  data.tar.gz: 59436f79df401f5b7b69bb4d1b8bf96d94b2657ff0a75b9616bfa059301fabe3465795ddbfbefbfdd6d429dcc721b5738d4871dc06862470ae28083dfd196b31
+  metadata.gz: 5dbaa9f8c0ed4d6ded4e164436062c2a919c2fe42a81da97d993785f6298963a34241cdf01900fb7d3a24eee1bd2f23844cab1764c1e1507d455793a4e85a60b
+  data.tar.gz: ad7d51c9fbd2c6751974d4cf8591f59c673b3ddf420cf6ce22d7fd60e4f62d1b7e028cc5647c3ac13867bf4f5a4c3ea0a275c9f34c1c9bd13ec62c09a3cc9854

data/README.md

@@ -1,24 +1,64 @@
+
+![regent_light](https://github.com/user-attachments/assets/62564dac-b8d7-4dc0-9b63-64c6841b5872)
+
 # Regent
+**Regent** is library for building AI agents with Ruby.
+
+> [!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.
 
-TODO: Delete this and the text below, and describe your gem
+## Showcase
+A basic Regnt Agent extended with a `price_tool` that allows for retrieving cryptocurrency prices from coingecko.com.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/regent`. To experiment with that code, run `bin/console` for an interactive prompt.
+![screencast 2024-12-25 21-53-47](https://github.com/user-attachments/assets/4e65b731-bbd7-4732-b157-b705d35a7824)
 
-## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Install
 
-Install the gem and add to the application's Gemfile by executing:
+```bash
+gem install regent
+```
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+or add regent to the Gemfile:
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+```ruby
+gem 'regent'
+```
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+and run
+
+```bash
+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:
+
+```ruby
+class WeatherTool < Regent::Tool
+  def call(location)
+    # implementation of a call to weather API
+  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])
+```
 
-TODO: Write usage instructions here
+Simply run an execute function, passing your query as an argument
+``` ruby
+agent.execute("What is the weather in London today?")
+```
 
 ## Development
 
@@ -28,8 +68,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/regent. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/regent/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/alchaplinsky/regent. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/alchaplinsky/regent/blob/main/CODE_OF_CONDUCT.md).
 
 ## Code of Conduct
 
-Everyone interacting in the Regent project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/regent/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Regent project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/alchaplinsky/regent/blob/main/CODE_OF_CONDUCT.md).

data/lib/regent/agent.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Regent
+  class Agent
+    include Concerns::Identifiable
+
+    DEFAULT_MAX_ITERATIONS = 10
+
+    def initialize(llm:, tools: [], **options)
+      super()
+
+      @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
+
+    def execute(task)
+      raise ArgumentError, "Task cannot be empty" if task.to_s.strip.empty?
+
+      start_session
+      react.reason(task)
+    ensure
+      complete_session
+    end
+
+    def running?
+      session&.active? || false
+    end
+
+    def session
+      @sessions.last
+    end
+
+    private
+
+    def start_session
+      complete_session
+      @sessions << Session.new
+      session.start
+    end
+
+    def complete_session
+      session&.complete if running?
+    end
+
+    def react
+      Regent::Engine::React.new(llm, tools, session, @max_iterations)
+    end
+  end
+end

data/lib/regent/concerns/durationable.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Regent
+  module Concerns
+    module Durationable
+      def duration
+        return 0 unless @start_time
+
+        (@end_time || Time.now) - @start_time
+      end
+    end
+  end
+end

data/lib/regent/concerns/identifiable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Regent
+  module Concerns
+    module Identifiable
+      def self.included(base)
+        base.class_eval do
+          attr_reader :id
+        end
+      end
+
+      private
+
+      def generate_id
+        @id = SecureRandom.uuid
+      end
+
+      def initialize(*)
+        generate_id
+        super
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Regent
+  module Engine
+    class React
+      module PromptTemplate
+        def self.system_prompt(tool_names)
+          <<~PROMPT
+            You are assisstant reasoning step-by-step to solve complex problems.
+            Your reasoning process happens in a loop of Though, 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..
+            Observation - is the result of running a tool.
+
+            ## Available tools:
+            #{tool_names}
+
+            ## Example session
+            Question: What is the weather in London today?
+            Thought: I need to get the wether in London
+            Action: weather_tool | "London"
+            PAUSE
+
+            You will have a response with Observation:
+            Observation: It is 32 degress and Sunny
+
+            ... (this Thought/Action/Observation can repeat N times)
+
+            Thought: I know the final answer
+            Answer: It is 32 degress and Sunny in London
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/regent/engine/react.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Regent
+  module Engine
+    class React
+      SEQUENCES = {
+        answer: "Answer:",
+        action: "Action:",
+        observation: "Observation:",
+        stop: "PAUSE"
+      }.freeze
+
+      def initialize(llm, toolchain, session, max_iterations)
+        @llm = llm
+        @toolchain = toolchain
+        @session = session
+        @max_iterations = max_iterations
+      end
+
+      attr_reader :llm, :toolchain, :session, :max_iterations
+
+      def reason(task)
+        initialize_session(task)
+
+        max_iterations.times do |i|
+          content = get_llm_response
+          session.add_message({role: :assistant, content: content })
+          return extract_answer(content) if answer_present?(content)
+
+          if action_present?(content)
+            tool, argument = parse_action(content)
+            return unless tool
+
+            process_tool_execution(tool, argument)
+          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(toolchain.to_s)})
+        session.add_message({role: :user, content: task})
+        session.exec(Span::Type::INPUT, 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]] })
+
+          # 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
+        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
+
+      def action_present?(content)
+        content.include?(SEQUENCES[:action])
+      end
+
+      def success_answer(content)
+        session.exec(Span::Type::ANSWER, 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 }
+      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]
+      end
+
+      def parse_tool_signature(content)
+        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('"', '')
+
+        # Handle cases where argument is nil, empty, or only whitespace
+        argument = nil if argument.nil? || argument.empty?
+
+        [tool_name, argument]
+      rescue
+        [nil, nil]
+      end
+    end
+  end
+end

data/lib/regent/logger.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Regent
+  class Logger
+    COLORS = %i[dim green yellow red blue cyan clear].freeze
+
+    def initialize
+      @pastel = Pastel.new
+      @spinner = build_spinner(spinner_symbol)
+      @nested_spinner = build_spinner("#{dim(" ├──")}#{spinner_symbol}")
+    end
+
+    attr_reader :spinner, :nested_spinner
+
+    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
+
+    def start(**args)
+      info(**args).auto_spin
+    end
+
+    def success(**args)
+      info(**args).success
+    end
+
+    def error(**args)
+      info(**args).error
+    end
+
+    private
+
+    def format_message(label, message, duration, type, meta)
+      parts = []
+      parts << "#{dim("[")}#{cyan(label)}"
+      parts << "#{dim(" ❯")} #{yellow(type)}" if type
+      parts << dim("]")
+      parts << dim("[#{meta}]") if meta
+      parts << dim("[#{duration.round(2)}s]") if duration
+      parts << dim(":")
+      parts << clear(" #{message}")
+
+      parts.join
+    end
+
+    def spinner_symbol
+      "#{dim("[")}#{green(":spinner")}#{dim("]")}"
+    end
+
+    def build_spinner(spinner_format)
+      TTY::Spinner.new("#{spinner_format} :title", format: :dots)
+    end
+
+    COLORS.each do |color|
+      define_method(color) do |message|
+        @pastel.send(color, message)
+      end
+    end
+  end
+end

data/lib/regent/session.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Regent
+  class Session
+    include Concerns::Identifiable
+    include Concerns::Durationable
+
+    class SessionError < StandardError; end
+    class InactiveSessionError < SessionError; end
+    class AlreadyStartedError < SessionError; end
+
+    def initialize
+      super()
+
+      @spans = []
+      @messages = []
+      @start_time = nil
+      @end_time = nil
+    end
+
+    attr_reader :id, :spans, :messages, :start_time, :end_time
+
+    # Starts the session
+    # @raise [AlreadyStartedError] if session is already started
+    # @return [void]
+    def start
+      raise AlreadyStartedError, "Session already started" if @start_time
+
+      @start_time = Time.now.freeze
+    end
+
+    # Executes a new span in the session
+    # @param type [Symbol, String] The type of span
+    # @param options [Hash] Options for the span
+    # @raise [InactiveSessionError] if session is not active
+    # @return [String] The output of the span
+    def exec(type, options = {}, &block)
+      raise InactiveSessionError, "Cannot execute span in inactive session" unless active?
+
+      @spans << Span.new(type: type, arguments: options)
+      current_span.run(&block)
+    end
+
+    # Replays the session
+    # @return [String] The result of the session
+    def replay
+      spans.each { |span| span.replay }
+      result
+    end
+
+    # Completes the session and returns the result
+    # @return [Object] The result of the last span
+    # @raise [InactiveSessionError] if session is not active
+    # @return [String] The result of the last span
+    def complete
+      raise InactiveSessionError, "Cannot complete inactive session" unless active?
+
+      @end_time = Time.now.freeze
+      result
+    end
+
+    # @return [Span, nil] The current span or nil if no spans exist
+    def current_span
+      @spans.last
+    end
+
+    # @return [String, nil] The output of the current span or nil if no spans exist
+    def result
+      current_span&.output
+    end
+
+    # @return [Boolean] Whether the session is currently active
+    def active?
+      start_time && end_time.nil?
+    end
+
+    # Adds a message to the session
+    # @param message [String] The message to add
+    # @raise [ArgumentError] if message is nil or empty
+    def add_message(message)
+      raise ArgumentError, "Message cannot be nil or empty" if message.nil? || message.empty?
+
+      @messages << message
+    end
+  end
+end

data/lib/regent/span.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Regent
+  class Span
+    include Concerns::Identifiable
+    include Concerns::Durationable
+
+    module Type
+      INPUT = 'INPUT'.freeze
+      LLM_CALL = 'LLM'.freeze
+      TOOL_EXECUTION = 'TOOL'.freeze
+      MEMORY_ACCESS = 'MEMO'.freeze
+      ANSWER = 'ANSWER'.freeze
+
+      def self.all
+        constants.map { |c| const_get(c) }
+      end
+
+      def self.valid?(type)
+        all.include?(type)
+      end
+    end
+
+    # @param type [String] The type of span (must be one of Type.all)
+    # @param arguments [Hash] Arguments for the span
+    # @param logger [Logger] Logger instance
+    def initialize(type:, arguments:, logger: Logger.new)
+      super()
+
+      validate_type!(type)
+
+      @logger = logger
+      @type = type
+      @arguments = arguments
+      @meta = nil
+      @output = nil
+    end
+
+    attr_reader :name, :arguments, :output, :type, :start_time, :end_time
+
+    # @raise [ArgumentError] if block is not given
+    # @return [String] The output of the span
+    def run
+      @output = log_operation do
+        yield
+      rescue StandardError => e
+        logger.error(label: type, message: e.message, **arguments)
+        raise
+      end
+    end
+
+    # @return [String] The output of the span
+    def replay
+      log_operation(live: false) { @output }
+    end
+
+    # @return [Boolean] Whether the span is currently running
+    def running?
+      @start_time && @end_time.nil?
+    end
+
+    # @return [Boolean] Whether the span is completed
+    def completed?
+      @start_time && @end_time
+    end
+
+    # @param value [String] The meta value to set
+    def set_meta(value)
+      @meta = value.freeze
+    end
+
+    private
+
+    attr_reader :logger, :meta
+
+    def validate_type!(type)
+      raise InvalidSpanType, "Invalid span type: #{type}" unless Type.valid?(type)
+    end
+
+    def log_operation(live: true, &block)
+      @start_time = live ? Time.now.freeze : @start_time
+      logger.start(label: type, **arguments)
+
+      result = yield
+
+      @end_time = live ? Time.now.freeze : @end_time
+      logger.success(label: type, **({ duration: duration.round(2), meta: meta }.merge(arguments)))
+
+      result
+    end
+  end
+end

data/lib/regent/tool.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Regent
+  class Tool
+    def initialize(name:, description:)
+      @name = name
+      @description = description
+    end
+
+    attr_reader :name, :description
+
+    def call(argument)
+      raise NotImplementedError, "Tool #{name} has not implemented the execute method"
+    end
+
+    def to_s
+      "#{name} - #{description}"
+    end
+  end
+end

data/lib/regent/toolchain.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Regent
+  class Toolchain
+    def initialize(tools)
+      @tools = tools
+    end
+
+    attr_reader :tools
+
+    def find(name)
+      tools.find { |tool| tool.name.downcase == name.downcase }
+    end
+
+    def to_s
+      tools.map(&:to_s).join("\n")
+    end
+  end
+end

data/lib/regent/version.rb

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

data/lib/regent.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
-require_relative "regent/version"
+require 'securerandom'
+require 'pastel'
+require 'tty-spinner'
+require 'zeitwerk'
 
 module Regent
   class Error < StandardError; end
   # Your code goes here...
+
+  loader = Zeitwerk::Loader.for_gem
+  loader.setup
 end

metadata

@@ -1,15 +1,85 @@
 --- !ruby/object:Gem::Specification
 name: regent
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alex Chaplinsky
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-18 00:00:00.000000000 Z
-dependencies: []
+date: 2024-12-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.3
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
 description: Write a longer description or delete this line.
 email:
 - alchaplinsky@gmail.com
@@ -24,6 +94,16 @@ files:
 - README.md
 - Rakefile
 - lib/regent.rb
+- lib/regent/agent.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/logger.rb
+- lib/regent/session.rb
+- lib/regent/span.rb
+- lib/regent/tool.rb
+- lib/regent/toolchain.rb
 - lib/regent/version.rb
 - sig/regent.rbs
 homepage: https://github.com/alchaplinsky/regent