msd-backtest 0.1.0__py3-none-any.whl

mbt/run/runner.py

@@ -0,0 +1,85 @@
+from mbt.account import Operation, ACTION_BUY_PERCENT, ACTION_SELL_PERCENT
+from mbt.strategy import Context
+from mbt.account import Account
+from mbt.strategy import Strategy
+import numpy as np
+
+
+class RunnerContext(Context):
+  """RunnerContext is a context for a strategy
+
+  It is used to pass data and operations to a strategy.
+
+  Data required internally are:
+  - ts: timestamp
+  - price: price of the stock
+  Data optional internally are:
+    - "dividend": dividend per share in dividend
+    - "transfer_shares": transfer shares per share in dividend
+    - "right_shares": right share per share in dividend
+    - "right_price": right price per share in dividend
+  Other data can be added by user for specific strategy
+
+  The strategy can use the following methods to operate the account:
+  - buy: buy a position
+  - sell: sell a position
+  and refer data by `ctx.data_name`
+  """
+
+  def __init__(self, account: Account):
+    self.accounts = [account.clone(g) for g in range(account.dp.groups)]
+    self.dp = account.dp
+    self.actions = np.zeros(len(self.dp.dates), dtype=np.int32)
+    self.action_percents = np.zeros(len(self.dp.dates), dtype=np.float64)
+
+  def data(self, name: str, /, symbol: str | None = None) -> np.ndarray:
+    # user may use it like ctx.open, ctx.high, ctx.low, ctx.close, ctx.volume
+    if name in self.dp.data:
+      return self.dp.all(name, symbol=symbol)
+    raise ValueError(f"data '{name}' not found")
+
+  def buy(self, flags: np.ndarray, percent: float = 1.0):
+    for g in range(self.dp.groups):
+      j = g * self.dp.bars + self.dp.i
+      if flags[j]:
+        self.actions[j] = ACTION_BUY_PERCENT
+        self.action_percents[j] = percent
+
+  def sell(self, flags: np.ndarray, percent: float = 1.0):
+    for g in range(self.dp.groups):
+      j = g * self.dp.bars + self.dp.i
+      if flags[j]:
+        self.actions[j] = ACTION_SELL_PERCENT
+        self.action_percents[j] = percent
+
+
+class Runner:
+  """Runner is a runner of a strategy"""
+
+  def __init__(self, account: Account):
+    self.ctx = RunnerContext(account)
+
+  def run(self, strategy: Strategy):
+    prices = self.ctx.dp.all("price")
+    for i in self.ctx.dp:
+      strategy.execute(self.ctx)
+      for g in range(self.ctx.dp.groups):
+        j = g * self.ctx.dp.bars + self.ctx.dp.i
+        action = self.ctx.actions[j]
+        percent = self.ctx.action_percents[j]
+        if action == ACTION_BUY_PERCENT:
+          self.ctx.accounts[g].do_operation(
+            self.ctx.dp.i,
+            Operation.buy_percent(
+              percent, prices[j] * (1 + self.ctx.accounts[g].slippage)
+            ),
+          )
+        elif action == ACTION_SELL_PERCENT:
+          self.ctx.accounts[g].do_operation(
+            self.ctx.dp.i,
+            Operation.sell_percent(
+              percent, prices[j] * (1 - self.ctx.accounts[g].slippage)
+            ),
+          )
+        else:
+          self.ctx.accounts[g].do_operation(self.ctx.dp.i, Operation.keep(prices[j]))

mbt/run/server.py

