bristow 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa9d6f366bc13e51f9b2aac247ac4103c61afab9da22670be1ff60ab3a0c5031
-  data.tar.gz: cb45d972b3597f4a525cfc91004702d8fd53ff19add9c414394be229edee159c
+  metadata.gz: e61544a71407814e6c09e22d56631df8ed7a0475cf8b182ba4d7bf86bcf68d4c
+  data.tar.gz: 29a5285d24236fbd6226bffebbdd34becd3a7c2ac81c33fafde0a35d0e8eaf31
 SHA512:
-  metadata.gz: c4af5ed27634ea26ee20045434a515ef43c4ddc2ed6640a37601b48fac83c5cab3245fe046978a6fb9be03dc793f823d6bb709136f7e9496b63d223b1b042c0d
-  data.tar.gz: cbd4c61ae965a4f238d8c0598c364235d3ff5dbfbf35c461e738c820ae49dc9cfa73b748150e4344218c98e4b8b651d23260b9515805cf695a3f553e3796bd38
+  metadata.gz: 2b9a904a1309e6d111ecf4b5172a4f07b6c57acfb7a8b219c4b890a6e914fcdc7e6bc9b7da5aa88b67aca1bffe57de185be2fe2583ab8fea8dedf416f67c1100
+  data.tar.gz: defc7c18b96063f1e1a4e88513ba7cc780c0fbf66aecf6f5eda74084721e4325a29a3f0ea3a50fec453309833280daa2db39aa3d782c548b86ee737dac1b92fe

data/README.md

@@ -1,15 +1,6 @@
 # Bristow
 
-Bristow is a Ruby framework for creating function-calling enabled agents that work with OpenAI's GPT models. It provides a simple way to expose Ruby functions to GPT, handle the function calling protocol, and manage conversations.
-
-## Features
-
-- 🤖 Simple function-calling interface for GPT models
-- 🔄 Automatic handling of OpenAI's function calling protocol
-- 🛠 Type-safe function definitions
-- 🔌 Easy to extend with custom functions
-- 📝 Clean conversation management
-- 🏢 Multi-agent coordination through agencies
+Bristow makes working with AI models in your application dead simple. Whether it's a simple chat, using function calls, or building multi-agent systems, Bristow will help you hit the ground running.
 
 ## Installation
 
@@ -27,25 +18,6 @@ Or install it yourself as:
 
     $ gem install bristow
 
-## Configuration
-
-Configure Bristow with your settings:
-
-```ruby
-Bristow.configure do |config|
-  # Your OpenAI API key (defaults to ENV['OPENAI_API_KEY'])
-  config.openai_api_key = 'your-api-key'
-  
-  # The default model to use (defaults to 'gpt-4o-mini')
-  config.default_model = 'gpt-4o'
-  
-  # Logger to use (defaults to Logger.new(STDOUT))
-  config.logger = Rails.logger
-end
-```
-
-These settings can be overridden on a per-agent basis when needed.
-
 ## Usage
 
 ### Simple Agent
@@ -61,18 +33,14 @@ storyteller = Bristow::Agent.new(
   system_message: 'Given a topic, you will tell a brief spy story',
 )
 
-# Chat with a single message
-response = storyteller.chat('Tell me a story about Cold War era Berlin') do |part|
-  print part # Stream the response
+# Either stream the response with a block:
+storyteller.chat('Tell me a story about Cold War era Berlin') do |response_chunk|
+  print response_chunk # response_chunk will be the next chunk of text in the response from the model
 end
 
-# Chat with multiple messages
-response = storyteller.chat([
-  'Tell me a story about Cold War era Berlin',
-  'Make it about a double agent'
-]) do |part|
-  print part
-end
+# Or work with the entire conversation once it's complete:
+conversation = storyteller.chat('Tell me a story about Cold War era Berlin')
+puts conversation.last['content'] 
 ```
 
 ### Basic Agent with Functions
@@ -82,16 +50,26 @@ end
 weather = Bristow::Function.new(
   name: "get_weather",
   description: "Get the current weather for a location",
-  parameters: {
-    location: String,
-    unit: String
+  parameters: { 
+    properties: {
+      location: {
+        type: "string",
+        description: "The city and state, e.g. San Francisco, CA"
+      },
+      unit: {
+        type: "string",
+        enum: ["celsius", "fahrenheit"],
+        description: "The unit of temperature to return"
+      }
+    },
+    required: ["location"]
   }
 ) do |location:, unit: 'celsius'|
-  # Your weather API call here
+  # Implement your application logic here
   { temperature: 22, unit: unit }
 end
 
-# Create an agent with these functions
+# Create an agent with access to the function
 weather_agent = Bristow::Agent.new(
   name: "WeatherAssistant",
   description: "Helps with weather-related queries",
@@ -99,17 +77,20 @@ weather_agent = Bristow::Agent.new(
 )
 
 # Chat with the agent
-weather_agent.chat("What's the weather like in London?") do |part|
-  print part  # Stream the response
+weather_agent.chat("What's the weather like in London?") do |response_chunk|
+  print response_chunk 
 end
 ```
 
