quant.ai

Quant research for US stocks, built to live inside your AI assistant. Plug it into Claude or Codex via MCP and ask about any ticker — get explainable ratings, key levels, and the reasoning, then discuss it in the same chat. Also works as a one-command CLI.

English | 中文

quant.ai is a command-line quant-research toolkit for US equities, built for everyday investors. Type one command and get an explainable rating, key support/stop levels, and the reasoning behind them — all derived from historical prices, fully offline-friendly, and with no brokerage attached.

⚠️ Research only — not investment advice. It never places or suggests live orders. Output is English by default; add --lang zh (or pick at quant-ai init) for Chinese (中文).

Quick start

Try the personal research workspace in your browser:

pip install -e .
quant-ai start --demo --open

The isolated demo uses simulated prices and holdings in .quant-demo/, with no network requests or access to your real portfolio. Add coverage, record holdings, generate a brief, then copy the brief with a research question into your AI assistant. Use quant-ai start --open for real data; it prefers configs/my.yaml when present, otherwise configs/default.yaml. The workspace runs at http://127.0.0.1:8765/app; the advanced console remains at /. This is a local, single-user beta. Copying a brief includes your recorded holdings. There are no model API calls, hosted accounts or payments.

pip install -e .          # or: pip install -r requirements.txt
quant-ai doctor           # environment self-check (deps + data connectivity)
quant-ai analyze AAPL     # rate one stock in seconds

No entry point? python -m quant_agent analyze AAPL works the same.

What you get

<img src="assets/analyze-example.png" alt="Real output of quant-ai analyze AAPL" width="820">

Real output from quant-ai analyze AAPL — English by default, --lang zh for Chinese. Ratings range from Strong Buy through Neutral to Strong Sell. Add --output-dir to export Markdown + JSON, or --chart for a PNG chart.

Use it inside Claude or Codex

The headline feature — expose quant.ai as an MCP server and let your AI assistant call it:

claude mcp add quant-research -- quant-ai mcp

Works from any directory. Inside a checkout it uses ./configs; installed elsewhere it keeps your config and data under ~/.quant-ai/ (override with $QUANT_AI_HOME).

Then just ask, in the same chat where you work:

"What's the read on NVDA?" · "Watch TSLA for me." · "I bought 15 AAPL at 182.5 — track it." · "How are my positions doing?" · "Generate today's market report."

Claude (or Codex) calls into real project data, shows you the quant analysis, and you discuss it inline — no separate website, no copy-pasting. The daily report opens with your holdings P&L and renders as a polished HTML artifact. See the manual (Chinese) for Claude Desktop / Codex config.

Let your AI assistant install it — paste this into Claude Code (or any AI CLI) and it can set everything up:

Install https://github.com/TingdeLiu/quant.ai as an MCP server:
1. git clone https://github.com/TingdeLiu/quant.ai && cd quant.ai
2. pip install -e .
3. claude mcp add quant-research -- quant-ai mcp
4. Verify: `claude mcp list` should show quant-research ✓ connected

Highlights

• 🤖 Lives inside your AI assistant — the headline feature. Plug the built-in MCP server into Claude or Codex and ask "what's the read on NVDA?" It pulls real quant analysis from this project, so you see the analysis and discuss it in one conversation. Most stock-analysis tools are standalone websites — this one is embedded in the AI you already chat with.
• 💼 Your watchlist & holdings, managed by chat. Tell Claude "watch NVDA" or "I bought 15 AAPL at 182.5" — they persist locally in data/portfolio.json, are folded into every analysis automatically, and the daily report opens with your positions and unrealized P&L (best-effort live quotes, falling back to last close).
• 🖼️ Artifact-ready daily report — the market brief ships as a self-contained light/dark HTML file that Claude renders as an inline artifact; Markdown and JSON are written alongside for everything else.
• 🎯 Zero-config single-stock analysis — analyze AAPL returns rating, returns, RSI, volatility, MA positions, support/stop levels, and human-readable reasons.
• 🧩 Personalized watchlist — quant-ai init builds a universe that is 2/3 your own picks (companies + sectors you care about) and 1/3 discovered by the engine from the wider market.
• 🔬 Research backtests — cross-sectional signals (12-1 momentum, 20/50 trend, 1-month reversal, low-vol), signal-weight search, walk-forward stability analysis, plus SPY and equal-weight baselines to separate alpha from beta.
• 📊 Local console — one page, four tabs (report / markets / backtest diagnostics / ops), served locally with no API key anywhere in the stack.
• 🛡️ Safe by design — deterministic signals + risk layer, friendly degradation on network/data errors, paper trading only — never submits real orders.

