mlquantx 0.2.5__py3-none-any.whl

mlquant/__init__.py

@@ -0,0 +1,18 @@
+"""mlquant — reference implementation of the ML-quant-trading paper.
+
+Public sub-packages:
+    data        — panel loaders and synthetic data generators
+    features    — tensor-accelerated factor engine and alpha library
+    training    — datasets, GBM augmentation, training loop
+    models      — neural networks and sign-aware losses
+    portfolio   — cross-sectional Markowitz with α-sweep
+    backtest    — vectorised backtest engine and metrics
+    cli         — Click entry points used by `mlquant ...`
+
+The package is import-light: `import mlquant` does **not** transitively
+import torch or cvxpy. Sub-packages are loaded lazily on demand.
+"""
+from __future__ import annotations
+
+__version__ = "0.2.5"
+__all__ = ["__version__"]

mlquant/backtest/__init__.py

@@ -0,0 +1,14 @@
+"""Vectorised backtest engine + reporting metrics."""
+from .engine import run_backtest, BacktestResult
+from .metrics import (
+    sharpe_ratio, sortino_ratio, calmar_ratio,
+    annualised_return, max_drawdown,
+    information_coefficient, rank_information_coefficient,
+)
+
+__all__ = [
+    "run_backtest", "BacktestResult",
+    "sharpe_ratio", "sortino_ratio", "calmar_ratio",
+    "annualised_return", "max_drawdown",
+    "information_coefficient", "rank_information_coefficient",
+]

mlquant/backtest/engine.py

