Chapaty

Chapaty is an Rust engine for building and evaluating quantitative trading agents. Designed with a familiar, Gym-style API, Chapaty brings the rigor of standardized simulation interfaces to event-driven financial backtesting.

Getting Started

Fast Track: Use the Chapaty Starter Template to instantly bootstrap a new project. It includes pre-configured AI prompts for backtesting with a LLM of your choice, built-in dashboard setups with Quantstats, and best-practice strategy examples.

Chapaty supports two primary workflows: Parallel Backtesting for evaluating agent grids, and the Canonical Gym Loop for step-by-step control over the environment.

1. Parallel Backtesting

For grid searches, Chapaty leverages rayon to evaluate agents in parallel, automatically tracking the top performers.

Run this example: examples/news_breakout_grid.rs

use std::path::Path;

use chapaty::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Initialize the environment (configure data sources, date ranges, filters)
    // See the full example file for the 'environment()' helper implementation.
    let mut env = environment().await?;

    // 2. Generate the Agent Grid
    // Creates a lazy parallel iterator of 1,000,000+ distinct parameter combinations.
    // This allows efficient streaming without loading all agents into RAM.
    let (count, agents) = news_breakout_grid();

    println!("Evaluating {count} agents...");

    // 3. Execute Parallel Evaluation
    // Chapaty manages the batching and threading, retaining the Top-100 agents
    let leaderboard = env.evaluate_agents(agents, 100, count as u64)?;

    // 4. Export the Leaderboard
    // Results are saved as a structured CSV dataset.
    leaderboard.to_file_sync(&FileConfig::default())?;

    Ok(())
}

2. The Canonical Gym Loop (Fine-Grained Control)

For custom integrations or those who prefer full control over the observation-action transition loop, Chapaty implements a standard API inspired by OpenAI Gym.

use std::path::Path;

use chapaty::prelude::*;

#[tokio::main]
async fn main() -> ChapatyResult<()> {
    // Initialize the environment
    let mut env = chapaty::make(EnvPreset::BinanceBtcUsdt1d).await?;

    // Reset the environment to generate the first observation
    let (mut obs, mut reward, mut outcome) = env.reset()?;

    while !outcome.is_done() {
        // This is where you would insert your custom policy or agent logic
        let actions = obs.action_space().sample()?;

        // Step (transition) through the environment with the actions,
        // receiving the next observation, reward, and termination status.
        (obs, reward, outcome) = env.step(actions)?;

        // If the episode has ended, reset to start a new episode
        if outcome.is_terminal() {
            // Optionally use the final observation and outcome to bootstrap reward logic
            drop(obs);
            (obs, reward, outcome) = env.reset()?;
        }
    }

    // Explicitly drop 'obs' to release the borrow on 'env'.
    // We cannot call 'env.journal()' while 'obs' is still active.
    drop(obs);

    // Extract the trading journal (ledger) for post-simulation analysis.
    let journal = env.journal()?;

    // Save the journal to a directory (the filename is handled internally).
    journal.to_file_sync(&FileConfig::default())?;

    Ok(())
}

Note: Environments are async because they stream large financial datasets directly from cloud storage (e.g. GCS, BigQuery, HuggingFace).

For practical, ready-to-run agents, check out the examples/ directory to get started quickly.

Related Projects

Community

If you are excited about the project, don't hesitate to join our Discord! It is the perfect place to ask questions, file data requests, discuss new features, and share what you have built with the community.

Contributing

Contributions are welcome! Before submitting a pull request, please make sure to run the pre-build script to verify your changes:

./bin/pre-push.sh

Disclaimer

Trading and investing involve substantial risk. You may lose some or all of your capital.

Chapaty is an open-source software project provided for research and educational purposes only. It does not constitute financial, investment, legal, or trading advice.

This software is provided “AS IS”, without warranties or conditions of any kind, express or implied, as stated in the Apache License, Version 2.0. The software may contain bugs, errors, or inaccuracies.

In no event shall the authors or contributors be liable for any direct or indirect losses, damages, or consequences, including but not limited to financial losses, arising from the use of this software.

By using Chapaty, you acknowledge that you are solely responsible for any trading decisions, strategies, or outcomes.