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

package/dist/composer/examples/pre_listing_classifier.graph.yaml

@@ -0,0 +1,204 @@
+# pre_listing_classifier — new-listing/IPOP strategy (tier 2) whose direction CLASSIFIER
+# is a per-graph pure_fn node (D2 kind 2).
+#
+# Why a pure_fn here (the slice-4 point): this strategy's pre-listing thesis is a CLASSIFIER
+# PREDICATE — the 4h structure classifies tradeable direction (NEUTRAL is dropped), the 1h
+# structure and smart money CONFIRM, and because SM data is sparse pre-listing its ABSENCE
+# falls back to a trend-only assumed-aligned bonus. That "SM present -> must agree; SM absent
+# -> assume aligned" branch is cross-feature conditional logic no registry scorer expresses.
+# The fn body re-expresses the corpus package magpie's `build_thesis_pre_listing`
+# (corpus: /Users/duncan/Senpi/skills/strategies/magpie/pre_listing/scanners/scoring.py) —
+# cited in the body — statically purity-checked, with inline fixture tests.
+#
+# DYNAMIC UNIVERSE (slice 5, restored): pre_listing_classifier's real universe is discovered each tick off
+# the LIVE market_list_instruments read by its IPOP funding signature (corpus
+# magpie/pre_listing/scanners/scan.py _fetch_ipop_universe + scoring.ipop_passes_universe).
+# The slice-4 whitelist stand-in is replaced by the discovery trio:
+#   instrument_list (live board records) -> classifier_predicate (funding + leverage +
+#   not-delisted, the ipop_passes_universe funding portion) -> universe_discover (xyz: prefix
+#   + leverage cap + min daily volume) -> the tradeable IPOP names.
+# Chaining the two predicates reproduces ipop_passes_universe's full conjunction while using
+# each registry node as declared (no registry change). emit_single_best is used because the
+# discovered pre-listing universe is naturally tiny (recon: "magpie-implicit-via-small-N").
+
+version: 1
+
+metadata:
+  archetype: event_new_listing
+  strategy: pre_listing_classifier
+  corpus_origin: magpie                # provenance only, for fidelity replay — not user-facing
+  exit_preset: protected_standard      # slice 9: emitted as runtime.yaml exit: (magpie = balanced discovery)
+  # EDGE (verbatim, machine never interprets): "catch trade.xyz pre-IPO perps as they start
+  # trending into the listing — 4h sets the side, 1h and smart money confirm, and when the
+  # book is too new for smart-money data, trust the trend."
+
+nodes:
+  # --- sources ---
+  - id: account
+    node: clearinghouse_state
+
+  - id: dedup_state
+    node: ttl_dedup_state
+    with:
+      ttl_seconds: 720                 # pre_listing_classifier's 720s per-coin dedup window
+
+  # --- dynamic universe discovery (the IPOP funding signature; see header) ---
+  - id: board
+    node: instrument_list              # live market_list_instruments records for the xyz venue
+    with:
+      dex: "xyz"
+
+  - id: ipop_funding
+    node: classifier_predicate         # ipop_passes_universe: |funding| tiny, lev<=5, live
+    with:
+      max_funding_abs: 0.0000001       # magpie ipopFundingMaxAbs 1e-7
+      max_leverage: 5                  # magpie ipopMaxLeverageCap
+      exclude_delisted: true
+
+  - id: ipop_universe
+    node: universe_discover            # xyz: prefix + leverage cap + min daily volume floor
+    with:
+      name_prefix: "xyz:"
+      max_leverage_cap: 5
+      min_day_volume: 100000           # magpie ipopMinDailyVolUsd
+
+  # --- universe narrowing over the discovered IPOP set ---
+  - id: exclude_held
+    node: held_asset_exclusion
+
+  - id: exclude_recent
+    node: recent_signal_ttl_dedup
+
+  # --- candle + leaderboard reads over the discovered, narrowed universe ---
+  - id: candles
+    node: candles_fetch
+    with:
+      intervals: ["1h", "4h"]          # universe is wired in (dynamic), not a static whitelist
+
+  - id: lean
+    node: sm_lean
+    with:
+      agree_threshold: 0.55            # magpie smTiltMinPct 55%
+
+  # --- trend structure at both intervals (the classifier's inputs) ---
+  - id: trend4h
+    node: trend_structure
+    with:
+      lookback: 6
+      interval: "4h"
+
+  - id: trend1h
+    node: trend_structure
+    with:
+      lookback: 6
+      interval: "1h"
+
+  # --- pure_fn classifier predicate (the bespoke, cross-feature edge; D2 kind 2) ---
+  - id: classify
+    kind: pure_fn
+    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: sm, type: feature_map, doc: "Smart-money long lean percent [0,100]; may be absent." }
+    outputs:
+      - { name: scores, type: score_map, doc: "Per-asset {score, direction, reasons[]} for tradeable IPOPs." }
+    params:
+      - { name: min_score, type: float, default: 3, doc: "Minimum pre-listing score to emit." }
+    fn: |
+      def classify_pre_listing(trend4h, trend1h, sm, min_score):
+          # Magpie PRE-LISTING (tier 2): a CLASSIFIER PREDICATE, not a weighted scorer. The
+          # 4h structure classifies the side (NEUTRAL -> not tradeable, dropped); 1h + SM
+          # confirm; SM is SPARSE pre-listing, so its ABSENCE falls back to trend-only
+          # (assumed aligned) while a PRESENT-but-opposing SM read drops the candidate.
+          # Ported from magpie/pre_listing/scanners/scoring.py build_thesis_pre_listing.
+          scores = {}
+          assets = sorted(set(trend4h) | set(trend1h) | set(sm))
+          for asset in assets:
+              t4 = trend4h.get(asset, "NEUTRAL")
+              if t4 == "NEUTRAL":
+                  continue
+              direction = "LONG" if t4 == "BULLISH" else "SHORT"
+              score = 3.0
+              reasons = ["4h_" + t4.lower()]
+              t1 = trend1h.get(asset, "NEUTRAL")
+              if (direction == "LONG" and t1 == "BULLISH") or (direction == "SHORT" and t1 == "BEARISH"):
+                  score = score + 2.0
+                  reasons.append("1h_confirms")
+              lean = sm.get(asset)
+              if lean is None:
+                  score = score + 2.0
+                  reasons.append("sm_sparse_assumed_aligned")
+              else:
+                  tilt = lean if direction == "LONG" else 100.0 - lean
+                  if tilt < 55.0:
+                      continue
+                  score = score + 2.0
+                  reasons.append("sm_aligned")
+                  if tilt >= 70.0:
+                      score = score + 1.0
+                      reasons.append("sm_strong")
+              if score < min_score:
+                  continue
+              scores[asset] = {"score": round(score, 4), "direction": direction, "reasons": reasons}
+          return scores
+    tests:
+      - name: bullish_confirmed_long
+        inputs:
+          trend4h: { ACME: BULLISH }
+          trend1h: { ACME: BULLISH }
+          sm: { ACME: 60.0 }
+        expect:
+          scores:
+            ACME: { score: 7.0, direction: LONG, reasons: [4h_bullish, 1h_confirms, sm_aligned] }
+      - name: neutral_4h_not_tradeable
+        inputs:
+          trend4h: { ACME: NEUTRAL }
+          trend1h: { ACME: BULLISH }
+          sm: { ACME: 60.0 }
+        expect:
+          scores: {}
+      - name: sparse_sm_trend_only
+        inputs:
+          trend4h: { ACME: BULLISH }
+          trend1h: { ACME: NEUTRAL }
+          sm: {}
+        expect:
+          scores:
+            ACME: { score: 5.0, direction: LONG, reasons: [4h_bullish, sm_sparse_assumed_aligned] }
+
+  # --- ranker + emitter ---
+  - id: best
+    node: emit_single_best
+    with:
+      min_score: 0                     # the pure_fn already applies pre_listing_classifier's score floor
+
+  - id: emit
+    node: signal_envelope
+    with:
+      margin_pct: 10                   # PERCENT of withdrawable
+      leverage: 5                      # pre_listing_classifier's IPOP venue max is <=5
+
+edges:
+  # dynamic universe discovery: board -> funding signature -> prefix/leverage/volume
+  - { from: board.instruments, to: ipop_funding.candidates }
+  - { from: ipop_funding.kept, to: ipop_universe.instruments }
+  # universe narrowing chain over the discovered IPOP names
+  - { from: ipop_universe.universe, to: exclude_held.candidates }
+  - { from: account.held, to: exclude_held.held }
+  - { from: exclude_held.kept, to: exclude_recent.candidates }
+  - { from: dedup_state.recent, to: exclude_recent.recent }
+  - { from: exclude_recent.kept, to: candles.assets }
+  - { from: exclude_recent.kept, to: lean.assets }
+  # candles fan out to trend structure at both intervals
+  - { from: candles.candles, to: trend4h.candles }
+  - { from: candles.candles, to: trend1h.candles }
+  # each feature wires into ONE declared pure_fn input port (single writer, no merge)
+  - { from: trend4h.direction, to: classify.trend4h }
+  - { from: trend1h.direction, to: classify.trend1h }
+  - { from: lean.lean, to: classify.sm }
+  # classify -> rank -> emit
+  - { from: classify.scores, to: best.scores }
+  - { from: best.selected, to: emit.selected }
+  - { from: account.equity, to: emit.equity }
+  # close the dedup loop
+  - { from: emit.signals, to: dedup_state.emitted }