@@ -0,0 +1,118 @@
+"""Vectorised backtest engine.
+
+Inputs
+------
+weights : np.ndarray [T, N]
+    Position weights. Row ``t`` is the weight vector chosen *with
+    information up to date t* and applied for the period ``t -> t+1``.
+returns : np.ndarray [T, N]
+    Realised simple returns from ``t-1 -> t`` (so ``returns[t]`` is
+    earned by ``weights[t-1]``).
+costs_bps : float
+    Round-trip transaction cost in basis points charged on absolute
+    weight changes. The default 5 bps roughly matches A-share retail
+    commissions + half-spread on liquid names.
+
+The engine is intentionally tiny — every realistic refinement (slippage
+models, borrow fees, T+1 settlement) goes into a sibling module rather
+than here. Doing so keeps the core path easy to audit.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+from . import metrics
+
+
+@dataclass
+class BacktestResult:
+    portfolio_returns: np.ndarray          # [T] net of costs
+    gross_returns:     np.ndarray          # [T] gross
+    cumulative_equity: np.ndarray          # [T]
+    weights:           np.ndarray          # [T, N]
+    cost_drag_cumulative: float            # total cost paid over the whole run
+    metrics:           dict                # summary table
+
+    @property
+    def cost_drag(self) -> float:
+        """Deprecated alias for :attr:`cost_drag_cumulative`.
+
+        The name was ambiguous: this figure is cumulative over the backtest,
+        while ``ann_return``, ``gross_ann_return`` and ``ann_vol`` alongside it
+        are annualised. Kept for one release so existing scripts and archived
+        JSON reports keep working. Prefer ``cost_drag_cumulative``.
+        """
+        return self.cost_drag_cumulative
+
+    def summary(self) -> dict:
+        return self.metrics
+
+    def __repr__(self) -> str:                      # pragma: no cover
+        m = self.metrics
+        return (
+            "BacktestResult("
+            f"ann_return={m.get('ann_return', 0):.2%}, "
+            f"sharpe={m.get('sharpe', 0):.2f}, "
+            f"max_dd={m.get('max_dd', 0):.2%}, "
+            f"turnover={m.get('turnover', 0):.2%})"
+        )
+
+
+def run_backtest(
+    weights: np.ndarray,
+    returns: np.ndarray,
+    *,
+    costs_bps: float = 5.0,
+    benchmark: Optional[np.ndarray] = None,
+) -> BacktestResult:
+    """Run a long-only / long-short vector backtest."""
+    if weights.shape != returns.shape:
+        raise ValueError(f"shape mismatch: weights {weights.shape}  returns {returns.shape}")
+
+    T, _ = weights.shape
+
+    # Lagged weights: weights[t-1] is what's earned over t-1 -> t.
+    w_lag = np.zeros_like(weights)
+    w_lag[1:] = weights[:-1]
+
+    gross = (w_lag * returns).sum(axis=1)
+    # Cost drag from rebalancing day t.
+    delta = np.zeros_like(weights)
+    delta[1:] = np.abs(weights[1:] - weights[:-1])
+    cost = delta.sum(axis=1) * (costs_bps * 1e-4)
+    net = gross - cost
+
+    equity = np.cumprod(1.0 + net)
+
+    summary = {
+        "ann_return": metrics.annualised_return(net),
+        "ann_vol":    metrics.annualised_vol(net),
+        "sharpe":     metrics.sharpe_ratio(net),
+        "sortino":    metrics.sortino_ratio(net),
+        "calmar":     metrics.calmar_ratio(net),
+        "max_dd":     metrics.max_drawdown(net),
+        "turnover":   metrics.turnover(weights),
+        # Cumulative over the run, unlike its annualised neighbours above.
+        # Both keys carry the same value for one release; `cost_drag` is
+        # deprecated. See docs/public_data_validation.md for the glossary.
+        "cost_drag_cumulative": float(cost.sum()),
+        "cost_drag":  float(cost.sum()),
+        "n_periods":  int(T),
+    }
+
+    if benchmark is not None and benchmark.shape == net.shape:
+        active = net - benchmark
+        summary["info_ratio"] = metrics.sharpe_ratio(active)
+        summary["alpha_ann"]  = metrics.annualised_return(active)
+
+    return BacktestResult(
+        portfolio_returns=net,
+        gross_returns=gross,
+        cumulative_equity=equity,
+        weights=weights,
+        cost_drag_cumulative=float(cost.sum()),
+        metrics=summary,
+    )

mlquant/backtest/metrics.py

@@ -0,0 +1,95 @@
+"""Performance and information-content metrics.
+
+All functions take 1-D numpy arrays so they can be unit-tested without
+torch. The conventions follow Bailey & López de Prado (2014):
+
+    annualised return  := (1 + mean(r))**P - 1
+    annualised vol     := std(r) * sqrt(P)
+    Sharpe             := annualised return / annualised vol
+    Sortino            := annualised return / (downside std * sqrt(P))
+    Calmar             := annualised return / max drawdown
+
+with ``P = 252`` for daily series.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+DAYS_PER_YEAR = 252
+
+
+def annualised_return(returns: np.ndarray, *, periods: int = DAYS_PER_YEAR) -> float:
+    if returns.size == 0:
+        return 0.0
+    return float((1.0 + returns).prod() ** (periods / returns.size) - 1.0)
+
+
+def annualised_vol(returns: np.ndarray, *, periods: int = DAYS_PER_YEAR) -> float:
+    return float(returns.std(ddof=1) * np.sqrt(periods)) if returns.size > 1 else 0.0
+
+
+def sharpe_ratio(returns: np.ndarray, *, rf: float = 0.0, periods: int = DAYS_PER_YEAR) -> float:
+    excess = returns - rf / periods
+    vol = excess.std(ddof=1)
+    if vol < 1e-12:
+        return 0.0
+    return float(excess.mean() / vol * np.sqrt(periods))
+
+
+def sortino_ratio(returns: np.ndarray, *, rf: float = 0.0, periods: int = DAYS_PER_YEAR) -> float:
+    excess = returns - rf / periods
+    downside = excess[excess < 0]
+    if downside.size == 0:
+        return float("inf")
+    if downside.size < 2:
+        return 0.0
+    dd = downside.std(ddof=1)
+    if not np.isfinite(dd) or dd < 1e-12:
+        return 0.0
+    return float(excess.mean() / dd * np.sqrt(periods))
+
+
+def max_drawdown(returns: np.ndarray) -> float:
+    if returns.size == 0:
+        return 0.0
+    equity = (1.0 + returns).cumprod()
+    peak = np.maximum.accumulate(equity)
+    return float(((peak - equity) / peak).max())
+
+
+def calmar_ratio(returns: np.ndarray, *, periods: int = DAYS_PER_YEAR) -> float:
+    mdd = max_drawdown(returns)
+    if mdd < 1e-12:
+        return float("inf")
+    return annualised_return(returns, periods=periods) / mdd
+
+
+def information_coefficient(pred: np.ndarray, target: np.ndarray) -> float:
+    """Pearson IC. NaNs are dropped pairwise."""
+    valid = np.isfinite(pred) & np.isfinite(target)
+    if valid.sum() < 2:
+        return 0.0
+    p = pred[valid]
+    t = target[valid]
+    pm = p - p.mean()
+    tm = t - t.mean()
+    denom = np.sqrt((pm ** 2).sum() * (tm ** 2).sum())
+    if denom < 1e-12:
+        return 0.0
+    return float((pm * tm).sum() / denom)
+
+
+def rank_information_coefficient(pred: np.ndarray, target: np.ndarray) -> float:
+    """Spearman IC."""
+    from scipy.stats import rankdata
+    valid = np.isfinite(pred) & np.isfinite(target)
+    if valid.sum() < 2:
+        return 0.0
+    return information_coefficient(rankdata(pred[valid]), rankdata(target[valid]))
+
+
+def turnover(weights: np.ndarray) -> float:
+    """Average L1 turnover between consecutive weight vectors."""
+    if weights.shape[0] < 2:
+        return 0.0
+    return float(0.5 * np.abs(weights[1:] - weights[:-1]).sum(axis=1).mean())

