Session 7e: Grade adapter, normalize consolidation, ARCH-2 banners
This commit is contained in:
@@ -0,0 +1,166 @@
|
||||
/**
|
||||
* Engine 1 (new) → legacy grader shape adapter.
|
||||
*
|
||||
* Engine 1 emits an 11-step grade (F..A+) + 0-1 confidence + a labelled
|
||||
* factors array. The frontend (`DemoScan.tsx`, `GradeCard.tsx`) and the
|
||||
* `/api/analyze`, `/api/scan`, `/api/bets` routes were built against the
|
||||
* legacy `grader.js` shape:
|
||||
*
|
||||
* {
|
||||
* player, stat_type, line, direction, book,
|
||||
* grade, // 'A' | 'B' | 'C' | 'D' (4-letter)
|
||||
* confidence, // 0-100 integer
|
||||
* edge_pct, // signed percentage
|
||||
* kill_conditions_triggered: [{ code, ... }],
|
||||
* reasoning: { summary: string, steps: {...} }
|
||||
* }
|
||||
*
|
||||
* Future route rewires that swap `analyzeProp` for the orchestrator/
|
||||
* engine1 path will pipe the result through `toLegacyShape()` so the
|
||||
* frontend sees no change.
|
||||
*
|
||||
* NOTE — Session 7e ESCAPE HATCH: the adapter is built but not yet
|
||||
* applied to a live route. Engine 1's input is a pre-computed feature
|
||||
* vector; the legacy analyzer takes a raw prop and fetches its own
|
||||
* data. Wiring those two together requires an orchestrator-lite
|
||||
* preprocessor that doesn't exist yet. This file exists so the next
|
||||
* session can drop it in once the preprocessor is in place. See
|
||||
* docs/SYSTEM-MANIFEST.md §8 ARCH-1.
|
||||
*/
|
||||
|
||||
const FOUR_LETTER_MAP = Object.freeze({
|
||||
'A+': 'A', 'A': 'A', 'A-': 'A',
|
||||
'B+': 'B', 'B': 'B', 'B-': 'B',
|
||||
'C+': 'C', 'C': 'C', 'C-': 'C',
|
||||
'D': 'D',
|
||||
'F': 'F', // DemoScan's ACCURACY map yields '—' for F, which is fine.
|
||||
});
|
||||
|
||||
// Factors that, when present, suggest a kill condition in the legacy
|
||||
// sense. Each maps to a stable code + human reason so the UI keeps
|
||||
// rendering the same chip set it always has. Unknown factors fall
|
||||
// through to a generic "signal" entry rather than disappearing.
|
||||
const FACTOR_TO_KILL_CONDITION = Object.freeze({
|
||||
trap_composite_high: { code: 'TRAP', reason: 'Multiple trap signals firing.' },
|
||||
l5_cold_vs_line: { code: 'COLD_L5', reason: 'Last-5 average significantly below the line.' },
|
||||
l5_hot_vs_under: { code: 'COLD_L5', reason: 'Hot streak conflicts with UNDER side.' },
|
||||
consistency_boom_bust: { code: 'BOOM_BUST', reason: 'Player is boom-or-bust on this stat.' },
|
||||
top_opponent_defense: { code: 'TOP_DEFENSE', reason: 'Opponent ranks top-five defending this stat.' },
|
||||
back_to_back: { code: 'B2B', reason: 'Back-to-back game.' },
|
||||
heavy_workload_7d: { code: 'FATIGUE', reason: '4+ games in the last 7 days.' },
|
||||
away_vs_top5_defense: { code: 'TOP_DEFENSE', reason: 'Away game vs a top-five defense.' },
|
||||
rookie_in_playoffs: { code: 'NEW_CONTEXT', reason: 'No prior playoff experience.' },
|
||||
});
|
||||
|
||||
function fourLetterGrade(elevenStep) {
|
||||
if (typeof elevenStep !== 'string') return null;
|
||||
return FOUR_LETTER_MAP[elevenStep.trim()] ?? null;
|
||||
}
|
||||
|
||||
function legacyConfidence(unitProb) {
|
||||
// Guard nullish first — Number(null) === 0 is finite, which would
|
||||
// silently produce a 0% confidence instead of "unknown".
|
||||
if (unitProb == null) return null;
|
||||
const n = Number(unitProb);
|
||||
if (!Number.isFinite(n)) return null;
|
||||
return Math.max(0, Math.min(100, Math.round(n * 100)));
|
||||
}
|
||||
|
||||
// Build kill_conditions_triggered from engine1 factors. Only factors
|
||||
// that signal something the user should worry about become chips —
|
||||
// positive factors (e.g. l5_hot_vs_line) don't.
|
||||
function killConditionsFromFactors(factors) {
|
||||
if (!Array.isArray(factors)) return [];
|
||||
const out = [];
|
||||
const seen = new Set();
|
||||
for (const f of factors) {
|
||||
const entry = FACTOR_TO_KILL_CONDITION[f];
|
||||
if (entry && !seen.has(entry.code)) {
|
||||
out.push({ ...entry });
|
||||
seen.add(entry.code);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
// Engine 1 factors are abstract labels. To produce a reasoning.summary
|
||||
// the legacy UI renders, we string the top-three factors together with a
|
||||
// human-readable verb. Callers that have richer context (e.g. the
|
||||
// orchestrator with featurePayload) should pass their own sentence in
|
||||
// `summaryOverride`.
|
||||
function buildReasoningSummary(engine1Result, prop, summaryOverride) {
|
||||
if (summaryOverride && typeof summaryOverride === 'string') return summaryOverride;
|
||||
const top = Array.isArray(engine1Result?.top_factors) ? engine1Result.top_factors.slice(0, 3) : [];
|
||||
if (top.length === 0) {
|
||||
return `Grade ${engine1Result?.grade ?? '—'} from Engine 1 (no surfaced factors).`;
|
||||
}
|
||||
const verb = engine1Result?.grade?.startsWith('A') ? 'favoring the play'
|
||||
: engine1Result?.grade?.startsWith('B') ? 'leaning the play'
|
||||
: engine1Result?.grade?.startsWith('C') ? 'split'
|
||||
: 'against the play';
|
||||
return `Engine 1 graded ${engine1Result?.grade ?? '—'} ${verb} — top factors: ${top.join(', ')}.`;
|
||||
}
|
||||
|
||||
// edge_pct lives in the legacy response. Engine 1 doesn't compute it.
|
||||
// If the caller passes a computed value (e.g. l5_avg − line), use it;
|
||||
// otherwise return 0 so the field exists and the UI doesn't blow up
|
||||
// on missing data.
|
||||
function legacyEdgePct(edgePctOverride) {
|
||||
const n = Number(edgePctOverride);
|
||||
return Number.isFinite(n) ? n : 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* toLegacyShape — transform an engine1 grading result into the shape
|
||||
* `/api/analyze` and downstream callers historically returned.
|
||||
*
|
||||
* @param {Object} engine1Result — { grade, confidence, top_factors, all_factors }
|
||||
* @param {Object} prop — { player, stat_type, line, direction, book, sport }
|
||||
* @param {Object} [opts]
|
||||
* @param {string} [opts.summaryOverride] — supply a fuller human sentence if available
|
||||
* @param {number} [opts.edgePct] — pre-computed edge percentage
|
||||
* @returns {Object} legacy-shaped result, including the `_cache: 'MISS'` field
|
||||
* the PERF-1 wrapper expects callers to receive.
|
||||
*/
|
||||
function toLegacyShape(engine1Result, prop = {}, opts = {}) {
|
||||
if (!engine1Result || typeof engine1Result !== 'object') return null;
|
||||
const grade = fourLetterGrade(engine1Result.grade);
|
||||
const confidence = legacyConfidence(engine1Result.confidence);
|
||||
const kill = killConditionsFromFactors(engine1Result.all_factors || engine1Result.top_factors);
|
||||
return {
|
||||
player: prop.player ?? null,
|
||||
stat_type: prop.stat_type ?? null,
|
||||
line: prop.line ?? null,
|
||||
direction: prop.direction ?? null,
|
||||
book: prop.book ?? null,
|
||||
grade,
|
||||
confidence,
|
||||
edge_pct: legacyEdgePct(opts.edgePct),
|
||||
kill_conditions_triggered: kill,
|
||||
reasoning: {
|
||||
summary: buildReasoningSummary(engine1Result, prop, opts.summaryOverride),
|
||||
// The legacy `steps` block carried season_avg / recent_form /
|
||||
// situational / line_comparison / kill_conditions / final_grade.
|
||||
// Engine 1 doesn't surface those individually, so the adapter
|
||||
// emits an `engine1_factors` block as the modern equivalent.
|
||||
// The frontend reads `.summary` only; this is documentation.
|
||||
steps: {
|
||||
engine1_factors: engine1Result.all_factors || engine1Result.top_factors || [],
|
||||
final_grade: grade,
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
toLegacyShape,
|
||||
__internals: {
|
||||
FOUR_LETTER_MAP,
|
||||
FACTOR_TO_KILL_CONDITION,
|
||||
fourLetterGrade,
|
||||
legacyConfidence,
|
||||
killConditionsFromFactors,
|
||||
buildReasoningSummary,
|
||||
legacyEdgePct,
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,30 @@
|
||||
/**
|
||||
* Player-name normalization for cross-source matching.
|
||||
*
|
||||
* ParlayAPI emits "Brunson, Jalen"; ESPN emits "Jalen Brunson"; nba_api
|
||||
* sometimes attaches a jersey number. Normalize aggressively so equality
|
||||
* comparisons just work.
|
||||
*
|
||||
* Pipeline:
|
||||
* NFD unicode → strip accents → lowercase → drop suffixes (jr/sr/ii/iii/
|
||||
* iv/v) → strip punctuation → collapse whitespace → trim.
|
||||
*
|
||||
* `keepDigits` (default false) controls whether digits survive the
|
||||
* punctuation strip. The trap detector matches names only and wants
|
||||
* digits gone; the player-ID population script keeps them because some
|
||||
* legacy roster fields encode jersey numbers inline.
|
||||
*/
|
||||
function normalizeName(name, { keepDigits = false } = {}) {
|
||||
if (!name) return '';
|
||||
const punctClass = keepDigits ? '[^a-z0-9\\s]' : '[^a-z\\s]';
|
||||
return String(name)
|
||||
.normalize('NFD')
|
||||
.replace(/[̀-ͯ]/g, '')
|
||||
.toLowerCase()
|
||||
.replace(/\b(jr|sr|ii|iii|iv|v)\.?\b/g, '')
|
||||
.replace(new RegExp(punctClass, 'g'), ' ')
|
||||
.replace(/\s+/g, ' ')
|
||||
.trim();
|
||||
}
|
||||
|
||||
module.exports = { normalizeName };
|
||||
Reference in New Issue
Block a user