NBA Statistical Engine

A natural language to SQL web app for exploring historical NBA statistics. Type plain-English questions like "Who averaged the most points in 2022-23?" and get real data back — with charts.

How It Works

1. You type a question in natural language
2. The AI (Llama 3.3 70B via Groq) translates it into a SQL query
3. The query runs against a local SQLite database of NBA stats
4. Results are displayed as a table and auto-generated chart

Tech Stack

Layer	Technology
Frontend	React, Vite, Tailwind CSS, Recharts
Backend	FastAPI (Python)
Database	SQLite
Data Source	nba_api (NBA.com)
AI	Llama 3.3 70B via Groq API

Data Coverage

• Seasons: 2015-16 through 2023-24
• Players: ~1,350 with per-game season averages (points, assists, rebounds, shooting splits, etc.)
• Teams: All 30 NBA teams with season records, ratings, and pace
• Records: ~4,800 player-season stats, ~270 team-season stats

Setup

Prerequisites

• Python 3.10+
• Node.js 20+
• Free Groq API key

Backend

cd backend
pip install -r requirements.txt

# Fetch NBA data (~5 min, only needed once)
python seed/fetch_data.py

# Seed the SQLite database
python seed/seed_db.py

# Start the API server
uvicorn main:app --reload

Frontend

cd frontend
npm install
npm run dev

Environment Variables

Copy .env.example to .env and add your Groq API key:

GROQ_API_KEY=gsk_your_key_here

Screenshots

LeBron James stats by season — multi-season breakdown with chart and full stat table:

Compare Jokic and Embiid — side-by-side player comparison:

Example Questions

• "Who averaged the most points per game in 2022-23?"
• "Show me LeBron's scoring average by season"
• "Which team had the best net rating in 2017-18?"
• "Best 3PT shooters with 60+ games in 2023-24"
• "Warriors win/loss record from 2015 to 2019"
• "Compare Jokic and Embiid last season"

Architecture

├── backend/
│   ├── main.py          # FastAPI app with /query endpoint
│   ├── ai.py            # Groq API integration (NL → SQL)
│   ├── database.py      # SQLite query executor
│   ├── schema.sql       # Database schema (injected into AI prompt)
│   └── seed/            # Data pipeline (fetch + seed scripts)
├── frontend/
│   └── src/
│       ├── App.jsx              # Main layout and state management
│       ├── api.js               # Backend API client
│       └── components/
│           ├── QueryInput.jsx   # Search bar with typewriter effect
│           ├── ResultsTable.jsx # Dynamic data table
│           ├── ResultsChart.jsx # Auto-generated bar charts
│           ├── QueryHistory.jsx # Collapsible sidebar history
│           ├── EmptyState.jsx   # Landing page with example queries
│           ├── ErrorState.jsx   # Error display
│           └── LoadingSkeleton.jsx
└── nba.db               # SQLite database (generated, gitignored)

Safety

• Only SELECT queries are allowed — INSERT, DROP, ATTACH, etc. are blocked
• Server-side row limit (100 max) regardless of AI output
• User input truncated to 500 characters
• SQL injection patterns detected and rejected

License

MIT