foobara-agent 0.0.1

data/src/foobara/agent/accomplish_goal.rb

@@ -0,0 +1,240 @@
+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 AccomplishGoal < Foobara::Command
+      possible_error :gave_up, context: { reason: :string }, message: "Gave up."
+
+      inputs do
+        agent_name :string, "Name of the agent"
+        goal :string, :required, "What do you want the agent to attempt to accomplish?"
+        # TODO: we should be able to specify a subclass as a type
+        command_classes [:duck], "Commands that can be ran to accomplish the goal"
+        final_result_type :duck, "Specifies how the result of the goal is to be structured"
+        existing_command_connector :duck, "A connector containing already-connected commands for the agent to use"
+        current_context :duck, "The current context of the agent"
+        llm_model :string,
+                  :allow_nil,
+                  one_of: Foobara::Ai::AnswerBot::Types::ModelEnum,
+                  default: "claude-3-7-sonnet-20250219",
+                  description: "The model to use for the LLM"
+      end
+
+      result do
+        message_to_user :string, :required, "Message to the user about successfully accomplishing the goal"
+        result_data :duck, "Optional result data to return to the user if final_result_type was given"
+      end
+
+      depends_on ListCommands
+
+      def execute
+        build_initial_context_if_necessary
+
+        if command_connector_passed_in?
+          set_accomplished_goal_command
+        else
+          build_command_connector
+          connect_user_provided_commands
+          connect_agent_commands
+        end
+
+        unless command_connector.agent_commands_connected?
+          connect_agent_commands
+        end
+
+        until mission_accomplished or given_up or timed_out
+          determine_next_command_name
+
+          if command_described?
+            fetch_next_command_class
+            determine_next_command_inputs
+          else
+            choose_describe_command_instead
+            fetch_next_command_class
+          end
+
+          run_next_command
+          log_command_outcome
+        end
+
+        if given_up
+          add_given_up_error
+        end
+
+        build_result
+      end
+
+      def validate
+        validate_either_command_classes_or_connector_given
+      end
+
+      def validate_either_command_classes_or_connector_given
+        # TODO: implement this!
+      end
+
+      attr_accessor :context, :next_command_name, :next_command_inputs, :mission_accomplished, :given_up,
+                    :next_command_class, :next_command, :command_outcome, :timed_out,
+                    :final_result, :final_message, :command_response, :delayed_command_name
+      attr_writer :command_connector
+
+      def agent_name
+        @agent_name ||= inputs[:agent_name] || "Anon#{SecureRandom.hex(2)}"
+      end
+
+      def build_initial_context_if_necessary
+        # TODO: shouldn't have to pass command_log here since it has a default, debug that
+        self.context = current_context || Context.new(command_log: [])
+      end
+
+      def command_connector_passed_in?
+        existing_command_connector
+      end
+
+      def command_connector
+        @command_connector ||= existing_command_connector
+      end
+
+      def build_command_connector
+        self.command_connector ||= Connector.new(
+          accomplish_goal_command: self,
+          default_serializers: [
+            Foobara::CommandConnectors::Serializers::ErrorsSerializer,
+            Foobara::CommandConnectors::Serializers::AtomicSerializer,
+            Foobara::CommandConnectors::Serializers::JsonSerializer
+          ],
+          llm_model:
+        )
+      end
+
+      def set_accomplished_goal_command
+        command_connector.accomplish_goal_command = self
+      end
+
+      def connect_agent_commands
+        command_connector.connect_agent_commands(final_result_type:, agent_name:)
+      end
+
+      def connect_user_provided_commands
+        command_classes.each do |command_class|
+          command_connector.connect(command_class)
+        end
+      end
+
+      def determine_next_command_name
+        self.next_command_name = if context.command_log.empty?
+                                   ListCommands.full_command_name
+                                 elsif delayed_command_name
+                                   name = delayed_command_name
+                                   self.delayed_command_name = nil
+                                   name
+                                 else
+                                   command_class = DetermineNextCommand.for(
+                                     command_class_names: all_command_classes, agent_id: agent_name
+                                   )
+
+                                   inputs = { goal:, context: }
+                                   if llm_model
+                                     inputs[:llm_model] = llm_model
+                                   end
+
+                                   command_class.run!(inputs)
+                                 end
+      end
+
+      def choose_describe_command_instead
+        self.delayed_command_name = next_command_name
+        self.next_command_inputs = { command_name: next_command_name }
+        self.next_command_name = DescribeCommand.full_command_name
+      end
+
+      def all_command_classes
+        @all_command_classes ||= run_subcommand!(ListCommands, command_connector:).values.flatten
+      end
+
+      def fetch_next_command_class
+        self.next_command_class = command_connector.transformed_command_from_name(next_command_name)
+      end
+
+      def determine_next_command_inputs
+        type = next_command_class.inputs_type
+
+        self.next_command_inputs = if type && !empty_attributes?(type)
+                                     command_class = DetermineInputsForNextCommand.for(
+                                       command_class: next_command_class, agent_id: agent_name
+                                     )
+
+                                     inputs = { goal:, context: }
+                                     if llm_model
+                                       inputs[:llm_model] = llm_model
+                                     end
+
+                                     command_class.run!(inputs)
+                                   end
+      end
+
+      def run_next_command
+        self.command_response = command_connector.run(
+          full_command_name: next_command_name,
+          inputs: next_command_inputs,
+          action: "run"
+        )
+
+        self.command_outcome = command_response.outcome
+      end
+
+      def log_command_outcome
+        outcome_hash = { success: command_outcome.success? }
+
+        if command_outcome.success?
+          outcome_hash[:result] = command_response.body
+        else
+          # :nocov:
+          outcome_hash[:errors_hash] = command_response.body
+          # :nocov:
+        end
+
+        context.command_log << CommandLogEntry.new(
+          command_name: next_command_name,
+          inputs: next_command_inputs,
+          outcome: outcome_hash
+        )
+      end
+
+      # TODO: these are awkwardly called from outside. Come up with a better solution.
+      def mission_accomplished!(final_result, message)
+        self.mission_accomplished = true
+        self.final_result = final_result
+        self.final_message = message
+      end
+
+      def give_up!(message)
+        self.given_up = true
+        self.final_message = message
+      end
+
+      def add_given_up_error
+        add_runtime_error(:gave_up, reason: final_message)
+      end
+
+      def build_result
+        {
+          message_to_user: final_message,
+          result_data: final_result
+        }
+      end
+
+      def command_described?
+        described_commands.include?(next_command_name)
+      end
+
+      def described_commands
+        @described_commands ||= Set.new
+      end
+
+      def empty_attributes?(type)
+        type.extends_type?(BuiltinTypes[:attributes]) && type.element_types.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+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
+                             EndSessionBecauseGoalHasBeenAccomplished.for(
+                               result_type: final_result_type,
+                               agent_id: agent_name
+                             )
+                           else
+                             EndSessionBecauseGoalHasBeenAccomplished
+                           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

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

