foobara-agent 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7288308d62332addbe98233f7652d718b16f496b02a632426c418642959c5aa4
-  data.tar.gz: 2da140d10bf62e8858de3d5f77c732a0295a4179dfa22e3ddb2c3becf7421029
+  metadata.gz: fc0affa9f2a80a45d94dbcde1ad4ba5f173d0e3aa91076d91147058e5e1c6829
+  data.tar.gz: 40f0e2ed19b6e95a0b325e54eb624b15d3cde7eeda9cfe325626bee5a347f001
 SHA512:
-  metadata.gz: 830b3932828ccb30587c64214425f7b4eea862f5deec5c6a9a8d2a8d80733720b66e0d73f936444d91f5dffa6b7f27d8736638c000e17d2caa37cbff477fe6d2
-  data.tar.gz: cd9e89b6dc3dc81f2bd71ed5d6269f7dc8268d950bb120508c8295d1b89b64cd345d79fec8aa2f85cba0945e534e5fc62305ca070f78490f5c3f0303bf72f011
+  metadata.gz: 716dbb353942408388d6a8e28f87c54911f44d067f398d8c224bbed7e926adc63eae816cea9d40f5acd7ccab478421319c542d2d28e9451996775fcd6ec5f9e7
+  data.tar.gz: 0e80baab41484b2843ddbbe49a1a9412cce157ed43758af7f621f8dc7c99d94d02e0767b92cbe069d5396373e561ee03da4b510e94cb1ddcc86b738b413d203c

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.0.4] - 2025-05-30
+
+- Refactor agent to be a command connector
+
+## [0.0.3] - 2025-05-30
+
+- Increase the retries, attempt to improve command descriptions,
+  and attempt to improve the information stored in the context/command log
+- Add some safeguards around changing the result type too late in the process
+- Add an agent state machine and a kill! method
+
+## [0.0.2] - 2025-05-27
+
+- Add maximum_call_count option
+- Try getting the command and inputs together to reduce calls
+- Tweaks to algorithms and improvements to what is stored in context/command_log
+
 ## [0.0.1] - 2025-05-21
 
 - Initial release

data/lib/foobara/agent.rb

@@ -3,7 +3,7 @@ require "foobara/ai"
 require "foobara/command_connectors"
 
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     foobara_domain!
 
     foobara_depends_on Foobara::Ai::AnswerBot

data/src/foobara/agent/accomplish_goal.rb

@@ -2,7 +2,7 @@ require_relative "list_commands"
 
 module Foobara
   # TODO: should agent maybe be a command connector? It feels a bit more like a command connector.
-  class Agent
+  class Agent < CommandConnector
     class AccomplishGoal < Foobara::Command
       possible_error :gave_up, context: { reason: :string }, message: "Gave up."
       possible_error :too_many_command_calls,
@@ -62,7 +62,8 @@ module Foobara
           connect_agent_commands
         end
 
-        until mission_accomplished or given_up or timed_out
+        until mission_accomplished or given_up
+          check_if_too_many_calls
           if choose_next_command_and_next_inputs_separately?
             determine_next_command_then_inputs_separately
           else
@@ -71,7 +72,6 @@ module Foobara
 
           run_next_command
           log_last_command_outcome
-          check_if_too_many_calls
         end
 
         if given_up
@@ -115,19 +115,17 @@ module Foobara
         @command_connector ||= existing_command_connector
       end
 
+      # Do we really want to support calling AccomplishGoal outside the context of an Agent?
+      # If not, just delete this awkward coupling
       def build_command_connector
