alphaspec 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,10 +1,35 @@
 # Changelog
 
+## 0.3.0 — 2026-10-12
+
+- Contract 0.3 (`schema/0.3/`): new `capabilities` document kind; `gate-result.tradeSettings` reports the exits,
+  sizing and execution an evaluation actually used and every value the runtime defaulted. Artifacts are unchanged
+  from 0.2.
+- Validator accepts 0.1, 0.2 and 0.3; a kind that does not exist in the declared version is `UNSUPPORTED_KIND`.
+- Client / CLI / MCP: `capabilities`, `strategies`, `export` (`export_strategy`), and `promote --target`
+  (`target_strategy_id`) to publish a passing modification as a new version of an existing strategy.
+- RUNTIME_API: the capabilities endpoint, submission checks (`RUNTIME_*` codes, no quota used), export and
+  write-back. Skill: check capabilities before writing; export–edit–resubmit flow.
+- Reference runtime: markets whose history does not cover the evaluation window are rejected at submission
+  instead of being backtested on a silently shorter in-sample; symbols with no bars in the window are rejected.
+
+## 0.2.1 — 2026-10-11
+
+Semantics clarified to match what a runtime can apply the same way in backtests and live trading:
+
+- `exits.minHoldDays` counts **trading days** (entry day = 0; weekends and holidays excluded) and holds back
+  `dsl.exit` as well as the other exits. 0.2.0 said calendar days and left `dsl.exit` free.
+- `sizing.scaleIn` add-ons are filled per `execution.fillTiming` (next open under `NEXT_OPEN`), and never on a bar
+  that also closes the position. 0.2.0 said "at the close of the triggering bar".
+- Reference runtime: backtests and live trading now apply both rules identically; live pyramiding honours
+  `maxTotalPct`; live minimum holding is counted from the start of the current position, not the first time the
+  symbol was ever held.
+
 ## 0.2.0 — 2026-10-11
 
 - Contract 0.2 (`schema/0.2/`): trade settings in three optional artifact blocks.
   - `exits`: stop loss, take profit, trailing stop with activation, ATR stop / take profit, minimum holding days
-    (calendar days on every timeframe), no-new-high exit.
+    (see 0.2.1), no-new-high exit.
   - `sizing`: `FIXED_PCT` or `ATR_RISK` per entry, `maxHoldings`, pyramiding `scaleIn`.
   - `execution`: fill timing (`NEXT_OPEN` / `BAR_CLOSE`).
   Semantics in SPEC §4a.

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: alphaspec
-Version: 0.2.0
+Version: 0.3.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.2/
+Project-URL: Schemas, https://openalpha-dev.github.io/alphaspec/schema/0.3/
 Author: OpenAlpha contributors
 License-Expression: Apache-2.0
 License-File: LICENSE

{alphaspec-0.2.0 → alphaspec-0.3.0}/docs/ROADMAP.md

@@ -37,14 +37,15 @@ Everything a strategy needs beyond its signal, in three optional blocks next to
 
 The per-symbol cap stays where it was, `riskProfile.maxSymbolExposurePct`.
 
-## 0.3 — Capabilities
+## 0.3 — Capabilities and round trip (done)
 
-A runtime publishes what it can do so an agent can plan before it writes:
-
-- markets with data, timeframes per market, indicator profiles available per market;
-- universe modes, benchmark used for out-of-sample comparison, where a passing strategy can be
-  promoted (paper account type per market);
-- `alphaspec capabilities` and an MCP tool; the Skill checks capabilities first.
+- `capabilities` document: per market, whether daily / intraday history covers the evaluation
+  window (and why not), usable indicator profiles, promotability, out-of-sample benchmark,
+  evaluation windows and quota. `alphaspec capabilities`, MCP `get_capabilities`; the Skill reads it first.
+- Runtimes reject at submission what they cannot run (`RUNTIME_*` codes), without using quota.
+- `gate-result.tradeSettings`: the exits, sizing and execution actually used, and every default.
+- Export: a runtime exports a strategy it holds as an artifact; a passing modification can be
+  promoted as a new version of it (`targetStrategyId`).
 
 ## 0.4 — Direction and derivatives
 
@@ -64,9 +65,7 @@ A runtime publishes what it can do so an agent can plan before it writes:
 - Whole-market universes with filters (listing age, liquidity, market cap, exclusions).
 - Dynamic universes defined by screening conditions and re-evaluated on a schedule.
 
-## Round trip and evidence
+## Evidence
 
