alphaspec 0.3.0__tar.gz → 0.4.0__tar.gz

{alphaspec-0.3.0 → alphaspec-0.4.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.0 — 2026-10-12
+
+- Contract 0.4 (`schema/0.4/`): factor-ranked strategies (`signalMode`, `factorBindings` with `factor` /
+  `direction` / `weight`, new `ranking` block; `dsl` optional for `FACTOR_ONLY`), short rules
+  (`dsl.shortEntry` / `dsl.shortExit`).
+- Lint rules AS019 (short rules on a market that cannot be shorted), AS020 (short entry without a short
+  exit), AS021 (factor bound twice), AS022 (topN covers the whole symbol list).
+- MARKETS.md: trading rules by market (lots, settlement, price limits, short selling).
+- SPEC §4b–4d: factor strategies, short rules, score series.
+- Client / CLI / MCP: `factors`, `submit-scores`, `scores`, `evidence`.
+- RUNTIME_API: factor evaluation window (2 + 1 years), score series, evidence, new `RUNTIME_*` codes.
+- Examples 07 (quality + value, monthly) and 08 (long/short futures).
+- `alphaspec validate` reads files holding a JSON array or JSON lines; `submit_scores` waits up to 300 s.
+- Reference runtime: factor backtests now report in-sample / out-of-sample segments, accept an explicit
+  symbol list and record which artifact they evaluated (all three were missing); factor + rule strategies
+  gate on rank only; score uploads write in bulk (30k rows in seconds instead of minutes); evidence judges
+  intraday strategies by their last evaluated bar.
+
 ## 0.3.0 — 2026-10-12
 
 - Contract 0.3 (`schema/0.3/`): new `capabilities` document kind; `gate-result.tradeSettings` reports the exits,

{alphaspec-0.3.0 → alphaspec-0.4.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: alphaspec
-Version: 0.3.0
+Version: 0.4.0
 Summary: The auditable contract between alpha and execution: JSON schemas, a validator and lint rules for declarative trading strategies.
 Project-URL: Homepage, https://github.com/openalpha-dev/alphaspec
 Project-URL: Documentation, https://github.com/openalpha-dev/alphaspec#readme
 Project-URL: Changelog, https://github.com/openalpha-dev/alphaspec/blob/main/CHANGELOG.md
-Project-URL: Schemas, https://openalpha-dev.github.io/alphaspec/schema/0.3/
+Project-URL: Schemas, https://openalpha-dev.github.io/alphaspec/schema/0.4/
 Author: OpenAlpha contributors
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -80,15 +80,15 @@ Two ways in, written by you or your agent:
 
 | Level | Document | For | You send |
 |---|---|---|---|
-| **L1 · Score** | [`score`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/score.schema.json) | ML teams, factor researchers | `(asOf, market, symbol, score)` or target weights |
-| **L2 · Artifact** | [`artifact`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/artifact.schema.json) | rule-based strategies, AI agents | a rule tree with parameters, universe and risk overrides |
+| **L1 · Score** | [`score`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/score.schema.json) | ML teams, factor researchers | `(asOf, market, symbol, score)` or target weights |
+| **L2 · Artifact** | [`artifact`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/artifact.schema.json) | rule-based strategies, AI agents | a rule tree with parameters, universe and risk overrides |
 
 Two ways back, written by the runtime and never by the submitter:
 
 | Document | What it answers |
 |---|---|
-| [`gate-result`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/gate-result.schema.json) | Did it pass, judged on figures the runtime **recomputed itself**, check by check |
-| [`evidence`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/evidence.schema.json) | What happened in a real market: rejections, slippage, fills, deviation from target, every number with its caliber |
+| [`gate-result`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/gate-result.schema.json) | Did it pass, judged on figures the runtime **recomputed itself**, check by check |
+| [`evidence`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/evidence.schema.json) | What happened in a real market: rejections, slippage, fills, deviation from target, every number with its caliber |
 
 The way back is the point. Research tools see prices, news and filings; none of that says whether
 an order was rejected, how much slippage it paid, or how far the portfolio drifted from its target.
@@ -110,7 +110,7 @@ A short artifact:
 
 ```json
 {
-  "contractVersion": "0.2",
+  "contractVersion": "0.4",
   "kind": "artifact",
   "title": "RSI rebound above the 60-day average",
   "market": "cn_stock",
@@ -319,7 +319,7 @@ Every document carries `contractVersion`, so a runtime can refuse what it does n
 Versions are additive and each keeps its own schema directory: a document is validated
 against the version it declares. 0.2 adds trade settings (`exits`, `sizing`, `execution`);
 see [docs/ROADMAP.md](https://github.com/openalpha-dev/alphaspec/blob/main/docs/ROADMAP.md). Schemas are published at their `$id` URLs, e.g.
-`https://openalpha-dev.github.io/alphaspec/schema/0.2/artifact.schema.json`.
+`https://openalpha-dev.github.io/alphaspec/schema/0.4/artifact.schema.json`.
 
 ## License
 

{alphaspec-0.3.0 → alphaspec-0.4.0}/README.md

@@ -53,15 +53,15 @@ Two ways in, written by you or your agent:
 
 | Level | Document | For | You send |
 |---|---|---|---|
-| **L1 · Score** | [`score`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/score.schema.json) | ML teams, factor researchers | `(asOf, market, symbol, score)` or target weights |
-| **L2 · Artifact** | [`artifact`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/artifact.schema.json) | rule-based strategies, AI agents | a rule tree with parameters, universe and risk overrides |
+| **L1 · Score** | [`score`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/score.schema.json) | ML teams, factor researchers | `(asOf, market, symbol, score)` or target weights |
+| **L2 · Artifact** | [`artifact`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/artifact.schema.json) | rule-based strategies, AI agents | a rule tree with parameters, universe and risk overrides |
 
 Two ways back, written by the runtime and never by the submitter:
 
 | Document | What it answers |
 |---|---|
-| [`gate-result`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/gate-result.schema.json) | Did it pass, judged on figures the runtime **recomputed itself**, check by check |
-| [`evidence`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/evidence.schema.json) | What happened in a real market: rejections, slippage, fills, deviation from target, every number with its caliber |
+| [`gate-result`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/gate-result.schema.json) | Did it pass, judged on figures the runtime **recomputed itself**, check by check |
+| [`evidence`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/evidence.schema.json) | What happened in a real market: rejections, slippage, fills, deviation from target, every number with its caliber |
 
 The way back is the point. Research tools see prices, news and filings; none of that says whether
 an order was rejected, how much slippage it paid, or how far the portfolio drifted from its target.
@@ -83,7 +83,7 @@ A short artifact:
 
 ```json
 {
-  "contractVersion": "0.2",
+  "contractVersion": "0.4",
   "kind": "artifact",
   "title": "RSI rebound above the 60-day average",
   "market": "cn_stock",
@@ -292,7 +292,7 @@ Every document carries `contractVersion`, so a runtime can refuse what it does n
 Versions are additive and each keeps its own schema directory: a document is validated
 against the version it declares. 0.2 adds trade settings (`exits`, `sizing`, `execution`);
 see [docs/ROADMAP.md](https://github.com/openalpha-dev/alphaspec/blob/main/docs/ROADMAP.md). Schemas are published at their `$id` URLs, e.g.
-`https://openalpha-dev.github.io/alphaspec/schema/0.2/artifact.schema.json`.
+`https://openalpha-dev.github.io/alphaspec/schema/0.4/artifact.schema.json`.
 
 ## License
 

{alphaspec-0.3.0 → alphaspec-0.4.0}/README.zh-CN.md

@@ -48,15 +48,15 @@ AlphaSpec 守的是那道边界：**跨进执行层的东西，必须是一份
 
 | 档位 | 文档 | 适合谁 | 提交什么 |
 |---|---|---|---|
-| **L1 · Score** | [`score`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/score.schema.json) | 机构 ML 团队、因子研究员 | `(asOf, market, symbol, score)`，或者直接给目标权重 |
-| **L2 · Artifact** | [`artifact`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/artifact.schema.json) | 规则策略、AI agent | 一棵完整的规则树，加上参数、标的范围和风控设置 |
+| **L1 · Score** | [`score`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/score.schema.json) | 机构 ML 团队、因子研究员 | `(asOf, market, symbol, score)`，或者直接给目标权重 |
+| **L2 · Artifact** | [`artifact`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/artifact.schema.json) | 规则策略、AI agent | 一棵完整的规则树，加上参数、标的范围和风控设置 |
 
 两种回执，只由执行系统生成，提交方不能自己填：
 
 | 文档 | 回答什么问题 |
 |---|---|
-| [`gate-result`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/gate-result.schema.json) | 门禁过没过。绩效由执行系统**自己重算**，逐项列出判据 |
-| [`evidence`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.2/evidence.schema.json) | 在真实市场里发生了什么：拒单、滑点、成交、与目标持仓的偏差，每个数字都注明口径 |
+| [`gate-result`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/gate-result.schema.json) | 门禁过没过。绩效由执行系统**自己重算**，逐项列出判据 |
+| [`evidence`](https://github.com/openalpha-dev/alphaspec/blob/main/schema/0.4/evidence.schema.json) | 在真实市场里发生了什么：拒单、滑点、成交、与目标持仓的偏差，每个数字都注明口径 |
 
 回执才是重点。研究端看得到行情、新闻和研报，却看不到一笔委托有没有被拒、付了多少滑点、
 组合离目标持仓偏了多远——这些只有执行系统知道，而且只有当它用研究端读得懂的格式说出来，才算数。
@@ -77,7 +77,7 @@ flowchart LR
 
 ```json
 {
-  "contractVersion": "0.2",
+  "contractVersion": "0.4",
   "kind": "artifact",
   "title": "RSI 超卖反弹 + 站上 60 日线",
   "market": "cn_stock",
@@ -266,7 +266,7 @@ docs/                字段语义、检查规则、市场、运行时接口
 文档按自己声明的版本校验。0.2 加入交易设置（`exits` 止盈止损、`sizing` 仓位、`execution` 成交时点），
 路线图见 [docs/ROADMAP.md](https://github.com/openalpha-dev/alphaspec/blob/main/docs/ROADMAP.md)。
 Schema 发布在各自的 `$id` 地址，例如
-`https://openalpha-dev.github.io/alphaspec/schema/0.2/artifact.schema.json`。
+`https://openalpha-dev.github.io/alphaspec/schema/0.4/artifact.schema.json`。
 
 ## 许可证
 

alphaspec-0.4.0/conformance/cases/as019-short-on-stock.json

@@ -0,0 +1,77 @@
+{
+  "description": "A-shares cannot be sold short.",
+  "document": {
+    "contractVersion": "0.4",
+    "kind": "artifact",
+    "title": "EMA 20/60 crossover",
+    "note": "The smallest useful artifact: two indicators, one entry, one exit, a fixed symbol list.",
+    "market": "cn_stock",
+    "timeframe": "1d",
+    "dsl": {
+      "version": 1,
+      "indicators": {
+        "fast": {
+          "type": "EMA",
+          "period": 20
+        },
+        "slow": {
+          "type": "EMA",
+          "period": 60
+        }
+      },
+      "entry": {
+        "type": "CROSS_UP",
+        "left": {
+          "ind": "fast"
+        },
+        "right": {
+          "ind": "slow"
+        }
+      },
+      "exit": {
+        "type": "CROSS_DOWN",
+        "left": {
+          "ind": "fast"
+        },
+        "right": {
+          "ind": "slow"
+        }
+      },
+      "shortEntry": {
+        "type": "CROSS_DOWN",
+        "left": {
+          "ind": "fast"
+        },
+        "right": {
+          "ind": "slow"
+        }
+      },
+      "shortExit": {
+        "type": "CROSS_UP",
+        "left": {
+          "ind": "fast"
+        },
+        "right": {
+          "ind": "slow"
+        }
+      }
+    },
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "600519.SH"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": false,
+    "errors": [
+      "AS019"
+    ],
+    "warnings": []
+  }
+}

alphaspec-0.4.0/conformance/cases/as020-short-without-exit.json

@@ -0,0 +1,68 @@
+{
+  "description": "Short entry and no way to cover.",
+  "document": {
+    "contractVersion": "0.4",
+    "kind": "artifact",
+    "title": "EMA 20/60 crossover",
+    "note": "The smallest useful artifact: two indicators, one entry, one exit, a fixed symbol list.",
+    "market": "cn_future",
+    "timeframe": "1d",
+    "dsl": {
+      "version": 1,
+      "indicators": {
+        "fast": {
+          "type": "EMA",
+          "period": 20
+        },
+        "slow": {
+          "type": "EMA",
+          "period": 60
+        }
+      },
+      "entry": {
+        "type": "CROSS_UP",
+        "left": {
+          "ind": "fast"
+        },
+        "right": {
+          "ind": "slow"
+        }
+      },
+      "exit": {
+        "type": "CROSS_DOWN",
+        "left": {
+          "ind": "fast"
+        },
+        "right": {
+          "ind": "slow"
+        }
+      },
+      "shortEntry": {
+        "type": "CROSS_DOWN",
+        "left": {
+          "ind": "fast"
+        },
+        "right": {
+          "ind": "slow"
+        }
+      }
+    },
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "RB2701.SHF"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": true,
+    "errors": [],
+    "warnings": [
+      "AS020"
+    ]
+  }
+}

alphaspec-0.4.0/conformance/cases/as021-duplicate-factor.json

@@ -0,0 +1,48 @@
+{
+  "description": "The same factor twice doubles its weight.",
+  "document": {
+    "contractVersion": "0.4",
+    "kind": "artifact",
+    "title": "momentum top 3",
+    "market": "cn_stock",
+    "timeframe": "1d",
+    "signalMode": "FACTOR_ONLY",
+    "factorBindings": [
+      {
+        "factor": "MOMENTUM_20",
+        "direction": "DESC"
+      },
+      {
+        "factor": "MOMENTUM_20",
+        "direction": "DESC",
+        "weight": 2
+      }
+    ],
+    "ranking": {
+      "topN": 3,
+      "rebalance": "WEEKLY"
+    },
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "600519.SH",
+        "000858.SZ",
+        "300750.SZ",
+        "601318.SH",
+        "600036.SH",
+        "000333.SZ"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": true,
+    "errors": [],
+    "warnings": [
+      "AS021"
+    ]
+  }
+}

alphaspec-0.4.0/conformance/cases/as022-topn-covers-all.json

@@ -0,0 +1,42 @@
+{
+  "description": "Top 6 of 6 symbols ranks nothing.",
+  "document": {
+    "contractVersion": "0.4",
+    "kind": "artifact",
+    "title": "momentum top 3",
+    "market": "cn_stock",
+    "timeframe": "1d",
+    "signalMode": "FACTOR_ONLY",
+    "factorBindings": [
+      {
+        "factor": "MOMENTUM_20",
+        "direction": "DESC"
+      }
+    ],
+    "ranking": {
+      "topN": 6
+    },
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "600519.SH",
+        "000858.SZ",
+        "300750.SZ",
+        "601318.SH",
+        "600036.SH",
+        "000333.SZ"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": true,
+    "errors": [],
+    "warnings": [
+      "AS022"
+    ]
+  }
+}

alphaspec-0.4.0/conformance/cases/schema-binding-topn-in-0.4.json

@@ -0,0 +1,44 @@
+{
+  "description": "Per-binding topN was replaced by ranking.topN in 0.4.",
+  "document": {
+    "contractVersion": "0.4",
+    "kind": "artifact",
+    "title": "momentum top 3",
+    "market": "cn_stock",
+    "timeframe": "1d",
+    "signalMode": "FACTOR_ONLY",
+    "factorBindings": [
+      {
+        "factor": "MOMENTUM_20",
+        "direction": "DESC",
+        "topN": 3
+      }
+    ],
+    "ranking": {
+      "topN": 3,
+      "rebalance": "WEEKLY"
+    },
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "600519.SH",
+        "000858.SZ",
+        "300750.SZ",
+        "601318.SH",
+        "600036.SH",
+        "000333.SZ"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": false,
+    "errors": [
+      "SCHEMA"
+    ],
+    "warnings": []
+  }
+}

alphaspec-0.4.0/conformance/cases/schema-factor-only-without-ranking.json

@@ -0,0 +1,39 @@
+{
+  "description": "FACTOR_ONLY must say how many to hold and how often to rebalance.",
+  "document": {
+    "contractVersion": "0.4",
+    "kind": "artifact",
+    "title": "momentum top 3",
+    "market": "cn_stock",
+    "timeframe": "1d",
+    "signalMode": "FACTOR_ONLY",
+    "factorBindings": [
+      {
+        "factor": "MOMENTUM_20",
+        "direction": "DESC"
+      }
+    ],
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "600519.SH",
+        "000858.SZ",
+        "300750.SZ",
+        "601318.SH",
+        "600036.SH",
+        "000333.SZ"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": false,
+    "errors": [
+      "SCHEMA"
+    ],
+    "warnings": []
+  }
+}

alphaspec-0.4.0/conformance/cases/schema-ranking-in-0.3.json

@@ -0,0 +1,43 @@
+{
+  "description": "ranking does not exist in contract 0.3.",
+  "document": {
+    "contractVersion": "0.3",
+    "kind": "artifact",
+    "title": "momentum top 3",
+    "market": "cn_stock",
+    "timeframe": "1d",
+    "signalMode": "FACTOR_ONLY",
+    "factorBindings": [
+      {
+        "factor": "MOMENTUM_20",
+        "direction": "DESC"
+      }
+    ],
+    "ranking": {
+      "topN": 3,
+      "rebalance": "WEEKLY"
+    },
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "600519.SH",
+        "000858.SZ",
+        "300750.SZ",
+        "601318.SH",
+        "600036.SH",
+        "000333.SZ"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": false,
+    "errors": [
+      "SCHEMA"
+    ],
+    "warnings": []
+  }
+}

alphaspec-0.4.0/conformance/cases/schema-rule-only-without-dsl.json

@@ -0,0 +1,43 @@
+{
+  "description": "RULE_ONLY without a rule tree.",
+  "document": {
+    "contractVersion": "0.4",
+    "kind": "artifact",
+    "title": "momentum top 3",
+    "market": "cn_stock",
+    "timeframe": "1d",
+    "signalMode": "RULE_ONLY",
+    "factorBindings": [
+      {
+        "factor": "MOMENTUM_20",
+        "direction": "DESC"
+      }
+    ],
+    "ranking": {
+      "topN": 3,
+      "rebalance": "WEEKLY"
+    },
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "600519.SH",
+        "000858.SZ",
+        "300750.SZ",
+        "601318.SH",
+        "600036.SH",
+        "000333.SZ"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": false,
+    "errors": [
+      "SCHEMA"
+    ],
+    "warnings": []
+  }
+}

alphaspec-0.4.0/conformance/cases/valid-factor-only.json

@@ -0,0 +1,41 @@
+{
+  "description": "Contract 0.4: a factor-ranked strategy needs no rule tree.",
+  "document": {
+    "contractVersion": "0.4",
+    "kind": "artifact",
+    "title": "momentum top 3",
+    "market": "cn_stock",
+    "timeframe": "1d",
+    "signalMode": "FACTOR_ONLY",
+    "factorBindings": [
+      {
+        "factor": "MOMENTUM_20",
+        "direction": "DESC"
+      }
+    ],
+    "ranking": {
+      "topN": 3,
+      "rebalance": "WEEKLY"
+    },
+    "universe": {
+      "mode": "SYMBOLS",
+      "symbols": [
+        "600519.SH",
+        "000858.SZ",
+        "300750.SZ",
+        "601318.SH",
+        "600036.SH",
+        "000333.SZ"
+      ]
+    },
+    "producer": {
+      "kind": "HUMAN",
+      "name": "example"
+    }
+  },
+  "expect": {
+    "valid": true,
+    "errors": [],
+    "warnings": []
+  }
+}