package/dist/composer/examples/trend_momentum_majors.graph.yaml

@@ -0,0 +1,133 @@
+# trend_momentum_majors — parabolic trend-momentum strategy (tier 1, LONG-only) over a
+# fixed 4-asset majors whitelist, as a typed dataflow DAG.
+#
+# Hand-authored from the corpus-recon inventory (stag section): a fixed 4-asset whitelist
+# scanned on 4h candles, gated by five hard conditions (above SMA-200, +trend%, volume
+# surge, acceleration, smart-money alignment), single-best emission, and the universal
+# TTL signal-dedup on ctx.state. This is the slice-2 "validates clean" fixture and the
+# slice-3 compile target. Re-expression of corpus package stag; semantics cited to
+# skills/strategies/stag/... throughout.
+#
+# Shape (why it is a DAG, not a pipeline): candles fan out to five indicators whose
+# per-asset features MERGE into the scorer; the universe is first narrowed by held-asset
+# exclusion and TTL dedup. The ttl_dedup_state node closes the dedup loop through
+# ctx.state (its `recent` output is prior-tick data, so it does not form a cycle).
+
+version: 1
+
+metadata:
+  archetype: trend_momentum
+  strategy: trend_momentum_majors
+  corpus_origin: stag                # provenance only, for fidelity replay — not user-facing
+  exit_preset: protected_wide        # slice 9: emitted as runtime.yaml exit: (stag = let the runner breathe)
+  # EDGE (verbatim, machine never interprets): "ride assets breaking to fresh highs with
+  # accelerating momentum, volume confirmation, and smart money leaning the same way."
+
+nodes:
+  # --- sources ---
+  - id: account
+    node: clearinghouse_state          # held-asset set + account equity
+
+  - id: dedup_state
+    node: ttl_dedup_state              # ctx.state TTL dedup; `recent` = assets within TTL
+    with:
+      ttl_seconds: 240
+
+  # --- universe narrowing (held-exclusion then recent-signal dedup) ---
+  - id: exclude_held
+    node: held_asset_exclusion         # candidates default to the whitelist universe
+
+  - id: exclude_recent
+    node: recent_signal_ttl_dedup
+
+  # --- candle + leaderboard reads over the narrowed universe ---
+  - id: candles
+    node: candles_fetch
+    with:
+      whitelist: ["BTC", "ETH", "SOL", "HYPE"]
+      intervals: ["4h"]
+
+  - id: lean
+    node: sm_lean
+    with:
+      agree_threshold: 0.6             # trend_momentum_majors requires >=60% SM alignment
+
+  # --- indicators (candles -> per-asset features) ---
+  - id: trend_sma
+    node: sma
+    with:
+      period: 200
+      interval: "4h"
+
+  - id: fresh_high
+    node: recent_high_bars_ago
+    with:
+      window: 60
+
+  - id: trend_pct
+    node: pct_change
+    with:
+      lookback: 42                     # ~7d of 4h bars
+      interval: "4h"
+
+  - id: vol_surge
+    node: volume_surge_ratio
+    with:
+      recent_window: 6
+      baseline_window: 42
+
+  - id: accel
+    node: acceleration
+    with:
+      short_window: 3
+      long_window: 6
+
+  # --- scorer: five hard gates + weighted score (bespoke edge slot) ---
+  - id: gates
+    node: hard_gates_all
+    with:
+      # gate/weight keys are SOURCE NODE IDs (the compiler merges features keyed by the
+      # producing node id — collision-free even when two producers share a port name).
+      required_gates: ["trend_sma", "accel"]   # above-SMA AND accelerating (both boolean)
+      # TODO(edge): tune these weights — the strategy's real edge lives here.
+      weights: { trend_pct: 1.0, vol_surge: 1.0, lean: 1.0 }
+      min_score: 3
+
+  # --- ranker + emitter ---
+  - id: best
+    node: emit_single_best
+    with:
+      min_score: 3
+
+  - id: emit
+    node: signal_envelope
+    with:
+      margin_pct: 5
+      leverage: 3
+
+edges:
+  # universe narrowing chain
+  - { from: account.held, to: exclude_held.held }
+  - { from: exclude_held.kept, to: exclude_recent.candidates }
+  - { from: dedup_state.recent, to: exclude_recent.recent }
+  - { from: exclude_recent.kept, to: candles.assets }
+  - { from: exclude_recent.kept, to: lean.assets }
+  # candles fan out to indicators
+  - { from: candles.candles, to: trend_sma.candles }
+  - { from: candles.candles, to: fresh_high.candles }
+  - { from: candles.candles, to: trend_pct.candles }
+  - { from: candles.candles, to: vol_surge.candles }
+  - { from: candles.candles, to: accel.candles }
+  # per-asset features MERGE into the scorer (feature_map inputs merge)
+  - { from: trend_sma.above, to: gates.features }
+  - { from: fresh_high.bars_ago, to: gates.features }
+  - { from: trend_pct.pct, to: gates.features }
+  - { from: vol_surge.ratio, to: gates.features }
+  - { from: accel.accelerating, to: gates.features }
+  - { from: lean.lean, to: gates.features }
+  # score -> rank -> emit
+  - { from: gates.scores, to: best.scores }
+  - { from: best.selected, to: emit.selected }
+  - { from: account.equity, to: emit.equity }
+  # close the dedup loop: this tick's signals are recorded in ctx.state
+  - { from: emit.signals, to: dedup_state.emitted }