Daily market report & local console

quant-ai market-report builds a daily US-equity research brief in an Anthropic-style design, written four ways: a full HTML page, a self-contained artifact fragment, Markdown and JSON. It is a single page with four tabs — Holdings, Market, Ideas, News — switched by pure CSS, so they still work inside an AI client's sandboxed artifact view.

Holdings — your positions come first

<img src="assets/report-holdings.png" alt="Daily market report — holdings P&L and per-position profile cards" width="820">

The brief opens with your P&L: market value, unrealized gain, day P&L, and a sparkline per position (best-effort live quotes, falling back to the last close). Right under it, Holdings at a glance gives each position its own card — portfolio weight, trend state, 5D/1M/3M returns, annualized volatility, 1-year max drawdown, distance from the 52-week high, strength against the benchmark, the sell-side analyst range, where it stands in the quant lists, its recent headlines, and a click-to-expand 1W–5Y close chart.

That section deliberately stops at the facts. It carries no buy/sell call and no price forecast — a test asserts the wording never drifts. This is a research tool, not a licensed adviser: it lays out the evidence and leaves the decision to you.

The per-holding news blurbs are hand-written and read from `data/news_digest.json` ({as_of, digests: {SYMBOL: "one line"}}) — the project never calls an LLM API for them. When that file's as_of is older than the report's data date, each card is stamped "digest as of …", so a stale summary can't pass itself off as today's.

Market — what the tape is actually doing

<img src="assets/report-market.png" alt="Market tab — benchmark, VIX gauge, breadth meters, sector rotation, cross-asset tracker" width="820">

Rather than just quoting the index: the benchmark's day/5D/1M/3M returns next to its distance from the 52-week high, drawdown and volatility; a VIX risk gauge with its trailing-year percentile; breadth meters — share of names advancing over 5D/1M and share holding above their 20D/50D moving averages, counted over your single stocks only, so a dozen index ETFs can't flatter the reading; sector rotation across the eleven SPDR sector ETFs, ranked by 1-month move with their excess over the benchmark; and a fund tracker grouped into broad indices, themes (semis, AI) and cross-asset (VIX, long Treasuries, gold, the dollar, crude) for where the money is going outside equities.

Ideas — quant picks, potential and high risk

<img src="assets/report-picks.png" alt="Ideas tab — research picks by holding horizon, potential picks and high-risk lists" width="820">

Research picks split by holding horizon (long / medium / short), each with the analyst valuation-range bar, day change, risk and confidence tags — positions you already hold are pinned to the top and highlighted. Below them, the potential picks and high risk tables spell out the statistical reason each name qualified. Index and sector ETFs are excluded from both lists.

Local console

quant-ai serve-dashboard serves one local page with four tabs — report, markets, backtest diagnostics and ops — reusing the report's own styling instead of a second design. write-dashboard writes the backtest-diagnostics page on its own, next to a run's outputs. The page language follows language: in your config.

<img src="assets/console-example.png" alt="Local console — backtest diagnostics tab" width="820">

Common commands

How it works

1. Data — daily OHLCV from Yahoo Finance (yfinance) by default, or local CSV/Parquet. Cached and validated.
2. Signals — cross-sectional, point-in-time-lagged factors, z-scored per day.
3. Portfolio & risk — deterministic target weights under position/turnover/liquidity limits.
4. Evaluation — train / validation / test split, walk-forward windows, and benchmark-relative metrics (Sharpe, Sortino, Calmar, max drawdown, alpha/beta).
5. AI — the project calls no LLM API of its own. It ships facts you can check: quantitative statistics, rule-based ratings, and third-party consensus. Synthesis and discussion happen in whichever AI client the MCP server is mounted in, so there is no API key, no extra cost, and no second model between you and the data.

Documentation

• Full manual (Chinese): docs/manual_zh.md — detailed config, backtest/walk-forward, dashboard API, MCP integration, output files.
• Changelog: CHANGELOG.md · Contributing: CONTRIBUTING.md · Roadmap: roadmap.md

Tests

python -m pytest      # 106 tests, network-free
python -m ruff check quant_agent tests conftest.py

Disclaimer

This project is for quantitative research and education only. It analyzes historical prices and produces research signals — not investment advice, and not authorization to trade. Markets carry risk; you are responsible for your own decisions.

License

MIT