diff --git a/README.md b/README.md index 9048e6e..f3f4580 100644 --- a/README.md +++ b/README.md @@ -1,194 +1,64 @@ # QuantStrategyPlugins - +[Chinese README](README.zh-CN.md) -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 > ⚠️ Investing involves risk. This project does not provide investment advice and is for educational and research purposes only. -## Open-source overview / 开源项目入口 +## What this project does -| Item | Description | -| --- | --- | -| Project type | plugin package | -| What it does | Sidecar strategy plugins for risk regime, crisis context and notification-only overlays used by QuantStrategyLab runtimes. | -| 中文说明 | 策略 sidecar 插件包，用于风险状态、危机上下文和通知/影子信号，不直接替代核心策略。 | -| Current status | Plugin package. Plugins should be mounted only when backtest evidence and runtime policy explicitly allow them. | +QuantStrategyPlugins is a **Plugin package** in the QuantStrategyLab ecosystem. It provides open sidecar strategy plugins that QuantStrategyLab runtimes can load without changing platform code. -### Quick start +## Who this is for -- `python -m pip install -e '.[test]'` -- `python -m pytest -q` +- Engineers and researchers who want to inspect, reproduce, or extend this part of the QuantStrategyLab stack. +- Operators who need a clear entry point before reading the deeper runbooks or workflow files. +- Reviewers who need to understand the repository purpose, safety boundary, and evidence requirements before enabling automation. -### Deploy / operate safely +## Current status -Publish through platform or snapshot plugin workflows; keep notification-only plugins out of execution paths unless explicitly accepted. +Extension package; plugin eligibility still depends on strategy validation. -### Strategy performance / evidence boundary +## Repository layout -See `docs/market-regime-control-plan.md` and `.zh-CN.md` for CAGR/drawdown impact and watch-only versus actionable signal policy. +- `src/`: main library and runtime code. +- `tests/`: unit and contract tests. +- `docs/`: detailed design notes, runbooks, and evidence docs. +- `.github/workflows/`: CI, scheduled jobs, and deployment workflows. +- `scripts/`: operator scripts and local helpers. -> Detailed runbooks, migration notes, workflow internals, and historical decisions are kept below. Start with this overview before using the lower-level operational sections. +## Quick start - - -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 - - -## 中文摘要 - -- 完整中文版见 [`README.zh-CN.md`](README.zh-CN.md)；本节保留在英文文件顶部，方便从当前文件直接找到中文入口。 -- 用途：本文档围绕 `QuantStrategyPlugins`，用于理解 `QuantStrategyPlugins` 的配置、运行、部署、研究或验收边界。 -- 主要覆盖：`What Is Public`、`What Stays Out`、`Plugins`、`Usage`、`Notification and Log i18n`。 -- 阅读顺序：先确认边界、输入输出和权限要求，再执行文档里的命令、CI、dry-run、发布或切换步骤。 -- 风险提示：涉及实盘、密钥、权限、Cloud Run、交易所或券商 API 的变更，必须先在测试环境或 dry-run 验证；不要只凭示例直接修改生产。 -- 英文正文保留更完整的命令、字段名和配置键；如果摘要和正文不一致，以正文中的实际命令和配置为准。 -Open sidecar strategy plugins for QuantStrategyLab runtimes. - -Documentation: English | [简体中文](README.zh-CN.md) - -The repository emits JSON signal artifacts that are consumed through -`quant_platform_kit.common.strategy_plugins`. Platform repositories such as -Interactive Brokers, Schwab, LongBridge, and Firstrade only load artifacts and -send notifications; plugin research and signal generation live here. - -## What Is Public - -- Plugin source code and synthetic tests. -- The artifact schema used by platform runtimes. -- Example local TOML config with placeholder paths. - -## What Stays Out - -- Broker credentials, tokens, account IDs, and SMTP settings. -- GCS bucket names, Cloud Run service names, and production deploy workflows. -- Generated `data/output` artifacts and proprietary runtime configuration. -- Non-public datasets. Tests use synthetic price histories. - -## Plugins - -- `crisis_response_shadow`: black-swan defense observer for leveraged US equity - strategies. It writes shadow-mode artifacts and never calls brokers. It can - optionally run AI shadow audit: the model audits evidence consistency and data - gaps only, never overrides the deterministic route, places orders, or changes - allocations. Local Codex is tried first when enabled; OpenAI-compatible and - Anthropic fallback endpoints can be configured. -- `macro_risk_governor`: deterministic macro de-leveraging governor for TQQQ. - It scores price trend, realized volatility, VIX, and credit-pair stress. The - artifact can expose - `leverage_scalar` and `risk_asset_scalar` to strategy runtimes that explicitly - opt in through mounted metadata. External hard-data fields such as HY OAS and - financial-stress indices, plus OSINT-style, sentiment, options-volatility, - rates, breadth, funding, and liquidity fields such as a Pentagon pizza index, - Fear & Greed, put/call, VVIX, SKEW, MOVE, yield curves, dollar stress, and - safe-haven demand, are kept as watch-only evidence by default. They do not - contribute to the actionable trading score unless explicitly enabled for - research. -- `market_regime_control`: unified deterministic facade for crisis, macro, and - TACO signals. Only strategies with positive backtest evidence should mount - position controls for automated consumption; SOXL/SOXX currently receives - broad macro/crisis signals through `notification_targets` only. Stock/ETF - rotation strategies should consume the same artifact through their local - risk-scaling policy and keep TACO as notification-only. See the - [Market Regime Control design plan](docs/market-regime-control-plan.md). -- `taco_rebound_shadow`: TQQQ-only event-rebound context notifier. It writes - manual-review artifacts and never recommends position size or changes - allocations. Softening/de-escalation events stay watch-only until post-event - price rebound confirmation passes, which reduces early bottom-fishing alerts. - It can optionally run the same shadow-only AI audit on event/source quality. -- TACO panic-rebound research and portfolio/overlay backtests also live here; - snapshot pipeline repositories keep only compatibility entrypoints. - -## Usage - -Run a plugin config: - -```bash -qsp-run-strategy-plugins --config docs/examples/strategy_plugins.example.toml -``` - -Build a crisis response artifact directly from a local price-history CSV: +From a fresh clone: ```bash -qsp-build-crisis-response-shadow-signal \ - --prices data/input/price_history.csv \ - --as-of 2026-05-22 \ - --ai-audit-enabled \ - --output-dir data/output/tqqq_growth_income/plugins/crisis_response_shadow +python -m pip install -e . +python -m pytest -q ``` -Build the public hard-data `external_context` CSV used by macro and unified -market-regime plugins: +If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git. -```bash -qsp-build-macro-external-context \ - --start 1999-01-01 \ - --output data/output/market_regime_control/input/external_context.csv -``` +## Deployment and operation -The builder downloads public FRED/CBOE fields when available: VIX, VIX3M, -VVIX, SKEW, Cboe put/call ratios, HY/IG OAS, financial-stress indices, yield -curves, trade-weighted dollar stress, and TED/funding stress. Fields without a -stable no-login historical feed, such as CNN Fear & Greed, AAII, NAAIM, -Pentagon pizza, MOVE, and breadth, can be supplied with `--manual-context`. -OAS coverage follows what the public FRED graph endpoint returns; archived -local OAS history can be injected with the same manual context path. +Install or package the plugins with the target runtime, then point the platform loader to the plugin entrypoint. Validate in dry-run before enabling live execution. -AI audit reads API settings from environment variables: +Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed. -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_CODEX_ENABLED`, default `true` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_CODEX_MODEL`, optional label for the local Codex provider -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_API_KEY`, falling back to `QSP_CRISIS_AI_AUDIT_API_KEY` / `OPENAI_API_KEY` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_BASE_URL`, falling back to `QSP_CRISIS_AI_AUDIT_BASE_URL` / `OPENAI_API_BASE_URL` / `OPENAI_BASE_URL` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_MODEL`, falling back to `QSP_CRISIS_AI_AUDIT_MODEL` / `OPENAI_MODEL` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_FALLBACK_API_KEY` / `QSP_STRATEGY_PLUGIN_AI_AUDIT_FALLBACK_BASE_URL` / `QSP_STRATEGY_PLUGIN_AI_AUDIT_FALLBACK_MODEL` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_API_KEY`, falling back to `QSP_CRISIS_AI_AUDIT_ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_MODEL` / `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_BASE_URL` / `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_VERSION` +## Strategy performance and evidence -If the runtime already injects `ANTHROPIC_API_KEY`, the strategy plugins can reuse it. Use `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_API_KEY` only when this audit path needs an explicit service-specific override. +Plugin code does not make a strategy live-ready by itself. Use the associated strategy research artifacts to evaluate returns, drawdowns, benchmark comparison, and robustness. -Build a TACO rebound notification artifact directly from a local price-history CSV: +README files are intentionally not a source of dated performance promises. Re-run the relevant tests, backtests, or pipeline jobs before relying on any result. -```bash -qsp-build-taco-rebound-shadow-signal \ - --prices data/input/price_history.csv \ - --event-set geopolitical-deescalation \ - --as-of 2026-05-22 \ - --ai-audit-enabled \ - --output-dir data/output/tqqq_growth_income/plugins/taco_rebound_shadow -``` +## Safety notes -Generated artifacts include `latest_signal.json`, dated JSON, dated CSV, and -an evidence CSV. `latest_signal.json` is the file platform runtimes mount via -`*_STRATEGY_PLUGIN_MOUNTS_JSON`. +- Never commit API keys, broker credentials, OAuth tokens, cookies, or account identifiers. +- Run new strategies and platform changes in dry-run or paper mode before any live execution. +- Review generated orders, artifacts, and logs manually before enabling schedules. -## Notification and Log i18n +## Contributing -Runner-managed artifacts add display-only i18n fields for notifications and -logs: - -- `localized_messages.schema_version = strategy_plugin_messages.v1` -- `localized_messages.notification.en-US` / `localized_messages.notification.zh-CN` -- `localized_messages.log.en-US` / `localized_messages.log.zh-CN` -- `log_record.schema_version = strategy_plugin_log.v1` -- `market_regime_control.notification.localized_message_schema_version` - -Strategy and broker runtimes should keep trading logic on machine fields such -as `schema_version`, `canonical_route`, `suggested_action`, `reason_codes`, and -`position_control`. Localized strings are for human notification surfaces and -logs only. `market_regime_control.notification` mirrors the localized -notification text and reason labels so existing notification code can render a -message without translating route/action codes itself. -General notification targets are configured under `notification_targets`, not as -synthetic strategies, and never receive position-control permission. - -## Local Checks - -```bash -python -m pip install -e '.[test]' -python -m pytest -q -ruff check . -``` +Keep changes small, reproducible, and covered by the narrowest useful tests. For strategy-facing changes, include the evidence artifact or command used to validate behavior. ## License -MIT License. Copyright (c) 2026 QuantStrategyLab. +See [LICENSE](LICENSE) if present in this repository. diff --git a/README.zh-CN.md b/README.zh-CN.md index 4f26eba..61819ed 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,131 +1,64 @@ # QuantStrategyPlugins -> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 - - -## English summary - -- Full English version: [`README.md`](README.md). This summary keeps an English entry point in the Chinese file. -- Purpose: this document covers `QuantStrategyPlugins` for `QuantStrategyPlugins`. -- Main topics: `开源范围`, `不进入开源仓库的内容`, `插件`, `使用方式`, `通知和日志 i18n`. -- Read the boundaries, inputs, outputs, and permission requirements before running commands, CI jobs, dry-runs, releases, or runtime switches. -- For live trading, secrets, Cloud Run, exchange, or broker API changes, validate in test or dry-run mode first and do not change production only from examples. -- If this summary differs from the detailed Chinese body, follow the concrete commands, configuration keys, and constraints in the body. - -QuantStrategyLab 的开源侧车策略插件仓库。 - -文档：[English](README.md) | 简体中文 +[English README](README.md) -本仓库生成 JSON 信号 artifact，平台运行时通过 -`quant_platform_kit.common.strategy_plugins` 读取这些 artifact。Interactive -Brokers、Schwab、LongBridge、Firstrade 等平台仓库只负责加载 artifact、发送通知和执行平台侧逻辑；插件研究、信号生成和证据输出放在这个仓库。 +> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。 -## 开源范围 +## 这个项目做什么 -- 插件源码和使用合成数据的测试。 -- 平台运行时读取的 artifact schema。 -- 带占位路径的本地 TOML 示例配置。 +QuantStrategyPlugins 是 QuantStrategyLab 体系中的**插件包**。提供 QuantStrategyLab 运行时可加载的开放 sidecar 策略插件，避免频繁修改平台代码。 -## 不进入开源仓库的内容 +## 适合谁使用 -- 券商凭据、token、账号 ID、SMTP 设置。 -- GCS bucket 名称、Cloud Run 服务名、生产部署 workflow。 -- 生成的 `data/output` artifact 和私有 runtime 配置。 -- 非公开数据集。测试只使用合成价格历史。 +- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。 +- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。 +- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。 -## 插件 +## 当前状态 -- `crisis_response_shadow`：面向杠杆美股策略的黑天鹅防守观察插件。它只写入 shadow-mode artifact，不调用券商接口。 - 可选启用 AI shadow audit：AI 只审计证据一致性和数据缺口，不改写确定性路线、不下单、不改仓位；默认优先尝试本机 Codex，失败后可走 OpenAI-compatible 或 Anthropic fallback endpoint。 -- `macro_risk_governor`：面向 TQQQ 的确定性宏观降杠杆插件。它按价格趋势、实现波动、VIX 和信用 ETF 相对压力打分，输出 `leverage_scalar` / `risk_asset_scalar` 给显式 opt-in 的策略运行时消费。HY OAS、金融压力指数、五角大楼比萨指数、Fear & Greed、put/call、VVIX、SKEW、MOVE、收益率曲线、美元压力、safe-haven demand 等外部硬数据、OSINT、情绪或跨资产字段默认只作为 watch-only 证据，不进入可执行分数；只有显式研究开关开启后才允许外部压力字段参与自动分数。 -- `market_regime_control`：统一确定性 facade，汇总 crisis、macro 和 TACO 信号，输出版本化的 `notification` 和 `position_control`。只有经过回测证明自动消费有效的策略才挂载仓位控制；SOXL/SOXX 这类未通过统一宏观插件复核的高波动行业杠杆策略只通过 `notification_targets` 接收通用通知，人工决定是否干预。股票/ETF 轮动策略通过本地风险缩放策略消费；TACO 在统一插件里保持通知-only，并会被危机和宏观降风险路线 veto。设计说明见 [Market Regime Control 统一插件方案](docs/market-regime-control-plan.zh-CN.md)。 -- `taco_rebound_shadow`：仅适用于 TQQQ 的事件反弹上下文通知插件。它只写入人工复核 artifact，不给仓位大小建议，也不改动配置或账户分配。缓和/降温事件会先保持 watch-only，只有事件后价格反弹确认通过后才触发人工复核通知，以减少过早抄底提醒。 - 该插件也可选启用同样的 shadow-only AI audit，但 AI 只复核事件来源和反弹证据质量。 -- TACO panic-rebound 研究、组合回测和 overlay 对比也归属本仓库；snapshot pipeline 仓库只保留兼容入口。 +扩展包；插件是否可 live 仍取决于策略验证结果。 -## 使用方式 +## 仓库结构 -运行插件 TOML 配置： +- `src/`：主要库代码和运行时代码。 +- `tests/`：单元测试和契约测试。 +- `docs/`：详细设计说明、运行手册和证据文档。 +- `.github/workflows/`：CI、定时任务和部署 workflow。 +- `scripts/`：运维脚本和本地辅助工具。 -```bash -qsp-run-strategy-plugins --config docs/examples/strategy_plugins.example.toml -``` +## 快速开始 -从本地价格历史 CSV 直接生成 crisis response artifact： +从全新 clone 开始： ```bash -qsp-build-crisis-response-shadow-signal \ - --prices data/input/price_history.csv \ - --as-of 2026-05-22 \ - --ai-audit-enabled \ - --output-dir data/output/tqqq_growth_income/plugins/crisis_response_shadow -``` - -生成宏观和统一市场状态插件使用的公开硬数据 `external_context` CSV： - -```bash -qsp-build-macro-external-context \ - --start 1999-01-01 \ - --output data/output/market_regime_control/input/external_context.csv +python -m pip install -e . +python -m pytest -q ``` -构建器会尽量下载公开 FRED/CBOE 字段：VIX、VIX3M、VVIX、SKEW、Cboe -put/call、HY/IG OAS、金融压力指数、收益率曲线、贸易加权美元压力和 -TED/funding stress。CNN Fear & Greed、AAII、NAAIM、五角大楼比萨指数、 -MOVE、市场宽度等没有稳定免登录历史源的字段，可以通过 `--manual-context` -提供。OAS 覆盖范围以 FRED 公开 graph endpoint 实际返回为准；如果需要更早的 -本地归档 OAS 历史，也通过同一个 manual context 注入。 - -AI audit 使用环境变量读取 API 配置： - -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_CODEX_ENABLED`，默认 `true` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_CODEX_MODEL`，本机 Codex provider 的可选标签 -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_API_KEY`，或 fallback 到 `QSP_CRISIS_AI_AUDIT_API_KEY` / `OPENAI_API_KEY` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_BASE_URL`，或 fallback 到 `QSP_CRISIS_AI_AUDIT_BASE_URL` / `OPENAI_API_BASE_URL` / `OPENAI_BASE_URL` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_MODEL`，或 fallback 到 `QSP_CRISIS_AI_AUDIT_MODEL` / `OPENAI_MODEL` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_FALLBACK_API_KEY` / `QSP_STRATEGY_PLUGIN_AI_AUDIT_FALLBACK_BASE_URL` / `QSP_STRATEGY_PLUGIN_AI_AUDIT_FALLBACK_MODEL` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_API_KEY`，或 fallback 到 `QSP_CRISIS_AI_AUDIT_ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY` -- `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_MODEL` / `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_BASE_URL` / `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_VERSION` +如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。 -如果运行环境已经统一注入 `ANTHROPIC_API_KEY`，不需要为策略插件重新申请 key；只有当希望把策略插件和其他 audit 服务隔离时，才使用 `QSP_STRATEGY_PLUGIN_AI_AUDIT_ANTHROPIC_API_KEY` 覆盖。 +## 部署和运行 -从本地价格历史 CSV 直接生成 TACO 反弹通知 artifact： +将插件安装或打包到目标运行时，并让平台加载器指向插件入口。启用 live 前必须先 dry-run 验证。 -```bash -qsp-build-taco-rebound-shadow-signal \ - --prices data/input/price_history.csv \ - --event-set geopolitical-deescalation \ - --as-of 2026-05-22 \ - --ai-audit-enabled \ - --output-dir data/output/tqqq_growth_income/plugins/taco_rebound_shadow -``` +建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。 -输出包括 `latest_signal.json`、按日期归档的 JSON、按日期归档的 CSV，以及 evidence CSV。平台运行时通过 `*_STRATEGY_PLUGIN_MOUNTS_JSON` 挂载的就是 `latest_signal.json`。 +## 策略表现与证据边界 -## 通知和日志 i18n +插件代码本身不能证明策略适合 live。收益、回撤、基准比较和稳健性应以对应策略研究产物为准。 -通过 strategy plugin runner 生成的 artifact 会附带展示层 i18n 字段： +README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。 -- `localized_messages.schema_version = strategy_plugin_messages.v1` -- `localized_messages.notification.en-US` / `localized_messages.notification.zh-CN` -- `localized_messages.log.en-US` / `localized_messages.log.zh-CN` -- `log_record.schema_version = strategy_plugin_log.v1` -- `market_regime_control.notification.localized_message_schema_version` +## 安全注意事项 -策略和券商运行时的交易逻辑仍应只读取 `schema_version`、`canonical_route`、 -`suggested_action`、`reason_codes` 和 `position_control` 等机器字段。中英文文案只用于通知界面和日志展示，不参与策略判断。`market_regime_control.notification` -会同步包含本地化通知文案和原因标签，方便现有通知代码直接渲染，不需要在策略仓库里重复翻译 route/action code。 -通用通知目标通过 `notification_targets` 配置，不再伪装成 synthetic strategy， -并且永远不会获得仓位控制权限。 +- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。 +- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。 +- 启用定时任务前，需要人工检查生成的订单、产物和日志。 -## 本地检查 +## 参与贡献 -```bash -python -m pip install -e '.[test]' -python -m pytest -q -ruff check . -``` +请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。 ## 许可证 -MIT License. Copyright (c) 2026 QuantStrategyLab. +如仓库包含 [LICENSE](LICENSE)，请以该文件为准。