Make Backtrader an optional extra

CLAUDE.md

@@ -26,6 +26,10 @@ uv run python cli.py portfolio eval --positions-path portfolio/eq_10m.pq --data-
 
 Add a runtime dep with `uv add <pkg>`, a dev/test dep with `uv add --dev <pkg>` (both update `pyproject.toml` + `uv.lock`).
 
+Backtrader is optional (`uv sync --extra backtrader`) and is not used by the
+current pipeline. Keep `portfolio simulate` as the canonical backtest/execution
+path unless an explicit future adapter is requested.
+
 Note: `tests/test_downloader.py` hits the network (live baostock/akshare); `tests/test_alpha.py` and `tests/test_portfolio.py` are pure and fast.
 
 ## Architecture: one decoupled pipeline

README.md

@@ -48,6 +48,13 @@ The env is managed with [uv](https://docs.astral.sh/uv/). `uv sync` builds `.ven
 uv sync
 ```
 
+Backtrader is an optional dependency and is **not used by the current pipeline**.
+Install it only for future experiments or adapter work:
+
+```bash
+uv sync --extra backtrader
+```
+
 ## Quick start
 
 ```bash
@@ -401,6 +408,9 @@ constructed positions, fills/costs, P&L, and target-weight research metrics.
 - [x] **Reference execution simulation** — next-open fills over constructed
   `position_shares`, with suspension, price-limit, volume-cap, transaction-cost,
   and slippage controls.
+- [ ] **Optional Backtrader adapter** — Backtrader is available as the
+  `backtrader` extra for possible future event-driven/broker-style experiments,
+  but it is not part of the current canonical portfolio workflow.
 - [ ] **Forward / paper trading** — run the same construction logic on live
   daily data, track simulated fills and a running P&L without real capital.
 - [ ] **Intraday / microstructure data** — bid/ask prices & sizes, mid-price,

pyproject.toml

@@ -4,7 +4,6 @@ version = "0.1.0"
 description = "A modular Chinese A-share quant research framework (daily frequency)."
 requires-python = ">=3.10"
 dependencies = [
-    "backtrader>=1.9.76.123",
     "akshare>=1.14.0",
     "baostock>=0.8.8",
     "pandas>=2.0.0",
@@ -13,6 +12,11 @@ dependencies = [
     "pyarrow>=14.0.0",
 ]
 
+[project.optional-dependencies]
+backtrader = [
+    "backtrader>=1.9.76.123",
+]
+
 [dependency-groups]
 dev = [
     "pytest>=7.0.0",

uv.lock

@@ -284,7 +284,6 @@ version = "0.1.0"
 source = { virtual = "." }
 dependencies = [
     { name = "akshare" },
-    { name = "backtrader" },
     { name = "baostock" },
     { name = "click" },
     { name = "matplotlib" },
@@ -293,6 +292,11 @@ dependencies = [
     { name = "pyarrow" },
 ]
 
+[package.optional-dependencies]
+backtrader = [
+    { name = "backtrader" },
+]
+
 [package.dev-dependencies]
 dev = [
     { name = "pytest" },
@@ -301,13 +305,14 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "akshare", specifier = ">=1.14.0" },
-    { name = "backtrader", specifier = ">=1.9.76.123" },
+    { name = "backtrader", marker = "extra == 'backtrader'", specifier = ">=1.9.76.123" },
     { name = "baostock", specifier = ">=0.8.8" },
     { name = "click", specifier = ">=8.0.0" },
     { name = "matplotlib", specifier = ">=3.7.0" },
     { name = "pandas", specifier = ">=2.0.0" },
     { name = "pyarrow", specifier = ">=14.0.0" },
 ]
+provides-extras = ["backtrader"]
 
 [package.metadata.requires-dev]
 dev = [{ name = "pytest", specifier = ">=7.0.0" }]