VerumTrade

KO | EN

gitlite — search

#javascript #python #hacktoberfest #go #android #docker #java #cli #kubernetes #pytorch #ios #mcp #openai #open-source

(★ 11)

VerumTrade -- An open-source multi-agent AI trading framework, with visible reasoning and decision traces from evidence to final trade proposal.

VerumTrade 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<a href="README.md">English</a>
 ·
 <a href="README.zh-CN.md">简体中文</a>

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.

<a href="#single-ticker-analysis">Watch the single-ticker demo ↓</a>
 ·
 <a href="https://muye1202.github.io/VerumTrade/demos/example-reports/MU-2026-06-23.html">View an example report ↗</a>
 
</div>

---

## 🔭 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](#-quick-start--web-app) → open the browser UI in minutes |
| 💻 **Terminal-first** | [Quick Start — CLI](#-quick-start--cli) → guided, no config files to edit |
| 🎯 **Evaluating one ticker** | [Single ticker analysis](#single-ticker-analysis) → inspect one name through the full agent pipeline |
| 🔎 **Looking for candidates** | [Stock discovery mode](#stock-discovery-mode) → screen the market, then analyze the strongest ideas |
| 🐍 **Building on top of it** | [Python API](#-python-api-programmatic) → embed VerumTrade in your own scripts |
| 🔬 **Researching multi-agent LLMs** | [Core workflows](#-core-workflows) · [Reasoning & Decision Traces](#-reasoning--decision-traces) · [Architecture](#%EF%B8%8F-architecture) |
| 💼 **Trading (paper or live)** | [CLI](#-quick-start--cli) · [Trade execution config](#%EF%B8%8F-configuration) · [Troubleshooting](#-troubleshooting--faq) |
| 🛠️ **Contributing** | [`CONTRIBUTING.md`](CONTRIBUTING.md) |

---

## ✨ What you get

VerumTrade builds on [Tauric Research's TradingAgents](https://github.com/tauricresearch/tradingagents)
(see [Credits](#-credits--acknowledgments)) 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 ↓](#-reasoning--decision-traces) |
| 🔗 **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](https://github.com/langchain-ai/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 ↓](#%EF%B8%8F-crowding--macro-pullback-awareness) |
| 🛰️ **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. |

<details>
<summary>📊 Full comparison — what VerumTrade adds over the original TradingAgents</summary>

| Area | Addition in VerumTrade |
|:--|:--|
| **Transparency** | Reasoning & decision **traces** plus a React UI to inspect them ([details](#-reasoning--decision-traces)) |
| **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](#%EF%B8%8F-crowding--macro-pullback-awareness)) |
| **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 |

</details>

---

## 🧭 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.

![MU single-ticker analysis demo](https://raw.githubusercontent.com/muye1202/VerumTrade/main/demos/MU_single_ticker_demo_preview.gif)

> 📹 Prefer the full-quality video? [Download the MU single-ticker demo (MP4)](https://github.com/muye1202/VerumTrade/raw/main/demos/MU_single_ticker_demo_720p_6x.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](https://muye1202.github.io/VerumTrade/demos/example-reports/MU-2026-06-23.html),
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`](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**

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

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

**2 — Configure API keys**

```bash
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`](.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:

The runtime can route each data category through a preferred vendor and automatically fall back when
a provider is unavailable. See [Configuration](#%EF%B8%8F-configuration) for the `data_vendors`
categories.

**3 — Install frontend dependencies**

```bash
cd frontend && npm install && cd ..
```

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

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

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

Open [http://localhost:5173](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.

<details>
<summary>💡 What to expect — cost & time</summary>

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

* 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.

</details>

---

## 💻 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 .`).

```bash
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:

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

<details>
<summary>Portfolio analysis & Stock discovery commands</summary>

**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](#stock-discovery-mode) for the workflow overview.

</details>

> [!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:

```python
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`](verumtrade/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`](verumtrade/graph/decision_schema.py)
  and extracted by [`graph/signal_processing.py`](verumtrade/graph/signal_processing.py).

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

```text
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:

![VerumTrade Multi-Agent Analysis Pipeline](https://raw.githubusercontent.com/muye1202/VerumTrade/main/assets/pipeline.png)

### 🧠 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:

### 🔗 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`](verumtrade/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.

<details>
<summary>🗄️ Data layer — routing, fallback & per-analyst tools</summary>

All market-data tool calls go through a single routing layer
([`dataflows/interface.py`](verumtrade/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:

> [!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.

</details>

<details>
<summary>📁 Portfolio mode & 🔎 Stock Discovery mode</summary>

**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/`](verumtrade/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.

</details>

---

## 🛡️ 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`](docs/macro_pullback_capability_upgrade.md).

---

## ⚙️ Configuration

All defaults live in [`verumtrade/default_config.py`](verumtrade/default_config.py). The knobs you'll
reach for most:

<details>
<summary>Data vendors & automatic fallback</summary>

Configured per category in the `data_vendors` dict:

> [!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.)

</details>

<details>
<summary>Trade execution & order types (Alpaca)</summary>

</details>

<details>
<summary>Risk-awareness toggles (macro-pullback capability)</summary>

All on by default; set the env var to `false` to disable. See
[Crowding & macro-pullback awareness](#%EF%B8%8F-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) |

</details>

<details>
<summary>Context budget mode (avoiding HTTP 400s on small context windows)</summary>

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

Set via `.env`:
```env
VERUMTRADE_CONTEXT_BUDGET_MODE=adaptive
```

</details>

---

## 🧰 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](#-quick-start--web-app)), 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`](CONTRIBUTING.md) for dev setup, project layout, and the PR process, and
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) for community guidelines.

---

## 📚 Citation

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

```bibtex
@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](https://github.com/tauricresearch/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](LICENSE) — see the [LICENSE](LICENSE) file for details.

VerumTrade

VerumTrade 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

VerumTrade

VerumTrade 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README