kalshi-trading-bot-cli 2.1.6 → 2.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kalshi-trading-bot-cli",
-  "version": "2.1.6",
+  "version": "2.1.7",
   "description": "Kalshi Trading Bot CLI - AI-powered prediction market terminal.",
   "license": "MIT",
   "author": "Octagon AI, Inc.",

package/src/commands/analyze.ts

@@ -35,12 +35,25 @@ export interface AnalyzeData {
    * cache time but didn't get a newer underlying report from Octagon.
    */
   staleUpstream: boolean;
-  modelProb: number;
-  marketProb: number;
-  edge: number;
-  edgePp: string;
-  confidence: string;
-  mispricingSignal: string;
+  /**
+   * Octagon's model probability for this market. null when hasModel is
+   * false — we deliberately do NOT emit the 0.5 placeholder fallback to
+   * JSON consumers. Always check hasModel before reading this field.
+   */
+  modelProb: number | null;
+  /**
+   * Last traded market probability. null when hasMarketPrice is false.
+   * Always check hasMarketPrice before reading.
+   */
+  marketProb: number | null;
+  /** modelProb − marketProb. null when either input is unavailable. */
+  edge: number | null;
+  /** Pretty-printed edge ("+14pp"). null when edge is null. */
+  edgePp: string | null;
+  /** "very_high" | "high" | "moderate" | "low" — null when edge is null. */
+  confidence: string | null;
+  /** "underpriced" | "overpriced" | "fair_value" — null when edge is null. */
+  mispricingSignal: string | null;
   signal: string;
   drivers: PriceDriver[];
   catalysts: Catalyst[];
@@ -228,6 +241,16 @@ export async function handleAnalyze(
   const latestDbReport = getLatestReport(db, resolvedTicker);
   const reportAge = latestDbReport ? formatAge(latestDbReport.fetched_at) : null;
 
+  // Decide trading-side gating BEFORE running edge / Kelly / signal math.
+  // hasModel uses report.modelProb directly (snapshot.modelProb is just
+  // propagated unchanged from computeEdge — verified in edge-computer.ts:38).
+  // canComputeEdge is the contract: any trading decision (signal, Kelly,
+  // mispricing) must check it first. Otherwise we'd build a "BUY YES @ $X"
+  // recommendation from a 0.5 placeholder modelProb on uncovered events.
+  const hasModel = !report.cacheMiss && Number.isFinite(report.modelProb)
+    && !(report.modelProb === 0.5 && report.drivers.length === 0 && report.catalysts.length === 0);
+  const canComputeEdge = hasModel && hasMarketPrice;
+
   const snapshot = edgeComputer.computeEdge(resolvedTicker, report, marketProb);
 
   // Persist edge
@@ -264,7 +287,9 @@ export async function handleAnalyze(
     liquidityAdjusted: false,
   };
   let kelly: KellyResult;
-  if (!hasMarketPrice) {
+  if (!canComputeEdge) {
+    // Either no model coverage or no last_price → any sizing computed from
+    // a placeholder modelProb / marketProb would be meaningless.
     kelly = emptyKelly;
   } else {
     try {
@@ -316,9 +341,16 @@ export async function handleAnalyze(
   const entryPrice = (snapshot.edge > 0 ? yesAsk : noAsk);
 
   let signal: string;
-  if (!hasMarketPrice) {
-    // No tradeable price — no actionable signal. Render explicitly.
-    signal = 'no signal (market has no last traded price)';
+  if (!canComputeEdge) {
+    // Any actionable signal needs both a real model probability and a real
+    // last_price. Spell out which one is missing so the user / bot knows
+    // why we're not making a recommendation.
+    const reason = !hasModel && !hasMarketPrice
+      ? 'no Octagon model coverage and no last traded price'
+      : !hasModel
+        ? 'no Octagon model coverage for this market'
+        : 'market has no last traded price';
+    signal = `no signal (${reason})`;
   } else if (existingPosition) {
     const holdDir = existingPosition.direction.toUpperCase();
     const edgeReversed =
@@ -365,11 +397,9 @@ export async function handleAnalyze(
     ? 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);
+  // hasModel + canComputeEdge were computed earlier (above Kelly/signal),
+  // so trading-side math never reads a placeholder edge. See top of
+  // handleAnalyze for the contract.
 
   // staleUpstream = user asked for --refresh but Octagon's upstream model run
   // timestamp didn't move. Cache fetch time bumped, but the underlying report
@@ -380,6 +410,11 @@ export async function handleAnalyze(
     && latestDbReport?.analysis_last_updated != null
     && preRefreshAnalysis === latestDbReport.analysis_last_updated;
 
+  // Null out trading-side fields when the underlying inputs are unavailable.
+  // JSON consumers previously saw modelProb: 0.5 / marketProb: 0.5 / edge: 0
+  // on degraded paths and treated them as real predictions. The hasModel and
+  // hasMarketPrice flags are the source of truth — fields here mirror them.
+  // (canComputeEdge was already evaluated at the top of the function.)
   return {
     ticker: resolvedTicker,
     eventTicker,
@@ -390,12 +425,12 @@ export async function handleAnalyze(
     staleUpstream,
     hasModel,
     hasMarketPrice,
-    modelProb: snapshot.modelProb,
-    marketProb,
-    edge: snapshot.edge,
-    edgePp,
-    confidence: snapshot.confidence,
-    mispricingSignal,
+    modelProb: hasModel ? snapshot.modelProb : null,
+    marketProb: hasMarketPrice ? marketProb : null,
+    edge: canComputeEdge ? snapshot.edge : null,
+    edgePp: canComputeEdge ? edgePp : null,
+    confidence: canComputeEdge ? snapshot.confidence : null,
+    mispricingSignal: canComputeEdge ? mispricingSignal : null,
     signal,
     drivers: snapshot.drivers,
     catalysts: snapshot.catalysts,
@@ -437,17 +472,17 @@ export function formatAnalyzeHuman(data: AnalyzeData): string {
   //   hasMarketPrice=false → Kalshi market has no last_price → Market Prob shows "--"
   // Edge needs both. Either being false means edge/confidence/mispricing
   // render "--" — we never show a number derived from a placeholder.
-  const modelStr = data.hasModel
+  const modelStr = data.hasModel && data.modelProb != null
     ? `${(data.modelProb * 100).toFixed(1)}%`
     : `--   (no Octagon model coverage for this market)`;
-  const marketStr = data.hasMarketPrice
+  const marketStr = data.hasMarketPrice && data.marketProb != null
     ? `${(data.marketProb * 100).toFixed(1)}%`
     : `--   (no last traded price — market hasn't traded yet)`;
-  const canComputeEdge = data.hasModel && data.hasMarketPrice;
+  const canComputeEdge = data.hasModel && data.hasMarketPrice && data.edge != null;
   lines.push(`  Model Prob:  ${modelStr}`);
   lines.push(`  Market Prob: ${marketStr}`);
   if (canComputeEdge) {
-    lines.push(`  Edge:        ${data.edgePp} (${(data.edge * 100).toFixed(1)}%)`);
+    lines.push(`  Edge:        ${data.edgePp} (${(data.edge! * 100).toFixed(1)}%)`);
     lines.push(`  Confidence:  ${data.confidence}`);
     lines.push(`  Mispricing:  ${data.mispricingSignal}`);
   } else {
@@ -624,8 +659,12 @@ export async function promptAnalyzeActions(data: AnalyzeData): Promise<void> {
           // Close position: sell what we hold
           const sellSide = data.existingPosition.direction;
           const sellSize = data.existingPosition.size;
+          // marketProb is guaranteed when isSell is reachable (we got a SELL
+          // recommendation, which requires a price), but type system can't
+          // see that — fall back to 50 if data was tampered with.
+          const mp = data.marketProb ?? 0.5;
           const closePrice = data.closePriceCents ?? Math.round(
-            (sellSide === 'yes' ? data.marketProb : 1 - data.marketProb) * 100
+            (sellSide === 'yes' ? mp : 1 - mp) * 100
           );
 
           console.log(`  Signal: SELL ${sellSize} ${sellSide.toUpperCase()} @ ${closePrice}¢ (close position)`);
@@ -701,7 +740,7 @@ export async function promptAnalyzeActions(data: AnalyzeData): Promise<void> {
           break;
         }
 
-        const side = data.edge > 0 ? 'yes' : 'no';
+        const side = (data.edge ?? 0) > 0 ? 'yes' : 'no';
         const price = data.kelly.entryPriceCents;
         console.log(`  Signal: BUY ${data.kelly.contracts} ${side.toUpperCase()} @ ${price}¢`);
         const confirm = await ask('  Execute? [y/n] ');

package/src/commands/review.ts

@@ -10,9 +10,12 @@ export interface PositionReview {
   direction: 'yes' | 'no';
   size: number;
   entryPrice: number | null;
-  currentMarketProb: number;
-  modelProb: number;
-  edge: number;
+  /** null when analyze couldn't read a last_price for the market. */
+  currentMarketProb: number | null;
+  /** null when Octagon has no model coverage for the market. */
+  modelProb: number | null;
+  /** null when either currentMarketProb or modelProb is null. */
+  edge: number | null;
   signal: 'HOLD' | 'SELL';
   sellSide: 'yes' | 'no';
   closePriceCents: number;
@@ -62,9 +65,9 @@ export async function reviewPortfolio(): Promise<PositionReview[]> {
         direction,
         size,
         entryPrice: null,
-        currentMarketProb: 0,
-        modelProb: 0,
-        edge: 0,
+        currentMarketProb: null,
+        modelProb: null,
+        edge: null,
         signal: 'HOLD' as const,
         sellSide: direction,
         closePriceCents: 0,
@@ -74,13 +77,20 @@ export async function reviewPortfolio(): Promise<PositionReview[]> {
     }
 
     const analysis: AnalyzeData = result.value;
-    const { edge, marketProb, modelProb, kelly } = analysis;
+    const { marketProb, modelProb, kelly } = analysis;
 
-    // Determine if edge has reversed against our position
+    // Determine if edge has reversed against our position.
+    // When edge is null (no model coverage or no last_price), we can't make
+    // a quantitative call — hold and surface the data gap as the reason.
     let signal: 'HOLD' | 'SELL' = 'HOLD';
     let reason = '';
+    const edge = analysis.edge;
 
-    if (direction === 'yes' && edge < -SELL_THRESHOLD) {
+    if (edge == null) {
+      reason = !analysis.hasModel
+        ? 'No Octagon model coverage — cannot evaluate edge for this position'
+        : 'No last traded price — cannot evaluate edge for this position';
+    } else if (direction === 'yes' && edge < -SELL_THRESHOLD) {
       signal = 'SELL';
       reason = `Edge reversed: model now favors NO by ${Math.abs(edge * 100).toFixed(0)}pp`;
     } else if (direction === 'no' && edge > SELL_THRESHOLD) {
@@ -97,15 +107,13 @@ export async function reviewPortfolio(): Promise<PositionReview[]> {
     }
 
     // Use the bid-derived close price from handleAnalyze when available,
-    // fall back to marketProb approximation only if missing
+    // fall back to marketProb approximation only if both are present
     const closePriceCents =
       analysis.closePriceCents && analysis.closePriceCents > 0
         ? analysis.closePriceCents
-        : Math.round(
-            direction === 'yes'
-              ? marketProb * 100 - 1
-              : (1 - marketProb) * 100 - 1
-          );
+        : marketProb != null
+          ? Math.round(direction === 'yes' ? marketProb * 100 - 1 : (1 - marketProb) * 100 - 1)
+          : 0;
 
     return {
       ticker: pos.ticker,
@@ -140,10 +148,13 @@ export function formatReviewHuman(reviews: PositionReview[]): string {
   lines.push(`  ${reviews.length} position${reviews.length === 1 ? '' : 's'} analyzed  |  ${sells.length} SELL signal${sells.length === 1 ? '' : 's'}  |  ${holds.length} HOLD`);
   lines.push('');
 
+  const edgePpStr = (edge: number | null): string =>
+    edge == null ? '--' : `${edge >= 0 ? '+' : ''}${(edge * 100).toFixed(0)}pp`;
+
   // Show SELL signals first
   for (const r of sells) {
     const dirLabel = r.direction.toUpperCase();
-    const edgePp = `${r.edge >= 0 ? '+' : ''}${(r.edge * 100).toFixed(0)}pp`;
+    const edgePp = edgePpStr(r.edge);
     lines.push(`  ⚠  ${r.ticker}  ${dirLabel} ×${r.size}`);
     lines.push(`     Edge: ${edgePp}  |  ${r.reason}`);
     lines.push(`     → SELL ${dirLabel} @ ${r.closePriceCents}¢`);
@@ -157,7 +168,7 @@ export function formatReviewHuman(reviews: PositionReview[]): string {
   // Show HOLD positions
   for (const r of holds) {
     const dirLabel = r.direction.toUpperCase();
-    const edgePp = `${r.edge >= 0 ? '+' : ''}${(r.edge * 100).toFixed(0)}pp`;
+    const edgePp = edgePpStr(r.edge);
     lines.push(`  ✓  ${r.ticker}  ${dirLabel} ×${r.size}`);
     lines.push(`     Edge: ${edgePp}  |  ${r.reason}`);
     if (r.analyzeError) {

package/src/scan/octagon-client.ts

@@ -415,10 +415,28 @@ export class OctagonClient {
   }
 
   private extractFromMarkdown(raw: string, defaults: OctagonReport): OctagonReport {
+    // For multi-outcome reports (World Cup Silver Ball, FOMC ladders, IPO
+    // event trees), the per-outcome probabilities live in markdown tables
+    // like:
+    //   | Player       | Market % | Model % |
+    //   |--------------|----------|---------|
+    //   | Harry Kane   | 35.0%    | 36.0%   |
+    //   | Lionel Messi | 29.0%    | 40.1%   |
+    // The simple key:value regex below misses these and leaves the
+    // 0.5/0.5 placeholder. Try table extraction first, matching against the
+    // outcome suffix of the ticker (e.g. KXWCAWARD-26SBALL-HKANE → Kane).
+    let modelProb = this.extractProbFromMarkdownTable(raw, defaults.ticker, 'model');
+    let marketProb = this.extractProbFromMarkdownTable(raw, defaults.ticker, 'market');
+    if (modelProb === null) {
+      modelProb = this.extractProb(raw, /model\s*(?:prob(?:ability)?|estimate)\s*[:=]\s*([\d.]+%?)/i);
+    }
+    if (marketProb === null) {
+      marketProb = this.extractProb(raw, /market\s*(?:prob(?:ability)?|price)\s*[:=]\s*([\d.]+%?)/i);
+    }
     return {
       ...defaults,
-      modelProb: this.extractProb(raw, /model\s*(?:prob(?:ability)?|estimate)\s*[:=]\s*([\d.]+%?)/i) ?? defaults.modelProb,
-      marketProb: this.extractProb(raw, /market\s*(?:prob(?:ability)?|price)\s*[:=]\s*([\d.]+%?)/i) ?? defaults.marketProb,
+      modelProb: modelProb ?? defaults.modelProb,
+      marketProb: marketProb ?? defaults.marketProb,
       mispricingSignal: this.extractSignal(raw) ?? defaults.mispricingSignal,
       drivers: this.extractDrivers(raw),
       catalysts: this.extractCatalysts(raw),
@@ -428,6 +446,116 @@ export class OctagonClient {
     };
   }
 
+  /**
+   * Parse markdown tables in `raw` looking for a Model/Market % grid, then
+   * find the row matching `ticker`'s outcome suffix and return that row's
+   * `kind` (model | market) probability as a 0-1 fraction. Returns null when
+   * no table is found, no row matches, or the percentage can't be parsed.
+   *
+   * Matching strategy: the outcome suffix is whatever follows the last `-`
+   * in the ticker (e.g. KXWCAWARD-26SBALL-HKANE → "HKANE"). We compare it
+   * against each row's first cell (the name) by stripping non-letters and
+   * checking if either string contains the other (case-insensitive). This
+   * handles the common patterns: initial+lastname ("HKANE" ⊆ "harrykane"),
+   * country abbreviations ("MEX" ⊆ "mexico"), full names, etc.
+   *
+   * If multiple rows match we pick the strongest (longest overlap) to keep
+   * abbreviations like "MEX" from accidentally matching "MEXICO CITY".
+   */
+  private extractProbFromMarkdownTable(
+    raw: string,
+    ticker: string,
+    kind: 'model' | 'market',
+  ): number | null {
+    const suffix = ticker.split('-').pop()?.toUpperCase() ?? '';
+    if (!suffix || suffix.length < 2) return null;
+    const tickerKey = suffix.replace(/[^A-Z0-9]/g, '');
+
+    // Split into possible table blocks. Each block is a contiguous run of
+    // lines that start with `|`. A real table has >=3 lines (header, sep,
+    // body), at least 3 columns, and at least two columns whose values are
+    // percentages.
+    const lines = raw.split('\n');
+    const blocks: string[][] = [];
+    let cur: string[] = [];
+    for (const line of lines) {
+      if (line.trim().startsWith('|')) {
+        cur.push(line);
+      } else {
+        if (cur.length > 0) blocks.push(cur);
+        cur = [];
+      }
+    }
+    if (cur.length > 0) blocks.push(cur);
+
+    const parseCells = (line: string): string[] =>
+      line.split('|').slice(1, -1).map((c) => c.trim());
+    const isPercent = (s: string): boolean => /^-?\d+(\.\d+)?%?$/.test(s.replace(/[,$]/g, ''));
+    const parsePercent = (s: string): number | null => {
+      // Honor an explicit % marker in the input — "0.9%" must be 0.009, not
+      // 0.9, and "1%" must be 0.01. The legacy `n > 1 ? n/100 : n` heuristic
+      // only works when the value is unambiguously > 1 (e.g. "35%") and
+      // misreads sub-1 percentages. We only fall back to the heuristic when
+      // there's no % sign at all (raw fractions like "0.35").
+      const hasPercentSign = s.includes('%');
+      const cleaned = s.replace(/[%,$\s]/g, '');
+      const n = parseFloat(cleaned);
+      if (!Number.isFinite(n)) return null;
+      if (hasPercentSign) return n / 100;
+      return n > 1 ? n / 100 : n;
+    };
+
+    let bestMatch: { score: number; value: number } | null = null;
+    for (const block of blocks) {
+      if (block.length < 3) continue;
+      const header = parseCells(block[0]).map((c) => c.toLowerCase());
+      // Find target column. Accept "model", "model %", "model prob", etc.
+      const targetCol = header.findIndex((c) =>
+        kind === 'model'
+          ? /\bmodel\b/.test(c)
+          : /\b(market|mkt|kalshi)\b/.test(c) && !/cap/.test(c),  // avoid "market cap"
+      );
+      if (targetCol < 0) continue;
+
+      // Body starts after the separator row (line index 2). Skip rows whose
+      // cells don't look like data (e.g. another separator).
+      for (let i = 2; i < block.length; i++) {
+        const cells = parseCells(block[i]);
+        if (cells.length <= targetCol) continue;
+        const cell = cells[targetCol];
+        if (!isPercent(cell)) continue;
+        const name = (cells[0] ?? '').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
+        if (!name) continue;
+        // Match strategies (try in order, take strongest):
+        //   1. ticker fully inside row name ("MEX" in "MEXICO")
+        //   2. row name fully inside ticker ("MESSI" in "LIONELMESSI")
+        //   3. ticker suffix without leading initial(s) inside row name
+        //      ("HKANE" → "KANE" in "HARRYKANE", "LMESSI" → "MESSI" in
+        //      "LIONELMESSI"). Common Kalshi convention is one or two
+        //      initials + lastname, so we strip up to 2 leading chars.
+        let score = 0;
+        if (name.includes(tickerKey)) score = tickerKey.length;
+        else if (tickerKey.includes(name)) score = name.length;
+        else {
+          for (let drop = 1; drop <= Math.min(2, tickerKey.length - 3); drop++) {
+            const trimmed = tickerKey.slice(drop);
+            if (trimmed.length >= 3 && name.includes(trimmed)) {
+              score = Math.max(score, trimmed.length);
+              break;
+            }
+          }
+        }
+        if (score === 0) continue;
+        const v = parsePercent(cell);
+        if (v === null) continue;
+        if (!bestMatch || score > bestMatch.score) {
+          bestMatch = { score, value: v };
+        }
+      }
+    }
+    return bestMatch?.value ?? null;
+  }
+
   private inferSignal(modelProb: number | null, marketProb: number | null): MispricingSignal | null {
     if (modelProb === null || marketProb === null) return null;
     const edge = modelProb - marketProb;

package/src/tools/v2/portfolio-review.ts

@@ -27,7 +27,7 @@ export const portfolioReviewTool = new DynamicStructuredTool({
         direction: r.direction,
         size: r.size,
         edge: r.edge,
-        edgePp: `${r.edge >= 0 ? '+' : ''}${(r.edge * 100).toFixed(0)}pp`,
+        edgePp: r.edge == null ? null : `${r.edge >= 0 ? '+' : ''}${(r.edge * 100).toFixed(0)}pp`,
         signal: r.signal,
         reason: r.reason,
         closePriceCents: r.closePriceCents,