QuantHub

KO | EN

gitlite — search

#cross-platform #tailwindcss #automation #terminal #cpp #tensorflow #containers #video #chatbot #privacy

(★ 9)

本地优先的多市场量化研究与模拟交易工作台，支持 A 股、加密资产与 MT5，集成 AI 因子挖掘、滚动验证、信号审核、组合账本和 OKX Demo。

File Explorer

ZIP Download

- - ci.yml
  - okx-runner.yml
  - release.yml
- - .env.example
  - __init__.py
  - container.py
  - contracts.py
  - database.py
  - deployment.py
  - main.py
  - models.py
  - pyproject.toml
  - store.py
- - __init__.py
  - confirm.py
  - main.py
  - pyproject.toml
  - risk.py
  - router.py
- - __init__.py
  - adapter.py
  - CHANGELOG.md
  - config.py
  - database.py
  - engine.py
  - main.py
  - migrate_legacy.py
  - okx_adapter.py
  - private_ws.py
  - public.py
  - pyproject.toml
  - reconcile_scheduler.py
  - runner_errors.py
  - schemas.py
  - VERSION
  - ws_manager.py
- - pyproject.toml
- - __init__.py
  - jobs.py
  - pyproject.toml
- __init__.py
- - a_share_acceptance_universe.json
  - default_relationships.json
- a_shares.yaml
- ai_analysis.yaml
- base.yaml
- crypto.yaml
- deployment.lan.env.example
- deployment.local.env
- deployment.postgresql.env.example
- mt5.yaml
- okx-runner.env.example
- portfolio.yaml
- us_stocks.yaml
- - __init__.py
- - __init__.py
  - dataset.py
  - engine.py
  - factors.py
  - grid.py
  - market_data.py
  - metrics.py
  - strategies_demo.py
- - __init__.py
  - akshare_source.py
  - base.py
  - cache.py
  - eastmoney_source.py
  - factory.py
  - local_parquet.py
  - okx_source.py
  - quality.py
  - sina_news_source.py
  - telemetry.py
  - tencent_source.py
  - yahoo_source.py
- - __init__.py
- - __init__.py
- __init__.py
- cohort_evaluation.py
- config.py
- cost_profiles.py
- cross_sectional_research.py
- factor_dsl.py
- factor_experiment_suite.py
- factor_monitoring.py
- factor_research.py
- factor_robustness.py
- news_event_research.py
- point_in_time_universe.py
- pyproject.toml
- research_decision.py
- trading_costs.py
- - okx_local_index.json
- - _bulk_sync_report.json
  - _bulk_sync_retry_report.json
- - labeled_news.jsonl
- - okx_download_manifest.json
- .gitkeep
- a_share_300_factor_baseline.json
- a_share_preregistered_experiments_01_07.json
- - quanthub-factor-research.png
  - quanthub-overview.png
- UI_CONTROL_PANEL.md
- Dockerfile.okx-runner
- - README.md
  - VIDEO_FEATURE_GAP_REQUIREMENTS_2026-08-22.md
- - DEMO_SAFETY_EVIDENCE.md
  - LIVE_REVIEW.md
  - OPERATIONS.md
- - 2026-08-09-Web工作台与OKX实盘-可执行工作安排.md
  - 2026-08-09-Web工作台收口与OKX实盘路线图.md
  - 2026-08-11-Web前端收敛与雷达真实数据-可执行路线图.md
  - 2026-08-12-因子实时数据-同期策略基准-AI评审与实盘准入路线图.md
  - 2026-08-16-多用户股票分析-财报估值-新闻宏观任务路线图.md
  - 2026-08-16-研究证据-风控-执行-归因闭环任务路线图.md
  - 2026-08-25-前端设计与排版布局整改路线图.md
  - 2026-08-25-多用户与流程报告质量架构路线图.md
  - 2026-08-25-总任务路线图.md
  - QUANTHUB_RELEASE_BASELINE_v0.3
  - QUANTHUB_RESEARCH_BOARD.md
- - 2026-07-30-research-factor-update.md
  - 2026-07-31-quanthub-v0.2.0.md
