mars_rb 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 847ba01853f9e5790faa121b22100fec0949826073843d2adbf07cd94806bdc0
-  data.tar.gz: 762a09a870b24bfaa622e87fd541af619fc24f96bd40adaf6a20562e45cd3987
+  metadata.gz: d9e07825e09769cad8d18f5b603b35031e2b1865f3cefab4232820e6740b5d09
+  data.tar.gz: 1245c01d79b166086c1138ce225dac87930f2f0e0cb24c8019908212a7235c34
 SHA512:
-  metadata.gz: e7ed3ad66f6bf77e4178eeae56f0d6eb27d2def10addb7841f80334e7a5ef33d5f6a3cba03cfb40cf07c6ca9e2c9b5be882063d67bd2f41c6443e3152215cc1b
-  data.tar.gz: 8c50f289df8e48e0ba0f89a8703f7c851e06ed88a93b15c640c7fbde03eea7b6f24fbfb1818caf9231b61e17b7d75728d34b3884aac1017c87715e7fa9475f97
+  metadata.gz: ef9998fc5881a51188f3ba533271cfee3f362fc42f7cba7fec34e03d93043758048fde5b9f5ea9e1a5a581c0539f64e1b1828fe5dc5bcb86dcb06aa9ed744e2d
+  data.tar.gz: 63473c75d3bd7b990c4aded7589c6b6edc201ffa36c6aef0bae62640d210278b913b5a45b229890f54956ce2e749620dd3f256c1be4773cf000b0d8b84675a0c

data/.rubocop.yml

@@ -1,9 +1,35 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
 AllCops:
   TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+  - "examples/**/*"
+  - "vendor/**/*"
 
 Lint/MissingSuper:
   Enabled: false
 
+Metrics/MethodLength:
+  Enabled: true
+  Exclude:
+  - "lib/mars/workflows/parallel.rb"
+  - "lib/mars/rendering/html.rb"
+  - "lib/mars/workflows/sequential.rb"
+
+Metrics/ParameterLists:
+  Enabled: true
+  Exclude:
+  - "lib/mars/agent.rb"
+
+Metrics/AbcSize:
+  Enabled: true
+  Exclude:
+  - "lib/mars/rendering/graph/parallel_workflow.rb"
+  - "lib/mars/workflows/sequential.rb"
+
 Style/Documentation:
   Enabled: false
 
@@ -12,3 +38,15 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/VerifiedDoubleReference:
+  Enabled: false

data/README.md

@@ -1,28 +1,165 @@
-# Mars
+# MARS (Multi-Agent Ruby SDK)
 
