alphaspec 0.1.0__py3-none-any.whl

alphaspec/_data/schema/0.1/artifact.schema.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openalpha-dev.github.io/alphaspec/schema/0.1/artifact.schema.json",
+  "title": "AlphaSpec Strategy Artifact (L2)",
+  "description": "A complete, declarative strategy: rule tree, parameters, universe and risk overrides. Contains no code; everything here can be validated before it runs.",
+  "type": "object",
+  "required": ["contractVersion", "kind", "title", "market", "timeframe", "dsl", "producer"],
+  "additionalProperties": false,
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "artifact" },
+    "title": { "type": "string", "minLength": 1, "maxLength": 120 },
+    "note": { "type": "string", "maxLength": 2000 },
+
+    "market": { "$ref": "common.schema.json#/$defs/marketId" },
+    "timeframe": { "$ref": "common.schema.json#/$defs/timeframe", "description": "Primary timeframe: the bar series the rule tree is evaluated on." },
+
+    "templateKey": {
+      "type": "string",
+      "pattern": "^[A-Z0-9_]+$",
+      "description": "Optional. Names a runtime template this artifact instantiates. Omit it for a self-contained rule tree."
+    },
+    "templateRevision": { "type": "integer", "minimum": 1, "description": "Pins the template revision so a template edit cannot silently change this artifact's meaning." },
+
+    "signalMode": {
+      "type": "string",
+      "enum": ["AUTO", "FACTOR_ONLY", "RULE_ONLY", "FACTOR_AND_RULE", "FACTOR_OR_RULE"],
+      "default": "AUTO",
+      "description": "How factor ranking and the rule tree combine. AUTO lets the runtime infer it from what is present."
+    },
+
+    "dsl": { "$ref": "#/$defs/dsl" },
+    "riskProfile": { "$ref": "common.schema.json#/$defs/riskProfile" },
+    "universe": { "$ref": "#/$defs/universe" },
+    "factorBindings": { "type": "array", "items": { "$ref": "#/$defs/factorBinding" } },
+    "producer": { "$ref": "common.schema.json#/$defs/producer" }
+  },
+
+  "$defs": {
+    "dsl": {
+      "type": "object",
+      "required": ["version", "indicators", "entry"],
+      "additionalProperties": false,
+      "properties": {
+        "version": { "const": 1 },
+        "params": {
+          "type": "object",
+          "description": "Named constants referenced from anywhere in the tree as {\"ref\": \"name\"}. This is what parameter scans vary.",
+          "additionalProperties": { "type": ["number", "string", "boolean"] }
+        },
+        "indicators": {
+          "type": "object",
+          "minProperties": 1,
+          "description": "Alias -> indicator. Aliases are referenced from rules as {\"ind\": \"alias\"}.",
+          "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+          "additionalProperties": { "$ref": "#/$defs/indicator" }
+        },
+        "entry": { "$ref": "#/$defs/rule" },
+        "exit": { "$ref": "#/$defs/rule" }
+      }
+    },
+
+    "indicator": {
+      "type": "object",
+      "required": ["type"],
+      "description": "One indicator instance. 'type' must exist in the indicator catalog (catalog/indicators.json); the remaining keys are that type's parameters.",
+      "properties": {
+        "type": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" },
+        "timeframe": { "$ref": "common.schema.json#/$defs/timeframe", "description": "Defaults to the artifact's primary timeframe." },
+        "barPolicy": {
+          "type": "string",
+          "enum": ["CLOSED", "LIVE"],
+          "default": "CLOSED",
+          "description": "For an indicator on a higher timeframe than the primary one: CLOSED uses only completed higher-timeframe bars; LIVE uses the still-forming bar. LIVE on a higher timeframe is look-ahead in a backtest and is rejected by rule AS003."
+        },
+        "in": { "$ref": "#/$defs/operand" },
+        "left": { "$ref": "#/$defs/operand" },
+        "right": { "$ref": "#/$defs/operand" }
+      },
+      "additionalProperties": true
+    },
+
+    "operand": {
+      "description": "Something that yields a number series. Constants are written {\"const\": 0}; a bare number is not an operand (the reference runtime would compile it to nothing).",
+      "oneOf": [
+        {
+          "type": "object", "required": ["ind"], "additionalProperties": false,
+          "properties": { "ind": { "type": "string", "minLength": 1 } }
+        },
+        {
+          "type": "object", "required": ["const"], "additionalProperties": false,
+          "properties": { "const": { "type": "number" } }
+        },
+        { "$ref": "common.schema.json#/$defs/paramRef" },
+        {
+          "type": "object", "required": ["op", "left"], "additionalProperties": false,
+          "description": "Inline arithmetic. ABS is unary (no right).",
+          "properties": {
+            "op": { "enum": ["ADD", "SUB", "MUL", "DIV", "ABS", "MAX", "MIN"] },
+            "left": { "$ref": "#/$defs/operand" },
+            "right": { "$ref": "#/$defs/operand" }
+          }
+        },
+        {
+          "type": "object", "required": ["op", "rule"], "additionalProperties": false,
+          "description": "COUNT = how many of the last N bars satisfied rule; BARS_SINCE = bars since rule last held.",
+          "properties": {
+            "op": { "enum": ["COUNT", "BARS_SINCE"] },
+            "rule": { "$ref": "#/$defs/rule" },
+            "bars": { "$ref": "common.schema.json#/$defs/number" }
+          }
+        }
+      ]
+    },
+
+    "rule": {
+      "type": "object",
+      "required": ["type"],
+      "description": "A boolean node. Comparison nodes take operands; logical nodes take rules.",
+      "properties": {
+        "type": {
+          "enum": [
+            "AND", "OR", "NOT",
+            "GT", "GTE", "LT", "LTE", "EQ", "NEQ", "CROSS_UP", "CROSS_DOWN",
+            "HOLD_FOR", "WITHIN", "SEQUENCE", "DAY_LATCH",
+            "TOUCH", "BREAK", "RECLAIM", "RETEST", "HOLD",
+            "VOL_BREAK", "MOM_BREAK", "GAP_UP", "GAP_DOWN"
+          ]
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "enum": ["AND", "OR"] } } },
+          "then": {
+            "required": ["left", "right"],
+            "properties": { "left": { "$ref": "#/$defs/rule" }, "right": { "$ref": "#/$defs/rule" } }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "enum": ["NOT", "DAY_LATCH"] } } },
+          "then": { "required": ["rule"], "properties": { "rule": { "$ref": "#/$defs/rule" } } }
+        },
+        {
+          "if": { "properties": { "type": { "enum": ["GT", "GTE", "LT", "LTE", "EQ", "NEQ", "CROSS_UP", "CROSS_DOWN"] } } },
+          "then": {
+            "required": ["left", "right"],
+            "properties": { "left": { "$ref": "#/$defs/operand" }, "right": { "$ref": "#/$defs/operand" } }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "enum": ["HOLD_FOR", "WITHIN"] } } },
+          "then": {
+            "required": ["rule"],
+            "description": "HOLD_FOR: rule held on each of the last N bars. WITHIN: rule held on at least one of the last N bars. bars defaults to 3.",
+            "properties": { "rule": { "$ref": "#/$defs/rule" }, "bars": { "$ref": "common.schema.json#/$defs/number" } }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "SEQUENCE" } } },
+          "then": {
+            "required": ["first", "then"],
+            "description": "'then' holds now, and 'first' held within the preceding N bars.",
+            "properties": {
+              "first": { "$ref": "#/$defs/rule" },
+              "then": { "$ref": "#/$defs/rule" },
+              "bars": { "$ref": "common.schema.json#/$defs/number" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "enum": ["TOUCH", "BREAK", "RECLAIM", "RETEST", "HOLD"] } } },
+          "then": {
+            "required": ["level"],
+            "description": "Price-vs-level events. level is any operand (a support line, a moving average, a pivot).",
+            "properties": {
+              "level": { "$ref": "#/$defs/operand" },
+              "direction": { "enum": ["UP", "DOWN"] },
+              "bars": { "$ref": "common.schema.json#/$defs/number" },
+              "tolerancePct": { "$ref": "common.schema.json#/$defs/number" },
+              "price": { "enum": ["CLOSE", "HIGH", "LOW"] },
+              "minVolumeRatio": { "$ref": "common.schema.json#/$defs/number" },
+              "maxVolumeRatio": { "$ref": "common.schema.json#/$defs/number" },
+              "volumeBaseline": { "enum": ["PRIOR_BARS", "SAME_TIME"] },
+              "volumeBars": { "$ref": "common.schema.json#/$defs/number" },
+              "volumeDays": { "$ref": "common.schema.json#/$defs/number" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "VOL_BREAK" } } },
+          "then": {
+            "required": ["price", "atr", "multiplier"],
+            "properties": {
+              "price": { "$ref": "#/$defs/operand" },
+              "atr": { "$ref": "#/$defs/operand" },
+              "multiplier": { "$ref": "common.schema.json#/$defs/number" },
+              "period": { "$ref": "common.schema.json#/$defs/number" },
+              "direction": { "enum": ["UP", "DOWN"] }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "MOM_BREAK" } } },
+          "then": {
+            "required": ["fast", "slow"],
+            "properties": {
+              "fast": { "$ref": "#/$defs/operand" },
+              "slow": { "$ref": "#/$defs/operand" },
+              "atr": { "$ref": "#/$defs/operand" },
+              "price": { "$ref": "#/$defs/operand" },
+              "atrThreshold": { "$ref": "common.schema.json#/$defs/number" }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "enum": ["GAP_UP", "GAP_DOWN"] } } },
+          "then": {
+            "required": ["ind", "threshold"],
+            "properties": {
+              "ind": { "$ref": "#/$defs/operand" },
+              "threshold": { "$ref": "common.schema.json#/$defs/number" },
+              "atr": { "$ref": "#/$defs/operand" },
+              "atrMultiplier": { "$ref": "common.schema.json#/$defs/number" }
+            }
+          }
+        }
+      ]
+    },
+
+    "universe": {
+      "type": "object",
+      "required": ["mode"],
+      "additionalProperties": false,
+      "description": "Which instruments the strategy runs on. The three modes are mutually exclusive.",
+      "properties": {
+        "mode": { "enum": ["SYMBOLS", "UNIVERSE", "ALL_MARKET"] },
+        "symbols": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "common.schema.json#/$defs/symbol" } },
+        "universeId": { "type": ["string", "integer"], "description": "A named universe defined in the runtime." }
+      },
+      "allOf": [
+        { "if": { "properties": { "mode": { "const": "SYMBOLS" } } }, "then": { "required": ["symbols"], "not": { "required": ["universeId"] } } },
+        { "if": { "properties": { "mode": { "const": "UNIVERSE" } } }, "then": { "required": ["universeId"], "not": { "required": ["symbols"] } } },
+        { "if": { "properties": { "mode": { "const": "ALL_MARKET" } } }, "then": { "not": { "anyOf": [ { "required": ["symbols"] }, { "required": ["universeId"] } ] } } }
+      ]
+    },
+
+    "factorBinding": {
+      "type": "object",
+      "required": ["factor", "direction"],
+      "additionalProperties": false,
+      "properties": {
+        "factor": { "type": ["string", "integer"], "description": "Factor identifier in the runtime's factor library." },
+        "direction": { "$ref": "common.schema.json#/$defs/direction" },
+        "weight": { "type": "number", "default": 1 },
+        "topN": { "type": "integer", "minimum": 1, "description": "Cross-sectional selection size (FACTOR_ONLY)." }
+      }
+    }
+  }
+}

