English · 简体中文

An open-source multi-agent AI trading framework where each agentic analyst follows a structured reasoning graph, with visible reasoning traces and decision traces from evidence to final trade proposal.

Watch the single-ticker demo ↓ · View an example report ↗

---

🔭 What is VerumTrade?

VerumTrade is an open-source, multi-agent trading research framework for two jobs: analyzing a ticker you already care about and discovering new candidates worth deeper work. It turns market data, fundamentals, news, sentiment, catalysts, and risk context into a transparent trade thesis instead of a black-box "buy/sell" signal.

The name pairs Latin verum ("truth") with trade: the goal is a verifiable, evidence-first path to every decision — you can read the reasoning, inspect the evidence, and audit how each recommendation was reached, rather than trusting an opaque score.

Every run follows an auditable path:

1. Analysts gather market, news, social, fundamental, and catalyst evidence.
2. Evidence Graph distills those findings into structured facts.
3. Bull/Bear debate tests the thesis from both sides.
4. Trader plan turns the debate into an actionable proposal.
5. Risk review checks sizing, timing, concentration, and downside.
6. Decision records the final rationale, traces, and optional trade instructions.

Important

VerumTrade is a research and decision-support pipeline, not an independent investment decision maker. Treat its output as a structured second opinion: inspect the evidence, challenge the thesis, paper-trade first, and make any real-money decision yourself. Market data can be incomplete or delayed, LLM outputs can be wrong, and trading involves risk of loss.

---

🧭 Choose your path

Jump straight to what you came for:

If you are…	Start here
⚡ Just want to run it	Quick Start — Web App → open the browser UI in minutes
💻 Terminal-first	Quick Start — CLI → guided, no config files to edit
🎯 Evaluating one ticker	Single ticker analysis → inspect one name through the full agent pipeline
🔎 Looking for candidates	Stock discovery mode → screen the market, then analyze the strongest ideas
🐍 Building on top of it	Python API → embed VerumTrade in your own scripts
🔬 Researching multi-agent LLMs	Core workflows · Reasoning & Decision Traces · Architecture
💼 Trading (paper or live)	CLI · Trade execution config · Troubleshooting
🛠️ Contributing	CONTRIBUTING.md

---

✨ What you get

VerumTrade builds on Tauric Research's TradingAgents (see Credits) and extends it into a transparent, risk-aware system.

Capability	What it gives you
🔎 Visible reasoning & decision traces	The namesake feature — every step from raw evidence to the final proposal is captured and rendered in the web UI. Details ↓
🔗 Evidence graph	Analyst findings are distilled into a structured fact graph that grounds every downstream agent, reducing hand-wavy reasoning.
🧩 Structured agent pipeline	Specialised analysts → bull/bear debate → trader plan → risk review → execution, wired as a LangGraph workflow.
🗞️ Catalyst & event-risk awareness	A dedicated analyst surfaces earnings, FDA, and macro catalysts that move prices.
🛡️ Crowding & macro-pullback awareness	(new) A regime context bus + per-ticker Pullback Vulnerability Score + peer/sector read-through warn when a crowded, extended name is fragile. Details ↓
🛰️ AI stock discovery	A multi-stage screener finds promising tickers, then runs the full pipeline on the best candidates.
🔌 Bring your own model & data	9 LLM providers (incl. local Ollama) and 6+ market-data vendors with automatic fallback. Start free with Yahoo Finance and one LLM key.
💸 Paper or live execution	Optional Alpaca integration with position-size and concentration guardrails and 5 order types.

📊 Full comparison — what VerumTrade adds over the original TradingAgents

