bristow 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ef9882c1bac79c842354a58c175fd1ed1c6228140c2139246dcdc22bb693728
-  data.tar.gz: 4f7c34334cda242b9a7dd1f34072df637aebb3d0e59ed06d2dd665219c44d210
+  metadata.gz: 1888aaf7dc60df075779ec15107d64b7b611f979821843690f9c55e6cae522be
+  data.tar.gz: 23e2cd997e1855c5060ceb08c5a5f64575ad0d68de046a6ddaa20bb1063fd48a
 SHA512:
-  metadata.gz: 3333d030e4db031098a26c6d1ddea67ba6c23a42b58b4f90ecab5289f6565c230b8a9e10becb4c9af11c18198da66fb5b1be6174b43c1ffc4350b5b1e19ba7f0
-  data.tar.gz: 75d286829802af2c80ba1a7638d1b27129aedf66d5e331195cffc942caeb1272eb5b5d317538aa359d2db9b627320c0e74a1c2d8e4867cf77bba7b43c12021e2
+  metadata.gz: 8413b8e49219c72ff68cd8870139843506c6d29737c6defaa8ccb7f67a60dd2c39ac29f092a56e0c3df55f8218962dbbfa5e94596c64cc7610472c5667eff789
+  data.tar.gz: f9f39a0ad386ba9a025deb0c98d994e46c9e043d06f0ac4208c7a4e1b1c5f37a7bdc195baa83fa1ed5167141fac028cc4925eaee3ffb0ce8fb52cad7b362f273

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.5.0] - 2025-05-08
+
+- Add termination conditions so you can ensure an agent stop after a certain amount of time.
+- Drop VCR in favor of WebMock for testing
+- Fix `name` shadowing the built-in function for agent and function
+
 ## [0.4.0] - 2025-02-15
 
 - Update the README to make it flow a bit better.

data/README.md

@@ -41,7 +41,7 @@ end
 # Define functions that the model can call to interact with your app
 class UserSearch < Bristow::Function
   # Name that will be provided to the AI model for function calls
-  name "user_search"
+  function_name "user_search"
 
   # Description for the AI model that it can use to determine when
   # it should call this function
@@ -76,7 +76,7 @@ end
 
 # Create an agent with access to the function
 class UserQueryAssistant < Bristow::Agent
-  name "UserQueryAssistant"
+  agent_name "UserQueryAssistant"
   description "Helps with user-related queries"
   system_message <<~MSG 
     You are a user management assistant. 
@@ -126,7 +126,7 @@ Agents can be configured similar to something like `ActiveJob` or `Sidekiq`. You
 
 ```ruby
 class Pirate < Bristow::Agent
-  name "Pirate"
+  agent_name "Pirate"
   description "An agent that assists the user while always talking like a pirate."
   system_message "You are a helpful assistant that always talks like a pirate. Try to be as corny and punny as possible."
 end
@@ -141,7 +141,7 @@ end
 
 Here's an overview of all config options available when configuring an Agent:
 
-- `name`: The name of the agent
+- `agent_name`: The name of the agent
 - `description`: Description of what the agent can do. Can be used by agencies to provide information about the agent, informing the model when this agent should be used.
 - `system_message`: The system message to be sent before the first user message. This can be used to provide context to the model about the conversation.
 - `functions`: An array of `Bristow::Function` classes that the agent has access to. When working on the task assigned by the user, the AI model will have access to these functions, and will decide when a call to any function call is necessary.
@@ -168,7 +168,7 @@ You can think of functions as an API for your application for the AI model. When
 
 ```ruby
 class TodoAssigner < Bristow::Function
