---
title: Scouting · Racing Santander
emoji: ⚽
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: true
---

# Scouting · Racing Santander

FastAPI + DuckDB scouting dashboard. Reuses the visual design of the static
HTML report but loads data from a Hugging Face Dataset and recomputes scoring
on the server.

## Required Space secrets

Set these in **Settings → Repository secrets** of the Space:

| Secret | Required | Purpose |
|---|---|---|
| `APP_PASSWORD` | yes | Shared password for the login gate |
| `SESSION_SECRET` | yes | Random string used to sign auth cookies |
| `DATASET_REPO_ID` | yes | HF dataset repo id, e.g. `racing-tools/scouting-data` |
| `HF_TOKEN` | yes if dataset is private | Read-scope token for the dataset repo |
| `DATA_MAX_AGE_HOURS` | no | Cache TTL before re-pulling the dataset (default 24) |

## Local development

```bash
cd scouting
# 1. produce parquets locally (one-time / on refresh)
python ingest_azure.py
python build_player_season.py
python enrich_attrs.py
python enrich_tm.py --skip-extra --limit 100

# 2. point app to the local data dir and run
export DATA_DIR=$(pwd)/data/clean
cd app && uvicorn main:app --reload --port 7860
```

Open http://localhost:7860/ — no `APP_PASSWORD` set means dev-mode (any
password is accepted on the login form, or skip if env unset).

## Refreshing data without a Docker rebuild

```bash
HF_TOKEN=hf_xxx python scripts/push_to_hf_dataset.py
```

Then restart the Space (Settings → Factory rebuild) — the next boot pulls the
new parquets via `huggingface_hub.snapshot_download`.

## Architecture

- `app/main.py` — FastAPI app, mounts static, registers routes
- `app/data.py` — DuckDB on parquet, registers `base` view joining player_season + tm_enrichment
- `app/scoring.py` — wraps `scouting_score.py` for in-memory scoring with custom weights
- `app/auth.py` — signed-cookie shared-password gate
- `app/routes/` — meta / score / player / best11 endpoints
- `app/static/` — extracted HTML, CSS, JS from `generate_report.py` with `fetch()` calls

## API quick reference

- `GET /api/meta` — seasons, leagues, positions, blocks
- `POST /api/score` — filtered + scored player-season rows
- `GET /api/player/{playerId}?season=24-25` — full detail
- `POST /api/best11` — top-1 per pitch slot
- `POST /api/login` — set auth cookie
- `GET /api/auth-status` — whether the current session is authenticated
- `GET /healthz` — bypasses auth, returns row counts