marsys 0.1.1

A powerful framework for orchestrating collaborative AI agents with sophisticated reasoning, planning, and autonomous capabilities

MARSYS - Multi-Agent Reasoning Systems

A powerful framework for orchestrating collaborative AI agents with sophisticated reasoning, planning, and autonomous capabilities

📚 Documentation | 🚀 Quick Start | 💡 Examples | 🤝 Contributing

---

📢 Latest News & Updates

🎉 MARSYS v0.1 Beta Released! (26/11/2025)

We're excited to announce the first beta release of MARSYS with major new features:

• 🌐 Dynamic Branching System: Revolutionary parallel execution with runtime branch spawning and convergence
• 🔄 Three-Way Topology: Define workflows using string notation, object-based, or pattern configurations
• 💾 State Persistence: Full pause/resume capability with checkpointing and recovery
• 👥 User Interaction Nodes: Built-in human-in-the-loop support for approval workflows and error recovery
• 📊 Enhanced Monitoring: Real-time execution tracking with StatusManager and comprehensive metrics
• 🎯 Rules Engine: Flexible constraint system for timeouts, resource limits, and custom business logic
• 🔧 Tool System: Automatic OpenAI-compatible schema generation from Python functions

Read the full release notes →

---

🌟 Key Features

Core Capabilities

• 🤖 Multi-Agent Orchestration: Coordinate complex workflows with multiple specialized agents
• ⚡ Parallel Execution: True parallel processing with AgentPool and dynamic branch spawning
• 🧠 Flexible Topologies: 7 pre-defined patterns (hub-and-spoke, pipeline, mesh, hierarchical, star, ring, broadcast)
• 💬 Conversation Management: Sophisticated memory system with retention policies
• 🛠️ Tool Integration: Seamless integration with external tools and APIs
• 🔐 Error Recovery: Intelligent error handling with retry strategies and user intervention
• 📈 Error Recovery & Observability: Advanced error handling, monitoring, and execution tracking

Advanced Features

• Dynamic Convergence: Automatic detection and synchronization of parallel branches
• Nested Execution: Hierarchical branch structures with parent-child relationships
• State Management: Persist and restore execution state across sessions
• Rule-Based Control: Define execution constraints and business logic
• Multi-Model Support: Works with OpenAI, Anthropic, Google, Groq, and local models
• Browser Automation: Built-in browser agents for web interaction
• Rich Communication: Enhanced terminal output with colors and formatting

---

🚀 Quick Start

Installation

Recommended Setup with uv (10-100x faster than pip)

Step 1: Create and activate a virtual environment

uv is the recommended package manager for MARSYS. Install it first if you haven't:

# Install uv (Unix/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or on Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Create and activate your virtual environment:

# Create virtual environment with uv
uv venv

# Activate (Unix/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Or use uv run without explicit activation
uv run python your_script.py

Step 2: Install MARSYS

Basic installation (recommended for most users):

uv pip install marsys

With local model support (PyTorch, Transformers):

uv pip install marsys[local-models]

For production inference (vLLM, Flash Attention):

uv pip install marsys[production]

For development:

uv pip install marsys[dev]

Alternative Installation Methods

Using pip (standard method)

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Unix/macOS
# .venv\Scripts\activate  # Windows

# Install
pip install marsys

From source (recommended for development)

git clone https://github.com/rezaho/MARSYS.git
cd MARSYS

# Basic installation (core framework with API model support)
pip install -e .

# Or with optional dependencies:
pip install -e .[local-models]  # Add local model support (PyTorch, Transformers)
pip install -e .[dev]           # Add development tools (testing, linting, docs)

Optional dependency groups:

• local-models: Install if you want to use local LLMs/VLMs (PyTorch, Transformers, PEFT, etc.)
• production: Install for production inference with vLLM and Flash Attention
• dev: Install for development (includes testing, linting, and documentation tools)

Required: API Key Configuration

⚠️ Before running any examples, configure your API keys:

MARSYS requires API keys for model providers. Choose one of these methods:

Method 1: Environment variables (recommended for production)

# Unix/macOS/Linux
export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"
export GOOGLE_API_KEY="your-key-here"
export OPENROUTER_API_KEY="your-key-here"

# Windows (Command Prompt)
set OPENAI_API_KEY=your-key-here

# Windows (PowerShell)
$env:OPENAI_API_KEY="your-key-here"

Method 2: .env file (recommended for development)

