alphaspec 0.1.0__py3-none-any.whl

alphaspec/_data/skills/alphaspec/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: alphaspec
+description: Write, fix, validate and submit AlphaSpec documents — declarative trading-strategy artifacts (a rule tree of indicators with entry/exit conditions, universe and risk settings) and model score submissions — and run them on an AlphaSpec runtime for backtest, gate and paper trading. Use when asked to turn a trading idea into a strategy, write or edit a strategy as JSON/DSL, explain an AlphaSpec validation error (SCHEMA, AS001–AS105), or submit / evaluate / promote a strategy.
+---
+
+# AlphaSpec
+
+AlphaSpec documents are JSON and contain no code. Everything you need comes from the `alphaspec` command; do not guess indicator names or parameter keys.
+
+## Setup (once)
+
+```bash
+pip install alphaspec          # validator, indicator catalog, schemas, examples, runtime client
+alphaspec --version
+```
+
+If you have no shell but the `alphaspec` MCP server is connected, use its tools instead: the same steps map to `list_examples`/`get_example`, `search_indicators`/`get_indicator`, `validate`/`explain_rule`, `submit`, `evaluate` then poll `gate_result`, and `promote`.
+
+## Workflow
+
+1. **Pick the document type.**
+   - The user has a model or factor producing a number per symbol per day → `kind: "score"` (see `alphaspec examples 01-model-scores` and `alphaspec schema score`).
+   - The user describes conditions on indicators → `kind: "artifact"`. The rest of this guide is about artifacts.
+2. **Start from an example**: `alphaspec examples` lists them; `alphaspec examples 01-ema-cross` prints one.
+3. **Choose market and timeframe.** Markets: `alphaspec docs markets`. Timeframes are exactly `tick 1m 5m 15m 30m 1h 4h 1d 1w` (`1h`, never `60m`).
+4. **Find indicators** — never invent names:
+   - `alphaspec catalog --market <market> --search <word>` to find candidates (search in English or Chinese: `RSI`, `moving average`, `breakout`, `均线`). Add `--lang zh` or `--lang en` to pick the description language; the default follows the locale.
+   - `alphaspec catalog --type <TYPE>` for the full entry: parameter keys, defaults, ranges, meaning, unit and **pitfalls**. Read the pitfalls; several conditions that look natural can never be true (e.g. `close > DAY_HIGH`).
+5. **Write the document**, then **validate until clean**:
+   ```bash
+   alphaspec validate doc.json          # fix every ERROR; treat WARNINGs as probable mistakes
+   alphaspec rules --explain AS003      # why a rule exists and how to fix it
+   ```
+6. **Submit and evaluate** (only if the user wants it run; see below).
+
+## Rule tree essentials
+
+```json
+"dsl": {
+  "version": 1,
+  "params": { "fastPeriod": 20 },
+  "indicators": {
+    "fast":  { "type": "EMA", "period": { "ref": "fastPeriod" } },
+    "slow":  { "type": "EMA", "period": 60 },
+    "trend": { "type": "EMA", "period": 50, "timeframe": "1d", "barPolicy": "CLOSED" }
+  },
+  "entry": { "type": "AND",
+             "left":  { "type": "CROSS_UP", "left": { "ind": "fast" }, "right": { "ind": "slow" } },
+             "right": { "type": "GT", "left": { "ind": "close" }, "right": { "ind": "trend" } } },
+  "exit":  { "type": "CROSS_DOWN", "left": { "ind": "fast" }, "right": { "ind": "slow" } }
+}
+```
+
+- `AND` / `OR`: `left` and `right` are **rules**. `NOT` / `DAY_LATCH`: the child goes in `rule`, not `left`.
+- Comparisons `GT GTE LT LTE EQ NEQ CROSS_UP CROSS_DOWN`: `left` / `right` are **operands**.
+- An operand is `{"ind": alias}`, `{"const": n}`, `{"ref": param}`, inline arithmetic `{"op": "SUB", "left": …, "right": …}` or `{"op": "COUNT" | "BARS_SINCE", "rule": …, "bars": n}`. **Never a bare number**: `"right": 30` is invalid, write `{"const": 30}`.
+- `close` is a built-in alias. Every other alias must be declared in `indicators`.
+- Temporal rules: `HOLD_FOR` (held each of the last N bars), `WITHIN` (held at least once in the last N), `SEQUENCE` (`first` then `then` within N bars).
+- Level events `TOUCH BREAK RECLAIM RETEST HOLD` take any operand as `level` (a band, a moving average, a pivot).
+- An indicator on a coarser `timeframe` than the strategy's must use `barPolicy: "CLOSED"` (the default). `LIVE` there is look-ahead (AS003).
+- Put anything tunable in `dsl.params` and reference it with `{"ref": …}`.
+- Symbols on `cn_*` / `hk_*` carry the venue suffix: `600000.SH`, `000001.SZ`, `00700.HK` (AS011).
+- Indicators of profile `ext.cn` (price-limit streaks, sealed boards, call auction) exist only on `cn_*` markets.
+
+## Producer
+
+If you (an AI) wrote or tuned the document: `"producer": {"kind": "AI_AGENT", "name": "<your tool>@<version>", "modelId": "<model>", "searchTrials": N}`, where `N` counts **every** candidate evaluated in this search, including discarded ones. Under-reporting it hides search luck from the gate.
+
+## Submitting to the runtime
+
+Needs `ALPHASPEC_BASE_URL` and `ALPHASPEC_API_KEY` (the user creates the key in the runtime's account page; never ask them to paste it into a file you commit).
+
+```bash
+alphaspec whoami                         # check the key first
+alphaspec submit doc.json --evaluate     # validate, submit, evaluate on platform-chosen windows, print the gate result
+alphaspec result <artifactId>            # re-read the latest gate result
+alphaspec promote <artifactId>           # only after the gate passed; creates a DISABLED paper strategy
+```
+
+- Exit code 1 = rejected, gate not passed or evaluation failed. Read the printed checks and hints, change the document, submit it again as a new artifact and count it in `searchTrials`.
+- Evaluations have a daily quota. Do not loop submissions hunting for a passing variant; that is exactly the search luck the gate corrects for.
+- Never state backtest numbers the runtime did not return. After `promote`, tell the user the strategy is created disabled and they start it themselves.
+- Full API and status codes: `alphaspec docs runtime`.
+
+## Never
+
+- Put code, scripts or expression strings into a document.
+- Include orders, account ids or broker routes.
+- Report performance figures as fields of a submission. The runtime computes them.
+
+## Reference
+
+`alphaspec docs spec` (field semantics: time, bars, units) · `alphaspec docs rules` (every lint rule) · `alphaspec schema artifact` (the JSON Schema).

alphaspec/_resources.py

@@ -0,0 +1,77 @@
+"""Locate the bundled schema and catalog files.
+
+Installed wheels carry them under alphaspec/_data; a source checkout reads them
+from the repository root, so there is exactly one copy to edit.
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+CONTRACT_VERSION = "0.1"
+
+_PKG_DATA = Path(__file__).resolve().parent / "_data"
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _root() -> Path:
+    if (_PKG_DATA / "schema").is_dir():
+        return _PKG_DATA
+    if (_REPO_ROOT / "schema").is_dir():
+        return _REPO_ROOT
+    raise FileNotFoundError("alphaspec schema files not found; reinstall the package")
+
+
+def schema_dir(version: str = CONTRACT_VERSION) -> Path:
+    return _root() / "schema" / version
+
+
+@lru_cache(maxsize=None)
+def load_schema(name: str, version: str = CONTRACT_VERSION) -> dict[str, Any]:
+    path = schema_dir(version) / f"{name}.schema.json"
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=None)
+def load_catalog() -> dict[str, Any]:
+    path = _root() / "catalog" / "indicators.json"
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def default_lang() -> str:
+    """Language for catalog text: $ALPHASPEC_LANG, else zh on a Chinese locale, else en."""
+    import os
+    lang = os.environ.get("ALPHASPEC_LANG") or ""
+    if lang in ("zh", "en"):
+        return lang
+    loc = os.environ.get("LC_ALL") or os.environ.get("LANG") or ""
+    return "zh" if loc.lower().startswith("zh") else "en"
+
+
+def localized(entry: dict[str, Any], lang: str) -> dict[str, Any]:
+    """A catalog entry with summary, pitfalls, label and parameter descriptions in one language.
+
+    The catalog keeps Chinese in the top-level fields and English under ``en``; agents asked
+    for one language should not have to read both."""
+    out = {k: v for k, v in entry.items() if k != "en"}
+    labels = entry.get("labels") or {}
+    if labels:
+        out["label"] = labels.get(lang) or labels.get("zh")
+        out.pop("labels")
+    if lang == "en" and "en" in entry:
+        en = entry["en"]
+        out["summary"] = en.get("summary", out.get("summary"))
+        if "pitfalls" in en:
+            out["pitfalls"] = en["pitfalls"]
+        descs = en.get("params", {})
+        out["params"] = [{**p, "description": descs[p["key"]]} if p["key"] in descs else p
+                         for p in entry.get("params", [])]
+    return out
+
+
+def data_root() -> Path:
+    """Directory holding schema/, catalog/, examples/ and docs/ (installed copy or checkout)."""
+    return _root()
+

alphaspec/cli.py

@@ -0,0 +1,360 @@
+"""Command line.
+
+    alphaspec validate FILE...              check documents locally
+    alphaspec rules [--explain CODE]        list lint rules / why one exists
+    alphaspec catalog [--market M] [--profile P] [--search TEXT] [--type T] [--lang en|zh]
+                                            indicators you may use, with meaning and parameters
+    alphaspec schema KIND                   print a JSON Schema (artifact, score, gate-result, evidence, common)
+    alphaspec examples [NAME]               list or print example documents
+    alphaspec docs NAME                     print a reference document (spec, rules, markets, runtime)
+    alphaspec skill [--install DIR]         print the Agent Skill, or write it to DIR/alphaspec/SKILL.md
+
+    alphaspec whoami                        check the API key against the runtime
+    alphaspec submit FILE [--evaluate] [--wait] [--promote [--name N]]
+    alphaspec evaluate ARTIFACT_ID [--wait]
+    alphaspec result ARTIFACT_ID
+    alphaspec list
+    alphaspec promote ARTIFACT_ID [--name N]
+
+Runtime commands read ALPHASPEC_BASE_URL and ALPHASPEC_API_KEY (or --base-url / --api-key).
+Exit codes: 0 ok · 1 rejected, gate not passed or evaluation failed · 2 usage · 3 runtime / network error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .client import AlphaSpecError, Client, EvaluationFailed, Rejected
+from ._resources import data_root, default_lang, load_catalog, load_schema, localized
+from .lints import RULES
+from .validate import validate
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    failed = 0
+    for name in args.files:
+        path = Path(name)
+        try:
+            doc = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"{path}: cannot read: {exc}")
+            failed += 1
+            continue
+        report = validate(doc)
+        bad = not report.ok or (args.strict and report.warnings)
+        failed += bool(bad)
+        if args.json:
+            print(json.dumps({
+                "file": str(path), "kind": report.kind, "ok": not bad,
+                "issues": [i.__dict__ for i in report.issues],
+            }, ensure_ascii=False))
+            continue
+        status = "FAIL" if bad else "ok"
+        print(f"{path}: {status} ({len(report.errors)} errors, {len(report.warnings)} warnings)")
+        for issue in report.issues:
+            print(f"  {issue}")
+    return 1 if failed else 0
+
+
+def _cmd_rules(args: argparse.Namespace) -> int:
+    if args.explain:
+        code = args.explain.upper()
+        text = (data_root() / "docs" / "RULES.md").read_text(encoding="utf-8")
+        start = text.find(f"### {code}")
+        if start < 0:
+            print(f"unknown rule {code}", file=sys.stderr)
+            return 2
+        end = text.find("\n### ", start + 1)
+        print(text[start:end if end > 0 else None].strip())
+        return 0
+    for code, title in RULES.items():
+        print(f"{code}  {title}")
+    return 0
+
+
+def _market_allows(profile: str, market: str | None) -> bool:
+    if market is None:
+        return True
+    if profile == "ext.cn":
+        return market.startswith("cn_")
+    return True
+
+
+def _cmd_catalog(args: argparse.Namespace) -> int:
+    cat = load_catalog()
+    if args.type:
+        t = next((x for x in cat["types"] if x["type"] == args.type.upper()), None)
+        if t is None:
+            print(f"unknown indicator type {args.type}", file=sys.stderr)
+            return 2
+        print(json.dumps(localized(t, args.lang), ensure_ascii=False, indent=2))
+        return 0
+    rows = [t for t in cat["types"]
+            if (args.profile is None or t["profile"] == args.profile)
+            and _market_allows(t["profile"], args.market)
+            and (args.search is None or args.search.lower() in json.dumps(t, ensure_ascii=False).lower())]
+    rows = [localized(t, args.lang) for t in rows]
+    if args.json:
+        print(json.dumps(rows, ensure_ascii=False, indent=2))
+        return 0
+    for t in rows:
+        params = ", ".join(f"{p['key']}={p.get('default', '?')}" for p in t.get("params", []))
+        operands = ", ".join(t.get("operandKeys", []))
+        sig = params or (f"operands: {operands}" if operands else "")
+        print(f"{t['type']:28} {t['profile']:8} {sig}")
+        if t.get("summary"):
+            print(f"    {t['summary']}")
+    print(f"\n{len(rows)} indicator types. Details: alphaspec catalog --type NAME", file=sys.stderr)
+    return 0
+
+
+def _cmd_schema(args: argparse.Namespace) -> int:
+    print(json.dumps(load_schema(args.kind), ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cmd_examples(args: argparse.Namespace) -> int:
+    files = sorted((data_root() / "examples").rglob("*.json"))
+    if not args.name:
+        for f in files:
+            doc = json.loads(f.read_text(encoding="utf-8"))
+            print(f"{f.stem:36} {doc.get('kind'):9} {doc.get('market'):12} {doc.get('title') or doc.get('scoreName')}")
+        return 0
+    match = [f for f in files if f.stem == args.name or f.stem.startswith(args.name)]
+    if not match:
+        print(f"no example named {args.name}", file=sys.stderr)
+        return 2
+    print(match[0].read_text(encoding="utf-8"), end="")
+    return 0
+
+
+_DOCS = {"spec": "SPEC.md", "rules": "RULES.md", "markets": "MARKETS.md", "runtime": "RUNTIME_API.md"}
+
+
+def _cmd_docs(args: argparse.Namespace) -> int:
+    print((data_root() / "docs" / _DOCS[args.name]).read_text(encoding="utf-8"), end="")
+    return 0
+
+
+def _cmd_skill(args: argparse.Namespace) -> int:
+    text = (data_root() / "skills" / "alphaspec" / "SKILL.md").read_text(encoding="utf-8")
+    if not args.install:
+        print(text, end="")
+        return 0
+    target = Path(args.install).expanduser() / "alphaspec" / "SKILL.md"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8")
+    print(f"installed {target}")
+    return 0
+
+
+def _client(args: argparse.Namespace) -> Client:
+    return Client(base_url=args.base_url, api_key=args.api_key)
+
+
+def _out(args: argparse.Namespace, obj: Any, human: str) -> None:
+    print(json.dumps(obj, ensure_ascii=False, indent=2) if args.json else human)
+
+
+def _print_gate(args: argparse.Namespace, gate: dict[str, Any]) -> int:
+    if args.json:
+        print(json.dumps(gate, ensure_ascii=False, indent=2))
+    else:
+        verdict = "PASSED" if gate.get("passed") else "NOT PASSED"
+        print(f"gate {verdict} (computedBy {gate.get('computedBy')})")
+        sample = gate.get("sample") or {}
+        if sample:
+            line = f"  in-sample {sample.get('inSampleFrom')} ~ {sample.get('inSampleTo')}"
+            if sample.get("outOfSampleFrom"):
+                line += f" · out-of-sample {sample.get('outOfSampleFrom')} ~ {sample.get('outOfSampleTo')}"
+            print(line)
+        for c in gate.get("checks", []):
+            mark = "✓" if c.get("passed") else "✗"
+            metric = c.get("metric") or "actual"
+            print(f"  {mark} {c.get('code'):24} {metric}={c.get('actual')} threshold={c.get('threshold')}")
+            # Printed for passing checks too: without it a reader guesses what the number is.
+            if c.get("hint"):
+                print(f"      {c['hint']}")
+    report = validate(gate)
+    if not report.ok:
+        print("warning: runtime returned a gate-result that does not match the contract:", file=sys.stderr)
+        for i in report.issues:
+            print(f"  {i}", file=sys.stderr)
+    return 0 if gate.get("passed") else 1
+
+
+def _cmd_whoami(args: argparse.Namespace) -> int:
+    me = _client(args).whoami()
+    _out(args, me, f"{me.get('username')} · key {me.get('keyId')} · contract {me.get('contractVersion')}\n"
+                   f"  can:    {', '.join(me.get('canDo', []))}\n"
+                   f"  cannot: {', '.join(me.get('cannotDo', []))}")
+    return 0
+
+
+def _evaluate_and_wait(args: argparse.Namespace, c: Client, artifact_id: int) -> int:
+    started = c.evaluate(artifact_id)
+    if not args.wait:
+        _out(args, started, f"evaluation {started.get('evaluationId')} {started.get('status')} "
+                            f"— poll with: alphaspec result {artifact_id}")
+        return 0
+    if not args.json:
+        print(f"evaluating artifact {artifact_id} (in-sample + out-of-sample backtests) ...", file=sys.stderr)
+    return _print_gate(args, c.wait(artifact_id, timeout=args.timeout))
+
+
+def _cmd_submit(args: argparse.Namespace) -> int:
+    doc = json.loads(Path(args.file).read_text(encoding="utf-8"))
+    c = _client(args)
+    res = c.submit(doc)
+    aid = res["artifactId"]
+    warnings = res.get("warnings") or []
+    if not args.json:
+        print(f"submitted: artifact {aid}" + (f" ({len(warnings)} warnings)" if warnings else ""))
+        for w in warnings:
+            print(f"  WARNING {w.get('code')} at {w.get('path')}: {w.get('message')}")
+    elif not (args.evaluate or args.promote):
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+    if not (args.evaluate or args.promote):
+        return 0
+    rc = _evaluate_and_wait(argparse.Namespace(**{**vars(args), "wait": True}), c, aid)
+    if rc != 0 or not args.promote:
+        return rc
+    return _promote(args, c, aid)
+
+
+def _cmd_evaluate(args: argparse.Namespace) -> int:
+    return _evaluate_and_wait(args, _client(args), args.artifact_id)
+
+
+def _cmd_result(args: argparse.Namespace) -> int:
+    state, body = _client(args).gate_result(args.artifact_id)
+    if state == "DONE":
+        return _print_gate(args, body)
+    _out(args, body, f"{state}" + (f": {body.get('error')}" if body.get("error") else ""))
+    return 1 if state == "FAILED" else 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    rows = _client(args).list()
+    if args.json:
+        print(json.dumps(rows, ensure_ascii=False, indent=2))
+        return 0
+    for r in rows:
+        verdict = "—" if not r.get("evaluated") else ("passed" if r.get("passed") else "not passed")
+        print(f"{r.get('artifactId'):>8}  {verdict:11}  {r.get('title')}")
+    return 0
+
+
+def _promote(args: argparse.Namespace, c: Client, artifact_id: int) -> int:
+    res = c.promote(artifact_id, getattr(args, "name", None))
+    what = "created" if res.get("created") else "already exists"
+    _out(args, res, f"paper strategy {res.get('strategyId')} {what} (disabled) — {res.get('next')}")
+    return 0
+
+
+def _cmd_promote(args: argparse.Namespace) -> int:
+    return _promote(args, _client(args), args.artifact_id)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="alphaspec", description="AlphaSpec: validate documents and talk to a runtime.")
+    parser.add_argument("--version", action="version", version=f"alphaspec {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    v = sub.add_parser("validate", help="validate documents locally")
+    v.add_argument("files", nargs="+")
+    v.add_argument("--strict", action="store_true", help="treat warnings as failures")
+    v.add_argument("--json", action="store_true", help="one JSON line per file")
+    v.set_defaults(func=_cmd_validate)
+
+    r = sub.add_parser("rules", help="list lint rules")
+    r.add_argument("--explain", metavar="CODE", help="print why a rule exists and how to fix it")
+    r.set_defaults(func=_cmd_rules)
+
+    c = sub.add_parser("catalog", help="indicator types you may use")
+    c.add_argument("--market", help="only types usable on this market (e.g. us_equity hides China-only types)")
+    c.add_argument("--profile", choices=["core", "ext.cn", "ext.l2", "ext.data"])
+    c.add_argument("--search", help="substring match on name, summary and parameters")
+    c.add_argument("--type", help="full entry for one type")
+    c.add_argument("--lang", choices=["en", "zh"], default=default_lang(),
+                   help="language of descriptions (default: $ALPHASPEC_LANG, else from the locale)")
+    c.add_argument("--json", action="store_true")
+    c.set_defaults(func=_cmd_catalog)
+
+    sc = sub.add_parser("schema", help="print a JSON Schema")
+    sc.add_argument("kind", choices=["artifact", "score", "gate-result", "evidence", "common"])
+    sc.set_defaults(func=_cmd_schema)
+
+    ex = sub.add_parser("examples", help="list or print example documents")
+    ex.add_argument("name", nargs="?")
+    ex.set_defaults(func=_cmd_examples)
+
+    dc = sub.add_parser("docs", help="print a reference document")
+    dc.add_argument("name", choices=sorted(_DOCS))
+    dc.set_defaults(func=_cmd_docs)
+
+    sk = sub.add_parser("skill", help="print or install the Agent Skill")
+    sk.add_argument("--install", metavar="DIR",
+                    help="skills directory, e.g. ~/.claude/skills (writes DIR/alphaspec/SKILL.md)")
+    sk.set_defaults(func=_cmd_skill)
+
+    remote = argparse.ArgumentParser(add_help=False)
+    remote.add_argument("--base-url", help="runtime base URL (default: $ALPHASPEC_BASE_URL)")
+    remote.add_argument("--api-key", help="API key (default: $ALPHASPEC_API_KEY)")
+    remote.add_argument("--json", action="store_true", help="machine-readable output")
+
+    w = sub.add_parser("whoami", parents=[remote], help="check the API key")
+    w.set_defaults(func=_cmd_whoami)
+
+    s = sub.add_parser("submit", parents=[remote], help="submit an artifact")
+    s.add_argument("file")
+    s.add_argument("--evaluate", action="store_true", help="start an evaluation after submitting and wait for it")
+    s.add_argument("--promote", action="store_true", help="also turn it into a paper strategy if the gate passes")
+    s.add_argument("--name", help="strategy name for --promote (default: document title)")
+    s.add_argument("--timeout", type=float, default=900, help="seconds to wait for the evaluation")
+    s.set_defaults(func=_cmd_submit)
+
+    e = sub.add_parser("evaluate", parents=[remote], help="start a platform evaluation")
+    e.add_argument("artifact_id", type=int)
+    e.add_argument("--wait", action="store_true", help="wait for the gate result")
+    e.add_argument("--timeout", type=float, default=900)
+    e.set_defaults(func=_cmd_evaluate)
+
+    g = sub.add_parser("result", parents=[remote], help="show the latest gate result")
+    g.add_argument("artifact_id", type=int)
+    g.set_defaults(func=_cmd_result)
+
+    lst = sub.add_parser("list", parents=[remote], help="list my submissions")
+    lst.set_defaults(func=_cmd_list)
+
+    p = sub.add_parser("promote", parents=[remote], help="turn a gate-passed artifact into a paper strategy")
+    p.add_argument("artifact_id", type=int)
+    p.add_argument("--name")
+    p.set_defaults(func=_cmd_promote)
+
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except Rejected as exc:
+        print(f"rejected: {len(exc.issues)} issue(s)", file=sys.stderr)
+        for i in exc.issues:
+            print(f"  {i.get('severity', 'error').upper():7} {i.get('code')} at {i.get('path') or '/'}: {i.get('message')}",
+                  file=sys.stderr)
+        return 1
+    except EvaluationFailed as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except (AlphaSpecError, OSError, TimeoutError) as exc:
+        print(f"runtime error: {exc}", file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())

alphaspec/client.py

@@ -0,0 +1,146 @@
+"""Client for an AlphaSpec runtime's agent API (/api/agent/v1).
+
+Standard library only. Configure with arguments or environment variables:
+
+    ALPHASPEC_BASE_URL   e.g. https://your-runtime.example.com
+    ALPHASPEC_API_KEY    eqk_... (created in the runtime's account page)
+
+The API key can submit documents, run evaluations and read results. It cannot place
+orders or touch accounts; that boundary is enforced by the runtime, not by this client.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .validate import Report, validate
+
+API_PREFIX = "/api/agent/v1"
+
+
+class AlphaSpecError(Exception):
+    """Any non-success response from the runtime."""
+
+    def __init__(self, status: int, body: Any, message: str | None = None):
+        self.status = status
+        self.body = body
+        detail = body.get("message") if isinstance(body, dict) else None
+        super().__init__(message or f"HTTP {status}: {detail or body}")
+
+
+class Rejected(AlphaSpecError):
+    """The document failed validation (locally or on the runtime). ``issues`` lists every problem."""
+
+    def __init__(self, status: int, body: Any, issues: list[dict[str, Any]]):
+        self.issues = issues
+        super().__init__(status, body, f"rejected with {len(issues)} issue(s)")
+
+
+class EvaluationFailed(AlphaSpecError):
+    """The runtime could not finish an evaluation (no data for the symbols, unsupported universe ...)."""
+
+
+class Client:
+    def __init__(self, base_url: str | None = None, api_key: str | None = None, timeout: float = 30.0):
+        base_url = base_url or os.environ.get("ALPHASPEC_BASE_URL")
+        api_key = api_key or os.environ.get("ALPHASPEC_API_KEY")
+        if not base_url:
+            raise ValueError("base_url is required (or set ALPHASPEC_BASE_URL)")
+        if not api_key:
+            raise ValueError("api_key is required (or set ALPHASPEC_API_KEY)")
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------ calls
+
+    def whoami(self) -> dict[str, Any]:
+        return self._request("GET", "/whoami")[1]
+
+    def submit(self, doc: dict[str, Any], validate_locally: bool = True) -> dict[str, Any]:
+        """Submit an artifact. Returns ``{"artifactId": ..., "warnings": [...]}``.
+
+        Validates locally first (same rules as the runtime) so obvious mistakes never
+        cost a round trip. Raises :class:`Rejected` with every issue on failure.
+        """
+        if validate_locally:
+            report: Report = validate(doc)
+            if not report.ok:
+                raise Rejected(0, None, [i.__dict__ for i in report.issues])
+        return self._request("POST", "/artifacts", doc)[1]
+
+    def list(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/artifacts")[1]
+
+    def evaluate(self, artifact_id: int) -> dict[str, Any]:
+        """Start a platform evaluation. Returns ``{"evaluationId", "status"}`` immediately."""
+        return self._request("POST", f"/artifacts/{artifact_id}/evaluate")[1]
+
+    def gate_result(self, artifact_id: int) -> tuple[str, dict[str, Any]]:
+        """Return ``(state, body)`` where state is DONE, RUNNING or FAILED.
+
+        DONE carries the gate-result document; RUNNING and FAILED carry ``{"status", "error"?}``.
+        """
+        status, body = self._request("GET", f"/artifacts/{artifact_id}/gate-result", allow=(202, 409))
+        if status == 202:
+            return "RUNNING", body
+        if status == 409:
+            return "FAILED", body
+        return "DONE", body
+
+    def wait(self, artifact_id: int, timeout: float = 900, interval: float = 3) -> dict[str, Any]:
+        """Poll until the evaluation finishes. Returns the gate-result document."""
+        deadline = time.monotonic() + timeout
+        while True:
+            state, body = self.gate_result(artifact_id)
+            if state == "DONE":
+                return body
+            if state == "FAILED":
+                raise EvaluationFailed(409, body, f"evaluation failed: {body.get('error')}")
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"evaluation of artifact {artifact_id} still running after {timeout}s")
+            time.sleep(interval)
+
+    def promote(self, artifact_id: int, name: str | None = None) -> dict[str, Any]:
+        """Turn a gate-passed artifact into a paper-trading strategy (created disabled;
+        the user starts it in the runtime's UI)."""
+        return self._request("POST", f"/artifacts/{artifact_id}/promote", {"name": name} if name else None)[1]
+
+    # ------------------------------------------------------------------ http
+
+    def _request(self, method: str, path: str, body: Any = None, allow: tuple[int, ...] = ()) -> tuple[int, Any]:
+        data = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(
+            self.base_url + API_PREFIX + path,
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "alphaspec-python",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.status, _decode(resp.read())
+        except urllib.error.HTTPError as e:
+            payload = _decode(e.read())
+            if e.code in allow:
+                return e.code, payload
+            if e.code == 422 and isinstance(payload, dict):
+                raise Rejected(422, payload, payload.get("issues", [])) from None
+            raise AlphaSpecError(e.code, payload) from None
+
+
+def _decode(raw: bytes) -> Any:
+    if not raw:
+        return None
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return raw.decode("utf-8", errors="replace")