package/dist/composer/generated/README.md

@@ -0,0 +1,22 @@
+# composer/generated/ — registry-derived artifacts (DO NOT EDIT)
+
+These files are generated from the node registry (`composer/registry/nodes.py`) — the
+single source of truth (D4). They are committed so the agent skill, the TS rim, and CI
+can read them without a build step, and so drift is caught by a golden-file diff.
+
+| File | What it is |
+|---|---|
+| `graph.schema.json` | JSON Schema for the graph document format (D6). YAML is authored; this JSON Schema is canonical. Per-node param constraints derive via `if`/`then` on the node name. YAML anchors/merge keys are banned at the document level (noted in the schema; enforced in the validator, slice 2). |
+| `catalog.md` | The ~1–2k-token progressive-disclosure index: node names, one-liners, param summaries. |
+| `describe.md` | Full ports / params / example / cost per node (`composer describe <node>`). |
+
+Regenerate after any registry change:
+
+```
+python -m composer.registry.generate          # rewrite the artifacts
+python -m composer.registry.generate --check   # CI-style: exit 1 if stale
+```
+
+Generation is deterministic (stable ordering, sorted JSON keys, no timestamps): running
+it twice produces byte-identical output. The golden-file tests in
+`python-tests/composer/` regenerate and diff against these committed files.

