kalshi-trading-bot-cli 2.1.2 → 2.1.4

package/src/commands/parse-args.ts

@@ -7,6 +7,10 @@ const SUBCOMMANDS = [
   'alerts', 'config', 'clear-cache', 'chat', 'init', 'status', 'themes',
   // Backtest
   'backtest',
+  // Octagon Kalshi search/clusters/basket (new)
+  'similar', 'clusters', 'peers', 'correlate', 'basket',
+  // Octagon events + Kalshi series rollup + editorial themes registry
+  'events', 'series', 'catalysts',
 ] as const;
 
 export type Subcommand = (typeof SUBCOMMANDS)[number];
@@ -39,6 +43,34 @@ export interface ParsedArgs {
   minVolume?: number;
   minPrice?: number;
   maxPrice?: number;
+  // Octagon Kalshi search/clusters/basket flags
+  topK?: number;
+  behavioral: boolean;
+  ranked: boolean;
+  labelContains?: string;
+  closeBefore?: string;
+  windowDays?: number;
+  correlationInterval?: '1h' | '1d';
+  timeframe?: '1w' | '1m' | '3m' | '6m' | '1y';
+  weights?: number[];
+  bankroll?: number;
+  kellyMultiplier?: number;
+  n?: number;
+  maxPerCluster?: number;
+  maxCorrelation?: number;
+  minReturn?: number;
+  seriesTicker?: string;
+  seriesPrefix?: string;
+  sortBy?: string;
+  probabilities?: string;
+  tickers?: string;
+  query?: string;
+  showCluster: boolean;
+  aggregateBy?: 'series';
+  activeOnly: boolean;
+  sides?: string;          // comma-separated yes/no per ticker for correlate
+  cells: boolean;          // include_cell_detail for correlate
+  autoProbs: boolean;      // basket size: auto-fetch leg probabilities via markets/edge
   parseErrors: string[];
 }
 