-- **Export**: a runtime can export any strategy it holds as AlphaSpec, so an agent can read,
-  modify and resubmit an existing strategy; promotion can target a new version of it.
-- **Evidence**: execution evidence (rejections, slippage, fills, drift from target) returned as
-  `evidence` documents for promoted strategies.
+- Execution evidence (rejections, slippage, fills, drift from target) returned as `evidence`
+  documents for promoted strategies.

{alphaspec-0.2.0 → alphaspec-0.3.0}/docs/RUNTIME_API.md

@@ -14,12 +14,50 @@ prefix.
 
 | Method & path | Success | Other responses |
 |---|---|---|
-| `GET /whoami` | 200 identity, `contractVersion` (latest) and `contractVersions` (all accepted), what the key can and cannot do | 401 invalid / revoked / expired key |
-| `POST /artifacts` — body: an `artifact` document | 201 `{artifactId, warnings}` | 422 `{issues}` (same codes as the local validator) · 400 unusable universe |
+| `GET /whoami` | 200 identity, `contractVersion` (latest) and `contractVersions` (all accepted), today's `evaluationQuota`, what the key can and cannot do | 401 invalid / revoked / expired key |
+| `GET /capabilities` | 200 `capabilities` document (contract 0.3): what can be evaluated and promoted right now | |
+| `POST /artifacts` — body: an `artifact` document | 201 `{artifactId, warnings}` | 422 `{issues}` (validator codes, plus `RUNTIME_*` codes below) · 400 unusable universe |
 | `GET /artifacts` | 200 your submissions, newest first, with the latest verdict | |
-| `POST /artifacts/{id}/evaluate` | 202 `{evaluationId, status}` | 429 daily evaluation quota used up · 503 queue full |
+| `POST /artifacts/{id}/evaluate` | 202 `{evaluationId, status}` | 422 `{issues}` the runtime cannot run it (not counted against the quota) · 429 daily evaluation quota used up · 503 queue full |
 | `GET /artifacts/{id}/gate-result` | 200 `gate-result` document | 202 still running · 409 `{status: FAILED, error}` |
-| `POST /artifacts/{id}/promote` — body optional: `{name}` | 201 `{strategyId, created, enabled: false}` · 200 if already promoted | 400 gate not passed · runtime product rules (market, pool size, names) apply as in its UI |
+| `POST /artifacts/{id}/promote` — body optional: `{name, targetStrategyId}` | 201 `{strategyId, created, enabled: false}` · 200 if already promoted · 200 `{updated: true}` with `targetStrategyId` | 400 gate not passed, market not promotable, or target's market / universe differs · runtime product rules (pool size, names) apply as in its UI |
+| `GET /strategies` | 200 your existing strategies | |
+| `GET /strategies/{id}/alphaspec` | 200 `{document, issues}` — an artifact you can edit and resubmit | 422 `{document, issues}` exported but does not validate (e.g. a factor strategy before 0.4) |
+
+## Capabilities
+
+`GET /capabilities` is computed from the runtime's live market data and changes as data is added. For
+every market it says whether the **daily** and **intraday** evaluation windows are covered by history
+(and, when not, how much history exists versus how much the window needs), which indicator profiles an
+evaluation can use there, whether a passing strategy can be promoted, and which index the out-of-sample
+segment is compared against. Read it before writing a document; the Skill does.
+
+The reference runtime's rules:
+
+- A market is evaluable on a timeframe tier when its bars reach back to the start of that tier's
+  in-sample window and are current. Today that is China A-shares, ETFs on daily bars; other markets
+  have months, not years, of history and are declared not evaluable until it is backfilled.
+- Indicator profiles: `core` everywhere; `ext.cn` on `cn_*`; `ext.data` on `cn_stock` (the fundamentals and
+  index datasets cover A-shares only); `ext.l2` nowhere (it needs order-book data a bar backtest does not have).
+- Out-of-sample benchmark: CSI 300 for `cn_stock`, `cn_etf`, `cn_convbond`; other markets are judged on an
+  absolute Sharpe floor.
+- Promotable markets: `cn_stock`, `cn_etf`, `cn_convbond`. Other evaluable markets return a gate result
+  but cannot be promoted.
+
+### Checks at submission
+
+These run on `POST /artifacts` and again before `evaluate` enqueues. Errors reject the document (422)
+and do not use the evaluation quota.
+
+| code | severity | meaning |
+|---|---|---|
+| `RUNTIME_MARKET_UNSUPPORTED` | error | the runtime does not run this market |
+| `RUNTIME_NO_HISTORY` | error | the market's bars do not cover the evaluation window for this timeframe (or `tick`) |
+| `RUNTIME_PROFILE_UNAVAILABLE` | error | an indicator's profile is not usable in an evaluation on this market |
+| `RUNTIME_UNIVERSE_MODE` | error | `ALL_MARKET` or no universe (until 0.4) |
+| `RUNTIME_SYMBOL_NO_DATA` | error | a listed symbol has no bars in the window — almost always a typo |
+| `RUNTIME_SYMBOL_PARTIAL_HISTORY` | warning | a symbol's history starts more than a month after the window does (its in-sample is shorter) |
+| `RUNTIME_NOT_PROMOTABLE` | warning | evaluable, but a passing strategy cannot be promoted on this runtime |
 
 ## Evaluation
 