-TODO: Delete this and the text below, and describe your gem
+[![Gem Version](https://badge.fury.io/rb/mars_rb.svg)](https://badge.fury.io/rb/mars_rb)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/mars`. To experiment with that code, run `bin/console` for an interactive prompt.
+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](https://github.com/gbaptista/ruby_llm)
+- 🛠️ **Tools & Schemas**: Define custom tools and structured outputs for agents
+
+## Requirements
+
+- Ruby >= 3.1.0
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem 'mars_rb'
+```
+
+And then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it yourself as:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install mars_rb
 ```
 
-## Usage
+## Quick Start
+
+Here's a simple example to get you started:
+
+```ruby
+require 'mars'
+
+# Define agents
+class Agent1 < MARS::Agent
+end
+
+class Agent2 < MARS::Agent
+end
+
+class Agent3 < MARS::Agent
+end
+
+# Create agents
+agent1 = Agent1.new
+agent2 = Agent2.new
+agent3 = Agent3.new
+
+# 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")
+```
 
-TODO: Write usage instructions here
+## Core Concepts
+
+### Agents
+
+Agents are the basic building blocks of MARS. They represent individual units of work:
+
+```ruby
+class CustomAgent < MARS::Agent
+  def system_prompt
+    "You are a helpful assistant"
+  end
+end
+
+agent = CustomAgent.new(
+  options: { model: "gpt-4o" }
+)
+```
+
+### Sequential Workflows
+
+Execute agents one after another, passing outputs as inputs:
+
+```ruby
+sequential = MARS::Workflows::Sequential.new(
+  "Sequential Pipeline",
+  steps: [agent1, agent2, agent3]
+)
+```
+
+### Parallel Workflows
+
+Run multiple agents concurrently and aggregate their results:
+
+```ruby
+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
+
+Gates act as guards that either let the workflow continue or divert to a fallback path:
+
+```ruby
+gate = MARS::Gate.new(
+  "Validation Gate",
+  check: ->(input) { :failure unless input[:score] > 0.5 },
+  fallbacks: {
+    failure: failure_workflow
+  }
+)
+```
+
+Control halt scope — `:local` (default) stops only the parent workflow, `:global` propagates to the root:
+
+```ruby
+gate = MARS::Gate.new(
+  "Critical Gate",
+  check: ->(input) { :error unless input[:valid] },
+  fallbacks: { error: error_workflow },
+  halt_scope: :global
+)
+```
+
+### Visualization
+
+Generate Mermaid diagrams to visualize your workflows:
+
+```ruby
+diagram = MARS::Rendering::Mermaid.new(workflow).render
+File.write("workflow_diagram.md", diagram)
+```
+
+## Examples
+
+Check out the [examples](examples/) directory for more detailed examples:
+
+- [Simple Workflow](examples/simple_workflow/) - Basic sequential workflow with gates
+- [Parallel Workflow](examples/parallel_workflow/) - Concurrent agent execution
+- [Complex Workflow](examples/complex_workflow/) - Nested workflows with multiple gates
+- [Complex LLM Workflow](examples/complex_llm_workflow/) - Real-world LLM integration with tools and schemas
 
 ## Development
 
@@ -30,14 +167,48 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 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](https://rubygems.org).
 
+## Testing
+
+Run the test suite with:
+
+```bash
+bundle exec rake spec
+```
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mars. 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/[USERNAME]/mars/blob/main/CODE_OF_CONDUCT.md).
+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](https://github.com/rootstrap/mars/blob/main/CODE_OF_CONDUCT.md).
+
+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](https://opensource.org/licenses/MIT).
 
+## Support
+
+- 🐛 [Issue Tracker](https://github.com/rootstrap/mars/issues)
+
+## Related Projects
+
+- [ruby_llm](https://github.com/gbaptista/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](https://github.com/[USERNAME]/mars/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the MARS project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rootstrap/mars/blob/main/CODE_OF_CONDUCT.md).
+
+## Credits
+
+Created and maintained by [Rootstrap](https://www.rootstrap.com).

data/examples/complex_llm_workflow/diagram.md

@@ -0,0 +1,32 @@
+```mermaid
+flowchart LR
+in((In))
+out((Out))
+agent1[agent1]
+gate{Gate}
+parallel_workflow_aggregator[Parallel workflow Aggregator]
+agent2[agent2]
+agent3[agent3]
+agent4[agent4]
+subgraph parallel_workflow["Parallel workflow"]
+  agent2
+  agent3
+  agent4
+end
+subgraph sequential_workflow["Sequential workflow"]
+  agent1
+  gate
+  parallel_workflow
+  parallel_workflow_aggregator
+end
+in --> agent1
+agent1 --> gate
+gate -->|failure| out
+gate --> agent2
+gate --> agent3
+gate --> agent4
+agent2 --> parallel_workflow_aggregator
+parallel_workflow_aggregator --> out
+agent3 --> parallel_workflow_aggregator
+agent4 --> parallel_workflow_aggregator
+```

data/examples/complex_llm_workflow/generator.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/mars"
+
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
+end
+
+# Define schema for sports
+class SportsSchema < RubyLLM::Schema
+  array :sports do
+    object do
+      string :name
+      array :top_3_players do
+        string :name
+      end
+    end
+  end
+end
+
+# Define weather tool
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+
+  params do
+    string :latitude, description: "Latitude (e.g., 52.5200)"
+    string :longitude, description: "Longitude (e.g., 13.4050)"
+  end
+
+  def execute(latitude:, longitude:)
+    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
+    response = Net::HTTP.get_response(URI(url))
+    JSON.parse(response.body)
+  rescue StandardError => e
+    { error: e.message }
+  end
+end
+
+class ExampleAgent < RubyLLM::Agent
+  instructions "You are a helpful assistant that can answer questions.
+     When asked about a country, only answer with its name."
+end
+
+class Agent1 < MARS::AgentStep
+  agent ExampleAgent
+end
+
+class FoodAgent < RubyLLM::Agent
+  instructions "You are a helpful assistant that can answer questions and help with tasks.
+     Return information about the typical food of the country."
+end
+
+class Agent2 < MARS::AgentStep
+  agent FoodAgent
+end
+
+class SportsAgent < RubyLLM::Agent
+  instructions "You are a helpful assistant that can answer questions and help with tasks.
+     Return information about the popular sports of the country."
+  schema SportsSchema
+end
+
+class Agent3 < MARS::AgentStep
+  agent SportsAgent
+end
+
+class WeatherAgent < RubyLLM::Agent
+  instructions "You are a helpful assistant that can answer questions and help with tasks.
+     Return the current weather of the country's capital."
+  tools Weather
+end
+
+class Agent4 < MARS::AgentStep
+  agent WeatherAgent
+end
+
+# Create the LLMs
+llm1 = Agent1.new
+llm2 = Agent2.new
+llm3 = Agent3.new
+llm4 = Agent4.new
+
+parallel_workflow = MARS::Workflows::Parallel.new(
+  "Parallel workflow",
+  steps: [llm2, llm3, llm4]
+)
+
+error_workflow = MARS::Workflows::Sequential.new(
+  "Error workflow",
+  steps: []
+)
+
+gate = MARS::Gate.new(
+  check: ->(input) { :failure unless input.split.length < 10 },
+  fallbacks: {
+    failure: error_workflow
+  }
+)
+
+sequential_workflow = MARS::Workflows::Sequential.new(
+  "Sequential workflow",
+  steps: [llm1, gate, parallel_workflow]
+)
+
+# Generate and save the diagram
+diagram = MARS::Rendering::Mermaid.new(sequential_workflow).render
+File.write("examples/complex_llm_workflow/diagram.md", diagram)
+puts "Complex workflow diagram saved to: examples/complex_llm_workflow/diagram.md"
+
+# Run the workflow
+puts sequential_workflow.run("Which is the largest country in Europe?")

data/examples/complex_workflow/diagram.md

@@ -0,0 +1,47 @@
+```mermaid
+flowchart LR
+in((In))
+out((Out))
+step1[step1]
+gate{Gate}
+step4[step4]
+parallel_workflow_aggregator[Parallel workflow Aggregator]
+step2[step2]
+step3[step3]
+parallel_workflow_2_aggregator[Parallel workflow 2 Aggregator]
+step5[step5]
+subgraph parallel_workflow_2["Parallel workflow 2"]
+  sequential_workflow
+  step5
+end
+subgraph parallel_workflow["Parallel workflow"]
+  step2
+  step3
+end
+subgraph sequential_workflow["Sequential workflow"]
+  step4
+  parallel_workflow
+  parallel_workflow_aggregator
+end
+subgraph main_pipeline["Main Pipeline"]
+  step1
+  gate
+  parallel_workflow_aggregator
+  parallel_workflow_2
+  parallel_workflow_2_aggregator
+end
+in --> step1
+step1 --> gate
+gate -->|warning| step4
+gate -->|error| step2
+gate -->|error| step3
+gate --> step4
+gate --> step5
+step4 --> step2
+step4 --> step3
+step2 --> parallel_workflow_aggregator
+parallel_workflow_aggregator --> parallel_workflow_2_aggregator
+step3 --> parallel_workflow_aggregator
+parallel_workflow_2_aggregator --> out
+step5 --> parallel_workflow_2_aggregator
+```

data/examples/complex_workflow/generator.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/mars"
+
+class Step1Formatter < MARS::Formatter
+  def format_output(context)
+    context + ['formatted']
+  end
+end
+
+class Step1 < MARS::Runnable
+  after_run do |context, result|
+    puts "after run from Step1 #{result}"
+  end
+  formatter Step1Formatter
+
+  def run(context)
+    context.current_input + ['step1']
+  end
+end
+
+class Step2 < MARS::Runnable
+  after_run do |context, result|
+    puts "after run from Step2 #{result}"
+  end
+
+  def run(context)
+    context.current_input + ['step2']
+  end
+end
+
+class Step3 < MARS::Runnable
+  after_run do |context, result|
+   puts "after run from Step3 #{result}"
+  end
+
+  def run(context)
+    context.current_input + ['step3']
+  end
+end
+
+class Step4 < MARS::Runnable
+  after_run do |context, result|
+    puts "after run from Step4 #{result}"
+  end
+
+  def run(context)
+    context.current_input + ['step4']
+  end
+end
+
+class Step5 < MARS::Runnable
+  after_run do |context, result|
+    puts "after run from Step5 #{result}"
+  end
+
+  def run(context)
+    context.current_input + ['step5']
+  end
+end
+
+# Create the Steps
+step1 = Step1.new
+step2 = Step2.new
+step3 = Step3.new
+step4 = Step4.new
+step5 = Step5.new
+
+# Create a parallel workflow (STEP 2 x STEP 3)
+parallel_workflow = MARS::Workflows::Parallel.new(
+  "Parallel workflow",
+  steps: [step2, step3]
+)
+
+# Create a sequential workflow (Parallel workflow -> LLM 4)
+sequential_workflow = MARS::Workflows::Sequential.new(
+  "Sequential workflow",
+  steps: [step4, parallel_workflow]
+)
+
+# Create a parallel workflow (Sequential workflow x LLM 5)
+parallel_workflow2 = MARS::Workflows::Parallel.new(
+  "Parallel workflow 2",
+  steps: [sequential_workflow, step5]
+)
+
+# Create the gate that decides between exit or continue
+gate = MARS::Gate.new(
+  check: ->(input) { :default if input == ["start", "step1", "formatted"] },
+  fallbacks: {
+    warning: sequential_workflow,
+    error: parallel_workflow
+  }
+)
+
+# Create the main workflow: LLM 1 -> Gate
+main_workflow = MARS::Workflows::Sequential.new(
+  "Main Pipeline",
+  steps: [step1, gate, parallel_workflow2]
+)
+
+main_workflow.run(["start"])
+
+# Generate and save the diagram
+diagram = MARS::Rendering::Mermaid.new(main_workflow).render
+File.write("examples/complex_workflow/diagram.md", diagram)
+puts "Complex workflow diagram saved to: examples/complex_workflow/diagram.md"

data/examples/parallel_workflow/diagram.md

@@ -0,0 +1,21 @@
+```mermaid
+flowchart LR
+in((In))
+out((Out))
+aggregator[Aggregator]
+agent1[agent1]
+agent2[agent2]
+agent3[agent3]
+subgraph parallel_workflow["Parallel workflow"]
+  agent1
+  agent2
+  agent3
+end
+in --> agent1
+in --> agent2
+in --> agent3
+agent1 --> aggregator
+aggregator --> out
+agent2 --> aggregator
+agent3 --> aggregator
+```

data/examples/parallel_workflow/generator.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/mars"
+
+# Define the LLMs
+class Agent1 < MARS::AgentStep
+end
+
+class Agent2 < MARS::AgentStep
+end
+
+class Agent3 < MARS::AgentStep
+end
+
+# Create the LLMs
+llm1 = Agent1.new
+llm2 = Agent2.new
+llm3 = Agent3.new
+
+aggregator = MARS::Aggregator.new("Aggregator", operation: lambda(&:sum))
+
+# Create the parallel workflow (LLM 1, LLM 2, LLM 3)
+parallel_workflow = MARS::Workflows::Parallel.new(
+  "Parallel workflow",
+  steps: [llm1, llm2, llm3],
+  aggregator: aggregator
+)
+
+# Generate and save the diagram
+diagram = MARS::Rendering::Mermaid.new(parallel_workflow).render
+File.write("examples/parallel_workflow/diagram.md", diagram)
+puts "Parallel workflow diagram saved to: examples/parallel_workflow/diagram.md"

data/examples/simple_workflow/diagram.md

@@ -0,0 +1,26 @@
+```mermaid
+flowchart LR
+in((In))
+out((Out))
+agent1[agent1]
+gate{Gate}
+agent4[agent4]
+agent2[agent2]
+agent3[agent3]
+subgraph failure_workflow["Failure workflow"]
+  agent4
+end
+subgraph main_pipeline["Main Pipeline"]
+  agent1
+  gate
+  agent4
+  agent2
+  agent3
+end
+in --> agent1
+agent1 --> gate
+gate -->|failure| agent4
+gate --> agent2
+agent2 --> agent3
+agent3 --> out
+```