swarm-agent 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: feee17f54f7b9bfd3b044457087d2dd3c581700b89e7b86d1de5dee600321c8a
+  data.tar.gz: 79f565ee94e692d163d152f696b0d1ec0800efdbd6d533c43b14b60d5d710545
+SHA512:
+  metadata.gz: eaaebb83be4304001ef0d87abe365c005ca95d28254a8c9deba510a1048f197cf8f4ee6109268f1fe72f12e8c498c8ad74e3ed190aed4f6c0e664e11955604a3
+  data.tar.gz: 3a24b50dae453d2a4fee8da558d644baaf069e3f51eebeaa4956eb5803bb1b25ed144b0ae617f28d95d66b74b40c7bdbb4a77b881f300b7cfdab51198449720c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 kiyo-e
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# Swarm
+
+Swarm is a Ruby library that simplifies the use of OpenAI API for chat completion and function calling.
+
+This project was inspired by [OpenAI's swarm repository](https://github.com/openai/swarm).
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem 'swarm'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it directly:
+
+```bash
+$ gem install swarm
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'swarm'
+
+# Create an agent
+agent = Swarm::Agent.new(
+  name: "assistant",
+  model: "gpt-4o-mini",
+  instructions: "You are a helpful assistant.",
+)
+
+# Create a Swarm instance
+swarm = Swarm::Swarm.new
+
+# Execute chat
+response = swarm.run(
+  agent: agent,
+  messages: [
+    { role: "user", content: "Hello!" }
+  ]
+)
+
+puts response.messages.last["content"]
+```
+
+### Using Function Calling
+
+```ruby
+def get_weather(location:)
+  "The weather in #{location} is sunny"
+end
+
+agent = Swarm::Agent.new(
+  name: "weather_bot",
+  model: "gpt-4o-mini",
+  instructions: "I am a weather information bot.",
+  functions: [method(:get_weather)]
+)
+
+swarm = Swarm::Swarm.new
+
+response = swarm.run(
+  agent: agent,
+  messages: [
+    { role: "user", content: "What's the weather in Tokyo?" }
+  ]
+)
+```
+
+### Using Streaming Response
+
+```ruby
+swarm.run(
+  agent: agent,
+  messages: messages,
+  stream: true
+) do |chunk|
+  print chunk.dig("delta", "content")
+end
+```
+
+## Environment Variables
+
+- `OPENAI_API_KEY`: Set your OpenAI API key.
+
+## Development
+
+Bug reports and pull requests are welcome at https://github.com/kiyo-e/swarm.
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/swarm/agent.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Swarm
+  class Agent
+    attr_accessor :name, :model, :instructions, :functions, :tool_choice
+
+    def initialize(name:, model:, instructions:, functions: [], tool_choice: 'auto')
+      @name = name
+      @model = model
+      @instructions = instructions
+      @functions = functions
+      @tool_choice = tool_choice
+    end
+  end
+end

data/lib/swarm/response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Swarm
+  class Response
+    attr_accessor :messages, :agent, :context_variables
+
+    def initialize(messages:, agent:, context_variables:)
+      @messages = messages
+      @agent = agent
+      @context_variables = context_variables
+    end
+  end
+end

data/lib/swarm/result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Swarm
+  class Result
+    attr_accessor :value, :agent, :context_variables
+
+    def initialize(value:, agent: nil, context_variables: {})
+      @value = value
+      @agent = agent
+      @context_variables = context_variables
+    end
+  end
+end

data/lib/swarm/swarm.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Swarm
+  CTX_VARS_NAME = 'context_variables'
+
+  class Swarm
+    attr_reader :client
+
+    def initialize(client: nil)
+      @client = client || OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
+    end
+
+    def get_chat_completion(agent:, history:, context_variables:, model_override: nil, stream: false, debug: false)
+      context_variables = Hash.new { |h, k| h[k] = '' }.merge(context_variables)
+      instructions = if agent.instructions.respond_to?(:call)
+                       agent.instructions.call(context_variables)
+                     else
+                       agent.instructions
+                     end
+      messages = [{ role: 'system', content: instructions }] + history
+      debug_print(debug, 'Getting chat completion for:', messages)
+
+      functions = agent.functions.map { |f| function_to_json(f) }
+
+      functions.each do |function|
+        params = function[:parameters]
+        params[:properties].delete(CTX_VARS_NAME)
+        params[:required]&.delete(CTX_VARS_NAME)
+      end
+
+      function_call_option = case agent.tool_choice
+                             when 'required'
+                               'auto'
+                             when 'none'
+                               'none'
+                             else
+                               'auto'
+                             end
+
+      create_params = {
+        model: model_override || agent.model,
+        messages: messages,
+        functions: functions.empty? ? nil : functions,
+        function_call: function_call_option,
+        stream: stream
+      }
+
+      @client.chat(parameters: create_params)
+    end
+
+    def handle_function_result(result, debug)
+      case result
+      when Result
+        result
+      when Agent
+        Result.new(value: { assistant: result.name }.to_json, agent: result)
+      else
+        begin
+          Result.new(value: result.to_s)
+        rescue StandardError => e
+          error_message = "Failed to cast response to string: #{result}. Ensure that agent functions return a string or Result object. Error: #{e.message}"
+          debug_print(debug, error_message)
+          raise TypeError, error_message
+        end
+      end
+    end
+
+    def handle_function_calls(function_calls, functions, context_variables, debug)
+      function_map = functions.each_with_object({}) { |f, h| h[f.name] = f }
+      partial_response = Response.new(messages: [], agent: nil, context_variables: {})
+
+      function_calls.each do |function_call|
+        name = function_call['name'].to_sym
+        if function_map.key?(name)
+          args = JSON.parse(function_call['arguments'])
+          debug_print(debug, "Processing function call: #{name} with arguments #{args}")
+
+          func = function_map[name]
+          if func.method(:call).parameters.any? { |_, param_name| param_name == CTX_VARS_NAME.to_sym }
+            args[CTX_VARS_NAME] = context_variables
+          end
+          raw_result = func.call(**args.transform_keys(&:to_sym))
+
+          result = handle_function_result(raw_result, debug)
+          partial_response.messages << {
+            role: 'function',
+            name: name,
+            content: result.value
+          }
+          partial_response.context_variables.merge!(result.context_variables || {})
+          partial_response.agent = result.agent if result.agent
+        else
+          debug_print(debug, "Function #{name} not found in function map.")
+          partial_response.messages << {
+            role: 'function',
+            name: name,
+            content: "Error: Function #{name} not found."
+          }
+        end
+      end
+
+      partial_response
+    end
+
+    def run_and_stream(agent:, messages:, context_variables: {}, model_override: nil, debug: false, max_turns: Float::INFINITY, execute_functions: true)
+      active_agent = agent
+      context_variables = Marshal.load(Marshal.dump(context_variables))
+      history = Marshal.load(Marshal.dump(messages))
+      init_len = messages.length
+
+      Enumerator.new do |y|
+        while history.length - init_len < max_turns
+          message = {
+            content: '',
+            sender: active_agent.name,
+            role: 'assistant',
+            function_call: nil
+          }
+
+          completion = get_chat_completion(
+            agent: active_agent,
+            history: history,
+            context_variables: context_variables,
+            model_override: model_override,
+            stream: true,
+            debug: debug
+          )
+
+          y << { delim: 'start' }
+          completion.each do |chunk|
+            delta = chunk.dig('choices', 0, 'delta') || {}
+            delta['sender'] = active_agent.name if delta['role'] == 'assistant'
+            y << delta
+            delta.delete('role')
+            delta.delete('sender')
+            merge_chunk(message, delta)
+          end
+          y << { delim: 'end' }
+
+          debug_print(debug, 'Received completion:', message)
+          history << message
+
+          function_call = message['function_call']
+          if function_call.nil? || !execute_functions
+            debug_print(debug, 'Ending turn.')
+            break
+          end
+
+          function_calls = [function_call]
+          partial_response = handle_function_calls(
+            function_calls, active_agent.functions, context_variables, debug
+          )
+          history.concat(partial_response.messages)
+          context_variables.merge!(partial_response.context_variables)
+          active_agent = partial_response.agent if partial_response.agent
+        end
+
+        y << { response: Response.new(messages: history[init_len..], agent: active_agent, context_variables: context_variables) }
+      end
+    end
+
+    def run(agent:, messages:, context_variables: {}, model_override: nil, stream: false, debug: false, max_turns: Float::INFINITY, execute_functions: true)
+      if stream
+        return run_and_stream(
+          agent: agent,
+          messages: messages,
+          context_variables: context_variables,
+          model_override: model_override,
+          debug: debug,
+          max_turns: max_turns,
+          execute_functions: execute_functions
+        )
+      end
+
+      active_agent = agent
+      context_variables = Marshal.load(Marshal.dump(context_variables))
+      history = Marshal.load(Marshal.dump(messages))
+      init_len = messages.length
+
+      while history.length - init_len < max_turns && active_agent
+        completion = get_chat_completion(
+          agent: active_agent,
+          history: history,
+          context_variables: context_variables,
+          model_override: model_override,
+          stream: false,
+          debug: debug
+        )
+        message = completion.dig('choices', 0, 'message')
+        debug_print(debug, 'Received completion:', message)
+        message['sender'] = active_agent.name
+        history << message
+
+        function_call = message['function_call']
+        if function_call.nil? || !execute_functions
+          debug_print(debug, 'Ending turn.')
+          break
+        end
+
+        function_calls = [function_call]
+        partial_response = handle_function_calls(
+          function_calls, active_agent.functions, context_variables, debug
+        )
+        history.concat(partial_response.messages)
+        context_variables.merge!(partial_response.context_variables)
+        active_agent = partial_response.agent if partial_response.agent
+      end
+
+      Response.new(
+        messages: history[init_len..],
+        agent: active_agent,
+        context_variables: context_variables
+      )
+    end
+
+    private
+
+    def merge_fields(target, source)
+      source.each do |key, value|
+        if value.is_a?(String)
+          target[key] = (target[key] || '') + value
+        elsif value.is_a?(Hash)
+          target[key] ||= {}
+          merge_fields(target[key], value)
+        end
+      end
+    end
+
+    def merge_chunk(final_response, delta)
+      delta.delete('role')
+      merge_fields(final_response, delta)
+    end
+
+    def function_to_json(func)
+      parameters = {}
+      required = []
+
+      begin
+        func.parameters.each do |type, name|
+          parameters[name.to_s] = { type: 'string' }
+          required << name.to_s if type == :req
+        end
+      rescue StandardError => e
+        raise ArgumentError, "Failed to get parameters for function #{func.name}: #{e.message}"
+      end
+
+      {
+        name: func.name.to_s,
+        description: func.respond_to?(:doc) ? func.doc : '',
+        parameters: {
+          type: 'object',
+          properties: parameters,
+          required: required
+        }
+      }
+    end
+
+    def debug_print(debug, *args)
+      return unless debug
+
+      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S')
+      message = args.map(&:to_s).join(' ')
+      puts "\e[97m[\e[90m#{timestamp}\e[97m]\e[90m #{message}\e[0m"
+    end
+  end
+end

data/lib/swarm/version.rb

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

data/lib/swarm.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openai'
+require 'swarm/version'
+require 'swarm/agent'
+require 'swarm/response'
+require 'swarm/result'
+require 'swarm/swarm'
+
+module Swarm
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: swarm-agent
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kiyo-e
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Swarm is a Ruby library that provides a simple interface for managing
+  OpenAI chat completions with function calling support. It includes features like
+  streaming responses, context management, and function execution.
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/swarm.rb
+- lib/swarm/agent.rb
+- lib/swarm/response.rb
+- lib/swarm/result.rb
+- lib/swarm/swarm.rb
+- lib/swarm/version.rb
+homepage: https://github.com/kiyo-e/swarm-agent
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kiyo-e/swarm-agent
+  changelog_uri: https://github.com/kiyo-e/swarm-agent/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.20
+signing_key:
+specification_version: 4
+summary: A Ruby library for managing OpenAI chat completions with function calling
+  support
+test_files: []