🏀 Hoop.io-人工智能NBA助理

NBA数据、实时比分和篮球知识的智能伴侣

______________________________________________________________________

📖 概述

Hoop.io 是一个复杂的人工智能聊天机器人，通过模型上下文协议（MCP）将谷歌Gemini 2.5 Flash与实时NBA数据相结合。询问NBA历史事实，获取实时比赛成绩，查看球员统计数据，探索球队排名，或询问最近的NBA新闻——所有这些都可以通过一个漂亮、现代的聊天界面完成。

与Gemini的广泛功能（包括LLM知识和网络搜索）相比，该应用程序智能地决定何时使用专用的NBA API工具，为您的所有篮球查询提供准确和最新的信息。

______________________________________________________________________

✨ 特性

🤖 智能查询处理

双源情报：在NBA API工具和Gemini的知识库之间自动切换
双子座2.5闪光灯：高级LLM，内置网络搜索功能，可搜索当前信息
语境对话：维护自然、多回合对话的对话历史记录
智能工具选择：明智地决定何时使用NBA API工具与一般知识/网络搜索

📊 NBA实时数据

实时游戏得分：通过NBA API获取今天比赛的当前分数和比赛状态
联赛排名：查看两个联盟的当前NBA排名
球员统计：获取任何NBA球员的详细职业统计数据
当前季节数据：Gemini提供球队记录、最近的比赛和最新消息
历史知识：询问NBA的历史、记录和历史成就

🎨 高级用户界面

现代设计：以玻璃形态为灵感的深色主题，搭配NBA色彩
两列布局：左侧为AI响应，右侧为聊天控件
消息来源：查看数据是否来自NBA API或Gemini
快捷操作：一键访问热门查询
对话历史：回顾并重新提出以前的问题

______________________________________________________________________

🚀 安装

先决条件

Python 3.13+
Node.js 18+
npm或纱线
Google Gemini API密钥(在这里买一个)

步骤1：克隆存储库

git clone 
cd Assignment4

步骤2：后端设置

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r backend/requirements.txt

# Configure environment variables
cd backend
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY

步骤3：前端设置

cd frontend
npm install

步骤4：启动应用程序

终端1-后端：

# From project root, activate venv first
source venv/bin/activate  # On Windows: venv\Scripts\activate
uvicorn backend.main:app --reload --port 8000

2号航站楼-前端：

cd frontend
npm run dev

访问 http://localhost:5173 在您的浏览器中！ 🎉

🌐 在MyBinder上部署（替代方案）

想在不安装任何东西的情况下尝试Hoop.io吗？在MyBinder上启动它！

