Skip to content

Commit c0765c2

Browse files
PigbibiPigbibi
committed
Add bilingual README and MIT license
1 parent ea95ba1 commit c0765c2

4 files changed

Lines changed: 206 additions & 0 deletions

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 QuantStrategyLab
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# AiLongHorizonSignalPipelines
22

3+
[English](README.md) | [简体中文](README.zh-CN.md)
4+
35
Research-only long-horizon AI signal artifact repository for QuantStrategyLab.
46

57
This repository does not place trades, store broker credentials, or own live
@@ -200,3 +202,7 @@ conservative:
200202
- `mixed`: reduce exposure to `0.8`
201203
- severe risk flags such as `liquidity_stress` cap exposure at `0.6`
202204
- the overlay never increases exposure above the baseline
205+
206+
## License
207+
208+
This repository is licensed under the MIT License. See [LICENSE](LICENSE).

‎README.zh-CN.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# AiLongHorizonSignalPipelines
2+
3+
[English](README.md) | [简体中文](README.zh-CN.md)
4+
5+
QuantStrategyLab 的研究型长周期 AI shadow signal artifact 仓库。
6+
7+
本仓库不下单、不保存券商凭证，也不拥有实盘仓位策略。它只负责准备、校验、保存和回放长周期 AI shadow signal。任何未来的下游使用，都必须经过单独评审，并由确定性插件或策略显式消费。
8+
9+
## 仓库定位
10+
11+
这是一个 research artifact repository，不是 agent runner、模型网关、执行服务或策略插件仓。
12+
13+
本仓库的职责是让点时研究证据可复现：
14+
15+
- 构建当前市场 context bundle
16+
- 创建带日期的 GitHub Issue 供 operator 审阅
17+
- 保存 schema-valid 的 shadow AI signal artifacts
18+
- 保存 `signal_history` 供未来 walk-forward replay
19+
- 围绕已保存 artifacts 提供确定性 replay 工具
20+
21+
`CodexAuditBridge` 仍然是唯一的模型 provider bridge/runner，负责模型 API、跨仓写权限和 PR/Issue 自动化。未来如果要接入实盘或通知系统，应在积累足够 shadow evidence 后，另建确定性插件 contract。
22+
23+
## 边界
24+
25+
本仓库负责：
26+
27+
- 长周期 AI context bundle 示例和生成工具
28+
- shadow signal JSON schema 约束
29+
- `latest_signal.json` 校验工具
30+
- 向 `QuantStrategyLab/CodexAuditBridge` 交接 issue/workflow
31+
- 可 replay 的 artifact 记录
32+
33+
本仓库不负责：
34+
35+
- 券商 API 访问
36+
- 下单
37+
- 实盘组合配置
38+
- `UsEquityStrategies` 中的确定性策略规则
39+
- `QuantStrategyPlugins` 中的运行时插件执行
40+
- 模型 provider API keys
41+
- Codex/OpenAI/Anthropic provider routing
42+
- source repo 写权限的 GitHub App token minting
43+
- Telegram 或券商侧运行时通知
44+
45+
## 当前状态
46+
47+
本仓库处于 shadow research accumulation mode。第一条已保存的点时 artifact 是：
48+
49+
```text
50+
data/output/signal_history/2026-05-28.json
51+
```
52+
53+
近期工作重点：
54+
55+
- 保持月度 workflow 健康
56+
- 持续积累 `signal_history/*.json`
57+
- 只 replay 已保存 artifacts，不让模型重新生成历史判断
58+
- 在任何下游插件集成前，先提升 context 质量并积累证据
59+
60+
在 `signal_history` 积累出足够 walk-forward evidence 之前，不应把输出接入运行时仓位或通知系统。
61+
62+
## 运行模式
63+
64+
1. 月度 workflow 根据当前市场价格构建 point-in-time context bundle。
65+
2. workflow 创建或更新带日期的 long-horizon shadow-signal issue，并把 context bundle 嵌入 issue 作为审阅证据。
66+
3. issue 被 dispatch 到 `QuantStrategyLab/CodexAuditBridge`，任务类型是 `long_horizon_signal_shadow`。
67+
4. `CodexAuditBridge` 优先运行 self-hosted Codex；只有在配置允许时才使用 OpenAI 或 Anthropic API fallback。
68+
5. 所有 AI 生成的 artifact 必须保持 `mode=shadow`，并通过本地 schema validation。
69+
6. 下游系统在单独的确定性 policy engine 显式消费前，只能把 artifact 当作 advisory context。
70+
71+
## GitHub 配置
72+
73+
模型 API key 集中在 `CodexAuditBridge`；不要把 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY` 放到本仓库。
74+
75+
本仓库只需要 bridge workflow dispatch 凭证：
76+
77+
- 推荐：`CROSS_REPO_GITHUB_APP_ID` variable 和 `CROSS_REPO_GITHUB_APP_PRIVATE_KEY` secret，且该 GitHub App 对 `CodexAuditBridge` 有 Actions write 权限
78+
- fallback：`CODEX_AUDIT_DISPATCH_TOKEN` secret，具备 dispatch bridge workflow 的权限
79+
80+
已配置的非 secret variables：
81+
82+
- `SELFHOSTED_CODEX_REVIEW_REPOSITORY=QuantStrategyLab/CodexAuditBridge`
83+
- `SELFHOSTED_CODEX_REVIEW_PROVIDER=auto`
84+
- `CROSS_REPO_GITHUB_APP_ID=3250578`
85+
86+
## 通知策略
87+
88+
`.github/workflows/dispatch_shadow_signal.yml` 创建的 GitHub Issue 是当前 operator notification channel。Issue 使用 `long-horizon-shadow` label，按日期去重，并接收 `CodexAuditBridge` 的审计回帖或 artifact PR。
89+
90+
当前阶段不要添加 Telegram、券商或 runtime plugin 通知。这些应在 shadow signal 晋级为确定性插件 contract 后，由下游系统负责。
91+
92+
## 本地验证
93+
94+
校验示例 artifact：
95+
96+
```bash
97+
python scripts/validate_latest_signal.py examples/latest_signal.example.json
98+
```
99+
100+
从本地价格文件构建 context bundle：
101+
102+
```bash
103+
python scripts/build_context_bundle.py \
104+
--prices examples/price_history.example.csv \
105+
--symbols QQQ \
106+
--output data/output/context_bundle/latest_context_bundle.json
107+
```
108+
109+
不传 `--prices` 时，脚本会通过 Yahoo chart endpoint 下载默认 universe 的近期日线价格，并写出月度 shadow issue 使用的 point-in-time context bundle。定时 workflow 使用 `--allow-download-errors`，所以外部数据源失败时仍会创建 operator issue，并把失败原因写入 context。
110+
111+
校验已 promoted 的 latest artifact：
112+
113+
```bash
114+
python scripts/validate_latest_signal.py
115+
```
116+
117+
运行合成 overlay replay：
118+
119+
```bash
120+
python scripts/backtest_signal_overlay.py \
121+
--prices examples/price_history.example.csv \
122+
--signals examples/signal_history \
123+
--symbol QQQ
124+
```
125+
126+
这个 replay 只测试确定性的 risk-reducing overlay。它不调用 AI model，也不把示例结果当作生产证据。
127+
128+
从现有 QuantStrategyLab 价格文件抽取紧凑 replay 输入：
129+
130+
```bash
131+
python scripts/extract_price_history.py \
132+
--source ../UsEquitySnapshotPipelines/data/output/tqqq_growth_income_real_full_archive_2026-05-26/price_history.csv \
133+
--target data/input/qqq_price_history.csv \
134+
--symbols QQQ
135+
```
136+
137+
然后用已保存的 shadow signals replay：
138+
139+
```bash
140+
python scripts/backtest_signal_overlay.py \
141+
--prices data/input/qqq_price_history.csv \
142+
--signals data/output/signal_history \
143+
--symbol QQQ \
144+
--output data/output/tmp/replay_summary.json
145+
```
146+
147+
price loader 同时支持本仓库的紧凑 `date,symbol,close` schema，以及现有 QuantStrategyLab 的 `symbol,as_of,close` schema。
148+
149+
## Artifact Contract
150+
151+
latest artifact 路径：
152+
153+
```text
154+
data/output/latest_signal.json
155+
```
156+
157+
历史副本路径：
158+
159+
```text
160+
data/output/signal_history/YYYY-MM-DD.json
161+
```
162+
163+
所有 artifacts 必须保持 shadow-only。它们不能编码券商订单、目标数量或实盘 allocation override。
164+
165+
## Replay Contract
166+
167+
历史验证必须 replay 已保存 signal artifacts，而不是让模型重新生成过去的判断。当前示例 policy 有意保持保守：
168+
169+
- 没有 active signal：保持 baseline exposure
170+
- `confidence < 0.55`：no-op
171+
- `risk_off`：降到 `0.5`
172+
- `mixed`：降到 `0.8`
173+
- 严重 risk flags，例如 `liquidity_stress`，把 exposure cap 到 `0.6`
174+
- overlay 永远不能把 exposure 提高到 baseline 以上
175+
176+
## 许可证
177+
178+
本仓库使用 MIT License。详见 [LICENSE](LICENSE)。

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ version = "0.1.0"
88
description = "Shadow-only long-horizon AI signal artifacts for QuantStrategyLab research."
99
requires-python = ">=3.11"
1010
dependencies = []
11+
license = { text = "MIT" }
1112

1213
[project.optional-dependencies]
1314
test = ["pytest>=8"]

0 commit comments

Comments
 (0)