@@ -0,0 +1,28 @@
+module Foobara
+  class Agent
+    class SetCommandConnectorInputsTransformer < TypeDeclarations::TypedTransformer
+      class << self
+        attr_accessor :command_connector
+
+        def for(command_connector)
+          Class.new(self).tap do |subclass|
+            subclass.command_connector = command_connector
+          end
+        end
+      end
+
+      def command_connector
+        self.class.command_connector
+      end
+
+      def from_type_declaration
+        to_declaration = to_type.declaration_data
+        TypeDeclarations::Attributes.reject(to_declaration, :command_connector)
+      end
+
+      def transform(inputs)
+        inputs.merge(command_connector:)
+      end
+    end
+  end
+end

data/src/foobara/agent/describe_command.rb

@@ -0,0 +1,59 @@
+module Foobara
+  class Agent
+    class DescribeCommand < Foobara::Command
+      inputs do
+        command_connector :duck, :required, "Connector to find relevant command in"
+        command_name :string, :required, "Name of the command to describe"
+      end
+
+      result :duck, description: "Information about the command"
+
+      def execute
+        find_command_class
+
+        set_command_name
+        set_description
+        set_inputs_type
+        set_result_type
+
+        mark_command_as_described
+
+        command_description
+      end
+
+      attr_accessor :command_class
+
+      def find_command_class
+        self.command_class = command_connector.transformed_command_from_name(command_name)
+      end
+
+      def command_description
+        @command_description ||= {}
+      end
+
+      def set_command_name
+        command_description[:full_command_name] = command_class.full_command_name
+      end
+
+      def set_description
+        command_description[:description] = command_class.description
+      end
+
+      def set_inputs_type
+        if command_class.inputs_type
+          command_description[:inputs_type] = JsonSchemaGenerator.to_json_schema(command_class.inputs_type)
+        end
+      end
+
+      def set_result_type
+        if command_class.result_type
+          command_description[:result_type] = JsonSchemaGenerator.to_json_schema(command_class.result_type)
+        end
+      end
+
+      def mark_command_as_described
+        command_connector.accomplish_goal_command.described_commands << command_class.full_command_name
+      end
+    end
+  end
+end

