ruby-openai-swarm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df437749d299781cdac584185c29c03d6bcdd0ae8ae547395d23656c7a5ff308
+  data.tar.gz: ad06764c570c061aab9077ae280bad27b174a740f5721616ab0f3fb052eeb638
+SHA512:
+  metadata.gz: 22dff45e435bbe72d598cae52e1924f1921f9d4c07e0795c6b0d58368c72050d33cb63f999c936465fdf5a9bd1065d7dcbeb8696259b9468f8c5b325bfb686d6
+  data.tar.gz: c578b9500e861456618f7a576756963cae6bfa53249123b23c7a57363c4cc4993dd796865b42c43d2ff8edd38d9b9d6823ec6b4388da26d43858a38fec9a922f

data/.github/workflows/rspec.yml

@@ -0,0 +1,27 @@
+name: RSpec Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0', '3.1']
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rspec
+    - name: Upload test results
+      uses: actions/upload-artifact@v3
+      if: failure()
+      with:
+        name: rspec-results
+        path: tmp/rspec_results

data/.gitignore

@@ -0,0 +1,32 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+.byebug_history
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+.rvmrc
+.ruby-version
+.ruby-gemset
+/tmp
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in swarm.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,56 @@
+PATH
+  remote: .
+  specs:
+    ruby-openai-swarm (0.1.0)
+      ruby-openai (~> 7.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.2.0)
+    coderay (1.1.3)
+    diff-lcs (1.5.1)
+    event_stream_parser (1.0.0)
+    faraday (2.8.1)
+      base64
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-multipart (1.0.4)
+      multipart-post (~> 2)
+    faraday-net_http (3.0.2)
+    method_source (1.1.0)
+    multipart-post (2.4.1)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rake (13.2.1)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    ruby-openai (7.3.1)
+      event_stream_parser (>= 0.3.0, < 2.0.0)
+      faraday (>= 1)
+      faraday-multipart (>= 1)
+    ruby2_keywords (0.0.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  pry
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  ruby-openai-swarm!
+
+BUNDLED WITH
+   2.1.4

data/README.md

@@ -0,0 +1,141 @@
+![Swarm Logo](assets/logo-swarm.png)
+
+# Ruby OpenAI Swarm
+
+[![rspec](https://github.com/graysonchen/ruby-openai-swarm/actions/workflows/rspec.yml/badge.svg)](https://github.com/graysonchen/ruby-openai-swarm/actions)
+
+A Ruby-based educational framework adapted from OpenAI’s [Swarm](https://github.com/openai/swarm), exploring ergonomic, lightweight multi-agent orchestration.
+
+> The primary goal of Swarm is to showcase the handoff & routines patterns explored in the [Orchestrating Agents: Handoffs & Routines](https://cookbook.openai.com/examples/orchestrating_agents) cookbook. It is not meant as a standalone library, and is primarily for educational purposes.
+
+## Contents
+- [Ruby OpenAI Swarm](#ruby-openai-swarm)
+- [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [Bundler](#bundler)
+    - [Gem install](#gem-install)
+  - [examples](#examples)
+  - [Documentation](#documentation)
+
+## Installation
+
+### Bundler
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "ruby-openai-swarm"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+### Gem install
+
+Or install with:
+
+```bash
+$ gem install ruby-openai-swarm
+```
+
+and require with:
+
+```ruby
+require "ruby-openai-swarm"
+```
+
+## Usage
+
+### With Config
+
+For a more robust setup, you can configure the gem with your API keys, for example in an `openai.rb` initializer file. Never hardcode secrets into your codebase - instead use something like [dotenv](https://github.com/motdotla/dotenv) to pass the keys safely into your environments.
+
+```ruby
+OpenAI.configure do |config|
+  config.access_token = ENV['OPENAI_ACCESS_TOKEN']
+end
+```
+
+OR
+
+```ruby
+# https://openrouter.ai
+OpenAI.configure do |config|
+  config.access_token = ENV['OPEN_ROUTER_ACCESS_TOKEN']
+  config.uri_base = "https://openrouter.ai/api/v1"
+end
+```
+
+more see: https://github.com/alexrudall/ruby-openai/tree/main?tab=readme-ov-file#ollama
+
+Then you can create a client like this:
+
+```ruby
+client = OpenAISwarm.new
+
+def spanish_agent
+  OpenAISwarm::Agent.new(
+    name: "Spanish Agent",
+    instructions: "You only speak Spanish.",
+    model: "gpt-4o-mini"
+  )
+end
+
+transfer_to_spanish_agent = OpenAISwarm::FunctionDescriptor.new(
+  target_method: :spanish_agent,
+  description: 'Transfer spanish speaking users immediately.'
+)
+
+english_agent = OpenAISwarm::Agent.new(
+  name: "English Agent",
+  instructions: "You only speak English.",
+  model: "gpt-4o-mini",
+  functions: [transfer_to_spanish_agent]
+)
+
+messages = [{"role": "user", "content": "Hola. ¿Como estás?"}]
+response = client.run(agent: english_agent, messages: messages, debug: true)
+
+pp response.messages.last
+```
+
+```ruby
+{"role"=>"assistant",
+ "content"=>"¡Hola! Estoy bien, gracias. ¿Y tú?",
+ "refusal"=>nil,
+ :sender=>"Spanish Agent"}
+```
+
+# Examples
+
+Check out `/examples` for inspiration! Learn more about each one in its README.
+
+- [X] [`basic`](examples/basic): Simple examples of fundamentals like setup, function calling, handoffs, and context variables
+- [X] [`triage_agent`](examples/triage_agent): Simple example of setting up a basic triage step to hand off to the right agent
+- [X] [`weather_agent`](examples/weather_agent): Simple example of function calling
+- [ ] [`airline`](examples/airline): A multi-agent setup for handling different customer service requests in an airline context.
+- [ ] [`support_bot`](examples/support_bot): A customer service bot which includes a user interface agent and a help center agent with several tools
+- [ ] [`personal_shopper`](examples/personal_shopper): A personal shopping agent that can help with making sales and refunding orders
+
+link: https://github.com/openai/swarm/tree/main?tab=readme-ov-file#examples
+
+## Documentation
+![Swarm Diagram](https://raw.githubusercontent.com/openai/swarm/refs/heads/main/assets/swarm_diagram.png)
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/graysonchen/ruby-openai-swarm. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/graysonchen/ruby-openai-swarm/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ruby-openai-swarm"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ruby-openai-swarm"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/examples/basic/agent_handoff.rb

@@ -0,0 +1,41 @@
+# link: https://github.com/openai/swarm/blob/main/examples/basic/agent_handoff.py
+
+# OpenAI.configure do |config|
+#   config.access_token = ENV['OPENAI_ACCESS_TOKEN']
+# end
+
+OpenAI.configure do |config|
+  config.access_token = ENV['OPEN_ROUTER_ACCESS_TOKEN']
+  config.uri_base = "https://openrouter.ai/api/v1"
+end
+
+client = OpenAISwarm.new
+
+def spanish_agent
+  OpenAISwarm::Agent.new(
+    name: "Spanish Agent",
+    instructions: "You only speak Spanish.",
+    model: "gpt-4o-mini"
+  )
+end
+
+transfer_to_spanish_agent = OpenAISwarm::FunctionDescriptor.new(
+  target_method: :spanish_agent,
+  description: 'Transfer spanish speaking users immediately.'
+)
+
+english_agent = OpenAISwarm::Agent.new(
+  name: "English Agent",
+  instructions: "You only speak English.",
+  model: "gpt-4o-mini",
+  functions: [transfer_to_spanish_agent]
+)
+
+messages = [{"role": "user", "content": "Hola. ¿Como estás?"}]
+response = client.run(agent: english_agent, messages: messages, debug: true)
+
+p response.messages.last
+# => {"role"=>"assistant", "content"=>"¡Hola! Estoy bien, gracias. ¿Y tú?", "refusal"=>nil, :sender=>"Spanish Agent"}
+
+msg = response.messages.last
+msg['sender'] == "Spanish Agent"

data/examples/basic/bare_minimum.rb

@@ -0,0 +1,27 @@
+require "bundler/setup"
+require "ruby-openai-swarm"
+
+# link: https://github.com/openai/swarm/blob/main/examples/basic/bare_minimum.py
+
+# OpenAI.configure do |config|
+#   config.access_token = ENV['OPENAI_ACCESS_TOKEN']
+# end
+
+OpenAI.configure do |config|
+  config.access_token = ENV['OPEN_ROUTER_ACCESS_TOKEN']
+  config.uri_base = "https://openrouter.ai/api/v1"
+end
+
+client = OpenAISwarm.new
+
+agent = OpenAISwarm::Agent.new(
+  name: "Agent",
+  instructions: "You are a helpful agent.",
+  model: "gpt-4o-mini"
+)
+messages = [{"role": "user", "content": "Hi!"}]
+response = client.run(agent: agent, messages: messages)
+p response.messages.last["content"]
+#  => "Hello! How can I assist you today?"
+p response.messages
+# => [{"role"=>"assistant", "content"=>"Hello! How can I assist you today?", "refusal"=>nil, :sender=>"Agent"}]

data/examples/basic/context_variables.rb

@@ -0,0 +1,67 @@
+# link: https://github.com/openai/swarm/blob/main/examples/basic/context_variables.py
+
+# OpenAI.configure do |config|
+#   config.access_token = ENV['OPENAI_ACCESS_TOKEN']
+# end
+OpenAI.configure do |config|
+  config.access_token = ENV['OPEN_ROUTER_ACCESS_TOKEN']
+  config.uri_base = "https://openrouter.ai/api/v1"
+end
+
+client = OpenAISwarm.new
+
+def instructions(context_variables)
+  name = context_variables.fetch(:name, :User)
+  "You are a helpful agent. Greet the user by name (#{name})."
+end
+
+def print_account_details(context_variables: {})
+  puts "print_account_details context_variables: #{context_variables.inspect}"
+
+  user_id = context_variables[:user_id]
+  name = context_variables[:name]
+  puts "Account Details: name: #{name}, user_id: #{user_id}"
+  "Success"
+end
+
+function_instance = OpenAISwarm::FunctionDescriptor.new(
+  target_method: :print_account_details,
+)
+
+agent = OpenAISwarm::Agent.new(
+  name: "Agent",
+  instructions: method(:instructions),
+  model: "gpt-4o-mini",
+  functions: [function_instance]
+)
+
+context_variables = { 'name': 'James', 'user_id': 123 }
+
+# debugger logger: {:model=>"gpt-4o-mini", :messages=>[{:role=>"system", :content=>"You are a helpful agent. Greet the user by name (James)."}, {:role=>"user", :content=>"Hi!"}], :tools=>[{:type=>"function", :function=>{:name=>"print_account_details", :description=>"", :parameters=>{:type=>"object", :properties=>{}, :required=>[]}}}], :stream=>false, :parallel_tool_calls=>true}
+response = client.run(
+  messages: [{"role": "user", "content": "Hi!"}],
+  agent: agent,
+  context_variables: context_variables,
+  debug: true,
+)
+msg = response.messages.last
+# Hello, James! How can I assist you today?
+
+msg['content'].include?('James')
+
+# debugger logger: {:model=>"gpt-4o-mini", :messages=>[{:role=>"system", :content=>"You are a helpful agent. Greet the user by name (James)."}, {:role=>"user", :content=>"Print my account details!"}], :tools=>[{:type=>"function", :function=>{:name=>"print_account_details", :description=>"", :parameters=>{:type=>"object", :properties=>{}, :required=>[]}}}], :stream=>false, :parallel_tool_calls=>true
+response = client.run(
+  messages: [{"role": "user", "content": "Print my account details!"}],
+  agent: agent,
+  context_variables: context_variables,
+  debug: true,
+)
+msg = response.messages.last
+msg['content']
+response.context_variables == {:name=>"James", :user_id=>123}
+
+# print(response.messages[-1]["content"])
+# Hello, James! Your account details have been printed successfully. If you need anything else, just let me know!
+#
+# print_account_details context_variables: {:name=>"James", :user_id=>123}
+# Account Details: name: James, user_id: 123

data/examples/basic/function_calling.rb

@@ -0,0 +1,32 @@
+
+OpenAI.configure do |config|
+  config.access_token = ENV['OPEN_ROUTER_ACCESS_TOKEN']
+  config.uri_base = "https://openrouter.ai/api/v1"
+end
+
+client = OpenAISwarm.new
+
+def get_weather(location:)
+  "{'temp':67, 'unit':'F'}"
+end
+
+function_instance = OpenAISwarm::FunctionDescriptor.new(
+  target_method: :get_weather,
+  description: 'Simulate fetching weather data'
+)
+
+agent = OpenAISwarm::Agent.new(
+  name: "Agent",
+  instructions: "You are a helpful agent.",
+  model: "gpt-4o-mini",
+  functions: [function_instance]
+)
+# debugger logger: {:model=>"gpt-4o-mini", :messages=>[{:role=>"system", :content=>"You are a helpful agent."}, {"role"=>"user", "content"=>"What's the weather in NYC?"}], :tools=>[{:type=>"function", :function=>{:name=>"get_weather", :description=>"", :parameters=>{:type=>"object", :properties=>{:location=>{:type=>"string"}}, :required=>["location"]}}}], :stream=>false, :parallel_tool_calls=>true}
+response = client.run(
+  messages: [{"role" => "user", "content" => "What's the weather in NYC?"}],
+  agent: agent,
+  debug: true,
+)
+
+# print(response.messages[-1]["content"])
+# The current temperature in New York City is 67°F. => nil

data/examples/basic/simple_loop_no_helpers.rb

@@ -0,0 +1,38 @@
+
+OpenAI.configure do |config|
+  config.access_token = ENV['OPEN_ROUTER_ACCESS_TOKEN']
+  config.uri_base = "https://openrouter.ai/api/v1"
+end
+
+client = OpenAISwarm.new
+
+agent = OpenAISwarm::Agent.new(
+  name: "Agent",
+  instructions: "You are a helpful agent.",
+  model: "gpt-4o-mini",
+)
+
+def pretty_print_messages(messages)
+  messages.each do |message|
+    next if message["content"].nil?
+    puts "#{message["sender"]}: #{message["content"]}"
+  end
+end
+
+messages = []
+agent = my_agent
+loop do
+  print "> "
+  user_input = gets.chomp
+
+  break if user_input.downcase == "exit"
+
+  messages << { "role": "user", "content": user_input }
+  response = client.run(agent: agent, messages: messages)
+
+  messages.concat(response.messages)
+  agent = response.agent
+
+  pretty_print_messages(response.messages)
+end
+puts "Goodbye!"

data/examples/triage_agent/README.md

@@ -0,0 +1,34 @@
+# Triage agent
+
+This example is a Swarm containing a triage agent, which takes in user inputs and chooses whether to respond directly, or triage the request
+to a sales or refunds agent.
+
+## Setup
+
+To run the triage agent Swarm:
+
+1. Run
+
+```shell
+ruby main.rb
+```
+or
+
+```shell
+ruby examples/triage_agent/main.rb
+```
+
+## Evals (TODO)
+
+> [!NOTE]
+> These evals are intended to be examples to demonstrate functionality, but will have to be updated and catered to your particular use case.
+
+This example uses `Pytest` to run eval unit tests. We have two tests in the `evals.py` file, one which
+tests if we call the correct triage function when expected, and one which assesses if a conversation
+is 'successful', as defined in our prompt in `evals.py`.
+
+To run the evals, run
+
+```shell
+ruby evals.rb
+```

data/examples/triage_agent/agents.rb

@@ -0,0 +1,84 @@
+require "bundler/setup"
+require "ruby-openai-swarm"
+
+OpenAI.configure do |config|
+  config.access_token = ENV['OPEN_ROUTER_ACCESS_TOKEN']
+  config.uri_base = "https://openrouter.ai/api/v1"
+end
+
+def client
+  OpenAISwarm.new
+end
+
+def process_refund(item_id, reason = "NOT SPECIFIED")
+  # Refund an item. Make sure you have the item_id of the form item_...
+  # Ask for user confirmation before processing the refund.
+  puts "[mock] Refunding item #{item_id} because #{reason}..."
+  "Success!"
+end
+
+def process_refund_function_instance
+  OpenAISwarm::FunctionDescriptor.new(
+    target_method: :process_refund,
+    description: "Refund an item. Make sure you have the item_id of the form item_...Ask for user confirmation before processing the refund."
+  )
+end
+
+def apply_discount
+  # Apply a discount to the user's cart.
+  puts "[mock] Applying discount..."
+  "Applied discount of 11%"
+end
+
+def apply_discount_function_instance
+  OpenAISwarm::FunctionDescriptor.new(
+    target_method: :apply_discount,
+    description: "Apply a discount to the user's cart."
+  )
+end
+
+def triage_agent
+  @triage_agent ||=
+    OpenAISwarm::Agent.new(
+      name: "Triage Agent",
+      instructions: "Determine which agent is best suited to handle the user's request, and transfer the conversation to that agent."
+    )
+end
+
+def sales_agent
+  @sales_agent ||=
+    OpenAISwarm::Agent.new(
+      name: "Sales Agent",
+      instructions: "Be super enthusiastic about selling bees."
+    )
+end
+
+def refunds_agent
+  @refunds_agent ||=
+    OpenAISwarm::Agent.new(
+      name: "Refunds Agent",
+      instructions: "Help the user with a refund. If the reason is that it was too expensive, offer the user a refund code. If they insist, then process the refund.",
+      functions: [
+        process_refund_function_instance,
+        apply_discount_function_instance
+      ]
+    )
+end
+
+transfer_back_to_triage = OpenAISwarm::FunctionDescriptor.new(
+  target_method: :triage_agent,
+  description: "Call this function if a user is asking about a topic that is not handled by the current agent."
+)
+
+def transfer_to_sales
+  sales_agent
+end
+
+def transfer_to_refunds
+  refunds_agent
+end
+
+# Assign functions to agents
+triage_agent.functions = [method(:transfer_to_sales), method(:transfer_to_refunds)]
+sales_agent.functions << transfer_back_to_triage
+refunds_agent.functions << transfer_back_to_triage

data/examples/triage_agent/main.rb

@@ -0,0 +1,3 @@
+require_relative "agents"
+
+OpenAISwarm::Repl.run_demo_loop(triage_agent)