@senpi/runtime 3.0.9-dev.20260710204324 → 3.0.9-dev.feat-strategy-compos.20260716013009

package/dist/composer/registry/models.py

@@ -0,0 +1,331 @@
+"""models — pydantic v2 node-definition models; the registry's typed vocabulary (D4, D8).
+
+A ``NodeDef`` is a single declaration in the registry: a name, a ``kind``, typed
+input/output ports drawn from a small closed :class:`PortType` vocabulary, a typed and
+bounded parameter schema, a docstring, a one-line YAML example, and a cost note. These
+models are the ONLY source of truth (D4): the graph JSON Schema, the catalog index, the
+per-node describe text, the validator's type rules, and (later) the compiler's emission
+all derive from ``NODES``. Nothing downstream is hand-maintained, so nothing can drift.
+
+Invalid declarations fail **at model construction** (this is the slice-1 oracle), not at
+use: an unknown port type, duplicate port names, a stateful node missing its state
+in/out pair, a numeric default outside its bounds, or an example ``with:`` key naming a
+param the node does not declare all raise ``ValidationError`` when ``NODES`` is built at
+import time.
+
+Port-type vocabulary (kept deliberately small; every type is justified by a real corpus
+usage — see the per-member comments):
+
+    asset_list   — a set of tradeable assets / instruments.
+    candles      — multi-interval OHLCV candle data keyed by asset.
+    feature_map  — a per-asset computed feature (float / bool / direction), keyed by asset.
+    score_map    — a per-asset {score, reasons[], ...} record.
+    signals      — the emitted signal-envelope list; the ``scan()`` return value.
+    scalar       — a single account-level numeric value (equity).
+    state        — the ``ctx.state`` carrier; stateful nodes only (D2).
+    record_list  — an ORDERED list of typed dict records with NO asset-keying invariant
+                   (strategy metadata / open orders / closed-trade rows). Distinct from
+                   ``asset_list`` (whose entries are coin symbols every consumer relies on,
+                   e.g. ``held_asset_exclusion``): a ``record_list`` is generic tabular data
+                   whose only intended consumer is a ``kind: pure_fn`` node that declares a
+                   ``record_list`` input and reads the record fields itself.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal, Optional, Union
+
+import yaml
+from pydantic import BaseModel, ConfigDict, model_validator
+
+SCHEMA_VERSION = 1
+
+
+class PortType(str, Enum):
+    """Closed vocabulary of data types that can flow along an edge (D1 typed ports).
+
+    Small by design: every member cites the corpus strategy that forces its existence.
+    An edge port declared with any value outside this enum fails at construction.
+    """
+
+    # stag's fixed whitelist BTC/ETH/SOL/HYPE; magpie's discovered IPOP universe;
+    # the held-position set from clearinghouse_state (all five packages exclude held).
+    asset_list = "asset_list"
+    # candles_fetch output; consumed by every indicator (stag 4h, hawk 1h+4h, bison 15m/1h/4h).
+    candles = "candles"
+    # per-asset indicator outputs (sma/pct_change/trend_structure/rsi/...), sm_lean tilt,
+    # own_return_24h — every indicator in stag/hawk/bison emits a per-asset feature.
+    feature_map = "feature_map"
+    # scorer output: weighted-sum score + reasons[] per asset (stag/hawk/bison/thesis-fund).
+    score_map = "score_map"
+    # signal_envelope output — the scan() list[dict] return (all five packages).
+    signals = "signals"
+    # clearinghouse_state dual-DEX max() account equity (stag/hawk/bison read it).
+    scalar = "scalar"
+    # ctx.state carrier owned by the stateful ttl_dedup_state node's in/out pair (D2);
+    # the dedup pattern is universal across the corpus.
+    state = "state"
+    # list of non-asset-keyed dict records (strategy_list / open_orders / trader_history
+    # rows) — the world-coverage read surface (batch C) exposes tabular reads that are not
+    # asset-keyed; a pure_fn declaring a record_list input is the intended consumer.
+    record_list = "record_list"
+
+
+class NodeKind(str, Enum):
+    """The node kinds (D2). ``pure_fn`` is reserved for slice 4 and has no slice-1 entry.
+
+    ``stateful`` also carries a cycle-detection semantic (D4, moved off the validator in
+    slice 2.5): a stateful node's outputs carry PRIOR-tick data (the ctx.state boundary),
+    so edges leaving a stateful node's outputs do not count as forward dependencies when
+    the validator's DFS looks for cycles — that is what lets the universal ttl-dedup
+    feedback loop (``recent`` -> filter -> ... -> ``ttl_dedup_state`` -> ``recent``) wire up
+    without tripping CMP035. This is keyed off ``kind``, not a per-port flag, because it is
+    a property of the whole node's tick semantics, not of any one port.
+    """
+
+    source = "source"
+    indicator = "indicator"
+    filter = "filter"
+    scorer = "scorer"
+    ranker = "ranker"
+    emitter = "emitter"
+    stateful = "stateful"
+    pure_fn = "pure_fn"
+
+
+# Closed param-type vocabulary. Scalars + a string list (whitelists/intervals) + a
+# str->float map (every scorer in the corpus is a weighted sum, so weight/tier maps are
+# a first-class shape, not free-form JSON).
+ParamType = Literal["int", "float", "str", "bool", "list[str]", "map_str_float"]
+
+ParamDefault = Union[int, float, str, bool, tuple, dict, None]
+
+
+class Port(BaseModel):
+    """A named, typed input or output port on a node (D1).
+
+    ``required`` and ``merge`` are INPUT-port semantics (D4): the registry is the single
+    source of truth for both, so the validator reads them off the port rather than
+    special-casing port names or types. ``NodeDef._check_port_flags`` rejects either flag
+    set to a non-default value on an OUTPUT port, since neither concept applies there.
+
+        required — False marks an input that may be left unwired: the strategy's
+            configured universe / preset supplies it at runtime instead of a graph edge
+            (e.g. an ``asset_list`` input named ``assets``/``candidates``, the
+            ``signal_envelope.equity`` sizing input, or a stateful node's ``state`` input,
+            which is wired by the runtime tick boundary — ctx.state — not a graph edge).
+            Defaults to True (unwired = CMP036).
+        merge — True marks an input that legally accepts more than one writer (a
+            key-union merge across writers), rather than the default single-writer rule
+            (a second writer = CMP037). Currently only the scorer/gate ``features``
+            (feature_map) inputs, since every indicator in the corpus emits one feature
+            and scorers consume the merged record. Defaults to False.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    type: PortType
+    doc: str
+    required: bool = True
+    merge: bool = False
+
+    @model_validator(mode="after")
+    def _check(self) -> "Port":
+        if not self.name.strip():
+            raise ValueError("port name must be non-empty")
+        if not self.doc.strip():
+            raise ValueError(f"port {self.name!r} must have a doc string")
+        return self
+
+
+class Param(BaseModel):
+    """A typed, bounded parameter with an optional corpus-median default.
+
+    A ``None`` default means the param is required in the graph document; any other value
+    makes it optional and is emitted into the JSON Schema as the ``default``.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    type: ParamType
+    doc: str
+    default: ParamDefault = None
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+    choices: Optional[tuple[str, ...]] = None
+
+    @model_validator(mode="after")
+    def _check(self) -> "Param":
+        if not self.name.strip():
+            raise ValueError("param name must be non-empty")
+        if not self.doc.strip():
+            raise ValueError(f"param {self.name!r} must have a doc string")
+
+        numeric = self.type in ("int", "float")
+        if not numeric and (self.minimum is not None or self.maximum is not None):
+            raise ValueError(
+                f"param {self.name!r}: bounds only valid on int/float, not {self.type}"
+            )
+        if (
+            self.minimum is not None
+            and self.maximum is not None
+            and self.minimum > self.maximum
+        ):
+            raise ValueError(
+                f"param {self.name!r}: minimum {self.minimum} > maximum {self.maximum}"
+            )
+        if self.choices is not None and self.type != "str":
+            raise ValueError(f"param {self.name!r}: choices only valid on str params")
+
+        if self.default is not None:
+            self._check_default_type()
+            if numeric:
+                d = float(self.default)  # type: ignore[arg-type]
+                if self.minimum is not None and d < self.minimum:
+                    raise ValueError(
+                        f"param {self.name!r}: default {self.default} < minimum {self.minimum}"
+                    )
+                if self.maximum is not None and d > self.maximum:
+                    raise ValueError(
+                        f"param {self.name!r}: default {self.default} > maximum {self.maximum}"
+                    )
+            if self.choices is not None and self.default not in self.choices:
+                raise ValueError(
+                    f"param {self.name!r}: default {self.default!r} not in choices {self.choices}"
+                )
+        return self
+
+    def _check_default_type(self) -> None:
+        d = self.default
+        is_bool = type(d) is bool
+        if self.type == "int":
+            if not (isinstance(d, int) and not is_bool):
+                raise ValueError(f"param {self.name!r}: default must be int, got {d!r}")
+        elif self.type == "float":
+            if is_bool or not isinstance(d, (int, float)):
+                raise ValueError(f"param {self.name!r}: default must be a number, got {d!r}")
+        elif self.type == "str":
+            if not isinstance(d, str):
+                raise ValueError(f"param {self.name!r}: default must be str, got {d!r}")
+        elif self.type == "bool":
+            if not is_bool:
+                raise ValueError(f"param {self.name!r}: default must be bool, got {d!r}")
+        elif self.type == "list[str]":
+            if not (isinstance(d, tuple) and all(isinstance(x, str) for x in d)):
+                raise ValueError(
+                    f"param {self.name!r}: default must be a tuple[str, ...], got {d!r}"
+                )
+        elif self.type == "map_str_float":
+            ok = isinstance(d, dict) and all(
+                isinstance(k, str) and isinstance(v, (int, float)) and type(v) is not bool
+                for k, v in d.items()
+            )
+            if not ok:
+                raise ValueError(
+                    f"param {self.name!r}: default must be a dict[str, float], got {d!r}"
+                )
+
+
+class NodeDef(BaseModel):
+    """A single node declaration — the atom of the registry."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    kind: NodeKind
+    summary: str  # one-liner for the catalog index
+    doc: str  # full description for `composer describe`
+    inputs: tuple[Port, ...] = ()
+    outputs: tuple[Port, ...] = ()
+    params: tuple[Param, ...] = ()
+    example: str  # a single-node YAML snippet
+    cost: str  # cost note (MCP calls / pure compute)
+
+    @model_validator(mode="after")
+    def _check(self) -> "NodeDef":
+        if not self.name.strip():
+            raise ValueError("node name must be non-empty")
+        for label, text in (("summary", self.summary), ("doc", self.doc), ("cost", self.cost)):
+            if not text.strip():
+                raise ValueError(f"node {self.name!r}: {label} must be non-empty")
+
+        self._check_unique(self.inputs, "input port")
+        self._check_unique(self.outputs, "output port")
+        self._check_unique(self.params, "param")
+
+        self._check_state_ports()
+        self._check_port_flags()
+        self._check_example()
+        return self
+
+    def _check_unique(self, items: tuple, label: str) -> None:
+        seen: set[str] = set()
+        for item in items:
+            if item.name in seen:
+                raise ValueError(f"node {self.name!r}: duplicate {label} {item.name!r}")
+            seen.add(item.name)
+
+    def _check_state_ports(self) -> None:
+        state_ins = [p for p in self.inputs if p.type == PortType.state]
+        state_outs = [p for p in self.outputs if p.type == PortType.state]
+        if self.kind == NodeKind.stateful:
+            # D2: a stateful node declares exactly one state in/out port pair.
+            if len(state_ins) != 1 or len(state_outs) != 1:
+                raise ValueError(
+                    f"node {self.name!r}: a stateful node must declare exactly one "
+                    f"state input and one state output (the ctx.state in/out pair, D2); "
+                    f"got {len(state_ins)} in / {len(state_outs)} out"
+                )
+        else:
+            if state_ins or state_outs:
+                raise ValueError(
+                    f"node {self.name!r}: only kind=stateful may use the 'state' port "
+                    f"type (D2); {self.kind.value} node declares a state port"
+                )
+
+    def _check_port_flags(self) -> None:
+        # required/merge are input-port concepts (see Port docstring); an output setting
+        # either to its non-default value is a registry authoring error, not a real state.
+        for port in self.outputs:
+            if not port.required:
+                raise ValueError(
+                    f"node {self.name!r}: output port {port.name!r} cannot set "
+                    f"required=False (required only applies to input ports)"
+                )
+            if port.merge:
+                raise ValueError(
+                    f"node {self.name!r}: output port {port.name!r} cannot set "
+                    f"merge=True (merge only applies to input ports)"
+                )
+
+    def _check_example(self) -> None:
+        try:
+            parsed = yaml.safe_load(self.example)
+        except yaml.YAMLError as exc:  # pragma: no cover - defensive
+            raise ValueError(f"node {self.name!r}: example is not valid YAML: {exc}")
+        if not isinstance(parsed, dict):
+            raise ValueError(f"node {self.name!r}: example must be a single YAML mapping")
+        if parsed.get("node") != self.name:
+            raise ValueError(
+                f"node {self.name!r}: example 'node:' must equal {self.name!r}, "
+                f"got {parsed.get('node')!r}"
+            )
+        param_names = {p.name for p in self.params}
+        with_block = parsed.get("with", {}) or {}
+        if not isinstance(with_block, dict):
+            raise ValueError(f"node {self.name!r}: example 'with:' must be a mapping")
+        for key in with_block:
+            if key not in param_names:
+                raise ValueError(
+                    f"node {self.name!r}: example references unknown param {key!r} "
+                    f"(declared params: {sorted(param_names)})"
+                )
+        extra = set(parsed) - {"node", "with", "id"}
+        if extra:
+            raise ValueError(
+                f"node {self.name!r}: example has unexpected keys {sorted(extra)} "
+                f"(allowed: id, node, with)"
+            )