-        self.command_connector ||= Connector.new(
-          accomplish_goal_command: self,
-          default_serializers: [
-            Foobara::CommandConnectors::Serializers::ErrorsSerializer,
-            Foobara::CommandConnectors::Serializers::AtomicSerializer
-          ],
+        self.command_connector ||= Agent.new(
+          current_accomplish_goal_command: self,
           llm_model:
         )
       end
 
       def set_accomplished_goal_command
-        command_connector.accomplish_goal_command = self
+        command_connector.current_accomplish_goal_command = self
       end
 
       def connect_agent_commands
@@ -140,7 +138,7 @@ module Foobara
         end
       end
 
-      def determine_next_command_and_inputs(retries = 1)
+      def determine_next_command_and_inputs(retries = 2)
         if context.command_log.empty?
           self.next_command_name = ListCommands.full_command_name
           self.next_command_inputs = nil
@@ -157,7 +155,13 @@ module Foobara
 
         determine_command = DetermineNextCommandNameAndInputs.new(inputs_for_determine)
 
-        outcome = determine_command.run
+        outcome = begin
+          determine_command.run
+        rescue CommandPatternImplementation::Concerns::Result::CouldNotProcessResult => e
+          # :nocov:
+          Outcome.errors(e.errors)
+          # :nocov:
+        end
 
         if outcome.success?
           self.next_command_name = outcome.result[:command_name]
@@ -182,7 +186,8 @@ module Foobara
                 log_command_outcome(
                   command: determine_command,
                   inputs: determine_command.inputs.except(:context),
-                  outcome:
+                  outcome:,
+                  result: outcome.result || determine_command.raw_result
                 )
 
                 determine_next_command_inputs
@@ -194,7 +199,8 @@ module Foobara
             log_command_outcome(
               command: determine_command,
               inputs: determine_command.inputs&.except(:context),
-              outcome:
+              outcome:,
+              result: outcome.result || determine_command.raw_result
             )
 
             if retries > 0
@@ -207,7 +213,8 @@ module Foobara
           log_command_outcome(
             command_name: determine_command.class.full_command_name,
             inputs: determine_command.inputs&.except(:context),
-            outcome:
+            outcome:,
+            result: outcome.result || determine_command.raw_result
           )
 
           if retries > 0
@@ -258,7 +265,7 @@ module Foobara
         @command_name_type ||= Agent.foobara_type_from_declaration(:string, one_of: all_command_classes)
       end
 
-      def determine_next_command_name(retries = 1)
+      def determine_next_command_name(retries = 2)
         self.next_command_name = if context.command_log.empty?
                                    ListCommands.full_command_name
                                  elsif delayed_command_name
@@ -276,13 +283,20 @@ module Foobara
                                    end
 
                                    command = command_class.new(inputs)
-                                   outcome = command.run
+                                   outcome = begin
+                                     command.run
+                                   rescue CommandPatternImplementation::Concerns::Result::CouldNotProcessResult => e
+                                     # :nocov:
+                                     Outcome.errors(e.errors)
+                                     # :nocov:
+                                   end
 
                                    if outcome.success?
                                      if log_successful_determine_command_and_inputs_outcomes?
                                        log_command_outcome(
                                          command:,
-                                         inputs: command.inputs.except(:context)
+                                         inputs: command.inputs.except(:context),
+                                         outcome:
                                        )
                                      end
                                    else
@@ -290,7 +304,9 @@ module Foobara
                                      # :nocov:
                                      log_command_outcome(
                                        command:,
-                                       inputs: command.inputs.except(:context)
+                                       inputs: command.inputs.except(:context),
+                                       outcome:,
+                                       result: outcome.result || command.raw_result
                                      )
 
                                      if retries > 0
@@ -318,7 +334,7 @@ module Foobara
         self.next_command_class = command_connector.transformed_command_from_name(next_command_name)
       end
 
-      def determine_next_command_inputs(retries = 1)
+      def determine_next_command_inputs(retries = 2)
         self.next_command_inputs = if next_command_has_inputs?
                                      command_class = command_class_for_determine_inputs_for_next_command
 
@@ -328,13 +344,20 @@ module Foobara
                                      end
 
                                      command = command_class.new(inputs)
-                                     outcome = command.run
+                                     outcome = begin
+                                       command.run
+                                     rescue CommandPatternImplementation::Concerns::Result::CouldNotProcessResult => e
+                                       # :nocov:
+                                       Outcome.errors(e.errors)
+                                       # :nocov:
+                                     end
 
                                      if outcome.success?
                                        if log_successful_determine_command_and_inputs_outcomes?
                                          log_command_outcome(
                                            command:,
-                                           inputs: command.inputs.except(:context)
+                                           inputs: command.inputs.except(:context),
+                                           outcome:
                                          )
                                        end
                                      else
@@ -342,7 +365,9 @@ module Foobara
                                        # :nocov:
                                        log_command_outcome(
                                          command:,
-                                         inputs: command.inputs.except(:context)
+                                         inputs: command.inputs.except(:context),
+                                         outcome:,
+                                         result: outcome.result || command.raw_result
                                        )
                                        if retries > 0
                                          return determine_next_command_inputs(retries - 1)
@@ -409,11 +434,13 @@ module Foobara
           outcome_hash[:errors_hash] = outcome.errors_hash
         end
 
-        context.command_log << CommandLogEntry.new(
+        log_entry = CommandLogEntry.new(
           command_name:,
           inputs:,
           outcome: outcome_hash
         )
+
+        context.command_log << log_entry
       end
 
       # TODO: these are awkwardly called from outside. Come up with a better solution.

data/src/foobara/agent/concerns/subclass_cacheable.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     module Concerns
       # There's nothing really subclass-specific about this concern, maybe rename it...
       module SubclassCacheable

data/src/foobara/agent/connector/set_command_connector_inputs_transformer.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class SetCommandConnectorInputsTransformer < TypeDeclarations::TypedTransformer
       class << self
         attr_accessor :command_connector

data/src/foobara/agent/describe_command.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class DescribeCommand < Foobara::Command
       inputs do
         command_connector :duck, :required, "Connector to find relevant command in"
@@ -52,7 +52,7 @@ module Foobara
       end
 
       def mark_command_as_described
-        command_connector.accomplish_goal_command.described_commands << command_class.full_command_name
+        command_connector.current_accomplish_goal_command.described_commands << command_class.full_command_name
       end
     end
   end

data/src/foobara/agent/describe_type.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class DescribeType < Foobara::Command
       inputs do
         command_connector :duck, :required, "Connector to find relevant type in"

data/src/foobara/agent/determine_inputs_for_next_command.rb

@@ -1,7 +1,7 @@
 require "foobara/llm_backed_command"
 
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class DetermineInputsForNextCommand < Foobara::LlmBackedCommand
       extend Concerns::SubclassCacheable
 
@@ -17,7 +17,7 @@ module Foobara
                               "accomplishing the goal."
 
             klass.inputs do
-              goal :string, :required, "What do you want the agent to attempt to accomplish?"
+              goal :string, :required, "The current (possibly already accomplished) goal"
               context Context, :required, "Context of the progress towards the goal so far"
               llm_model :string,
                         one_of: Foobara::Ai::AnswerBot::Types::ModelEnum,

data/src/foobara/agent/determine_next_command.rb

@@ -1,7 +1,7 @@
 require "foobara/llm_backed_command"
 
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class DetermineNextCommand < Foobara::LlmBackedCommand
       extend Concerns::SubclassCacheable
 
@@ -12,8 +12,17 @@ module Foobara
             command_name = "Foobara::Agent::#{agent_id}::DetermineNextCommand"
             klass = Util.make_class_p(command_name, self)
 
+            klass.description "Accepts the current goal, which might already be accomplished, " \
+                              "and context of the work  " \
+                              "so far and returns the name of " \
+                              "the next command to run to make progress towards " \
+                              "accomplishing the goal. If the goal has already been accomplished then choose the " \
+                              "NotifyUserThatCurrentGoalHasBeenAccomplished command."
+
             klass.inputs do
-              goal :string, :required, "What do you want the agent to attempt to accomplish?"
+              goal :string, :required, "The current goal to accomplish. If the goal has already been accomplished " \
+                                       "by the previous command runs then choose " \
+                                       "NotifyUserThatCurrentGoalHasBeenAccomplished to stop the loop."
               context Context, :required, "Context of progress so far"
               llm_model :string,
                         one_of: Foobara::Ai::AnswerBot::Types::ModelEnum,

data/src/foobara/agent/determine_next_command_name_and_inputs.rb

@@ -1,14 +1,18 @@
 require "foobara/llm_backed_command"
 
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class DetermineNextCommandNameAndInputs < Foobara::LlmBackedCommand
-      description "Accepts a goal and context of the work so far and returns the inputs for " \
+      description "Accepts the current goal, which might already be accomplished, and context of the work  " \
+                  "so far and returns the inputs for " \
                   "the next command to run to make progress towards " \
-                  "accomplishing the goal."
+                  "accomplishing the goal. If the goal has already been accomplished then choose the " \
+                  "NotifyUserThatCurrentGoalHasBeenAccomplished command."
 
       inputs do
-        goal :string, :required, "What do you want the agent to attempt to accomplish?"
+        goal :string, :required, "The current goal to accomplish. If the goal has already been accomplished " \
+                                 "by the previous command runs then choose " \
+                                 "NotifyUserThatCurrentGoalHasBeenAccomplished to stop the loop."
         context Context, :required, "Context of the progress towards the goal so far"
         command_class_names [:string], :required
         llm_model :string,

data/src/foobara/agent/give_up.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class GiveUp < Foobara::Command
       inputs do
         command_connector CommandConnector, :required, "Connector to end"

data/src/foobara/agent/list_commands.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class ListCommands < Foobara::Command
       inputs do
         command_connector :duck, :required, "Connector to end"

data/src/foobara/agent/list_types.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class ListTypes < Foobara::Command
       inputs do
         command_connector :duck, :required, "Connector to fetch types from"

data/src/foobara/agent/notify_user_that_current_goal_has_been_accomplished.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class NotifyUserThatCurrentGoalHasBeenAccomplished < Foobara::Command
       extend Concerns::SubclassCacheable
 
@@ -71,6 +71,7 @@ module Foobara
         data = if result_type
                  inputs[:result_data]
                end
+
         command_connector.mark_mission_accomplished(data, message_to_user)
       end
 

data/src/foobara/agent/types/command_log_entry.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class CommandLogEntry < Foobara::Model
       attributes do
         command_name :string, :required, "Name of the command that was run"

data/src/foobara/agent/types/context.rb

@@ -1,5 +1,5 @@
 module Foobara
-  class Agent
+  class Agent < CommandConnector
     class Context < Foobara::Model
       attributes do
         # TODO: why doesn't this default of [] work as expected on newly created models?

data/src/foobara/agent.rb

@@ -1,56 +1,140 @@
 module Foobara
-  class Agent
-    attr_accessor :context, :agent_command_connector, :agent_name, :llm_model
+  class Agent < CommandConnector
+    StateMachine = Foobara::StateMachine.for(
+      [:initialized, :idle, :error, :failure] => {
+        kill: :killed,
+        accomplish_goal: :accomplishing_goal
+      },
+      accomplishing_goal: {
+        goal_accomplished: :idle,
+        goal_errored: :error,
+        goal_failed: :failure,
+        kill: :killed
+      }
+    )
+
+    attr_accessor :context,
+                  :agent_name,
+                  :llm_model,
+                  :current_accomplish_goal_command,
+                  :result_type,
+                  :agent_commands_connected
 
     def initialize(
       context: nil,
       agent_name: nil,
       command_classes: nil,
-      agent_command_connector: nil,
-      llm_model: nil
+      llm_model: nil,
+      result_type: nil,
+      current_accomplish_goal_command: nil,
+      **opts
     )
       # TODO: shouldn't have to pass command_log here since it has a default, debug that
       self.context = context
-      self.agent_command_connector = agent_command_connector
       self.agent_name = agent_name if agent_name
       self.llm_model = llm_model
+      self.result_type = result_type
+      self.current_accomplish_goal_command = current_accomplish_goal_command
+
+      unless opts.key?(:default_serializers)
+        opts = opts.merge(default_serializers: [
+                            Foobara::CommandConnectors::Serializers::ErrorsSerializer,
+                            Foobara::CommandConnectors::Serializers::AtomicSerializer
+                          ])
+      end
+
+      super(**opts)
 
       build_initial_context
-      build_agent_command_connector
 
+      # TODO: push this convenience method up into base class?
       command_classes&.each do |command_class|
-        self.agent_command_connector.connect(command_class)
+        connect(command_class)
+      end
+    end
+
+    def run(*args, **)
+      if args.first.is_a?(::String)
+        accomplish_goal(*args, **)
+      else
+        unless agent_commands_connected?
+          connect_agent_commands
+        end
+
+        super
       end
     end
 
+    def state_machine
+      @state_machine ||= StateMachine.new
+    end
+
+    def kill!
+      state_machine.perform_transition!(:kill)
+    end
+
+    def killed?
+      state_machine.current_state == :killed
+    end
+
     def accomplish_goal(
       goal,
       result_type: nil,
       choose_next_command_and_next_inputs_separately: nil,
       maximum_call_count: nil
     )
-      inputs = {
-        goal:,
-        final_result_type: result_type,
-        current_context: context,
-        existing_command_connector: agent_command_connector,
-        agent_name:
+      if result_type && self.result_type != result_type
+        if self.result_type
+          # :nocov:
+          raise ArgumentError, "You can only specify a result type once"
+          # :nocov:
+        elsif agent_commands_connected?
+          # :nocov:
+          raise ArgumentError, "You can't specify a result type this late in the process"
+          # :nocov:
+        else
+          self.result_type = result_type
+        end
+      end
 
-      }
+      state_machine.perform_transition!(:accomplish_goal)
 
-      if llm_model
-        inputs[:llm_model] = llm_model
-      end
+      begin
+        inputs = {
+          goal:,
+          final_result_type: self.result_type,
+          current_context: context,
+          existing_command_connector: self,
+          agent_name:
+        }
 
-      unless choose_next_command_and_next_inputs_separately.nil?
-        inputs[:choose_next_command_and_next_inputs_separately] = choose_next_command_and_next_inputs_separately
-      end
+        if llm_model
+          inputs[:llm_model] = llm_model
+        end
 
-      unless maximum_call_count.nil?
-        inputs[:maximum_command_calls] = maximum_call_count
-      end
+        unless choose_next_command_and_next_inputs_separately.nil?
+          inputs[:choose_next_command_and_next_inputs_separately] = choose_next_command_and_next_inputs_separately
+        end
+
+        unless maximum_call_count.nil?
+          inputs[:maximum_command_calls] = maximum_call_count
+        end
 
-      AccomplishGoal.run(inputs)
+        self.current_accomplish_goal_command = AccomplishGoal.new(inputs)
+
+        current_accomplish_goal_command.run.tap do |outcome|
+          if outcome.success?
+            state_machine.perform_transition!(:goal_accomplished)
+          else
+            state_machine.perform_transition!(:goal_errored)
+          end
+        end
+      rescue
+        # :nocov:
+        state_machine.perform_transition!(:goal_failed)
+        raise
+        # :nocov:
+      end
     end
 
     def build_initial_context
@@ -58,15 +142,45 @@ module Foobara
       self.context ||= Context.new(command_log: [])
     end
 
-    def build_agent_command_connector
-      self.agent_command_connector ||= Connector.new(
-        accomplish_goal_command: self,
-        llm_model:,
-        default_serializers: [
-          Foobara::CommandConnectors::Serializers::ErrorsSerializer,
-          Foobara::CommandConnectors::Serializers::AtomicSerializer
-        ]
-      )
+    def mark_mission_accomplished(final_result, message_to_user)
+      # TODO: this is a pretty awkward way to communicate between commands hmmm...
+      # maybe see if there's a less hacky way to pull this off.
+      current_accomplish_goal_command.mission_accomplished!(final_result, message_to_user)
+    end
+
+    def give_up(reason)
+      current_accomplish_goal_command.give_up!(reason)
+    end
+
+    def agent_commands_connected?
+      agent_commands_connected
+    end
+
+    def connect_agent_commands(final_result_type: nil, agent_name: nil)
+      command_classes = [
+        DescribeCommand,
+        DescribeType,
+        GiveUp,
+        ListCommands,
+        ListTypes
+      ]
+
+      command_classes << if final_result_type
+                           NotifyUserThatCurrentGoalHasBeenAccomplished.for(
+                             result_type: final_result_type,
+                             agent_id: agent_name
+                           )
+                         else
+                           NotifyUserThatCurrentGoalHasBeenAccomplished
+                         end
+
+      set_command_connector_transformer = SetCommandConnectorInputsTransformer.for(self)
+
+      command_classes.each do |command_class|
+        connect(command_class, inputs: set_command_connector_transformer)
+      end
+
+      self.agent_commands_connected = true
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foobara-agent
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Miles Georgi
@@ -51,7 +51,6 @@ files:
 - src/foobara/agent.rb
 - src/foobara/agent/accomplish_goal.rb
 - src/foobara/agent/concerns/subclass_cacheable.rb
-- src/foobara/agent/connector/connector.rb
 - src/foobara/agent/connector/set_command_connector_inputs_transformer.rb
 - src/foobara/agent/describe_command.rb
 - src/foobara/agent/describe_type.rb

data/src/foobara/agent/connector/connector.rb

@@ -1,59 +0,0 @@
-require "foobara/command_connectors"
-
-module Foobara
-  class Agent
-    class Connector < Foobara::CommandConnector
-      attr_accessor :accomplish_goal_command, :agent_commands_connected, :llm_model
-
-      def initialize(*, accomplish_goal_command:, llm_model: nil, **)
-        self.accomplish_goal_command = accomplish_goal_command
-        self.llm_model = llm_model
-
-        super(*, **)
-      end
-
-      def mark_mission_accomplished(final_result, message_to_user)
-        # TODO: this is a pretty awkward way to communicate between commands hmmm...
-        # maybe see if there's a less hacky way to pull this off.
-        accomplish_goal_command.mission_accomplished!(final_result, message_to_user)
-      end
-
-      def give_up(reason)
-        accomplish_goal_command.give_up!(reason)
-      end
-
-      def agent_commands_connected?
-        agent_commands_connected
-      end
-
-      def connect_agent_commands(final_result_type: nil, agent_name: nil)
-        command_classes = [
-          DescribeCommand,
-          DescribeType,
-          GiveUp,
-          ListCommands,
-          ListTypes
-        ]
-
-        command_classes << if final_result_type
-                             NotifyUserThatCurrentGoalHasBeenAccomplished.for(
-                               result_type: final_result_type,
-                               agent_id: agent_name
-                             )
-                           else
-                             NotifyUserThatCurrentGoalHasBeenAccomplished
-                           end
-
-        command_classes.each do |command_class|
-          connect(command_class, inputs: set_command_connector_transformer)
-        end
-
-        self.agent_commands_connected = true
-      end
-
-      def set_command_connector_transformer
-        @set_command_connector_transformer ||= SetCommandConnectorInputsTransformer.for(self)
-      end
-    end
-  end
-end