Vibe-Trading: an agent framework for market data, backtests and trade reports

What Vibe-Trading actually solves for a Python researcher

The gap Vibe-Trading targets is the plumbing between a question and a number. A researcher who wants to know whether a moving-average rule holds on a basket of instruments normally writes the same four things: a data fetcher per provider, a cleaning step, a backtest loop, and a report. The project's own description calls it a research framework that coordinates agents for market data collection, analysis, strategy testing, and trading reports. That is the whole claim. It is not a prediction engine and it does not tell you what to buy.

The intended user is someone comfortable in Python who wants the agent to do the orchestration. The pyproject.toml lists dependencies that make the shape clear: yfinance, akshare, tushare and ccxt for market data across equities and crypto, pandas, numpy, scipy and duckdb for the compute, and langchain, langchain-core and langgraph for the agent graph. The package is published as vibe-trading-ai with requires-python >=3.11, and the classifier is Development Status :: 4 - Beta. Take that beta label literally: the project ships fixes for correctness bugs in its own backtester on a near-weekly cadence, which is what you want from a beta and also a warning about pinning versions.

How the agent loop, the backtester and the broker layer fit together

Three layers are visible in the repository. The agent layer is a LangGraph application under agent/, with persistent state in a user-level directory. The docker-compose.yml mounts vibe-home at /home/vibe/.vibe-trading and comments that this holds persistent memory, a cross-session search index (sessions.db), user-created skills, shadow accounts, a hypothesis registry, broker connector config and agent.json, and that without the volume a rebuild wipes it all. So the agent is stateful by design, and the state lives outside the checkout.

The compute layer is the backtester plus a module the release notes call quantlib. The v0.1.13 notes describe a finance-math layer, and the v0.1.14 notes add Heston (1993) stochastic-volatility pricing, Hierarchical Risk Parity, Gaussian and Archimedean copulas, microstructure estimators (VPIN, Roll, Amihud, Kyle) and finite-difference barrier Greeks, reported as 306 tested functions across 23 modules. That is a real quant surface, and it is also where the correctness bugs have landed: the 2026-08-28 notes describe every cross-market backtest dying on v0.1.14 because the runner passes bars_per_year=None for a basket spanning markets and the risk x-ray called math.sqrt on it.

The broker layer is the part to treat with the most caution. The 2026-08-27 notes describe a kill-switch sweep that counted any broker response as success, while the MCP adapter turns a failed call into a {"status": "error"} envelope, so a dropped connection produced a compliant-looking audit trail while the resting order stayed live. The 2026-08-29 notes add a second bug in the same area: when a halted channel's broker reads failed, the sweep iterated the error envelope as a list of orders and marked itself fired anyway. Both were fixed, and the fixes are described in detail. The design lesson stands: this framework can place orders, so the failure modes are financial, not cosmetic.

Installing Vibe-Trading and running a first backtest

The package is on PyPI as vibe-trading-ai and requires Python 3.11 or newer. The README points to vibetrading.wiki/docs/ for the full setup, and the repository ships a Dockerfile and a docker-compose.yml for the container route. The compose file binds the API to loopback only, which is a deliberate default worth keeping.

For a local install, the project metadata gives the package name directly:

pip install vibe-trading-ai

After that you need an LLM endpoint before the agent will do anything. The compose file reads agent/.env and defaults OLLAMA_BASE_URL to http://host.docker.internal:11434, so a local Ollama instance is one supported path. If you use the container instead of a bare install, the compose file is the entry point:

docker compose up

The service publishes 127.0.0.1:8899:8899, so the web UI and API answer on port 8899 on your own machine and not on your network. The compose file also mounts published Taiwan stock snapshots read-only from /data/tw-stock/latest.db via VIBE_TW_STOCK_DB, and its comment states the default host path stays outside the checkout because no market data may ever land in the working tree. Keep that convention.

