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

package/dist/composer/authoring/archetypes/skeleton.py

@@ -0,0 +1,76 @@
+"""skeleton — the off-map fallback (D7 step 5): no matching archetype -> a MINIMAL valid
+graph (universe -> fetch -> score slot -> emit) so the anchor property holds even for a
+strategy shape the ~10 archetypes do not cover.
+
+It is deliberately the smallest graph that validates and compiles: one candle fetch over
+the universe, one trend indicator, a hard-gates scorer as the single TODO edge slot, and
+single-best emission. The model grows it from here (full edit rights, D7) — the skeleton
+only guarantees a valid starting point exists.
+"""
+
+from __future__ import annotations
+
+from ..answers import Answers
+from ..builder import GraphBuilder
+from . import _common
+
+BANNER = [
+    "minimal skeleton — machine-generated anchor (composer new).",
+    "",
+    "No archetype matched, so this is the smallest VALID graph: universe -> fetch -> score",
+    "slot -> emit. It validates and compiles as-is; grow it toward your strategy by editing",
+    "the scorer slot and adding nodes (`composer catalog` / `composer describe <node>`).",
+]
+
+
+def build(answers: Answers) -> GraphBuilder:
+    b = GraphBuilder()
+    iv = answers.intervals[0] if answers.intervals else "4h"
+    whitelist = list(answers.universe.whitelist) or ["BTC"]
+
+    b.add("candles", "candles_fetch", {"whitelist": whitelist, "intervals": list(answers.intervals)},
+          header=("universe -> fetch.",))
+    b.add("trend", "trend_structure", {"lookback": 6, "interval": iv},
+          header=("one feature to score on.",))
+
+    # F1 — ADDITIONAL registry indicators requested by the answers (empty => no-op, byte-identical).
+    extra = _common.add_indicator_nodes(b, answers.indicators)
+
+    # F1 — answers.scoring overrides else the skeleton default (weights only; no hard gate).
+    required_gates, weights, min_score = _common.resolve_scoring(
+        answers,
+        default_required=(),
+        default_weights={"trend": 1.0},
+        default_min=0,
+        feature_ids=["trend"] + [r.id for r in extra],
+    )
+    # Preserve the skeleton's param ORDER (weights, min_score); required_gates only appears when
+    # the answers ask for a hard gate, so an un-overridden skeleton stays byte-identical.
+    score_params: dict = {}
+    if required_gates:
+        score_params["required_gates"] = required_gates
+    score_params["weights"] = weights
+    score_params["min_score"] = min_score
+    b.add(
+        "score", "hard_gates_all",
+        score_params,
+        header=("scorer — THE EDGE SLOT (see the EDGE block above); edit the weights/gates.",),
+        param_comments={
+            "weights": "TODO(edit): source-node-id -> weight; add features and weight them here.",
+            "min_score": "TODO(edit): minimum score to emit.",
+        },
+        slots=("weights", "min_score"),
+    )
+    b.set_edge_anchor("score")
+    b.add("best", "emit_single_best", {"min_score": 0}, header=("ranker.",))
+    b.add("emit", "signal_envelope",
+          {"margin_pct": answers.risk.margin_pct, "leverage": answers.risk.leverage},
+          header=("emitter.",))
+
+    b.connect("candles", "candles", "trend", "candles", section="fetch -> feature")
+    _common.wire_indicator_inputs(b, extra, candles_id="candles")
+    b.connect("trend", "direction", "score", "features", section="feature -> score -> rank -> emit")
+    _common.wire_indicator_features(b, extra, scorer_id="score")
+    b.connect("score", "scores", "best", "scores")
+    b.connect("best", "selected", "emit", "selected")
+    return b

package/dist/composer/authoring/archetypes/thesis_fund.py

