Model or dataset
whchien/ai-trader avatar
whchien/ai-trader

ai-trader's source is 0.3.4, its newest tag is v0.3.3 from January, and the previous tag drops the v

Backtrader-powered backtesting framework for algorithmic trading, featuring 20+ strategies, multi-market support, CLI tools, and an integrated MCP server for professional traders.

1,141 stars144 forksPythonGPL-3.0

At a glance

What is it?
A config-driven Backtrader backtesting framework with a CLI, twenty-plus strategies, four data markets and an MCP server so an assistant can run backtests. Three dependency managers and three manifests disagree with each other, the documented cash figure differs by a factor of ten between two entry points, and nothing in the documentation places an order.
Who is it for?
Use this if you want backtests driven by YAML files you can commit, and you are willing to manage the dependency situation yourself, because that is the weakest part of the project. Three things to check first.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Activity is slowing. The repository last received commits 7 months ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • whchien/ai-trader1,141 ★ · +66
Star history
Repository2026-09-112026-11-15
whchien/ai-trader1.1k1.1k

66 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The two most recent tags are not named the same way

The source tree and the release history have drifted, and the release history is internally inconsistent before that.

The packaging metadata declares version 0.3.4. The newest tag is `v0.3.3`, published 2026-01-05. The one before it is `0.3.1`, published 2025-12-19, with no `v` prefix. So the two most recent tags use different naming conventions, and the sequence skips 0.3.2, which by date would have fallen between them and would therefore have appeared in the list if it existed under either convention.

That is a small thing on its own, and it matters in practice for one reason: `pip install ai-trader` resolves the published version, while the source tree is one minor version ahead at 0.3.4. Anyone reading the repository and anyone installing from the index are looking at different code, and the page gives no version pin in its install command.

The activity picture is worth stating plainly rather than characterising. The last push to the default branch is dated 2026-03-28, and the newest release is from 2026-01-05, so there were commits after the last tag and no tag since. The version in the metadata is the only forward-looking number on the page.

Three install methods, three manifests, and a numpy floor that differs between them

The source install offers three choices in one block:

bash
git clone https://github.com/whchien/ai-trader.git
cd ai-trader

# Install dependencies (choose one method)
uv sync        # Recommended (fastest, modern tool)
# poetry install   # Or use Poetry
# pip install -e .  # Or traditional pip with editable install

Three tools, and the page recommends one. But the manifests behind them are not equivalent. `pyproject.toml` declares ranges, with `pandas>=2.0.0,<3.0.0`, `numpy>=1.24.0,<2.0.0` and `matplotlib>=3.7.0,<4.0.0`. `requirements.txt` is a full freeze with exact versions, and those versions are not recent: `numpy==1.24.4`, `pandas==2.0.3`, `matplotlib==3.7.5`, `scipy==1.10.1`, `statsmodels==0.14.1`, `TA-Lib==0.4.31`, `yfinance==0.2.40`, `twstock==1.4.0`.

So a `uv sync` reads the range metadata, and a `pip install -r requirements.txt` installs a specific old world. The two can resolve to different numpy and pandas versions for the same commit.

The frozen file is also wider than the project. It lists packages that are not in the dependency list at all, among them `peewee`, `multitasking`, `kiwisolver` and `patsy`, which are Backtrader's own dependencies, plus `beautifulsoup4` and `html5lib`. So the freeze was produced by walking the full dependency tree, while the project metadata only declares the direct one. A third file sits alongside both, `uv.lock`, and the root also carries a `MANIFEST.in` for the sdist.

Backtrader is pinned to an exact three-part version while everything else has a range

The one dependency that everything else depends on is the one with the tightest constraint. The requirement is `backtrader==1.9.78.123`, an exact pin on a three-part version with no upper or lower range at all.

That is a deliberate and correct choice. Backtrader's API is what every strategy in this repository subclasses and what `run_backtest` drives, and a framework that pinned a moving version of its engine would break strategies unpredictably. Pinning the engine hard and ranging everything around it is the sensible allocation.

It also has a consequence worth planning for. Because the pin is exact, there is no path forward without a new release of this project, and because Backtrader's version string has a fourth component, it is a fork or build identifier rather than a plain three-part release. A reader comparing `1.9.78.123` against the Backtrader versions they have seen elsewhere will not find a match.

The rest of the direct dependencies are ranged, and several are ranged broadly: `yfinance>=0.2.0` has no ceiling at all, and `twstock>=1.4.0` and `TA-Lib>=0.4.0` do not either. So a data source library can move forward underneath a pinned engine, which is the one combination in this file that is genuinely hard to reason about.