data/src/foobara/agent/describe_type.rb

@@ -0,0 +1,39 @@
+module Foobara
+  class Agent
+    class DescribeType < Foobara::Command
+      inputs do
+        command_connector :duck, :required, "Connector to find relevant type in"
+        type_name :string, :required, "Name of the type to describe"
+      end
+
+      result :duck, description: "Information about the type"
+
+      def execute
+        find_type
+
+        set_type_name
+        set_json_schema
+
+        type_description
+      end
+
+      attr_accessor :type
+
+      def find_type
+        self.type = command_connector.command_registry.foobara_lookup_type(type_name)
+      end
+
+      def type_description
+        @type_description ||= {}
+      end
+
+      def set_type_name
+        type_description[:full_type_name] = type.scoped_full_name
+      end
+
+      def set_json_schema
+        type_description[:json_schema] = JsonSchemaGenerator.to_json_schema(type)
+      end
+    end
+  end
+end

data/src/foobara/agent/determine_inputs_for_next_command.rb

@@ -0,0 +1,75 @@
+require "foobara/llm_backed_command"
+
+module Foobara
+  class Agent
+    class DetermineInputsForNextCommand < Foobara::LlmBackedCommand
+      class << self
+        attr_accessor :command_class
+
+        def command_cache
+          @command_cache ||= {}
+        end
+
+        def clear_cache
+          @command_cache = nil
+        end
+
+        def cached_command(agent_id, full_command_name)
+          key = [agent_id, full_command_name]
+
+          if command_cache.key?(key)
+            command_cache[key]
+          else
+            command_cache[key] = yield
+          end
+        end
+
+        def for(command_class:, agent_id:)
+          cached_command(agent_id, command_class.full_command_name) do
+            command_short_name = Util.non_full_name(command_class.command_name)
+            class_name = "Foobara::Agent::#{agent_id}::DetermineInputsForNext#{command_short_name}Command"
+            klass = Util.make_class_p(class_name, self)
+
+            klass.command_class = command_class
+
+            klass.description "Accepts a goal and context of the work so far and returns the inputs for " \
+                              "the next #{command_short_name} command to run to make progress towards " \
+                              "accomplishing the goal."
+
+            klass.inputs do
+              goal :string, :required, "What do you want the agent to attempt to accomplish?"
+              context Context, :required, "Context of the progress towards the goal so far"
+              llm_model :string,
+                        one_of: Foobara::Ai::AnswerBot::Types::ModelEnum,
+                        default: "claude-3-7-sonnet-20250219",
+                        description: "The model to use for the LLM"
+            end
+
+            if command_class.inputs_type
+              klass.result command_class.inputs_type
+            end
+
+            klass
+          end
+        end
+      end
+
+      description "Accepts a goal and context of the work so far and returns the inputs for the next command to " \
+                  "run to make progress towards accomplishing the mission."
+
+      inputs do
+        goal :string, :required, "What do you want the agent to attempt to accomplish?"
+        context Context, :required, "Context of the current mission so far"
+        command_class :duck, :required, "Command to run to accomplish the goal"
+        llm_model :string,
+                  one_of: Foobara::Ai::AnswerBot::Types::ModelEnum,
+                  default: "claude-3-7-sonnet-20250219",
+                  description: "The model to use for the LLM"
+      end
+
+      result :duck,
+             description: "Inputs to pass to the next command to run to make progress " \
+                          "towards accomplishing the mission."
+    end
+  end
+end

data/src/foobara/agent/determine_next_command.rb

