alphaspec 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,5 +1,18 @@
 # 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:

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: alphaspec
-Version: 0.2.1
+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.1 → 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.1 → 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.1 → 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
 

{alphaspec-0.2.1 → 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"]