The metadata also declares `requires-python = ">=3.11,<4.0"` with classifiers for 3.11, 3.12 and 3.13, so the floor is explicit and the ceiling is the whole of Python 4.

The config file and the quick command disagree about how much money there is

Two documented entry points, two different cash figures, a factor of ten apart.

The YAML configuration example sets the broker to a million:

yaml
broker:
   cash: 1000000
  commission: 0.001425

The quick command example sets it to a hundred thousand:

bash
# Quick backtest on your own data file
ai-trader quick CrossSMAStrategy your_data.csv --cash 100000

Neither is wrong, and both are plausible starting points, but a reader moving from one to the other will silently change the notional by 10x. Since the strategy is the same cross of two simple moving averages in both cases, the two examples are not comparable without accounting for it.

The position sizing setting compounds the point. The config has a `sizer` with `type: "percent"` and `percents: 95`, so a single position takes 95 percent of available cash. That is an aggressive default to arrive at by editing a number, and the page does not discuss what it means for the results of a strategy that opens more than one position.

The commission value is the third thing in that block. `0.001425` is a plausible per-side rate, but nothing on the page says whether it is per side or per round trip, and for a strategy that trades often that single unlabelled field changes every reported number.

Some CLI commands need a source checkout and the rest do not

The install section splits the two installation methods by what they unlock, and the split is not cosmetic. Installing from PyPI is recommended for using the CLI, and it is described as sufficient for the `run`, `fetch` and `quick` commands, for backtesting your own data files, and for use as a library. Installing from source is recommended for examples and config templates, and it is described as sufficient for the config-based examples in `config/backtest/`, the example data in `data/`, the example scripts in `scripts/examples/`, and for contributing or customising strategies.

Then the run section draws the line explicitly. A backtest from a configuration file is annotated as requiring source installation, while a quick backtest on a data file is annotated as working with both pip and source installation.

So `ai-trader run` is a source-only command and `ai-trader quick` is the one that works from the index. The reason is structural rather than a limitation of the package: the config templates and example data are repository content, not package content, and a wheel would not carry them.

That makes the config-driven workflow, which the page calls the most solid way to run backtests, unavailable to anyone who installed from PyPI. A user on the recommended path for the CLI cannot use the recommended workflow without switching to the other install method, and the page does not draw that conclusion explicitly.

Four markets take four different argument shapes

The fetch command takes the same four flags for four quite different identifiers:

bash
# US Stock (default: saves to CSV)
ai-trader fetch TSM --market us_stock --start-date 2020-01-01

# Taiwan Stock (台灣股票)
ai-trader fetch 2330 --market tw_stock --start-date 2020-01-01

# Cryptocurrency
ai-trader fetch BTC-USD --market crypto --start-date 2020-01-01

# With SQLite persistent caching (NEW!)
ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite

# Save to both CSV and SQLite
ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage both

A US ticker is alphabetic, a Taiwan ticker is numeric, and a crypto pair is hyphenated. There is no normalisation layer in evidence, so the market flag and the identifier format have to agree or nothing will resolve. A user who writes `2330` with `us_stock` gets a symbol that does not exist, and a user who writes `TSM` with `tw_stock` has the same problem in the other direction.

The storage flag has three values, `csv` as the default, `sqlite`, and `both`, and the SQLite path is described with timings: a first fetch downloads from the API and caches in two to three seconds, and a repeated fetch loads from cache in about fifty milliseconds with no API call. That is the only performance figure given anywhere on the page, and it is a cache measurement rather than a backtest measurement.

Three further subcommands manage the cache, `ai-trader data list`, `ai-trader data info` and `ai-trader data clean --market us_stock --before 2020-01-01`, so the cache is inspectable and prunable by date rather than being an append-only store.

Two similarly named packages sit at the root and the docs link into the one you do not import

The repository root carries both `ai_trader/` and `agentic_ai_trader/`, and the import path in every example is the first of those:

python
from ai_trader import run_backtest
from ai_trader.backtesting.strategies.classic.sma import CrossSMAStrategy

The MCP server is the same package, `python -m ai_trader.mcp`.

The second directory is where the documentation points. The SQLite section ends with a link into `agentic_ai_trader/trading-backtester/README.md#persistent-data-storage-with-sqlite`, which is a three-level path inside the tree nobody is told to import from. There is also a root-level `SQLITE_STORAGE_GUIDE.md` covering the same subject, so the same feature has two documents in two different trees and the page links the one that does not match the import path.

