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

package/dist/composer/primitives/indicators.py

@@ -0,0 +1,326 @@
+"""indicators — pure per-asset indicator primitives (candles -> feature_map).
+
+Each function takes the ``candles`` port value (``{asset: {interval: [candle]}}``)
+plus the node's registry params, and returns one feature_map per declared output
+port (``{asset: value}``). Pure compute, no I/O. Two exceptions take a non-candle input
+(each with its own compiler emission branch): ``threshold_gate`` takes a feature_map (a raw
+indicator output to threshold), and ``aggregate_bias`` takes a record_list of trader-state
+records (the cross-trader cohort aggregation) — see their docstrings.
+
+Convention (compiler + goldens rely on it): an asset with INSUFFICIENT data for the
+indicator is OMITTED from the returned map(s). A downstream required gate that names
+this feature then fails for that asset (missing key -> not truthy), which reproduces
+the corpus originals' "return None -> no signal" behaviour without special-casing.
+
+Semantics are ported from the corpus originals under
+``/Users/duncan/Senpi/skills/strategies/{stag,hawk}/main/scanners/scoring.py``
+(cited per function). The per-primitive golden vectors WE author define correctness.
+"""
+
+from __future__ import annotations
+
+from ._candles import _closes, _high, _low, _pct_change, _vol
+
+
+def sma(candles: dict, *, period: int, interval: str) -> tuple[dict, dict]:
+    """SMA of close + a close>SMA flag. Ports: value (feature_map), above (feature_map).
+
+    Ported from stag ``scoring.sma`` / ``is_above_sma``: mean of the last ``period``
+    closes; ``above`` is latest_close > SMA. Assets with < ``period`` closes are omitted.
+    """
+    value: dict = {}
+    above: dict = {}
+    for asset in sorted(candles):
+        closes = _closes(candles[asset].get(interval, []))
+        if len(closes) < period:
+            continue
+        window = closes[-period:]
+        s = sum(window) / period
+        value[asset] = s
+        above[asset] = closes[-1] > s
+    return value, above
+
+
+def pct_change(candles: dict, *, lookback: int, interval: str) -> dict:
+    """Percent change of close over ``lookback`` bars. Port: pct (feature_map).
+
+    Ported from stag ``scoring.pct_change`` (7d trend %). Assets with <= ``lookback``
+    closes, or a non-positive reference price, are omitted.
+    """
+    out: dict = {}
+    for asset in sorted(candles):
+        closes = _closes(candles[asset].get(interval, []))
+        pct = _pct_change(closes, lookback)
+        if pct is not None:
+            out[asset] = pct
+    return out
+
+
+def recent_high_bars_ago(candles: dict, *, window: int, interval: str) -> dict:
+    """Bars since the highest close in the window. Port: bars_ago (feature_map).
+
+    Ported from stag ``scoring.recent_high_bars_ago`` (fresh-high freshness check;
+    ``window`` maps to the original ``lookback``): 0 = the latest bar is the high.
+    Assets with <= ``window`` closes are omitted.
+    """
+    out: dict = {}
+    for asset in sorted(candles):
+        closes = _closes(candles[asset].get(interval, []))
+        if len(closes) <= window:
+            continue
+        win = closes[-(window + 1):]
+        high_idx = max(range(len(win)), key=lambda i: win[i])
+        out[asset] = len(win) - 1 - high_idx
+    return out
+
+
+def volume_surge_ratio(candles: dict, *, recent_window: int, baseline_window: int, interval: str) -> dict:
+    """mean(recent volumes) / mean(baseline volumes). Port: ratio (feature_map).
+
+    Unifies stag ``scoring.volume_surge`` (ratio part), hawk ``volume_ratio`` and
+    bison ``volume_trend`` into one parameterized primitive. Assets with < baseline
+    volumes, or a non-positive baseline mean, are omitted.
+    """
+    out: dict = {}
+    for asset in sorted(candles):
+        vols = [_vol(c) for c in candles[asset].get(interval, [])]
+        if len(vols) < baseline_window:
+            continue
+        recent = vols[-recent_window:]
+        baseline = vols[-baseline_window:]
+        rmean = sum(recent) / len(recent) if recent else 0.0
+        bmean = sum(baseline) / len(baseline) if baseline else 0.0
+        if bmean <= 0:
+            continue
+        out[asset] = rmean / bmean
+    return out
+
+
+def acceleration(candles: dict, *, short_window: int, long_window: int, interval: str) -> dict:
+    """Whether the short-window move is >= half the long-window move. Port: accelerating.
+
+    Ported from stag ``scoring.is_accelerating`` composed with ``pct_change``: the
+    recent half is keeping pace or faster, and the long move is positive (LONG-bias).
+    Assets where either move is uncomputable are omitted.
+    """
+    out: dict = {}
+    for asset in sorted(candles):
+        closes = _closes(candles[asset].get(interval, []))
+        short_move = _pct_change(closes, short_window)
+        long_move = _pct_change(closes, long_window)
+        if short_move is None or long_move is None:
+            continue
+        out[asset] = bool(long_move > 0 and short_move >= (long_move / 2.0))
+    return out
+
+
+def trend_structure(candles: dict, *, lookback: int, interval: str) -> dict:
+    """Higher-lows / lower-highs structure. Port: direction (feature_map).
+
+    Ported VERBATIM from hawk ``scoring.trend_4h`` (the corpus' single most-duplicated
+    indicator): strict higher-low / lower-high counting, gated at ``>= (lookback-1)*0.6``.
+    Emits the corpus' BULLISH / BEARISH / NEUTRAL vocabulary (a deliberate deviation
+    from the registry prose's "LONG/SHORT/NEUTRAL": keeping this distinct from a trade
+    DIRECTION lets a graph wire both breakout_detect.direction AND trend_structure into
+    one scorer without the direction detector confusing the two). Assets with < lookback
+    candles are omitted.
+    """
+    out: dict = {}
+    for asset in sorted(candles):
+        series = candles[asset].get(interval, [])
+        if len(series) < lookback:
+            continue
+        lows = [_low(c) for c in series[-lookback:]]
+        highs = [_high(c) for c in series[-lookback:]]
+        higher_lows = sum(1 for i in range(1, len(lows)) if lows[i] > lows[i - 1])
+        lower_highs = sum(1 for i in range(1, len(highs)) if highs[i] < highs[i - 1])
+        total = lookback - 1
+        if higher_lows >= total * 0.6:
+            out[asset] = "BULLISH"
+        elif lower_highs >= total * 0.6:
+            out[asset] = "BEARISH"
+        else:
+            out[asset] = "NEUTRAL"
+    return out
+
+
+def rsi(candles: dict, *, period: int, interval: str) -> dict:
+    """Relative Strength Index over the last ``period`` bars. Port: rsi (feature_map).
+
+    Ported VERBATIM from bison ``scoring.calc_rsi`` / thesis-fund ``scoring.calc_rsi``
+    (both use the trailing-window variant: the LAST ``period`` gains/losses). ``avg_l == 0``
+    -> 100.0. Assets with < ``period + 1`` closes are omitted (the corpus returns a neutral
+    50 there; omission lets a downstream consumer supply its own default, per this module's
+    insufficient-data convention).
+    """
+    out: dict = {}
+    for asset in sorted(candles):
+        closes = _closes(candles[asset].get(interval, []))
+        if len(closes) < period + 1:
+            continue
+        gains: list = []
+        losses: list = []
+        for i in range(1, len(closes)):
+            d = closes[i] - closes[i - 1]
+            gains.append(max(0.0, d))
+            losses.append(max(0.0, -d))
+        g = gains[-period:]
+        l = losses[-period:]
+        avg_g = sum(g) / period
+        avg_l = sum(l) / period
+        if avg_l == 0:
+            out[asset] = 100.0
+        else:
+            out[asset] = 100.0 - (100.0 / (1.0 + avg_g / avg_l))
+    return out
+
+
+_THRESHOLD_OPS = {
+    "lt": lambda a, b: a < b,
+    "lte": lambda a, b: a <= b,
+    "gt": lambda a, b: a > b,
+    "gte": lambda a, b: a >= b,
+}
+
+
+def threshold_gate(values: dict, *, op: str, value: float) -> dict:
+    """Compare a per-asset numeric feature against a threshold. Port: passed (feature_map).
+
+    Takes a feature_map ``{asset: value}`` (a RAW indicator output — e.g.
+    recent_high_bars_ago's ``bars_ago``) and emits ``1.0`` where ``value <op> threshold``
+    holds, ``0.0`` otherwise, so the result reads as a truthy/falsy gate the scorer's
+    ``required_gates`` can consume. ``op`` is one of ``lt|lte|gt|gte``. A missing key is
+    simply absent from the output (the downstream gate then fails for that asset, the
+    module's insufficient-data convention); a present ``None`` (or a non-numeric value)
+    maps to ``0.0`` — never a crash. This closes the C1 inversion where a raw bars-ago
+    feature was hard-gated on TRUTHINESS (a fresh 0-bars-ago high read as falsy and FAILED,
+    a stale 40-bar-old high read as truthy and PASSED); a real threshold makes ``bars_ago
+    <= 5`` mean "fresh".
+    """
+    cmp = _THRESHOLD_OPS.get(op)
+    if cmp is None:
+        raise ValueError(
+            f"threshold_gate: unknown op {op!r}; choose one of {sorted(_THRESHOLD_OPS)}"
+        )
+    out: dict = {}
+    for asset in sorted(values or {}):
+        raw = values[asset]
+        if raw is None:
+            out[asset] = 0.0
+            continue
+        try:
+            fv = float(raw)
+        except (TypeError, ValueError):
+            out[asset] = 0.0
+            continue
+        out[asset] = 1.0 if cmp(fv, value) else 0.0
+    return out
+
+
+def breakout_detect(candles: dict, *, window: int, interval: str) -> dict:
+    """Directional breakout of the prior-window close high/low. Port: direction.
+
+    Ported from hawk ``scoring.detect_breakout``: LONG if the latest close breaks the
+    max of the PRIOR ``window`` closes (the latest bar excluded from its own range),
+    SHORT if it breaks the min, else NEUTRAL. Emits LONG / SHORT / NEUTRAL (a trade
+    direction; the scorer's direction detector reads it). Assets with < window+1
+    closes, or a non-positive latest close, are omitted.
+    """
+    out: dict = {}
+    for asset in sorted(candles):
+        series = candles[asset].get(interval, [])
+        if len(series) < window + 1:
+            continue
+        win = series[-window:]
+        closes = _closes(win)
+        latest_close = closes[-1]
+        prior = closes[:-1]
+        if not prior or latest_close <= 0:
+            continue
+        high = max(prior)
+        low = min(prior)
+        if latest_close > high:
+            out[asset] = "LONG"
+        elif latest_close < low:
+            out[asset] = "SHORT"
+        else:
+            out[asset] = "NEUTRAL"
+    return out
+
+
+# --------------------------------------------------------------------- aggregate_bias
+# The ONE sanctioned promote-loop primitive (registry-mapping-audit.md:49-51): the cross-
+# trader net/gross bias per coin, shared NEAR-VERBATIM by whalehunter (scoring.aggregate_bias
+# fused) and chimp/gibbon/gorilla/orangutan (the split cohort_positions_bias + finalize_bias).
+# Ported from whalehunter scoring.py:40-70. Takes a record_list of TraderState records (from
+# trader_states_fetch, whose normalized rows carry open_positions[] with coin/szi/position_value/
+# entry_px) and emits a per-coin feature_map — the indicator output contract, hence kind=indicator
+# (a scorer must emit a score_map+reasons, which this does not). The concentration/consensus
+# cohort packages (oxpecker/remora) DIVERGE — they score per-candidate top positions, not net/
+# gross cohort bias — so only this common core is promoted; those stay pure_fn.
+
+
+def _bias_f(x, *keys, default=0.0):
+    """Float from a dict trying each key in order (whalehunter scoring._f), tolerating the camel-
+    AND snake-case field names trader_states_fetch may surface."""
+    if not isinstance(x, dict):
+        return default
+    for k in keys:
+        if x.get(k) is not None:
+            try:
+                return float(x[k])
+            except (TypeError, ValueError):
+                continue
+    return default
+
+
+def _signed_notional(p) -> float:
+    """Signed notional of one position: sign(szi) * |value|, value falling back to |szi|*entry
+    when positionValue is missing (whalehunter scoring._signed_notional, verbatim contract)."""
+    szi = _bias_f(p, "szi", "size")
+    val = _bias_f(p, "positionValue", "position_value", "notional")
+    if val <= 0:
+        val = abs(szi) * _bias_f(p, "entryPx", "entry_px", "markPx", "entry_price")
+    return (1.0 if szi > 0 else (-1.0 if szi < 0 else 0.0)) * abs(val)
+
+
+def aggregate_bias(traders: list) -> dict:
+    """Aggregate a cohort's NET positioning per coin. Port: bias (feature_map).
+
+    Given a record_list of trader-state records, sums each coin's signed notional across every
+    trader's open positions and emits a per-coin record:
+    ``{coin: {net, gross, bias, n_long, n_short, direction}}`` where ``bias = net/gross`` in
+    [-1,+1] (+1 all long, -1 all short) and ``direction`` = LONG / SHORT / NEUTRAL from the sign
+    of net. n_long/n_short are the per-side member counts (whalehunter reads them as the confirm
+    count; the split cohort packages surface members = n_long+n_short, recoverable by summing).
+    Pure compute — no clock, no I/O. Both openPositions/open_positions and coin/asset field
+    spellings are tolerated so the node consumes trader_states_fetch's normalized rows directly.
+    """
+    per: dict = {}
+    for t in traders or []:
+        if not isinstance(t, dict):
+            continue
+        positions = t.get("open_positions") or t.get("openPositions") or []
+        for p in positions:
+            if not isinstance(p, dict):
+                continue
+            coin = p.get("coin") or p.get("asset")
+            if not coin:
+                continue
+            sn = _signed_notional(p)
+            if sn == 0:
+                continue
+            d = per.setdefault(coin, {"net": 0.0, "gross": 0.0, "n_long": 0, "n_short": 0})
+            d["net"] += sn
+            d["gross"] += abs(sn)
+            d["n_long" if sn > 0 else "n_short"] += 1
+    out: dict = {}
+    for coin in sorted(per):
+        d = per[coin]
+        bias = round(d["net"] / d["gross"], 3) if d["gross"] > 0 else 0.0
+        direction = "LONG" if d["net"] > 0 else ("SHORT" if d["net"] < 0 else "NEUTRAL")
+        out[coin] = {
+            "net": round(d["net"], 6), "gross": round(d["gross"], 6), "bias": bias,
+            "n_long": d["n_long"], "n_short": d["n_short"], "direction": direction,
+        }
+    return out