mlquant/cli/__init__.py

@@ -0,0 +1 @@
+"""``mlquant`` Click entry points (``mlquant gen-data``, ``mlquant features`` ...)."""

mlquant/cli/main.py

@@ -0,0 +1,292 @@
+"""Command-line entry point: ``mlquant <subcommand> --config configs/foo.yaml``.
+
+Subcommands form a deterministic pipeline; each writes its outputs to a
+sub-directory of ``artifacts/`` so downstream stages can be re-run
+without recomputing upstream work.
+"""
+from __future__ import annotations
+
+import json
+import math
+import pickle
+from importlib.resources import as_file, files
+from pathlib import Path
+
+import click
+import numpy as np
+import torch
+
+from ..backtest.engine import run_backtest
+from ..data.synthetic import SyntheticConfig, make_synthetic_panel
+from ..features.legacy_factors import compute_legacy_set
+from ..features.alpha101 import compute_alpha_set  # backward compat
+from ..features.bias import limit_move_mask
+from ..models.losses import AdjMSELoss
+from ..models.nets import MLPRegressor
+from ..portfolio.markowitz import MarkowitzConfig, MarkowitzOptimizer
+from ..training.dataset import FactorDataset
+from ..training.trainer import TrainConfig, Trainer
+from ..utils.config import load_config
+from ..utils.seed import seed_everything
+
+
+def _artifacts_dir(cfg) -> Path:
+    p = Path(cfg.get("artifacts_dir", "artifacts"))
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _write_backtest_summary(
+    output_dir: Path,
+    metrics: dict,
+    *,
+    config_path: str,
+    costs_bps: float,
+) -> tuple[Path, Path]:
+    """Write portable JSON and Markdown summaries for sharing and review."""
+    clean_metrics = {
+        key: value if not isinstance(value, float) or math.isfinite(value) else None
+        for key, value in metrics.items()
+    }
+    payload = {
+        "project": "ml-quant-trading",
+        "workflow": "synthetic factor-to-backtest demo",
+        "config": config_path,
+        "costs_bps": float(costs_bps),
+        "metrics": clean_metrics,
+        "disclaimer": (
+            "Synthetic research output only; not investment advice or evidence of live performance."
+        ),
+    }
+    json_path = output_dir / "summary.json"
+    json_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+
+    rows = []
+    for key, value in clean_metrics.items():
+        if value is None:
+            display = "n/a"
+        elif isinstance(value, float):
+            display = f"{value:.6f}"
+        else:
+            display = str(value)
+        rows.append(f"| `{key}` | {display} |")
+
+    markdown = "\n".join(
+        [
+            "# mlquant demo result",
+            "",
+            f"- Config: `{config_path}`",
+            f"- Transaction cost assumption: `{costs_bps:g} bps`",
+            "- Workflow: synthetic data → 213 factors → MLP → Markowitz → backtest",
+            "",
+            "| Metric | Value |",
+            "|---|---:|",
+            *rows,
+            "",
+            "> Synthetic research output only. This is not investment advice or evidence of",
+            "> live or out-of-sample trading performance.",
+            "",
+        ]
+    )
+    markdown_path = output_dir / "summary.md"
+    markdown_path.write_text(markdown)
+    return markdown_path, json_path
+
+
+# ---------------------------------------------------------------------------
+# Click app
+# ---------------------------------------------------------------------------
+@click.group()
+def cli() -> None:
+    """ml-quant-trading command-line interface."""
+
+
+@cli.command("demo")
+@click.option(
+    "--config",
+    "config_path",
+    default=None,
+    show_default="packaged small config",
+    type=click.Path(exists=True),
+)
+@click.pass_context
+def cmd_demo(ctx: click.Context, config_path: str | None) -> None:
+    """Run the complete synthetic factor-to-backtest pipeline."""
+    if config_path is not None:
+        _run_demo(ctx, config_path)
+        return
+
+    default_config = files("mlquant.configs").joinpath("small.yaml")
+    with as_file(default_config) as default_path:
+        click.echo("Using packaged default config (override with --config PATH).\n")
+        _run_demo(ctx, str(default_path))
+
+
+def _run_demo(ctx: click.Context, config_path: str) -> None:
+    """Run all demo stages with an explicit, existing config path."""
+    stages = (
+        ("1/5 Generate deterministic synthetic data", cmd_gen_data),
+        ("2/5 Compute the 213-factor tensor", cmd_features),
+        ("3/5 Train the baseline model", cmd_train),
+        ("4/5 Build portfolio weights", cmd_portfolio),
+        ("5/5 Run the cost-aware backtest", cmd_backtest),
+    )
+    click.echo("mlquant demo — data → factors → model → portfolio → backtest\n")
+    for label, command in stages:
+        click.echo(f"[{label}]")
+        ctx.invoke(command, config_path=config_path)
+        click.echo()
+    click.echo("Demo complete. Inspect the backtest summary above and artifacts/ for outputs.")
+
+
+@cli.command("gen-data")
+@click.option("--config", "config_path", required=True, type=click.Path(exists=True))
+def cmd_gen_data(config_path: str) -> None:
+    cfg = load_config(config_path)
+    seed_everything(cfg.get("seed", 42))
+    syn = SyntheticConfig(**cfg.synthetic.to_dict()) if "synthetic" in cfg else SyntheticConfig()
+    panel = make_synthetic_panel(syn)
+    out = _artifacts_dir(cfg) / "panel.pt"
+    torch.save({
+        "dates": panel.dates, "stocks": panel.stocks,
+        "open":  panel.open,  "high":  panel.high,  "low":  panel.low,
+        "close": panel.close, "volume": panel.volume, "vwap": panel.vwap,
+        "mask":  panel.mask,
+    }, out)
+    click.echo(f"wrote {out}  ({panel.n_dates} dates × {panel.n_stocks} stocks)")
+
+
+@cli.command("features")
+@click.option("--config", "config_path", required=True, type=click.Path(exists=True))
+def cmd_features(config_path: str) -> None:
+    cfg = load_config(config_path)
+    seed_everything(cfg.get("seed", 42))
+    art = _artifacts_dir(cfg)
+    panel_blob = torch.load(art / "panel.pt", weights_only=False)
+    from ..data.panel import Panel
+    panel = Panel(
+        dates=panel_blob["dates"], stocks=panel_blob["stocks"],
+        open=panel_blob["open"], high=panel_blob["high"], low=panel_blob["low"],
+        close=panel_blob["close"], volume=panel_blob["volume"], vwap=panel_blob["vwap"],
+        mask=panel_blob["mask"],
+    )
+    bias_mask = limit_move_mask(panel, limit_pct=cfg.get("limit_pct", 0.098))
+    factors, mask, names = compute_legacy_set(panel)
+    mask = mask & bias_mask
+    torch.save({"factors": factors, "mask": mask, "names": names}, art / "features.pt")
+    click.echo(f"wrote features: {factors.shape}  alphas={names}")
+
+
+@cli.command("train")
+@click.option("--config", "config_path", required=True, type=click.Path(exists=True))
+def cmd_train(config_path: str) -> None:
+    cfg = load_config(config_path)
+    seed_everything(cfg.get("seed", 42))
+    art = _artifacts_dir(cfg)
+    panel_blob = torch.load(art / "panel.pt", weights_only=False)
+    feat_blob  = torch.load(art / "features.pt", weights_only=False)
+
+    close = panel_blob["close"]
+    fwd_ret = torch.zeros_like(close)
+    fwd_ret[:-1] = close[1:] / close[:-1].clamp_min(1e-9) - 1.0
+
+    ds = FactorDataset(
+        factors=feat_blob["factors"],
+        mask=feat_blob["mask"],
+        forward_returns=fwd_ret,
+    )
+    n_features = ds.features.shape[1]
+    model = MLPRegressor(in_dim=n_features, hidden=cfg.get("hidden", 128))
+    trainer = Trainer(model, AdjMSELoss(gamma=cfg.get("loss_gamma", 0.1)),
+                      TrainConfig(**(cfg.train.to_dict() if "train" in cfg else {})))
+    trainer.fit(ds)
+
+    # Write predictions for every (t, n) cell that's tradable.
+    with torch.no_grad():
+        T, N, F = feat_blob["factors"].shape
+        flat = feat_blob["factors"].reshape(-1, F)
+        pred = model(flat.to(trainer.cfg.device)).cpu().reshape(T, N)
+    pred = pred * feat_blob["mask"].float()
+    torch.save({"pred": pred}, art / "predictions.pt")
+    click.echo(f"wrote predictions: {pred.shape}")
+
+
+@cli.command("portfolio")
+@click.option("--config", "config_path", required=True, type=click.Path(exists=True))
+def cmd_portfolio(config_path: str) -> None:
+    cfg = load_config(config_path)
+    seed_everything(cfg.get("seed", 42))
+    art = _artifacts_dir(cfg)
+    panel_blob = torch.load(art / "panel.pt", weights_only=False)
+    pred_blob  = torch.load(art / "predictions.pt", weights_only=False)
+
+    close = panel_blob["close"].numpy()
+    mask = panel_blob["mask"].numpy()
+    pred = pred_blob["pred"].numpy()
+    rets = np.zeros_like(close)
+    rets[1:] = close[1:] / np.clip(close[:-1], 1e-9, None) - 1.0
+
+    look_back = cfg.get("cov_lookback", 60)
+    mk_cfg = MarkowitzConfig(**(cfg.portfolio.to_dict() if "portfolio" in cfg else {}))
+    opt = MarkowitzOptimizer(mk_cfg)
+
+    T, N = pred.shape
+    weights = np.zeros_like(pred)
+    for t in range(look_back, T - 1):
+        tradable = mask[t]
+        idx = np.where(tradable)[0]
+        if idx.size < 5:
+            continue
+        mu = pred[t, idx].astype(np.float64)
+        history = rets[t - look_back:t, idx]
+        try:
+            w = opt.solve(mu, history)
+        except Exception as exc:                          # pragma: no cover
+            click.echo(f"[warn] solver failed at t={t}: {exc}")
+            continue
+        weights[t, idx] = w
+    torch.save({"weights": torch.from_numpy(weights)}, art / "weights.pt")
+    click.echo(f"wrote weights: {weights.shape}")
+
+
+@cli.command("backtest")
+@click.option("--config", "config_path", required=True, type=click.Path(exists=True))
+def cmd_backtest(config_path: str) -> None:
+    cfg = load_config(config_path)
+    art = _artifacts_dir(cfg)
+    panel_blob = torch.load(art / "panel.pt", weights_only=False)
+    weight_blob = torch.load(art / "weights.pt", weights_only=False)
+
+    close = panel_blob["close"].numpy()
+    rets = np.zeros_like(close)
+    rets[1:] = close[1:] / np.clip(close[:-1], 1e-9, None) - 1.0
+
+    weights = weight_blob["weights"].numpy()
+    costs_bps = cfg.get("costs_bps", 5.0)
+    res = run_backtest(weights, rets, costs_bps=costs_bps)
+    out = art / "backtest.pkl"
+    with open(out, "wb") as fh:
+        pickle.dump(res, fh)
+    markdown_path, json_path = _write_backtest_summary(
+        art,
+        res.metrics,
+        config_path=config_path,
+        costs_bps=costs_bps,
+    )
+
+    click.echo("\nBacktest summary")
+    click.echo("-" * 40)
+    for k, v in res.metrics.items():
+        if isinstance(v, float):
+            click.echo(f"  {k:<12s}  {v:>10.4f}")
+        else:
+            click.echo(f"  {k:<12s}  {v:>10}")
+    click.echo(f"\nShareable reports: {markdown_path}  {json_path}")
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":              # pragma: no cover
+    main()

