AI Market Pulse is not just a scheduled stock script. It turns daily market data into a quant-oriented research product: technical factors, rule-based signals, benchmark-relative strength, portfolio attribution, risk findings, Markdown/HTML/JSON reports, a web dashboard, a static research site, and optional OpenAI-compatible summaries.

The project is designed for quant trading research workflows such as watchlist screening, signal review, portfolio risk checks, and pre-trade decision support. It does not connect to brokers, place orders, or promise returns.

It is an original implementation inspired by the demand for daily AI stock analysis tools. It is not a fork or copy of another repository.

Dashboard	Daily report

1. Input holdings — type any supported symbol, add portfolio positions manually, or transcribe a brokerage screenshot with an OpenAI-compatible model.
2. Run quant research — calculate technical factors, rules-first scores, benchmark-relative strength, portfolio attribution, themes, and freshness checks.
3. Review the evidence — inspect the daily signal overview, risk board, contribution board, history lens, and report-grounded AI answers.
4. Monitor and publish — detect meaningful score/risk changes, push alerts, and publish the bilingual static site through GitHub Pages.

The interface is a real operating surface, not a mock dashboard: every score, matrix bar, freshness flag, and portfolio value is derived from generated report or JSONL history data.

Run the complete offline demo. It uses deterministic sample data, so no market API, news API, or LLM key is required.

pip install -e ".[dev]"
market-pulse demo --output demo

Then open:

• demo/site/index.html
• demo/reports/dashboard.html
• demo/reports/market-pulse-20260708-0930.html

• Unified dark quant-research UI with persistent light mode and EN / 中文 controls.
• Four-stage visual workflow: holdings input, theme research, report Q&A, and change alerts.
• Real-data signal overview and research matrix instead of decorative dashboard metrics.
• Watchlist-driven analysis for stocks, ETFs, crypto, and Yahoo Finance compatible symbols.
• Local visual console with arbitrary symbol input, editable AI screenshot import, report Q&A, dashboard refresh, and static-site links.
• One-command custom ticker analysis with market-pulse run --symbols.
• Quant research workflow for screening, signal review, benchmark comparison, portfolio attribution, and risk control.
• Technical snapshot: moving averages, RSI, MACD, Bollinger position, ATR, drawdown, volume ratio, 5/20/60-day returns.
• Rules-first signal score from 0 to 100 with readable reasons and risk labels.
• Portfolio mode with quantity, cost basis, allocation, day P/L, and unrealized P/L.
• Tag-driven theme research with grouped scores, returns, relative strength, allocation, contribution, and risk pressure.
• Focus Board for attention items, risk findings, contribution ranking, and daily checklist.
• Interactive dashboard exploration: symbol search, risk filter, relative-strength filter, history window, and symbol drilldown.
• Benchmark context for SPY, QQQ, CSI 300, Hang Seng Index, and configurable market baselines.
• Relative strength per symbol: 20/60-day performance versus its assigned benchmark.
• Data freshness checks: latest trading day, source, row count, and stale/missing data warnings.
• Provider registry with ordered fallback: yfinance by default, optional AkShare, Baostock, Tushare, and runtime extensions.
• Optional OpenAI-compatible asset/portfolio summaries, screenshot transcription, and report-grounded Q&A with local cache.
• Threshold alerts for score changes, risk upgrades, large daily moves, relative-strength deterioration, and stale data.
• Push notifications through Telegram, Slack, Discord, Feishu, WeCom, generic webhooks, or email.
• GitHub Actions and GitHub Pages workflows for zero-server daily publishing.

git clone <your-repo-url>
cd ai-market-pulse
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
market-pulse serve

Open http://127.0.0.1:8766. Enter symbols directly, add editable position rows, or upload a brokerage screenshot before clicking Run Analysis. Quantity, cost, and theme tags can all be confirmed in the browser. The console saves the portfolio to data/console-watchlist.yaml.

Prefer terminal usage?

market-pulse run --symbols "AAPL,MSFT,NVDA,TSLA,600519" --output reports --no-notify

Open the generated HTML file in reports/. Replace the symbols with any Yahoo Finance compatible ticker, crypto pair, HK ticker, or mainland A-share code. Plain 6-digit A-share codes are normalized automatically, for example 600519 becomes 600519.SS.

To build the full dashboard and static site for your own watchlist:

market-pulse run --symbols "AAPL,MSFT,NVDA,TSLA,600519" --output reports --history data/history.jsonl --no-notify
market-pulse dashboard --history data/history.jsonl --output reports/dashboard.html
market-pulse site --reports reports --output site --title "My Market Pulse"