-  name "todo_assigner"
+  function_name "todo_assigner"
   description "Given a user ID and a todo ID, it will assign the todo to the user."
   parameters({
     properties: {
@@ -198,7 +198,7 @@ end
 
 Functions have 3 config options, and a `#perform` function:
 
-- `name`: The name of the function. Provided to the AI model to help it call this function, and can be used to determine whether or not this function should be called.
+- `function_name`: The name of the function. Provided to the AI model to help it call this function, and can be used to determine whether or not this function should be called.
 - `description`: A description of the function that will be provided to the AI model. Important for informing the model about what this function can do, so it's able to determine when to call this function.
 - `parameters`: The JSON schema definition of the function's API. See Open AI's [function docs](https://platform.openai.com/docs/guides/function-calling) for detailed information.
 - `#perform`: The perform function is your implementation for the function. You'll check out the parameters passed in from the model, and handle any operation it's requesting to do.
@@ -288,7 +288,7 @@ end
 
 # You can overrided these settings on a per-agent basis like this:
 storyteller = Bristow::Agent.new(
-  name: 'Sydney',
+  agent_name: 'Sydney',
   description: 'Agent for telling spy stories',
   system_message: 'Given a topic, you will tell a brief spy story',
   model: 'gpt-4o-mini',

data/examples/basic_agency.rb

@@ -1,13 +1,13 @@
 require_relative '../lib/bristow'
 
 class PirateTalker < Bristow::Agent
-  name "PirateSpeaker"
+  agent_name "PirateSpeaker"
   description "Agent for translating input to pirate-speak"
   system_message 'Given a text, you will translate it to pirate-speak.'
 end
 
 class TravelAgent < Bristow::Agent
-  name "TravelAgent"
+  agent_name "TravelAgent"
   description "Agent for planning trips"
   system_message 'Given a destination, you will plan a trip. You will respond with an itinerary that includes dates, times, and locations only.'
 end

data/examples/basic_agent.rb

@@ -5,7 +5,7 @@ Bristow.configure do |config|
 end
 
 class Sydney < Bristow::Agent
-  name 'Sydney'
+  agent_name 'Sydney'
   description 'Agent for telling spy stories'
   system_message 'Given a topic, you will tell a brief spy story'
 end

data/examples/basic_termination.rb

@@ -0,0 +1,29 @@
+require_relative '../lib/bristow'
+
+class CountAgent < Bristow::Agent
+  agent_name "CounterAgent"
+  description "Knows how to count"
+  system_message "You are a helpful mupet vampire that knows how to count very well. You will find the last message in the series and reply with the next integer."
+  termination Bristow::Terminations::MaxMessages.new(3)
+end
+
+fake_history = [
+  { role: "user", content: "What comes after 3" },
+  { role: "assistant", content: "4" },
+  { role: "user", content: "What comes after 4" },
+  { role: "assistant", content: "5" },
+  { role: "user", content: "What comes after 5" },
+  { role: "assistant", content: "6" }
+]
+
+# Start a conversation, but given the termination condition,
+# there should be no more messages added. It should return
+# immediately returning the provided input.
+messages = CountAgent.chat(fake_history) do |part|
+  puts "This will never execute"
+end
+
+puts ''
+puts '*' * 10
+puts 'All messages:'
+pp messages

data/examples/function_calls.rb

@@ -6,7 +6,7 @@ end
 
 # Define functions that GPT can call
 class WeatherLookup < Bristow::Function
-  name "get_weather"
+  function_name "get_weather"
   description "Get the current weather for a location"
   parameters ({
     type: "object",
@@ -32,7 +32,7 @@ end
 
 # Create an agent with these functions
 class WeatherAgent < Bristow::Agent
-  name "WeatherAssistant"
+  agent_name "WeatherAssistant"
   description "Helps with weather-related queries"
   system_message "You are a helpful weather assistant. You'll be asked about the weather, and should use the get_weather function to respond."
   functions [WeatherLookup]

data/examples/workflow_agency.rb

@@ -1,13 +1,13 @@
 require_relative '../lib/bristow'
 
 class TravelAgent < Bristow::Agent
-  name "TravelAgent"
+  agent_name "TravelAgent"
   description "Agent for planning trips"
   system_message 'Given a destination, you will plan a trip. You will respond with an itinerary that includes dates, times, and locations only.'
 end
 
 class StoryTeller < Bristow::Agent
-  name "StoryTeller"
+  agent_name "StoryTeller"
   description 'An agent that tells a story given an agenda'
   system_message "Given a trip agenda, you will tell a story about a traveler who recently took that trip. Be sure to highlight the traveler's experiences and emotions."
 end

data/lib/bristow/agencies/supervisor.rb

@@ -5,13 +5,15 @@ module Bristow
 
       sgetter :custom_instructions, default: nil
 
-      def initialize(agents: self.class.agents.dup)
-        @custom_instructions = self.class.custom_instructions
+      def initialize(agents: self.class.agents.dup, custom_instructions: self.class.custom_instructions, termination: Bristow::Terminations::MaxMessages.new(100))
+        @custom_instructions = custom_instructions
         @agents = agents
+        @termination = termination
         @supervisor = Agents::Supervisor.new(
           child_agents: agents,
           agency: self,
-          custom_instructions: custom_instructions
+          custom_instructions: custom_instructions,
+          termination: termination
         )
       end
 

data/lib/bristow/agency.rb

@@ -17,7 +17,7 @@ module Bristow
     end
 
     def find_agent(name)
-      agent = agents.find { |agent| agent_name(agent) == name }
+      agent = agents.find { |agent| agent_name_for(agent) == name }
       return nil unless agent
       
       agent.is_a?(Class) ? agent.new : agent
@@ -32,8 +32,8 @@ module Bristow
 
     private
 
-    def agent_name(agent)
-      agent.is_a?(Class) ? agent.name : agent.class.name
+    def agent_name_for(agent)
+      agent.is_a?(Class) ? agent.agent_name : agent.class.agent_name
     end
   end
 end

data/lib/bristow/agent.rb

@@ -2,25 +2,29 @@ module Bristow
   class Agent
     include Bristow::Sgetter
 
-    sgetter :name
+    sgetter :agent_name
     sgetter :description
     sgetter :system_message
     sgetter :functions, default: []
     sgetter :model, default: -> { Bristow.configuration.model }
     sgetter :client, default: -> { Bristow.configuration.client }
     sgetter :logger, default: -> { Bristow.configuration.logger }
+    sgetter :termination, default: -> { Bristow::Terminations::MaxMessages.new(100) }
     attr_reader :chat_history
+    
+
 
     def initialize(
-      name: self.class.name,
-      description: self.class.name,
+      agent_name: self.class.agent_name,
+      description: self.class.description,
       system_message: self.class.system_message,
       functions: self.class.functions.dup,
       model: self.class.model,
       client: self.class.client,
-      logger: self.class.logger
+      logger: self.class.logger,
+      termination: self.class.termination
     )
-      @name = name
+      @agent_name = agent_name
       @description = description
       @system_message = system_message
       @functions = functions
@@ -28,10 +32,11 @@ module Bristow
       @client = client
       @logger = logger
       @chat_history = []
+      @termination = termination
     end
 
     def handle_function_call(name, arguments)
-      function = functions.find { |f| f.name == name }
+      function = functions.find { |f| f.function_name == name }
       raise ArgumentError, "Function #{name} not found" unless function
       function.call(**arguments.transform_keys(&:to_sym))
     end
@@ -53,7 +58,7 @@ module Bristow
 
       @chat_history = messages.dup
 
-      loop do
+      while termination.continue?(messages) do
         params = {
           model: model,
           messages: messages

data/lib/bristow/agents/supervisor.rb

@@ -5,7 +5,7 @@ module Bristow
     class Supervisor < Agent
       attr_reader :agency
 
-      name "Supervisor"
+      agent_name "Supervisor"
       description "A supervisor agent that coordinates between specialized agents"
       system_message <<~MESSAGE
         You are a supervisor agent that coordinates between specialized agents.
@@ -24,21 +24,23 @@ module Bristow
 
       sgetter :custom_instructions, default: nil
 
-      def initialize(child_agents:, agency:, custom_instructions: nil)
+      def initialize(child_agents:, agency:, custom_instructions: nil, termination: self.class.termination)
         super()
         @custom_instructions = custom_instructions || self.class.custom_instructions
         @system_message = build_system_message(child_agents)
         @agency = agency
         @custom_instructions = custom_instructions || self.class.custom_instructions
+        @termination = termination
         agency.agents << self
-        functions << Functions::Delegate.new(self, agency)
+        @functions ||= []
+        @functions << Functions::Delegate.new(self, agency)
       end
 
       private
 
       def build_system_message(available_agents)
         agent_descriptions = available_agents.map do |agent|
-          "- #{agent.name}: #{agent.description}"
+          "- #{agent.agent_name}: #{agent.description}"
         end.join("\n")
 
         <<~MESSAGE

data/lib/bristow/function.rb

@@ -5,13 +5,23 @@ module Bristow
     include Bristow::Sgetter
     include Bristow::Delegate
 
-    sgetter :name, default: -> { self.class.name }
+    sgetter :function_name, default: nil
     sgetter :description
     sgetter :parameters, default: {}
 
+    def initialize(
+      function_name: self.class.function_name,
+      description: self.class.description,
+      parameters: self.class.parameters
+    )
+      @function_name = function_name
+      @description = description
+      @parameters = parameters
+    end
+
     def self.to_openai_schema
       {
-        name: name,
+        name: function_name,
         description: description,
         parameters: parameters
       }

data/lib/bristow/functions/delegate.rb

@@ -3,9 +3,7 @@
 module Bristow
   module Functions
     class Delegate < Function
-      def self.name
-        "delegate_to"
-      end
+      function_name "delegate_to"
 
       def self.description
         "Delegate a task to a specialized agent"
@@ -28,10 +26,6 @@ module Bristow
         }
       end
 
-      def name
-        self.class.name
-      end
-
       def description
         self.class.description
       end
@@ -45,6 +39,7 @@ module Bristow
 
         @agent = agent
         @agency = agency
+        super()
       end
 
       def agency=(agency)
@@ -54,7 +49,7 @@ module Bristow
       def perform(agent_name:, message:)
         raise "Agency not set" if @agency.nil?
 
-        if agent_name == @agent.name
+        if agent_name == @agent.agent_name
           { error: "Cannot delegate to self" }
         else
           agent = @agency.find_agent(agent_name)

data/lib/bristow/helpers/sgetter.rb

@@ -4,16 +4,16 @@
 # Example:
 # class Agent
 #   include Bristow::Sgetter
-#   sgetter :name
+#   sgetter :agent_name
 #   sgetter :model, default: -> { Bristow.configuration.model }
 # end
 #
 # class Sydney < Agent
-#   name 'Sydney'
+#   agent_name 'Sydney'
 # end
 #
 # sydney = Sydney.new
-# sydney.name # => 'Sydney'
+# sydney.agent_name # => 'Sydney'
 module Bristow
   module Sgetter
     def self.included(base)

data/lib/bristow/termination.rb

@@ -0,0 +1,5 @@
+class Bristow::Termination
+  def continue?(messages)
+    raise NotImplementedError, "`#continue?` must be implemented in #{self.class}"
+  end
+end

data/lib/bristow/terminations/can_not_stop_will_not_stop.rb

@@ -0,0 +1,9 @@
+module Bristow
+  module Terminations
+    class CanNotStopWillNotStop < Bristow::Termination
+      def continue?(_messages)
+        true
+      end
+    end
+  end
+end

data/lib/bristow/terminations/max_messages.rb

@@ -0,0 +1,13 @@
+module Bristow
+  module Terminations
+    class MaxMessages < Bristow::Termination
+      def initialize(max_messages)
+        @max_messages = max_messages
+      end
+
+      def continue?(messages)
+        messages.size < @max_messages
+      end
+    end
+  end
+end

data/lib/bristow/terminations/timeout.rb

@@ -0,0 +1,13 @@
+module Bristow
+  module Terminations
+    class Timeout < Bristow::Termination
+      def initialize(end_time: Time.now + 60)
+        @end_time = end_time
+      end
+
+      def continue?(_messages)
+        Time.now < @end_time
+      end
+    end
+  end
+end

data/lib/bristow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bristow
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/bristow.rb

@@ -14,6 +14,10 @@ require_relative "bristow/agents/supervisor"
 require_relative "bristow/agency"
 require_relative "bristow/agencies/supervisor"
 require_relative "bristow/agencies/workflow"
+require_relative "bristow/termination"
+require_relative "bristow/terminations/max_messages"
+require_relative "bristow/terminations/timeout"
+require_relative "bristow/terminations/can_not_stop_will_not_stop"
 
 module Bristow
   class Error < StandardError; end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bristow
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Andrew Hampton
 bindir: bin
 cert_chain: []
-date: 2025-02-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-openai
@@ -65,20 +65,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -125,6 +111,7 @@ files:
 - Rakefile
 - examples/basic_agency.rb
 - examples/basic_agent.rb
+- examples/basic_termination.rb
 - examples/function_calls.rb
 - examples/workflow_agency.rb
 - lib/bristow.rb
@@ -138,6 +125,10 @@ files:
 - lib/bristow/functions/delegate.rb
 - lib/bristow/helpers/delegate.rb
 - lib/bristow/helpers/sgetter.rb
+- lib/bristow/termination.rb
+- lib/bristow/terminations/can_not_stop_will_not_stop.rb
+- lib/bristow/terminations/max_messages.rb
+- lib/bristow/terminations/timeout.rb
 - lib/bristow/version.rb
 homepage: https://github.com/andrewhampton/bristow
 licenses:
@@ -163,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.8
 specification_version: 4
 summary: A Ruby framework for creating systems of cooperative AI agents with function
   calling capabilities