Magents

Multi-Agent Generative Trading System
This is a proof of concept for an AI-powered multi-strategy hedge fund simulation and backtesting framework.

Overview

Magents is an open-source Python framework for a multi-strategy hedge fund backtesting and simulation system. The platform is designed as a multi-agent system in which independent strategy "pods" operate concurrently within a shared simulation environment. The goal is to enable realistic backtesting of multiple trading strategies under one umbrella, with unified data feeds and rigorous risk controls.

flowchart TD

    %% === DATA PIPELINE & MANAGEMENT ===
    DP[Data Pipeline] --> DM[Data Management]

    subgraph CentralTeam [Central Team Modules]
        DM
        RM[Risk Management]
        DAT[Data Team]
        AIT[AI Team]
        EXE[Execution Team]
    end

    %% === TRADING PODS ===
    subgraph Pods [Trading Pods]
        
        subgraph FundamentalPod
            F1(Agent 1: ben_graham.py)
            F2(Agent 2: cathie_wood.py)
        end

        subgraph EventDrivenPod
            E1(Agent 1: bill_ackman.py)
            E2(Agent 2: congressional_trading.py)
        end

        subgraph LongBiasedPod
            L1(Agent 1: warren_buffett.py)
            L2(Agent 2: charlie_munger.py)
        end

        subgraph QuantPod
            Q1(Agent 1: sentiment.py)
            Q2(Agent 2: sentiment_trading.py)
        end

        subgraph MacroPod
            M1(Agent 1: stanley_druckenmiller.py)
            M2(Agent 2: macro.py)
        end
    end

    %% === INTERACTIONS ===
    DM --> Pods
    Pods --> DM
    Pods --> RM
    RM --> Pods
    Pods --> BE[Backtesting Engine]
    BE --> Pods

    %% === CLI INTERFACE ===
    CLI[CLI Interface] -.-> BE

Key Features

Multi-Agent System: Each trading strategy runs as an independent "pod" with its own agents
Event-Driven Architecture: Built on an event-driven foundation for realistic simulation
Comprehensive Risk Management: Central risk controls that monitor and enforce limits
High-Fidelity Backtesting: Realistic transaction costs, slippage, and order execution
Modular Design: Easily extend with new strategies, data sources, or risk rules

High-Level Table of Main Strategy Types

Strategy Category	Definition Overview	Example Path
Arbitrage	Looks for mispricings in the same (or closely related) instruments. Encompasses convertible bond arbitrage, tail protection trades, volatility arbitrage, opportunistic arbitrage, etc.	`src/pods/strategies/arbitrage/`
Credit	Focuses on debt instruments (corporate bonds, distressed debt, direct lending, structured credit, etc.), often employing long/short relative value trades or fundamental analysis of credit quality.	`src/pods/strategies/credit/`
Equity Long/Short	Invests in global equities, both long and short. Typically fundamental-driven (value or growth) but can also incorporate technical or tactical approaches. Sub-categories include US equity L/S, APAC, Europe, global, sector-focused, etc.	`src/pods/strategies/equity_ls/`
Event Driven	Trades around corporate events (mergers, spin-offs, restructurings, activist campaigns). Includes merger arbitrage, activist strategies, and multi-event approaches.	`src/pods/strategies/event_driven/`
Long Biased	Primarily long-only or overwhelmingly net long. May focus on equities, commodities, or broader diversified growth portfolios, but uses hedge-fund-style structures (leverage, shorting in small measure, etc.).	`src/pods/strategies/long_biased/`
Macro	Takes positions (directional or relative-value) in global macro instruments (currencies, bonds, equities, commodities) based on top-down fundamental or qualitative judgments. Sub-categories include fixed income relative value, commodity-focused macro, global macro, emerging markets macro, etc.	`src/pods/strategies/macro/`
Multi-Strategy	Allocates capital across multiple sub-strategies and asset classes. Often extremely diversified, with multiple PM teams under one fund umbrella.	`src/pods/strategies/multi_strategy/`
Quant	Systematic strategies driven by algorithms. Can include CTA (trend-following on futures/FX), quant macro, statistical arbitrage, quant equity market neutral, or factor/risk-premia approaches.	`src/pods/strategies/quant/`
Crypto	Focuses on digital assets (long-only, long/short, arbitrage, or market-neutral). Often a hybrid of fundamental and quantitative approaches.	`src/pods/strategies/crypto/`