alphaspec/_data/schema/0.1/common.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openalpha-dev.github.io/alphaspec/schema/0.1/common.schema.json",
+  "title": "AlphaSpec common definitions",
+  "$defs": {
+    "contractVersion": {
+      "const": "0.1",
+      "description": "Contract version. Every document carries it so a runtime can refuse what it does not understand instead of guessing."
+    },
+
+    "marketId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Market identifier, lower snake case (e.g. cn_stock, hk_stock, us_equity, crypto_spot). The registry of known ids lives in docs/MARKETS.md; runtimes may support a subset and must reject ids they do not know.",
+      "examples": ["cn_stock", "cn_etf", "cn_future", "cn_option", "cn_convbond", "hk_stock", "us_equity", "crypto_spot"]
+    },
+
+    "timeframe": {
+      "type": "string",
+      "enum": ["tick", "1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"],
+      "description": "Bar period. Canonical spellings only: '1h' not '60m'. 'tick' means event-driven evaluation on every market-data frame and cannot be bar-backtested."
+    },
+
+    "symbol": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Instrument code as the market spells it. For markets where the venue disambiguates the code (cn_*, hk_stock) the venue suffix is part of the identity: 600000.SH, 00700.HK. A bare code there is a different series, not a shorthand."
+    },
+
+    "number": {
+      "description": "A scalar setting: a literal number, {\"const\": n}, or a reference to a key in dsl.params.",
+      "oneOf": [
+        { "type": "number" },
+        { "type": "object", "required": ["const"], "additionalProperties": false, "properties": { "const": { "type": "number" } } },
+        { "$ref": "#/$defs/paramRef" }
+      ]
+    },
+
+    "paramRef": {
+      "type": "object",
+      "required": ["ref"],
+      "additionalProperties": false,
+      "properties": { "ref": { "type": "string", "minLength": 1 } }
+    },
+
+    "producer": {
+      "type": "object",
+      "required": ["kind", "name"],
+      "additionalProperties": false,
+      "description": "Who produced this document and how. Needed for multiple-testing correction and for diffing iterations.",
+      "properties": {
+        "kind": { "type": "string", "enum": ["HUMAN", "AI_AGENT", "INSTITUTION", "FACTOR_MINER"] },
+        "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Tool, agent or team name with version, e.g. my-agent@0.3.1." },
+        "modelId": { "type": "string", "description": "Model identifier when kind=AI_AGENT." },
+        "searchTrials": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How many candidates were evaluated before this one was submitted. Input to multiple-testing correction (deflated Sharpe). Required for AI_AGENT and FACTOR_MINER. Under-reporting loosens the gate; runtimes should cross-check it against their own call logs."
+        },
+        "parent": { "type": "string", "description": "Identifier of the previous iteration, for diffs." }
+      }
+    },
+
+    "riskProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-strategy risk overrides. Anything omitted inherits the runtime's account-level settings. Percentages are 0-100, notionals are in the instrument's quote currency.",
+      "properties": {
+        "maxOrderQty": { "type": "number", "exclusiveMinimum": 0 },
+        "maxOrderNotional": { "type": "number", "exclusiveMinimum": 0 },
+        "maxDailyOrders": { "type": "integer", "minimum": 1 },
+        "maxDailyNotional": { "type": "number", "exclusiveMinimum": 0 },
+        "maxPositionQtyPerSymbol": { "type": "number", "exclusiveMinimum": 0 },
+        "maxTotalExposurePct": { "type": "number", "minimum": 0, "maximum": 100 },
+        "maxSymbolExposurePct": { "type": "number", "minimum": 0, "maximum": 100 },
+        "maxIndustryExposurePct": { "type": "number", "minimum": 0, "maximum": 100 },
+        "maxThemeExposurePct": { "type": "number", "minimum": 0, "maximum": 100 },
+        "maxIndustryExposurePctMap": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } },
+        "maxThemeExposurePctMap": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 100 } },
+        "maxImpactSlippageBps": { "type": "number", "minimum": 0 },
+        "maxImpactBlockOnInsufficientDepth": { "type": "boolean" },
+        "portfolioMaxDailyNotional": { "type": "number", "exclusiveMinimum": 0 },
+        "optionQuoteMaxAgeSeconds": { "type": "integer", "minimum": 0 },
+        "optionQuoteMaxSpreadBps": { "type": "number", "minimum": 0 },
+        "optionMinQuoteSize": { "type": "number", "minimum": 0 }
+      }
+    },
+
+    "direction": {
+      "type": "string",
+      "enum": ["ASC", "DESC"],
+      "description": "Ranking direction. DESC = higher is better. Required with no default: a flipped direction raises no error, it just loses money for a long time."
+    }
+  }
+}