Area	Addition in VerumTrade
Transparency	Reasoning & decision traces plus a React UI to inspect them (details)
Grounding	Evidence Graph synthesis layer between analysts and researchers
New analyst	Catalyst / Event-Risk Analyst (earnings, FDA, macro catalysts)
Risk awareness	Macro-regime context bus, per-ticker Pullback Vulnerability Score, and peer/sector read-through with a dedicated risk-judge override (details)
Discovery	Multi-stage stock-discovery pipeline + a macro Theme Engine
Decision rigor	Structured Decision Schema + pre-execution Decision Guard validation
Execution	Live/paper Alpaca execution with concentration & position-size guardrails and 5 order types
Reach	9 LLM providers (OpenAI, Azure Foundry, Anthropic, Google, DeepSeek, Qwen, GLM, OpenRouter, Ollama) and a multi-vendor data layer with fallback
Engineering	A context-budget manager for token control, plus full FastAPI + React + Typer/Rich apps

---

🧭 Core workflows

VerumTrade has two main entry points: analyze a ticker you already care about, or discover candidates first and send the strongest ideas into the same multi-agent review process.

Single ticker analysis

Use this when you already have a stock in mind and want an auditable investment or trading thesis. VerumTrade runs the selected analyst team against one ticker, builds a structured evidence graph, stages the bull/bear research debate, asks the trader for a plan, and routes the result through risk review before producing a final decision.

📹 Prefer the full-quality video? Download the MU single-ticker demo (MP4).

You get a completed report with reasoning traces, decision traces, analyst evidence, risk notes, and an optional paper/live Alpaca order if execution is enabled. Start from the web app by entering a ticker in the main analysis form, or use the CLI with python -m cli.main analyze and choose single-ticker analysis at the first prompt.

Want to inspect the output quality before running your own analysis? Open the interactive MU example report, generated from a completed VerumTrade run and rendered with app-like navigation, search, and collapsible report panels. The source artifact lives at demos/example-reports/MU-2026-06-23.html.

Stock discovery mode

Use this when you want VerumTrade to help find names worth researching instead of starting from a known ticker. Discovery screens a market universe through catalyst, theme, enrichment, inflection, attention-gap, and scoring stages, then promotes the most promising candidates into deeper VerumTrade analysis.

You get ranked candidates, evidence packs, two-layer discovery scores, thesis cards, and completed reports for the selected names. Start from the web app by switching to Discovery mode, or use the CLI with python -m cli.main analyze and choose Stock Discovery (AI finds promising stocks) at the first prompt.

---

🚀 Quick Start — Web App

The web interface is the easiest way to get started. It launches a React + Vite frontend and a FastAPI backend.

Prerequisites

Tool	Version	Check
Python	≥ 3.10	python --version
Node.js	≥ 18	node --version
npm	≥ 9	npm --version

1 — Clone & install

git clone https://github.com/muye1202/VerumTrade.git
cd VerumTrade

pip install -e .       # or, if you have uv:  uv sync

2 — Configure API keys

cp .env.example .env         # Linux / macOS
copy .env.example .env       # Windows

Open .env and paste in at least one LLM provider key (OpenAI, Azure Foundry, Anthropic, Google, DeepSeek, …). That's all you need — market data from Yahoo Finance works with no key at all.

Tip

See .env.example for every supported key and what it does.

Supported data sources

VerumTrade starts with a no-key Yahoo Finance path for basic stock data, then uses optional provider keys for richer coverage, fallback, filings, news, fundamentals, and execution data:

Source	Setup	Used for
Yahoo Finance / yfinance	No key	Default fallback for stock prices, indicators, financial statements, and insider transactions
Alpaca	APCA_API_KEY_ID, APCA_API_SECRET_KEY	Broker market data plus optional paper/live execution
Alpha Vantage	ALPHA_VANTAGE_API_KEY	Stock prices, indicators, fundamentals, financial statements, insider data, and news
Twelve Data	TWELVE_DATA_API_KEY	Technical indicators fallback
Finnhub	FINNHUB_API_KEY	Company/global news, news sentiment, earnings calendar, and insider data
SEC EDGAR	No key	Recent company filings
Local cached data	VERUMTRADE_DATA_DIR optional	Offline/cache-backed fallback data
LLM-backed news	Existing LLM key	News synthesis fallback when configured