package/dist/composer/generated/catalog.md

@@ -0,0 +1,118 @@
+# Strategy Composer — Node Catalog
+
+Schema version: 1. Generated from composer/registry/nodes.py — do not edit by hand.
+
+Progressive-disclosure index (D4): node names, one-liners, param summaries. `composer describe <node>` gives full ports/params/examples.
+
+## scoring
+
+Bespoke scoring/classification is a `kind: pure_fn` node (typed ports, one `def`, math/statistics only, inline tests), never a primitive; `hard_gates_all` covers simple gate-and-weigh. Repeated shapes promote post-MVP.
+
+## source
+
+- **account_history_fetch** — Own-account bucketed PnL / account-value history across timeframes.
+  - params: bucket_duration_ms (int=3600000, 60000..604800000)
+- **arena_leaderboard_fetch** — Senpi Arena prize-competition leaderboard (AI agents, not HL traders).
+  - params: period_type (str='WEEK'); period_number (int=0, 0..); limit (int=100, 1..500); offset (int=0, 0..); qualified (bool=False)
+- **asset_trading_limits_fetch** — Per-asset venue max-leverage limit for the own wallet.
+  - params: dex (str='')
+- **candles_fetch** — Fetch multi-interval OHLCV candles for a universe of assets.
+  - params: whitelist (list[str]=[]); intervals (list[str]=[4h]); include_funding (bool=False); include_asset_context (bool=False)
+- **clearinghouse_state** — Read account equity and the set of currently-held positions.
+- **cross_asset_flows_fetch** — Leader move + correlated laggards that haven't followed yet.
+  - params: leader_asset (str='BTC'); min_move_pct (float=2.0, 0.0..); window (str='4h')
+- **funding_history_fetch** — Per-asset extreme-funding history with direction + trend enums.
+  - params: asset (str=''); min_annualized_pct (float=20.0, 0.0..); min_persistence_hours (float=0.0, 0.0..)
+- **funding_regime_fetch** — Market-wide funding regime (crowding) label plus its numeric companions.
+- **instrument_list** — List live tradeable instruments with venue metadata.
+  - params: dex (str='')
+- **leaderboard_top_fetch** — FAST 4h-window smart-money leaderboard (delta-PnL 'Predators').
+  - params: limit (int=100, 1..500)
+- **leaderboard_trader_fetch** — One trader's live 4h-window leaderboard headline scalars.
+  - params: trader_id (str=required)
+- **market_prices_fetch** — Latest per-asset mark prices for a venue.
+  - params: dex (str='')
+- **mcp_read** — Escape hatch: read any MCP tool, emitting its unwrapped payload as `raw`.
+  - params: tool (str=required); args (map_str_json={}); timeout_seconds (float=0.0, 0.0..120.0)
+- **momentum_events_fetch** — Recent momentum threshold-crossing events (traders crossing profit tiers).
+  - params: limit (int=50, 1..200); tier (int=0, 0..3); asset (str=''); from_time (str=''); to_time (str='')
+- **open_orders_fetch** — Open resting orders for the strategy's own wallet.
+- **open_positions_realized_pnl_fetch** — Realized (banked) PnL already taken on STILL-OPEN positions, batched.
+  - params: latest (bool=False)
+- **own_return_24h** — Per-asset 24h return derived from markPx/prevDayPx asset_context.
+- **sm_lean** — Smart-money net long/short lean per asset from the leaderboard.
+  - params: agree_threshold (float=0.55, 0.0..1.0)
+- **strategy_list_fetch** — List strategy-metadata records (id, wallet, status, type, funded).
+  - params: status (str=''); strategy_type (str='')
+- **strategy_pnl_snapshot** — Today's PnL / account-value / drawdown snapshot for the own wallet.
+  - params: period (str=''); drawdown_reset_on_day_rollover (bool=False)
+- **top_strategies_fetch** — Ranked Senpi copy-trading strategies (paginated) sorted by total PnL.
+  - params: limit (int=20, 1..); offset (int=0, 0..); force_fetch (bool=False); max_pages (int=1, 1..)
+- **top_traders_fetch** — Ranked best-track-record Hyperliquid traders (paginated).
+  - params: time_frame (str=required); sort_by (str='RETURN_ON_INVESTMENT'); bias (str='ALL'); limit (int=100, 1..1000); max_pages (int=1, 1..); open_position_filter (bool=False); activity_labels (list[str]=[]); consistency (list[str]=[]); risk_labels (list[str]=[])
+- **trader_history_fetch** — Closed-trade history for an arbitrary trader address.
+  - params: trader_address (str=required); limit (int=100, 1..1000)
+- **trader_positions_fetch** — One leaderboard trader's per-position 4h PnL breakdown.
+  - params: trader_id (str=required)
+- **trader_state_fetch** — An arbitrary trader's current book: held set + account equity.
+  - params: trader_address (str=required)
+- **trader_states_fetch** — Full current books for a batch of traders (chunked at 50).
+  - params: wallets (list[str]=[]); latest (bool=False); include_position_age (bool=False); sort_open_positions_by (str=''); sort_open_positions_direction (str='DESC')
+- **universe_discover** — Derive a tradeable universe by filtering live instruments on a predicate.
+  - params: min_day_volume (float=0.0, 0.0..); max_leverage_cap (float=5.0, 1.0..); name_prefix (str='')
+
+## indicator
+
+- **acceleration** — Whether a short-window move is at least half a long-window move.
+  - params: short_window (int=3, 1..); long_window (int=6, 2..); interval (str='4h')
+- **aggregate_bias** — Cross-trader net/gross cohort bias per coin.
+- **breakout_detect** — Directional breakout of the prior-window high/low.
+  - params: window (int=168, 2..); interval (str='1h')
+- **pct_change** — Percent change of close over a lookback window.
+  - params: lookback (int=42, 1..); interval (str='4h')
+- **recent_high_bars_ago** — Bars elapsed since the highest high in a window (fresh-high check).
+  - params: window (int=60, 2..); interval (str='4h')
+- **rsi** — Relative Strength Index over the last N bars.
+  - params: period (int=14, 2..100); interval (str='1h')
+- **sma** — Simple moving average of close and an above/below flag.
+  - params: period (int=200, 1..1000); interval (str='4h')
+- **threshold_gate** — Compare a per-asset feature against a threshold, emitting a 1.0/0.0 gate.
+  - params: op (str='lt'); value (float=0.0)
+- **trend_structure** — Higher-lows / lower-highs trend direction over a lookback.
+  - params: lookback (int=6, 2..); interval (str='4h')
+- **volume_surge_ratio** — Recent-window mean volume divided by a baseline-window mean.
+  - params: recent_window (int=6, 1..); baseline_window (int=42, 1..); interval (str='4h')
+
+## filter
+
+- **classifier_predicate** — Gate universe membership on a set of instrument-field predicates.
+  - params: max_funding_abs (float=1e-07, 0.0..); max_leverage (float=5.0, 1.0..); exclude_delisted (bool=True)
+- **held_asset_exclusion** — Drop candidates already held in the account.
+- **live_instrument_validation** — Keep only candidates still live on the venue board.
+- **recent_signal_ttl_dedup** — Drop candidates signaled within the dedup TTL.
+
+## scorer
+
+- **hard_gates_all** — Require all named gates to pass, then score the survivors.
+  - params: required_gates (list[str]=[]); weights (map_str_float={}); min_score (float=0.0, 0.0..)
+
+## ranker
+
+- **emit_single_best** — Sort by score and select the single best candidate.
+  - params: min_score (float=0.0)
+- **rank_pool_cap_to_open_slots** — Sort by score and take the top (max_slots - held) candidates.
+  - params: max_slots (int=5, 1..50); min_score (float=0.0)
+
+## emitter
+
+- **signal_envelope** — Build the scan() signal list from selected candidates.
+  - params: margin_pct (float=5.0, 0.0001..100.0); leverage (float=3.0, 1.0..50.0); clamp_leverage_to_venue (bool=True); valid_for_seconds (int=0, 0..); signal_type (str='')
+
+## stateful
+
+- **cohort_cache_state** — Cache a cohort in ctx.state behind a TTL + version.
+  - params: ttl_hours (float=24.0, 0.0..); version (int=1, 0..)
+- **snapshot_diff_state** — Rolling per-key snapshots; growth vs the window's oldest.
+  - params: value_field (str=''); bucket_seconds (int=86400, 1..); max_snapshots (int=12, 2..)
+- **ttl_dedup_state** — Track recently-signaled assets in ctx.state with a TTL and pruning.
+  - params: ttl_seconds (int=240, 1..); prune_factor (int=4, 1..)