alphaspec/_data/schema/0.1/evidence.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openalpha-dev.github.io/alphaspec/schema/0.1/evidence.schema.json",
+  "title": "AlphaSpec Execution Evidence",
+  "description": "What actually happened when a strategy ran: rejections, fills, slippage, risk hits, the ledger, and whether the pipeline ran at all. Every number states its caliber, because an unlabeled number is worse than none for an agent consuming it.",
+  "type": "object",
+  "required": ["contractVersion", "kind", "subject", "window", "caliber"],
+  "additionalProperties": false,
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "evidence" },
+
+    "subject": {
+      "type": "object",
+      "required": ["mode"],
+      "additionalProperties": false,
+      "properties": {
+        "strategy": { "type": "string" },
+        "artifact": { "type": "string" },
+        "account": { "type": "string" },
+        "mode": {
+          "enum": ["BACKTEST", "PAPER", "LIVE"],
+          "description": "The mode the orders actually ran in, derived from the account that holds the positions, not from configuration."
+        }
+      }
+    },
+
+    "window": {
+      "type": "object",
+      "required": ["from", "to"],
+      "additionalProperties": false,
+      "properties": {
+        "from": { "type": "string", "format": "date" },
+        "to": { "type": "string", "format": "date" },
+        "timezone": { "type": "string", "description": "IANA zone of the market, e.g. Asia/Shanghai, America/New_York." }
+      }
+    },
+
+    "caliber": {
+      "type": "object",
+      "required": ["slippageBasis", "feeIncluded", "volumeUnit", "currency"],
+      "additionalProperties": false,
+      "properties": {
+        "slippageBasis": { "enum": ["VS_SIGNAL_PRICE", "VS_ARRIVAL_PRICE", "VS_VWAP"] },
+        "feeIncluded": { "type": "boolean", "description": "Whether pnl and average prices include fees." },
+        "priceSource": { "enum": ["TICK", "BAR_1M", "BAR_1D", "SNAPSHOT"] },
+        "volumeUnit": {
+          "enum": ["SHARE", "LOT", "CONTRACT"],
+          "description": "Quantities are in this unit. Derivatives quantities are contracts; notional = qty x price x multiplier."
+        },
+        "multiplierApplied": { "type": "boolean", "description": "Whether notionals and pnl already include the contract multiplier." },
+        "currency": { "type": "string", "pattern": "^[A-Z]{3,5}$", "description": "Currency of every monetary field in this document." }
+      }
+    },
+
+    "rejects": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["category", "code", "count"],
+        "additionalProperties": false,
+        "properties": {
+          "category": { "enum": ["STRATEGY", "UNIVERSE", "RISK", "BROKER", "MARKET_DATA"] },
+          "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "Runtime-specific reason code. Runtimes publish their code list." },
+          "count": { "type": "integer", "minimum": 0 },
+          "message": { "type": "string", "description": "Original message, not normalized." },
+          "hint": { "type": "string", "description": "What to change." }
+        }
+      }
+    },
+
+    "executionQuality": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "orders": { "type": "integer", "minimum": 0 },
+        "fillRatePct": { "type": "number" },
+        "rejectRatePct": { "type": "number" },
+        "avgSlippageBps": { "type": "number" },
+        "p95SlippageBps": { "type": "number" },
+        "paperVsLiveDiffBps": { "type": "number", "description": "Average gap between paper and live fills for the same signals." }
+      }
+    },
+
+    "targetDeviation": {
+      "type": "array",
+      "description": "For score/weights submissions: where the actual portfolio differs from the target and why.",
+      "items": {
+        "type": "object",
+        "required": ["symbol", "reason"],
+        "additionalProperties": false,
+        "properties": {
+          "symbol": { "$ref": "common.schema.json#/$defs/symbol" },
+          "targetWeight": { "type": "number" },
+          "actualWeight": { "type": "number" },
+          "reason": {
+            "enum": ["LOT_ROUNDING", "PRICE_LIMIT", "SETTLEMENT_RULE", "RISK_REJECT", "MIN_FEE_FLOOR", "NOT_IN_UNIVERSE", "NO_PRICE", "HALTED", "OTHER"]
+          }
+        }
+      }
+    },
+
+    "riskHits": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code", "count", "blocking"],
+        "additionalProperties": false,
+        "properties": {
+          "code": { "type": "string" },
+          "count": { "type": "integer", "minimum": 0 },
+          "blocking": { "type": "boolean" }
+        }
+      }
+    },
+
+    "ledger": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["ts", "symbol", "side", "qty", "price"],
+        "additionalProperties": false,
+        "properties": {
+          "ts": { "type": "string", "format": "date-time" },
+          "symbol": { "$ref": "common.schema.json#/$defs/symbol" },
+          "side": { "enum": ["BUY", "SELL"] },
+          "qty": { "type": "number" },
+          "price": { "type": "number" },
+          "fee": { "type": "number" },
+          "realizedPnl": { "type": "number" },
+          "trigger": { "type": "string", "description": "Why the order was placed: ENTRY, EXIT, STOP_LOSS, TAKE_PROFIT, REBALANCE ..." }
+        }
+      }
+    },
+
+    "pipeline": {
+      "type": "array",
+      "description": "Answers 'did it run when it should have', not only 'was the output right'.",
+      "items": {
+        "type": "object",
+        "required": ["stage", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "stage": { "type": "string" },
+          "status": { "enum": ["OK", "DEGRADED", "ABSENT", "FAILED"] },
+          "at": { "type": "string", "format": "date-time" },
+          "violations": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}

alphaspec/_data/schema/0.1/gate-result.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openalpha-dev.github.io/alphaspec/schema/0.1/gate-result.schema.json",
+  "title": "AlphaSpec Gate Result",
+  "description": "What a runtime returns after judging a submitted artifact or score series. Produced by the runtime, never by the submitter.",
+  "type": "object",
+  "required": ["contractVersion", "kind", "passed", "computedBy", "checks"],
+  "additionalProperties": false,
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "gate-result" },
+    "subject": { "type": "string", "description": "Identifier of the judged artifact or score series." },
+    "passed": { "type": "boolean" },
+    "computedBy": {
+      "enum": ["PLATFORM", "SELF_REPORTED"],
+      "description": "PLATFORM: performance figures were recomputed by the runtime. SELF_REPORTED: they came from the submitter. Public rankings must accept PLATFORM only."
+    },
+    "sample": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "inSampleFrom": { "type": "string", "format": "date" },
+        "inSampleTo": { "type": "string", "format": "date" },
+        "outOfSampleFrom": { "type": "string", "format": "date", "description": "Chosen by the runtime and not visible at submission time." },
+        "outOfSampleTo": { "type": "string", "format": "date" }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "description": "One entry per criterion, so a failure can be diffed and explained, not just reported.",
+      "items": {
+        "type": "object",
+        "required": ["code", "passed"],
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "enum": [
+              "GATE_MIN_RETURN", "GATE_MAX_DRAWDOWN", "GATE_MIN_SHARPE",
+              "GATE_OUT_OF_SAMPLE", "GATE_MULTIPLE_TESTING", "GATE_LOOKAHEAD",
+              "GATE_COST_SENSITIVITY", "GATE_CAPACITY", "GATE_MARKETABILITY"
+            ]
+          },
+          "metric": {
+            "type": "string",
+            "description": "What `actual` and `threshold` measure, so a reader never infers it from the code. One check can switch measures (out-of-sample is judged on excess return when the runtime has a benchmark index, on Sharpe when it has not). Values used by the reference runtime: totalReturn, maxDrawdown, sharpe, excessReturnVsIndex, deflatedSharpeProbability, structural. Returns and drawdowns are fractions (0.05 = 5%)."
+          },
+          "passed": { "type": "boolean" },
+          "actual": { "type": ["number", "string", "null"] },
+          "threshold": { "type": ["number", "string", "null"] },
+          "hint": { "type": "string", "description": "What to change to pass, in plain language." }
+        }
+      }
+    }
+  }
+}