The runtime can route each data category through a preferred vendor and automatically fall back when a provider is unavailable. See Configuration for the data_vendors categories.

3 — Install frontend dependencies

cd frontend && npm install && cd ..

4 — Launch — open two terminals from the project root:

# Terminal 1 — Backend (FastAPI)
uvicorn api.main:app --reload

# Terminal 2 — Frontend (Vite)
cd frontend && npm run dev

Open http://localhost:5173. The frontend talks to the backend on http://localhost:8000, and completed analyses are persisted so you can revisit them from the History view.

Note

python run.py starts both the backend and frontend in a single terminal. Separate terminals just give you better visibility into logs.

💡 What to expect — cost & time

VerumTrade runs many LLM calls per analysis, so each run takes time and incurs API cost:

Setting	Rough time	Rough LLM cost*
Shallow depth, small models (e.g. gpt-4o-mini, gemini-2.0-flash)	~1–3 min	a few cents
Deep depth, larger reasoning models	several minutes	~$0.50–$2+
Local models via Ollama	depends on hardware	free (your compute)

_{* Approximate, provider-dependent — not a quote. Watch your provider dashboard for actual usage.}

First run? Start with Shallow depth and small quick/deep models to confirm everything works before spending on deeper analyses.

---

💻 Quick Start — CLI

The interactive CLI walks you through every setting step by step — no config files to edit. It needs the same prerequisites as above plus the editable install (pip install -e .).

python -m cli.main analyze       # or, after editable install:  verumtrade analyze

analyze first asks whether you want single-ticker analysis, portfolio analysis, or AI stock discovery, then walks you through:

Prompt	What it does
Ticker	Stock symbol(s) to analyse (e.g. NVDA, AAPL)
Date	Analysis date in YYYY-MM-DD format
Analysts	Which specialists to include — Catalyst/Event-Risk, Market, Social, News, Fundamentals
Research depth	How many debate rounds: Shallow (fast) · Medium · Deep (thorough)
Time horizon	Target holding period (1–2 weeks up to 2–3 months)
LLM Provider	OpenAI, Azure Foundry, Google, Anthropic, DeepSeek, Qwen, GLM, OpenRouter, or Ollama
Models	Quick-thinking model (analysts) and deep-thinking model (judges)
Execution	Analysis only, or also place a paper trade via Alpaca

A live terminal dashboard streams agent progress, tool calls, and the growing report in real time. Results are saved to results/stocks/{date}/{ticker}/.

Portfolio analysis & Stock discovery commands

Portfolio analysis — verumtrade analyze-portfolio Pulls your Alpaca positions, runs a triage step to identify which stocks most need attention, then performs full multi-agent analysis on those. Remaining stocks get a lightweight "HOLD" entry.

Stock discovery — runs from the main analyze command; choose "Stock Discovery (AI finds promising stocks)" at the first prompt. The system screens for promising tickers using multi-factor scoring, then runs deep multi-agent analysis on the top candidates. You can launch a fresh discovery run or resume from a previously saved candidate list. See Stock discovery mode for the workflow overview.

Tip

Run verumtrade --help (or python -m cli.main --help) to see every command and option.

---

🐍 Python API (programmatic)

For scripting or integration, skip the UI entirely:

from verumtrade.graph.verumtrade_graph import VerumtradeGraph
from verumtrade.default_config import DEFAULT_CONFIG
from dotenv import load_dotenv

load_dotenv()

config = DEFAULT_CONFIG.copy()
config["llm_provider"]      = "google"          # or "openai", "azure-foundry", "anthropic", "deepseek", etc.
config["deep_think_llm"]    = "gemini-2.5-flash"
config["quick_think_llm"]   = "gemini-2.0-flash"

ta = VerumtradeGraph(config=config)

# Returns the full state and a structured trade decision
state, decision = ta.propagate("NVDA", "2024-05-10")
print(decision)

---

🔬 Reasoning & Decision Traces

