kalshi-trading-bot-cli 2.1.3 → 2.1.5

package/src/commands/analyze-batch.ts

@@ -0,0 +1,101 @@
+/**
+ * Batch analyze — fan out across multiple tickers in a single Octagon call.
+ *
+ * The full per-ticker `analyze` does deep work (resolve market, run risk gate,
+ * Kelly-size, etc.) and is slow because it makes a fresh Octagon call per
+ * ticker. When the user just wants a model-edge readout across N tickers,
+ * `POST /kalshi/markets/edge` returns them all in one shot — orders of
+ * magnitude faster.
+ *
+ * This is a complement to `analyze <ticker>`, not a replacement. Use it when
+ * you need:
+ *   - quick edge ladder across 5-100 tickers
+ *   - JSON output for downstream scripting
+ *   - refresh without paying per-ticker Octagon round-trips
+ */
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import { getMarketsEdge, type PerTickerEdgeRow } from '../scan/octagon-kalshi-api.js';
+import { formatTable } from './scan-formatters.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtVol(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1_000) return `${(v / 1_000).toFixed(1)}k`;
+  return v.toFixed(0);
+}
+
+export interface AnalyzeBatchResult {
+  run_id: string;
+  captured_at: string;
+  data: PerTickerEdgeRow[];
+  scored: number;
+  unscored: number;
+}
+
+export async function handleAnalyzeBatch(tickers: string[]): Promise<CLIResponse<AnalyzeBatchResult>> {
+  const cleaned = Array.from(new Set(
+    tickers.map((t) => t.trim().toUpperCase()).filter(Boolean),
+  ));
+  if (cleaned.length === 0) {
+    return wrapError('analyze', 'NO_TICKERS', 'analyze (batch): supply 1+ tickers');
+  }
+  if (cleaned.length > 100) {
+    return wrapError('analyze', 'TOO_MANY_TICKERS', 'analyze (batch): at most 100 tickers per call');
+  }
+  try {
+    const resp = await getMarketsEdge({ tickers: cleaned });
+    const scored = resp.data.filter((r) => r.status === 'scored').length;
+    return wrapSuccess('analyze', {
+      run_id: resp.run_id,
+      captured_at: resp.captured_at,
+      data: resp.data,
+      scored,
+      unscored: resp.data.length - scored,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('analyze', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatAnalyzeBatchHuman(data: AnalyzeBatchResult): string {
+  const lines: string[] = [];
+  lines.push(`Batch analyze — ${data.scored}/${data.data.length} scored in run ${data.run_id.slice(0, 8)} (${data.captured_at.slice(0, 16).replace('T', ' ')})`);
+  lines.push('');
+  if (data.data.length === 0) {
+    lines.push('No tickers returned.');
+    return lines.join('\n');
+  }
+  const rows: string[][] = data.data.map((r) => {
+    const status = r.status === 'scored' ? '✓' : '—';
+    const modelStr = r.model_probability == null ? '-' : `${(r.model_probability * 100).toFixed(1)}%`;
+    const marketStr = r.market_probability == null ? '-' : `${(r.market_probability * 100).toFixed(1)}%`;
+    const edgeStr = r.edge_pp == null ? '-' : `${r.edge_pp > 0 ? '+' : ''}${r.edge_pp.toFixed(1)}pp`;
+    const erStr = r.expected_return == null ? '-' : `${(r.expected_return * 100).toFixed(1)}%`;
+    return [
+      r.input_ticker,
+      status,
+      truncate(r.title ?? '', 32),
+      r.series_category ?? '-',
+      modelStr,
+      marketStr,
+      edgeStr,
+      erStr,
+      fmtVol(r.total_volume),
+    ];
+  });
+  lines.push(formatTable(
+    ['Ticker', '?', 'Title', 'Category', 'Model', 'Market', 'Edge', 'Exp Ret', 'Volume'],
+    rows,
+  ));
+  if (data.unscored > 0) {
+    lines.push('');
+    lines.push(`${data.unscored} ticker(s) not scored in this Octagon run — try \`kalshi analyze <ticker> --refresh\` for a one-off deep call.`);
+  }
+  return lines.join('\n');
+}

package/src/commands/analyze.ts

@@ -25,7 +25,16 @@ export interface AnalyzeData {
   eventTicker: string;
   title: string;
   expirationTime: string | null;
-  modelLastUpdated: string | null;
+  /** Local timestamp when we last pulled the report from Octagon. */
+  refreshedAt: string | null;
+  /** Upstream Octagon model-run timestamp (Octagon's `analysis_last_updated`). */
+  modelRunAt: string | null;
+  /**
+   * True when --refresh just ran but the upstream `analysis_last_updated`
+   * is unchanged from before the refresh. Tells the user we bumped the
+   * cache time but didn't get a newer underlying report from Octagon.
+   */
+  staleUpstream: boolean;
   modelProb: number;
   marketProb: number;
   edge: number;
@@ -40,6 +49,12 @@ export interface AnalyzeData {
   riskGate: RiskGateResult;
   liquidityGrade: string;
   fromCache: boolean;
+  /**
+   * True when Octagon has no model scoring for this market in the cached report.
+   * When true, model probability + edge fields should be rendered as "--",
+   * not as the 0.5 placeholder.
+   */
+  hasModel: boolean;
   reportAge: string | null;
   reportId: string;
   rawReport: string;
@@ -162,6 +177,15 @@ export async function handleAnalyze(
   const octagonClient = new OctagonClient(invoker, db, auditTrail);
   const edgeComputer = new EdgeComputer(db, auditTrail);
 
+  // Capture the upstream Octagon `analysis_last_updated` BEFORE the refresh
+  // so we can detect when --refresh re-fetches the same stale upstream
+  // report (cache fetch time bumped, but Octagon's underlying model run
+  // didn't move). This catches "stale upstream" cases where the user thinks
+  // they got fresh analysis but actually got the same body Octagon last
+  // generated weeks ago.
+  const preRefreshReport = refresh ? getLatestReport(db, resolvedTicker) : null;
+  const preRefreshAnalysis = preRefreshReport?.analysis_last_updated ?? null;
+
   // Use cache by default; only refresh when explicitly requested
   // Try prefetch first to avoid an individual Octagon API call
   let variant: 'cache' | 'refresh' = refresh ? 'refresh' : 'cache';
@@ -302,17 +326,42 @@ export async function handleAnalyze(
     risk_gate: gate.passed ? 'PASSED' : 'FAILED',
   });
 
-  // Model last-updated timestamp
-  const modelUpdatedAt = latestDbReport
+  // Two distinct timestamps:
+  //   refreshedAt = our local fetched_at (when WE pulled this from Octagon).
+  //                 This is the "Refreshed" date — what bumps when --refresh runs.
+  //   modelRunAt  = Octagon's analysis_last_updated (when their model last
+  //                 scored this event). Independent of our cache.
+  const refreshedAt = latestDbReport
     ? new Date(latestDbReport.fetched_at * 1000).toISOString().replace('T', ' ').slice(0, 16) + ' UTC'
     : null;
+  const modelRunAt = latestDbReport?.analysis_last_updated
+    ? latestDbReport.analysis_last_updated.replace('T', ' ').slice(0, 16) + ' UTC'
+    : null;
+
+  // hasModel = Octagon returned a real probability for this market. A
+  // cache-miss report keeps modelProb at the 0.5 placeholder; we must NOT
+  // render that as if it were a real prediction.
+  const hasModel = !report.cacheMiss && Number.isFinite(snapshot.modelProb)
+    && !(snapshot.modelProb === 0.5 && report.drivers.length === 0 && report.catalysts.length === 0);
+
+  // staleUpstream = user asked for --refresh but Octagon's upstream model run
+  // timestamp didn't move. Cache fetch time bumped, but the underlying report
+  // body is the same one Octagon previously generated. The user wanted fresh
+  // analysis; they got an unchanged stale one.
+  const staleUpstream = refresh
+    && preRefreshAnalysis != null
+    && latestDbReport?.analysis_last_updated != null
+    && preRefreshAnalysis === latestDbReport.analysis_last_updated;
 
   return {
     ticker: resolvedTicker,
     eventTicker,
     title: market.title || market.subtitle || resolvedTicker,
     expirationTime: market.expiration_time || market.expected_expiration_time || market.close_time || null,
-    modelLastUpdated: modelUpdatedAt,
+    refreshedAt,
+    modelRunAt,
+    staleUpstream,
+    hasModel,
     modelProb: snapshot.modelProb,
     marketProb,
     edge: snapshot.edge,
@@ -355,12 +404,23 @@ export function formatAnalyzeHuman(data: AnalyzeData): string {
   }
   lines.push('');
 
-  // Edge & Probabilities
-  lines.push(`  Model Prob:  ${(data.modelProb * 100).toFixed(1)}%`);
-  lines.push(`  Market Prob: ${(data.marketProb * 100).toFixed(1)}%`);
-  lines.push(`  Edge:        ${data.edgePp} (${(data.edge * 100).toFixed(1)}%)`);
-  lines.push(`  Confidence:  ${data.confidence}`);
-  lines.push(`  Mispricing:  ${data.mispricingSignal}`);
+  // Edge & Probabilities.
+  // When Octagon has no model scoring for this market (hasModel=false), render
+  // the model/edge fields as "--" instead of the 0.5 placeholder — otherwise
+  // downstream consumers (bots, dashboards) think we have a 50/50 prediction.
+  if (data.hasModel) {
+    lines.push(`  Model Prob:  ${(data.modelProb * 100).toFixed(1)}%`);
+    lines.push(`  Market Prob: ${(data.marketProb * 100).toFixed(1)}%`);
+    lines.push(`  Edge:        ${data.edgePp} (${(data.edge * 100).toFixed(1)}%)`);
+    lines.push(`  Confidence:  ${data.confidence}`);
+    lines.push(`  Mispricing:  ${data.mispricingSignal}`);
+  } else {
+    lines.push(`  Model Prob:  --   (no Octagon model coverage for this market)`);
+    lines.push(`  Market Prob: ${(data.marketProb * 100).toFixed(1)}%`);
+    lines.push(`  Edge:        --`);
+    lines.push(`  Confidence:  --`);
+    lines.push(`  Mispricing:  --`);
+  }
   lines.push('');
 
   // Price Drivers
@@ -428,15 +488,37 @@ export function formatAnalyzeHuman(data: AnalyzeData): string {
     }
   }
 
-  // Cache status & model timestamp
+  // Two distinct timestamps — labeled with the wording users actually use:
+  //
+  //   Cache refreshed at    = when the bot last fetched/re-read the Octagon
+  //                           payload. This is what bumps on --refresh.
+  //   Report body updated at = the upstream Octagon `analysis_last_updated`
+  //                            (matches the "Updated: …" date embedded in the
+  //                            report body text). Doesn't change unless
+  //                            Octagon re-runs their analysis upstream.
+  //
+  // If you're a bot/agent reading this output: use **Report body updated at**
+  // to decide whether the underlying analysis is fresh. The Cache refreshed
+  // at time only tells you when we last re-pulled the same body — it can be
+  // recent while the report itself is weeks old.
   lines.push('');
-  if (data.modelLastUpdated) {
-    lines.push(`  Model Updated: ${data.modelLastUpdated}`);
+  if (data.refreshedAt) {
+    const ageSuffix = data.reportAge ? ` (${data.reportAge})` : '';
+    lines.push(`  Cache refreshed at:    ${data.refreshedAt}${ageSuffix}`);
+    lines.push(`                         ↳ when the bot last fetched the Octagon payload; bumps on --refresh`);
+  }
+  if (data.modelRunAt) {
+    lines.push(`  Report body updated at: ${data.modelRunAt}`);
+    lines.push(`                         ↳ when Octagon last ran the model upstream (the "Updated:" date inside the report)`);
+  }
+  if (data.staleUpstream) {
+    lines.push('');
+    lines.push(`  ⚠ --refresh pulled the same Octagon report body. The cache fetch time bumped,`);
+    lines.push(`    but Octagon's upstream analysis hasn't been re-run since ${data.modelRunAt ?? 'an earlier date'}.`);
+    lines.push(`    Treat this as a stale upstream report — no newer analysis is available.`);
   }
-  if (data.fromCache && data.reportAge) {
-    lines.push(`  Data: cached (${data.reportAge}). Run \`analyze ${data.ticker} --refresh\` for latest (costs 3 credits).`);
-  } else if (data.fromCache) {
-    lines.push(`  Data: cached. Run \`analyze ${data.ticker} --refresh\` for latest (costs 3 credits).`);
+  if (data.fromCache) {
+    lines.push(`  Data: cached. Run \`analyze ${data.ticker} --refresh\` for the latest report (costs 3 credits).`);
   } else {
     lines.push('  Data: freshly generated.');
   }