- - v0.1.1.md
  - v0.2.0.md
  - v0.3.0.md
  - v0.4.0.md
- ARCHITECTURE.md
- CODE_QUALITY.md
- DATA_QUALITY.md
- DEPLOYMENT.md
- ENGINEERING_GUIDE.md
- FUNCTION_BOUNDARIES.md
- LIVE_TRADING_ADAPTER_EVALUATION.md
- m4_observation_template.md
- OKX_ALPHA_PARAMETERS.md
- OPERATIONS_CONTROL.md
- OPERATIONS_GUIDE.md
- PA_AGENT_ADAPTATION.md
- PRODUCT_USABILITY_AND_REPORT_REQUIREMENTS.md
- QUALITY_GATES.md
- README.md
- RESEARCH_EXECUTION_CLOSURE.md
- TRADING_COST_SOURCES.md
- TRADING_SAFETY.md
- UPGRADE.md
- - __init__.py
  - okx.py
- - __init__.py
  - checks.py
- - __init__.py
  - akshare_provider.py
  - akshare_valuation.py
  - analysis.py
  - contracts.py
  - events.py
  - guidance.py
  - macro.py
  - normalization.py
  - provider.py
  - sec_provider.py
- - __init__.py
  - contracts.py
  - okx_public_ws.py
- - __init__.py
  - client.py
- - __init__.py
  - middleware.py
- - __init__.py
  - contracts.py
- - __init__.py
  - contracts.py
- __init__.py
- README.md
- - __init__.py
- - __init__.py
- - __init__.py
- - __init__.py
- - __init__.py
- __init__.py
- base.py
- signal_contract.py
- - __init__.py
  - test_core_contracts.py
  - test_okx_ccxt_adapter.py
  - test_okx_runner_product.py
  - test_product_auth.py
  - test_product_backup.py
  - test_product_migrations.py
- __init__.py
- test_a_shares_news_failclosed.py
- test_a_shares_selector_data_source.py
- test_adapter_release_gate.py
- test_akshare_news_scope.py
- test_alphagpt_market_data_failclosed.py
- test_alphagpt_risk_failclosed.py
- test_alphamaster_market_data_failclosed.py
- test_api_health.py
- test_cohort_evaluation.py
- test_cross_sectional_research.py
- test_data_source_contract.py
- test_demo_run_read_only.py
- test_dispatcher_boundaries.py
- test_ensemble_fail_closed.py
- test_factor_ai_review.py
- test_factor_candidate_blind_benchmark.py
- test_factor_dsl.py
- test_factor_experiment_suite.py
- test_factor_factory_automation.py
- test_factor_factory_demo.py
- test_factor_factory_okx_demo.py
- test_factor_factory_valuation_api.py
- test_factor_monitoring.py
- test_factor_registry_ledger.py
- test_factor_research.py
- test_factor_research_persistence.py
- test_factor_robustness.py
- test_gate_isolation.py
- test_instrument_search.py
- test_ledger_trade_analytics.py
- test_llm_client_configuration.py
- test_m4_regressions.py
- test_market_data_live.py
- test_market_evaluation.py
- test_market_source_provenance.py
- test_news_event_research.py
- test_no_autoseed.py
- test_ohlcv_quality.py
- test_okx_credentials.py
- test_okx_grid_strategy_failclosed.py
- test_okx_public_ws.py
- test_pa_prompt_cache.py
- test_pa_validation.py
- test_point_in_time_universe.py
- test_portfolio_market_breadth.py
- test_private_ws_mock.py
- test_product_workflows.py
- test_public_market_stream_manager.py
- test_radar_signal_truth.py
- test_realtime_analyzer_data_source.py
- test_reconcile_scheduler.py
- test_research_context_mismatch.py
- test_research_data_fail_closed.py
- test_research_execution_closure.py
- test_research_run_metadata.py
- test_signal_ensemble_gate.py
- test_simulation_numeric_gate.py
- test_single_path_strategy_failclosed.py
- test_stage_3_5.py
- test_stock_research_contracts.py
- test_strategy_lab_research_contract.py
- test_supertrend_strategy_failclosed.py
- test_symbol_configuration_failclosed.py
- test_trading_proxy.py
- test_yahoo_source.py
- __init__.py
- audit_radar_signals.py
- backup_store.py
- block_secrets.py
- block_secrets.sh
- check_fake_data.py
- check_product_licenses.py
- check_product_secrets.py
- eval_news_metrics.py
- export_runtime_baseline.py
- generate_factor_cohort_evidence.py
- health_check.py
- migrate_instrument_references.py
- migrate_product_data.py
- observe_daily.py
- okx_ws_mock_server.py
- okx_ws_probe.py
- product_database.py
- purge_test_audit.py
- purge_test_signals.py
- quality_baseline.py
- repair_indices_parquet.py
- run_a_share_factor_baseline.py
- run_backend_tests.py
- run_factor_archive_acceptance.mjs
- run_factor_brain_acceptance.mjs
- run_factor_candidate_blind_benchmark.py
- run_factor_cohort_acceptance.mjs
- run_fault_drills.py
- run_okx_catalog_error_acceptance.cjs
- run_okx_public_reconnect_drill.py
- run_okx_settings_acceptance.mjs
- run_pre_m4_web_acceptance.mjs
- run_prelive_risk_drills.py
- run_preregistered_factor_experiments.py
- run_r7_web_acceptance.cjs
- run_recovery_drill.py
- run_research_closure_acceptance.mjs
- run_runner_shadow_acceptance.py
- run_runner_unavailable_acceptance.mjs
- run_stock_research_acceptance.mjs
- run_stock_research_data_acceptance.py
- scaffold_strategy.py
- start-quanthub.ps1
- stop-quanthub.ps1
- test_check_fake_data.py
- verify_no_autoseed_guard.py
- - favicon.svg
- - lint-css.mjs
- - App.test.tsx
  - App.tsx
  - i18n.test.tsx
  - i18n.tsx
  - main.tsx
  - vite-env.d.ts