@@ -69,6 +101,34 @@ export function parseArgs(argv: string[] = process.argv.slice(2)): ParsedArgs {
   let minVolume: number | undefined;
   let minPrice: number | undefined;
   let maxPrice: number | undefined;
+  // Octagon Kalshi flags
+  let topK: number | undefined;
+  let behavioral = false;
+  let ranked = false;
+  let labelContains: string | undefined;
+  let closeBefore: string | undefined;
+  let windowDays: number | undefined;
+  let correlationInterval: '1h' | '1d' | undefined;
+  let timeframe: '1w' | '1m' | '3m' | '6m' | '1y' | undefined;
+  let weights: number[] | undefined;
+  let bankroll: number | undefined;
+  let kellyMultiplier: number | undefined;
+  let n: number | undefined;
+  let maxPerCluster: number | undefined;
+  let maxCorrelation: number | undefined;
+  let minReturn: number | undefined;
+  let seriesTicker: string | undefined;
+  let seriesPrefix: string | undefined;
+  let sortBy: string | undefined;
+  let probabilities: string | undefined;
+  let tickers: string | undefined;
+  let query: string | undefined;
+  let showCluster = false;
+  let aggregateBy: 'series' | undefined;
+  let activeOnly = false;
+  let sides: string | undefined;
+  let cells = false;
+  let autoProbs = false;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -203,6 +263,140 @@ export function parseArgs(argv: string[] = process.argv.slice(2)): ParsedArgs {
         if (Number.isFinite(numeric) && numeric >= 0 && numeric <= 100) { maxPrice = numeric; }
         else { parseErrors.push(`Invalid --max-price value: "${raw}" (expected 0-100)`); }
       } else { parseErrors.push('--max-price requires a value'); }
+    } else if (arg === '--top-k') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric) && Number.isInteger(numeric) && numeric > 0) { topK = numeric; }
+        else { parseErrors.push(`Invalid --top-k value: "${raw}" (expected a positive integer)`); }
+      } else { parseErrors.push('--top-k requires a value'); }
+    } else if (arg === '--behavioral') {
+      behavioral = true;
+    } else if (arg === '--ranked') {
+      ranked = true;
+    } else if (arg === '--show-cluster') {
+      showCluster = true;
+    } else if (arg === '--label') {
+      const val = argv[++i];
+      if (val != null) { labelContains = val; } else { parseErrors.push('--label requires a value'); }
+    } else if (arg === '--close-before') {
+      const val = argv[++i];
+      if (val != null) { closeBefore = val; } else { parseErrors.push('--close-before requires a value'); }
+    } else if (arg === '--window-days') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric) && Number.isInteger(numeric) && numeric > 0) { windowDays = numeric; }
+        else { parseErrors.push(`Invalid --window-days value: "${raw}" (expected a positive integer)`); }
+      } else { parseErrors.push('--window-days requires a value'); }
+    } else if (arg === '--correlation-interval') {
+      const val = argv[++i];
+      if (val === '1h' || val === '1d') { correlationInterval = val; }
+      else { parseErrors.push(`Invalid --correlation-interval value: "${val}" (expected "1h" or "1d")`); }
+    } else if (arg === '--timeframe') {
+      const val = argv[++i];
+      if (val === '1w' || val === '1m' || val === '3m' || val === '6m' || val === '1y') {
+        timeframe = val;
+      } else {
+        parseErrors.push(`Invalid --timeframe value: "${val}" (expected one of 1w, 1m, 3m, 6m, 1y)`);
+      }
+    } else if (arg === '--weights') {
+      const val = argv[++i];
+      if (val != null) {
+        const parts = val.split(',').map((s) => Number(s.trim()));
+        if (parts.every((p) => Number.isFinite(p))) { weights = parts; }
+        else { parseErrors.push(`Invalid --weights value: "${val}" (expected comma-separated numbers)`); }
+      } else { parseErrors.push('--weights requires a value (e.g., --weights 0.4,0.4,0.2)'); }
+    } else if (arg === '--bankroll') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric) && numeric > 0) { bankroll = numeric; }
+        else { parseErrors.push(`Invalid --bankroll value: "${raw}" (expected a positive number)`); }
+      } else { parseErrors.push('--bankroll requires a value'); }
+    } else if (arg === '--kelly') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric) && numeric >= 0 && numeric <= 1) { kellyMultiplier = numeric; }
+        else { parseErrors.push(`Invalid --kelly value: "${raw}" (expected 0-1)`); }
+      } else { parseErrors.push('--kelly requires a value (e.g., --kelly 0.25)'); }
+    } else if (arg === '-n' || arg === '--n') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric) && Number.isInteger(numeric) && numeric > 0) { n = numeric; }
+        else { parseErrors.push(`Invalid -n value: "${raw}" (expected a positive integer)`); }
+      } else { parseErrors.push('-n requires a value'); }
+    } else if (arg === '--max-per-cluster') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric) && Number.isInteger(numeric) && numeric > 0) { maxPerCluster = numeric; }
+        else { parseErrors.push(`Invalid --max-per-cluster value: "${raw}" (expected a positive integer)`); }
+      } else { parseErrors.push('--max-per-cluster requires a value'); }
+    } else if (arg === '--max-corr') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric) && numeric >= -1 && numeric <= 1) { maxCorrelation = numeric; }
+        else { parseErrors.push(`Invalid --max-corr value: "${raw}" (expected -1 to 1)`); }
+      } else { parseErrors.push('--max-corr requires a value'); }
+    } else if (arg === '--min-return') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric)) { minReturn = numeric; }
+        else { parseErrors.push(`Invalid --min-return value: "${raw}" (expected a number, e.g. 0.2 for 20%)`); }
+      } else { parseErrors.push('--min-return requires a value'); }
+    } else if (arg === '--series') {
+      const val = argv[++i];
+      if (val != null) { seriesTicker = val; } else { parseErrors.push('--series requires a value'); }
+    } else if (arg === '--series-prefix') {
+      const val = argv[++i];
+      if (val != null) { seriesPrefix = val.toUpperCase(); } else { parseErrors.push('--series-prefix requires a value'); }
+    } else if (arg === '--sort-by') {
+      const val = argv[++i];
+      if (val == null) {
+        parseErrors.push('--sort-by requires a value');
+      } else {
+        // Union across both consumers (search edge + search). Each consumer
+        // additionally filters to its own subset; this guards against typos at
+        // the CLI surface so invalid values don't silently fall through to defaults.
+        const VALID_SORT_BY = new Set([
+          // search edge (markets-with-edge)
+          'edge_pp', 'expected_return', 'total_volume', 'model_probability',
+          // search (markets)
+          'volume_24h', 'close_time', 'last_price',
+        ]);
+        if (VALID_SORT_BY.has(val)) {
+          sortBy = val;
+        } else {
+          parseErrors.push(`Invalid --sort-by value: "${val}" (expected one of ${Array.from(VALID_SORT_BY).join(', ')})`);
+        }
+      }
+    } else if (arg === '--probs') {
+      const val = argv[++i];
+      if (val != null) { probabilities = val; } else { parseErrors.push('--probs requires a value (e.g., --probs KXBTC-...:0.62,KXETH-...:0.58)'); }
+    } else if (arg === '--tickers') {
+      const val = argv[++i];
+      if (val != null) { tickers = val; } else { parseErrors.push('--tickers requires a value (comma-separated list)'); }
+    } else if (arg === '-q' || arg === '--query') {
+      const val = argv[++i];
+      if (val != null) { query = val; } else { parseErrors.push(`${arg} requires a value`); }
+    } else if (arg === '--aggregate-by') {
+      const val = argv[++i];
+      if (val === 'series') { aggregateBy = 'series'; }
+      else { parseErrors.push(`Invalid --aggregate-by value: "${val}" (expected "series")`); }
+    } else if (arg === '--active-only') {
+      activeOnly = true;
+    } else if (arg === '--sides') {
+      const val = argv[++i];
+      if (val != null) { sides = val; } else { parseErrors.push('--sides requires a value (e.g., --sides yes,no,yes)'); }
+    } else if (arg === '--cells') {
+      cells = true;
+    } else if (arg === '--auto-probs') {
+      autoProbs = true;
     } else if (arg.startsWith('--')) {
       parseErrors.push(`Unknown flag: ${arg}`);
     } else {
@@ -225,5 +419,14 @@ export function parseArgs(argv: string[] = process.argv.slice(2)): ParsedArgs {
     positionalArgs.unshift(first);
   }
 
-  return { subcommand, positionalArgs, json, theme, ticker, interval, since, minConfidence, minEdge, side, live, refresh, report, dryRun, verbose, performance, resolved, unresolved, days, maxAge, category, limit, exportPath, minVolume, minPrice, maxPrice, parseErrors };
+  return {
+    subcommand, positionalArgs, json, theme, ticker, interval, since, minConfidence, minEdge, side,
+    live, refresh, report, dryRun, verbose, performance, resolved, unresolved, days, maxAge, category,
+    limit, exportPath, minVolume, minPrice, maxPrice,
+    topK, behavioral, ranked, labelContains, closeBefore, windowDays, correlationInterval, timeframe,
+    weights, bankroll, kellyMultiplier, n, maxPerCluster, maxCorrelation, minReturn, seriesTicker,
+    sortBy, probabilities, tickers, query, showCluster, aggregateBy, activeOnly,
+    seriesPrefix, sides, cells, autoProbs,
+    parseErrors,
+  };
 }