@@ -0,0 +1,67 @@
+require "foobara/llm_backed_command"
+
+module Foobara
+  class Agent
+    class DetermineNextCommand < Foobara::LlmBackedCommand
+      class << self
+        attr_accessor :command_class_names
+
+        def command_cache
+          @command_cache ||= {}
+        end
+
+        def clear_cache
+          @command_cache = nil
+        end
+
+        def cached_command(agent_id)
+          if command_cache.key?(agent_id)
+            command_cache[agent_id]
+          else
+            command_cache[agent_id] = yield
+          end
+        end
+
+        def for(command_class_names:, agent_id:)
+          cached_command(agent_id) do
+            command_name = "Foobara::Agent::#{agent_id}::DetermineNextCommand"
+            klass = Util.make_class_p(command_name, self)
+
+            klass.command_class_names = command_class_names
+
+            klass.inputs do
+              goal :string, :required, "What do you want the agent to attempt to accomplish?"
+              context Context, :required, "Context of the current mission so far"
+              llm_model :string,
+                        one_of: Foobara::Ai::AnswerBot::Types::ModelEnum,
+                        default: "claude-3-7-sonnet-20250219",
+                        description: "The model to use for the LLM"
+            end
+
+            klass.result :string,
+                         one_of: command_class_names,
+                         description: "Name of the next command to run to make progress " \
+                                      "towards accomplishing the mission"
+
+            klass
+          end
+        end
+      end
+
+      description "Accepts a goal and context of the work so far and returns the name of the next command to run to " \
+                  "make progress towards accomplishing the mission. Make sure you have called DescribeCommand the" \
+                  "command first so that you will know how to construct its inputs in the next step."
+
+      inputs do
+        goal :string, :required, "What do you want the agent to attempt to accomplish?"
+        context Context, :required, "Context of the current mission so far"
+        llm_model :string,
+                  one_of: Foobara::Ai::AnswerBot::Types::ModelEnum,
+                  default: "claude-3-7-sonnet-20250219",
+                  description: "The model to use for the LLM"
+      end
+
+      result :string, description: "Name of the next command to run to make progress towards accomplishing the mission."
+    end
+  end
+end

data/src/foobara/agent/end_session_because_goal_has_been_accomplished.rb

@@ -0,0 +1,99 @@
+module Foobara
+  class Agent
+    class EndSessionBecauseGoalHasBeenAccomplished < Foobara::Command
+      class << self
+        attr_accessor :command_class
+
+        def command_cache
+          @command_cache ||= {}
+        end
+
+        def clear_cache
+          @command_cache = nil
+        end
+
+        def cached_command(agent_id, result_type)
+          key = [agent_id, result_type]
+
+          if command_cache.key?(key)
+            # :nocov:
+            command_cache[key]
+            # :nocov:
+          else
+            command_cache[key] = yield
+          end
+        end
+
+        def for(result_type:, agent_id:)
+          cached_command(agent_id, result_type) do
+            command_name = "Foobara::Agent::#{agent_id}::EndSessionBecauseGoalHasBeenAccomplished"
+            klass = Util.make_class_p(command_name, self)
+
+            klass.description "Ends the session giving a final result formatted according to the " \
+                              "result schema if relevant and an optional message to the user."
+
+            inputs do
+              # TODO: Are we still not able to uses classes as foobara types??
+              command_connector :duck, :required, "Connector to end"
+              message_to_user :string, "Optional message to the user"
+            end
+
+            if result_type
+              add_inputs do
+                result_data(*result_type)
+              end
+
+              klass.result do
+                message_to_user :string
+                result_data(*result_type)
+              end
+
+              klass.description "Ends the session giving a final result formatted according to the " \
+                                "result schema and an optional message to the user."
+            else
+              # TODO: test this code path
+              # :nocov:
+              klass.description "Ends the session giving an optional message to the user."
+              # :nocov:
+            end
+
+            klass
+          end
+        end
+      end
+
+      description "Ends the session giving a final result formatted according to the " \
+                  "result schema if relevant and an optional message to the user."
+
+      inputs do
+        # TODO: Are we still not able to uses classes as foobara types??
+        command_connector :duck, :required, "Connector to end"
+        message_to_user :string, "Optional message to the user"
+        result_data :duck, "The final result of the work if relevant/expected"
+      end
+
+      def execute
+        mark_mission_accomplished
+
+        parsed_result
+      end
+
+      def mark_mission_accomplished
+        data = if result_type
+                 inputs[:result_data]
+               end
+        command_connector.mark_mission_accomplished(data, message_to_user)
+      end
+
+      def parsed_result
+        h = { message_to_user: }
+
+        if inputs[:result_data] && result_type
+          h[:result_data] = result_data
+        end
+
+        h
+      end
+    end
+  end
+end

data/src/foobara/agent/give_up.rb

@@ -0,0 +1,20 @@
+module Foobara
+  class Agent
+    class GiveUp < Foobara::Command
+      inputs do
+        command_connector :duck, :required, "Connector to end"
+        message_to_user :string, "Optional message to the user explaining why you decided to give up"
+      end
+
+      def execute
+        mark_given_up
+
+        nil
+      end
+
+      def mark_given_up
+        command_connector.give_up(message_to_user)
+      end
+    end
+  end
+end