+The `parameters` hash is passed directly through to OpenAI's API. You can see details about how to define parameters in [OpenAI's documentation for defining functions](https://platform.openai.com/docs/guides/function-calling#defining-functions).
+
+
 ### Multi-Agent System
 
-You can coordinate multiple agents using agencies. Here's an example using the included supervisor agency:
+You can coordinate multiple agents using `Bristow::Agency`. Bristow includes a few common patterns, including the one like [langchain's multi-agent supervisor](https://langchain-ai.github.io/langgraph/tutorials/multi_agent/agent_supervisor/). Here's how to use the supervisor agency:
 
 ```ruby
-# Create specialized agents
+# Create specialized agents. These can be configured with functions, as well.
 pirate_talker = Bristow::Agent.new(
   name: "PirateSpeaker",
   description: "Agent for translating input to pirate-speak",
@@ -125,21 +106,43 @@ travel_agent = Bristow::Agent.new(
 # Create a supervisor agency to coordinate the agents
 agency = Bristow::Agencies::Supervisor.create(agents: [pirate_talker, travel_agent])
 
-# The supervisor will automatically delegate to the appropriate agent.
-# In this case, it will almost certainly delegate to the travel_agent first, to get a bulleted itenerary.
-# Then, it will delegate to the pirate_talker to translate the itenerary into pirate-speak.
+# The supervisor will automatically delegate to the appropriate agent as needed before generating a response for the user.
 agency.chat([
   { role: "user", content: "I want to go to New York. Tell me about it as if you were a pirate." }
-]) do |part|
-  print part
+]) do |response_chunk|
+  print response_chunk
 end
 ```
 
-The supervisor will:
-1. Understand the user's request
-2. Choose the appropriate agent(s)
-3. Delegate parts of the task to different agents
-4. Combine their responses into a coherent answer
+## 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.
+
+## Configuration
+
+Configure Bristow with your settings:
+
+```ruby
+Bristow.configure do |config|
+  # Your OpenAI API key (defaults to ENV['OPENAI_API_KEY'])
+  config.openai_api_key = 'your-api-key'
+  
+  # The default model to use (defaults to 'gpt-4o-mini')
+  config.default_model = 'gpt-4o'
+  
+  # Logger to use (defaults to Logger.new(STDOUT))
+  config.logger = Rails.logger
+end
+
+# You can overrided these settings on a per-agent basis like this:
+storyteller = Bristow::Agent.new(
+  name: 'Sydney',
+  description: 'Agent for telling spy stories',
+  system_message: 'Given a topic, you will tell a brief spy story',
+  model: 'gpt-4o-mini',
+  logger: Logger.new(STDOUT)
+)
+```
 
 ## Development
 

data/examples/agency.rb

@@ -20,5 +20,4 @@ messages = agency.chat([
     print part
 end
 
-
-puts messages
+puts messages

data/examples/function_calls.rb

@@ -9,8 +9,19 @@ weather = Bristow::Function.new(
   name: "get_weather",
   description: "Get the current weather for a location",
   parameters: {
-    location: String,
-    unit: String
+    type: "object",
+    properties: {
+      location: {
+        type: "string",
+        description: "The city and state, e.g. San Francisco, CA"
+      },
+      unit: {
+        type: "string",
+        enum: ["celsius", "fahrenheit"],
+        description: "The unit of temperature to return"
+      }
+    },
+    required: [:location]
   }
 ) do |location:, unit: 'celsius'|
   # Your weather API call here
@@ -33,7 +44,7 @@ messages_from_chat = weather_agent.chat(messages) do |part|
   print part
 end
 
-
+puts ''
 puts '*' * 10
 puts 'All messages:'
-pp messages_from_chat
+pp messages

data/lib/bristow/agencies/supervisor.rb

@@ -25,9 +25,6 @@ module Bristow
         # Convert string message to proper format
         messages = [{ role: "user", content: messages }] if messages.is_a?(String)
         
-        # Convert array of strings to proper format
-        messages = messages.map { |msg| msg.is_a?(String) ? { role: "user", content: msg } : msg } if messages.is_a?(Array)
-
         supervisor.chat(messages, &block)
       end
     end

data/lib/bristow/agency.rb

@@ -7,12 +7,6 @@ module Bristow
     end
 
     def chat(messages, &block)
-      # Convert string message to proper format
-      messages = [{ role: "user", content: messages }] if messages.is_a?(String)
-      
-      # Convert array of strings to proper format
-      messages = messages.map { |msg| msg.is_a?(String) ? { role: "user", content: msg } : msg } if messages.is_a?(Array)
-
       raise NotImplementedError, "Agency#chat must be implemented by a subclass"
     end
 

data/lib/bristow/agent.rb

@@ -25,37 +25,13 @@ module Bristow
 
     def functions_for_openai
       functions.map do |function|
-        {
-          name: function.name,
-          description: function.description,
-          parameters: {
-            type: "object",
-            properties: function.parameters.transform_values { |type| parameter_type_for(type) },
-            required: function.parameters.keys.map(&:to_s)
-          }
-        }
+        function.to_openai_schema
       end
     end
 
     def chat(messages, &block)
       # Convert string message to proper format
       messages = [{ role: "user", content: messages }] if messages.is_a?(String)
-      
-      # Convert array to array of hashes
-      messages = if messages.is_a?(Array)
-        messages.map do |msg|
-          case msg
-          when String
-            { role: "user", content: msg }
-          when Hash
-            msg.transform_keys(&:to_sym)
-          else
-            raise ArgumentError, "Invalid message format: #{msg.inspect}"
-          end
-        end
-      else
-        messages
-      end
 
       messages = messages.dup
       messages.unshift(system_message_hash) if system_message

data/lib/bristow/function.rb

@@ -10,10 +10,14 @@ module Bristow
       @description = description
       @parameters = parameters
       @block = block
+
+      if !parameters.has_key?(:type)
+        parameters[:type] = "object"
+      end
     end
 
     def call(**kwargs)
-      validate_parameters!(kwargs)
+      validate_required_parameters!(kwargs)
       @block.call(**kwargs)
     end
 
@@ -21,61 +25,16 @@ module Bristow
       {
         name: name,
         description: description,
-        parameters: {
-          type: "object",
-          properties: parameters_schema,
-          required: required_parameters
-        }
+        parameters: parameters
       }
     end
 
     private
 
-    def validate_parameters!(kwargs)
-      # Check for missing required parameters
-      missing = required_parameters - kwargs.keys
-      raise ArgumentError, "missing keyword: :#{missing.first}" if missing.any?
-
-      # Check parameter types
-      kwargs.each do |key, value|
-        expected_type = parameters[key].is_a?(Hash) ? parameters[key][:type] : parameters[key]
-        next unless expected_type.is_a?(Class) # Skip complex type definitions
-
-        unless value.is_a?(expected_type)
-          raise TypeError, "#{key} must be a #{expected_type}"
-        end
-      end
-    end
-
-    def parameters_schema
-      parameters.transform_values do |type|
-        if type.is_a?(Hash)
-          { type: ruby_type_to_json_type(type[:type]) }
-        else
-          { type: ruby_type_to_json_type(type) }
-        end
-      end
-    end
-
-    def required_parameters
-      parameters.reject { |_, type| type.is_a?(Hash) && type[:optional] }.keys
-    end
-
-    def ruby_type_to_json_type(type)
-      case type
-      when String, Class
-        case type.to_s
-        when "String" then "string"
-        when "Integer" then "integer"
-        when "Float" then "number"
-        when "TrueClass", "FalseClass", "Boolean" then "boolean"
-        when "Array" then "array"
-        when "Hash" then "object"
-        else "string" # Default to string for unknown types
-        end
-      else
-        "string" # Default to string for unknown types
-      end
+    def validate_required_parameters!(kwargs)
+      required_params = parameters.dig(:required) || []
+      missing = required_params.map(&:to_sym) - kwargs.keys.map(&:to_sym)
+      raise ArgumentError, "missing keyword: #{missing.first}" if missing.any?
     end
   end
 end

data/lib/bristow/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bristow
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrew Hampton
 bindir: bin
 cert_chain: []
-date: 2025-01-22 00:00:00.000000000 Z
+date: 2025-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-openai
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement