jackson-cmd/risk-aware-trading-agents

What it is

Risk-aware-trading-agents is a Python package for building and testing US equity swing-trading strategies. Four analysis modules (macro regime, technical setups, earnings quality, news) produce signals, and a deterministic risk manager has final say over every order, enforcing a 30% cash/T-bill floor, position and sector caps, tranche entries and regime-specific rules. It is aimed at people who trade over days to weeks, study LLM trading agents, or want a repeatable backtesting setup rather than a black-box bot.

The project also ships a frozen 2026 dataset for research: daily bars from 2024 for 64 stocks and 25 ETFs, the VIX term structure, and 16,945 headlines plus SEC filings, each tagged with publication time. Every research run is checked for look-ahead bias by re-running with a randomized future past three cut days; if decisions before each cut change, the run is flagged (research kit).

Optional LLM reviewers (bull, bear, risk judge) can adjust conviction by at most ±0.15 or veto a buy, and never create trades or alter limits. The same agents are exposed over MCP so Claude, Codex, Gemini or Cursor can query regimes, run backtests and write strategies from plain-language descriptions (MCP server).

Quick start

Python 3.10+ is required. Install with the dashboard and MCP extras, then launch the web UI:

pip install "risk-aware-trading-agents[dashboard,mcp]"
riskaware dashboard   # http://localhost:8501, English and 中文

In another terminal, initialize the config (language, risk profile, broker, watchlist) and inspect the market:

riskaware init
riskaware regime
riskaware scan
riskaware analyze NVDA
riskaware backtest --compare buy_and_hold,ema_bounce
riskaware run             # one paper-trading cycle on the built-in paper account

No account or API key is needed for these commands. riskaware research run -s swing_trend tests a strategy on the frozen 2026 market with the look-ahead check. A Docker image is also published for x86-64 and ARM; GitHub Codespaces opens the repo with extras preinstalled (quick start).

Using it

The dashboard, CLI, MCP integration and Python API cover different workflows. Paper-trading agents can run side by side on simulated money and are ranked against SPY each trading day; schedule them with riskaware agents schedule --install, which installs a LaunchAgent, cron line or Windows scheduled task that trades once per trading day before the New York close (paper-trading agents).

Custom strategies are one Python class with an on_bar method returning Signal objects; the risk manager still enforces the cash floor, caps and regime rules, so a strategy inherits the protection (custom strategies). The strategy lab lets an MCP client write code, blocks hard-coded dates and tickers, then backtests it in a separate process (strategy lab).

Constraints

• This is for research and education, not investment advice; trading involves loss risk.
• Live trading requires three separate switches: execution.mode: live in the config, --live on the command line, and a typed confirmation. The default is paper mode with a built-in account.
• Some brokers need optional extras (.[ibkr], .[schwab], .[tastytrade], .[futu], .[tiger], .[longbridge]); Alpaca, Public.com and Tradier are built in. Only the built-in paper account and Alpaca paper are described as tested on paper accounts (brokers).
• Options support is backtest-only in this version; riskaware run skips option orders. Option backtests price with Black-Scholes on modelled implied volatility and are sensitive to those assumptions.
• The 2026 dataset covers only the 64 built-in stocks and 25 ETFs; news for other years must be built locally (riskaware news-history build), and Benzinga headlines require an API key. The 2018–2026 backtest uses today's large-cap list, which carries survivorship bias, and the agent underperforms SPY over that long bull market while losing roughly half as much in drawdowns.
• License is MIT.

HotRepo's take

On the HotRepo Python new-project list for 2026-11-13, the repository recorded 107 stars and 19 forks, with 7 stars gained over the roughly 90-minute window from 17:46 to 19:15 UTC. That is early traction for a finance research tool rather than a signal of adoption or strategy quality. The more useful signal in the material is the project's emphasis on repeatability: the frozen 2026 dataset, the per-run look-ahead check, saved data hashes and a Zenodo DOI for citation. The README also reports a negative result — headline sentiment made each of five swing strategies slightly worse in its 2026 test — which is the kind of finding that distinguishes a research kit from a marketing page. Readers should treat the backtest numbers as the author's results under stated assumptions, not as evidence of future performance.