package/dist/composer/primitives/rankers.py

@@ -0,0 +1,40 @@
+"""rankers — selection primitives over a score_map.
+
+``emit_single_best`` is the stag/hawk/bison selector: sort descending, keep the top
+one at/above the floor. Ported from stag/hawk ``candidates.sort(..., reverse=True)[0]``.
+``rank_pool_cap_to_open_slots`` is thesis-fund's rank-the-pool-then-cap selector: sort the
+whole confirming pool descending and take the top ``max_slots - held`` — the one corpus
+strategy that is not single-best.
+"""
+
+from __future__ import annotations
+
+
+def emit_single_best(scores: dict, *, min_score: float) -> dict:
+    """Select the single highest-scoring candidate at/above ``min_score``. Port: selected.
+
+    Deterministic tie-break: highest ``score``, then asset name ascending. Returns a
+    score_map with at most one entry (``{}`` when nothing clears the floor).
+    """
+    eligible = [(a, e) for a, e in scores.items() if e.get("score", 0) >= min_score]
+    if not eligible:
+        return {}
+    # highest score first; ascending asset name as the deterministic tie-break.
+    eligible.sort(key=lambda item: (-item[1].get("score", 0), item[0]))
+    asset, entry = eligible[0]
+    return {asset: entry}
+
+
+def rank_pool_cap_to_open_slots(scores: dict, held: list, *, max_slots: int, min_score: float) -> dict:
+    """Rank the confirming pool and cap emissions to the open slots. Port: selected.
+
+    Ported from thesis-fund ``scan.scan``: ``open_slots = max(0, max_slots - len(held))``;
+    sort all candidates at/above ``min_score`` by score desc (asset name asc tie-break) and
+    keep the top ``open_slots``. When every slot is already taken (open_slots == 0) the pool
+    is ranked but NOTHING is selected — the recon's "pool ranked but all open slots taken"
+    case. Returns a score_map with 0..open_slots entries.
+    """
+    eligible = [(a, e) for a, e in scores.items() if e.get("score", 0) >= min_score]
+    eligible.sort(key=lambda item: (-item[1].get("score", 0), item[0]))
+    open_slots = max(0, int(max_slots) - len(held or []))
+    return {a: e for a, e in eligible[:open_slots]}

