docs: add custom data loader guide

README.md

@@ -264,6 +264,52 @@ Detailed inventories are folded below to keep the main README scannable. Open th
 
 </details>
 
+<details>
+<summary><b>Custom Data Source</b> <sub>register your own historical OHLCV loader</sub></summary>
+
+Need a market or vendor we don't ship a loader for? Add your own historical-bar
+loader and select it with `source="<name>"`. The steps edit package source, so
+run from a clone (`pip install -e .`).
+
+1. **Write the loader** — create `agent/backtest/loaders/<name>_loader.py` with a
+   class that satisfies `DataLoaderProtocol` (duck-typed, no base class needed)
+   and is tagged with `@register`:
+
+   ```python
+   import pandas as pd
+   from backtest.loaders.registry import register
+
+   @register
+   class DataLoader:
+       name = "mysource"            # the value you pass as source=
+       markets = {"us_equity"}      # a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex
+       requires_auth = False
+
+       def is_available(self) -> bool:
+           return True              # token present? network reachable?
+
+       def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None):
+           # return {symbol: DataFrame indexed by trade_date,
+           #         columns: open, high, low, close, volume}
+           ...
+   ```
+
+2. **Register the module** so `@register` fires — add
+   `"backtest.loaders.<name>_loader"` to `_loader_modules` in
+   `agent/backtest/loaders/registry.py`.
+3. **Allow the name** through config validation — add `"mysource"` to
+   `_VALID_SOURCES` in `agent/backtest/runner.py`.
+4. *(Optional)* slot it into a market's `FALLBACK_CHAINS` in `registry.py` so
+   `source="auto"` can reach it.
+5. **Use it** — `source="mysource"` in a backtest config, or via the CLI / agent.
+
+> **Real-time ticks / order-book depth are out of scope for loaders** — the
+> loader layer is point-in-time historical bars only. Live market data flows
+> through the broker connectors instead: `okx` / `binance` / `ccxt` for crypto,
+> `futu` / `tiger` for equities.
+
+</details>
+
 <details>
 <summary><b>Preset Trading Teams</b> <sub>29 swarm presets</sub></summary>
 

README_ar.md

@@ -265,6 +265,50 @@ vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, an
 
 </details>
 
+<details>
+<summary><b>مصدر بيانات مخصص</b> <sub>سجّل loader تاريخيًا خاصًا بك لبيانات OHLCV</sub></summary>
+
+تحتاج إلى سوق أو مزوّد لا نوفّر له loader جاهزًا؟ أضِف loader تاريخيًا خاصًا بك
+واخترْه عبر `source="<name>"`. الخطوات التالية تعدّل مصدر الحزمة، لذا شغّلها من
+نسخة clone (`pip install -e .`).
+
+1. **اكتب الـ loader** —— أنشئ `agent/backtest/loaders/<name>_loader.py` مع صنف
+   يحقّق `DataLoaderProtocol` (duck-typed، دون صنف أساس) ووسمه بـ `@register`:
+
+   ```python
+   import pandas as pd
+   from backtest.loaders.registry import register
+
+   @register
+   class DataLoader:
+       name = "mysource"            # the value you pass as source=
+       markets = {"us_equity"}      # a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex
+       requires_auth = False
+
+       def is_available(self) -> bool:
+           return True              # token present? network reachable?
+
+       def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None):
+           # return {symbol: DataFrame indexed by trade_date,
+           #         columns: open, high, low, close, volume}
+           ...
+   ```
+
+2. **سجّل الوحدة** كي يعمل `@register` —— أضِف `"backtest.loaders.<name>_loader"`
+   إلى `_loader_modules` في `agent/backtest/loaders/registry.py`.
+3. **اسمح بالاسم** ليجتاز التحقق من الإعدادات —— أضِف `"mysource"` إلى
+   `_VALID_SOURCES` في `agent/backtest/runner.py`.
+4. *(اختياري)* أدرِجه ضمن `FALLBACK_CHAINS` لأحد الأسواق في `registry.py` كي
+   يصل إليه `source="auto"`.
+5. **استخدمه** —— `source="mysource"` في إعداد الباك-تست، أو عبر CLI / agent.
+
+> **بيانات الـ ticks اللحظية / عمق دفتر الأوامر خارج نطاق الـ loaders** —— طبقة
+> الـ loader تتعامل فقط مع الأشرطة التاريخية point-in-time. تتدفق بيانات السوق
+> اللحظية عبر broker connectors بدلًا من ذلك: `okx` / `binance` / `ccxt`
+> للعملات المشفّرة، و`futu` / `tiger` للأسهم.
+
+</details>
+
 <details>
 <summary><b>فرق تداول جاهزة</b> <sub>29 إعداد سرب مسبق</sub></summary>
 

