Quickstart

Install, create a project, understand the structure. Five minutes to a working pipeline.

1. Prerequisites

Python 3.11+
DuckDB (auto-installed as a dependency)
DolphinDB server (streaming mode only — free Community Edition available)

2. Install QuantFlow

pip install quantflow

3. Create a Project

# Create a project from a template
qf init my_project --template crypto

# Enter the project
cd my_project

Available templates:

Template	Contents
`crypto`	133 FeatureTypes, full state/label engine config — best starting point
`equity`	Equity-market defaults
`forex`	FX-market defaults

4. Edit the Two Config Files

.local_config.yml — credentials and local paths (git-ignored):

engine:
  - name: duckdb
    database: ./data/my_project/quantflow.duckdb
  - name: dolphindb
    host: localhost
    port: 8848

feed_provider_credentials:
  - provider: cryptohftdata
    key: "your-api-key-here"

local_cache:
  path: ./.cache/raw

quantflow_project.yml — symbols, features, thresholds. At minimum, set your symbols:

symbols:
  - BTCUSDT
  - ETHUSDT

The template provides sensible defaults for everything else.

5. Validate and Run

# Check your configuration
qf validate

# Run the full batch pipeline for a single day
qf run --start-date 2026-01-15 --end-date 2026-01-15

This downloads raw data, runs the State Engine (bars, snapshots, trade enrichment), computes features and labels, and writes everything to DuckDB.

Alternative: Run via Dagster (batch only)

# Start Dagster UI
dagster dev -w dagster_workspace.yaml

# Or trigger programmatically
python -c "
from quantflow.metadata import load_metadata
from quantflow.pipeline import create_runner

meta = load_metadata(project_dir='.')
runner = create_runner(meta)
result = runner.run(stage='all')
print(result)
"

Dagster provides asset lineage, run history, per-stage retries, and a web UI. Streaming (live trading) still runs via DolphinDB — not through Dagster.

6. Project Structure

my_project/
├── quantflow_project.yml          # Main config — you edit this
├── .local_config.yml              # Credentials (git-ignored)
├── dagster_workspace.yaml         # Dagster workspace (auto-generated)
├── .definitions/
│   ├── feature_types/             # Formula-based FeatureType blueprints
│   │   ├── signal/                #   OFI, VPIN, momentum, mean reversion
│   │   ├── execution/             #   Spreads, market impact, depth elasticity
│   │   ├── quality/               #   SNR, entropy, IC, Sharpe ratio
│   │   ├── regime/                #   Toxicity, stress, liquidity regime, VaR
│   │   ├── stability/             #   Autocorrelation, half-life, turnover
│   │   └── technical/             #   RSI, MACD, Bollinger Bands, MA crossover
│   ├── features/                  # Feature set definitions
│   └── feed_providers/            # Data provider connection specs
└── data/                          # Local DuckDB database (runtime)

What to edit vs. what to leave alone

File	Edit it?	When
`quantflow_project.yml`	Yes	Set symbols, pick features, adjust thresholds
`.local_config.yml`	Yes	Set paths, API keys, credentials
`.definitions/feature_types/*.yml`	Only for custom FeatureTypes	See customization guide
`.definitions/features/*.yml`	Only for custom feature definitions	See customization guide
`.definitions/feed_providers/*.yml`	Only for new data sources	See customization guide

7. Next Steps

Configuration guide — understand every config option
Running pipelines — batch mode, streaming mode, Dagster, CLI reference
Common workflows — research workflows, switching to production, troubleshooting
Customization guide — define custom features, labels, providers

1. Prerequisites​

2. Install QuantFlow​

3. Create a Project​

4. Edit the Two Config Files​

5. Validate and Run​

Alternative: Run via Dagster (batch only)​

6. Project Structure​

What to edit vs. what to leave alone​

7. Next Steps​