mlquant/configs/__init__.py

@@ -0,0 +1 @@
+"""Packaged configuration files for zero-setup CLI entry points."""

mlquant/configs/small.yaml

@@ -0,0 +1,41 @@
+# Small synthetic config — runs end-to-end in <1 minute on a laptop CPU.
+# This is the configuration that `make paper` and CI exercise.
+
+seed: 42
+artifacts_dir: artifacts/small
+limit_pct: 0.098
+costs_bps: 5.0
+cov_lookback: 60
+hidden: 64
+loss_gamma: 0.1
+
+synthetic:
+  n_stocks:     200
+  n_dates:      500
+  start_date:   "2022-01-04"
+  annual_drift: 0.05
+  annual_vol:   0.30
+  market_beta:  0.6
+  halt_prob:    0.005
+  limit_pct:    0.10
+  seed:         42
+  device:       cpu
+
+train:
+  epochs:       8
+  batch_size:   1024
+  lr:           1.0e-3
+  weight_decay: 1.0e-5
+  grad_clip:    1.0
+  device:       cpu
+  log_every:    50
+  save_dir:     artifacts/small/checkpoints
+  val_split:    0.1
+
+portfolio:
+  risk_aversion: 5.0
+  weight_cap:    0.05
+  long_only:     true
+  cash_weight:   0.0
+  solver:        SCS
+  shrinkage:     true