![Binder](https://mybinder.org/v2/gh/sudhamanc/Hoop.io/main)

步骤：

点击上方的“启动绑定器”徽章
等待环境构建（第一次需要~5-10分钟）
加载后，在JupyterLab中打开一个终端
设置API密钥：

   export GOOGLE_API_KEY="your_key_here"

运行MyBinder启动脚本：

   ./start_mybinder.sh

复制显示的URL（例如。， https://hub.gesis.mybinder.org/user/.../proxy/8000/)
将其粘贴到浏览器中并开始聊天！ 🏀

它是如何工作的：

start_mybinder.sh 构建前端并通过后端提供服务
使用单个端口（8000）避免JupyterHub代理身份验证问题
该应用程序与所有NBA工具和Gemini集成功能齐全

活页夹配置文件：

binder/environment.yml -包含Python、Node.js和依赖项的Conda环境
binder/postBuild -安装前端软件包的后构建脚本
start_mybinder.sh -MyBinder启动脚本（构建前端+启动后端）

______________________________________________________________________

🛠️ 用法

基本查询

历史问题 （使用双子座的知识）：

"Which team has won the most NBA titles?"
"Who is the all-time leading scorer?"
"Tell me about Michael Jordan's career"

实时数据 （使用NBA API）：

"What are today's games?"
"Show me current standings"
"Get Stephen Curry's career stats"

最近/当前季节 （使用Gemini）：

"How many wins does the Lakers have this season?"
"Who won last night's game between Warriors and Celtics?"
"Latest NBA trade news"

对话示例

You: Who won the most NBA championships?
Hoop.io: The Boston Celtics have won 17 NBA championships.
         Source: Gemini

You: What about the Lakers?
Hoop.io: The Los Angeles Lakers have also won 17 championships, 
         tied with the Celtics for the most all-time.
         Source: Gemini

You: Show me LeBron James' career stats
Hoop.io: [Detailed career statistics from NBA API]
         Source: NBA API

You: How many wins does the Lakers have this season?
Hoop.io: [Current season record from Gemini's knowledge/web search]
         Source: Gemini

______________________________________________________________________

📦 技术

后端

快速API -现代Python web框架
谷歌双子座2.5 Flash -高级LLM，内置网络搜索功能
MCP（模型上下文协议） -工具集成框架
FastMCP -Python MCP服务器实现
nba_api -NBA官方统计API包装
Python 3.13 -最新Python运行时

前端

反应18 -UI框架
TypeScript -类型安全的JavaScript
维特 -下一代前端工具
顺风CSS v4 -实用程序优先的CSS框架
反应降价 -Markdown渲染以获得丰富的响应

建筑

MCP协议 -标准化工具调用界面
异步/等待 -无阻塞I/O，性能更佳
RESTful API -前端和后端之间的干净HTTP接口

______________________________________________________________________

🔧 配置

环境变量

创建一个 .env 文件在 backend/ 目录：

GOOGLE_API_KEY=your_gemini_api_key_here

获取Gemini API密钥：

访问谷歌人工智能工作室
使用您的Google帐户登录
单击“创建API密钥”
复制密钥并将其粘贴到您的 .env 文件

⚠️ 安全说明：永远不要承诺你的 .env 文件到版本控制。这 .gitignore 已配置为排除它。

系统说明（可选）

您可以通过在中编辑系统指令来定制AI的行为 backend/main.py:

system_instruction = """You are an expert NBA assistant..."""

______________________________________________________________________

✅ 需求

Python依赖关系

fastapi>=0.115.0
uvicorn>=0.32.0
google-generativeai>=0.8.3
mcp>=1.1.2
nba_api>=1.5.2
python-dotenv>=1.0.1
httpx>=0.27.2

节点依赖关系

{
  "react": "^18.3.1",
  "vite": "^6.0.1",
  "tailwindcss": "^4.0.0",
  "react-markdown": "^9.0.1",
  "remark-gfm": "^5.0.0"
}

______________________________________________________________________

🗂️ 存储库结构

Assignment4/
├── backend/                    # FastAPI backend server
│   ├── main.py                # Main application entry point
│   │                          # - FastAPI app configuration
│   │                          # - MCP client setup and lifespan management
│   │                          # - Environment detection (MyBinder vs local)
│   │                          # - Static file serving for MyBinder
│   │                          # - Chat endpoint with Gemini 2.5 Flash
│   │                          # - Combined tool with Google Search + NBA API
│   │                          # - Tool calling and response handling
│   ├── requirements.txt       # Python dependencies
│   ├── .env.example          # Environment variables template
│   ├── .env                  # Your API keys (gitignored)
│   └── .gitignore            # Git ignore rules
│
├── frontend/                  # React frontend application
│   ├── src/
│   │   ├── components/
│   │   │   └── ChatInterface.tsx  # Main chat UI component
│   │   │                          # - Message display and management
│   │   │                          # - User input handling
│   │   │                          # - History and quick actions
│   │   ├── App.tsx               # Root React component
│   │   ├── main.tsx              # React entry point
│   │   └── index.css             # Global styles and Tailwind config
│   ├── package.json              # Node dependencies
│   ├── tailwind.config.js        # Tailwind CSS configuration
│   ├── postcss.config.js         # PostCSS configuration
│   ├── vite.config.ts            # Vite build configuration
│   └── .env.local                # Local dev API URL (gitignored)
│
├── mcp-server/                # MCP server for NBA data
│   └── nba_server.py         # FastMCP server implementation
│                             # - get_live_games() tool
│                             # - get_standings() tool
│                             # - get_player_stats() tool
│
├── binder/                    # MyBinder configuration
│   ├── environment.yml       # Conda environment specification
│   └── postBuild             # Post-build script for npm install
│
├── start_mybinder.sh          # MyBinder startup script
├── venv/                      # Python virtual environment (gitignored)
└── README.md                 # This file

关键部件说明

backend/main.py

寿命经理：启动时连接到MCP服务器，加载NBA工具
聊天端点：处理用户消息，管理对话历史记录
组合工具：创建具有Google搜索基础+NBA API功能的统一工具
工具集成：将MCP工具转换为Gemini格式，执行工具调用
响应处理：跟踪数据源（NBA API、谷歌搜索或Gemini LLM）

mcp-server/nba_server.py

FastMCP服务器：将NBA数据作为MCP工具公开
NBA API集成：用途 nba_api 实时数据库
工具定义：具有清晰描述和模式的三个主要工具

frontend/src/components/ChatInterface.tsx

状态管理：跟踪消息、输入、加载状态
API通信：向后端发送请求，处理响应
UI渲染：两柱布局，玻璃造型设计
用户交互：输入处理、快速操作、历史管理
Markdown表格支持：用途 remark-gfm GitHub风格Markdown表渲染插件
自定义样式：用于专业表格边框、填充和布局的顺风散文课程

______________________________________________________________________

🔗 流程图

graph TB
    subgraph "User Interface"
        A[User enters question] --> B[ChatInterface.tsx]
        B --> C[Send to Backend API]
    end
    
    subgraph "Backend Processing"
        C --> D[FastAPI /api/chat endpoint]
        D --> E[Build conversation history]
        E --> F[Create Gemini model with system instruction]
        F --> G[Send message with available tools]
    end
    
    subgraph "Gemini Decision"
        G --> H{Does question need live data?}
        H -->|No| I[Use general knowledge]
        H -->|Yes| J[Call appropriate tool]
    end
    
    subgraph "Tool Execution"
        J --> K[Gemini returns function_call]
        K --> L[Backend detects function_call]
        L --> M[Execute tool via MCP session]
        M --> N[MCP Server calls NBA API]
        N --> O[Return data to backend]
        O --> P[Send result back to Gemini]
        P --> Q[Gemini formats response]
    end
    
    I --> R[Return response to frontend]
    Q --> R
    R --> S[Display in chat UI]
    S --> T[Show source attribution]
    
    style A fill:#4CAF50
    style S fill:#2196F3
    style H fill:#FF9800
    style N fill:#F44336

数据流说明

用户输入 → 用户在聊天界面中键入问题
前端 → 将消息+历史记录发送到后端API
后端 → 准备上下文，创建组合工具（谷歌搜索+NBA功能），发送到Gemini
双子座分析 → 决定是否使用LLM知识、Google搜索或NBA API工具
工具执行 （如果需要）→ 后端执行NBA MCP调用或处理谷歌搜索结果
响应 → Gemini格式化数据→ 后端添加源属性（NBA API/谷歌搜索/Gemini）→ 前端显示源标签

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是您可以提供帮助的方式：

复刻仓库
创建要素分支: git checkout -b feature/amazing-feature
进行更改 并进行彻底测试
提交您的更改: git commit -m 'Add amazing feature'
推到分支: git push origin feature/amazing-feature
打开拉取请求

开发指南

Python代码遵循PEP 8
将TypeScript用于新的React组件
为复杂逻辑添加注释
提交前使用多种查询类型进行测试

______________________________________________________________________

📄 文档

额外资源

关键概念

MCP（模型上下文协议）：LLM与外部工具交互的标准化方式
函数调用双子座识别何时使用工具的能力与一般知识
谷歌搜索暂停：实时网络搜索集成，提供培训数据以外的最新信息
工具编排：在一个统一的界面中组合多个数据源（NBA API+谷歌搜索+LLM）
代理行为：LLM充当智能代理，对工具使用做出决策

______________________________________________________________________

❤️ 致谢

谷歌双子座 -强大的语言模型和函数调用功能
Anthropic -开创了模型上下文协议
nba_api -便于访问NBA统计数据
快速API -优秀的Python web框架
反应团队 -对于令人惊叹的前端库
顺风 CSS -对于实用程序优先的CSS框架

特别感谢开源社区使这样的项目成为可能！

______________________________________________________________________

📝 更新日志

版本1.1.0（当前-2025年11月）

✅ Markdown表格渲染：已添加 remark-gfm 用于正确设置表格格式的插件
✅ 增强型系统说明：带有错误与正确示例的显式格式规则
✅ 工具关联逻辑：智能工具使用（例如，玩家提问→ 球队排名）
✅ 精致护栏：仅篮球政策，回答所有NBA问题，包括过去的比赛
✅ 搜索接地：当前季节数据的自动谷歌搜索集成
✅ MyBinder就绪：environment.yml中的完整依赖关系规范
✅ 生产硬化：针对边缘情况进行6次系统指令改进迭代

1.0.0版本（首次发布）

✅ 具有完整功能的初始版本
✅ 集成Google Gemini 2.5 Flash与MCP和Google搜索基础
✅ 实施了三个NBA API工具（现场比赛、积分榜、球员统计数据）
✅ 构建了具有两列布局的高级glassmorphism UI
✅ 添加了对话历史和上下文管理
✅ 实现了三源归因（NBA API、谷歌搜索、Gemini LLM）
✅ 添加了快速操作和建议查询
✅ 创建了全面的文档

未来的增强功能

🔄 添加更多NBA工具（球队统计数据、比赛亮点、季后赛括号）
🔄 实施用户身份验证和保存对话
🔄 添加统计数据可视化
🔄 支持多个体育联盟
🔄 语音输入/输出功能

______________________________________________________________________

内置于❤️ 对于世界各地的篮球迷来说

Hoop Io

快速接入

详细介绍

🏀 Hoop.io-人工智能NBA助理

📖 概述

✨ 特性

🤖 智能查询处理

📊 NBA实时数据

🎨 高级用户界面

🚀 安装

先决条件

步骤1：克隆存储库

步骤2：后端设置

步骤3：前端设置

步骤4：启动应用程序

🌐 在MyBinder上部署（替代方案）

🛠️ 用法

基本查询

对话示例

📦 技术

后端

前端

建筑

🔧 配置

环境变量

系统说明（可选）

✅ 需求

Python依赖关系

节点依赖关系

🗂️ 存储库结构

关键部件说明

🔗 流程图

数据流说明

🤝 贡献

开发指南

📄 文档

额外资源

关键概念

❤️ 致谢

📝 更新日志

版本1.1.0（当前-2025年11月）

1.0.0版本（首次发布）

未来的增强功能

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP