scripts: round-2 peer-review fixes (year derivation + render cap)

- parse_bills_to_tracker: bill_id and encounter_id year tokens are
  now derived from the row's own statement_date / DOS instead of the
  current calendar year, so a 2025-dated statement processed in 2026
  still gets numbered under 2025. Added a small _year_of() helper to
  centralize the parse.
- classify_rename_medical_bills: render_pdf_pages now stops iterating
  after MAX_PAGES, matching the fix already applied to classify_eobs.
  Previously the full PDF was rasterized in memory and then sliced,
  which was wasteful on multi-page itemizations.
- scripts/README.md: documents that --help / CLI overrides cover
  input/output paths but the Azure OpenAI .env path is intentionally
  hardcoded to the workspace-wide location per AGENTS.md §4.

Author: k3rt4s

scripts/README.md

@@ -51,7 +51,7 @@ Skips rows whose `status` is settled or closed. Returns exit code 1 if any bill
 
 The scripts below are for a single-workstation pipeline that takes a folder full of scanned medical-bill PDFs and turns it into a clean per-provider folder layout plus a tracker CSV the LLM workflow can consume. They are deliberately not part of the kit's instruction-only contract: they call Azure OpenAI for vision OCR, expect a specific local folder layout, and read API credentials from a workstation `.env`. Use them, ignore them, or rewrite them to fit your own setup.
 
-All four accept `--help` and CLI overrides for every default path.
+All four accept `--help` and CLI overrides for every input/output path. The Azure OpenAI `.env` location is the one exception, intentionally hardcoded to `C:/Code/projects/ai-toolkit/.env` per the workspace-wide AGENTS.md §4 pre-push peer review pattern — edit the constant at the top of each script if your workstation keeps the credentials somewhere else.
 
 ### classify_rename_medical_bills.py
 

scripts/classify_rename_medical_bills.py

@@ -142,12 +142,17 @@ def make_client():
     )
 
 
-def render_pdf_pages(pdf_path: Path) -> list[bytes]:
+def render_pdf_pages(pdf_path: Path, max_pages: int = MAX_PAGES) -> list[bytes]:
+    """Render up to max_pages of the PDF as JPEG bytes; stop iterating
+    after the cap to avoid paying the render cost on pages we will not
+    send to the model."""
     doc = fitz.open(str(pdf_path))
     pages: list[bytes] = []
     zoom = RENDER_DPI / 72.0
     mat = fitz.Matrix(zoom, zoom)
-    for page in doc:
+    for i, page in enumerate(doc):
+        if i >= max_pages:
+            break
         pix = page.get_pixmap(matrix=mat)
         pages.append(pix.tobytes("jpeg", jpg_quality=JPEG_QUALITY))
     doc.close()
@@ -275,7 +280,7 @@ def process_file(client, deployment, path: Path,
 
     if suffix == ".pdf":
         try:
-            images = render_pdf_pages(path)
+            images = render_pdf_pages(path, max_pages=MAX_PAGES)
         except Exception as exc:
             print(f"  [skip] render failed: {exc}", flush=True)
             return
@@ -285,11 +290,6 @@ def process_file(client, deployment, path: Path,
         print(f"  [skip] unsupported type: {suffix}", flush=True)
         return
 
-    if len(images) > MAX_PAGES:
-        print(f"  [warn] {len(images)} pages, capping at {MAX_PAGES}",
-              flush=True)
-        images = images[:MAX_PAGES]
-
     try:
         result = call_vision(client, deployment, images)
     except Exception as exc:

scripts/parse_bills_to_tracker.py

@@ -296,6 +296,13 @@ def normalize_account(acct) -> str:
     return re.sub(r"\s+", "", str(acct))
 
 
+def _year_of(iso_date: str | None) -> int | None:
+    if not iso_date or len(iso_date) < 4 or not iso_date[:4].isdigit():
+        return None
+    y = int(iso_date[:4])
+    return y if 1900 <= y <= 2100 else None
+
+
 def _merge_into(existing: dict, statement_date: str | None,
                  current_balance: float | None) -> None:
     """Update an existing bill row with a newer statement's data."""
@@ -358,13 +365,18 @@ def make_bill_record(extracted: dict, source_file: Path,
                 _merge_into(existing, statement_date, current_balance)
                 return None, "merged"
 
-    # New bill
-    year = datetime.date.today().year
-    bill_seq[year] = bill_seq.get(year, 0) + 1
-    bill_id = f"B-{year}-{bill_seq[year]:03d}"
+    # New bill. Derive the bill_id year from the row's own statement_date
+    # (or DOS start, then last_statement_date) rather than today, so that
+    # late-arriving 2025 statements processed in 2026 are still numbered
+    # under 2025 instead of jumping years.
+    bill_year = _year_of(statement_date) or _year_of(dos_start) \
+        or datetime.date.today().year
+    bill_seq[bill_year] = bill_seq.get(bill_year, 0) + 1
+    bill_id = f"B-{bill_year}-{bill_seq[bill_year]:03d}"
 
     # Encounter assignment: share encounter_id with any existing bill that
-    # has the same date_of_service_start
+    # has the same date_of_service_start. Year of the encounter id is the
+    # year of the DOS itself.
     encounter_id = ""
     if dos_start:
         for existing in known_bills:
@@ -373,8 +385,9 @@ def make_bill_record(extracted: dict, source_file: Path,
                 encounter_id = existing["encounter_id"]
                 break
     if not encounter_id and dos_start:
-        encounter_seq[year] = encounter_seq.get(year, 0) + 1
-        encounter_id = f"E-{year}-{encounter_seq[year]:03d}"
+        enc_year = _year_of(dos_start) or bill_year
+        encounter_seq[enc_year] = encounter_seq.get(enc_year, 0) + 1
+        encounter_id = f"E-{enc_year}-{encounter_seq[enc_year]:03d}"
 
     findings = extracted.get("findings") or []
     if not isinstance(findings, list):