@@ -0,0 +1,103 @@
+"""thesis_fund — the thesis-fund shape (D7 step 2): a fixed long/short basket whose direction
+is FIXED per leg, scored for CONFIRMATION by a pure_fn, ranked, and capped to open slots.
+
+This is the archetype that ranks a pool against open slots rather than emitting a single
+best (recon). Direction is not derived — long_basket names are LONG, short_basket names are
+SHORT — so the scorer is a pure_fn (D2 kind 2) with a WORKING DEFAULT body (thesis-fund's
+score_thesis) as the TODO slot. Mechanically bound: baskets -> candles whitelist + the
+pure_fn's basket params, max_positions -> the rank-pool-cap ranker, intervals/ttl/risk as
+usual. The lay-thesis -> basket mapping happens in elicitation (the answer), not here.
+"""
+
+from __future__ import annotations
+
+from ..answers import Answers
+from ..builder import GraphBuilder
+from . import _common
+
+BANNER = [
+    "thesis_fund strategy — machine-generated anchor (composer new).",
+    "",
+    "A fixed long/short basket: each name's direction is FIXED by its leg (long -> LONG,",
+    "short -> SHORT), and a pure_fn scores how strongly the tape CONFIRMS that side (drops a",
+    "name whose 4h structure opposes its leg). Confirming names are ranked and the top",
+    "(max_positions - held) fill the open slots. Edit ONLY the pure_fn body (the EDGE slot).",
+]
+
+_MIN_SCORE = 4.0
+
+
+def build(answers: Answers) -> GraphBuilder:
+    b = GraphBuilder()
+    u = answers.universe
+    basket = list(u.long_basket) + list(u.short_basket)
+
+    b.add("account", "clearinghouse_state", header=("sources.",))
+    b.add("dedup_state", "ttl_dedup_state", {"ttl_seconds": answers.ttl_seconds})
+    b.add("board", "instrument_list", header=("live venue board for live-instrument validation.",))
+
+    b.add("exclude_held", "held_asset_exclusion",
+          header=("universe narrowing: held-exclusion, recent dedup, live-board validation.",))
+    b.add("exclude_recent", "recent_signal_ttl_dedup")
+    b.add("validate_live", "live_instrument_validation")
+
+    b.add("candles", "candles_fetch",
+          {"whitelist": basket, "intervals": list(answers.intervals), "include_asset_context": True},
+          header=("candle reads over the validated basket (asset_context for the 24h return).",))
+
+    b.add("ret24", "own_return_24h", header=("features feeding the confirmation scorer.",))
+    b.add("trend4h", "trend_structure", {"lookback": 6, "interval": "4h"})
+    b.add("trend1h", "trend_structure", {"lookback": 6, "interval": "1h"})
+    b.add("rsi1h", "rsi", {"period": 4, "interval": "1h"})
+
+    b.add_pure_fn(
+        "score",
+        inputs=(
+            {"name": "trend4h", "type": "feature_map", "doc": "4h trend structure (BULLISH/BEARISH/NEUTRAL)."},
+            {"name": "trend1h", "type": "feature_map", "doc": "1h trend structure (BULLISH/BEARISH/NEUTRAL)."},
+            {"name": "rsi", "type": "feature_map", "doc": "Trailing-window RSI [0,100]."},
+            {"name": "own24h", "type": "feature_map", "doc": "24h percent return (markPx vs prevDayPx)."},
+        ),
+        outputs=({"name": "scores", "type": "score_map", "doc": "Per-asset {score, direction, reasons[]} for confirming names."},),
+        params=(
+            {"name": "long_basket", "type": "list[str]", "default": list(u.long_basket) or ["BTC"], "doc": "Names whose fixed thesis direction is LONG."},
+            {"name": "short_basket", "type": "list[str]", "default": list(u.short_basket) or ["ETH"], "doc": "Names whose fixed thesis direction is SHORT."},
+            {"name": "min_score", "type": "float", "default": _MIN_SCORE, "doc": "Minimum confirmation score to keep a name."},
+        ),
+        fn=_common.THESIS_FN,
+        tests=_common.thesis_tests(list(u.long_basket), list(u.short_basket), _MIN_SCORE),
+        header=("pure_fn confirmation scorer — THE EDGE SLOT (edit the body; see the EDGE block above).",),
+    )
+    b.set_edge_anchor("score")
+
+    b.add("rank", "rank_pool_cap_to_open_slots",
+          {"max_slots": answers.max_positions, "min_score": 0},
+          header=(f"ranker: rank the confirming pool, fill up to {answers.max_positions} open slots.",))
+    b.add("emit", "signal_envelope",
+          {"margin_pct": answers.risk.margin_pct, "leverage": answers.risk.leverage},
+          header=("emitter.",))
+
+    # universe narrowing chain
+    b.connect("account", "held", "exclude_held", "held", section="universe narrowing chain")
+    b.connect("exclude_held", "kept", "exclude_recent", "candidates")
+    b.connect("dedup_state", "recent", "exclude_recent", "recent")
+    b.connect("exclude_recent", "kept", "validate_live", "candidates")
+    b.connect("board", "instruments", "validate_live", "instruments")
+    b.connect("validate_live", "kept", "candles", "assets")
+    # candles fan out to the confirmation features
+    b.connect("candles", "candles", "ret24", "candles", section="candles fan out to the confirmation features")
+    b.connect("candles", "candles", "trend4h", "candles")
+    b.connect("candles", "candles", "trend1h", "candles")
+    b.connect("candles", "candles", "rsi1h", "candles")
+    # each feature wires into one declared pure_fn input port
+    b.connect("trend4h", "direction", "score", "trend4h", section="features into the confirmation pure_fn")
+    b.connect("trend1h", "direction", "score", "trend1h")
+    b.connect("rsi1h", "rsi", "score", "rsi")
+    b.connect("ret24", "return_24h", "score", "own24h")
+    # score -> rank-pool-cap -> emit
+    b.connect("score", "scores", "rank", "scores", section="score -> rank-pool-cap-to-slots -> emit")
+    b.connect("account", "held", "rank", "held")
+    b.connect("rank", "selected", "emit", "selected")
+    b.connect("account", "equity", "emit", "equity")
+    b.connect("emit", "signals", "dedup_state", "emitted", section="close the dedup loop")
+    return b