@@ -66,6 +104,11 @@ The evaluation backtest and the promoted strategy use the same `exits`, `sizing`
   signals. Always send a `sizing` block if position size matters to your result — it usually
   does.
 
+The gate result (contract 0.3) reports what was actually used in `tradeSettings`: the effective
+`exits`, `sizing` and `execution`, and under `defaults` every field the runtime filled in. When the
+default sizing cannot be written as an AlphaSpec `sizing` block, `sizing` is absent and the `/sizing`
+default says in words how positions were sized, with the limits that applied.
+
 "Out-of-sample" here means *chosen by the platform*, not *unseen at submission*: recent
 market data is public. The only truly unseen period is the one after you submit, which is
 what paper trading is for.
@@ -81,6 +124,14 @@ and dropped. The promoted strategy therefore carries no `params`; your submitted
 its parameters, stays attached to the artifact. Trade settings are carried over unchanged and show
 up in the runtime's strategy builder as its stop, position-size and fill-timing settings.
 
+### Updating an existing strategy
+
+`GET /strategies/{id}/alphaspec` exports one of your strategies (rules, trade settings, risk limits,
+universe) as an artifact. Edit it, submit it as a new artifact (count it in `searchTrials`), evaluate,
+and promote with `targetStrategyId` to publish it as a new version of that strategy. Market and
+universe must stay the same; change those in the runtime's UI or promote to a new strategy instead.
+Factor strategies and long/short rule sets cannot be exported before contract 0.4.
+
 ## Python
 
 ```python
@@ -92,4 +143,9 @@ c.evaluate(aid)
 gate = c.wait(aid)                 # polls until done
 if gate["passed"]:
     c.promote(aid, name="my strategy")
+
+c.capabilities()                   # what can be evaluated right now
+doc, issues = c.export_strategy(438)
+# ... edit doc, submit, evaluate ...
+c.promote(new_aid, target_strategy_id=438)
 ```

{alphaspec-0.2.0 → alphaspec-0.3.0}/docs/SPEC.md

@@ -1,4 +1,4 @@
-# AlphaSpec 0.2 — semantics
+# AlphaSpec 0.3 — semantics
 
 The JSON Schemas in `schema/<version>/` define the shape of each document. This page defines
 what the fields **mean**, where the shape alone cannot. Where this page and a runtime
@@ -14,11 +14,18 @@ Every document has `contractVersion` and `kind`.
 | `score` | model / research pipeline | cross-sectional scores or target weights (L1) |
 | `gate-result` | runtime | the verdict on a submission |
 | `evidence` | runtime | what happened when it ran |
+| `capabilities` | runtime | what it can evaluate and promote right now (0.3) |
 
 A runtime must refuse a `contractVersion` it does not implement rather than guess.
 Versions are additive: a document is validated against the schemas of the version it
-declares, so a `0.1` document carrying `0.2` fields is rejected, not half-read. Use `0.2`
-when you need trade settings (section 4a).
+declares, so a `0.1` document carrying `0.2` fields is rejected, not half-read. Use `0.2` or
+later when you need trade settings (section 4a). 0.3 adds no artifact fields; it adds the
+`capabilities` document and `tradeSettings` in gate results.
+
+A runtime must not accept a document it cannot run as written. When its data or features fall
+short (a market without enough history, an indicator it cannot compute in a backtest), it rejects
+at submission and says why; it publishes those limits in its `capabilities` document so an author
+can check before writing.
 
 ## 2. Time
 
@@ -99,11 +106,14 @@ Whichever fires first closes the whole position.
 | `atrStopMultiplier` | close ≤ entry − k × ATR(14) |
 | `atrTakeProfitMultiplier` | close ≥ entry + k × ATR(14) |
 | `noNewHighDays` | n trading days pass without a new highest close since entry |