@@ -0,0 +1,103 @@
+from dotenv import load_dotenv
+load_dotenv(override=True)
+
+from mbt import Runner, Account, Fee
+from mbt.run import Report, build_report, build_json_report, RunRequest
+from mbt.run.msd import load_data
+import logging
+from typing import List, Optional
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+import os
+
+# Configuration
+logging.basicConfig(
+  format="%(asctime)s %(name)s %(levelname)s %(message)s", level=logging.INFO
+)
+logger = logging.getLogger("backtest-server")
+
+DEFAULT_MSD_HOST = "http://localhost:50510"
+
+DEFAULT_FEE = Fee()
+
+app = FastAPI(title="MSD Backtest Server")
+
+
+class RunRequestModel(BaseModel):
+  strategy: str
+  symbols: List[str]
+  start: str
+  end: str
+  args: Optional[List] = None
+
+
+
+
+@app.post("/backtest")
+async def run_backtest(req_model: RunRequestModel):
+  try:
+    logger.info(f"Received backtest request for symbols: {req_model.symbols}")
+
+    # Use RunRequest to load the strategy (can be source code or file path)
+    # The RunRequest class in backend.py expects strategy, symbols, start, end, args
+    # We'll pass the strategy string directly to load_strategy logic if needed,
+    # but RunRequest handles it.
+
+    # We need to load data first as in cli.py
+    logger.info(f"Loading data from {DEFAULT_MSD_HOST} for {req_model.symbols}")
+    dp, symbols = load_data(
+      DEFAULT_MSD_HOST, req_model.symbols, req_model.start, req_model.end
+    )
+
+    if "ts" not in dp.data:
+      raise ValueError(
+        "No data found for the given symbols and date range. Please check your MSD server and parameters."
+      )
+
+    logger.info("Data loaded successfully")
+
+    # Initialize Account and Runner
+    account = Account(10000.0, dp, fee=DEFAULT_FEE)
+    runner = Runner(account)
+
+    # Load the strategy using backend logic
+    # RunRequest constructor expects strategy as (str | IO | Strategy)
+    strategy_obj = RunRequest.load_strategy(req_model.strategy, args=req_model.args)
+
+    logger.info("Running strategy...")
+    runner.run(strategy_obj)
+    logger.info("Strategy run completed")
+
+    # Build report
+    reports = build_report(dp, runner.ctx.accounts)[1:]
+    report = build_json_report(reports)
+    return report
+
+  except Exception as e:
+    logger.exception("Error during backtest execution")
+    raise HTTPException(status_code=500, detail=str(e))
+
+
+if __name__ == "__main__":
+  import uvicorn
+  import argparse
+
+  parser = argparse.ArgumentParser(description="MSD Backtest Server")
+  parser.add_argument("--host", default="0.0.0.0", help="Listen host")
+  parser.add_argument("--port", type=int, default=8000, help="Listen port")
+  parser.add_argument(
+    "--msd", default=os.getenv("MSD_HOST", DEFAULT_MSD_HOST), help="Default MSD host"
+  )
+  parser.add_argument(
+    "--fee",
+    default=os.environ.get("MSD_BT_FEE", ""),
+    help="fee config path, env $MSD_BT_FEE",
+  )
+  args = parser.parse_args()
+
+  if len(args.fee) > 0:
+    DEFAULT_FEE = Fee(args.fee)
+
+  DEFAULT_MSD_HOST = args.msd
+
+  uvicorn.run(app, host=args.host, port=args.port)

mbt/strategy.py

@@ -0,0 +1,85 @@
+from mbt.account import Operation
+import numpy as np
+
+
+class Context:
+  """Context of a strategy"""
+
+  def __init__(self):
+    pass
+
+  def order(self, op: Operation) -> Operation:
+    """
+    execute an operation and return the result
+
+    Args:
+      op: operation to be executed
+    """
+    pass
+
+  def data(self, name: str, /, symbol: str | None = None) -> np.ndarray:
+    """
+    return the corresponding data
+
+    Args:
+      name: name of the data
+
+    Returns:
+      numpy array of the data
+    """
+    pass
+
+  def __getattr__(self, name: str) -> np.ndarray:
+    """
+    return the corresponding data
+
+    Args:
+      name: name of the data
+
+    Returns:
+      numpy array of the data
+    """
+    return self.data(name)
+
+  def symbols(self) -> list[str]:
+    """
+    return the symbols of the account
+
+    Returns:
+      list of symbols
+    """
+    pass
+
+  def buy(self, flags: np.ndarray, percent: float = 1.0):
+    """
+    buy a position
+
+    Args:
+      flags: boolean array of flags, True means buy
+      percent: percent of cash to buy
+    """
+    pass
+
+  def sell(self, flags: np.ndarray, percent: float = 1.0):
+    """
+    sell a position
+
+    Args:
+      flags: boolean array of flags, True means sell
+      percent: percent of position to sell
+    """
+    pass
+
+
+class Strategy:
+  """Base class of a strategy"""
+
+  def execute(self, ctx: Context):
+    """
+    execute the strategy, this method will be called for each bar.
+    use ctx.order() to order, ctx.data() to get data
+
+    Args:
+      ctx: context of the strategy
+    """
+    pass