package/dist/composer/primitives/scorers.py

@@ -0,0 +1,100 @@
+"""scorers — the weighted-sum-with-gates scorer primitive + the merge helper.
+
+The corpus scorers are all "weighted sum + reasons[]" at the core, differing only in
+the gate wrapper. ``hard_gates_all`` is the stag/hawk pattern (a set of hard gates,
+then a weighted score with a min-score floor). Correctness is defined by the goldens
+WE author (the graph re-expresses the strategy via registry primitives; it is not a
+bit-transcription of stag's ``parabolic_score`` — see the POC plan slice-3 note).
+"""
+
+from __future__ import annotations
+
+
+def merge_features(feature_maps: dict) -> dict:
+    """Merge several feature_maps into one per-asset record keyed by SOURCE NODE ID.
+
+    ``feature_maps`` = ``{node_id: {asset: value}}`` (the compiler passes the wired
+    producers). Returns ``{asset: {node_id: value}}`` over the union of assets. Keying
+    by node id (not port name) is collision-free even when two producers share a port
+    name (e.g. breakout_detect.direction and trend_structure.direction), and it is what
+    a graph's ``required_gates`` / ``weights`` reference.
+    """
+    assets: set = set()
+    for fm in feature_maps.values():
+        assets.update(fm.keys())
+    merged: dict = {}
+    for asset in sorted(assets):
+        rec: dict = {}
+        for node_id in sorted(feature_maps):
+            fm = feature_maps[node_id]
+            if asset in fm:
+                rec[node_id] = fm[asset]
+        merged[asset] = rec
+    return merged
+
+
+def _truthy(value) -> bool:
+    """Gate truthiness: a decisive, present feature. bool -> itself; number -> > 0;
+    str -> a decisive direction (not '' / 'NEUTRAL'); missing/None -> False."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value > 0
+    if isinstance(value, str):
+        return value.strip().upper() not in ("", "NEUTRAL")
+    return False
+
+
+def _num(value) -> float:
+    """Scoring coercion: bool -> 1/0; number -> itself; decisive str -> 1.0 else 0.0;
+    missing/None -> 0.0."""
+    if isinstance(value, bool):
+        return 1.0 if value else 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        return 1.0 if _truthy(value) else 0.0
+    return 0.0
+
+
+def _detect_direction(rec: dict) -> str:
+    """A candidate's trade direction = the unique feature whose value is a trade
+    direction ('LONG'/'SHORT'). None or ambiguous -> 'LONG' (LONG-only default)."""
+    dirs = {
+        v.strip().upper()
+        for v in rec.values()
+        if isinstance(v, str) and v.strip().upper() in ("LONG", "SHORT")
+    }
+    return dirs.pop() if len(dirs) == 1 else "LONG"
+
+
+def hard_gates_all(features: dict, *, required_gates: list, weights: dict, min_score: float) -> dict:
+    """Require every named gate, then score survivors by a weighted sum. Port: scores.
+
+    ``features`` = merged ``{asset: {node_id: value}}``. For each asset: every key in
+    ``required_gates`` must be truthy; the score is ``sum(weights[k] * num(features[k]))``
+    over the (sorted) weight keys; keep the asset iff score >= ``min_score``. Emits a
+    ``score_map`` = ``{asset: {score, direction, reasons[], features}}``.
+    """
+    out: dict = {}
+    for asset in sorted(features):
+        rec = features[asset]
+        if not all(_truthy(rec.get(g)) for g in required_gates):
+            continue
+        score = 0.0
+        reasons: list = []
+        for gate in required_gates:
+            reasons.append(f"gate:{gate}")
+        for key in sorted(weights):
+            contribution = weights[key] * _num(rec.get(key))
+            score += contribution
+            reasons.append(f"{key}={round(contribution, 4)}")
+        if score < min_score:
+            continue
+        out[asset] = {
+            "score": round(score, 6),
+            "direction": _detect_direction(rec),
+            "reasons": reasons,
+            "features": dict(rec),
+        }
+    return out