The explanation is a rename that the documentation and the link targets did not follow, but the effect for a reader is the same: the tree contains a package that is not the package, and the primary feature documentation points inside it.

The rest of the root is more conventional and worth noting for what it implies about the project's shape. There are `config/`, `data/`, `docs/`, `scripts/`, `skills/`, `tests/` and `ai_trader/`, plus a `skills/` directory that matches the `/add-strategy` slash command the page documents as the fastest way to create a strategy. And a `.DS_Store` file is tracked at the root, the Finder metadata file macOS writes into any directory a person has browsed.

Nothing in the documentation describes placing an order

The project describes itself as a backtesting framework, and that is exactly what the documentation supports. Across the install, fetch, run, config, library and MCP sections there is no broker connection, no order submission, no exchange credential, no position reconciliation and no live or paper trading mode. The four markets are data sources: `yfinance` and `twstock` in the dependency list, and the fetch command writing files.

The MCP section is the closest it comes, and even there the examples are all retrospective. The suggested natural language commands are to run a backtest of a strategy on data from a given range, to list available strategies, and to fetch stock data for a date range. An assistant wired to this server can compute over history and cannot place anything.

That is worth stating plainly because the surrounding vocabulary invites the other reading. The repository description says professional traders, the market list includes crypto and forex, and the search terms around the project are full of trading bots. None of that changes what the code does, and a reader who wants live execution will not find a path here.

The library path makes the boundary concrete. The simple example passes `data_source=None`, with a comment saying it uses built-in example data, so a backtest runs with no market data at all. That is the correct design for a research tool, and it is also the clearest statement of scope on the page.

Editorial conclusion

Use this if you want backtests driven by YAML files you can commit, and you are willing to manage the dependency situation yourself, because that is the weakest part of the project. Three things to check first. Decide which of the three documented install methods you are using, because the range-based metadata and the frozen requirements file describe different worlds and the frozen one is old. Pin an exact version, since the source tree sits one minor version ahead of the newest tag and the two most recent tags are not even named consistently. And read the backtrader pin, which is an exact three-part version rather than a range, since that is the dependency everything else depends on. On scope: this is a backtester. No page in the documentation describes placing an order, connecting to a broker, or routing to an exchange, so treat it as a research tool and nothing more. The last push is dated 2026-03-28, which is worth knowing before you plan around it.

Frequently asked questions

How do I install ai-trader?

Two documented routes. `pip install ai-trader` from PyPI, which the page recommends for the CLI commands, your own data files and library use. Or clone the repository and run `uv sync`, which the page recommends for the config examples, the example data and contributing, with Poetry and editable pip given as alternatives to the sync command.

What is the current version of ai-trader?

The packaging metadata declares 0.3.4. The newest published tag is v0.3.3 from 2026-01-05, and the tag before it is 0.3.1 from 2025-12-19, written without a v prefix. The last push to the default branch is dated 2026-03-28.

Which markets can ai-trader fetch data for?

US stocks, Taiwan stocks, cryptocurrency and forex are the four named markets, selected with the `--market` flag as `us_stock`, `tw_stock`, `crypto` and forex. The identifier shape differs per market: a US ticker such as TSM, a numeric Taiwan ticker such as 2330, and a hyphenated crypto pair such as BTC-USD.

Does ai-trader support live trading or place orders?

No page in the documentation describes it. The project is described as a backtesting framework, the data commands write CSV or SQLite files, and the MCP examples cover running backtests, listing strategies and fetching data. No broker connection, credential or order submission appears anywhere.

How do I cache market data in ai-trader?

Pass `--storage sqlite` to the fetch command, or `--storage both` to write CSV and SQLite. The page gives a first fetch at about two to three seconds from the API and a repeated fetch at about fifty milliseconds from cache with no API call, and offers `ai-trader data list`, `ai-trader data info` and `ai-trader data clean --before` to manage it.

What does the ai-trader MCP server let an assistant do?

You run it with `python -m ai_trader.mcp` and add it to an `mcpServers` block, and the page's example commands are to run a backtest of a strategy over a date range, list all available trading strategies, and fetch stock data for a given range. The configuration note says to point the command at the full path of a virtual environment's Python if one is in use.

Official sources

  1. Issues
  2. License: GPL-3.0
  3. README
  4. Releases
  5. whchien/ai-trader on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/whchien-ai-trader.svg)](https://hysenlabs.com/projects/whchien-ai-trader)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/whchien-ai-trader.svg)](https://hysenlabs.com/projects/whchien-ai-trader)

Was this useful?