To save a reusable watchlist file:

market-pulse init --symbols "AAPL,MSFT,NVDA,TSLA,600519" --path watchlist.yaml
market-pulse run --config watchlist.yaml --output reports --history data/history.jsonl --no-notify

Prefer a prebuilt starting point? Use a template instead of --symbols.

market-pulse init --list-templates
market-pulse init --template us-tech --path watchlist.yaml
market-pulse init --template cn-stock --path watchlist.yaml
market-pulse init --template crypto --path watchlist.yaml

The visual console accepts PNG/JPEG/WebP brokerage screenshots when OPENAI_API_KEY and OPENAI_MODEL are configured. The image is sent to the configured AI provider, so redact account identifiers first. AI only transcribes the image; quantity, cost, market, and tags remain editable before they enter the deterministic analysis pipeline.

File import is also available from the CLI:

market-pulse import-portfolio --input examples/portfolio.csv --output watchlist.yaml --template default --force

Supported formats: .csv, .tsv, .xlsx with pip install -e ".[excel]".

Recognized columns include symbol, ticker, code, name, market, currency, quantity, qty, shares, cost_basis, avg_cost, tags, and note. Chinese headers such as 股票代码, 股票名称, 持仓, 成本价, 标签, and 备注 are also accepted.

market-pulse run --config watchlist.yaml --output reports --history data/history.jsonl --no-notify
market-pulse dashboard --history data/history.jsonl --output reports/dashboard.html
market-pulse site --reports reports --output site --title "AI Market Pulse"

Open site/index.html. The generated report, dashboard, and site include an EN / 中文 switch.

data:
  providers: ["akshare", "yfinance"]

benchmarks:
  enabled: true
  symbols: ["SPY", "QQQ", "000300.SS", "^HSI"]
  default_by_market:
    US: "SPY"
    CN: "000300.SS"
    HK: "^HSI"
  compare:
    AAPL: "QQQ"
    NVDA: "QQQ"
  stale_after_days: 4

Reports show benchmark context, per-symbol relative strength, latest trading day, data source, and stale/missing data warnings.

Optional mainland China providers:

pip install -e ".[cn]"
pip install -e ".[tushare]"
export TUSHARE_TOKEN="..."

Providers are tried in order; if one is missing or cannot serve a symbol, the app falls back to the next provider.

Custom providers can be registered with ProviderSpec and register_provider() without editing the core fallback dispatcher.

llm:
  enabled: true
  base_url: "${OPENAI_BASE_URL:-https://api.openai.com/v1}"
  api_key_env: "OPENAI_API_KEY"
  model: "${OPENAI_MODEL:-}"
  temperature: 0.2
  prompts_dir: "prompts"
  cache_enabled: true
  cache_dir: "data/ai-cache"

export OPENAI_API_KEY="..."
export OPENAI_MODEL="your-model-name"
market-pulse run --config watchlist.yaml --output reports

Useful switches:

market-pulse run --config watchlist.yaml --output reports --no-ai
market-pulse run --config watchlist.yaml --output reports --ai-only
market-pulse doctor --config watchlist.yaml

The same environment variables enable screenshot transcription and the console's Ask This Report box. Answers are grounded in the generated report JSON and do not call market tools or alter signal scores.

alerts:
  enabled: true
  score_change: 10
  daily_move: 0.05
  relative_20d_drop: 0.05
  risk_upgrade: true
  stale_data: true

market-pulse alert-check --config watchlist.yaml --state data/alert-state.json

The first run creates a baseline. Later runs only emit new threshold events and reuse the existing notification channels. .github/workflows/intraday-alert.yml is opt-in: set repository variable ENABLE_INTRADAY_ALERTS=true after configuring data and notification credentials.

docker compose up --build

This generates reports/, data/history.jsonl, and site/.

This repository includes:

• .github/workflows/ci.yml
• .github/workflows/daily-report.yml
• .github/workflows/pages.yml
• .github/workflows/intraday-alert.yml
• docs/PUBLISHING.md

After pushing to GitHub, add optional secrets such as OPENAI_API_KEY, OPENAI_MODEL, OPENAI_BASE_URL, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, and TUSHARE_TOKEN.

See CHANGELOG.md and ROADMAP.md.

This software is for quant trading research automation only. It does not provide financial advice, does not guarantee returns, does not connect to brokers, and does not place trades. Always verify market data, news, model outputs, and corporate actions before making decisions.