-| `minHoldDays` | (modifies all of the above) none fires within n **calendar** days of entry; `dsl.exit` still does |
+| `minHoldDays` | (modifies everything, `dsl.exit` included) nothing closes the position until n **trading days** after entry |
 
 - Omit a field to leave that exit off. `0` is rejected for the on/off fields: one runtime's
   "disabled" is another's "stop immediately".
-- `minHoldDays` counts calendar days on every timeframe: 3 on a 5m strategy is three days.
+- `minHoldDays` counts trading days in the market's calendar: the entry day is day 0, weekends and
+  holidays do not count, and the meaning is the same on every timeframe (3 on a 5m strategy is three
+  trading days). It holds back rule exits too: its purpose is to keep a fresh position from being
+  shaken out by short-term noise. Leave it out if the strategy should be free to exit at once.
 
 **`sizing`** — how large each position is and how many are held.
 
@@ -112,7 +122,7 @@ Whichever fires first closes the whole position.
 | `positionMode` | `FIXED_PCT` (default): each entry buys `targetPctPerOrder`% of current equity. `ATR_RISK`: each entry is sized so one ATR(14) against it costs `targetPctPerOrder`% of equity; no entry while ATR cannot be computed |
 | `targetPctPerOrder` | the percentage above (required when `sizing` is present) |
 | `maxHoldings` | at most n symbols held at once; buys already queued count as held, so signals on the same bar cannot overshoot; further entries are skipped |
-| `scaleIn` | pyramiding: `{maxAddOns, spacingAtr, maxTotalPct}` — add to a winner each time the close is `spacingAtr` × ATR(14) above the last buy, at most `maxAddOns` times; an add-on that would take the symbol above `maxTotalPct`% of equity is skipped |
+| `scaleIn` | pyramiding: `{maxAddOns, spacingAtr, maxTotalPct}` — add to a winner each time the close is `spacingAtr` × ATR(14) above the last buy, at most `maxAddOns` times; an add-on that would take the symbol above `maxTotalPct`% of equity is skipped; filled per `execution.fillTiming`, never on a bar that closes the position |
 
 Equity is cash plus the market value of all positions. Every buy rounds down to the market's
 lot and is capped by `riskProfile.maxSymbolExposurePct` and by cash. Without a `sizing`

{alphaspec-0.2.0 → alphaspec-0.3.0}/pyproject.toml

@@ -27,7 +27,7 @@ dependencies = [
 Homepage = "https://github.com/openalpha-dev/alphaspec"
 Documentation = "https://github.com/openalpha-dev/alphaspec#readme"
 Changelog = "https://github.com/openalpha-dev/alphaspec/blob/main/CHANGELOG.md"
-Schemas = "https://openalpha-dev.github.io/alphaspec/schema/0.2/"
+Schemas = "https://openalpha-dev.github.io/alphaspec/schema/0.3/"
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.2"]

{alphaspec-0.2.0 → alphaspec-0.3.0}/schema/0.2/artifact.schema.json

@@ -756,7 +756,7 @@
           "type": "integer",
           "minimum": 1,
           "maximum": 365,
-          "description": "Calendar days after entry during which none of the exits above fire (dsl.exit still does). Calendar days on every timeframe: 3 on a 5m strategy is three days, not three bars."
+          "description": "Trading days after entry during which nothing closes the position: neither the exits above nor dsl.exit. The entry day is day 0; weekends and market holidays do not count, on every timeframe (3 on a 5m strategy is three trading days). Use it to keep a fresh position from being shaken out by short-term noise; omit it if that is not wanted."
         },
         "noNewHighDays": {
           "type": "integer",
@@ -821,7 +821,7 @@
         "maxAddOns",
         "spacingAtr"
       ],
-      "description": "Pyramiding: add to a winning position each time the close rises spacingAtr × ATR(14) above the last buy price. Each add-on is sized like an entry (positionMode / targetPctPerOrder). Filled at the close of the bar that triggers it.",
+      "description": "Pyramiding: add to a winning position each time the close rises spacingAtr × ATR(14) above the last buy price. Each add-on is sized like an entry (positionMode / targetPctPerOrder). Filled like any other order under execution.fillTiming: at the triggering bar's close (BAR_CLOSE) or at the next bar's open (NEXT_OPEN). No add-on is made on a bar that also closes the position.",
       "properties": {
         "maxAddOns": {
           "type": "integer",