mlquant/data/__init__.py

@@ -0,0 +1,88 @@
+"""Panel-data loaders + synthetic generator.
+
+The package treats market data as a pair of ``[date, stock]`` torch
+tensors plus a boolean mask telling us which cells are tradable. All
+downstream code (factors, training, portfolio) operates on this layout.
+
+Five data sources are wired up out of the box:
+
+* ``"synthetic"`` — :func:`make_synthetic_panel`, deterministic GBM panel
+  for tests, demos and CI.
+* ``"csv"`` — :func:`load_ochlv_csv`, generic tab-separated Wind / Tushare
+  dump with optional ``LIMIT_UP`` / ``LIMIT_DOWN`` / ``LAST_CLOSE`` /
+  ``S_DQ_AMOUNT`` columns.
+* ``"yfinance"`` — :func:`load_yfinance_panel`, public Yahoo Finance
+  market data.
+* ``"baostock"`` — :func:`load_baostock_panel`, authenticated A-share
+  daily data.
+* ``"akshare"`` — :func:`load_akshare_panel`, zero-auth A-share daily
+  data from public upstream interfaces.
+
+All return the same :class:`Panel`, so consumers should never branch
+on the source.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+from .panel import Panel
+from .synthetic import SyntheticConfig, make_synthetic_panel
+from .loaders import load_ochlv_csv
+from .yfinance_loader import load_yfinance_panel
+from .baostock_loader import load_baostock_panel
+from .akshare_loader import load_akshare_panel
+
+__all__ = [
+    "Panel",
+    "SyntheticConfig",
+    "make_synthetic_panel",
+    "load_ochlv_csv",
+    "load_yfinance_panel",
+    "load_baostock_panel",
+    "load_akshare_panel",
+    "make_panel",
+]
+
+
+def make_panel(source: str = "synthetic", **kwargs: Any) -> Panel:
+    """Build a panel from synthetic, CSV, yfinance, Baostock, or AkShare data.
+
+    Parameters
+    ----------
+    source : str
+        One of ``"synthetic"``, ``"csv"``, ``"yfinance"``,
+        ``"baostock"``, or ``"akshare"``.
+    **kwargs
+        Source-specific keyword arguments.
+    """
+    if source == "synthetic":
+        cfg = SyntheticConfig(**kwargs) if kwargs else None
+        return make_synthetic_panel(cfg)
+    if source == "csv":
+        path: Optional[str | Path] = kwargs.pop("path", None)
+        if path is None:
+            raise TypeError("make_panel(source='csv', ...) requires a `path=` kwarg")
+        return load_ochlv_csv(path, **kwargs)
+    if source == "yfinance":
+        tickers = kwargs.pop("tickers", None)
+        start = kwargs.pop("start", None)
+        end = kwargs.pop("end", None)
+        if tickers is None or start is None or end is None:
+            raise TypeError("make_panel(source='yfinance', ...) requires `tickers`, `start`, and `end` kwargs")
+        return load_yfinance_panel(tickers, start, end, **kwargs)
+    if source == "baostock":
+        tickers = kwargs.pop("tickers", None)
+        start = kwargs.pop("start", None)
+        end = kwargs.pop("end", None)
+        if tickers is None or start is None or end is None:
+            raise TypeError("make_panel(source='baostock', ...) requires `tickers`, `start`, and `end` kwargs")
+        return load_baostock_panel(tickers, start, end, **kwargs)
+    if source == "akshare":
+        tickers = kwargs.pop("tickers", None)
+        start = kwargs.pop("start", None)
+        end = kwargs.pop("end", None)
+        if tickers is None or start is None or end is None:
+            raise TypeError("make_panel(source='akshare', ...) requires `tickers`, `start`, and `end` kwargs")
+        return load_akshare_panel(tickers, start, end, **kwargs)
+    raise ValueError(f"unknown panel source: {source!r}")