@semanticintent/semantic-chirp-intelligence-mcp 3.1.0 → 4.0.0

package/build/analyses/DraftPickAnalysis.js

@@ -0,0 +1,431 @@
+/**
+ * 🎯 Draft Pick Analysis — ICE at the draft table
+ *
+ * Answers one question: with pick N on the clock, who should you take?
+ *
+ * A public draft board ranks players in the abstract. This ranks them against
+ * *your* draft: who is already gone, what your roster is still missing, what
+ * your league's categories reward, and what each player's club schedule is
+ * worth in the weeks your league plays its playoffs.
+ *
+ * Value is measured as ADP delta — Yahoo's own average draft position minus
+ * the pick actually on the clock — so "value" means the market is wrong here,
+ * not "this player is good".
+ *
+ * Semantic Identity: ICE - Intent Chirp Engine (Draft)
+ * Intent: I tell you who to take, and why the board is wrong
+ * Chirp Style: ice_cold_truth
+ */
+import { AnalysisTemplate } from '../template/AnalysisTemplate.js';
+import { ChirpIntelligence } from '../services/ChirpIntelligence.js';
+import { NHL_SCHEDULE, NhlScheduleService } from '../services/NhlScheduleService.js';
+import { toNhlTricode } from '../domain/nhl-teams.js';
+import { LEAGUE_DATA, LeagueDataService } from '../services/LeagueDataService.js';
+import { NHL_STATS } from '../services/NhlStatsService.js';
+/** Skater and goalie slots this analysis reasons about. */
+const TRACKED_POSITIONS = ['C', 'LW', 'RW', 'D', 'G'];
+export class DraftPickAnalysis extends AnalysisTemplate {
+    constructor() {
+        super('chirp_draft_pick', 'draft_pick');
+    }
+    // ==========================================
+    // Hook 1: Fetch
+    // ==========================================
+    async fetchData(args) {
+        await Promise.all([NHL_STATS.load(), NHL_SCHEDULE.load(), NHL_SCHEDULE.loadStandings()]);
+        // v4: the board is every NHL player, ranked on last season's production.
+        // Yahoo's ADP is gone, so "value" is measured against production rank
+        // rather than against where a market drafts a player.
+        return {
+            pool: LEAGUE_DATA.getPlayerPool({ limit: Math.min(args.pool_size ?? 250, 400) }),
+            roster: LEAGUE_DATA.getRoster(),
+            pool_caveat: LeagueDataService.POOL_CAVEAT
+        };
+    }
+    // ==========================================
+    // Hook 2: Prepare
+    // ==========================================
+    async prepareData(rawData, args) {
+        // Board state comes entirely from what the user tells us — there is no
+        // platform to ask. `already_drafted` is therefore the source, not a
+        // fallback, and the pick number follows from it unless stated.
+        const draftedNames = new Set((args.already_drafted ?? []).map(n => this.normalizeName(n)));
+        const rosterPositions = {};
+        for (const p of rawData.roster?.players ?? []) {
+            for (const pos of String(p.position ?? '').split(',')) {
+                const clean = pos.trim().toUpperCase();
+                if (TRACKED_POSITIONS.includes(clean)) {
+                    rosterPositions[clean] = (rosterPositions[clean] ?? 0) + 1;
+                }
+            }
+        }
+        // Rank the pool by production; that rank stands in for a draft board.
+        const pool = (rawData.pool ?? []).map((p, index) => ({
+            player_id: p.player_id,
+            name: p.name,
+            position: p.position,
+            positions: String(p.position ?? '').split(',').map((x) => x.trim().toUpperCase()).filter(Boolean),
+            team: p.team,
+            // Production rank is the board position: the Nth best producer is,
+            // absent a market, the Nth pick worth making.
+            average_pick: index + 1,
+            average_round: null,
+            percent_drafted: null,
+            stats: p.stats ?? null
+        }));
+        return {
+            draftPool: pool,
+            draftedIds: new Set(),
+            draftedNames,
+            draftedCount: draftedNames.size,
+            draftResultsAvailable: false,
+            manualDraftedCount: draftedNames.size,
+            rosterPositions,
+            playoffWindow: this.resolvePlayoffWindow(null),
+            poolCaveat: rawData.pool_caveat
+        };
+    }
+    // ==========================================
+    // Hook 3: Analyze
+    // ==========================================
+    async analyzeData(data, args) {
+        const d = data;
+        const maxResults = args.max_results ?? 8;
+        // Pick on the clock: explicit, else inferred from picks already made.
+        const pickNumber = args.pick_number ?? (Math.max(d.draftedCount, d.draftedNames.size) + 1);
+        const needs = args.roster_needs?.length
+            ? args.roster_needs.map(p => p.toUpperCase())
+            : this.inferNeeds(d.rosterPositions);
+        // Yahoo's REST draft results can lag a fast live draft, so `already_drafted`
+        // is a first-class second source rather than a fallback: a player is off
+        // the board if either source says so.
+        const available = d.draftPool.filter((p) => !d.draftedIds.has(String(p.player_id)) &&
+            !d.draftedNames.has(this.normalizeName(p.name)));
+        const candidates = available
+            .map((p) => this.rateCandidate(p, pickNumber, needs, d.playoffWindow))
+            .sort((a, b) => b.draft_score - a.draft_score)
+            .slice(0, maxResults);
+        return {
+            pick_number: pickNumber,
+            pick_number_source: args.pick_number ? 'explicit' : 'inferred from draft results',
+            roster_needs: needs,
+            pool_size: d.draftPool.length,
+            available_count: available.length,
+            players_off_board: d.draftedIds.size + d.draftedNames.size,
+            draft_results_available: d.draftResultsAvailable,
+            manual_drafted_count: d.manualDraftedCount,
+            playoff_window: d.playoffWindow,
+            pool_caveat: d.poolCaveat,
+            schedule_available: NHL_SCHEDULE.isAvailable(),
+            candidates
+        };
+    }
+    // ==========================================
+    // Hook 4: Chirp
+    // ==========================================
+    async generateChirp(analysisResults, semanticContract, data) {
+        const contract = this.mergeContractWithDefaults(semanticContract);
+        const enhanced = ChirpIntelligence.enhance(this.toolName, analysisResults, contract);
+        const top = analysisResults.candidates[0];
+        let chirp;
+        if (!top) {
+            chirp = 'Nobody left worth chirping about. Either the pool is empty or everyone is drafted.';
+        }
+        else if (top.adp_delta !== null && top.adp_delta >= 12) {
+            chirp =
+                `${top.name} is still sitting there at ${analysisResults.pick_number} and the room ` +
+                    `usually takes him at ${top.average_pick}. That is ${Math.round(top.adp_delta)} picks of ` +
+                    `free value. Take him before someone wakes up.`;
+        }
+        else if (top.fills_need) {
+            chirp =
+                `${top.name} fills the hole you actually have (${top.position}), and ` +
+                    `${top.team} plays ${top.playoff_games ?? '?'} games in your playoff window. ` +
+                    `Best available is a luxury; a full lineup is not.`;
+        }
+        else {
+            chirp =
+                `${top.name} is the pick. No bargain, no drama — just the best board-and-schedule ` +
+                    `combination left at ${analysisResults.pick_number}.`;
+        }
+        if (analysisResults.players_off_board === 0) {
+            chirp +=
+                ' ⚠️ Nobody is marked as drafted yet — pass `already_drafted` as picks go by ' +
+                    'and this board stays accurate.';
+        }
+        return {
+            ...enhanced,
+            chirp_intelligence: {
+                ...enhanced.chirp_intelligence,
+                analysis_chirp: chirp
+            }
+        };
+    }
+    // ==========================================
+    // Hook 5: Format
+    // ==========================================
+    async formatResponse(chirpEnhanced, data) {
+        const candidates = chirpEnhanced.candidates ?? [];
+        const recommendations = candidates.map((c, index) => ({
+            priority: index === 0 ? 'CRITICAL' : index < 3 ? 'HIGH' : 'MEDIUM',
+            action: 'draft',
+            reasoning: c.reasoning
+        }));
+        const analysisInsights = {
+            pick_number: chirpEnhanced.pick_number,
+            pick_number_source: chirpEnhanced.pick_number_source,
+            roster_needs: chirpEnhanced.roster_needs,
+            players_off_board: chirpEnhanced.players_off_board,
+            board_state: `${chirpEnhanced.players_off_board} player(s) marked as already drafted. ` +
+                'Board state comes from `already_drafted` — there is no platform to read it from, ' +
+                'so tell me who has gone and the board updates.',
+            board_note: chirpEnhanced.pool_caveat,
+            schedule_source: chirpEnhanced.schedule_available
+                ? `NHL public API (season ${NHL_SCHEDULE.getSeason()})`
+                : `UNAVAILABLE - ${NHL_SCHEDULE.getUnavailableReason()}; schedule value excluded from scoring`,
+            playoff_window: chirpEnhanced.playoff_window,
+            top_candidates: candidates
+        };
+        const metadata = {
+            analysis_type: this.analysisType,
+            timestamp: new Date().toISOString(),
+            team_context: { team_name: 'Draft Board' },
+            semantic_contract_applied: true
+        };
+        return {
+            analysis_insights: analysisInsights,
+            recommendations,
+            chirp_intelligence: chirpEnhanced.chirp_intelligence,
+            metadata
+        };
+    }
+    // ==========================================
+    // 🎯 Scoring
+    // ==========================================
+    rateCandidate(player, pickNumber, needs, window) {
+        const averagePick = player.average_pick;
+        const adpDelta = averagePick !== null ? pickNumber - averagePick : null;
+        const tricode = toNhlTricode(player.team);
+        const profile = tricode && NHL_SCHEDULE.isAvailable()
+            ? NHL_SCHEDULE.getTeamProfile(tricode)
+            : null;
+        const playoffGames = profile && window?.start && window?.end
+            ? NHL_SCHEDULE.countGamesInRange(tricode, window.start, window.end)
+            : null;
+        const fillsNeed = needs.some(need => player.positions.includes(need));
+        // --- components, each 0-1 ---
+        // Value: how far past his usual draft slot he has fallen. A player going
+        // 20 picks later than the market takes him is the whole point.
+        const valueComponent = adpDelta === null
+            ? 0.5
+            : Math.max(0, Math.min(1, (adpDelta + 10) / 40));
+        // Board rank: earlier average pick is a better player, all else equal.
+        const rankComponent = averagePick === null
+            ? 0.3
+            : Math.max(0, Math.min(1, 1 - (averagePick / 250)));
+        // Schedule: playoff-window volume, normalized against a 4-game week.
+        const weekCount = window?.weeks?.length ?? 0;
+        const scheduleComponent = playoffGames !== null && weekCount > 0
+            ? Math.min(1, (playoffGames / weekCount) / 4)
+            : 0.5;
+        const needComponent = fillsNeed ? 1 : 0;
+        const score = (0.40 * valueComponent) +
+            (0.30 * rankComponent) +
+            (0.18 * needComponent) +
+            (0.12 * scheduleComponent);
+        return {
+            player_id: player.player_id,
+            name: player.name,
+            position: player.position,
+            team: player.team,
+            average_pick: averagePick,
+            percent_drafted: player.percent_drafted,
+            adp_delta: adpDelta === null ? null : Number(adpDelta.toFixed(1)),
+            playoff_games: playoffGames,
+            four_game_weeks: profile?.weeks_with_4_plus ?? null,
+            fills_need: fillsNeed,
+            draft_score: Math.round(score * 100),
+            verdict: this.verdictFor(adpDelta),
+            reasoning: this.reasoningFor(player, adpDelta, playoffGames, weekCount, fillsNeed)
+        };
+    }
+    verdictFor(adpDelta) {
+        if (adpDelta === null)
+            return 'FAIR';
+        if (adpDelta >= 20)
+            return 'STEAL';
+        if (adpDelta >= 8)
+            return 'VALUE';
+        if (adpDelta <= -12)
+            return 'REACH';
+        return 'FAIR';
+    }
+    reasoningFor(player, adpDelta, playoffGames, weekCount, fillsNeed) {
+        const parts = [`${player.name} (${player.position}, ${player.team})`];
+        if (adpDelta === null) {
+            parts.push('no Yahoo ADP available');
+        }
+        else if (adpDelta > 0) {
+            parts.push(`${Math.round(adpDelta)} picks past his ADP of ${player.average_pick}`);
+        }
+        else if (adpDelta < 0) {
+            parts.push(`${Math.abs(Math.round(adpDelta))} picks ahead of his ADP of ${player.average_pick}`);
+        }
+        else {
+            parts.push(`right at his ADP of ${player.average_pick}`);
+        }
+        if (playoffGames !== null && weekCount > 0) {
+            parts.push(`${playoffGames} games across your ${weekCount} playoff weeks`);
+        }
+        if (fillsNeed)
+            parts.push('fills a roster hole');
+        return parts.join(' — ') + '.';
+    }
+    // ==========================================
+    // 🎯 Roster needs
+    // ==========================================
+    /** Positions with the thinnest coverage on the current roster. */
+    inferNeeds(rosterPositions) {
+        const counts = TRACKED_POSITIONS.map(pos => ({ pos, count: rosterPositions[pos] ?? 0 }));
+        const minimum = Math.min(...counts.map(c => c.count));
+        return counts.filter(c => c.count === minimum).map(c => c.pos);
+    }
+    // ==========================================
+    // 🎯 Yahoo parsing (defensive)
+    // ==========================================
+    /**
+     * Yahoo's fantasy JSON alternates between arrays and count-keyed objects
+     * depending on the resource and, in places, the request. Everything below
+     * accepts either shape and returns empty rather than throwing, so a shape
+     * change degrades one field instead of the whole draft tool.
+     */
+    keyedEntries(container) {
+        if (!container)
+            return [];
+        if (Array.isArray(container))
+            return container;
+        return Object.keys(container)
+            .filter(k => k !== 'count')
+            .map(k => container[k]);
+    }
+    parsePlayerPool(poolPages) {
+        const players = [];
+        for (const page of poolPages ?? []) {
+            if (!page)
+                continue;
+            const container = page?.fantasy_content?.league?.[1]?.players ??
+                page?.fantasy_content?.league?.players;
+            for (const entry of this.keyedEntries(container)) {
+                const player = entry?.player;
+                if (!player)
+                    continue;
+                const identity = Array.isArray(player[0]) ? player[0] : [];
+                const find = (key) => identity.find((item) => item?.[key])?.[key];
+                const name = find('name')?.full;
+                const playerId = find('player_id');
+                if (!name || !playerId)
+                    continue;
+                // draft_analysis rides on the second element, occasionally nested.
+                const analysis = player[1]?.draft_analysis ??
+                    player[1]?.[0]?.draft_analysis ??
+                    (Array.isArray(player[1])
+                        ? player[1].find((item) => item?.draft_analysis)?.draft_analysis
+                        : undefined);
+                const displayPosition = find('display_position') ?? '';
+                players.push({
+                    player_id: String(playerId),
+                    name,
+                    position: displayPosition,
+                    positions: String(displayPosition)
+                        .split(',')
+                        .map((p) => p.trim().toUpperCase())
+                        .filter(Boolean),
+                    team: find('editorial_team_abbr') ?? '',
+                    average_pick: this.toNumberOrNull(analysis?.average_pick),
+                    average_round: this.toNumberOrNull(analysis?.average_round),
+                    percent_drafted: this.toNumberOrNull(analysis?.percent_drafted)
+                });
+            }
+        }
+        // Same player can appear across pages; keep one.
+        return Array.from(new Map(players.map(p => [p.player_id, p])).values());
+    }
+    parseDraftResults(payload) {
+        const container = payload?.fantasy_content?.league?.[1]?.draft_results ??
+            payload?.fantasy_content?.league?.draft_results;
+        const entries = this.keyedEntries(container);
+        if (entries.length === 0) {
+            return { available: false, count: 0, ids: new Set() };
+        }
+        const ids = new Set();
+        let count = 0;
+        for (const entry of entries) {
+            const result = entry?.draft_result ?? entry;
+            if (!result?.player_key)
+                continue;
+            count++;
+            // Draft results carry player_key (`nhl.p.1234`), never a name, so the
+            // board state is matched to the pool by id.
+            const id = String(result.player_key).split('.').pop();
+            if (id)
+                ids.add(id);
+        }
+        return { available: count > 0, count, ids };
+    }
+    parseRosterPositions(payload) {
+        const counts = {};
+        const container = payload?.fantasy_content?.team?.[1]?.roster?.['0']?.players ??
+            payload?.fantasy_content?.team?.[1]?.roster?.players;
+        for (const entry of this.keyedEntries(container)) {
+            const player = entry?.player;
+            if (!player)
+                continue;
+            const identity = Array.isArray(player[0]) ? player[0] : [];
+            const displayPosition = identity.find((item) => item?.display_position)?.display_position;
+            for (const pos of String(displayPosition ?? '').split(',')) {
+                const clean = pos.trim().toUpperCase();
+                if (TRACKED_POSITIONS.includes(clean)) {
+                    counts[clean] = (counts[clean] ?? 0) + 1;
+                }
+            }
+        }
+        return counts;
+    }
+    resolvePlayoffWindow(settings) {
+        const leagueMeta = settings?.fantasy_content?.league?.[0] ?? {};
+        const leagueSettings = settings?.fantasy_content?.league?.[1]?.settings?.[0] ?? {};
+        const startDate = leagueMeta.start_date;
+        const endWeek = Number(leagueMeta.end_week ?? leagueSettings.end_week ?? 0);
+        const playoffStartWeek = Number(leagueSettings.playoff_start_week ?? 0);
+        if (!startDate || !playoffStartWeek || !endWeek || playoffStartWeek > endWeek) {
+            return { resolved: false, start: null, end: null, weeks: [] };
+        }
+        const week1Monday = NhlScheduleService.weekStart(startDate);
+        const weeks = [];
+        for (let week = playoffStartWeek; week <= endWeek; week++) {
+            weeks.push(NhlScheduleService.addDays(week1Monday, (week - 1) * 7));
+        }
+        return {
+            resolved: true,
+            playoff_start_week: playoffStartWeek,
+            end_week: endWeek,
+            start: NhlScheduleService.addDays(week1Monday, (playoffStartWeek - 1) * 7),
+            end: NhlScheduleService.addDays(week1Monday, endWeek * 7 - 1),
+            weeks
+        };
+    }
+    toNumberOrNull(value) {
+        if (value === undefined || value === null || value === '' || value === '-')
+            return null;
+        const parsed = parseFloat(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    /** Case- and punctuation-insensitive name key for matching drafted players. */
+    normalizeName(name) {
+        return String(name)
+            .toLowerCase()
+            .normalize('NFD')
+            .replace(/[̀-ͯ]/g, '')
+            .replace(/[^a-z0-9]/g, '');
+    }
+}

package/build/analyses/GamesInHandAnalysis.js

@@ -7,133 +7,36 @@
  */
 import { AnalysisTemplate } from '../template/AnalysisTemplate.js';
 import { ChirpIntelligence } from '../services/ChirpIntelligence.js';
+import { NHL_SCHEDULE, NhlScheduleService } from '../services/NhlScheduleService.js';
+import { LEAGUE_DATA, NO_ROSTER_MESSAGE, NO_OPPONENT_MESSAGE } from '../services/LeagueDataService.js';
+import { NHL_STATS } from '../services/NhlStatsService.js';
 export class GamesInHandAnalysis extends AnalysisTemplate {
-    apiClient;
-    leagueId;
-    teamId;
-    constructor(apiClient, leagueId, teamId) {
+    constructor() {
         super("get_games_in_hand", "schedule_advantage");
-        this.apiClient = apiClient;
-        this.leagueId = leagueId;
-        this.teamId = teamId;
     }
     /**
      * Hook 1: Fetch raw data from Yahoo API
      */
     async fetchData(args) {
-        try {
-            // Fetch current matchup data
-            const matchupData = await this.apiClient.getTeamMatchup(this.leagueId, this.teamId);
-            // Fetch league scoreboard for schedule data
-            const scoreboardData = await this.apiClient.getLeagueScoreboard(this.leagueId);
-            return {
-                matchup: matchupData,
-                scoreboard: scoreboardData
-            };
-        }
-        catch (error) {
-            throw new Error(`Failed to fetch games in hand data: ${error}`);
-        }
+        await Promise.all([NHL_STATS.load(), NHL_SCHEDULE.load()]);
+        const roster = LEAGUE_DATA.getRoster();
+        if (!roster)
+            throw new Error(NO_ROSTER_MESSAGE);
+        const opponent = LEAGUE_DATA.getOpponentRoster();
+        if (!opponent)
+            throw new Error(NO_OPPONENT_MESSAGE);
+        return { roster, opponent };
     }
     /**
      * Hook 2: Prepare data into FantasyData structure
      */
     async prepareData(rawData, args) {
-        const { matchup, scoreboard } = rawData;
-        // Parse matchup to find opponent - try multiple potential structures
-        let teams = matchup.fantasy_content?.team?.[1]?.matchup?.['0']?.teams?.['0']?.team || [];
-        // If teams is empty, try alternative structure (matchups array)
-        if (teams.length === 0) {
-            const matchups = matchup.fantasy_content?.team?.[1]?.matchups;
-            if (matchups && matchups.count !== '0') {
-                // Find the current matchup where status === "midevent"
-                const matchupKeys = Object.keys(matchups).filter(key => key !== 'count');
-                const currentMatchupKey = matchupKeys.find(key => {
-                    const matchupData = matchups[key]?.matchup?.[0] || matchups[key]?.matchup;
-                    return matchupData?.status === 'midevent';
-                });
-                // Use current matchup if found, otherwise fallback to last matchup
-                const selectedKey = currentMatchupKey || matchupKeys[matchupKeys.length - 1];
-                if (selectedKey && matchups[selectedKey]?.matchup?.[0]) {
-                    teams = matchups[selectedKey].matchup[0].teams?.['0']?.team || [];
-                }
-            }
-        }
-        // Handle both full team IDs (nhl.l.123.t.1) and partial (just the number)
-        const cleanLeagueId = this.leagueId.replace(/^nhl\.l\./, '');
-        const cleanTeamId = this.teamId.replace(/^.*\.t\./, '');
-        const fullTeamKey = `nhl.l.${cleanLeagueId}.t.${cleanTeamId}`;
-        const yourTeam = teams.find((t) => {
-            // Team data can be nested as an array or direct object
-            const teamData = Array.isArray(t) ? t[0] : t;
-            const teamKey = teamData?.team_key;
-            return teamKey === fullTeamKey || teamKey === this.teamId || teamKey?.endsWith(`.t.${cleanTeamId}`);
-        });
-        const opponentTeam = teams.find((t) => {
-            const teamData = Array.isArray(t) ? t[0] : t;
-            const teamKey = teamData?.team_key;
-            return teamKey && teamKey !== fullTeamKey && !teamKey?.endsWith(`.t.${cleanTeamId}`);
-        });
-        if (!yourTeam || !opponentTeam) {
-            throw new Error(`Could not find matchup data. Teams found: ${teams.length}, Structure: ${JSON.stringify(matchup.fantasy_content?.team?.[1], null, 2).substring(0, 500)}`);
-        }
-        // Extract team data (handle both array and object structures)
-        const yourTeamData = Array.isArray(yourTeam) ? yourTeam[0] : yourTeam;
-        const opponentTeamData = Array.isArray(opponentTeam) ? opponentTeam[0] : opponentTeam;
-        // Extract team rosters
-        const yourRoster = yourTeamData.roster?.players || [];
-        const opponentRoster = opponentTeamData.roster?.players || [];
-        // Parse player data using .find() pattern like IceAnalysis and LineupAnalysis
-        const parsePlayer = (playerData) => {
-            const player = playerData.player?.[0] || playerData;
-            // Use .find() pattern since player is an array of property objects
-            const player_id = Array.isArray(player)
-                ? player.find((item) => item.player_id)?.player_id
-                : player.player_id;
-            const name = Array.isArray(player)
-                ? player.find((item) => item.name)?.name?.full
-                : player.name?.full;
-            const position = Array.isArray(player)
-                ? player.find((item) => item.display_position)?.display_position ||
-                    player.find((item) => item.primary_positions)?.primary_positions?.[0]
-                : player.display_position || player.primary_positions?.[0];
-            const team = Array.isArray(player)
-                ? player.find((item) => item.editorial_team_abbr)?.editorial_team_abbr
-                : player.editorial_team_abbr;
-            const status = Array.isArray(player)
-                ? player.find((item) => item.status)?.status
-                : player.status;
-            const selected_position = Array.isArray(player)
-                ? player.find((item) => item.selected_position)?.selected_position
-                : player.selected_position;
-            return {
-                player_id: player_id || '',
-                name: name || 'Unknown',
-                position: position || 'Unknown',
-                team: team || '',
-                selected_position: selected_position || [],
-                status: status || ''
-            };
-        };
-        const yourPlayers = yourRoster.map(parsePlayer);
-        const opponentPlayers = opponentRoster.map(parsePlayer);
         return {
-            roster: {
-                team_key: yourTeamData.team_key || '',
-                team_name: yourTeamData.name || 'Your Team',
-                players: yourPlayers
-            },
+            roster: rawData.roster,
             opponent: {
-                team_key: opponentTeamData.team_key || '',
-                team_name: opponentTeamData.name || 'Opponent',
-                players: opponentPlayers
-            },
-            matchup: {
-                week: matchup.fantasy_content?.team?.[0]?.matchups?.['0']?.matchup?.week || 'current',
-                your_team_key: yourTeamData.team_key || '',
-                opponent_team_key: opponentTeamData.team_key || ''
-            },
-            scoreboard: scoreboard
+                team_name: rawData.opponent.team_name,
+                players: rawData.opponent.players
+            }
         };
     }
     /**
@@ -141,9 +44,29 @@ export class GamesInHandAnalysis extends AnalysisTemplate {
      */
     async analyzeData(data, args) {
         const lookAheadDays = args.look_ahead_days || 7;
-        // Calculate games remaining for each team
+        // Calculate games remaining for each team from the real NHL schedule
         const yourGamesRemaining = this.calculateGamesRemaining(data.roster.players, lookAheadDays);
         const opponentGamesRemaining = this.calculateGamesRemaining(data.opponent.players || [], lookAheadDays);
+        // 🏛️ Rule 3: without the schedule there is no schedule advantage to report.
+        // Say so plainly instead of inventing a differential.
+        if (yourGamesRemaining === null || opponentGamesRemaining === null) {
+            return {
+                schedule_available: false,
+                schedule_note: NHL_SCHEDULE.getUnavailableReason() ?? 'NHL schedule unavailable',
+                your_team: {
+                    team_name: data.roster.team_name,
+                    games_remaining: null,
+                    players_with_games: data.roster.players.filter(p => !p.selected_position.includes('IR'))
+                },
+                opponent: {
+                    team_name: data.opponent.team_name || 'Opponent',
+                    games_remaining: null,
+                    players_with_games: (data.opponent.players || []).filter((p) => !p.selected_position.includes('IR'))
+                },
+                advantage: null,
+                strategic_recommendation: 'SCHEDULE UNAVAILABLE: could not reach the NHL schedule API, so no games-in-hand edge can be calculated. Retry shortly.'
+            };
+        }
         const advantage = yourGamesRemaining - opponentGamesRemaining;
         // Generate strategic recommendation based on advantage
         let strategicRecommendation;
@@ -169,6 +92,8 @@ export class GamesInHandAnalysis extends AnalysisTemplate {
             strategicRecommendation = "MASSIVE DISADVANTAGE: Quality over quantity - pick your spots carefully";
         }
         return {
+            schedule_available: true,
+            schedule_source: `NHL public API (season ${NHL_SCHEDULE.getSeason()})`,
             your_team: {
                 team_name: data.roster.team_name,
                 games_remaining: yourGamesRemaining,
@@ -242,16 +167,22 @@ export class GamesInHandAnalysis extends AnalysisTemplate {
         };
     }
     /**
-     * Helper: Calculate total games remaining for a roster
+     * Helper: Count real games remaining for a roster over the look-ahead window.
+     *
+     * Sums each active player's club games from the NHL schedule. A roster of
+     * eight MTL skaters and a roster of eight SEA skaters are not the same
+     * number of games, which is precisely the edge this tool exists to find.
+     *
+     * Returns null when the schedule is unavailable — callers must report that
+     * rather than fall back to an estimate.
      */
     calculateGamesRemaining(players, lookAheadDays) {
-        // This is a simplified calculation
-        // In production, would parse actual NHL schedule data from scoreboard
-        // Active players (not on IR) typically play 3-4 games per week
+        if (!NHL_SCHEDULE.isAvailable())
+            return null;
+        const start = NhlScheduleService.today();
+        const end = NhlScheduleService.addDays(start, Math.max(0, lookAheadDays - 1));
         const activePlayers = players.filter(p => !p.selected_position.includes('IR') &&
             !p.selected_position.includes('BN'));
-        // Rough estimate: 3.5 games per active player per week
-        const weeksInLookAhead = lookAheadDays / 7;
-        return Math.round(activePlayers.length * 3.5 * weeksInLookAhead);
+        return activePlayers.reduce((total, player) => total + NHL_SCHEDULE.countGamesInRange(player.team, start, end), 0);
     }
 }