When you describe a strategy to the agent, the v0.1.14 notes introduce the parameter that matters most for correctness. A long-lookback strategy needs bars from before the period you asked about, so the agent used to move start_date back a year to feed MA200 and then grade that year too. The fix is to separate the two windows. The notes name warmup_bars (or evaluation_start_date) as the way to do it: warm-up bars prime the indicators and reach nothing else. If you leave the split implicit, the run still completes and the metrics are internally consistent, which is exactly why the bug was quiet.

Where Vibe-Trading is the wrong tool

It is the wrong tool for anyone who wants a hosted product. There is no managed service described in the repository. You install a Python package or run a container, you supply the model endpoint, and you own the data provider keys. The pyproject.toml pulls in yfinance, akshare, tushare and ccxt, and the v0.1.12 notes mention three new providers plus MetaTrader 5, so the provider surface is wide but each one has its own auth and rate limits that you have to manage.

It is also the wrong tool if you cannot read the changelog. The 2026-08-29 notes describe a symbol-resolution bug where asking for ETH-USDT returned AETHUSDT-USD, Aave Ethereum USDT, a different asset, because symbol search never covered exchange pairs and Yahoo's nearest string won. The fix resolves exact pairs against venue catalogs, which are public and need no broker account. A near-miss ticker that silently resolves to another instrument is the kind of error that invalidates a study without producing an exception.

Finally, the broker integration is not a hands-off feature. The kill switch, the cancel-and-flatten sweep and the fired-once latch are all described in the notes as things that were wrong and are now fixed. That is normal for software that touches live orders, and it means the trading path deserves more scrutiny than the research path. If you only want backtests, do not configure a broker connection at all.

How it differs from backtesting libraries and from hosted trading bots

The closest comparison is a plain backtesting library. A library such as backtrader or vectorbt gives you a strategy API and a results object, and you write the data loading and the reporting yourself. Vibe-Trading inverts that: the agent decides which data to fetch, writes and runs the strategy, and produces a report, and the library-shaped parts (pandas, numpy, scipy, duckdb) sit underneath as dependencies. The trade is control for convenience. With a library you know exactly which bars entered the calculation. Here the v0.1.14 warmup_bars fix exists precisely because the agent was making that decision on your behalf and getting it wrong.

The other comparison is a hosted trading bot. Those typically hide the strategy, run on someone else's infrastructure and report a return curve. Vibe-Trading is MIT-licensed, runs on your machine, keeps its state in a directory you can inspect, and its release notes document its own bugs in public. For a researcher that transparency is the point. For someone who wants a product, it is a maintenance burden.

Licence, maintenance and what an upgrade costs you

The licence is MIT, declared in both pyproject.toml and the LICENSE file at the repository root. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice travel with it. The repository also carries a NOTICE file, which is worth reading alongside the licence. None of this is legal advice, and the market data you pull through yfinance, akshare, tushare, ccxt or a broker is governed by those providers' terms, not by the project's licence.

On maintenance: the repository is not archived, and the last push was on 2026-08-20. Releases have been frequent, with v0.1.12 on 2026-07-22, v0.1.13 on 2026-08-10 and v0.1.14 on 2026-08-20, while pyproject.toml already declares version 0.1.15. The upgrade cost is the interesting part. The Dockerfile installs Python dependencies from requirements-lock.txt with --require-hashes, and its comment states that agent/requirements.txt is the human-edited source and the lock must be regenerated with the command documented at the top of requirements-lock.txt whenever that file changes. If you build your own image, that regeneration step is on you. The dependency set also pins tightly, for example langgraph >=1.2.5,<1.3 and langchain >=1.3.9,<2, so a major upgrade of the agent stack is a deliberate migration rather than a routine bump.

Editorial conclusion

Adopt Vibe-Trading if you already write Python and want an agent loop that can pull data, run a backtest and produce a readable report in one place, and you are willing to read the changelog before trusting a number. Do not adopt it if you want a hosted product, a signal feed, or anything that trades without your supervision. Before you install, check three things: that your Python is 3.11 or newer, that you have an LLM endpoint configured in agent/.env, and that you understand the warmup_bars / evaluation_start_date split from v0.1.14, because a backtest that grades a year you did not ask for will still report internally consistent metrics.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes