Add manual OCR page selection and deterministic review ordering

smoke_signal_tab.py

@@ -631,6 +631,48 @@ def log_line(msg: str) -> str:
     return f"[{datetime.utcnow().strftime('%H:%M:%S')}] {msg}"
 
 
+def _parse_page_selection(spec: str, max_page: int | None = None) -> tuple[set[int] | None, str | None]:
+    """
+    Parse optional page-selection text.
+    Accepted forms:
+      - empty / all / *  -> None (means all pages)
+      - "7"
+      - "3-8"
+      - "1,3,5-7"
+    """
+    raw = (spec or "").strip().lower()
+    if raw in ("", "all", "*"):
+        return None, None
+
+    out: set[int] = set()
+    for token in [t.strip() for t in raw.split(",") if t.strip()]:
+        if "-" in token:
+            parts = token.split("-", 1)
+            if len(parts) != 2 or (not parts[0].isdigit()) or (not parts[1].isdigit()):
+                return None, f"Invalid page range token: '{token}'"
+            start = int(parts[0])
+            end = int(parts[1])
+            if start <= 0 or end <= 0:
+                return None, f"Pages must be >= 1 (token: '{token}')"
+            if end < start:
+                return None, f"Range end before start (token: '{token}')"
+            out.update(range(start, end + 1))
+        else:
+            if not token.isdigit():
+                return None, f"Invalid page token: '{token}'"
+            page = int(token)
+            if page <= 0:
+                return None, f"Pages must be >= 1 (token: '{token}')"
+            out.add(page)
+
+    if max_page is not None:
+        out = {p for p in out if p <= int(max_page)}
+        if not out:
+            return None, f"No selected pages fall within this PDF (max page {max_page})."
+
+    return out, None
+
+
 # ── Step 1: INGEST ─────────────────────────────────────────────────────────────
 def ingest_pdfs(files, rights_class: str, notes: str) -> tuple:
     """Register uploaded PDFs into the source manifest."""
@@ -1196,7 +1238,7 @@ def _run_tesseract_batch(images):
     return outputs
 
 
-def run_ocr() -> tuple:
+def run_ocr(page_selection: str = "", replace_book_queue: bool = True) -> tuple:
     """Run Surya OCR on all profiled PDFs."""
     df = load_manifest_df()
     debug = f"[DEBUG] SS_ROOT={SS_ROOT}\nMANIFEST_CSV={MANIFEST_CSV}\nCSV exists={MANIFEST_CSV.exists()}\n"
@@ -1223,6 +1265,15 @@ def run_ocr() -> tuple:
 
     log = []
     queue_rows = []
+    processed_books = []
+    selection_set, selection_error = _parse_page_selection(page_selection)
+    if selection_error:
+        return _ocr_status_html(), f"{debug}Invalid page selection: {selection_error}"
+    if selection_set is None:
+        log.append(log_line("ℹ Page selection: all pages"))
+    else:
+        selected_preview = ",".join(str(p) for p in sorted(selection_set))
+        log.append(log_line(f"ℹ Page selection: {selected_preview}"))
 
     surya, surya_error, reused = _get_surya_runtime_with_timeout(SS_SURYA_LOAD_TIMEOUT_SEC)
     if surya:
@@ -1254,6 +1305,18 @@ def run_ocr() -> tuple:
 
         with open(profile_path, encoding="utf-8") as f:
             profile = json.load(f)
+        pages_all = profile.get("pages", [])
+        page_numbers = [int(p.get("page_number", 0) or 0) for p in pages_all]
+        max_page = max(page_numbers) if page_numbers else None
+        selected_pages_for_book = selection_set
+        if selection_set is not None:
+            selected_pages_for_book, sel_err = _parse_page_selection(page_selection, max_page=max_page)
+            if sel_err:
+                log.append(log_line(f"⚠ {book_id}: {sel_err}"))
+                continue
+            selected_preview = ",".join(str(p) for p in sorted(selected_pages_for_book))
+            log.append(log_line(f"ℹ {book_id}: selected pages {selected_preview}"))
+        processed_books.append(book_id)
 
         ocr_pages = []
         review_pages = []