README_ja.md

@@ -265,6 +265,50 @@ vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, an
 
 </details>
 
+<details>
+<summary><b>カスタムデータソース</b> <sub>独自の過去 OHLCV loader を登録</sub></summary>
+
+loader を同梱していない市場やベンダーが必要ですか？独自の過去バー loader を追加し、
+`source="<name>"` で選択できます。以下の手順はパッケージのソースを編集するため、
+clone から実行してください（`pip install -e .`）。
+
+1. **loader を書く** —— `agent/backtest/loaders/<name>_loader.py` を作成し、
+   `DataLoaderProtocol` を満たすクラス（duck-typed、基底クラス不要）を定義して
+   `@register` を付けます：
+
+   ```python
+   import pandas as pd
+   from backtest.loaders.registry import register
+
+   @register
+   class DataLoader:
+       name = "mysource"            # the value you pass as source=
+       markets = {"us_equity"}      # a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex
+       requires_auth = False
+
+       def is_available(self) -> bool:
+           return True              # token present? network reachable?
+
+       def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None):
+           # return {symbol: DataFrame indexed by trade_date,
+           #         columns: open, high, low, close, volume}
+           ...
+   ```
+
+2. **モジュールを登録** して `@register` を発火させる —— `agent/backtest/loaders/registry.py`
+   の `_loader_modules` に `"backtest.loaders.<name>_loader"` を追加します。
+3. **名前を許可** して設定バリデーションを通す —— `agent/backtest/runner.py` の
+   `_VALID_SOURCES` に `"mysource"` を追加します。
+4. *（任意）* `registry.py` のある市場の `FALLBACK_CHAINS` に組み込むと、
+   `source="auto"` からも到達できます。
+5. **使う** —— バックテスト設定で `source="mysource"`、または CLI / agent 経由で。
+
+> **リアルタイムの ticks / 板情報（depth）は loader の対象外です** —— loader 層は
+> point-in-time の過去バーのみを扱います。リアルタイム市場データは broker connector
+> を通します：暗号資産は `okx` / `binance` / `ccxt`、株式は `futu` / `tiger`。
+
+</details>
+
 <details>
 <summary><b>Preset Trading Teams</b> <sub>29 swarm presets</sub></summary>
 

README_ko.md

@@ -265,6 +265,50 @@ vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, an
 
 </details>
 
