Fix Kalshi broad future event titles

Author: realfishsam

changelog.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.44.6] - 2026-05-25
+
+### Fixed
+
+- **Kalshi**: Use enriched series titles to normalize contaminated broad-future event titles. Multi-market futures such as Champions League Winner and conference championship winner events no longer inherit current-matchup labels like `PSG vs Arsenal` or `Cleveland vs New York` as their PMXT event title, while true match events keep their matchup titles.
+- **Kalshi**: Add regression coverage for contaminated futures, already-sane futures, and true matchup events.
+
 ## [2.44.5] - 2026-05-25
 
 ### Fixed

core/src/exchanges/kalshi/fetcher.ts

@@ -42,15 +42,23 @@ export interface KalshiRawMarket {
 export interface KalshiRawEvent {
     event_ticker: string;
     title: string;
+    sub_title?: string;
     image_url?: string;
     category?: string;
     tags?: string[];
     series_ticker?: string;
+    series_title?: string;
+    mutually_exclusive?: boolean;
     markets?: KalshiRawMarket[];
 
     [key: string]: unknown;
 }
 
+interface KalshiSeriesInfo {
+    title?: string;
+    tags?: string[];
+}
+
 export interface KalshiRawEventPage {
     events: KalshiRawEvent[];
     cursor?: string | null;
@@ -149,7 +157,7 @@ export class KalshiFetcher implements IExchangeFetcher<KalshiRawEvent, KalshiRaw
 
     // Instance-level cache (moved from module-level)
     private cachedEvents: KalshiRawEvent[] | null = null;
-    private cachedSeriesMap: Map<string, string[]> | null = null;
+    private cachedSeriesMap: Map<string, KalshiSeriesInfo> | null = null;
     private lastCacheTime: number = 0;
 
     constructor(ctx: FetcherContext) {
@@ -205,16 +213,16 @@ export class KalshiFetcher implements IExchangeFetcher<KalshiRawEvent, KalshiRaw
                     this.fetchAllWithStatus('closed'),
                     this.fetchAllWithStatus('settled'),
                 ]);
-                return [...openEvents, ...closedEvents, ...settledEvents];
+                return this.enrichEventsWithSeriesList([...openEvents, ...closedEvents, ...settledEvents]);
             } else if (status === 'closed' || status === 'inactive') {
                 const [closedEvents, settledEvents] = await Promise.all([
                     this.fetchAllWithStatus('closed'),
                     this.fetchAllWithStatus('settled'),
                 ]);
-                return [...closedEvents, ...settledEvents];
+                return this.enrichEventsWithSeriesList([...closedEvents, ...settledEvents]);
             }
 
-            return this.fetchAllWithStatus('open');
+            return this.enrichEventsWithSeriesList(await this.fetchAllWithStatus('open'));
         } catch (error: any) {
             throw kalshiErrorMapper.mapError(error);
         }
@@ -232,7 +240,9 @@ export class KalshiFetcher implements IExchangeFetcher<KalshiRawEvent, KalshiRaw
             if (status === 'settled') apiStatus = 'settled';
 
             const limit = Math.max(1, Math.floor(params.limit || BATCH_SIZE));
-            return this.fetchPageWithStatus(apiStatus, limit, params.cursor);
+            const page = await this.fetchPageWithStatus(apiStatus, limit, params.cursor);
+            await this.enrichEventsWithSeriesList(page.events);
+            return page;
         } catch (error: any) {
             throw kalshiErrorMapper.mapError(error);
         }
@@ -366,14 +376,17 @@ export class KalshiFetcher implements IExchangeFetcher<KalshiRawEvent, KalshiRaw
         return data.orders || [];
     }
 
