CBB预测仪表板
 
NCAA男子D1大学篮球赛——实时仪表板+预测获胜概率引擎
仪表板预览
CBB Live Dashboard - Interactive US Map with AP Top 25 Rankings
一个全栈Python应用程序，将实时大学篮球MCP服务器与交互式仪表板和游戏内获胜概率预测器相结合。在交互式美国地图上实时观看游戏，探索盒子分数并逐个游戏，并获得由集成ML模型提供支持的实时获胜概率。
______________________________________________________________________
特性
实时仪表盘
- 交互式美国地图 --每场D1比赛按场地绘制，颜色编码状态（绿色=直播，灰色=决赛，蓝色=即将到来）
- 30秒自动刷新 --实时分数自动更新
- 游戏面板 --单击任何标记打开实时框分数并逐个播放
- AP Top 25+所有团队侧栏 --362支D1团队可通过即时搜索按会议浏览
- AI 聊天 --由实时数据工具（分数、统计数据、排名、比较）支持的自然语言查询
- 会议筛选器 --将地图缩小到一个会议
预测引擎
- 游戏中获胜概率 --使用当前分数、剩余时间和游戏时间每30秒更新一次直播百分比
- 集成模型 --将逻辑回归（稳定锚）和XGBoost（非线性模式）与等权重相结合
- 特性：分数差、时间比、剩余分钟数、时段
- 培训管道 --逐个游戏快照收集历史游戏，并使用单个命令重新训练
- 模型工件 --保存为
cbb_predictor_bundle.joblib（LR型号+XGBoost+定标器+功能列表）
MCP服务器（16个工具）
| 工具 | 说明 |
|---|---|
get_live_scores | 任何日期的实时/最终得分，可按会议或前25名进行筛选 |
get_team | 按名称查找任何团队（模糊匹配） |
search_teams | 按名称或会议搜索团队 |
get_team_roster | 包含球员详细信息的完整名单 |
get_team_schedule | 带结果的完整时间表 |
get_game_detail | 比赛信息及得分总结 |
get_box_score | 每位球员和球队的得分 |
get_play_by_play | 使用时间戳逐个播放 |
get_rankings | 美联社前25名，教练投票 |
get_standings | 会议排名出现连胜 |
get_team_stats | 赛季球队统计数据（PPG、FG%、RPG等） |
get_player_stats | 球队的个人球员统计数据 |
get_stat_leaders | 按类别分列的国家统计领导人 |
compare_teams | 并排团队比较 |
get_games_by_date | 与电视信息约会的所有游戏 |
get_tournament_bracket | 三月疯狂括号和结果 |
______________________________________________________________________
项目结构
├── src/cbb_mcp/ # MCP server (data layer)
│ ├── server.py # Tool registrations + entry point
│ ├── config.py # Environment-based configuration
│ ├── services/ # Business logic (games, teams, rankings, stats)
│ ├── sources/ # ESPN, NCAA, sportsdataverse, cbbpy adapters
│ ├── models/ # Pydantic data models
│ └── utils/ # Cache, rate limiter, HTTP client
├── dashboard/ # Dash web application
│ ├── app.py # Entry point
│ ├── layout.py # Full page layout
│ ├── components/ # Map, game panel, rankings sidebar, chat
│ ├── callbacks/ # Dash reactive callbacks
│ ├── ai/ # AI chat agent + tool dispatcher
│ ├── data/ # Venue coordinates for all 362 D1 schools
│ └── scripts/
│ ├── collect_historical_data.py # Fetch play-by-play training data
│ ├── train_predictor.py # Train + save ensemble model
│ └── build_venue_coords.py # Geocode venue locations
├── tests/ # 51 unit tests
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml______________________________________________________________________
快速开始
安装
git clone https://github.com/RajaChaiban/CBB_Predictive_Dashboard.git
cd CBB_Predictive_Dashboard
pip install -e ".[dashboard]"配置
复制 .env.example 到 .env 并填写您的值：
cp .env.example .env关键变量：
| 变量 | 描述 |
|---|---|
AI_API_KEY | 人工智能聊天后台的API密钥 |
AI_MODEL | 用于聊天的型号名称 |
CBB_DASH_PORT | 仪表板端口（默认 8050) |
CBB_TRANSPORT | stdio 或 streamable-http |
运行仪表板
python dashboard/app.py打开 http://localhost:8050 在您的浏览器中。
______________________________________________________________________
预测引擎
1.收集培训数据
2025-26赛季（推荐），使用预先构建的增强训练数据：
python dashboard/scripts/train_predictor.py --input enhanced_training_data_2025_26.csv用于自定义日期范围，先收集数据：
python dashboard/scripts/collect_historical_data.py \
--start 2025-11-01 \
--end 2026-02-27 \
--output cbb_training_data_2025_26.csv
python dashboard/scripts/train_predictor.py --input cbb_training_data_2025_26.csv⚠️ 注： 仅使用2025-26年的季节数据。大学名册在不同季节之间变化很大。
每一行都是一个游戏快照，其中包含： score_diff, momentum, strength_diff, time_ratio, mins_remaining, period，加上12个上下文功能。
输出：
- 逻辑回归准确率+Brier评分（2025-26年为99.50%）
- XGBoost精度+Brier评分（2025-26年为99.75%）
- 集成准确率+Brier评分（2025-26年为99.75%）
cbb_predictor_bundle.joblib--已保存的模型包
3.实时预测
曾经 cbb_predictor_bundle.joblib 存在于项目根目录中，仪表板会自动加载它，并在每个实时游戏标记和游戏面板中显示获胜概率。概率每30秒更新一次实时分数刷新。
运作原理
Live Score (ESPN)
│
▼
score_diff = home_score - away_score
time_ratio = elapsed_time / total_game_time
mins_remaining = minutes left in game
period = 1st half / 2nd half / OT
│
▼
Logistic Regression ──┐
├── average → Win Probability %
XGBoost ──────────────┘______________________________________________________________________
数据源
所有来源都是免费的，不需要API密钥：
| 来源 | 它提供了什么 |
|---|---|
| ESPN隐藏的API | 现场得分、球队、排名、排名、时间表、方框得分 |
| NCAA API | 分数、排名、比赛详情 |
| sportsdataverse | 每场比赛的历史比赛，球队/球员的得分 |
| cbbpy | 盒子得分，逐局播放，时间表 |
服务器首先尝试ESPN（最全面），然后自动回退。
______________________________________________________________________
远程托管（HTTP）
CBB_TRANSPORT=streamable-http python -m cbb_mcp.server
# With API key authentication
CBB_TRANSPORT=streamable-http CBB_SERVER_API_KEY=your-secret python -m cbb_mcp.server码头工人
docker build -t cbb-dashboard .
docker run -p 8000:8000 -p 8050:8050 cbb-dashboard
# Or with docker-compose
docker compose up______________________________________________________________________
配置
所有配置均通过环境变量或 .env 文件：
| 变量 | 默认值 | 描述 |
|---|---|---|
CBB_TRANSPORT | stdio | stdio 或 streamable-http |
CBB_HOST | 127.0.0.1 | MCP服务器绑定地址 |
CBB_PORT | 8000 | MCP服务器端口 |
CBB_SERVER_API_KEY | *（空）* | HTTP身份验证的承载令牌 |
CBB_DASH_HOST | 127.0.0.1 | 仪表板绑定地址 |
CBB_DASH_PORT | 8050 | 仪表板端口 |
CBB_CACHE_ENABLED | true | 启用/禁用缓存 |
CBB_CACHE_DIR | .cache | 磁盘缓存目录 |
CBB_LOG_LEVEL | INFO | 日志记录级别 |
CBB_ESPN_RATE_LIMIT | 10 | ESPN请求/秒 |
CBB_NCAA_RATE_LIMIT | 5 | NCAA请求/秒 |
______________________________________________________________________
发展
pip install -e ".[dev]"
pytest51个测试，涵盖服务、模型、缓存、速率限制和源回退逻辑。
______________________________________________________________________
安全
- 所有输入都经过验证，长度有限
- HTTP身份验证使用定时安全比较
- API密钥从未记录或在响应中返回
- HTTP响应上限为5 MB
- 非root Docker用户
______________________________________________________________________
许可证
麻省理工学院