package/src/commands/peers.ts

@@ -0,0 +1,87 @@
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import {
+  getClusterPeers,
+  getMarketClusterMembership,
+  type ClusterPeersResponse,
+  type ClusterMembership,
+} 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;
+}
+
+export type PeersResult =
+  | { kind: 'peers'; data: ClusterPeersResponse }
+  | { kind: 'membership'; data: ClusterMembership };
+
+export async function handlePeers(args: ParsedArgs): Promise<CLIResponse<PeersResult>> {
+  const ticker = args.positionalArgs[0]?.toUpperCase() ?? args.ticker?.toUpperCase();
+  if (!ticker) {
+    return wrapError('peers', 'MISSING_TICKER', 'Usage: peers <ticker> [--behavioral] [--limit N] [--show-cluster]');
+  }
+  try {
+    if (args.showCluster) {
+      const data = await getMarketClusterMembership(ticker);
+      return wrapSuccess('peers', { kind: 'membership', data });
+    }
+    const data = await getClusterPeers(ticker, {
+      kind: args.behavioral ? 'behavioral' : 'thematic',
+      limit: args.limit,
+    });
+    return wrapSuccess('peers', { kind: 'peers', data });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('peers', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatPeersHuman(result: PeersResult): string {
+  if (result.kind === 'membership') return formatMembership(result.data);
+  return formatPeers(result.data);
+}
+
+function formatPeers(data: ClusterPeersResponse): string {
+  const lines: string[] = [];
+  const c = data.cluster;
+  lines.push(`Peers for ${data.market_ticker} (${data.kind} cluster ${c.cluster_id}: "${c.label}", size ${c.size})`);
+  if (c.description) lines.push(`  ${c.description}`);
+  lines.push('');
+
+  if (data.data.length === 0) {
+    lines.push('No peer markets in this cluster.');
+    return lines.join('\n');
+  }
+
+  const rows: string[][] = data.data.map((m) => [
+    m.market_ticker,
+    truncate(m.title, 45),
+    m.distance != null ? m.distance.toFixed(3) : '-',
+    m.category ?? '-',
+  ]);
+
+  lines.push(formatTable(['Ticker', 'Title', 'Distance', 'Category'], rows));
+  return lines.join('\n');
+}
+
+function formatMembership(data: ClusterMembership): string {
+  const lines: string[] = [];
+  lines.push(`Cluster membership for ${data.market_ticker}`);
+  lines.push('');
+  if (data.thematic) {
+    lines.push(`  Thematic   cluster ${data.thematic.cluster_id}: "${data.thematic.label}" (size ${data.thematic.size})`);
+    if (data.thematic.description) lines.push(`             ${data.thematic.description}`);
+  } else {
+    lines.push('  Thematic   (not assigned in current run)');
+  }
+  if (data.behavioral) {
+    const meanRet = data.behavioral.mean_daily_return != null ? ` · mean ${(data.behavioral.mean_daily_return * 100).toFixed(2)}%/day` : '';
+    const vol = data.behavioral.daily_volatility != null ? ` · vol ${(data.behavioral.daily_volatility * 100).toFixed(2)}%/day` : '';
+    lines.push(`  Behavioral cluster ${data.behavioral.cluster_id}: "${data.behavioral.label}" (size ${data.behavioral.size})${meanRet}${vol}`);
+  } else {
+    lines.push('  Behavioral (not assigned in current run)');
+  }
+  return lines.join('\n');
+}

package/src/commands/search-remote.ts

@@ -0,0 +1,90 @@
+/**
+ * Octagon-powered search formatters that back the extended /search and
+ * /search edge code paths. Used by dispatch.ts and index.ts when
+ * OCTAGON_API_KEY is set; the legacy local-SQLite paths remain as fallback.
+ */
+import { formatTable } from './scan-formatters.js';
+import type { KalshiMarketRow, PagedResult, MarketsWithEdgeResponse } from '../scan/octagon-kalshi-api.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtMoney(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  return `$${v.toFixed(2)}`;
+}
+
+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);
+}
+
+function fmtCloseDate(iso: string | null): string {
+  if (!iso) return '-';
+  return iso.slice(0, 10);
+}
+
+export function formatMarketSearchHuman(query: string, page: PagedResult<KalshiMarketRow>): string {
+  const lines: string[] = [];
+  const more = page.has_more ? ' (more available)' : '';
+  lines.push(`Markets matching "${query}" — ${page.data.length} shown${more}`);
+  lines.push('');
+
+  if (page.data.length === 0) {
+    lines.push('No markets found.');
+    return lines.join('\n');
+  }
+
+  const rows: string[][] = page.data.map((m) => [
+    m.market_ticker,
+    truncate(m.title, 40),
+    fmtMoney(m.last_price ?? m.yes_ask),
+    fmtVol(m.volume_24h),
+    m.category ?? '-',
+    fmtCloseDate(m.close_time),
+  ]);
+  lines.push(formatTable(['Ticker', 'Title', 'Last', '24h Vol', 'Category', 'Closes'], rows));
+  return lines.join('\n');
+}
+
+export function formatMarketsWithEdgeHuman(data: MarketsWithEdgeResponse, minEdgePp: number): string {
+  const lines: string[] = [];
+  // Guard against invalid date strings — new Date('garbage').toISOString() throws RangeError.
+  let captured = 'unknown';
+  if (data.captured_at) {
+    const d = new Date(data.captured_at);
+    if (!Number.isNaN(d.getTime())) {
+      captured = d.toISOString().slice(0, 16).replace('T', ' ');
+    }
+  }
+  lines.push(`Octagon Edge Scanner (server-side) — run ${data.run_id.slice(0, 8)}, captured ${captured} UTC, sort by ${data.sort_by}`);
+  lines.push('════════════════════════════════════════════════════════');
+  lines.push('');
+
+  if (data.data.length === 0) {
+    lines.push(`  No events with |edge| ≥ ${minEdgePp}pp found.`);
+    return lines.join('\n');
+  }
+
+  const rows: string[][] = data.data.map((r, i) => [
+    String(i + 1),
+    r.market_ticker || r.event_ticker,
+    truncate(r.title, 35),
+    `${r.model_probability.toFixed(1)}%`,
+    `${r.market_probability.toFixed(1)}%`,
+    `${r.edge_pp >= 0 ? '+' : ''}${r.edge_pp.toFixed(1)}pp`,
+    `${(r.expected_return * 100).toFixed(1)}%`,
+    fmtVol(r.total_volume),
+    r.series_category ?? '-',
+  ]);
+  lines.push(formatTable(
+    ['#', 'Ticker', 'Title', 'Model', 'Market', 'Edge', 'Exp Ret', 'Volume', 'Category'],
+    rows,
+  ));
+  lines.push('');
+  lines.push(`${data.data.length} event(s) returned${data.has_more ? ' (more available)' : ''}.`);
+  return lines.join('\n');
+}