Refactor: modular project with uv, Typer CLI, Streamlit, and Pydantic

[scottfrasso]

Summary

Breaks the monolithic 767-line pipeline.py into a proper Python package with modern tooling and an interactive Streamlit dashboard for data exploration.

• uv + pyproject.toml replaces zero-dep stdlib approach with managed dependencies
• Typer CLI with run, explore, serve, and cache-clear commands
• Pydantic models for data validation (CleanedRecord, DashboardStats)
• Streamlit app with folium heatmap + plotly charts for interactive local exploration
• python-dateutil for robust datetime parsing (replaces manual format loops)
• Caching layer in tmp/ to avoid slow CKAN API re-fetches during development
• ruff + mypy (strict) for linting and type checking
• lefthook for pre-commit hooks (ruff + mypy)
• CI split: all check jobs run in parallel with an all-checks-pass gate
• pydantic-ai added as dependency for future AI agent work
• Static HTML generation preserved for GitHub Pages deployment

Streamlit Dashboard

New CLI

$ uv run boston-needle-map --help

 Usage: boston-needle-map [OPTIONS] COMMAND [ARGS]...

 Boston 311 Needle Hotspot Pipeline

╭─ Commands ──────────────────────────────────────╮
│ run          Fetch + compute + generate HTML    │
│ explore      Launch Streamlit dashboard         │
│ cache-clear  Clear tmp/ cache                   │
│ serve        Preview docs/ locally              │
╰─────────────────────────────────────────────────╯

Test plan

• uv sync installs all dependencies
• uv run boston-needle-map run generates docs/index.html and docs/needle_data.json
• uv run boston-needle-map explore launches Streamlit with heatmap and charts
• uv run boston-needle-map cache-clear clears tmp/ cache
• uv run ruff check src/ passes clean
• uv run mypy src/ passes strict mode
• lefthook install && git commit runs pre-commit hooks
• CI workflow runs all checks in parallel with gate job

🤖 Generated with Claude Code