Transparency is VerumTrade's reason for existing. Every analysis emits two kinds of trace, both viewable in the web UI:

• Reasoning trace — for each agent, what it looked at and how it concluded. Built by graph/reasoning_trace.py and surfaced in the Trader Reasoning and Evidence Graph panels.
• Decision trace — the chain from evidence → research debate → trader plan → risk review → final structured decision, rendered in the Decision Trace panel. The final decision itself is a structured object validated against graph/decision_schema.py and extracted by graph/signal_processing.py.

Conceptually, a trace lets you answer "why this trade?" at every level:

Evidence Graph        →  "Q3 revenue +18% YoY; RSI 71 (overbought); insider selling last week"
   ↓
Research debate       →  Bull: durable demand · Bear: valuation stretched → Manager: cautious BUY
   ↓
Trader plan           →  BUY, LIMIT @ $X, size 10% of buying power
   ↓
Risk review           →  Conservative trims size; Risk Judge approves with concentration cap
   ↓
Final decision        →  { action: BUY, order_type: LIMIT, qty: ..., rationale: ... }

_{Illustrative — the exact fields come from the decision schema and evidence-graph code above.}

The web UI renders these via dedicated React panels (DecisionTracePanel, TraderReasoningPanel, EvidenceGraphPanel under frontend/src/), so you can expand any agent's contribution instead of trusting a single opaque verdict.

---

🏗️ Architecture

VerumTrade is built on LangGraph — each agent is a node in a directed workflow graph. Here is the full pipeline:

🧠 Two tiers of LLM

Every agent uses one of two model slots — you set both in one place (deep_think_llm, quick_think_llm) and the system routes them automatically:

Tier	Used by	Why
Quick-thinking	Catalyst / Market / Social / News / Fundamentals Analysts, Bull & Bear Researchers, Trader, Risk Debaters	Speed and cost — these agents run many times and don't need heavy reasoning
Deep-thinking	Research Manager, Risk Judge, Portfolio Triage Agent	The key decision points where accuracy matters most; a stronger model pays off here

🔗 Evidence graph

After the analysts finish, VerumTrade doesn't just concatenate their reports. It distills them into a structured evidence graph (agents/utils/agent_runtime/evidence_graph.py) — a compact set of typed facts (catalysts, metrics, risks, sentiment) that every downstream agent references. This keeps the bull/bear debate and the trader anchored to concrete evidence instead of free-floating prose, and it's what powers the Evidence Graph panel in the UI.

🗄️ Data layer — routing, fallback & per-analyst tools

All market-data tool calls go through a single routing layer (dataflows/interface.py). You pick a preferred vendor per category in your config; if that vendor is unavailable the system silently tries the next one.

Each analyst has access to a curated set of data tools:

Analyst	Key tools
Catalyst Event	Catalyst event bundle, company news window, SEC filings, insider transactions, price action
Market	Stock data, indicators, VWAP, options flow, dark pool volume, short interest
Social	News, company news window, news sentiment
News	News, company news window, global news, news sentiment, SEC filings
Fundamentals	Fundamentals, balance sheet, cash flow, income statement, insider sentiment & transactions

[!TIP] When enable_bundle_tools is on (default), each analyst also gets a one-shot "bundle" tool that fetches all key data in a single call, reducing LLM turns and latency.

📁 Portfolio mode & 🔎 Stock Discovery mode

Portfolio mode — an additional Triage Agent runs first. It scans all your positions and picks the ones that need the most attention right now — based on breaking news, unusual price moves, concentration risk, and more. Only those stocks go through the full multi-agent pipeline; everything else gets a quick "HOLD" recommendation.

Stock Discovery mode — the discovery pipeline runs independently of the main analysis graph:

1. Stage 0 — Catalyst prefilter: screens for upcoming earnings, FDA events, and macro catalysts
2. Stage 1 — Multi-factor enrichment: technical momentum, relative strength, volume analysis across the universe
3. Stage 2 — Candidate scoring: composite ranking with configurable relaxation rules
4. Deep analysis: top candidates are fed into the full VerumtradeGraph for multi-agent analysis

