bristow 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83bcff1d07e84dc62048bb20b5efbde10141e5c453b055bbef3d8ca38b5cd2a6
-  data.tar.gz: 006d1be92b480065c507bfd5045c6f504c640e01bf8977c07f133059a4f56b50
+  metadata.gz: 2ef9882c1bac79c842354a58c175fd1ed1c6228140c2139246dcdc22bb693728
+  data.tar.gz: 4f7c34334cda242b9a7dd1f34072df637aebb3d0e59ed06d2dd665219c44d210
 SHA512:
-  metadata.gz: '019da82b66875e737c376f4f4284a7f81ee7991fe8da8fa5da913954b372c107f99b44773e21eacf307be3fe30bbdc13e9fd68a1536d65ca2fd71e47c2fd62a4'
-  data.tar.gz: e82a99a0311273a57ae882777a9afa1905fedea747ea9594ae38d4d2ba3163833d5c8b854ca475bf81eecac6acd718864461c29a1886d5f1bc74df0e0ef5fed9
+  metadata.gz: 3333d030e4db031098a26c6d1ddea67ba6c23a42b58b4f90ecab5289f6565c230b8a9e10becb4c9af11c18198da66fb5b1be6174b43c1ffc4350b5b1e19ba7f0
+  data.tar.gz: 75d286829802af2c80ba1a7638d1b27129aedf66d5e331195cffc942caeb1272eb5b5d317538aa359d2db9b627320c0e74a1c2d8e4867cf77bba7b43c12021e2

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [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
+  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
+  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
+  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:
+
+- `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
+  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:
+
+- `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.

data/examples/workflow_agency.rb

@@ -0,0 +1,27 @@
+require_relative '../lib/bristow'
+
+class TravelAgent < Bristow::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"
+  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/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/function.rb

@@ -5,7 +5,7 @@ module Bristow
     include Bristow::Sgetter
     include Bristow::Delegate
 
-    sgetter :name
+    sgetter :name, default: -> { self.class.name }
     sgetter :description
     sgetter :parameters, default: {}
 

data/lib/bristow/version.rb

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

data/lib/bristow.rb

@@ -13,6 +13,7 @@ require_relative "bristow/agent"
 require_relative "bristow/agents/supervisor"
 require_relative "bristow/agency"
 require_relative "bristow/agencies/supervisor"
+require_relative "bristow/agencies/workflow"
 
 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.4.0
 platform: ruby
 authors:
 - Andrew Hampton
 bindir: bin
 cert_chain: []
-date: 2025-02-01 00:00:00.000000000 Z
+date: 2025-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-openai
@@ -123,11 +123,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- examples/agency.rb
+- examples/basic_agency.rb
 - examples/basic_agent.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