- .gitignore
- index.html
- package-lock.json
- package.json
- tsconfig.json
- tsconfig.node.json
- vite.config.ts
- vitest.config.ts
.dockerignore
.gitattributes
.gitignore
.pre-commit-config.yaml
AI_FACTOR_DISCOVERY_ROADMAP.md
alembic.ini
Dockerfile
LICENSE
pyproject.toml
README.md
README.zh-CN.md
uv.lock

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[English](README.md) | [中文](README.zh-CN.md)

> A local-first quantitative research, strategy validation, and simulated trading workbench for individual investors and quantitative researchers.

QuantHub unifies comprehensive market evaluation, factor validation, AI research evidence, strategy backtesting, signal review, simulated trading, account ledgers, and operational controls in one Web application. It is built with React and FastAPI, supports China A-shares, US equities, crypto assets, and MT5 data, and can be extended through strategy plugins.

![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12-3776AB?logo=python&logoColor=white)
![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=111827)
![FastAPI](https://img.shields.io/badge/FastAPI-0.110%2B-009688?logo=fastapi&logoColor=white)
![Version](https://img.shields.io/badge/version-v0.4.0-4FB3C8)
![License](https://img.shields.io/badge/License-AGPL--3.0-blue)

![QuantHub factor research workbench](https://raw.githubusercontent.com/1634594707/QuantHub/main/design/screenshots/quanthub-factor-research.png)

## Project Video

[![Watch the QuantHub introduction on Bilibili](https://i0.hdslb.com/bfs/archive/1ac43b7f015f871fdfd6adab439daf5ca635a4e4.jpg)](https://www.bilibili.com/video/BV1uW8B6KEBW)

> The full walkthrough covers research traceability, workspace profiles, streaming reports and auditability, factor-research safety checks and seven-day gates, financial, valuation, news, and macro inputs, signal review, simulated ledgers, local startup, and safety boundaries. [Watch on Bilibili](https://www.bilibili.com/video/BV1uW8B6KEBW)

> [!WARNING]
> QuantHub is a research and simulated-execution tool. Live trading is disabled by default. Nothing produced by this project is investment advice. Before connecting a real account, independently validate data, strategies, risk controls, and compliance requirements.

> [!IMPORTANT]
> The current release targets local single-user research and simulated execution. Multi-user isolation for positions, signals, simulated orders, ledgers, and global search is still being strengthened. Read the P0 isolation requirements in [Product Usability and Reporting Requirements](docs/PRODUCT_USABILITY_AND_REPORT_REQUIREMENTS.md) before a production multi-user deployment.

## Highlights

- **One multi-market workbench:** Manage A-shares, US equities, crypto assets, MT5 data, and strategies from one workspace. Each market uses its configured primary provider, and provider failures are explicit rather than silently falling back across sources.
- **Comprehensive research:** Launch quantitative snapshots, news AI, price-structure AI, and model consensus in one workflow and write results to a shared research record.
- **Rigorous factor validation:** Evaluate trend, reversal, price-volume, and risk factors with training, holdout, rolling out-of-sample windows, drawdown and trade-count gates, and cost stress tests.
- **Factor Factory:** Generate candidates from BRAIN-style rules, manual JSON batches, libraries, or AI proposals. Expressions are checked against an AST allow-list, future-data constraints, parameter boundaries, duplicate hashes, and observed signal correlation.
- **Real observation gate:** A winning factor must pass a seven-calendar-day observation period in OKX Demo or a local isolated simulation before research acceptance.
- **Review-first execution:** Signals enter a review center before simulated orders and the account ledger. FIFO trade analytics calculate win rate, profit factor, payoff ratio, holding duration, long and short differences, and fee erosion.
- **Configurable AI:** Configure DeepSeek, OpenAI, or compatible providers, select a model, and test connectivity in System Settings. AI submits hypotheses and analyses; it does not change statistical results.
- **Local-first safety:** SQLite is the default store. Windows credentials use DPAPI and are not echoed in the UI. Live trading is disabled by default, while the OKX Runner starts in read-only shadow mode.
- **Operational controls:** Automated tasks, incidents, backups, access controls, and runtime health are part of the product.

## Workspace Overview

| Workspace | Primary capabilities |
| --- | --- |
| Overview | Account value, holdings, watchlist, market status, action queue, and PA decision summary |
| Research | Comprehensive evaluation, factor validation, and research tasks |
| Strategies | Installed strategy runs, reproducible experiments, and strategy portfolios |
| Execution | Signal review, simulated trading, account ledger, and price alerts |
| Operations | Instruments and data, job scheduling, incidents, access controls, backups, and system settings |

Built-in strategies cover sentiment analysis, news scanning, stock selection, SuperTrend, morning briefs, real-time analysis, OKX grids, AlphaGPT, PA Agent, and AlphaMaster.

## Safety and Product Boundaries

- Factor Factory DSL candidates currently operate on **single-instrument OHLCV time series**. Broad cross-sectional fields, industry ranking, and other WorldQuant-style operations require a stable cross-sectional data layer.
- Similarity filtering compares formula structure and observed signal correlation for the same target. It does not claim factors are intrinsically equivalent across markets or frequencies.
- Seven-day simulated-account results are research evidence, not live-trading authorization. Live trading requires separate configuration, human approval, and a longer observation period.
- The frontend never silently writes demo positions or watchlists. Real-data failures are explicit and do not render replacement values as market data.

## Technology Stack

- Frontend: React 18, TypeScript, Vite, React Router, Vitest
- Backend: FastAPI, Pydantic, SQLAlchemy, Alembic
- Data: Pandas, NumPy, PyArrow, SQLite / PostgreSQL
- Engineering: uv workspace, plugin strategies, domain-oriented APIs, and PowerShell lifecycle scripts

## Quick Start

### Prerequisites

- Python 3.11 or 3.12
- Node.js 18+
- [uv](https://docs.astral.sh/uv/)
- PowerShell for one-command startup on Windows

### 1. Clone the Project

```bash
git clone https://github.com/1634594707/QuantHub.git
cd QuantHub
```

### 2. One-Command Windows Startup

The launcher validates the runtime, syncs dependencies, checks ports and API health, and writes logs to `logs/launcher/`. It starts the Web workbench, unified API, and headless OKX Runner together.

For the first startup, or after dependency changes:

```powershell
# Safe default: Runner uses read-only shadow mode and never submits orders.
powershell -ExecutionPolicy Bypass -File tools/start-quanthub.ps1
```

For routine development after dependencies are installed:

```powershell
# Read-only research and trading-status view.
powershell -ExecutionPolicy Bypass -File tools/start-quanthub.ps1 -SkipSync

# OKX Demo integration: starts Web, API, and Demo Runner.
powershell -ExecutionPolicy Bypass -File tools/start-quanthub.ps1 -SkipSync -Demo

# Start Web and API only; do not start the Runner.
powershell -ExecutionPolicy Bypass -File tools/start-quanthub.ps1 -SkipSync -SkipRunner
```

After startup, open:

- Web workbench: <http://127.0.0.1:5173>
- API documentation: <http://127.0.0.1:8001/docs>
- Health check: <http://127.0.0.1:8001/health>

The OKX Runner listens on `127.0.0.1:8103`. It is not exposed to the browser and has no independent UI. The Web app reaches it only through `/api/trading/*` on the unified API.

Before switching between `shadow`, `Demo`, and `-SkipRunner`, stop existing processes. Otherwise the launcher can reuse an existing process whose environment does not match the new command.

```powershell
powershell -ExecutionPolicy Bypass -File tools/stop-quanthub.ps1
```

### 3. Manual Startup

Install base dependencies:

```bash
uv sync --locked
npm --prefix web install
```

Start the API:

```bash
uv run uvicorn apps.api.main:app --host 127.0.0.1 --port 8001
```

Start the frontend in another terminal:

```bash
npm --prefix web run dev
```

Start the default read-only OKX Runner in a third terminal:

```bash
uv run uvicorn apps.okx_runner.main:app --host 127.0.0.1 --port 8103
```

Vite proxies `/api` to `http://127.0.0.1:8001`, and the unified API reaches the Runner at `http://127.0.0.1:8103`. Research pages work when only Web and API are running. Trading surfaces report `TRADING_RUNNER_UNAVAILABLE` until the Runner is available.

### 4. Docker Image

Release images are published to GitHub Container Registry. The image serves the Web workbench and API on the same port and persists SQLite data at `/data`:

```bash
docker run --name quanthub -p 8080:8080 -v quanthub-data:/data ghcr.io/1634594707/quanthub:latest
```

Open <http://127.0.0.1:8080> after startup. The health endpoint is <http://127.0.0.1:8080/health>.

## Optional Capabilities

The base installation starts the Web workbench. Install an extra only when a market or analysis capability needs it:

```bash
# A-share data and Chinese sentiment analysis
uv sync --locked --extra a_shares

# Crypto data sources
uv sync --locked --extra crypto

# OpenAI-compatible LLM features
uv sync --locked --extra ai

# Backtrader backtesting engine
uv sync --locked --extra backtest
```

Extras can be combined:

```bash
uv sync --locked --extra a_shares --extra ai --extra backtest
```

## Configuration

### Local Environment Variables

Basic quantitative analysis and factor validation do not require an API key. To enable AI research evidence, configure DeepSeek, OpenAI, or an OpenAI-compatible provider in **System Settings -> Model Providers**, or copy the environment template:

```powershell
Copy-Item apps/api/.env.example apps/api/.env
```

```dotenv
DEEPSEEK_API_KEY=your-key-here
# or
OPENAI_API_KEY=your-key-here
# or
QUANTHUB_CUSTOM_LLM_API_KEY=your-key-here
```

The UI configures API base URLs, default models, timeouts, retries, and connectivity checks. Keys are written only to the runtime environment and never echoed. `apps/api/.env` is ignored by Git. Never commit API keys, database passwords, exchange keys, or access tokens.

### Local OKX Credentials

Open **System Settings -> OKX Connection**, enter API Key, Secret Key, and API Passphrase, then run a read-only connection test. For initial integration, grant only **Read** permissions and create a dedicated key in OKX **Demo Trading**.

Runner defaults:

- `QH_RUNNER_ENVIRONMENT=shadow`: read-only shadow mode; no orders.
- `QH_RUNNER_ENVIRONMENT=demo`: explicitly connects to the OKX Demo Trading environment.
- Live use additionally requires `QH_RUNNER_LIVE_APPROVED=1` and should only be enabled after a Demo observation period and human acceptance.

### Main Configuration Files

| File | Purpose |
| --- | --- |
| `configs/base.yaml` | Global switches, cache, signal weights, alerts, LLM, and backtest configuration |
| `configs/a_shares.yaml` | A-share data sources and strategy configuration |
| `configs/us_stocks.yaml` | US-equity primary provider and diagnostics-provider configuration |
| `configs/crypto.yaml` | Crypto data sources and strategy configuration |
| `configs/mt5.yaml` | MT5 data and AlphaMaster configuration |
| `configs/ai_analysis.yaml` | PA Agent analysis configuration |
| `configs/portfolio.yaml` | Portfolio and account configuration |

QuantHub supports `local`, `lan`, and `postgresql` deployment modes. LAN and PostgreSQL deployments must explicitly configure CORS, authentication tokens, and database connections. See [deployment and database migrations](docs/DEPLOYMENT.md).

## Project Layout

```text
apps/
  api/          FastAPI gateway and domain APIs
  dispatcher/   Signal aggregation, risk controls, and order routing
  okx_runner/   Headless OKX execution, risk, and reconciliation service
  scheduler/    Automated task definitions
core/           Shared configuration, market data, signals, backtesting, alerts, and LLM capabilities
strategies/     A-share, crypto, AI-analysis, and MT5 strategy plugins
web/            React and Vite Web client
configs/        Market, portfolio, and deployment configuration
data/           Local market data and runtime data
docs/           Architecture, deployment, quality, and operations documentation
tools/          Lifecycle, backup, migration, recovery, and strategy-scaffolding tools
tests/          Backend product-workflow tests
```

## Development and Validation

Install development tools and Git hooks:

```bash
uv sync --locked --extra dev
uv run pre-commit install
```

Run backend tests:

```bash
uv sync --locked --group test
uv run --frozen python -B tools/run_backend_tests.py
```

Run frontend tests, type checks, and the production build:

```bash
npm --prefix web test
npm --prefix web run typecheck
npm --prefix web run build
```

Run data and credential gates:

```bash
uv run --frozen python -B tools/check_fake_data.py
uv run --frozen python -B tools/check_product_secrets.py --product okx-runner
```

Command references, test coverage, and historical browser evidence live in `docs/README.md`, `docs/QUALITY_GATES.md`, and `docs/Plan/evidence/`.

## Documentation

- [Documentation index](docs/README.md)
- [Product Usability and Reporting Requirements](docs/PRODUCT_USABILITY_AND_REPORT_REQUIREMENTS.md)
- [v0.4.0 release notes](docs/releases/v0.4.0.md)
- [v0.3.0 release notes](docs/releases/v0.3.0.md)
- [AI factor discovery roadmap](AI_FACTOR_DISCOVERY_ROADMAP.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Function boundaries](docs/FUNCTION_BOUNDARIES.md)
- [Deployment and database migrations](docs/DEPLOYMENT.md)
- [Quality gates](docs/QUALITY_GATES.md)
- [Upgrade and extension](docs/UPGRADE.md)
- [Data quality](docs/DATA_QUALITY.md)

## Contributing

Use Issues for defects, feature requests, and data-source adapters. Before opening a pull request, run the backend tests, frontend tests, type checks, and production build relevant to the change.

## License

QuantHub is licensed under AGPL-3.0-or-later. Upstream components in `strategies/mt5/alphamaster/_upstream` retain their original licenses and copyright notices.

QuantHub

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README