@@ -1275,6 +1338,8 @@ def run_ocr() -> tuple:
         for page_data in profile.get("pages", []):
             page_num = page_data["page_number"]
             route = page_data["route"]
+            if selected_pages_for_book is not None and int(page_num) not in selected_pages_for_book:
+                continue
 
             if route == "embedded_text":
                 continue
@@ -1427,6 +1492,8 @@ def run_ocr() -> tuple:
         for page_data in profile.get("pages", []):
             page_num = page_data["page_number"]
             route = page_data["route"]
+            if selected_pages_for_book is not None and int(page_num) not in selected_pages_for_book:
+                continue
 
             if route == "embedded_text":
                 try:
@@ -1534,14 +1601,28 @@ def run_ocr() -> tuple:
 
         df.loc[df["book_id"] == book_id, "status"] = "ocred"
         total_review = len(review_pages) + len(quarantine_pages)
-        log.append(log_line(f"✓ {book_id}: {len(ocr_pages)}pp — review queue: {total_review}"))
+        log.append(log_line(f"✓ {book_id}: {len(ocr_pages)} selected pp — review queue: {total_review}"))
 
-    if queue_rows:
-        qdf = pd.DataFrame(queue_rows)
-        if QUEUE_CSV.exists():
-            existing = pd.read_csv(QUEUE_CSV)
-            qdf = pd.concat([existing, qdf], ignore_index=True).drop_duplicates(subset=["region_id"], keep="last")
-        qdf.to_csv(QUEUE_CSV, index=False)
+    qdf_new = pd.DataFrame(queue_rows)
+    if QUEUE_CSV.exists():
+        existing = pd.read_csv(QUEUE_CSV)
+    else:
+        existing = pd.DataFrame()
+
+    if replace_book_queue and processed_books and not existing.empty and "book_id" in existing.columns:
+        existing = existing[~existing["book_id"].isin(processed_books)]
+
+    if not existing.empty and not qdf_new.empty:
+        qdf_out = pd.concat([existing, qdf_new], ignore_index=True).drop_duplicates(subset=["region_id"], keep="last")
+    elif not qdf_new.empty:
+        qdf_out = qdf_new
+    else:
+        qdf_out = existing
+
+    if not qdf_out.empty:
+        qdf_out.to_csv(QUEUE_CSV, index=False)
+    elif QUEUE_CSV.exists():
+        QUEUE_CSV.unlink()
 
     save_manifest_df(df)
     return _ocr_status_html(), "\n".join(log)
@@ -1586,6 +1667,8 @@ def get_review_item(idx: int) -> tuple:
 
     decided_ids = set(d_df["region_id"].tolist()) if not d_df.empty else set()
     pending     = q_df[~q_df["region_id"].isin(decided_ids)]
+    if not pending.empty and {"book_id", "page"}.issubset(pending.columns):
+        pending = pending.sort_values(["book_id", "page"], ascending=[True, True], kind="stable")
     if pending.empty:
         return None, "All items reviewed!", "", len(q_df), len(q_df)
 
@@ -1939,11 +2022,21 @@ def smoke_signal_tab():
                     </div>
                 </div>""")
 
+                ocr_page_selection = gr.Textbox(
+                    label="Pages to OCR (optional)",
+                    placeholder="all or e.g. 7 or 3-8 or 1,4,9-12",
+                    lines=1,
+                )
+                ocr_replace_queue = gr.Checkbox(
+                    label="Replace existing review queue entries for processed books",
+                    value=True,
+                )
                 ocr_btn = gr.Button("Run OCR →", elem_classes=["ss-btn-run"])
                 ocr_log = gr.Textbox(label="Log", lines=10, interactive=False, elem_classes=["ss-log"])
 
                 ocr_run_event = ocr_btn.click(
                     run_ocr,
+                    inputs=[ocr_page_selection, ocr_replace_queue],
                     outputs=[ocr_status, ocr_log],
                     show_progress="minimal",
                 )