#!/usr/bin/env python3
# Author: Simon-Pierre Boucher — contact@spboucher.ai
"""Step 01 — Build the estimation sample.

Reads the raw DuckDB snapshot (``data/raw/realtor_mls_unique.duckdb``),
parses the semi-structured fields, applies the sample restrictions and trims,
and writes ``data/processed/analysis.parquet``.

Usage:  python scripts/01_build_sample.py
"""
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))

from wp9 import sample  # noqa: E402


def main() -> None:
    s = sample.build_and_save()
    by_cat = s.groupby("cat").size().to_dict()
    print(f"Estimation sample written: {len(s):,} listings")
    print(f"  by category : {by_cat}")
    print(f"  by province : {s.groupby('prov').size().to_dict()}")
    print(f"  FSA levels  : {s['fsa_c'].nunique():,} (incl. pooled residual categories)")


if __name__ == "__main__":
    main()