Runbook

Quickstart (any developer machine)

This assumes you already have Python 3.10+ installed.

python -m venv .venv
# Activate:
#   Windows: .venv\Scripts\activate
#   macOS/Linux: source .venv/bin/activate

pip install --upgrade pip
pip install nba_api pbpstats pandas requests

Then run:

python truth_poc.py --date 2025-12-15 --max-games 1 --db pilot.sqlite --pbp-mode nba_api --sleep 1.5

Inspect the output

Check row counts:

python -c "import sqlite3; con=sqlite3.connect('pilot.sqlite');
print('schedule', con.execute('select count(*) from canonical_schedule_rest').fetchone()[0]);
print('box', con.execute('select count(*) from canonical_box_score').fetchone()[0]);
print('pbp', con.execute('select count(*) from canonical_pbp').fetchone()[0]);
con.close()"

Common gotcha: re-running into the same DB

If you rerun the same date/game into the same SQLite file, you may hit UNIQUE constraint errors depending on your capture timestamp strategy. Two easy ways around this:

• Use a new DB filename per test run, or
• Drop and recreate the target table(s) before re-ingesting.