# Create .env file in your project root
cat > .env << EOF
OPENAI_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here
GOOGLE_API_KEY=your-key-here
OPENROUTER_API_KEY=your-key-here
EOF

MARSYS automatically loads .env files using python-dotenv.

!!! warning "Security" Never commit .env files to version control. Add .env to your .gitignore file.

Optional: Playwright Setup (Only for BrowserAgent)

⚠️ Only required if you plan to use BrowserAgent for web automation

After installing the playwright package, install browser binaries:

# Install Chromium (recommended)
playwright install chromium

# Or install all browsers
playwright install

# With system dependencies (Linux)
playwright install --with-deps chromium

If you don't use BrowserAgent, you can skip this step entirely.

Basic Usage

Here's a simple two-agent collaboration using allowed_peers:

import asyncio
from marsys.agents import Agent
from marsys.models import ModelConfig

async def main():
    # Create a single model configuration
    model_config = ModelConfig(
        type="api",
        name="anthropic/claude-haiku-4.5",
        provider="openrouter"
    )

    # Create specialized agents with allowed_peers
    researcher = Agent(
        model_config=model_config,
        name="Researcher",
        goal="Expert at finding and analyzing information",
        instruction="You are a research specialist. Find and analyze information thoroughly.",
        allowed_peers=["Writer"]  # Can invoke Writer
    )

    writer = Agent(
        model_config=model_config,
        name="Writer",
        goal="Skilled at creating clear, engaging content",
        instruction="You are a skilled writer. Create clear, engaging content based on research.",
        allowed_peers=[]  # Cannot invoke other agents
    )

    # Run with automatic topology creation from allowed_peers
    result = await researcher.auto_run(
        task="Research the latest AI breakthroughs and write a summary",
        max_steps=20,
        verbosity=1  # Show progress
    )

    print(result)

asyncio.run(main())

Three-Agent Sequential Workflow

For more control, define the topology explicitly using Orchestra.run():

import asyncio
from marsys.coordination import Orchestra
from marsys.agents import Agent
from marsys.models import ModelConfig

async def main():
    model_config = ModelConfig(
        type="api",
        name="anthropic/claude-haiku-4.5",
        provider="openrouter"
    )

    # Create three specialized agents
    data_collector = Agent(
        model_config=model_config,
        name="DataCollector",
        goal="Collects and gathers relevant data",
        instruction="You are a data collection specialist. Gather relevant information systematically."
    )

    analyzer = Agent(
        model_config=model_config,
        name="Analyzer",
        goal="Analyzes collected data and finds patterns",
        instruction="You are a data analyst. Analyze data thoroughly and identify key patterns."
    )

    reporter = Agent(
        model_config=model_config,
        name="Reporter",
        goal="Creates comprehensive reports from analysis",
        instruction="You are a report writer. Create clear, comprehensive reports from analysis results."
    )

    # Define sequential workflow
    topology = {
        "agents": ["DataCollector", "Analyzer", "Reporter"],
        "flows": [
            "DataCollector -> Analyzer",
            "Analyzer -> Reporter"
        ]
    }

    # Run the workflow
    result = await Orchestra.run(
        task="Analyze market trends in the technology sector",
        topology=topology
    )

    print(result.final_response)

asyncio.run(main())

More examples →

---

📖 Documentation

Comprehensive documentation is available at https://marsys.io

Quick Links

• Getting Started

  • Installation Guide
  • Quick Start Tutorial
  • Your First Agent

• Core Concepts

  • Agents & Memory
  • Topology System
  • Execution Flow
  • Branching Model

• API Reference

  • Orchestra API
  • Agent API
  • Configuration API
  • Complete API Docs

---

🏗️ System Architecture

MARSYS uses a sophisticated branching execution model that enables true parallel processing and dynamic workflow adaptation:

graph TD
    A[Task Input] --> B[Topology Analysis]
    B --> C[Branch Creation]
    C --> D[Agent Execution]
    D --> E{Decision Point}
    E -->|Sequential| F[Next Agent]
    E -->|Parallel| G[Spawn Branches]
    E -->|Complete| H[Result]
    G --> I[Convergence Point]
    I --> J[Aggregate Results]
    J --> F
    F --> D

Key Components

• Orchestra: High-level coordination and workflow management
• Topology System: Defines agent relationships and allowed interactions
• Branch Executor: Manages parallel execution paths
• Validation Processor: Centralizes response parsing and validation
• Rules Engine: Enforces constraints and business logic
• State Manager: Handles persistence and recovery
• Communication Manager: Manages user interactions

