MARS (Multi-Agent Ruby SDK)

MARS (Multi-Agent Ruby SDK) provides a comprehensive framework for developers to implement multi-agent solutions using pure Ruby. It offers a simple, intuitive API for orchestrating multiple agents with support for sequential and parallel workflows, conditional branching, and visual workflow diagrams.

Features

• 🤖 Agent Orchestration: Coordinate multiple agents with ease
• 🔄 Sequential Workflows: Chain agents to execute tasks in order
• ⚡ Parallel Workflows: Run multiple agents concurrently
• 🚦 Conditional Gates: Branch workflows based on runtime conditions
• 🔧 Aggregators: Combine results from parallel operations
• 📊 Visual Diagrams: Generate Mermaid diagrams of your workflows
• 🔌 LLM Integration: Built-in support for LLM agents via ruby_llm
• 🛠️ Tools & Schemas: Define custom tools and structured outputs for agents

Requirements

• Ruby >= 3.1.0

Installation

Add this line to your application's Gemfile:

gem 'mars_rb'

And then execute:

bundle install

Or install it yourself as:

gem install mars_rb

Quick Start

Here's a simple example to get you started:

require 'mars'

# Create agents
agent1 = Mars::Agent.new(name: "Agent 1")
agent2 = Mars::Agent.new(name: "Agent 2")
agent3 = Mars::Agent.new(name: "Agent 3")

# Create a sequential workflow
workflow = Mars::Workflows::Sequential.new(
  "My First Workflow",
  steps: [agent1, agent2, agent3]
)

# Run the workflow
result = workflow.run("Your input here")

Core Concepts

Agents

Agents are the basic building blocks of MARS. They represent individual units of work:

agent = Mars::Agent.new(
  name: "My Agent",
  instructions: "You are a helpful assistant",
  options: { model: "gpt-4o" }
)

Sequential Workflows

Execute agents one after another, passing outputs as inputs:

sequential = Mars::Workflows::Sequential.new(
  "Sequential Pipeline",
  steps: [agent1, agent2, agent3]
)

Parallel Workflows

Run multiple agents concurrently and aggregate their results:

aggregator = Mars::Aggregator.new(
  "Results Aggregator",
  operation: lambda { |results| results.join(", ") }
)

parallel = Mars::Workflows::Parallel.new(
  "Parallel Pipeline",
  steps: [agent1, agent2, agent3],
  aggregator: aggregator
)

Gates

Create conditional branching in your workflows:

gate = Mars::Gate.new(
  name: "Decision Gate",
  condition: ->(input) { input[:score] > 0.5 ? :success : :failure },
  branches: {
    success: success_workflow,
    failure: failure_workflow
  }
)

Visualization

Generate Mermaid diagrams to visualize your workflows:

diagram = Mars::Rendering::Mermaid.new(workflow).render
File.write("workflow_diagram.md", diagram)

Examples

Check out the examples directory for more detailed examples:

• Simple Workflow - Basic sequential workflow with gates
• Parallel Workflow - Concurrent agent execution
• Complex Workflow - Nested workflows with multiple gates
• Complex LLM Workflow - Real-world LLM integration with tools and schemas

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 the created tag, and push the .gem file to rubygems.org.

Testing

Run the test suite with:

bundle exec rake spec

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rootstrap/mars. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

To contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to:

• Write tests for new features
• Update documentation as needed
• Follow the existing code style
• Ensure all tests pass before submitting

License

The gem is available as open source under the terms of the MIT License.

Support

• 🐛 Issue Tracker

Related Projects

• ruby_llm - Ruby interface for LLM providers

Code of Conduct

Everyone interacting in the Mars project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Credits

Created and maintained by Rootstrap.