package/dist/composer/authoring/archetypes/trend_momentum.py

@@ -0,0 +1,132 @@
+"""trend_momentum — the stag/hawk shape (D7 step 2): fixed universe, fan-out to indicators,
+a hard-gates-plus-weighted-sum scorer, TTL dedup, single-best (or pool-cap) emission.
+
+Mechanically bound from the answers (D7 step 3): universe -> candles whitelist, intervals ->
+candles + indicators, ttl_seconds -> ttl_dedup_state, cardinality -> ranker, risk knobs ->
+emitter. Bespoke slots left TODO-marked WITH WORKING DEFAULTS: the gate list, the weighted-
+sum weights, the score floor, and the smart-money agreement band — the graph validates and
+compiles before any of them is touched.
+"""
+
+from __future__ import annotations
+
+from ..answers import Answers
+from ..builder import GraphBuilder
+from . import _common
+
+BANNER = [
+    "trend_momentum strategy — machine-generated anchor (composer new).",
+    "",
+    "A fixed universe scanned each tick: candles fan out to trend / momentum / volume /",
+    "acceleration indicators whose per-asset features MERGE into a hard-gates + weighted-sum",
+    "scorer, then single-best (or pool-cap) emission with the universal TTL signal-dedup on",
+    "ctx.state. Edit ONLY the TODO(edit) slots on the scorer to move this toward your edge;",
+    "every intermediate state stays valid (run `composer check`).",
+]
+
+
+def build(answers: Answers) -> GraphBuilder:
+    b = GraphBuilder()
+    iv = answers.intervals[0] if answers.intervals else "4h"
+    u = answers.universe
+
+    # F3 — trend_momentum is the FIXED-universe shape (stag/hawk). It never read u.discover, so
+    # a discover=True answer silently emitted `whitelist: []` (an empty universe). Reject LOUDLY
+    # instead: discovery lives in the `classifier` / `breakout` archetypes, which bind the live
+    # instrument board. (Never emit an empty whitelist without a word.)
+    if u.discover:
+        raise _common.GenerationError(
+            "archetype 'trend_momentum' is a FIXED-universe shape and cannot discover a "
+            "universe from the live board. Use archetype 'breakout' (breakout + discovery) or "
+            "'classifier' (discovery classifier) for universe.discover, or set "
+            "universe.whitelist for trend_momentum."
+        )
+
+    b.add("account", "clearinghouse_state", header=("sources.",))
+    b.add("dedup_state", "ttl_dedup_state", {"ttl_seconds": answers.ttl_seconds})
+
+    b.add("exclude_held", "held_asset_exclusion",
+          header=("universe narrowing: held-exclusion then recent-signal dedup.",))
+    b.add("exclude_recent", "recent_signal_ttl_dedup")
+
+    b.add("candles", "candles_fetch",
+          {"whitelist": list(u.whitelist), "intervals": list(answers.intervals)},
+          header=("candle + leaderboard reads over the narrowed universe.",))
+    b.add("lean", "sm_lean", {"agree_threshold": 0.6},
+          param_comments={"agree_threshold": "TODO(edit): smart-money agreement band (stag 0.6, hawk 0.55, bison 0.58)."},
+          slots=("agree_threshold",))
+
+    b.add("trend_sma", "sma", {"period": 200, "interval": iv},
+          header=("indicators: candles -> per-asset features.",))
+    b.add("fresh_high", "recent_high_bars_ago", {"window": 60, "interval": iv})
+    b.add("trend_pct", "pct_change", {"lookback": 42, "interval": iv})
+    b.add("vol_surge", "volume_surge_ratio", {"recent_window": 6, "baseline_window": 42, "interval": iv})
+    b.add("accel", "acceleration", {"short_window": 3, "long_window": 6, "interval": iv})
+
+    # F1 — ADDITIONAL registry indicators requested by the answers (empty => no-op, byte-identical).
+    extra = _common.add_indicator_nodes(b, answers.indicators)
+
+    # F1 — the scorer's hard-vs-weighted split: answers.scoring overrides else these defaults.
+    feature_ids = ["trend_sma", "fresh_high", "trend_pct", "vol_surge", "accel", "lean"]
+    feature_ids += [r.id for r in extra]
+    required_gates, weights, min_score = _common.resolve_scoring(
+        answers,
+        default_required=("trend_sma", "accel"),
+        default_weights={"trend_pct": 1.0, "vol_surge": 1.0, "lean": 1.0},
+        default_min=3,
+        feature_ids=feature_ids,
+    )
+
+    b.add(
+        "gates", "hard_gates_all",
+        {
+            "required_gates": required_gates,
+            "weights": weights,
+            "min_score": min_score,
+        },
+        header=("scorer: hard gates + weighted sum — THE EDGE SLOT (see the EDGE block above).",),
+        param_comments={
+            "required_gates": "TODO(edit): feature keys (SOURCE NODE IDS) that must ALL pass.",
+            "weights": "TODO(edit): source-node-id -> weight; this weighted sum IS your edge.",
+            "min_score": "TODO(edit): minimum score to emit.",
+        },
+        slots=("required_gates", "weights", "min_score"),
+    )
+    b.set_edge_anchor("gates")
+
+    _common.add_ranker(
+        b, ranker_id="best", scorer_id="gates", scorer_port="scores",
+        account_id="account", max_positions=answers.max_positions,
+    )
+
+    b.add("emit", "signal_envelope",
+          {"margin_pct": answers.risk.margin_pct, "leverage": answers.risk.leverage},
+          header=("emitter: build the scan() signal list.",))
+
+    # universe narrowing chain
+    b.connect("account", "held", "exclude_held", "held", section="universe narrowing chain")
+    b.connect("exclude_held", "kept", "exclude_recent", "candidates")
+    b.connect("dedup_state", "recent", "exclude_recent", "recent")
+    b.connect("exclude_recent", "kept", "candles", "assets")
+    b.connect("exclude_recent", "kept", "lean", "assets")
+    # candles fan out to indicators
+    b.connect("candles", "candles", "trend_sma", "candles", section="candles fan out to indicators")
+    b.connect("candles", "candles", "fresh_high", "candles")
+    b.connect("candles", "candles", "trend_pct", "candles")
+    b.connect("candles", "candles", "vol_surge", "candles")
+    b.connect("candles", "candles", "accel", "candles")
+    _common.wire_indicator_inputs(b, extra, candles_id="candles")
+    # per-asset features MERGE into the scorer (keyed by source node id)
+    b.connect("trend_sma", "above", "gates", "features", section="per-asset features merge into the scorer (keyed by source node id)")
+    b.connect("fresh_high", "bars_ago", "gates", "features")
+    b.connect("trend_pct", "pct", "gates", "features")
+    b.connect("vol_surge", "ratio", "gates", "features")
+    b.connect("accel", "accelerating", "gates", "features")
+    b.connect("lean", "lean", "gates", "features")
+    _common.wire_indicator_features(b, extra, scorer_id="gates")
+    # score -> rank -> emit (rank wiring added by add_ranker)
+    b.connect("best", "selected", "emit", "selected")
+    b.connect("account", "equity", "emit", "equity")
+    # close the dedup loop
+    b.connect("emit", "signals", "dedup_state", "emitted", section="close the dedup loop: this tick's signals are recorded in ctx.state")
+    return b