msd_backtest-0.1.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: msd-backtest
+Version: 0.1.0
+Summary: MSD backtest framework
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=2.4.2
+Provides-Extra: alpha
+Requires-Dist: py-alpha-lib>=0.2; extra == "alpha"
+Provides-Extra: msd
+Requires-Dist: pymsd>=0.1; extra == "msd"
+Requires-Dist: requests>=2.32; extra == "msd"
+Requires-Dist: pandas>=3.0; extra == "msd"
+Provides-Extra: server
+Requires-Dist: fastapi[standard]>=0.135.1; extra == "server"
+Requires-Dist: msd-backtest[cli]; extra == "server"
+Provides-Extra: cli
+Requires-Dist: orjson>=3.11.9; extra == "cli"
+Requires-Dist: msd-backtest[alpha,msd]; extra == "cli"
+Requires-Dist: python-dotenv>=1.2.2; extra == "cli"
+Requires-Dist: tabulate>=0.10.0; extra == "cli"
+
+# msd-backtest
+
+`msd-backtest` 是一个基于 Python 的高性能、向量化股票策略回测框架。它旨在为量化开发者提供一个简单、高效且灵活的工具，用于开发、测试和优化交易策略。
+
+## 🌟 核心特性
+
+- **高性能向量化计算**：核心数据处理基于 NumPy，支持大规模数据的快速回测。
+- **多标的支持**：原生支持同时对多个股票或指数进行回测。
+- **模块化架构**：
+  - `Account`：模拟真实交易账户，处理资金、持仓、手续费和滑点。
+  - `Strategy`：解耦策略逻辑，通过继承 `Strategy` 基类快速实现自定义逻辑。
+  - `DataProvider`：灵活的数据提供接口，支持接入不同的行情数据源。
+- **完善的报表输出**：支持生成 CSV、Excel (XLSX) 和 JSON 格式的回测结果报表。
+- **内置 MSD 集成**：支持从 MSD (Market Strategy Data) 服务端直接拉取行情和财务数据。
+- **远程回测支持**：内置 FastAPI 服务器，支持跨语言或远程调用回测引擎。
+
+## 🚀 快速开始
+
+### 安装
+
+推荐使用 `uv` 进行依赖管理：
+
+#### 普通用户
+
+```bash
+uv add "msd-backtest[cli]" # 仅cli
+# or
+uv add "msd-backtest[server]" # 支持作为服务运行
+```
+
+#### 开发者
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-repo/msd-backtest.git
+cd msd-backtest
+
+# 安装依赖
+uv sync --with cli
+
+# 如果需要运行回测服务器
+uv sync --with server
+```
+
+### 运行回测
+
+你可以通过命令行工具直接运行已有的策略：
+
+```bash
+uv run python -m mbt.run.cli strategy/double_avg.py -s 000001.SZ 600000.SH --begin 2023-01-01 --end 2023-12-31 -o report.xlsx
+```
+
+**常用参数说明：**
+- `strategy`: 策略文件路径（`.py` 或 `.json`）。
+- `-s`, `--symbols`: 股票代码列表。
+- `-b`, `--begin`: 开始日期 (YYYY-MM-DD)。
+- `-e`, `--end`: 结束日期 (YYYY-MM-DD)。
+- `-o`, `--output`: 输出文件路径（支持 `.csv`, `.xlsx`, `.json`）。
+
+## 🛡️ 回测机制：杜绝未来数据
+
+`msd-backtest` 采用**逐条数据迭代**（Bar-by-Bar Iteration）的执行机制，确保回测过程的严谨性和真实性。
+
+- **单向时间线**：回测引擎（`mbt.Runner`）严格按照时间顺序，逐个时间步调用策略的 `execute` 方法。
+- **数据隔离**：在任一时刻，策略仅能通过 `ctx` 访问当前及之前的数据，无法窥视未来的行情。
+- **真实模拟**：所有的买卖指令都在当前 Bar 生成，并在当前或下一个 Bar 的价格基础上执行（取决于配置和滑点），完美模拟真实市场的环境。
+
+## 💡 编写你的策略
+
+编写策略非常简单，只需要继承 `mbt.Strategy` 并实现 `execute` 方法：
+
+```python
+from mbt import Strategy, Context
+
+class MyStrategy(Strategy):
+    def __init__(self, fast_period=5, slow_period=20):
+        self.fast_period = fast_period
+        self.slow_period = slow_period
+
+    def execute(self, ctx: Context):
+        # 获取当前收盘价序列
+        close = ctx.close 
+        
+        # 计算移动平均线
+        # 注意：ctx 提供的是 NumPy 数组，支持向量化操作
+        # 这里仅为示意，实际开发中建议预计算指标
+        
+        # 买入逻辑示例
+        # ctx.buy(buy_flags, percent=1.0)
+        
+        # 卖出逻辑示例
+        # ctx.sell(sell_flags, percent=1.0)
+        pass
+```
+
+## 🧠 AI 辅助策略编写
+
+本项目深度集成 AI 辅助开发流程。利用 [msd_strategy](.agents/skills/write-strategy/SKILL.md) 技能，AI 可以根据用户描述自动生成符合规范的策略代码。
+
+### 核心方法与目标
+- **目标：** 通过自然语言描述，由 AI 生成高效、可运行的 Python 策略类。
+- **技术栈：** Python 3.11+, NumPy, `py-alpha-lib`。
+- **编码规范：**
+  - 必须继承 `mbt.Strategy`。
+  - 实现 `execute(self, ctx: mbt.Context)` 方法。
+  - 使用 `ctx.buy()` 和 `ctx.sell()` 进行下单。
+
+### 常用算子库 (alpha-lib)
+为了支持 AI 高效构建因子，框架内置了丰富的 `alpha-lib` 算子，包括：
+- **时间序列算子：** `MA`, `EMA`, `HHV`, `LLV`, `STDDEV`, `CORR`, `SLOPE` 等。
+- **横截面算子：** `CC_RANK`, `CC_ZSCORE`, `GROUP_RANK`, `NEUTRALIZE` 等。
+- **逻辑算子：** `CROSS`, `LONGCROSS`, `BARSLAST` 等。
+
+AI 在编写策略时应优先使用这些向量化算子，以确保最佳性能。
+
+## 📂 项目结构
+
+```text
+.
+├── mbt/                # 核心回测包
+│   ├── account.py      # 账户、持仓、手续费管理
+│   ├── strategy.py     # 策略基类与上下文定义
+│   ├── data_provider.py # 数据提供接口
+│   └── run/            # 运行引擎
+│       ├── runner.py   # 回测执行核心
+│       ├── cli.py      # 命令行界面
+│       ├── msd.py      # MSD 数据源接入
+│       └── server.py    # REST API 服务
+├── strategy/           # 示例策略目录
+├── tests/              # 单元测试
+└── pyproject.toml      # 项目配置与依赖说明
+```
+
+## 🔧 进阶配置
+
+### 手续费配置 (Fee)
+
+在 `mbt/account.py` 中支持自定义手续费。你可以通过 JSON 配置文件或代码中初始化 `Fee` 类来设置不同时间段的印花税、过户费及佣金。
+
+### 复权处理
+
+`msd-backtest` 默认在 `mbt/run/msd.py` 中实现了前/后复权的计算逻辑，确保回测收益计算的准确性。
+
+## 🛠️ 开发与测试
+
+运行单元测试：
+
+```bash
+uv run pytest
+```
+
+运行性能基准测试：
+
+```bash
+uv run pytest --benchmark-only
+```
+
+---
+
+*更多详细文档请参考各模块代码注释。*

msd_backtest-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mbt/__init__.py,sha256=4OzOWR9DtXwwcprjeq9EyPAc_nD2GfRjka5_QH56To8,503
+mbt/account.py,sha256=SIJdlolAcZVcf6ctvjXLR956KAG9fe35iMD1FhEa52M,13375
+mbt/data_provider.py,sha256=ZoG-rT2K-EFbC4Mi5mSdc-OaQy0E0nSFTRi3il63F9A,4142
+mbt/strategy.py,sha256=krDT_EBGCR_HEw_-QKejnLfQ2M0gvdJWZD4zPC1KxXI,1555
+mbt/run/__init__.py,sha256=KVdmGXMB0CZulU3IlcLpgVM4e8utSlsg4on504Z3CHI,165
+mbt/run/backend.py,sha256=sh2LjlSCe-KqGu2qlqn7EWhCkPZwYHuPlR3eGxrB4Hs,2973
+mbt/run/cli.py,sha256=EfxlGRnkBsgQ5hXTS4sfCUckK0K8ENGdLXtW_0mfi2A,5843
+mbt/run/msd.py,sha256=yWhxFOt0x3ATv6mCT4LrvkOe4klWDIgzZxJj0psCw4k,2774
+mbt/run/report.py,sha256=SERAHZ6LHnPvDWdgoWi4KTEU3DNVgVvePabcmsH1Cks,9951
+mbt/run/review.py,sha256=udkiOG8E2bwNhGcILfJgkt-63oVLXCdgRYNmbryjUao,2192
+mbt/run/runner.py,sha256=9YHciHsZZSsSWl8CMIqwVFEIwb_2JKUtQW0eLNiL0w0,2959
+mbt/run/server.py,sha256=Rwqioec8g_vM2qv5sek7VdOxGu1LLFyZu4iQYx1ZyNI,3023
+mbt/select/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+msd_backtest-0.1.0.dist-info/METADATA,sha256=dd4_Lu4tNjClc3d2guoZww2Uyt-nADLcV3_8s_XBrGg,6449
+msd_backtest-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+msd_backtest-0.1.0.dist-info/top_level.txt,sha256=GXOojMcn-hI0kcRSUPX73WOB_zhHW35goKON-Rxu_dg,4
+msd_backtest-0.1.0.dist-info/RECORD,,

msd_backtest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

msd_backtest-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mbt