A self-contained Python monorepo for algorithmic trading, shipping two applications over three shared installable packages (ba2_common / ba2_providers / ba2_experts):
- ba2-trade (repo root) — the live trader: a NiceGUI web app that runs a fleet of market experts against broker accounts (Alpaca for equities and options, TastyTrade for equities), with ruleset-driven trade actions, classic or AI risk management, order execution, manual portfolio allocation and performance analytics.
- ba2-test (
testplatform/) — the backtesting & optimization platform: a FastAPI + React app that backtests the experts day by day, searches their settings, rulesets and exits with a genetic algorithm (optionally across remote workers), stress-tests the winners and hands them to the live platform. It also carries a deep-learning forecasting module. See testplatform/README.md.
Both apps run the same expert/provider code, which is what makes a backtest predictive of live behaviour.
# 1. Clone
git clone https://github.com/bmigette/BA2TradePlatform.git
cd BA2TradePlatform
# 2. Install: both venvs under ~/ba2-venvs/{trade,test}, plus the ba2-trade / ba2-test commands
./install.sh --editable # Windows: .\install.ps1 -Editable
# or by hand, trade app only (the in-repo packages first, then requirements.txt)
python -m venv .venv # then activate it
python -m pip install -e packages/common -e packages/providers -e "packages/experts[ui]"
python -m pip install -r requirements.txt
# 3. Run the live app: http://localhost:8080
ba2-trade # or: python main.py
python main.py --port 8081 --db-file ~/Documents/ba2/trade/dev.db # a second instance- PyTorch on Windows: the install scripts choose CPU or CUDA wheels for you. By hand, install the
CPU-only build first and pin a known working version such as
torch==2.6.0+cpu; recent builds (2.10+) can fail withWinError 1114. See Troubleshooting. - Flags:
--port(default 8080),--db-file,--log-folder,--cache-folder. - First-time setup: enter API keys and broker accounts on the Settings page
(
/settings). They are stored in the app's database, not in.env. See First-Time Configuration. - Configuration: the live app does not read
.env. The optional path overrides are the environment variablesBA2_HOME(data root, default~/Documents/ba2),DB_FILE,LOG_FOLDERandCACHE_FOLDER(seepackages/common/ba2_common/config.pyandba2_trade_platform/config.py). - Test platform: run
ba2-test serve(API on :8000, UI on :5173), ortestplatform/start.bat/start.sh. See the test platform quick start. - Tests: three suites, each run in its own invocation:
python -m pytestfrom the repo root runstests/;python -m pytest packages/common/testsruns a package suite (likewiseproviders,experts);python -m pytest testsfromtestplatform/backend, with the test venv, runs the backend suite.
Analysis jobs, recommendations, orders per account and trade performance at a glance.
P&L, win rate and per-expert breakdowns over a chosen period.
Every expert run per symbol, with its status, recommendation, confidence and expected profit.
What an expert saw and why it decided: here the Deterministic Multi-Section Scorer's section scores behind a BUY.
Recommendations summarised by symbol, with the orders they produced; process them and run the risk manager from here.
Rules combine triggers (conditions) with actions; rulesets order them per expert.
Triggers are grouped by category (position, signal, targets, options, market, timing) and searchable. Market-condition triggers say which profile the expert needs to use them.
The backtesting and GA-optimization platform; see the test platform README for more screenshots.
- 🧪 Experimental Release: This is pre-beta software with active development and breaking changes
- 🔄 Frequent Updates: APIs, database schema, and core functionality may change without notice
- 🐛 Expect Bugs: Known and unknown issues exist throughout the platform
- 📝 Incomplete Features: Some functionality may be partially implemented or missing
- 🔧 Developer Focused: Currently intended for developers and advanced users willing to troubleshoot
- 💾 No Migration Guarantees: Database schema changes may require fresh installations
- 📋 Documentation Gaps: Some features may lack complete documentation
USE ONLY FOR TESTING AND DEVELOPMENT - NOT SUITABLE FOR PRODUCTION TRADING
THIS SOFTWARE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND.
- 🚨 Trading involves substantial risk of loss and is not suitable for all investors
- 🧪 This software is experimental and should be thoroughly tested in paper trading mode before considering live trading
- 💰 You can lose money - possibly all of your investment capital
- 🤖 AI-driven decisions are not infallible - algorithms can make mistakes, markets are unpredictable
- 📉 Past performance does not guarantee future results - backtesting and historical analysis may not reflect real trading conditions
- ⚙️ Software bugs may exist - thoroughly review all code and test extensively before use
- 🔒 Use at your own risk and discretion - you are solely responsible for any trading decisions and their outcomes
- 💼 Not financial advice - this platform is a tool for educational and research purposes
RECOMMENDED PRACTICES:
- ✅ Start with paper trading to familiarize yourself with the platform
- ✅ Set strict risk limits and position sizing rules
- ✅ Monitor all automated trades closely
- ✅ Never invest more than you can afford to lose
- ✅ Understand the underlying strategies and code before enabling automation
- ✅ Keep detailed logs and review trading decisions regularly
- ✅ Test thoroughly in various market conditions before live deployment
By using this software, you acknowledge that you understand and accept these risks.
- Plugin Architecture: brokers implement
AccountInterface(plusOptionsAccountInterfacefor options), experts implementMarketExpertInterface; both declare their settings throughExtendableSettingsInterfaceand are configured from the web UI - Shared package split (see the intro):
ba2_commonholds models/DB/interfaces/types/position sizing/rule evaluation,ba2_providersthe market-data providers, screener and caches,ba2_expertsthe expert implementations — so an expert is written once and runs identically live and in backtest. - SQLModel ORM: SQLite backend with Alembic migrations (
migrate.py) - NiceGUI Web Interface: configuration and monitoring UI, with a responsive layout for phones
- Scheduling & Parallelism:
JobManager(APScheduler) runs weekly or monthly expert schedules;WorkerQueueanalyses symbols in parallel and persists queued tasks so they resume after a restart - Instrument Selection: static lists, AI-selected, expert-selected, or a configurable stock screener (EXPERTS.md)
- Centralized Logging: rotating app/debug/error logs plus one log file per expert instance
- Rulesets: each expert instance links an enter-market ruleset and an open-positions ruleset.
A rule (
EventAction) pairs trigger conditions with actions;TradeActionEvaluatorevaluates the ruleset's rules in order against each new recommendation or open position - Actions: buy, sell, close, adjust take-profit / stop-loss, increase / decrease instrument share, stop processing, and the option actions listed below
- Trigger picker: the rule editor groups triggers into position, signal, targets, options, market and timing categories; the Ruleset Test page evaluates a ruleset without trading
- Market-condition gates: set an expert's
market_condition_profile(ohlcv-v1,ta-structure-v1) and its rules can gate on that profile's fields, numerically or categorically. A rule using a market field while the expert serves no profile is refused at save/import - Import/Export: rules, rulesets and expert settings (single expert or batch)
- Semi-automatic or automatic: an expert only opens or modifies positions by itself when
allow_automated_trade_opening/allow_automated_trade_modificationare enabled (both default to off); otherwise recommendations are processed from the UI
- Option actions: long call / put, bull and bear call / put spreads, covered call, protective put, cash-secured put, long and short straddle / strangle, iron condor, jade lizard, call butterfly, put ratio spread, call / put backspread, poor man's covered call (open and roll), close option
- Entry-option path: a ruleset can open an option structure with no equity leg
- Broker: Alpaca implements
OptionsAccountInterface; the Live Trades page has an Options tab with structure detail and a payoff chart - Option risk rails:
risk_manager_mode: classic_optionsgates every option entry with sleeve rails (max deployment, notional leverage, undefined-risk cap, max concurrent structures, one-per-underlying, assignment capacity) and a drawdown circuit breaker, identically in live and in backtests - Historical option data for backtests: Alpaca, ThetaData (requires a locally running Theta Terminal) and TastyTrade providers; historical implied volatility / greeks are computed with Black-Scholes
- Classic risk manager (
risk_manager_mode: classic, the default): ranks and sizes recommendations using the expert's rules and sizing settings; every run is recorded (ranking inputs, capital mapping, per-order sizing) and shown in the UI - Smart Risk Manager (
smart): a LangGraph agent that manages the expert's portfolio with the configuredrisk_manager_model; each job has a detail page - Virtual Equity: each expert instance works with a
virtual_equity_pctshare of the account, with per-instrument caps (max_virtual_equity_per_instrument_percent) - Stops: optional ATR-based stop sizing (
use_atr_stop); account refresh force-closes a position whose stop was breached without filling (market hours only) - Margin: per-account
margin_enabled/margin_factor(default 1.8, minimum 1.0) let experts size against balance × factor, never above the broker's own buying power
- Enabled per account with the Manually traded account setting; refuses to run on an account with an enabled expert
- Group holdings by instrument label, set each label's portfolio target, each symbol's share of its label and a cash reserve
- Review and Submit builds a dry-run rebalance plan (sells first, then buys), supports fractional shares, checks market hours and broker buying power, and records every run
- Dividend / cash income ledger for reinvesting into a label; cost or market valuation per account
- Overview: account overview, account growth (in $ or %), performance analytics, LLM usage, and provider billing / credits for configured LLM keys
- Live Trades: Stocks and Options tabs; the current price is highlighted near a TP/SL leg
- Activity Monitor: filterable log of transactions, TP/SL changes, risk-manager runs and analyses
- Market Analysis: job monitoring, manual analysis, scheduled jobs (startable on demand) and trade recommendations; per-analysis detail pages, per-symbol history and PDF export
- Tools: SYMBOL360 symbol dashboard, FMP Senate trades, analyst ratings, penny screener
- Live capture / replay (off by default,
replay_capture_enabledapp setting): records the inputs of every live expert analysis so it can be replayed offline and compared with a backtest
- Event-driven backtest engine: daily and 5-minute bars, point-in-time data only, hermetic runs (never fetches mid-run) so results are reproducible
- Genetic optimization (DEAP): searches entry/exit rulesets, expert settings and risk-manager parameters together; per-generation checkpoints mean an interrupted multi-day run resumes rather than restarts
- Distributed evaluation: master + local process pool + version-matched remote workers, with a per-box memory governor that sheds concurrency instead of OOMing
- Robustness-adjusted fitness: a genome's raw score is discounted by concentration (does the book survive without its top trades?), Monte Carlo resampling, and a bid-ask spread stress test — both the raw and adjusted values are stored so a discounted result is explainable
- Realistic cost modelling: per-fill commission and measured per-cap-band bid-ask spreads (Alpaca SIP quotes), with an optional widening stress applied on top
- Screener metric store: precomputed cap-band/factor metrics so a genome's universe is selected point-in-time, per day, without re-scanning the market
- Option strategy grids and market-condition genes, evaluated by the same rule code as live
- TradingAgents: multi-agent LLM framework — market, news, fundamentals, social media and macro analysts; bull/bear researcher debate with a research manager; a trader; an aggressive / conservative / neutral risk debate with a risk manager
- Deterministic compute:
finance_calcrisk statistics and valuation snapshots (DCF, WACC) are injected into the analysts' context - LLM providers: OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot (Kimi), OpenRouter, NagaAI and AWS Bedrock, selectable per expert
- LLM-free experts: most experts (ratings, Senate/House, insider, earnings, FactorRanker, DeterministicScorer) need no LLM at all — see the table below
| Category | Providers |
|---|---|
| OHLCV | Yahoo Finance, Alpha Vantage, Alpaca, FMP, EODHD, Polygon |
| Fundamentals | FMP, Alpha Vantage, Yahoo Finance |
| News | Alpaca, Alpha Vantage, Google News, FMP, Finnhub, local files |
| Macro / Insider | FRED / FMP |
| Social sentiment | StockTwits |
| Screener | FMP (live and historical) |
| Indicators | local pandas calculation, Alpha Vantage |
| Options history | Alpaca, ThetaData, TastyTrade |
| Compute (offline) | finance_calc risk stats and valuation |
The LLM-backed news, company-overview and social-sentiment providers (AINewsProvider,
AICompanyOverviewProvider, AISocialMediaSentiment) stay in-tree under
ba2_trade_platform/modules/dataproviders/.
| Broker | Status |
|---|---|
| Alpaca | Paper and live; equities and options; TP/SL as limit, stop or OCO exit orders. The primary, most exercised broker |
| TastyTrade | Equities: market / limit / stop / stop-limit orders, cancellation, order and position refresh, account snapshot. No TP/SL legs, order modification or options trading |
| Interactive Brokers (IBKR) | Present, but trading is disabled (submit_order raises NotImplementedError pending a rework) |
New brokers are added by implementing AccountInterface and registering the class in
ba2_trade_platform/modules/accounts/__init__.py.
The live expert registry (ba2_trade_platform/modules/experts/__init__.py):
| Expert | Description | Data Sources | Special Features |
|---|---|---|---|
| TradingAgents | Multi-agent AI system with debate-based analysis | Market data, news, fundamentals, social, macro | LLM analyst team, bull/bear and risk debates (in-tree, live-only) |
| FinnHubRating | Analyst consensus tracker | Finnhub analyst ratings | Weighted consensus scoring |
| FMPRating | Price target analyzer | FMP analyst data | Profit potential calculation, rating-recency filter |
| FMPSenateTraderWeight | Government trading tracker (sophisticated) | FMP Senate/House data | Trader-skill scoring, portfolio allocation analysis |
| FMPSenateTraderCopy | Government trading tracker (simple copy) | FMP Senate/House data | 100% confidence copy trading, can recommend instruments |
| FMPInsiderClusterBuy | Insider cluster-buy detector — BUY when several insiders bought recently | FMP insider transactions | Cluster/recency windows, min distinct insiders (no large-cap data: small/mid only) |
| FMPEarningsDrift | Post-earnings-announcement drift — BUY fresh EPS beats, time-boxed hold | FMP earnings surprises | Surprise threshold, freshness window, forced time exit (small/mid only) |
| FMPEarningsEvent | Ranks upcoming earnings events for an earnings long-volatility option strategy | FMP earnings history, option chain | Historical earnings-day move, EPS-surprise volatility, implied-move cheapness |
| PennyMomentumTrader | AI-powered intraday penny-stock momentum trader | Market data, screener, social/news catalysts | Self-executing live expert, screener universe, staged exits |
| FactorRanker | Cross-sectional multi-factor equity ranker | FMP fundamentals & prices, StockScreener | momentum / value / quality / PEAD factors, static or screener universe, self-rebalancing top-N (no recommendations) |
| DeterministicScorer | LLM-free multi-section scorer — reproduces a TradingAgents-style verdict with pure local math, zero LLM calls | FMP/FinnHub fundamentals, prices, ratings, FRED macro | Technical + fundamental + analyst + macro sections, tanh-bounded composite score, Altman-Z hard veto, fully deterministic and free to run |
ba2_experts also contains ETFTrend, a research expert the backtester can load; it is not in the
live registry. PremiumSeller was removed on 2026-08-31 — its option rails and exit lifecycle became
shared code, so any expert can use risk_manager_mode: classic_options (see
EXPERTS.md §8 for what is and is not wired).
📖 For detailed documentation on all experts, their settings, and configuration options, see EXPERTS.md — and the dedicated FactorRanker guide.
- Python 3.11+ (the install scripts default to 3.12), SQLModel/SQLAlchemy ORM on SQLite (Alembic migrations)
- ba2-trade UI: NiceGUI, with a few HTTP API endpoints on the same FastAPI app
- ba2-test: FastAPI + Uvicorn backend; React 19 + TypeScript + Vite + Tailwind CSS frontend (lightweight-charts, recharts)
- LLM stack: LangChain / LangGraph (TradingAgents, Smart Risk Manager)
- ML: PyTorch — 12 forecasting architectures (LSTM, GRU, TCN, InceptionTime, ResNet, XceptionTime, OmniScale CNN, MiniRocket, PatchTST, TST, LSTM-FCN, N-BEATS), GA-tuned
- Optimization: DEAP genetic algorithms (strategy rails S1–S7, option strategy grids, distributed workers, robustness-adjusted fitness)
- Shared state: one
BA2_HOMEdata tree — a provider cache shared by both apps (parquet OHLCV, options history, screener metric store) plus a separate database per app
- Python 3.11+ (3.12 recommended: the install scripts use it and the test platform's
pandas-taneeds it) - SQLite (included with Python)
- Node.js / npm for the test-platform frontend
- An LLM API key for the LLM-based components (TradingAgents, PennyMomentumTrader, Smart Risk Manager, the AI data providers); the other experts run without one
- A broker account: Alpaca (free paper trading) or TastyTrade
- Data API keys as needed by your experts: FMP (most non-LLM experts and the screener), Finnhub, FRED, Alpha Vantage
- Optional: a local Theta Terminal for ThetaData option history
Configure API keys on the Settings page (http://localhost:8080/settings, Global Settings tab).
Keys are stored in the app's SQLite database (AppSetting table).
The Global Settings tab has key fields for OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, OpenRouter and NagaAI, plus AWS credentials and region for Amazon Bedrock. Optional admin keys (OpenAI, Anthropic, xAI, NagaAI) let the Overview page show provider usage and billing.
- Models are chosen per expert in Expert Settings with the model selector; a model is stored as a
provider/modelstring, so different experts can use different providers at the same time. - TradingAgents has separate settings for its quick-thinking, deep-thinking and final
trade-recommendation models; the Smart Risk Manager uses
risk_manager_model. - Configure a valid key for every provider you select before enabling an expert — an expert pointed at a provider without a key fails at run time.
Broker credentials are configured per account (Settings → Account Settings → add an Alpaca or TastyTrade account). The application-level Alpaca API key (Global Settings) is used for market data and news.
| Key | Used by |
|---|---|
| FMP | FMPRating, Senate/House, insider and earnings experts, FactorRanker, DeterministicScorer, screener, fundamentals |
| Finnhub | FinnHubRating, news |
| FRED | Macro data (TradingAgents macro analyst, DeterministicScorer) |
| Alpha Vantage | Optional OHLCV / fundamentals / news / indicators provider |
- API keys are stored in plain text in the local SQLite database — keep the database file secure
- The web UI and the
/api/*endpoints have no authentication; only run the app on a trusted network - Use paper trading accounts for testing (Alpaca provides free paper trading)
- Never commit keys or
.envfiles; rotate keys regularly
- Python 3.11+ (3.12 recommended), Git, Node.js/npm (test-platform frontend only)
- Windows, Linux or macOS
git clone https://github.com/bmigette/BA2TradePlatform.git
cd BA2TradePlatformThis is a self-contained monorepo — the shared packages (packages/common, packages/providers,
packages/experts), the live trade app (repo root → ba2-trade) and the backtest/optimization
platform (testplatform/ → ba2-test) all live here.
The install script creates two isolated venvs under ~/ba2-venvs/{trade,test}, installs the in-repo
packages/ chain plus each app's requirements (PyTorch from the CPU or CUDA wheel index, auto-detected),
runs npm install for the test frontend, and registers the ba2-trade / ba2-test console commands.
It then copies a database from the old ~/Documents/ba2_trade_platform/ location if the new one does not
exist yet, and applies migrations.
Windows:
.\install.ps1 -Editable # -e in-repo packages for developmentLinux/macOS:
./install.sh --editableUseful flags: -TradeOnly/-TestOnly (--trade-only/--test-only) to build just one venv,
-Ui (--ui) for the experts' NiceGUI extra, -Upgrade (--upgrade) to re-resolve deps,
-NoDb (--no-db) to skip the database step, -Python (--python) to choose the interpreter.
requirements.txt lists third-party dependencies only. The three shared packages are installed
from the in-repo packages/ first (pip resolves a relative path in a requirements file against the
current directory, so they are kept out of it). From the repo root:
uv venv --python 3.12 .venv
uv pip install -e packages/common -e packages/providers -e "packages/experts[ui]"
uv pip install -r requirements.txt
uv pip install --no-deps -e . # optional: registers the ba2-trade command(uv is optional: python -m pip install ... runs the same commands.) On Windows, prefer the CPU-only PyTorch build — see
Troubleshooting.
ba2-trade # installed console command (same options as main.py)
# or directly from a venv
.venv\Scripts\python.exe main.py # Windows
.venv/bin/python main.py # Linux/macOSThen open http://localhost:8080. A new database is created and stamped at the latest migration on
first run; for an existing database run python migrate.py upgrade after pulling (set BA2_DB_FILE to
migrate a database other than the default).
python main.py [--db-file PATH] [--cache-folder PATH] [--log-folder PATH] [--port PORT]| Option | Description | Default |
|---|---|---|
--db-file |
SQLite database of this instance | ~/Documents/ba2/trade/db.sqlite |
--cache-folder |
Provider cache folder (shared with the test platform) | ~/Documents/ba2/common/cache |
--log-folder |
Log folder | ~/Documents/ba2/trade/logs |
--port |
HTTP port for the web interface | 8080 |
The defaults follow BA2_HOME and can also be set with the DB_FILE, CACHE_FOLDER and LOG_FOLDER
environment variables. At startup the application's file logs are moved next to the database, into
<db folder>/logs/, so each instance keeps its logs with its data.
# Separate dev instance with its own database and port
python main.py --db-file ~/Documents/ba2/trade/dev.db --port 8081- Open Settings (
http://localhost:8080/settings) - Global Settings: enter your LLM and data API keys
- Account Settings: add an Alpaca (or TastyTrade) account
- Expert Settings: create an expert instance, pick its instruments, schedule and virtual equity share
- Trade Settings: create rules and rulesets, then select them as the expert's enter-market / open-positions rulesets in Expert Settings
- Enable automated opening/modification on the expert only once you trust its behaviour
Nothing is cached inside the repo. Data lives under a single root, BA2_HOME (env-overridable,
default ~/Documents/ba2), defined in packages/common/ba2_common/config.py:
BA2_HOME (default ~/Documents/ba2)
├── common/
│ └── cache/ # provider cache SHARED by both apps (CACHE_FOLDER):
│ ├── <provider>/ # OHLCV parquet, fmp_history, ...
│ ├── screener/ # metric_store/ (parquet) + screener_history.sqlite
│ └── options/ # options_history.sqlite
├── test/ # test platform data: dl_forecasting.db, datasets, trained models
└── trade/ # live trade data: db.sqlite (default --db-file) + logs/
- Each app has its own database holding its app settings and API keys:
trade/db.sqlitefor the live trader (or whatever--db-filepoints at),test/dl_forecasting.dbfor the test platform. BA2_HOMErelocates the whole tree;CACHE_FOLDER/DB_FILEstill win when set explicitly.- Data from the old
~/Documents/ba2_trade_platformlayout can be moved withtestplatform/scripts/migrate_cache_layout.py(dry run by default,--applyto move).
The Dockerfile copies packages/ from the build context and installs it with requirements.txt in
one uv pip install --no-sources step (Python 3.11 image, multi-stage). No GitHub access is needed at
build time. The compose file builds the image, serves the UI on port 8000 and keeps three named
volumes (ba2_db_volume, ba2_cache_volume, ba2_logs_volume) mounted under /opt/ba2_trade_platform/;
the container runs as the non-root user trader (UID 1000). The image pulls the default (CUDA) PyTorch
wheels from PyPI, so expect a multi-GB image.
docker-compose up -d # build + start, http://localhost:8000
docker-compose logs -f
docker-compose down # add -v to also delete the volumes (and the database)| Package | Import name | Contents |
|---|---|---|
packages/common |
ba2_common |
Models, DB helpers, interfaces, types, position sizing, trade conditions/rules, market conditions, option risk rails, replay contract |
packages/providers |
ba2_providers |
Market-data providers and their registries, stock screener, caches |
packages/experts |
ba2_experts |
The non-LLM experts (and PennyMomentumTrader) |
| repo root | ba2_trade_platform |
Live-only code: brokers, TradingAgents, Smart Risk Manager, LLM/model factory, AI providers, JobManager / WorkerQueue / TradeManager, instance caches, UI |
testplatform/ |
app (backend) + React frontend |
Backtesting, GA optimization, ML, ba2-test CLI |
Many in-tree modules (e.g. core/types.py, core/db.py, core/models.py, core/interfaces/*, the
non-AI data providers, the package experts) are re-export shims: existing
from ba2_trade_platform... imports keep working, but the implementation lives in the package. Change
shared code in packages/, not in the shim. The packages are wired to the live app at startup by
core/seam_wiring.py:wire_all_seams(). See CLAUDE.md for the full rules.
BA2TradePlatform/
├── main.py # Live app entry point (argument parsing + startup)
├── migrate.py # Alembic wrapper (create / upgrade / downgrade / current / ...)
├── alembic/ # Migration scripts for the live DB
├── install.ps1, install.sh # Two-venv installer
├── ba2_trade_platform/
│ ├── core/ # Live orchestration + shims into ba2_common
│ │ ├── interfaces/ # Re-export shims (AccountInterface, MarketExpertInterface, ...)
│ │ ├── TradeManager.py # Order processing and recommendation handling
│ │ ├── TradeActionEvaluator.py, TradeActions.py, TradeRiskManagement.py
│ │ ├── JobManager.py, WorkerQueue.py, ScheduledExpertExecutor.py
│ │ ├── SmartRiskManagerGraph.py (+ Toolkit, Queue, Prompts)
│ │ ├── ModelFactory.py, llm_service.py, LLMUsageTracker.py, ModelBillingUsage.py
│ │ ├── portfolio_allocation_service.py, option_lifecycle_service.py
│ │ ├── replay_capture.py, seam_wiring.py, utils.py
│ │ └── rules_export_import.py, MarketAnalysisPDFExport.py
│ ├── modules/
│ │ ├── accounts/ # AlpacaAccount, TastyTradeAccount, IBKRAccount + registry
│ │ ├── experts/ # TradingAgents (live) + shims/registry for ba2_experts
│ │ └── dataproviders/ # AI providers (live) + shims for ba2_providers
│ ├── thirdparties/TradingAgents/ # Multi-agent LLM framework
│ ├── ui/ # NiceGUI app: main.py (routes), menus.py, api_routes.py, pages/, components/
│ ├── config.py, logger.py, version.py
├── packages/{common,providers,experts}/ # Shared installable packages (each with its own tests/)
├── testplatform/ # ba2-test: backend/ (FastAPI), frontend/ (React), version.py
├── tests/ # pytest suite for the live app
├── test_files/ # Ad-hoc scripts (not collected by pytest)
├── tools/ # Operational scripts (reports, deploy, cache, backup, ...)
└── docs/ # Design docs, plans, runbooks, screenshots
All live in ba2_common.core.interfaces (re-exported from ba2_trade_platform.core.interfaces).
ReadOnlyAccountInterface→AccountInterface: brokers implement balance/positions/orders reads,refresh_positions/refresh_orders, prices, and_submit_order_impl,cancel_order,modify_order,adjust_tp/adjust_sl/adjust_tp_sl. The basesubmit_orderwraps_submit_order_implwith validation, transactions and TP/SL handling.OptionsAccountInterface: option chains, quotes, ATM IV, option positions,_submit_option_order_impl,close_option_position.MarketExpertInterface: experts implementdescription(),run_analysis(symbol, market_analysis)andrender_market_analysis(market_analysis); the base class declares the shared settings (trade permissions, risk manager mode, position sizing, market-condition profile, option rails, ...).ExtendableSettingsInterface:get_settings_definitions()declares typed settings that are stored as key/value rows and rendered in the UI.
Defined in ba2_common.core.models (re-exported as ba2_trade_platform.core.models):
- Configuration:
AppSetting,AccountDefinition,AccountSetting,ExpertInstance(virtual equity %, linked rulesets, priority),ExpertSetting,Instrument - Analysis:
MarketAnalysis,AnalysisOutput,ExpertRecommendation - Trading:
TradingOrder,Transaction,Position,TradeActionResult - Rules:
Ruleset,EventAction,RulesetEventActionLink - Risk & operations:
RiskManagerRun,SmartRiskManagerJob,ActivityLog,PersistedQueueTask,LLMUsageLog - Options:
OptionIVSnapshot,OptionActivity - Portfolio allocation:
PortfolioAllocationConfig,PortfolioAllocationLabel,PortfolioAllocationSymbol,PortfolioAllocationRun,PortfolioIncomeEvent,AccountSymbolFacts,SymbolMarketStats
Schema changes go through Alembic (python migrate.py create "message", then upgrade); see
MIGRATIONS.md.
ba2_trade_platform/thirdparties/TradingAgents/ is an adapted copy of the TradingAgents multi-agent
framework (see Credits):
- Analysts: Market (technical), News, Fundamentals, Social Media, Macro
- Researchers: Bull and Bear researchers, synthesised by a Research Manager
- Trader: turns the research plan into a trade proposal
- Risk team: Aggressive, Conservative and Neutral debaters, judged by a Risk Manager
- Data Collection: provider data is gathered for the analysts (pre-fetched for most of them)
- Agent Analysis: specialised analyst reports
- Debate Phase: bull vs bear researcher arguments
- Synthesis: research manager plan, trader proposal
- Risk Assessment: three-way risk debate
- Final Recommendation: trading decision with a confidence level (1–100)
| Page | Route | Contents |
|---|---|---|
| Overview | / |
Overview, Account Overview, Account Growth, Performance, LLM Usage tabs |
| Market Analysis | /marketanalysis |
Job Monitoring, Manual Analysis, Scheduled Jobs, Trade Recommendations |
| Activity Monitor | /activitymonitor |
Filterable activity log |
| Live Trades | /livetrades |
Stocks and Options tabs |
| Portfolio Allocation | /portfolioallocation |
Manual rebalancing for manually traded accounts |
| Tools | /tools |
SYMBOL360, FMP Senate Trade, Analyst Ratings, Penny Screener |
| Settings | /settings |
Global, Account, Expert, Trade (rules & rulesets), Instruments, Cleanup |
Detail pages: /market_analysis/{id}, /marketanalysishistory/{symbol},
/smartriskmanagerdetail/{job_id}, /rulesettest.
HTTP API (ba2_trade_platform/ui/api_routes.py, unauthenticated):
POST /api/reload— drop cached expert/account instances and settings and re-read them from the DBPOST /api/run-schedule— fire a registered scheduled analysis nowPOST /api/process-recommendations— run the risk-manager pass over an expert's existing recommendations
📖 For existing experts and their implementation patterns, see EXPERTS.md
New shared code (experts that also run in backtests, providers, interfaces) belongs in packages/;
live-only code (brokers, LLM, UI) belongs in ba2_trade_platform/.
from ba2_trade_platform.core.interfaces import AccountInterface
class MyBrokerAccount(AccountInterface):
@classmethod
def get_settings_definitions(cls):
return {
"api_key": {"type": "str", "required": True, "description": "API key"},
"paper_trading": {"type": "bool", "required": True, "description": "Paper account"},
}
# implement the abstract methods of ReadOnlyAccountInterface and AccountInterface
# (get_balance, get_positions, get_orders, refresh_orders, _submit_order_impl, cancel_order, ...)Register it in the providers dict of ba2_trade_platform/modules/accounts/__init__.py to make it
selectable in Settings → Account Settings.
from ba2_common.core.interfaces import MarketExpertInterface
class MyExpert(MarketExpertInterface):
@classmethod
def description(cls) -> str:
return "What this expert does"
@classmethod
def get_settings_definitions(cls):
return {
"threshold": {"type": "float", "required": True, "default": 0.5, "description": "Signal threshold"},
}
def run_analysis(self, symbol, market_analysis):
... # create ExpertRecommendation rows for the symbol
def render_market_analysis(self, market_analysis):
... # UI rendering of the analysisAdd it to the experts list in packages/experts/ba2_experts/__init__.py (backtest registry) and to
_build_experts_list() in ba2_trade_platform/modules/experts/__init__.py (live registry).
.venv\Scripts\python.exe -m pytest # live-app suite (tests/)
.venv\Scripts\python.exe -m pytest -x # stop on first failure
.venv\Scripts\python.exe -m pytest -k "test_name" # run specific testspytest.inisetstestpaths = testsand putspackages/*on the path, so the in-repo packages are tested.- Each package has its own suite under
packages/<name>/tests/; run those in a separate invocation. test_files/holds ad-hoc investigation scripts that pytest does not collect; port a script intotests/when it becomes a durable regression test.
Two independent build versions, both YYYY.MM.NNNNN:
ba2_trade_platform/version.py→APP_VERSION(trade app; shown in the UI sidebar and logged at startup)testplatform/version.py→TEST_APP_VERSION(test platform; remote GA workers self-update by comparing it)
Bump APP_VERSION for changes under ba2_trade_platform/, and TEST_APP_VERSION for changes under
testplatform/ or packages/, before pushing.
- Logs are written to
<db folder>/logs/(default~/Documents/ba2/trade/logs/):app.log,app.debug.log, the sharedall.debug.log/all.error.log, and one<ExpertClass>-exp<id>.logper expert instance - Size-based rotation (10 MB per file)
STDOUT_LOGGING/FILE_LOGGINGinba2_trade_platform/config.pytoggle the console and file sinks
- Configuration: API keys and settings via the Settings page; after editing settings directly in
the database, call
POST /api/reloadinstead of restarting - Error handling mode:
BA2_ERROR_MODE=enforce(default: unexpected errors in broad handlers propagate),observe(log what would have propagated) orlegacy(absorb everything) - Backups:
tools/backup_dbs.pytakes online SQLite backups (safe while the app is running), integrity-checks them, zips them into--destand keeps the newest--keepcopies. Its default database list and destination are specific to the maintainer's machine — review them before use - Multiple instances: run each with its own
--db-fileand--port
- Import errors /
ModuleNotFoundError: ba2_common: the in-repo packages are not installed in the venv — rerun the install script or the manual steps above. Always use the venv's Python, not a global one. - Port already in use: start with
--port 9090(default 8080). - Database schema errors after an update: run
python migrate.py upgrade(withBA2_DB_FILEfor a non-default database). - API key issues: configure keys in Settings → Global Settings; each app has its own database, so keys set in the trade app are not seen by the test platform.
- PyTorch DLL error on Windows (
OSError: [WinError 1114]): install the CPU-only build:Do not blindly upgrade torch to the latest version (e.g. 2.10+) — pin to a known working version such aspip install torch --index-url https://download.pytorch.org/whl/cpu
torch==2.6.0+cpu.
- LLM stack: unified model registry and per-expert model selector, AWS Bedrock provider, native web
search (xAI, Google, Moonshot), per-role models in TradingAgents, prompt caching,
finance_calccompute tools for the analysts - New experts: PennyMomentumTrader, FactorRanker, FMPInsiderClusterBuy, FMPEarningsDrift, DeterministicScorer, FMPEarningsEvent; trader-skill scoring in FMPSenateTraderWeight; stock screener instrument-selection mode; monthly schedules
- Monorepo & shared packages: code split into
ba2_common/ba2_providers/ba2_experts, the four sibling repos and the test platform merged into this repo,ba2-trade/ba2-testcommands, two-venv installers,BA2_HOMEdata layout, independent app/test version numbers - Backtesting & optimization (
ba2-test): GA over rulesets, expert settings and risk parameters; distributed remote workers; robustness-adjusted fitness; measured spread costs; point-in-time screener metric store; option strategy grids; market-condition genes - Options: option actions from single legs to iron condors, PMCC and backspreads; entry-option path;
shared option risk rails and circuit breaker (
classic_options); historical option data from Alpaca, ThetaData and TastyTrade; Options tab in Live Trades - Rules: unified rule model shared with the backtester, content-aware import dedup, categorised
trigger picker, market-condition gates (
ohlcv-v1,ta-structure-v1) - Accounts & risk: TastyTrade equity trading, market-hours awareness with an offline NYSE calendar, margin trading, structure-aware Alpaca TP/SL exits, breached-stop safety net, recorded classic risk-manager runs, Smart Risk Manager sizing improvements
- UI: Activity Monitor and Live Trades pages, Portfolio Allocation page, SYMBOL360 and symbol info panel, account growth in $/%, phone layout
- Operations:
/api/reload,/api/run-schedule,/api/process-recommendations; live capture and offline replay; nightly DB backup tool; fail-loud error mode (BA2_ERROR_MODE)
- EXPERTS.md — every expert, its settings and scheduling
- docs/ — design docs, plans (
docs/plans/,docs/superpowers/) and runbooks - MIGRATIONS.md — database migrations; MIGRATION.md — the move to a monorepo
- testplatform/README.md — the backtest & ML platform
- CLAUDE.md — development conventions (package vs in-tree code, config access, logging, versioning)
- Package READMEs:
packages/common/README.md,packages/providers/README.md,packages/experts/README.md
- Fork the repository
- Create feature branch:
git checkout -b feature-name - Make changes with proper tests
- Submit pull request
Source-available under the PolyForm Noncommercial License 1.0.0: you may use, study, modify and share it for any noncommercial purpose, and you may run it on your own personal brokerage accounts. Commercial use (a product, a hosted service, selling signals, or managing other people's money) is not licensed. Contact the author for a commercial license.
Third-party code keeps its own license: ba2_trade_platform/thirdparties/TradingAgents/ is
Apache-2.0.
Project that uses TradingAgents https://github.com/TauricResearch/TradingAgents
@misc{xiao2025tradingagentsmultiagentsllmfinancial,
title={TradingAgents: Multi-Agents LLM Financial Trading Framework},
author={Yijia Xiao and Edward Sun and Di Luo and Wei Wang},
year={2025},
eprint={2412.20138},
archivePrefix={arXiv},
primaryClass={q-fin.TR},
url={https://arxiv.org/abs/2412.20138},
}