package/dist/composer/authoring/builder.py

@@ -0,0 +1,191 @@
+"""builder — construct a strategy graph from the SAME registry types (D7 step 2).
+
+Archetype templates are CODE, not YAML-with-holes: they call this builder, which resolves
+every node against the registry (``NODES_BY_NAME``) and every edge port against the node's
+declared ``Port``s. A template that names a nonexistent node raises ``KeyError`` at
+``add()``; a template that wires a nonexistent port raises ``ValueError`` at ``connect()``.
+Both fire at construction time, so "construct every archetype and validate its output" (the
+CI test) is a hard guarantee that a template can never drift from the vocabulary — the
+build-guide's archetype table cannot rot the way an 83-package clone corpus did.
+
+A :class:`GraphBuilder` accumulates an ORDERED node list and edge list plus presentation
+metadata (per-node header comments, per-param TODO-slot comments, edge section labels, and
+which node is the scoring "edge anchor"). ``composer.authoring.emit`` turns that into the
+teaching YAML. The builder itself emits nothing and interprets no edge text — it only
+guarantees structural validity against the registry.
+
+pure_fn nodes (D2 kind 2) are added via :meth:`add_pure_fn`; their declared inputs/outputs
+are validated as ports here too, so wiring against a pure_fn is checked identically to a
+primitive.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from composer.registry import NODES_BY_NAME, Port, PortType
+
+
+@dataclass
+class BuiltNode:
+    """One node in the builder's ordered list (primitive or pure_fn)."""
+
+    id: str
+    node: Optional[str] = None            # registry node name (primitive)
+    kind: Optional[str] = None            # "pure_fn" or None
+    params: dict = field(default_factory=dict)      # `with:` values (primitive)
+    # pure_fn payload
+    inputs: tuple[dict, ...] = ()
+    outputs: tuple[dict, ...] = ()
+    pure_params: tuple[dict, ...] = ()
+    fn: Optional[str] = None
+    tests: tuple[dict, ...] = ()
+    # presentation
+    header: tuple[str, ...] = ()          # comment lines emitted above the node
+    param_comments: dict = field(default_factory=dict)   # param -> trailing comment
+    slot_params: tuple[str, ...] = ()     # params that are TODO(edit) slots
+
+    def out_ports(self) -> set[str]:
+        if self.kind == "pure_fn":
+            return {p["name"] for p in self.outputs}
+        return {p.name for p in NODES_BY_NAME[self.node].outputs}
+
+    def in_ports(self) -> set[str]:
+        if self.kind == "pure_fn":
+            return {p["name"] for p in self.inputs}
+        return {p.name for p in NODES_BY_NAME[self.node].inputs}
+
+
+@dataclass
+class BuiltEdge:
+    frm: str        # "node_id.port"
+    to: str         # "node_id.port"
+    section: Optional[str] = None   # comment line emitted before this edge (a group label)
+
+
+class GraphBuilder:
+    """Accumulates nodes + edges against the registry; the archetype templates' one API."""
+
+    def __init__(self) -> None:
+        self._nodes: list[BuiltNode] = []
+        self._edges: list[BuiltEdge] = []
+        self._by_id: dict[str, BuiltNode] = {}
+        self.edge_anchor: Optional[str] = None   # node the EDGE comment block sits above
+
+    # ------------------------------------------------------------------ node construction
+    def add(
+        self,
+        node_id: str,
+        node: str,
+        params: Optional[dict] = None,
+        *,
+        header: tuple[str, ...] = (),
+        param_comments: Optional[dict] = None,
+        slots: tuple[str, ...] = (),
+    ) -> "GraphBuilder":
+        """Add a primitive node. ``KeyError`` if ``node`` is not in the registry; a param
+        naming a key the node does not declare is a ``ValueError`` (CI catches template drift)."""
+        nd = NODES_BY_NAME[node]                     # KeyError = nonexistent node -> CI fail
+        params = dict(params or {})
+        declared = {p.name for p in nd.params}
+        for key in params:
+            if key not in declared:
+                raise ValueError(
+                    f"archetype template error: node {node_id!r} ({node}) sets unknown "
+                    f"param {key!r} (declared: {sorted(declared)})"
+                )
+        self._register(
+            BuiltNode(
+                id=node_id,
+                node=node,
+                params=params,
+                header=tuple(header),
+                param_comments=dict(param_comments or {}),
+                slot_params=tuple(slots),
+            )
+        )
+        return self
+
+    def add_pure_fn(
+        self,
+        node_id: str,
+        *,
+        inputs: tuple[dict, ...],
+        outputs: tuple[dict, ...],
+        params: tuple[dict, ...],
+        fn: str,
+        tests: tuple[dict, ...] = (),
+        header: tuple[str, ...] = (),
+    ) -> "GraphBuilder":
+        """Add a per-graph pure_fn node (D2 kind 2). Its declared ports must use the closed
+        PortType vocabulary — a bad type is a ``ValueError`` (CI catches template drift)."""
+        for side, ports in (("input", inputs), ("output", outputs)):
+            for p in ports:
+                try:
+                    PortType(p["type"])
+                except ValueError as exc:
+                    raise ValueError(
+                        f"archetype template error: pure_fn {node_id!r} {side} port "
+                        f"{p.get('name')!r} has bad type {p.get('type')!r}"
+                    ) from exc
+        self._register(
+            BuiltNode(
+                id=node_id,
+                kind="pure_fn",
+                inputs=tuple(inputs),
+                outputs=tuple(outputs),
+                pure_params=tuple(params),
+                fn=fn,
+                tests=tuple(tests),
+                header=tuple(header),
+            )
+        )
+        return self
+
+    def connect(
+        self, frm_id: str, frm_port: str, to_id: str, to_port: str, *, section: Optional[str] = None
+    ) -> "GraphBuilder":
+        """Wire ``frm_id.frm_port`` -> ``to_id.to_port``, validating both ports exist.
+
+        A port the node does not declare is a ``ValueError`` here (construction time), so a
+        template can never emit a graph that references a nonexistent port — the CI guarantee.
+        """
+        frm = self._by_id.get(frm_id)
+        to = self._by_id.get(to_id)
+        if frm is None:
+            raise ValueError(f"archetype template error: edge from unknown node {frm_id!r}")
+        if to is None:
+            raise ValueError(f"archetype template error: edge to unknown node {to_id!r}")
+        if frm_port not in frm.out_ports():
+            raise ValueError(
+                f"archetype template error: node {frm_id!r} has no output port {frm_port!r} "
+                f"(has: {sorted(frm.out_ports())})"
+            )
+        if to_port not in to.in_ports():
+            raise ValueError(
+                f"archetype template error: node {to_id!r} has no input port {to_port!r} "
+                f"(has: {sorted(to.in_ports())})"
+            )
+        self._edges.append(BuiltEdge(frm=f"{frm_id}.{frm_port}", to=f"{to_id}.{to_port}", section=section))
+        return self
+
+    def set_edge_anchor(self, node_id: str) -> "GraphBuilder":
+        """Mark the scoring node above which the verbatim EDGE comment block is emitted."""
+        self.edge_anchor = node_id
+        return self
+
+    # ------------------------------------------------------------------ accessors
+    @property
+    def nodes(self) -> list[BuiltNode]:
+        return list(self._nodes)
+
+    @property
+    def edges(self) -> list[BuiltEdge]:
+        return list(self._edges)
+
+    def _register(self, node: BuiltNode) -> None:
+        if node.id in self._by_id:
+            raise ValueError(f"archetype template error: duplicate node id {node.id!r}")
+        self._nodes.append(node)
+        self._by_id[node.id] = node