@hoox-sh/pynets 0.3.0 → 0.5.0

package/src/runtime/interpret.ts

@@ -123,6 +123,27 @@ import {
   type StubKwargs,
 } from "./library.ts";
 import { isRequestBuiltin, resolveRequest, resolveSecurity } from "./request.ts";
+import {
+  Footprint,
+  footprintBuyVolume,
+  footprintDelta,
+  footprintGetRowByPrice,
+  footprintPoc,
+  footprintRows,
+  footprintSellVolume,
+  footprintTotalVolume,
+  footprintVah,
+  footprintVal,
+  volumeRowBuyVolume,
+  volumeRowDelta,
+  volumeRowDownPrice,
+  volumeRowHasBuyImbalance,
+  volumeRowHasSellImbalance,
+  volumeRowSellVolume,
+  volumeRowTotalVolume,
+  volumeRowUpPrice,
+  type VolumeRow,
+} from "./footprint.ts";
 import { NA, PineSeries, type Cell } from "./series.ts";
 import {
   strContains,
@@ -254,6 +275,8 @@ type Value =
   | PineMap
   | PineMatrix
   | TickerId
+  | Footprint
+  | VolumeRow
   | UdtType
   | UdtInstance
   | LibraryModule
@@ -337,7 +360,7 @@ interface Env {
   onceFired: WeakSet<object>;
   /** Python `_max_bars_back_decls` — recorded only; evaluation is unbounded. */
   maxBarsBackDecls: Array<{ var: Value; num: Value }>;
-  /** Python `_alert_fire_bars` keys for `alertcondition` once_per_bar. */
+  /** Python `_alert_fire_bars` keys for `alert` / `alertcondition` freq gating. */
   alertFireBars: Map<string, number>;
 }
 
@@ -1510,6 +1533,22 @@ export const MATH_CONSTANTS: Record<string, Value> = {
   "plot.linestyle_solid": "linestyle_solid",
   "plot.linestyle_dashed": "linestyle_dashed",
   "plot.linestyle_dotted": "linestyle_dotted",
+  // Python plotting.py PlotStyle tokens — longer than hline's "solid".
+  "plot.style_line": "style_line",
+  "plot.style_linebr": "style_linebr",
+  "plot.style_stepline": "style_stepline",
+  "plot.style_steplinebr": "style_steplinebr",
+  "plot.style_stepline_diamond": "style_stepline_diamond",
+  "plot.style_histogram": "style_histogram",
+  "plot.style_columns": "style_columns",
+  "plot.style_cross": "style_cross",
+  "plot.style_area": "style_area",
+  "plot.style_areabr": "style_areabr",
+  "plot.style_circles": "style_circles",
+  // Python alerts.py `_alerts_builtin_map`.
+  "alert.freq_once_per_bar": "once_per_bar",
+  "alert.freq_once_per_bar_close": "once_per_bar_close",
+  "alert.freq_all": "all",
   "dayofweek.sunday": 1,
   "dayofweek.monday": 2,
   "dayofweek.tuesday": 3,
@@ -1889,6 +1928,8 @@ function evalCall(node: Call, env: Env): Value {
   ) {
     return evalRequestCall(fname!, node, env);
   }
+  const fpCall = evalFootprintCall(fname, node, env);
+  if (fpCall !== undefined) return fpCall;
   const arrVal = evalArrayCall(fname, node, env);
   if (arrVal !== undefined) return arrVal;
   const colorVal = evalColorCall(fname, node, env);
@@ -2577,14 +2618,66 @@ function packDrawings(book: DrawingBook): DrawingEvent[] | undefined {
   return book.items.length === 0 ? undefined : book.items;
 }
 
-/** Python `_emit_alert(..., source="alertcondition", freq=once_per_bar)`. */
-function fireAlertCondition(env: Env, title: string, message: string): void {
-  const key = `alertcondition|${title}|${message}|once_per_bar`;
-  if (env.alertFireBars.get(key) === env.barIndex) return;
+const FREQ_ONCE_PER_BAR = "once_per_bar";
+const FREQ_ONCE_PER_BAR_CLOSE = "once_per_bar_close";
+const FREQ_ALL = "all";
+
+const ALERT_FREQ_ALIASES: Record<string, string> = {
+  once_per_bar: FREQ_ONCE_PER_BAR,
+  freq_once_per_bar: FREQ_ONCE_PER_BAR,
+  "alert.freq_once_per_bar": FREQ_ONCE_PER_BAR,
+  once_per_bar_close: FREQ_ONCE_PER_BAR_CLOSE,
+  freq_once_per_bar_close: FREQ_ONCE_PER_BAR_CLOSE,
+  "alert.freq_once_per_bar_close": FREQ_ONCE_PER_BAR_CLOSE,
+  all: FREQ_ALL,
+  freq_all: FREQ_ALL,
+  "alert.freq_all": FREQ_ALL,
+};
+
+/** Python `normalize_alert_freq`. Unknown non-empty tokens are kept (still once-per-bar gated). */
+function normalizeAlertFreq(freq: unknown): string {
+  if (freq == null) return FREQ_ONCE_PER_BAR;
+  if (typeof freq === "number" && !Number.isFinite(freq)) return FREQ_ONCE_PER_BAR;
+  const s = String(freq).trim().toLowerCase().replace(/ /g, "_");
+  return ALERT_FREQ_ALIASES[s] ?? (s ? s : FREQ_ONCE_PER_BAR);
+}
+
+/** Python `_bar_is_confirmed`. This host sets `barstate.isconfirmed` to 1 on every bar. */
+function barIsConfirmed(_env: Env): boolean {
+  return true;
+}
+
+/** Python `_should_fire_alert`. */
+function shouldFireAlert(env: Env, source: string, title: string, message: string, freq: string): boolean {
+  const freqN = normalizeAlertFreq(freq);
+  if (freqN === FREQ_ALL) return true;
+  if (freqN === FREQ_ONCE_PER_BAR_CLOSE && !barIsConfirmed(env)) return false;
+  const key = `${source}|${title}|${message}|${freqN}`;
+  if (env.alertFireBars.get(key) === env.barIndex) return false;
   env.alertFireBars.set(key, env.barIndex);
+  return true;
+}
+
+/** Python `_emit_alert`. Records on the drawing book (no separate alerts array). */
+function emitAlert(
+  env: Env,
+  message: string,
+  freq: unknown,
+  opts?: { title?: string; source?: string },
+): void {
+  const source = opts?.source ?? "alert";
+  const title = opts?.title ?? "";
+  const freqN = normalizeAlertFreq(freq);
+  if (!shouldFireAlert(env, source, title, message, freqN)) return;
   env.drawings.alert(env.barIndex, message);
   const ev = env.drawings.items[env.drawings.items.length - 1];
-  if (ev != null) ev.extra = { source: "alertcondition", title, freq: "once_per_bar" };
+  if (ev == null) return;
+  ev.extra = title ? { source, title, freq: freqN } : { source, freq: freqN };
+}
+
+/** Python `_emit_alert(..., source="alertcondition", freq=once_per_bar)`. */
+function fireAlertCondition(env: Env, title: string, message: string): void {
+  emitAlert(env, message, FREQ_ONCE_PER_BAR, { title, source: "alertcondition" });
 }
 
 function inputTitle(node: Call): string | null {
@@ -2895,7 +2988,7 @@ function evalRequestSecurity(node: Call, env: Env): Cell {
   );
 }
 
-function evalRequestCall(fname: string, node: Call, env: Env): Cell {
+function evalRequestCall(fname: string, node: Call, env: Env): Value {
   if (
     fname === "request.security" ||
     fname === "request.security_lower_tf" ||
@@ -2916,10 +3009,75 @@ function evalRequestCall(fname: string, node: Call, env: Env): Cell {
     const v = resolveRequest(fname, host, { seed });
     return typeof v === "number" || v === null ? v : NA;
   }
+  if (fname === "request.footprint") {
+    const numTicks = unwrap(evalExpr(callArg(node.args, 0, ["num_ticks"]), env));
+    const va = unwrap(evalExpr(callArg(node.args, 1, ["va_percentage"]), env));
+    const v = resolveRequest(fname, host, {
+      num_ticks: numTicks ?? 100,
+      va_percentage: va ?? 70,
+    });
+    return v instanceof Footprint ? v : NA;
+  }
   const v = resolveRequest(fname, host, {});
   return typeof v === "number" || v === null ? v : NA;
 }
 
+function evalFootprintCall(fname: string | null, node: Call, env: Env): Value | undefined {
+  if (fname == null) return undefined;
+  if (fname.startsWith("footprint.")) {
+    const fp = evalExpr(callArg(node.args, 0, ["id", "footprint"]), env);
+    switch (fname) {
+      case "footprint.buy_volume":
+        return footprintBuyVolume(fp);
+      case "footprint.sell_volume":
+        return footprintSellVolume(fp);
+      case "footprint.delta":
+        return footprintDelta(fp);
+      case "footprint.total_volume":
+        return footprintTotalVolume(fp);
+      case "footprint.vah":
+        return footprintVah(fp);
+      case "footprint.val":
+        return footprintVal(fp);
+      case "footprint.poc":
+        return footprintPoc(fp);
+      case "footprint.rows": {
+        const arr = new PineArray();
+        for (const row of footprintRows(fp)) arr.push(row);
+        return arr;
+      }
+      case "footprint.get_row_by_price":
+        return footprintGetRowByPrice(fp, unwrap(evalExpr(callArg(node.args, 1, ["price"]), env)));
+      default:
+        return undefined;
+    }
+  }
+  if (fname.startsWith("volume_row.")) {
+    const vr = evalExpr(callArg(node.args, 0, ["id", "volume_row"]), env);
+    switch (fname) {
+      case "volume_row.up_price":
+        return volumeRowUpPrice(vr);
+      case "volume_row.down_price":
+        return volumeRowDownPrice(vr);
+      case "volume_row.buy_volume":
+        return volumeRowBuyVolume(vr);
+      case "volume_row.sell_volume":
+        return volumeRowSellVolume(vr);
+      case "volume_row.delta":
+        return volumeRowDelta(vr);
+      case "volume_row.total_volume":
+        return volumeRowTotalVolume(vr);
+      case "volume_row.has_buy_imbalance":
+        return volumeRowHasBuyImbalance(vr);
+      case "volume_row.has_sell_imbalance":
+        return volumeRowHasSellImbalance(vr);
+      default:
+        return undefined;
+    }
+  }
+  return undefined;
+}
+
 function evalMathCall(fname: string | null, node: Call, env: Env): Cell | undefined {
   if (fname === "math.abs" || fname === "abs") {
     return mathAbs(cellArg(node, env, 0, ["number", "x"]));
@@ -3951,6 +4109,157 @@ function evalExtraTa(fname: string | null, node: Call, env: Env, site: string):
     const z = env.ta.zigzag(site, srcArg(node, env), th);
     return tupleOf([z.high, z.low, z.dir]);
   }
+  // wave10a-start
+  const wave10aArg = (index: number, names: string[], message: string): expr => {
+    const arg = callArg(node.args, index, names);
+    if (arg == null) runtimeError(message);
+    return arg;
+  };
+  if (fname === "ta.hammer" || fname === "hammer") {
+    const msg = "ta.hammer() requires 4 arguments: open, high, low, close";
+    return env.ta.hammer(
+      unwrap(evalExpr(wave10aArg(0, ["open"], msg), env)),
+      unwrap(evalExpr(wave10aArg(1, ["high"], msg), env)),
+      unwrap(evalExpr(wave10aArg(2, ["low"], msg), env)),
+      unwrap(evalExpr(wave10aArg(3, ["close"], msg), env)),
+    );
+  }
+  if (fname === "ta.engulfing" || fname === "engulfing") {
+    const msg = "ta.engulfing() requires 4 arguments: open, high, low, close";
+    unwrap(evalExpr(wave10aArg(0, ["open"], msg), env));
+    unwrap(evalExpr(wave10aArg(1, ["high"], msg), env));
+    unwrap(evalExpr(wave10aArg(2, ["low"], msg), env));
+    unwrap(evalExpr(wave10aArg(3, ["close"], msg), env));
+    return env.ta.engulfing();
+  }
+  if (fname === "ta.gap_detector" || fname === "gap_detector") {
+    const msg = "ta.gap_detector() requires 3 arguments: high, low, prev_close";
+    return env.ta.gapDetector(
+      unwrap(evalExpr(wave10aArg(0, ["high"], msg), env)),
+      unwrap(evalExpr(wave10aArg(1, ["low"], msg), env)),
+      unwrap(evalExpr(wave10aArg(2, ["prev_close", "prev"], msg), env)),
+    );
+  }
+  if (fname === "ta.double_top_bottom" || fname === "double_top_bottom") {
+    const msg = "ta.double_top_bottom() requires 3 arguments";
+    unwrap(evalExpr(wave10aArg(0, ["high"], msg), env));
+    unwrap(evalExpr(wave10aArg(1, ["low"], msg), env));
+    return env.ta.doubleTopBottom(unwrap(evalExpr(wave10aArg(2, ["period", "length"], msg), env)));
+  }
+  if (fname === "ta.inside_bar_pattern" || fname === "inside_bar_pattern") {
+    const msg = "ta.inside_bar_pattern() requires 2 arguments";
+    unwrap(evalExpr(wave10aArg(0, ["high"], msg), env));
+    unwrap(evalExpr(wave10aArg(1, ["low"], msg), env));
+    return env.ta.insideBarPattern();
+  }
+  if (fname === "ta.macd_signal" || fname === "macd_signal") {
+    const msg = "ta.macd_signal() requires 2 arguments: macd_line, signal_line";
+    return env.ta.macdSignal(
+      unwrap(evalExpr(wave10aArg(0, ["macd_line", "macd"], msg), env)),
+      unwrap(evalExpr(wave10aArg(1, ["signal_line", "signal"], msg), env)),
+    );
+  }
+  if (fname === "ta.acceleration_factor" || fname === "acceleration_factor") {
+    const msg = "ta.acceleration_factor() requires 2 arguments";
+    return env.ta.accelerationFactor(
+      site,
+      unwrap(evalExpr(wave10aArg(0, ["momentum_list", "momentum", "source", "series"], msg), env)),
+      unwrap(evalExpr(wave10aArg(1, ["period", "length"], msg), env)),
+    );
+  }
+  if (fname === "ta.stoch_smooth" || fname === "stoch_smooth") {
+    const msg = "ta.stoch_smooth() requires 6 arguments: high, low, close, period, smooth_k, smooth_d";
+    return env.ta.stochSmooth(
+      unwrap(evalExpr(wave10aArg(0, ["high"], msg), env)),
+      unwrap(evalExpr(wave10aArg(1, ["low"], msg), env)),
+      unwrap(evalExpr(wave10aArg(2, ["close"], msg), env)),
+      unwrap(evalExpr(wave10aArg(3, ["period", "length"], msg), env)),
+      unwrap(evalExpr(wave10aArg(4, ["smooth_k", "k"], msg), env)),
+      unwrap(evalExpr(wave10aArg(5, ["smooth_d", "d"], msg), env)),
+    );
+  }
+  // wave10a-end
+  // wave10b-start
+  const wave10bList = (index: number, names: string[]): Array<number | null> => {
+    const raw = evalExpr(callArg(node.args, index, names), env);
+    const arr = asArray(raw);
+    if (arr == null) return [unwrap(raw)];
+    const out: Array<number | null> = [];
+    for (let i = 0; i < arr.size(); i++) out.push(arr.get(i));
+    return out;
+  };
+  if (fname === "ta.voi" || fname === "voi") {
+    return env.ta.voi(
+      unwrap(evalExpr(callArg(node.args, 0, ["buy_volume", "buy"]), env)),
+      unwrap(evalExpr(callArg(node.args, 1, ["sell_volume", "sell"]), env)),
+    );
+  }
+  if (fname === "ta.bid_ask_imbalance" || fname === "bid_ask_imbalance") {
+    return env.ta.bidAskImbalance(
+      unwrap(evalExpr(callArg(node.args, 0, ["bid_size", "bid"]), env)),
+      unwrap(evalExpr(callArg(node.args, 1, ["ask_size", "ask"]), env)),
+      unwrap(evalExpr(callArg(node.args, 2, ["bid_price"]), env)),
+      unwrap(evalExpr(callArg(node.args, 3, ["ask_price"]), env)),
+    );
+  }
+  if (fname === "ta.rsi_oversold_overbought" || fname === "rsi_oversold_overbought") {
+    const os = unwrap(evalExpr(callArg(node.args, 1, ["oversold_level", "oversold"]), env));
+    const ob = unwrap(evalExpr(callArg(node.args, 2, ["overbought_level", "overbought"]), env));
+    return env.ta.rsiOversoldOverbought(
+      unwrap(evalExpr(callArg(node.args, 0, ["rsi_series", "rsi", "source"]), env)),
+      os ?? Number.NaN,
+      ob ?? Number.NaN,
+    );
+  }
+  if (fname === "ta.rsi_divergence" || fname === "rsi_divergence") {
+    const period = unwrap(evalExpr(callArg(node.args, 1, ["period", "length"]), env));
+    return env.ta.rsiDivergence(wave10bList(0, ["rsi_series", "series", "source"]), period ?? 0);
+  }
+  if (fname === "ta.cumulative_delta" || fname === "cumulative_delta") {
+    const period = unwrap(evalExpr(callArg(node.args, 2, ["period", "length"]), env));
+    return env.ta.cumulativeDelta(
+      site,
+      unwrap(evalExpr(callArg(node.args, 0, ["close", "source"]), env)),
+      unwrap(evalExpr(callArg(node.args, 1, ["volume"]), env)),
+      period ?? 0,
+    );
+  }
+  if (fname === "ta.volume_momentum" || fname === "volume_momentum") {
+    const period = unwrap(evalExpr(callArg(node.args, 1, ["period", "length"]), env));
+    return env.ta.volumeMomentum(
+      site,
+      unwrap(evalExpr(callArg(node.args, 0, ["volume", "source"]), env)),
+      period ?? 0,
+    );
+  }
+  if (fname === "ta.volume_profile_high" || fname === "volume_profile_high") {
+    return env.ta.volumeProfileHigh(
+      wave10bList(0, ["close", "price", "source", "series"]),
+      wave10bList(1, ["volume"]),
+    );
+  }
+  if (fname === "ta.volume_profile_low" || fname === "volume_profile_low") {
+    const period = unwrap(evalExpr(callArg(node.args, 2, ["period", "length"]), env));
+    const levels = unwrap(evalExpr(callArg(node.args, 3, ["levels"]), env));
+    return env.ta.volumeProfileLow(
+      site,
+      unwrap(evalExpr(callArg(node.args, 0, ["close", "source"]), env)),
+      unwrap(evalExpr(callArg(node.args, 1, ["volume"]), env)),
+      period ?? 0,
+      levels ?? 0,
+    );
+  }
+  if (fname === "ta.volume_thrust" || fname === "volume_thrust") {
+    const sens = unwrap(evalExpr(callArg(node.args, 3, ["sensitivity"]), env));
+    return env.ta.volumeThrust(
+      site,
+      unwrap(evalExpr(callArg(node.args, 0, ["close", "source"]), env)),
+      unwrap(evalExpr(callArg(node.args, 1, ["volume"]), env)),
+      unwrap(evalExpr(callArg(node.args, 2, ["volume_sma", "vol_sma", "sma"]), env)),
+      sens ?? 0.3,
+    );
+  }
+  // wave10b-end
   return undefined;
 }
 
@@ -4827,8 +5136,16 @@ function evalDrawingCall(fname: string | null, node: Call, env: Env): Value | un
     return book.boxNew(env.barIndex, extra);
   }
   if (fname === "alert") {
+    // Python `_builtin_alert`: zero-arg `alert()` is a soft no-op.
+    if (asArgs(node.args).length === 0) return NA;
     const msg = evalAlertMessage(callArg(node.args, 0, ["message"]), env);
-    book.alert(env.barIndex, msg);
+    const freqExpr = callArg(node.args, 1, ["freq"]);
+    let freq: unknown = null;
+    if (freqExpr != null) {
+      const v = evalExpr(freqExpr, env);
+      freq = typeof v === "string" ? v : unwrap(v);
+    }
+    emitAlert(env, msg, freq, { source: "alert" });
     return NA;
   }
   if (fname === "table.new") {

package/src/runtime/request.ts

@@ -9,8 +9,11 @@
  * is the host's job (`bucketIndex` / `shouldForwardFill`).
  * Lower-TF request without a feed is na — no invented intra-bar array.
  * Interpret should call this from `evalCall`; this module is host-agnostic.
+ * `request.footprint` is the Python mock (not foreign-na).
  */
 
+import { createFootprint, seedFootprintRng } from "./footprint.ts";
+
 export type Cell = number | null;
 
 export interface SecurityArgs {
@@ -29,7 +32,7 @@ export interface RequestHost {
  * Named or positional args for `resolveRequest`.
  * Security uses `symbol` / `timeframe` / `sameSymbolValue`;
  * currency uses `from`/`to` (or `from_currency`/`to_currency`);
- * seed uses `seed`.
+ * seed uses `seed`; footprint uses `num_ticks` / `va_percentage`.
  */
 export interface RequestNamedArgs {
   symbol?: string | null;
@@ -41,6 +44,8 @@ export interface RequestNamedArgs {
   from_currency?: string | null;
   to_currency?: string | null;
   seed?: unknown;
+  num_ticks?: unknown;
+  va_percentage?: unknown;
 }
 
 export type RequestArgs = readonly unknown[] | RequestNamedArgs;
@@ -231,7 +236,7 @@ function bareTicker(symbol: string): string {
   return colon >= 0 ? s.slice(colon + 1) : s;
 }
 
-/** Missing / foreign fundamentals, economic, quandl, footprint → na. */
+/** Missing / foreign fundamentals, economic, quandl → na. */
 export function resolveForeignNa(): Cell {
   return null;
 }
@@ -249,9 +254,10 @@ export function resolveCurrencyRate(
   return null;
 }
 
-/** `request.seed` — record the seed (Python returns None). */
+/** `request.seed` — record the seed and seed the footprint RNG (Python returns None). */
 export function resolveSeed(seed?: unknown): Cell {
   lastSeed = coerceSeed(seed ?? 0);
+  seedFootprintRng(lastSeed);
   return null;
 }
 
@@ -262,7 +268,7 @@ export function lastRequestSeed(): number | null {
 /**
  * Dispatch a `request.*` name. Security keeps `resolveSecurity` semantics;
  * lower-TF without a feed is na; currency is 1.0 only for identical codes;
- * everything else is na.
+ * footprint is the Python mock; everything else is na.
  */
 export function resolveRequest(
   fname: string,
@@ -284,6 +290,10 @@ export function resolveRequest(
   if (fname === "request.seed") {
     return resolveSeed(seedFromArgs(args));
   }
+  if (fname === "request.footprint") {
+    const [numTicks, va] = footprintFromArgs(args);
+    return createFootprint(numTicks, va);
+  }
   return resolveForeignNa();
 }
 
@@ -326,6 +336,11 @@ function seedFromArgs(args: RequestArgs): unknown {
   return args.seed ?? 0;
 }
 
+function footprintFromArgs(args: RequestArgs): [unknown, unknown] {
+  if (!isNamedArgs(args)) return [args[0] ?? 100, args[1] ?? 70];
+  return [args.num_ticks ?? 100, args.va_percentage ?? 70];
+}
+
 function currencyPair(
   from: string | null | undefined,
   to: string | null | undefined,