+<details>
+<summary><b>커스텀 데이터 소스</b> <sub>직접 만든 과거 OHLCV loader 등록</sub></summary>
+
+loader를 기본 제공하지 않는 시장이나 벤더가 필요하신가요? 직접 과거 봉 loader를
+추가하고 `source="<name>"`으로 선택하세요. 아래 단계는 패키지 소스를 수정하므로
+clone에서 실행하세요(`pip install -e .`).
+
+1. **loader 작성** —— `agent/backtest/loaders/<name>_loader.py`를 만들고
+   `DataLoaderProtocol`을 만족하는 클래스(duck-typed, 기반 클래스 불필요)를 정의한 뒤
+   `@register`를 붙입니다:
+
+   ```python
+   import pandas as pd
+   from backtest.loaders.registry import register
+
+   @register
+   class DataLoader:
+       name = "mysource"            # the value you pass as source=
+       markets = {"us_equity"}      # a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex
+       requires_auth = False
+
+       def is_available(self) -> bool:
+           return True              # token present? network reachable?
+
+       def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None):
+           # return {symbol: DataFrame indexed by trade_date,
+           #         columns: open, high, low, close, volume}
+           ...
+   ```
+
+2. **모듈 등록** 으로 `@register`가 실행되게 —— `agent/backtest/loaders/registry.py`의
+   `_loader_modules`에 `"backtest.loaders.<name>_loader"`를 추가합니다.
+3. **이름 허용** 으로 설정 검증 통과 —— `agent/backtest/runner.py`의
+   `_VALID_SOURCES`에 `"mysource"`를 추가합니다.
+4. *(선택)* `registry.py`의 특정 시장 `FALLBACK_CHAINS`에 넣으면
+   `source="auto"`로도 도달할 수 있습니다.
+5. **사용** —— 백테스트 설정에서 `source="mysource"`, 또는 CLI / agent를 통해.
+
+> **실시간 ticks / 호가창 depth는 loader 범위 밖입니다** —— loader 계층은
+> point-in-time 과거 봉만 다룹니다. 실시간 시장 데이터는 broker connector를
+> 통합니다: 암호화폐는 `okx` / `binance` / `ccxt`, 주식은 `futu` / `tiger`.
+
+</details>
+
 <details>
 <summary><b>프리셋 트레이딩 팀</b> <sub>29개 swarm preset</sub></summary>
 

README_zh.md

@@ -264,6 +264,48 @@ vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, an
 
 </details>
 
+<details>
+<summary><b>自定义数据源</b> <sub>注册你自己的历史 OHLCV loader</sub></summary>
+
+需要一个我们没有内置 loader 的市场或数据商？自己加一个历史 K 线 loader，用
+`source="<name>"` 选用即可。以下步骤会改动包源码，请从 clone 运行（`pip install -e .`）。
+
+1. **编写 loader** —— 新建 `agent/backtest/loaders/<name>_loader.py`，写一个满足
+   `DataLoaderProtocol` 的类（duck-typed，无需基类），并打上 `@register`：
+
+   ```python
+   import pandas as pd
+   from backtest.loaders.registry import register
+
+   @register
+   class DataLoader:
+       name = "mysource"            # the value you pass as source=
+       markets = {"us_equity"}      # a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex
+       requires_auth = False
+
+       def is_available(self) -> bool:
+           return True              # token present? network reachable?
+
+       def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None):
+           # return {symbol: DataFrame indexed by trade_date,
+           #         columns: open, high, low, close, volume}
+           ...
+   ```
+
+2. **注册模块** 让 `@register` 生效 —— 把 `"backtest.loaders.<name>_loader"` 加进
+   `agent/backtest/loaders/registry.py` 的 `_loader_modules`。
+3. **放行名称** 通过配置校验 —— 把 `"mysource"` 加进 `agent/backtest/runner.py`
+   的 `_VALID_SOURCES`。
+4. *（可选）* 把它放进 `registry.py` 中某个市场的 `FALLBACK_CHAINS`，让
+   `source="auto"` 也能命中它。
+5. **使用** —— 在回测配置里写 `source="mysource"`，或经 CLI / agent 调用。
+
+> **实时 ticks / 盘口深度不在 loader 范围内** —— loader 层只负责 point-in-time
+> 历史 K 线。实时行情走 broker connector：加密用 `okx` / `binance` / `ccxt`，
+> 股票用 `futu` / `tiger`。
+
+</details>
+
 <details>
 <summary><b>Preset Trading Teams</b> <sub>29 个 swarm presets</sub></summary>