Architecture documentation →

---

🛣️ Roadmap

Q1 2025 - Performance & Scale

• Distributed Execution: Multi-machine agent coordination with message passing
• Advanced Caching: Intelligent result caching and memoization
• Stream Processing: Real-time streaming responses for long-running tasks

Q2 2025 - Intelligence & Learning

• Self-Optimizing Topologies: Automatic topology adjustment based on task patterns
• Agent Fine-tuning: In-workflow agent specialization and improvement
• Execution History Learning: Pattern recognition from historical executions

Q3 2025 - Advanced Features

• Workflow Designer UI: Visual topology builder and execution monitor
• Production Readiness: Performance optimizations and scalability improvements
• Advanced Observability: OpenTelemetry integration, detailed tracing, and analytics

Full roadmap →

---

📊 Use Cases

MARSYS excels in complex, multi-step workflows requiring coordination between specialized agents:

Research & Analysis

• Multi-source information gathering
• Comparative analysis across domains
• Report generation with fact-checking

Software Development

• Code generation with review cycles
• Bug analysis and fixing
• Architecture design and validation

Business Automation

• Document processing pipelines
• Customer support workflows
• Data extraction and transformation

Creative Applications

• Content generation with editing loops
• Multi-perspective storytelling
• Design iteration with feedback

More use cases →

---

🤝 Contributing

We welcome contributions from the community! MARSYS is an open-source project that thrives on collaboration.

📝 Contributor License Agreement (CLA)

Before your first contribution can be merged, you must sign our CLA. This is a one-time, automated process:

1. Open a pull request
2. CLA Assistant bot will comment with a link
3. Click the link and sign (takes 1 minute)
4. Your PR will be automatically unblocked

Why a CLA? The CLA ensures we can maintain flexible licensing while keeping MARSYS open-source:

• Enables potential dual-licensing in the future
• Protects the project's sustainability and long-term development
• Maintains licensing flexibility for the project

You retain ownership of your code and can use it elsewhere. Read the full CLA details and copyright information.

How to Contribute

1. Sign the CLA (automatic on first PR - see above)
2. Fork the repository and create your branch from main
3. Make your changes and ensure tests pass
4. Write/update tests for your changes
5. Update documentation as needed
6. Submit a pull request with clear description

Development Setup

# Clone the repository
git clone https://github.com/rezaho/MARSYS.git
cd MARSYS

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linting
flake8 src/
black src/ --check

Areas for Contribution

• 🐛 Bug fixes and improvements
• 📚 Documentation enhancements
• 🧪 Test coverage expansion
• 🎨 New agent implementations
• 🔌 Integration with external services
• 🌐 Internationalization support

Contributing guide →

---

📚 Citation

If you use MARSYS in your research or projects, please cite:

@software{marsys2025,
  author = {Hosseini, Reza},
  title = {MARSYS: Multi-Agent Reasoning Systems Framework},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/rezaho/MARSYS}
}

Academic Paper

@article{hosseini2025marsys,
  title={MARSYS: A Framework for Orchestrating Multi-Agent Reasoning Systems with Dynamic Branching and Convergence},
  author={Hosseini, Reza},
  journal={arXiv preprint arXiv:2025.xxxxx},
  year={2025}
}

---

🛡️ License

MARSYS is released under the Apache License 2.0. See LICENSE for full terms.

Copyright & Ownership

Copyright © 2025 Marsys Project Original Author: rezaho ([e-mail])

Important: The copyright is held solely by the original author. Contributors grant a license to their contributions but do not transfer copyright ownership. See COPYRIGHT for details.

Contributing

By contributing to MARSYS, you agree that your contributions will be licensed under the Apache License 2.0, subject to our Contributor License Agreement. See CONTRIBUTING.md for full contribution guidelines.

---

🙏 Acknowledgments

Special thanks to:

• The open-source community for invaluable feedback and contributions
• Model providers (OpenAI, Anthropic, Google) for their powerful APIs
• Early adopters and testers who helped shape MARSYS

---

📮 Contact & Support

• Documentation: https://marsys.io
• GitHub Issues: Bug reports and feature requests
• Discussions: Community forum
• Email: [e-mail]
• Twitter: @marsys_ai

---

Built with ❤️ by Reza Hosseini and contributors

⭐ Star us on GitHub — it helps!

Website • Documentation • Examples • Blog