bristow 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83bcff1d07e84dc62048bb20b5efbde10141e5c453b055bbef3d8ca38b5cd2a6
-  data.tar.gz: 006d1be92b480065c507bfd5045c6f504c640e01bf8977c07f133059a4f56b50
+  metadata.gz: 1888aaf7dc60df075779ec15107d64b7b611f979821843690f9c55e6cae522be
+  data.tar.gz: 23e2cd997e1855c5060ceb08c5a5f64575ad0d68de046a6ddaa20bb1063fd48a
 SHA512:
-  metadata.gz: '019da82b66875e737c376f4f4284a7f81ee7991fe8da8fa5da913954b372c107f99b44773e21eacf307be3fe30bbdc13e9fd68a1536d65ca2fd71e47c2fd62a4'
-  data.tar.gz: e82a99a0311273a57ae882777a9afa1905fedea747ea9594ae38d4d2ba3163833d5c8b854ca475bf81eecac6acd718864461c29a1886d5f1bc74df0e0ef5fed9
+  metadata.gz: 8413b8e49219c72ff68cd8870139843506c6d29737c6defaa8ccb7f67a60dd2c39ac29f092a56e0c3df55f8218962dbbfa5e94596c64cc7610472c5667eff789
+  data.tar.gz: f9f39a0ad386ba9a025deb0c98d994e46c9e043d06f0ac4208c7a4e1b1c5f37a7bdc195baa83fa1ed5167141fac028cc4925eaee3ffb0ce8fb52cad7b362f273

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [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.
+- Add .chat to Agent
+- Give functions a default name that is the name of the class
+- Add the workflow agency
+
 ## [0.3.1] - 2025-02-01
 
 - Dropped errant require of 'debug'

data/README.md

@@ -18,107 +18,254 @@ Or install it yourself as:
 
     $ gem install bristow
 
-## Usage
+## Quick start
+
+The main ideas concepts of this gem are:
+
+- **Agents**: Basically an AI model wrapper with a baked in system prompt, instructing it what it should do.
+- **Functions**: code the AI model can call to work with data in your application.
+- **Agencies**: Systems of agents working together to accomplish a task for a user. A chat call to an agency may call any number of agents within the agency to accomplish the task defined by the user.
+
+Here's how you might define an agent that can lookup user information in your application to answer questions from an admin:
 
 ```ruby
 require 'bristow'
 
 # Configure Bristow
 Bristow.configure do |config|
-  config.api_key = ENV['OPENAI_API_KEY']
+  # Bristow will use ENV['OPENAI_API_KEY'] by default, but you can
+  # set a custom OpenAI API key with:
+  config.api_key = ENV['MY_OPENAI_KEY']
 end
 
-# Define functions that the model can call
-class WeatherLookup < Bristow::Function
-  name "get_weather"
-  description "Get the current weather for a location"
-  system_message "You are a weather forecast assistant. Given a location, you will look up the weather forecast and provide a brief description."
-  parameters { 
+# 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
+  function_name "user_search"
+
+  # Description for the AI model that it can use to determine when
+  # it should call this function
+  description "Allows searching for users by domain or email. You must provide at least one search param."
+
+  # API of the function that will be provided to the model.
+  # https://platform.openai.com/docs/guides/function-calling
+  parameters({ 
     properties: {
-      location: {
+      domain: {
         type: "string",
-        description: "The city and state, e.g. San Francisco, CA"
+        description: "Search users by email domain"
       },
-      unit: {
+      email: {
         type: "string",
-        enum: ["celsius", "fahrenheit"],
-        description: "The unit of temperature to return"
+        description: "Search users by email address"
       }
-    },
-    required: ["location"]
-  }
-
-  def perform(location:, unit: 'celsius')
-    # Implement your application logic here
-    { temperature: 22, unit: unit }
+    }
+  })
+
+  # The implementation of this function. The AI model can choose
+  # whether or not to call this function, and this is the code that
+  # will execute if it does. It's how the AI works with data in 
+  # your application. 
+  def perform(domain: nil, email: nil)
+	query = { domain:, email: }.compact	
+    return "You must specify either domain or email for the user search" if query.empty?
+    
+	User.where(query).to_json
   end
 end
 
 # Create an agent with access to the function
-class Forecaster < Bristow::Agent
-  name "WeatherAssistant"
-  description "Helps with weather-related queries"
-  system_message "You are a weather forecast assistant. Given a location, you will look up the weather forecast and provide a brief description."
+class UserQueryAssistant < Bristow::Agent
+  agent_name "UserQueryAssistant"
+  description "Helps with user-related queries"
+  system_message <<~MSG 
+    You are a user management assistant. 
+    Given a task by an end user, will work on their behalf using function calls to accomplish this task.
+  MSG
   functions [WeatherLookup]
 end
 
 # Chat with the agent
-forecaster_agent = Forecaster.new
-forecaster_agent.chat("What's the weather like in London?") do |response_chunk|
-  # As the agent streams the response, print each chunk
+user_query_assistant = UserQueryAssistant.new
+user_query_assistant.chat("Which users from Google have the fanciest sounding titles?") do |response_chunk|
+  # As the agent streams the response to this block. 
+  # This block with receive a few characters of the response
+  # at a time as the response streams from the API.  
   print response_chunk 
 end
+```
+
+# Agents
+
+Agents provide you with an easy way to make calls to OpenAI. Once you've written the agent class, you can use it by calling `#chat` on any instance. The response from the AI is provided in two ways:
+
+```ruby
+conversation = UserQueryAssistant.new.chat('Who is the CEO of Google?')
+
+# At this point, `conversation` will contain the entire conversation history UserQueryAssistant had to work on the task on behalf of the user. This will include:
+#  - Original system prompt
+#  - The original user query
+#  - Any function calls made, and the responses to those function calls
+#  - The final response to the user
+puts conversation 
+
+# You can also provide a block to #chat that will stream only the final response to the user as it is generated by the AI:
+UserQueryAssistant.new.chat('Who is the CEO of Google?') do |text_chunk|
+  # This block will be called many times while the final user response 
+  # is being generated. In each call, `text_chunk` will contain the next
+  # few characters of the response, which you can render for your user.
+  puts text_chunk
+end
+```
+
+## Agent configuration
+
+Agents can be configured similar to something like `ActiveJob` or `Sidekiq`. You inherit from `Bristow::Agent` then call some helpers that will set the default config values. These defaults can be overridden when instantiating. 
+
+### Basic agent definition
+
+```ruby
+class Pirate < Bristow::Agent
+  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
+
+Pirate.new.chat("What's the best way to get from New York to Miami?") do |chunk|
+  puts chunk # => "Ahoy matey! If ye be lookin' to sail the seas from..."
+end
+
+```
+
+### Agent config options
+
+Here's an overview of all config options available when configuring an 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.
+- `model`: The AI model to use. Defaults to `Bristow.configuration.model`.
+- `client`: The client to use. Defaults to `Bristow.configuration.client`.
+- `logger`: The logger class to use when logging debug information. Defaults to `Bristow.configuration.logger`.
+
+When instantiating an instance of an agent, you can override these options for a specific instaces like this:
+
+```ruby
+class Pirate < Bristow::Agent
+  ...
+end
+
+regular_pirate = Pirate.new
+smart_pirate = Pirate.new(model: 'o3')
+```
+
+# Functions
 
-# Create a more complex agent that can access multiple functions
-class WeatherDatabase < Bristow::Function
-  name "store_weather"
-  description "Store weather data in the database"
-  parameters {
+You can think of functions as an API for your application for the AI model. When responding to a user's request, the AI model may respond directly, or choose to call functions you provide. 
+
+### Basic agent definition
+
+```ruby
+class TodoAssigner < Bristow::Function
+  function_name "todo_assigner"
+  description "Given a user ID and a todo ID, it will assign the todo to the user."
+  parameters({
     properties: {
-      location: {
+      user_id: {
         type: "string",
-        description: "The city and state, e.g. San Francisco, CA"
+        description: "ID of the user the todo should be assigned to"
       },
-      temperature: {
-        type: "number",
-        description: "The temperature in the specified unit"
+      todo_id: {
+        type: "string",
+        description: "ID of the todo to assign"
       },
-      unit: {
+      reason: {
         type: "string",
-        enum: ["celsius", "fahrenheit"],
-        description: "The unit of temperature"
+        description: "Why you decided to assign this todo to the user"
       }
     },
-    required: ["location", "temperature", "unit"]
-  }
+    required: ["user_id", "todo_id"]
+  })
 
-  def self.perform(location:, temperature:, unit:)
-    # Store the weather data in your database
-    { status: "success", message: "Weather data stored for #{location}" }
+  def perform(user_id:, todo_id:, reason: '')
+    TodoUsers.create( user_id:, todo_id:, reason:)  
   end
 end
+```
 
-class WeatherManager < Bristow::Agent
-  name "WeatherManager"
-  description "Manages weather data collection and storage"
-  system_message "You are a weather data management assistant. You can look up weather data and store it in the database."
-  functions [WeatherLookup, WeatherDatabase]
-end
+### Function config options
 
-# Create an agency to coordinate multiple agents. The supervisor agent is a
-# pre-configured agency that includes a supervisor agent that knows how to
-# delegate tasks to other agents
-class WeatherAgency < Bristow::Agencies::Supervisor
-  agents [Forecaster, WeatherManager]
-end
+Functions have 3 config options, and a `#perform` function:
+
+- `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.
+
+# Agencies
+
+Agencies are sets of agents that can work together on a task. It's how we can implement something like AutoGen's [multi-agent design patterns](https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/design-patterns/intro.html) in Ruby.
+
+There've very little going on in the base agent class. The long term goal of this gem is to pre-package common patterns. We currently only have the Supervisor pattern pre-packaged. It's probably best to start there. However, once you're ready to build your own multi-agent pattern, here's what you need to know.
 
-# Use the agency to coordinate multiple agents
-agency = WeatherAgency.new
-agency.chat("Can you check the weather in London and store it in the database?") do |response_chunk|
-  print response_chunk
+The base agency only has 3 items in it's public API:
+
+- `agents`: A config option that holds the list of `Agents` it can work with.
+- `#chat`: The chat method that is the entry point for the user's task. It raises a `NotImplementedError` in the base class, so it's up to you to implement the interaction pattern unless you want to use a pre-packaged agency.
+- `#find_agent(name)`: A helper function for facilitating hand-offs between agents.
+### Agency definition
+
+```ruby
+# We'll name this agency Sterling Cooper to
+# keep in line with our out of date TV show
+# reference naming convention.
+class SterlingCooper < Agency
+  agents [DonDraper, PeggyOlson, PeteCampbell]
+
+  def chat(messages, &block)
+    # Here's where you'd implement the multi-agent patternn
+    # In this example, we'll just do a workflow, where we
+    # loop through each agent and allow them to respond once.
+    # This sort of simple workflow could work if you want a
+    # specific set of steps to be repeated every time.
+    agents.each do |agent|
+	    messages = agent.chat(messages, &block)
+	end
+
+	messages
+  end
 end
+
+campaign = SterlingCooper.new.chat("Please come up with an ad campaign for the Bristow gem")
 ```
 
+## Pre-packaged agencies
+
+### Supervisor Agency Overview
+
+The supervisor agency implements a pattern something like [LangChain's Multi-agent supervisor pattern](https://langchain-ai.github.io/langgraph/tutorials/multi_agent/agent_supervisor/). You provide an array of agents, and a pre-packaged Supervisor agent will handle:
+
+1. Receive the task from the user
+2. Analyze which agent you've provided might be best suited to handle the next step of the work
+3. Call that agent
+4. Repeat agent calls until it believes the task is complete
+5. Craft a final answer to the end user
+
+This can be useful when building a chat bot for your application. You can build out the agents and functions that interact with different parts of your system, a reporting agent, a user management agent, etc. You then throw them all together in in a supervisor agency, and expose a chat UI for admins. This chat UI would then be allow the AI model to interact with your application.
+
+You can see `examples/basic_agency.rb` for example code.
+
+### Worfkflow Agency Overview
+
+The workflow agency is a simple pattern that allows you to define a set of steps that should be repeated every time a user interacts with the agency. This can be useful when you have a specific set of steps that should be repeated every time a user interacts with the agency. It will:
+
+1. Receive the task from the user
+2. Call each agent in order
+3. Stream the response from the last agent in the series
+
+You can see `examples/workflow_agency.rb` for example code.
+
 ## Examples
 
 A few working examples are in the `examples/` directory. If you have `OPENAI_API_KEY` set in the environment, you can run the examples with with `bundle exec ruby examples/<example file>.rb` to get a taste of Bristow.
@@ -141,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/{agency.rb → 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

@@ -0,0 +1,27 @@
+require_relative '../lib/bristow'
+
+class TravelAgent < Bristow::Agent
+  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
+  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
+
+# The workflow agent implements basic workflow. It will call each agent in the
+# order they are listed, passing the message history to each agent. The response
+# from the last agent is streamed to the block passed to chat, but the entire
+# message history is returned.
+workflow = Bristow::Agencies::Workflow.new(agents: [TravelAgent, StoryTeller])
+
+messages = workflow.chat('New York') do |part|
+  print part
+end
+
+puts '*' * 80
+puts 'Chat history:'
+pp messages

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/agencies/workflow.rb

@@ -0,0 +1,16 @@
+module Bristow
+  module Agencies
+    class Workflow < Agency
+      def chat(messages, &block)
+        return messages if agents.empty?
+
+        agents.each.with_index(1) do |agent, index|
+          last = index == agents.size
+          messages = agent.chat(messages, &(last ? block : nil))
+        end
+
+        messages
+      end
+    end
+  end
+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
+    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.3.1"
+  VERSION = "0.5.0"
 end

data/lib/bristow.rb

@@ -13,6 +13,11 @@ require_relative "bristow/agent"
 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.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Andrew Hampton
 bindir: bin
 cert_chain: []
-date: 2025-02-01 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
@@ -123,11 +109,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- examples/agency.rb
+- examples/basic_agency.rb
 - examples/basic_agent.rb
+- examples/basic_termination.rb
 - examples/function_calls.rb
+- examples/workflow_agency.rb
 - lib/bristow.rb
 - lib/bristow/agencies/supervisor.rb
+- lib/bristow/agencies/workflow.rb
 - lib/bristow/agency.rb
 - lib/bristow/agent.rb
 - lib/bristow/agents/supervisor.rb
@@ -136,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:
@@ -161,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