Below are more detailed definitions for each category and example sub-strategies. You might use these definitions to guide your Pod design and structure within src/pods/strategies/.

Installation

Prerequisites

Python 3.8 or higher
Poetry package manager

Install with Poetry

# Clone the repository
git clone https://github.com/LLMQuant/magents.git
cd magents

# Install dependencies
poetry install

# Activate the virtual environment
poetry shell

Usage

Running a Backtest

# Basic backtest with default parameters
python -m src.main --data-dir /path/to/data --instruments AAPL,MSFT,GOOGL

# Backtest with custom time period and initial capital
python -m src.main --data-dir /path/to/data --instruments AAPL,MSFT,GOOGL \
    --start-date 2022-01-01 --end-date 2022-12-31 --initial-capital 1000000

# Run with specific strategies
python -m src.main --data-dir /path/to/data --instruments AAPL,MSFT,GOOGL \
    --strategies ma,congress

# Use a custom configuration file
python -m src.main --data-dir /path/to/data --instruments AAPL,MSFT,GOOGL \
    --strategies ma,value,sentiment --config config/default.yaml

# Generate an HTML report for the backtest
python -m src.main --data-dir /path/to/data --instruments AAPL,MSFT,GOOGL \
    --strategies ma,value --generate-report

Using the Example Script

For a more complete example of how to run a multi-strategy backtest:

python examples/run_multi_strategy_backtest.py

This script demonstrates:

Loading strategy configuration from a YAML file
Creating mock data if necessary
Running a backtest with multiple strategies
Generating visualizations and reports

Configuration System

Magents includes a flexible configuration system that allows you to customize all aspects of the backtesting process via YAML or JSON files.

Example configuration file (config/default.yaml):

# Global Settings
global:
  initial_capital: 1000000.0  # Initial capital in USD
  max_leverage: 2.0           # Maximum allowed leverage
  transaction_cost: 0.001     # 10 basis points per trade

# Strategy-specific Settings
strategies:
  ma:
    fast_window: 10
    slow_window: 30

  value:
    signal_threshold: 0.65
    max_positions: 5

You can specify configuration files via the CLI:

python -m src.main --config config/default.yaml

Available Strategies

The framework already includes a few built-in example strategy pods:

Moving Average Crossover (ma)
A simple strategy that generates buy/sell signals based on the crossing of fast and slow moving averages.
Congressional Trading (congress)
A strategy that looks at companies possibly impacted by policy changes or legislation, attempting to identify potential beneficiaries of new regulatory or government contracting opportunities.
Value Investing (value)
A fundamental strategy that uses valuation measures (like P/E ratios, balance sheet strength, Graham Number) to find mispriced securities.
Sentiment Trading (sentiment)
A strategy that aggregates insider activity and sentiment data (news, social media) to form trading signals.

Feel free to adapt or extend these examples, or replace them altogether with your own ideas.

Creating Custom Strategy Pods

To add your own strategy:

Create a new file in src/pods/strategies/ (e.g. src/pods/strategies/my_strategy.py).
Implement one or more agents (signal agent, execution agent, etc.) in that file:
- A signal agent might generate trade signals based on your logic (technical, fundamental, sentiment, etc.).
- An execution agent might convert signals into actual orders.
Combine these agents into a Pod (a Python class) that orchestrates their actions.
Register your new Pod in src/pods/strategies/factory.py (so that the CLI and engine can discover it).

Hedge Fund Strategy Classifications & Example Pod Structure

Below is a more comprehensive overview of hedge fund strategy types, which you can use to inspire how you organize and name your strategy pods in Magents. For each main strategy category (Arbitrage, Credit, Equity Long/Short, Event Driven, Long Biased, Macro, Multi-Strategy, Quant, Crypto), we list typical sub-strategies and provide high-level definitions. You can create corresponding .py files in src/pods/strategies/<category>/ for each sub-strategy you wish to implement. For example, a convertible bond arbitrage strategy might live at:

src/pods/strategies/arbitrage/convertible_bond_arbitrage.py

Each sub-strategy can have different agents (signal generation, risk filters, execution logic) that reflect the nuances of that strategy.

1. Arbitrage

General Definition: Strategies that attempt to capture risk-free (or low-risk) profits by exploiting mispricings of the same or closely related instruments.
Typical sub-strategies include:

Convertible Bond Arbitrage (CB)
Tail Protection (Tail)
Volatility Arbitrage (Vol)
Opportunistic Arbitrage (Opp)