Buzzr Sports Engines

Pure-TypeScript, zero-dependency engines for sports betting and DFS apps — auditable pick'em settlement, sportsbook odds math, and transparent game-entertainment scoring. Every package is a set of pure functions: no I/O, no framework lock-in, no native deps. Feed data in, get deterministic, explainable decisions out — with validation reports and audit trails, because settling money on if (points > line) is how disputes happen. Built and used in production by Buzzr, a sports social app.

The packages

Package	What it does	Install
@buzzr/dfs-engine	DFS settlement OS: book policies, grading, payouts, audit trails, batch settlement	npm i @buzzr/dfs-engine
@buzzr/bets-core	Odds math: no-vig fair lines, parlays, EV, Kelly staking, CLV, period analytics	npm i @buzzr/bets-core
@buzzr/entertainment-engine	Transparent buzz scoring, hybrid ML predictions, personalized game recommendations	npm i @buzzr/entertainment-engine
@buzzr/mcp	MCP server exposing the engines to AI agents (8 tools)	npx -y @buzzr/mcp
@buzzr/dfs-cli	Grade a DFS entry from JSON on the command line	npm i -g @buzzr/dfs-cli
@buzzr/dfs-react	Settlement → UI view-models (React/Vue/Svelte/vanilla; no React dep)	npm i @buzzr/dfs-react
@buzzr/dfs-testkit	Fixture builders + mock stat providers for tests	npm i -D @buzzr/dfs-testkit
@buzzr/dfs-provider-espn	ESPN-shaped stat provider contract	npm i @buzzr/dfs-provider-espn
@buzzr/dfs-provider-sportradar	Sportradar-shaped stat provider contract	npm i @buzzr/dfs-provider-sportradar
@buzzr/dfs-engine-test-vectors	Golden fixtures proving your integration grades identically to Buzzr's	npm i -D @buzzr/dfs-engine-test-vectors

All packages: TypeScript-first with full .d.ts, ESM + CJS builds (the CLI is ESM-only), Node >= 22, MIT, zero runtime dependencies outside the family.

Architecture

flowchart LR
    subgraph data["Your data layer"]
        ESPN["@buzzr/dfs-provider-espn"]
        SR["@buzzr/dfs-provider-sportradar"]
        Custom["custom StatProvider"]
    end

    subgraph core["Core engines (pure functions)"]
        Engine["@buzzr/dfs-engine<br/>policies · grading · payouts · audit"]
        Bets["@buzzr/bets-core<br/>odds · parlays · EV · Kelly · CLV"]
        Ent["@buzzr/entertainment-engine<br/>buzz scores · ML · recommendations"]
    end

    subgraph consumers["Consumers"]
        CLI["@buzzr/dfs-cli"]
        React["@buzzr/dfs-react"]
        MCP["@buzzr/mcp → AI agents"]
        App["your app / Buzzr app"]
    end

    subgraph testing["Testing"]
        Testkit["@buzzr/dfs-testkit"]
        Vectors["@buzzr/dfs-engine-test-vectors"]
    end

    ESPN --> Engine
    SR --> Engine
    Custom --> Engine
    Engine --> CLI
    Engine --> React
    Engine --> MCP
    Bets --> MCP
    Ent --> MCP
    Engine --> App
    Bets --> App
    Ent --> App
    Testkit -.-> Engine
    Vectors -.-> Engine

Loading

Quick starts

Settle a DFS entry — @buzzr/dfs-engine

import { createDfsEngine, defineStatProvider } from '@buzzr/dfs-engine';

const provider = defineStatProvider({
  id: 'my-stats',
  getGameLog: ({ leg }) => fetchGameLogRows(leg.playerId, leg.gameDate),
});

const engine = createDfsEngine({ statProviders: [provider] });

const result = await engine.settleEntry(entry, { statProviderId: 'my-stats' });
// result.status, result.payout, result.legs[].actual, result.auditTrail, ...

// v5: settle a whole slate in one call with a shared, memoized stat cache
const batch = await engine.settleEntries(entries, { statProviderId: 'my-stats' });

Book policies for PrizePicks- and Underdog-style play types are built in and versioned; custom books plug in via defineBookPolicy, and v5 adds policy validation plus a draft prediction-market (Kalshi-style) policy.

Price a bet — @buzzr/bets-core

import {
  americanOddsToImpliedProbability,
  calculateNoVigFairLine,
  calculateExpectedValue,
  calculateKellyStake,
} from '@buzzr/bets-core';

americanOddsToImpliedProbability(-120); // 0.545455

const fair = calculateNoVigFairLine({
  selected: { side: 'home', americanOdds: -120 },
  opposite: { side: 'away', americanOdds: 100 },
}); // vig removed → fair probability for the selected side

const ev = calculateExpectedValue({ stake: 100, americanOdds: 120, winProbability: 0.5 });

const kelly = calculateKellyStake({ bankroll: 1000, americanOdds: 120, winProbability: 0.5 });
// kelly.recommendedStake — quarter-Kelly by default

v5 also ships parlay math (combineAmericanOdds, calculateParlayFairValue), closing-line value, and period analytics (calculateRollupByPeriod, calculateDrawdown, calculateStreaks).

Score a game — @buzzr/entertainment-engine

import { resolveBuzzScores, isMustWatch } from '@buzzr/entertainment-engine';

const scores = resolveBuzzScores(
  {
    league: 'NBA',
    status: 'final',
    entertainmentScore: 87,
    predictedEntertainmentScore: 74,
  },
  { upcomingLike: false },
);
// scores.entertainmentScore, scores.predictedEntertainmentScore,
// scores.source (which model won), scores.diagnostics (why)

isMustWatch(scores.entertainmentScore); // boolean against the must-watch threshold

v5 adds calibrated ML confidence, DST-safe primetime detection, search-heat and star-power features, and rankGamesForUser personalized recommendations.

Give it to your AI agent — @buzzr/mcp

Add to your MCP client config (Claude Desktop, Claude Code, Cursor, …):

{
  "mcpServers": {
    "buzzr": {
      "command": "npx",
      "args": ["-y", "@buzzr/mcp"]
    }
  }
}

The server exposes the engines as 8 tools — settle entries, price parlays, compute EV/Kelly, score games — so agents get book-accurate math instead of hallucinated numbers.

Used in production by Buzzr

These packages are extracted from — and power — the Buzzr sports app: DFS slip grading, sportsbook bet tracking, and the buzz scores on every game card run through exactly this code. The app is the first consumer of every release, so the published API is the one we live with ourselves.

Development

npm ci
npm run typecheck
npm test
npm run build

Release hardening

Before publishing or cutting a release, run:

npm run verify
npm run audit:high

verify runs typecheck, lint, format check, tests, coverage, build, docs, export smoke tests, package size checks, and a dry-run pack across all packages.

Reporting bugs

Use the GitHub bug report template for package defects. Include the package version, Node version, book policy/play type, provider data shape, and a minimal reproduction.

For settlement correctness or security-sensitive issues, follow SECURITY.md so reports can be triaged before public disclosure.

Links

• API docs (typedoc)
• Issues
• AGENTS.md — how AI coding agents should use this repo
• llms.txt — machine-readable package index

License

MIT