alphaspec/_data/schema/0.1/score.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openalpha-dev.github.io/alphaspec/schema/0.1/score.schema.json",
+  "title": "AlphaSpec Score Submission (L1)",
+  "description": "Cross-sectional output of any model (pandas, LightGBM, PyTorch, an LLM pipeline) handed to an execution runtime. You keep your research stack; the runtime handles sizing, rebalancing, risk, execution and the ledger. Carries either 'scores' (the runtime ranks and weights) or 'weights' (portfolio construction already done).",
+  "type": "object",
+  "required": ["contractVersion", "kind", "asOf", "market", "scoreName", "producer"],
+  "additionalProperties": false,
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "score" },
+    "asOf": {
+      "type": "string",
+      "format": "date",
+      "description": "The last trading day whose information was used, in the market's local calendar. A score with asOf=T may use T's close and nothing later, and is executed no earlier than the next session. This is where look-ahead enters if anywhere."
+    },
+    "market": { "$ref": "common.schema.json#/$defs/marketId" },
+    "scoreName": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Model or signal name. Submissions with the same scoreName form one time series." },
+    "direction": { "$ref": "common.schema.json#/$defs/direction" },
+
+    "scores": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["symbol", "score"],
+        "additionalProperties": false,
+        "properties": {
+          "symbol": { "$ref": "common.schema.json#/$defs/symbol" },
+          "score": {
+            "type": ["number", "null"],
+            "description": "null = no valid score today (halted, missing data). Never use 0 for 'unknown': 0 is a real rank position."
+          }
+        }
+      }
+    },
+
+    "weights": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Target portfolio weights in [0,1]. Sum must be <= 1; the remainder is cash.",
+      "items": {
+        "type": "object",
+        "required": ["symbol", "weight"],
+        "additionalProperties": false,
+        "properties": {
+          "symbol": { "$ref": "common.schema.json#/$defs/symbol" },
+          "weight": { "type": "number", "minimum": 0, "maximum": 1 }
+        }
+      }
+    },
+
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional portfolio-construction settings. Omitted fields use the runtime defaults.",
+      "properties": {
+        "topN": { "type": "integer", "minimum": 1 },
+        "weighting": { "enum": ["EQUAL", "SCORE_PROPORTIONAL", "INV_VOL"] },
+        "universePolicy": {
+          "enum": ["SUBMITTED", "INTERSECT_UNIVERSE"],
+          "description": "SUBMITTED: trade only from the submitted symbols. INTERSECT_UNIVERSE: intersect with the runtime-side universe; symbols dropped by the intersection must be reported back as evidence, never silently discarded."
+        },
+        "riskProfile": { "$ref": "common.schema.json#/$defs/riskProfile" }
+      }
+    },
+
+    "producer": { "$ref": "common.schema.json#/$defs/producer" }
+  },
+
+  "oneOf": [
+    { "required": ["scores", "direction"], "not": { "required": ["weights"] } },
+    {
+      "required": ["weights"],
+      "not": { "anyOf": [ { "required": ["scores"] } ] },
+      "properties": { "execution": { "properties": { "topN": false, "weighting": false } } }
+    }
+  ]
+}