Supports three tracks: Enricher (swing trade), Anomaly Scan (intraday/next-day), and Dual-Track (merged). A complementary Theme Engine (agents/discovery/theme_engine/) scans for active macro themes and scores how exposed each candidate is to them, so discovery can be steered by what's actually driving the market.

---

🛡️ Crowding & macro-pullback awareness

Single-ticker pipelines tend to be blind to a whole class of risk: a crowded, extended, sector-correlated name getting hit by a soft / second-order catalyst (a peer's guidance tone, a policy headline) in a deteriorating macro tape (rising rates, spiking oil, risk-off). None of those triggers is a discrete, dated, company-specific event — exactly the quadrant a news/catalyst analyst is built to ignore.

VerumTrade now computes that fragility from data it already fetches and feeds it into every decision:

Layer	What it does	Default	Config flag
Macro / regime context bus (macro_regime)	A once-per-run cross-asset & positioning snapshot — risk-off flag, rate impulse, oil/VIX, sector heatmap, momentum-vs-SPY — injected into the news, catalyst, and risk nodes.	on	enable_macro_regime_context
Pullback Vulnerability Score	A per-ticker, explainable 0–100 rating (LOW / MEDIUM / HIGH / CRITICAL) fusing price extension (distance above 50/200-DMA, YTD run), crowding, tape fragility, and valuation richness.	on	enable_pullback_vulnerability
Peer & sector read-through	Pulls peers' earnings dates into the ticker's calendar as peer_catalyst events and checks whether the ticker's sector basket is parabolic (basket beta) — so a sector bellwether reporting tomorrow becomes a visible, dated risk.	on (earnings + basket beta); peer-news fetch off	enable_peer_read_through
Risk-judge override	On a HIGH/CRITICAL rating the Risk Judge is steered toward reduced size, tighter invalidation, or wait-for-trigger on new exposure — a second override path mirroring the catalyst-risk gate.	on	—

Note

This capability is grounded in a post-mortem of two real 2026 sector pullbacks (the May memory-complex shock and the June AI-infra unwind). Design notes and backtests: docs/macro_pullback_capability_upgrade.md.

---

⚙️ Configuration

All defaults live in verumtrade/default_config.py. The knobs you'll reach for most:

Key	What it controls	Example / default
llm_provider	Which LLM backend to use	openai · azure-foundry · anthropic · google · deepseek · openrouter · qwen3-cn · glm · ollama
deep_think_llm	Model for judges & managers	"o4-mini" · "gemini-2.5-flash" · "claude-sonnet-4-20250514"
quick_think_llm	Model for analysts & researchers	"gpt-4o-mini" · "gemini-2.0-flash"
max_debate_rounds	Bull ↔ Bear debate rounds	1 (default), capped at 3

Data vendors & automatic fallback

Configured per category in the data_vendors dict:

Category	Available sources	Default
core_stock_apis	alpaca · yfinance · alpha_vantage · twelve_data · local	alpaca
technical_indicators	alpaca · yfinance · alpha_vantage · twelve_data · local	alpaca
fundamental_data	alpha_vantage · openai · local	alpha_vantage
news_data	alpha_vantage · openai · google · local	alpha_vantage

[!TIP] If a vendor is unavailable at runtime the system automatically falls back to the next option — nothing crashes. (Finnhub and SEC EDGAR back specific tools such as insider/filing data rather than the four switchable categories above.)

Trade execution & order types (Alpaca)

Key	What it controls	Default
alpaca_execution.enabled	Turn trading on / off	false
alpaca_execution.paper_trading	Paper vs. live	true
alpaca_execution.position_size_pct	Default position size	0.10 (10%)
alpaca_execution.max_concentration_pct	Max single-stock concentration	0.20 (20%)

Order type	Description
MARKET	Execute immediately at the current market price
LIMIT	Execute only at a specified price or better
STOP	Triggers a market order once the stock hits a stop price
STOP_LIMIT	Triggers a limit order once the stock hits a stop price
TRAILING_STOP	Stop that moves with the stock price, locking in gains

Risk-awareness toggles (macro-pullback capability)

All on by default; set the env var to false to disable. See Crowding & macro-pullback awareness.

Env var	What it controls
VERUMTRADE_ENABLE_MACRO_REGIME_CONTEXT	Build & inject the cross-asset/regime macro_regime context bus
VERUMTRADE_ENABLE_PULLBACK_VULNERABILITY	Compute the per-ticker Pullback Vulnerability Score + risk-judge override
enable_peer_read_through / enable_sector_parabola	Peer earnings → peer_catalyst events + sector-parabola / basket-beta crowding signal
peer_read_through.fetch_peer_news	Opt-in bounded peer-news fetch (off by default — costs extra vendor calls)

Context budget mode (avoiding HTTP 400s on small context windows)

Controls how prompts are compressed to fit within model context windows:

Mode	Behaviour
adaptive (default)	Cap prompt sections and apply a soft token budget
compact	Stronger compression for tighter context windows
off	No limiting — ⚠️ may cause 400 errors on models with strict limits

Set via .env:

VERUMTRADE_CONTEXT_BUDGET_MODE=adaptive

---

🧰 Troubleshooting & FAQ

Symptom	Likely cause & fix
No API key / auth errors	A provider key is missing or wrong in .env. You need one LLM key; market data works with no key via Yahoo Finance.
HTTP 400 — context length exceeded	The model's context window is too small for the prompt. Keep VERUMTRADE_CONTEXT_BUDGET_MODE=adaptive (default) or set it to compact; avoid off on strict models.
HTTP 429 — rate limited	Your provider is throttling. Use a smaller/faster model, lower research depth, or raise the manager delay knobs (VERUMTRADE_RESEARCH_MANAGER_MIN_DELAY_S, VERUMTRADE_RISK_MANAGER_MIN_DELAY_S).
Frontend loads but calls fail	The backend isn't running or is on a different port. Start uvicorn api.main:app --reload (default http://localhost:8000).
npm run dev fails	Check Node ≥ 18 and run npm install inside frontend/.
ChromaDB / native build errors on install	Ensure you're on Python ≥ 3.10 in a clean virtualenv; upgrade pip before pip install -e ..
Analysis is slow / expensive	Use Shallow depth and small quick/deep models (see cost & time), or run local models with Ollama.

Run verumtrade --help to discover every command and flag.

---

🤝 Contributing

Contributions — research ideas and engineering fixes alike — are welcome. See CONTRIBUTING.md for dev setup, project layout, and the PR process, and CODE_OF_CONDUCT.md for community guidelines.

---

📚 Citation

If you use VerumTrade in academic work, please cite this repository (see CITATION.cff) and the upstream TradingAgents framework it builds on:

@software{verumtrade,
  title  = {VerumTrade: A multi-agent AI trading framework with visible reasoning and decision traces},
  author = {Jia, Muye},
  year   = {2026},
  url    = {https://github.com/muye1202/VerumTrade}
}

@misc{tradingagents,
  title        = {TradingAgents: Multi-Agents LLM Financial Trading Framework},
  author       = {Tauric Research},
  howpublished = {\url{https://github.com/tauricresearch/tradingagents}}
}

---

🤝 Credits & Acknowledgments

This project is built upon the open-source TradingAgents framework developed by Tauric Research. We are grateful to the original authors for their pioneering work on multi-agent LLM systems for financial analysis and trading.

---

⚠️ Disclaimer

VerumTrade is a research and educational decision-support tool. It is not financial advice and is not an independent investment decision maker. Always inspect the evidence yourself, paper-trade first, and understand the risks before using real money. The authors are not responsible for any financial losses incurred through the use of this software.

---

📄 License

Apache License 2.0 — see the LICENSE file for details.