-    async fetchRawSeriesMap(): Promise<Map<string, string[]>> {
+    async fetchRawSeriesMap(): Promise<Map<string, KalshiSeriesInfo>> {
         try {
             const data = await this.ctx.callApi('GetSeriesList');
             const seriesList = data.series || [];
-            const map = new Map<string, string[]>();
+            const map = new Map<string, KalshiSeriesInfo>();
             for (const series of seriesList) {
-                if (series.tags && series.tags.length > 0) {
-                    map.set(series.ticker, series.tags);
+                if (series.ticker) {
+                    map.set(series.ticker, {
+                        title: typeof series.title === 'string' ? series.title : undefined,
+                        tags: Array.isArray(series.tags) ? series.tags : undefined,
+                    });
                 }
             }
             return map;
@@ -394,19 +407,23 @@ export class KalshiFetcher implements IExchangeFetcher<KalshiRawEvent, KalshiRaw
         const event = data.event;
         if (!event) return [];
 
-        // Enrich with series tags
+        // Enrich with series metadata. The series title helps the normalizer
+        // avoid polluted event titles on multi-market futures.
         if (event.series_ticker) {
             try {
                 const seriesData = await this.ctx.callApi('GetSeries', {
                     series_ticker: event.series_ticker,
                 });
                 const series = seriesData.series;
+                if (typeof series?.title === 'string' && series.title.trim()) {
+                    event.series_title = series.title.trim();
+                }
                 if (series?.tags?.length > 0 && (!event.tags || event.tags.length === 0)) {
                     event.tags = series.tags;
                 }
             } catch (err: unknown) {
-                // Non-critical — tags are enrichment only.
-                logger.warn('kalshi: series tag fetch failed', {
+                // Non-critical — series metadata is enrichment only.
+                logger.warn('kalshi: series metadata fetch failed', {
                     series_ticker: event.series_ticker,
                     error: err instanceof Error ? err.message : String(err),
                 });
@@ -438,14 +455,7 @@ export class KalshiFetcher implements IExchangeFetcher<KalshiRawEvent, KalshiRaw
             this.fetchRawSeriesMap(),
         ]);
 
-        // Enrich events with series tags
-        for (const event of allEvents) {
-            if (event.series_ticker && fetchedSeriesMap.has(event.series_ticker)) {
-                if (!event.tags || event.tags.length === 0) {
-                    event.tags = fetchedSeriesMap.get(event.series_ticker);
-                }
-            }
-        }
+        this.enrichEventsWithSeriesMap(allEvents, fetchedSeriesMap);
 
         if (fetchLimit >= 1000 && useCache) {
             this.cachedEvents = allEvents;
@@ -456,6 +466,40 @@ export class KalshiFetcher implements IExchangeFetcher<KalshiRawEvent, KalshiRaw
         return allEvents;
     }
 
+    private async enrichEventsWithSeriesList(events: KalshiRawEvent[]): Promise<KalshiRawEvent[]> {
+        if (events.length === 0) return events;
+
+        try {
+            const seriesMap = await this.fetchRawSeriesMap();
+            this.enrichEventsWithSeriesMap(events, seriesMap);
+        } catch (err: unknown) {
+            // Non-critical — callers can still normalize the venue-native title.
+            logger.warn('kalshi: series list enrichment failed', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+
+        return events;
+    }
+
+    private enrichEventsWithSeriesMap(
+        events: KalshiRawEvent[],
+        seriesMap: Map<string, KalshiSeriesInfo>,
+    ): void {
+        for (const event of events) {
+            if (!event.series_ticker) continue;
+            const seriesInfo = seriesMap.get(event.series_ticker);
+            if (!seriesInfo) continue;
+
+            if (seriesInfo.title) {
+                event.series_title = seriesInfo.title;
+            }
+            if (seriesInfo.tags?.length && (!event.tags || event.tags.length === 0)) {
+                event.tags = seriesInfo.tags;
+            }
+        }
+    }
+
     private async fetchActiveEvents(targetMarketCount?: number, status: string = 'open'): Promise<KalshiRawEvent[]> {
         let allEvents: KalshiRawEvent[] = [];
         let totalMarketCount = 0;

core/src/exchanges/kalshi/normalizer.ts

@@ -105,7 +105,7 @@ export class KalshiNormalizer implements IExchangeNormalizer<KalshiRawEvent, Kal
 
         return {
             id: raw.event_ticker,
-            title: raw.title,
+            title: this.deriveEventTitle(raw),
             description: this.deriveEventDescription(raw.markets || []),
             slug: raw.event_ticker,
             markets,
@@ -325,6 +325,149 @@ export class KalshiNormalizer implements IExchangeNormalizer<KalshiRawEvent, Kal
         return texts[0];
     }
 
+    private deriveEventTitle(event: KalshiRawEvent): string {
+        const rawTitle = this.cleanLabel(event.title) || event.event_ticker;
+        const seriesTitle = this.cleanLabel(event.series_title);
+        const markets = event.markets || [];
+
+        if (!seriesTitle || !this.shouldUseSeriesTitle(event, markets)) {
+            return rawTitle;
+        }
+
+        return this.composeSeriesTitle(seriesTitle, this.deriveCommonEventTitle(event, markets));
+    }
+
+    private shouldUseSeriesTitle(event: KalshiRawEvent, markets: KalshiRawMarket[]): boolean {
+        if (event.mutually_exclusive !== true) return false;
+        if (markets.length < 4) return false;
+
+        const rawTitle = this.cleanLabel(event.title);
+        if (!rawTitle) return false;
+
+        const titleLooksScoped = /(?:\bvs\.?\b|\bversus\b|:)/i.test(rawTitle);
+        if (!titleLooksScoped) return false;
+
+        const candidateLabels = markets
+            .map((market) => this.deriveOutcomeLabel(market))
+            .filter((label): label is string => label != null && label.length >= 3);
+
+        if (candidateLabels.length < 4) return false;
+
+        const normalizedTitle = this.normalizeTitleText(rawTitle);
+        const containedLabels = new Set<string>();
+        for (const label of candidateLabels) {
+            const normalizedLabel = this.normalizeTitleText(label);
+            if (normalizedLabel && normalizedTitle.includes(normalizedLabel)) {
+                containedLabels.add(normalizedLabel);
+            }
+        }
+
+        return containedLabels.size >= 2;
+    }
+
+    private deriveCommonEventTitle(event: KalshiRawEvent, markets: KalshiRawMarket[]): string | null {
+        const eventTitlePrefix = this.extractEventTitlePrefix(event.title);
+        if (eventTitlePrefix) {
+            if (this.hasWinVerb(eventTitlePrefix)) return 'Winner';
+            if (this.hasResolutionTerm(eventTitlePrefix)) return eventTitlePrefix;
+        }
+
+        const candidates = new Map<string, number>();
+
+        for (const market of markets) {
+            const marketTitle = this.cleanLabel(market.title);
+            if (!marketTitle) continue;
+
+            const outcomeLabel = this.deriveOutcomeLabel(market);
+            const candidate = this.extractEventTitleFromMarketTitle(marketTitle, outcomeLabel);
+            if (!candidate) continue;
+
+            candidates.set(candidate, (candidates.get(candidate) ?? 0) + 1);
+        }
+
+        let best: string | null = null;
+        let bestCount = 0;
+        for (const [candidate, count] of candidates.entries()) {
+            if (count > bestCount) {
+                best = candidate;
+                bestCount = count;
+            }
+        }
+
+        return best;
+    }
+
+    private extractEventTitleFromMarketTitle(title: string, outcomeLabel: string | null): string | null {
+        const escapedOutcome = outcomeLabel ? this.escapeRegExp(outcomeLabel) : '[^?]+?';
+        const winPattern = new RegExp(`^Will (?:the )?${escapedOutcome} win (?:the )?(.+?)\\??$`, 'i');
+        const winMatch = title.match(winPattern);
+        if (winMatch?.[1]) {
+            return this.ensureWinnerTitle(winMatch[1].trim());
+        }
+
+        const plainWinnerMatch = title.match(/^(.+? Winner)\??$/i);
+        if (plainWinnerMatch?.[1]) return plainWinnerMatch[1].trim();
+
+        const championMatch = title.match(/^(.+? Champion(?:ship)?)\??$/i);
+        if (championMatch?.[1]) return championMatch[1].trim();
+
+        return null;
+    }
+
+    private composeSeriesTitle(seriesTitle: string, commonTitle: string | null): string {
+        if (!commonTitle) return seriesTitle;
+
+        let title = seriesTitle;
+        const year = commonTitle.match(/^\s*(20\d{2})\b/)?.[1];
+        if (year && !new RegExp(`\\b${year}\\b`).test(title)) {
+            title = `${year} ${title}`;
+        }
+
+        if (this.hasResolutionTerm(title)) {
+            return title;
+        }
+
+        const resolutionTerm = this.extractResolutionTerm(commonTitle);
+        if (resolutionTerm) {
+            return `${title} ${resolutionTerm}`;
+        }
+
+        return title;
+    }
+
+    private ensureWinnerTitle(title: string): string {
+        if (this.hasResolutionTerm(title)) return title;
+        return `${title} Winner`;
+    }
+
+    private hasResolutionTerm(title: string): boolean {
+        return /\b(winner|champion|championship|nominee|nomination|election|finals?|cup|award)\b/i.test(title);
+    }
+
+    private extractEventTitlePrefix(title: string): string | null {
+        const match = title.match(/^(.+?)(?:\s*:\s*|\s+[-\u2013\u2014]\s+)(.+)$/u);
+        const prefix = match?.[1]?.trim();
+        if (prefix && this.normalizeTitleText(prefix) === 'series winner') return null;
+        return prefix || null;
+    }
+
+    private extractResolutionTerm(title: string): string | null {
+        const match = title.match(/\b(Winner|Champion|Championship|Nominee|Nomination|Election|Finals?|Cup|Award)\b\s*$/i);
+        return match?.[1] || null;
+    }
+
+    private hasWinVerb(title: string): boolean {
+        return /\bwin(?:s|ning)?\b/i.test(title);
+    }
+
+    private normalizeTitleText(value: string): string {
+        return value.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+    }
+
+    private escapeRegExp(value: string): string {
+        return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+
     private deriveOutcomeLabel(market: KalshiRawMarket): string | null {
         const yesSubtitle = this.cleanLabel(market.yes_sub_title);
         if (yesSubtitle) return yesSubtitle;