### Install and Verify Dependencies Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-ocr-matcher.md Commands to install necessary Python packages for OCR matching and verify their availability in the environment. ```bash pip install regex weighted-levenshtein numpy python -c "import regex; import weighted_levenshtein; print('OK')" ``` -------------------------------- ### GET /api/preview Source: https://context7.com/zapatok/pdfoverseer/llms.txt Retrieves a PNG image of the top 25% of a specific page for visual review. ```APIDOC ## GET /api/preview ### Description Retrieves a PNG image of the top 25% of a specific page for visual review. ### Method GET ### Endpoint /api/preview ### Parameters #### Query Parameters - **pdf_path** (string) - Required - The path to the PDF document. - **page** (integer) - Required - The page number to preview (1-based index). ### Request Example ```bash curl -X GET "http://localhost:8000/api/preview?pdf_path=/path/documento.pdf&page=45" --output preview.png ``` ### Response #### Success Response (200) - Content-Type: image/png (binary data) #### Response Example (Binary PNG image data) ``` -------------------------------- ### GET /api/add_folder Source: https://context7.com/zapatok/pdfoverseer/llms.txt Opens a native system dialog to select a folder and recursively adds all PDF files found to the processing queue. ```APIDOC ## GET /api/add_folder ### Description Opens a native system dialog to select a folder and recursively adds all PDF files found to the processing queue. ### Method GET ### Endpoint /api/add_folder ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **pdfs** (array) - List of added PDF objects with name, path, and status. #### Response Example { "success": true, "pdfs": [ {"name": "CH_39docs.pdf", "path": "/path/to/CH_39docs.pdf", "status": "pending"} ] } ``` -------------------------------- ### GET /api/open_pdf Source: https://context7.com/zapatok/pdfoverseer/llms.txt Opens the specified PDF file in the operating system's default viewer. ```APIDOC ## GET /api/open_pdf ### Description Opens the PDF file in the operating system's default viewer. ### Method GET ### Endpoint /api/open_pdf ### Parameters #### Query Parameters - **pdf_path** (string) - Required - The path to the PDF document. - **page** (integer) - Optional - The page number to open to (1-based index). ### Request Example ```bash curl -X GET "http://localhost:8000/api/open_pdf?pdf_path=/path/documento.pdf&page=1" ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. #### Error Response (e.g., 404) - **success** (boolean) - Indicates failure. - **error** (string) - Error message (e.g., "File not found"). #### Response Example (Success) ```json { "success": true } ``` ``` -------------------------------- ### GET /api/state Source: https://context7.com/zapatok/pdfoverseer/llms.txt Retrieves the full current state of the backend, including file status, global metrics, and detected issues. ```APIDOC ## GET /api/state ### Description Returns the complete state of the backend, including the list of PDFs, global metrics, and detected issues. Useful for frontend state synchronization. ### Method GET ### Endpoint /api/state ### Response #### Success Response (200) - **running** (boolean) - Current processing status. - **pdf_list** (array) - List of PDFs and their current status. - **issues** (array) - List of inference issues detected. - **metrics** (object) - Global processing metrics. #### Response Example { "running": true, "pdf_list": [], "metrics": { "docs": 90, "complete": 85 } } ``` -------------------------------- ### Control PDF Processing Lifecycle Source: https://context7.com/zapatok/pdfoverseer/llms.txt Endpoints to start, pause, resume, skip, or stop the PDF analysis pipeline. These commands manage the background worker threads and state transitions. ```bash curl -X POST "http://localhost:8000/api/start" -H "Content-Type: application/json" -d '{"start_index": 0}' curl -X POST "http://localhost:8000/api/pause" curl -X POST "http://localhost:8000/api/resume" curl -X POST "http://localhost:8000/api/stop" curl -X POST "http://localhost:8000/api/skip" ``` -------------------------------- ### Initialize ocr_matcher Package Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-ocr-matcher.md Scaffolding the project structure by creating the package directory and the initialization file. ```python """ocr_matcher — OCR-aware fuzzy word matching. Standalone, off-pipeline.""" ``` -------------------------------- ### POST /api/start Source: https://context7.com/zapatok/pdfoverseer/llms.txt Initiates the PDF processing pipeline from a specified index, running in a separate thread. ```APIDOC ## POST /api/start ### Description Starts the processing of the PDF queue from a specific index. The analysis runs in a background thread and emits events via WebSocket. ### Method POST ### Endpoint /api/start ### Request Body - **start_index** (integer) - Required - The index in the queue to begin processing from. ### Request Example { "start_index": 0 } ### Response #### Success Response (200) - **success** (boolean) - Status of the operation. #### Response Example { "success": true } ``` -------------------------------- ### Execute Tests and Version Control Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-ocr-matcher.md Standard terminal commands for verifying the OCR pattern logic via pytest and committing the changes to the repository. ```bash pytest tests/test_ocr_pattern.py -v git add ocr_matcher/pattern.py tests/test_ocr_pattern.py git commit -m "feat(ocr_matcher): charclass + fuzzy pattern generator" ``` -------------------------------- ### Preview PDF Page (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Generates a PNG image of the top 25% of a specified PDF page for visual review. Requires the PDF path and page number as query parameters. The output is a binary PNG image. ```bash curl -X GET "http://localhost:8000/api/preview?pdf_path=/path/documento.pdf&page=45" \ --output preview.png ``` -------------------------------- ### Create History Entry and Load History (Python) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Demonstrates how to create a `HistoryEntry` object with PDF results and add it to the history using `add_entry`. It also shows how to load the complete history and iterate through entries, printing details. This functionality is crucial for tracking analysis sessions. ```python from datetime import datetime # Assuming PDFResult and HistoryEntry classes are defined elsewhere # and add_entry, load_history, clear_history are available functions. pdf_results = [ PDFResult( name="CH_39docs.pdf", path="/path/to/CH_39docs.pdf", total_docs=39, complete=38, incomplete=1, inferred=3 ), PDFResult( name="CH_51docs.pdf", path="/path/to/CH_51docs.pdf", total_docs=51, complete=51, incomplete=0, inferred=5 ) ] entry = HistoryEntry( date=datetime.now().strftime("%Y-%m-%d %H:%M:%S"), source="/path/to/carpeta", source_name="carpeta", is_folder=True, total_docs=90, total_complete=89, total_incomplete=1, total_inferred=8, pdfs=pdf_results, is_session=False ) # Add to history (persists automatically) add_entry(entry) # Load complete history history = load_history() for e in history: print(f"{e.date}: {e.source_name} - {e.total_docs} docs ({e.total_complete} completos)") # Clear history clear_history() ``` -------------------------------- ### Run Pytest for Pixel Density Tests Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-pixel-density.md Executes the pytest test suite for the pixel density module. This command navigates to the project's worktree directory and runs all tests defined in 'test_pixel_density.py' using the virtual environment's Python interpreter. It's used to verify the correctness of the implemented pure functions. ```bash cd A:/PROJECTS/PDFoverseer/.worktrees/pixel-density ../../.venv-cuda/Scripts/python -m pytest test_pixel_density.py -v ``` -------------------------------- ### Generate Adjacent Parameter Configurations (Python) Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-eval-harness.md Creates a list of configurations that are one step away from a given 'base' configuration in the parameter space. It iterates through each parameter and generates new configurations by adjusting the parameter's value to its immediate neighbors within 'PARAM_SPACE'. ```python def adjacent_configs(base: dict) -> list[dict]: """All single-param adjacent-step perturbations of base config.""" configs = [] for k, vals in PARAM_SPACE.items(): idx = vals.index(base[k]) for new_idx in [idx - 1, idx + 1]: if 0 <= new_idx < len(vals): cfg = dict(base) cfg[k] = vals[new_idx] configs.append(cfg) return configs ``` -------------------------------- ### Open PDF in Native Viewer (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Opens a specified PDF file using the operating system's default PDF viewer application. Requires the PDF path and optionally a page number to open to. Returns a success or error message. ```bash curl -X GET "http://localhost:8000/api/open_pdf?pdf_path=/path/documento.pdf&page=1" ``` -------------------------------- ### Implement Confusion Matrix Module Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-ocr-matcher.md The core module defining the character substitution cost table using a NumPy matrix to represent OCR error probabilities. ```python """ confusion.py — OCR character substitution cost table. Costs are in range [0.0, 1.0]: 0.0 = same character (free) 0.05–0.15 = very common OCR confusion 0.2–0.4 = plausible OCR confusion 1.0 = default (unrelated characters) """ import numpy as np ``` -------------------------------- ### Test OCR Confusion Matrix Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-ocr-matcher.md Unit tests for the confusion matrix module, ensuring bidirectional cost symmetry, correct diagonal values, and expected costs for common OCR errors. ```python from ocr_matcher.confusion import substitution_cost, build_matrix def test_identical_chars_cost_zero(): assert substitution_cost('a', 'a') == 0.0 def test_common_ocr_pair_low_cost(): assert substitution_cost('g', 'q') < 0.2 assert substitution_cost('q', 'g') < 0.2 def test_unrelated_chars_full_cost(): assert substitution_cost('g', 'z') == 1.0 def test_matrix_shape(): m = build_matrix() assert m.shape == (128, 128) def test_matrix_diagonal_zero(): import numpy as np m = build_matrix() assert all(m[i, i] == 0.0 for i in range(128)) def test_matrix_is_symmetric_for_known_pair(): m = build_matrix() assert m[ord('g'), ord('q')] == m[ord('q'), ord('g')] ``` -------------------------------- ### Manage PDF File Selection via API Source: https://context7.com/zapatok/pdfoverseer/llms.txt Endpoints to trigger native system dialogs for adding folders or individual PDF files to the processing queue. Returns a list of added files with their initial status. ```bash curl -X GET "http://localhost:8000/api/add_folder" curl -X GET "http://localhost:8000/api/add_files" ``` -------------------------------- ### Compute Dark Pixel Ratios for All PDF Pages Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-pixel-density.md Opens a PDF file and calculates the dark pixel ratio for each page using the 'render_thumbnail' and 'dark_ratio' functions. It takes the PDF file path and desired DPI for rendering as input. The function returns a list of float values, where each float represents the dark ratio for a corresponding page in the PDF. ```python import fitz # PyMuPDF import numpy as np def compute_ratios(pdf_path: str, dpi: int) -> list[float]: """Open a PDF and return dark_ratio for every page. Args: pdf_path: Path to the PDF file. dpi: Render resolution passed to render_thumbnail. Returns: List of floats, one per page, 0-indexed. """ doc = fitz.open(pdf_path) ratios: list[float] = [] for page in doc: img = render_thumbnail(page, dpi) ratios.append(dark_ratio(img)) doc.close() return ratios ``` -------------------------------- ### Retrieve System State and Metrics Source: https://context7.com/zapatok/pdfoverseer/llms.txt Fetches the current status of the backend, including the PDF queue, processing metrics, and detected inference issues. Useful for synchronizing frontend state. ```bash curl -X GET "http://localhost:8000/api/state" ``` -------------------------------- ### Capture OCR Failures from PDF (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt A command-line tool to capture pages with OCR failures from PDFs. It saves images of pages where Tesseract fails, with options to include EasyOCR results and specify an output directory. ```bash # Capturar fallos de un PDF específico python tools/capture_failures.py /path/to/documento.pdf # Capturar fallos de todos los PDFs en un directorio python tools/capture_failures.py /path/to/carpeta/ # Incluir resultados de EasyOCR Tier 3 python tools/capture_failures.py /path/to/documento.pdf --easyocr # Especificar directorio de salida python tools/capture_failures.py /path/to/documento.pdf --out /custom/output/ # Salida: # [capture] CH_39docs: 78 pages # [FAIL] page 37 — saved CH_39docs/p037_20260317_143022.png # [FAIL] page 45 — saved CH_39docs/p045_20260317_143023.png # [capture] done: 2 failures / 78 pages ``` -------------------------------- ### Find Pages with Similar Dark Pixel Ratio Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-pixel-density.md Identifies pages within a list of dark pixel ratios that are close to a reference page's ratio. It takes a list of ratios, the index of the reference page, and a threshold as input. It returns a sorted list of 0-based page indices, including the reference page index, whose dark ratios fall within the specified threshold. ```python def find_matches(ratios: list[float], ref_idx: int, threshold: float) -> list[int]: """Return 0-based page indices whose dark_ratio is within threshold of ref. Args: ratios: dark_ratio per page (0-indexed). ref_idx: 0-based index of the reference page. threshold: absolute tolerance (e.g. 0.08 means ±8 percentage points). Returns: Sorted list of matching 0-based page indices (always includes ref_idx). """ ref = ratios[ref_idx] return [i for i, r in enumerate(ratios) if abs(r - ref) <= threshold] ``` -------------------------------- ### Render PDF Page as Grayscale Thumbnail Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-pixel-density.md Renders a single PDF page into a low-resolution grayscale NumPy array. It utilizes the PyMuPDF library to create a pixmap at a specified DPI and converts it into a 2-D uint8 grayscale array. This is a utility function for image processing tasks on PDF documents. ```python import fitz # PyMuPDF import numpy as np def render_thumbnail(page: fitz.Page, dpi: int = 15) -> np.ndarray: """Render one PDF page as a grayscale numpy array at low DPI. Args: page: PyMuPDF page object. dpi: Render resolution. 15 DPI gives ~124×175 px for A4. Returns: 2-D uint8 grayscale array (H × W). """ mat = fitz.Matrix(dpi / 72, dpi / 72) pix = page.get_pixmap(matrix=mat, colorspace=fitz.csGRAY, alpha=False) # alpha=False guarantees pix.n == 1 (no alpha channel), reshape is safe. return np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.h, pix.w) ``` -------------------------------- ### Generate OCR-Resilient Regex Patterns Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-ocr-matcher.md Generates a regex pattern for a given word that incorporates character-class alternatives for OCR noise. It supports mandatory prefixes and optional suffixes to handle abbreviations and common character substitutions. ```python def generate_charclass_pattern(word: str, min_prefix: int = 2) -> str: word = word.strip() n = len(word) if n == 0: return "" prefix_len = min(min_prefix, n) prefix_chars = word[:prefix_len] suffix_chars = word[prefix_len:] first = _char_class(prefix_chars[0]) if len(prefix_chars) == 1: prefix_pat = first else: rest = "".join(_char_class(c) for c in prefix_chars[1:]) prefix_pat = first + (".?" if n > min_prefix else "") + rest if suffix_chars: suffix_pat = "".join(_char_class(c) for c in suffix_chars) full_pat = prefix_pat + f"(?:{suffix_pat})?" else: full_pat = prefix_pat return r"\b" + full_pat + r"\.?" ``` -------------------------------- ### Generate Latin Hypercube Samples (Python) Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-eval-harness.md Generates 'n' well-distributed parameter configurations from a predefined 'PARAM_SPACE' using the Latin Hypercube Sampling method. It ensures that each parameter's sampled values are spread across its possible range. A random seed can be provided for reproducibility. ```python def lhs_sample(n: int, seed: int = RANDOM_SEED) -> list[dict]: """Generate n well-distributed configs from PARAM_SPACE using LHS.""" rng = random.Random(seed) keys = list(PARAM_SPACE.keys()) # For each param, divide n slots and sample one per slot indices_per_param: dict[str, list[int]] = {} for k, vals in PARAM_SPACE.items(): m = len(vals) # Map n slots → m values slots = [rng.randint(0, m - 1) for _ in range(n)] rng.shuffle(slots) indices_per_param[k] = slots configs = [] for i in range(n): cfg = {k: PARAM_SPACE[k][indices_per_param[k][i]] for k in keys} configs.append(cfg) return configs ``` -------------------------------- ### POST /api/correct Source: https://context7.com/zapatok/pdfoverseer/llms.txt Applies a manual correction to a specific page and re-runs the inference engine. ```APIDOC ## POST /api/correct ### Description Applies a manual correction to a specific page and re-runs the inference engine to propagate changes. ### Method POST ### Endpoint /api/correct ### Parameters #### Request Body - **pdf_path** (string) - Required - The path to the PDF document. - **page** (integer) - Required - The page number to correct (1-based index). - **correct_curr** (integer) - Required - The correct current page number. - **correct_tot** (integer) - Required - The correct total number of pages. ### Request Example ```json { "pdf_path": "/path/to/documento.pdf", "page": 45, "correct_curr": 2, "correct_tot": 3 } ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. #### Error Response (e.g., 400) - **success** (boolean) - Indicates failure. - **msg** (string) - Error message (e.g., "PDF reads not found in memory"). #### Response Example (Success) ```json { "success": true } ``` ``` -------------------------------- ### Generate Fuzzy Matching Patterns Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-ocr-matcher.md Creates a fuzzy regex pattern compatible with the 'regex' library. It allows for a specified edit distance (k) to match strings despite insertions, deletions, or substitutions. ```python def generate_fuzzy_pattern(word: str, k: int = 1) -> str: escaped = re.escape(word.strip()) return rf"({escaped}){{e<={k}}}" ``` -------------------------------- ### Run Inference Engine Parameter Sweep (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Executes a 3-pass parameter sweep (Latin Hypercube, fine grid, beam search) to optimize inference engine parameters. This command-line execution is part of the eval/sweep.py script. ```bash # Ejecutar barrido completo (~500k combinaciones) cd /path/to/PDFoverseer python eval/sweep.py # Salida: # Loaded 25 fixtures, 25 ground truth entries # Scoring baseline (production params)... # baseline composite=45 doc_exact=23 passes=20/25 # # Pass 1: Latin Hypercube Sample (500 configs)... # Pass1: 500/500 done # # Pass 2: Fine grid around top-20... # Pass2: 180/180 done # # Pass 3: Beam search from top-5... # Pass3: 50/50 done # # Results saved to eval/results/sweep_20260317_143022.json # Top config: composite=52 regressions=0 ``` -------------------------------- ### Correct PDF Page Reading (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Applies a manual correction to a specific PDF page and re-runs the inference engine. Requires the PDF path, page number, and the correct page values. Returns a success or error message. ```bash curl -X POST "http://localhost:8000/api/correct" \ -H "Content-Type: application/json" \ -d '{ "pdf_path": "/path/to/documento.pdf", "page": 45, "correct_curr": 2, "correct_tot": 3 }' ``` -------------------------------- ### Programmatic Inference Engine Parameter Sweep (Python) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Provides programmatic access to the parameter sweeping functionality for the inference engine. It involves loading fixtures and ground truth data, then scoring configurations using functions from eval.sweep. ```python # Uso programático del sweep from eval.sweep import load_fixtures, load_ground_truth, score_config from eval.params import PRODUCTION_PARAMS fixtures = load_fixtures() gt = load_ground_truth() # Evaluar configuración actual de producción result = score_config(PRODUCTION_PARAMS, fixtures, gt, baseline_passes=set()) print(f"Puntaje compuesto: {result['composite_score']}") print(f"Documentos exactos: {result['doc_count_exact']}") print(f"Delta inferidos: {result['inferred_delta']}") print(f"Regresiones: {result['regression_count']}") # Ver resultados por fixture for name, status in result['_fixture_results'].items(): print(f" {name}: {status}") ``` -------------------------------- ### Monitor PDF processing with WebSockets Source: https://context7.com/zapatok/pdfoverseer/llms.txt Establishes a WebSocket connection to the PDFOverseer server to receive real-time updates. It handles various event types such as logs, file progress, global metrics, and issue detection to update the UI accordingly. ```javascript const ws = new WebSocket('ws://localhost:8000/ws'); ws.onmessage = (event) => { const msg = JSON.parse(event.data); switch(msg.type) { case 'log': console.log(`[${msg.payload.level}] ${msg.payload.msg}`); break; case 'file_progress': updateFileProgress(msg.payload.done, msg.payload.total); break; case 'global_progress': updateGlobalProgress(msg.payload); break; case 'status_update': updatePdfStatus(msg.payload.idx, msg.payload.status); break; case 'metrics': updateMetrics(msg.payload); break; case 'new_issue': addIssue(msg.payload); break; case 'issues_refresh': refreshIssues(msg.payload); break; case 'process_finished': onProcessComplete(msg.payload.metrics); break; } }; ``` -------------------------------- ### List Historical Sessions (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Retrieves a list of all previously saved sessions, ordered by date in descending order. This endpoint does not require any request body. Returns a JSON object containing an array of session data. ```bash curl -X GET "http://localhost:8000/api/sessions" ``` -------------------------------- ### Commit Pixel Density Code Changes Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-pixel-density.md Stages and commits changes related to the pixel density module. This command adds the modified Python files ('pixel_density.py' and 'test_pixel_density.py') to the Git staging area and then creates a commit with a descriptive message indicating the addition of pure functions and tests. ```bash cd A:/PROJECTS/PDFoverseer/.worktrees/pixel-density git add pixel_density.py test_pixel_density.py git commit -m "feat(pixel-density): pure functions dark_ratio + find_matches with tests" ``` -------------------------------- ### Manage Analysis History with Python Source: https://context7.com/zapatok/pdfoverseer/llms.txt Provides functions for persisting and retrieving analysis results using the `history.py` module. It includes functionalities for loading, saving, adding entries, and clearing the history. ```python from history import ( load_history, save_history, add_entry, clear_history, HistoryEntry, PDFResult ) from datetime import datetime ``` -------------------------------- ### Execute evaluation test suites Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-inference-tuning.md Commands to run specific scoring tests and the full evaluation test suite using pytest. ```bash cd a:/PROJECTS/PDFoverseer && python -m pytest eval/tests/test_sweep_scoring.py -v cd a:/PROJECTS/PDFoverseer && python -m pytest eval/tests/ -v ``` -------------------------------- ### Reset Server Session Source: https://context7.com/zapatok/pdfoverseer/llms.txt Clears the backend state, removing all loaded PDFs and resetting metrics for a fresh processing session. ```bash curl -X POST "http://localhost:8000/api/reset" ``` -------------------------------- ### Analyze PDF with OCR Engine Source: https://context7.com/zapatok/pdfoverseer/llms.txt Executes the V4 analysis pipeline on a PDF file using parallel Tesseract workers and GPU-accelerated OCR. It accepts control events for pausing/canceling and callbacks for progress and issue reporting. ```python from core.analyzer import analyze_pdf import threading pause_event = threading.Event() pause_event.set() cancel_event = threading.Event() def on_progress(done: int, total: int): print(f"Progreso: {done}/{total} páginas") def on_log(msg: str, level: str = "info"): print(f"[{level}] {msg}") def on_issue(page: int, kind: str, detail: str, pil_img): print(f"Issue en página {page}: {kind} - {detail}") documents, reads = analyze_pdf( pdf_path="/path/to/documento.pdf", on_progress=on_progress, on_log=on_log, pause_event=pause_event, cancel_event=cancel_event, on_issue=on_issue, doc_mode="charla" ) ``` -------------------------------- ### Page Navigation Component in React Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-crop-selector.md Implements navigation controls for a PDF viewer, allowing users to move between pages. It includes buttons for 'Previous' and 'Next' pages, and an input field to directly set the current page number. Dependencies include React state management for `currentPage` and `totalPages`. ```jsx
Página setCurrentPage(Math.min(totalPages, Math.max(1, parseInt(e.target.value) || 1)))} className="w-12 px-2 py-1 bg-black/40 border border-white/10 rounded text-white text-center" min="1" max={totalPages} /> de {totalPages}
``` -------------------------------- ### Save Current Session (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Persists the current session's final metrics and statistics to a local JSON file. This endpoint does not require any request body. Returns a success message with the path to the saved session file. ```bash curl -X POST "http://localhost:8000/api/save_session" ``` -------------------------------- ### Programmatic OCR Failure Capture (Python) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Enables programmatic capture of OCR failures from PDFs using the `capture_pdf` function. It returns a list of dictionaries, each containing details about the failed page and OCR results from different tiers. ```python # Uso programático from tools.capture_failures import capture_pdf # Capturar fallos de un PDF rows = capture_pdf( pdf_path="/path/to/documento.pdf", out_dir="data/ocr_failures", include_easyocr=True ) # Cada row contiene: for row in rows: print(f"Página {row['page_num']}:") print(f" Imagen: {row['image_path']}") print(f" Tier 1 (Tesseract): {row['tier1_text'][:50]}...") print(f" Tier 2 (SR+Tess): {row['tier2_text'][:50]}...") print(f" Tier 3 (EasyOCR): {row['tier3_text'][:50]}...") ``` -------------------------------- ### Score PDF Processing Pipeline Results (Python) Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-eval-harness.md Calculates various scoring metrics for PDF processing results, including exact and delta document counts, completeness, inferred page counts, and regressions. It also provides per-fixture pass/fail status and a composite score. This function requires ground truth data and pipeline parameters. ```python def score_config(params: dict, fixtures: list[dict], gt: dict[str, dict], baseline_passes: set[str]) -> dict: """ Returns scores dict: doc_count_exact, doc_count_delta, complete_count_exact, inferred_delta, regression_count, composite_score And per-fixture pass/fail. """ doc_exact = doc_delta = complete_exact = inf_delta = regressions = 0 fixture_results = {} for fx in fixtures: name = fx["name"] if name not in gt: continue truth = gt[name] docs = run_pipeline(fx["reads"], params) got_docs = len(docs) got_complete = sum(1 for d in docs if d.is_complete) got_inferred = sum(len(d.inferred_pages) for d in docs) d_doc = abs(got_docs - truth["doc_count"]) d_comp = got_docs == truth["doc_count"] and got_complete == truth["complete_count"] d_inf = abs(got_inferred - truth["inferred_count"]) passed = (d_doc == 0 and d_comp) if d_doc == 0: doc_exact += 1 doc_delta += d_doc if d_comp: complete_exact += 1 inf_delta += d_inf if name in baseline_passes and not passed: regressions += 1 fixture_results[name] = "pass" if passed else "fail" composite = doc_exact * 3 + complete_exact * 2 - doc_delta - inf_delta - regressions * 5 return { "doc_count_exact": doc_exact, "doc_count_delta": doc_delta, "complete_count_exact": complete_exact, "inferred_delta": inf_delta, "regression_count": regressions, "composite_score": composite, "_fixture_results": fixture_results, } ``` -------------------------------- ### Calculate Dark Pixel Ratio in Grayscale Image Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-pixel-density.md Computes the fraction of pixels in a grayscale image that are strictly darker than mid-grey (value < 128). It takes a 2-D uint8 grayscale NumPy array as input and returns a float between 0.0 and 1.0, representing the proportion of dark pixels. ```python import numpy as np def dark_ratio(img: np.ndarray) -> float: """Return fraction of pixels strictly darker than mid-grey (value < 128). Args: img: 2-D uint8 grayscale array (H × W). Returns: Float in [0.0, 1.0]; 1.0 = all black, 0.0 = all white. """ return float((img < 128).mean()) ``` -------------------------------- ### POST /api/exclude Source: https://context7.com/zapatok/pdfoverseer/llms.txt Marks a page as excluded from analysis and recalculates inference. ```APIDOC ## POST /api/exclude ### Description Marks a page as excluded from analysis (e.g., covers, dividers) and recalculates inference. ### Method POST ### Endpoint /api/exclude ### Parameters #### Request Body - **pdf_path** (string) - Required - The path to the PDF document. - **page** (integer) - Required - The page number to exclude (1-based index). ### Request Example ```json { "pdf_path": "/path/to/documento.pdf", "page": 1 } ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. #### Response Example ```json { "success": true } ``` ``` -------------------------------- ### Re-infer documents with manual corrections Source: https://context7.com/zapatok/pdfoverseer/llms.txt Allows for the adjustment of OCR results by applying manual page numbering corrections and excluding specific pages. This function re-runs the inference engine to update document structures based on user input. ```python from core.analyzer import re_infer_documents original_reads = [...] corrections = {45: (2, 3), 89: (1, 2)} exclusions = [1, 50, 100] def on_log(msg, level="info"): print(f"[{level}] {msg}") def on_issue(page, kind, detail, pil_img): print(f"Issue: página {page} - {kind}") documents, new_reads = re_infer_documents( reads=original_reads, corrections=corrections, on_log=on_log, on_issue=on_issue, exclusions=exclusions ) ``` -------------------------------- ### Session Management API Source: https://context7.com/zapatok/pdfoverseer/llms.txt Endpoints for managing PDF analysis sessions, including saving, listing, and deleting historical sessions. ```APIDOC ## POST /api/save_session ### Description Persists the current session's final metrics and statistics to a local JSON file. ### Method POST ### Endpoint /api/save_session ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. - **path** (string) - The path to the saved session JSON file. #### Response Example ```json { "success": true, "path": "data/sessions/session_20260317_143022.json" } ``` ## GET /api/sessions ### Description Returns all previously saved sessions, ordered by descending date. ### Method GET ### Endpoint /api/sessions ### Response #### Success Response (200) - **sessions** (array) - A list of historical sessions. - Each session object contains: - **timestamp** (string) - The timestamp of the session. - **metrics** (object) - Session metrics (docs, complete, incomplete, inferred, total_time). - **issues_count** (integer) - Number of issues found. - **files_processed** (integer) - Number of files processed. #### Response Example ```json { "sessions": [ { "timestamp": "20260317_143022", "metrics": {"docs": 150, "complete": 142, "incomplete": 8, "inferred": 23, "total_time": 245.7}, "issues_count": 15, "files_processed": 7 }, { "timestamp": "20260316_091532", "metrics": {"docs": 80, "complete": 78, "incomplete": 2, "inferred": 5, "total_time": 120.3}, "issues_count": 3, "files_processed": 4 } ] } ``` ## POST /api/delete_session ### Description Deletes a saved session from the history. ### Method POST ### Endpoint /api/delete_session ### Parameters #### Request Body - **timestamp** (string) - Required - The timestamp of the session to delete. ### Request Example ```json { "timestamp": "20260316_091532" } ``` ### Response #### Success Response (200) - **success** (boolean) - Indicates if the operation was successful. #### Response Example ```json { "success": true } ``` ``` -------------------------------- ### Exclude PDF Page from Analysis (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Marks a specific page in a PDF as excluded from analysis, such as cover pages or dividers, and recalculates inference. Requires the PDF path and the page number to exclude. Returns a success message. ```bash curl -X POST "http://localhost:8000/api/exclude" \ -H "Content-Type: application/json" \ -d '{ "pdf_path": "/path/to/documento.pdf", "page": 1 }' ``` -------------------------------- ### Action Buttons Component in React Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-crop-selector.md Implements action buttons for a PDF selection interface, including 'Limpiar' (Clear), 'Cancelar' (Cancel), and 'Seleccionar' (Select). Each button has distinct styling and triggers corresponding handler functions (`handleReset`, `handleCancel`, `handleConfirm`). ```jsx
``` -------------------------------- ### Detect Document Repetition Period with Python Source: https://context7.com/zapatok/pdfoverseer/llms.txt Analyzes OCR reads to detect document repetition periods using spacing, common totals, and autocorrelation. Requires the _PageRead class and _detect_period function from core.analyzer. ```python from core.analyzer import _detect_period, _PageRead # Simular reads de un PDF con documentos de 2 páginas cada uno reads = [ _PageRead(pdf_page=1, curr=1, total=2, method="direct", confidence=1.0), _PageRead(pdf_page=2, curr=2, total=2, method="direct", confidence=1.0), _PageRead(pdf_page=3, curr=1, total=2, method="direct", confidence=1.0), _PageRead(pdf_page=4, curr=2, total=2, method="direct", confidence=1.0), _PageRead(pdf_page=5, curr=None, total=None, method="failed", confidence=0.0), _PageRead(pdf_page=6, curr=2, total=2, method="SR", confidence=1.0), ] period_info = _detect_period(reads) print(f"Periodo detectado: {period_info['period']} páginas/ciclo") print(f"Confianza: {period_info['confidence']:.0%}") print(f"Total esperado: {period_info['expected_total']}") # Salida esperada: # Periodo detectado: 2 páginas/ciclo # Confianza: 85% # Total esperado: 2 ``` -------------------------------- ### Update score_config logic for source-aware evaluation Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-inference-tuning.md Modifies the scoring function to branch logic based on the fixture source. Real fixtures are evaluated primarily on document count with heavier penalties, while synthetic fixtures maintain original multi-metric validation. ```python def score_config(params: dict, fixtures: list[dict], gt: dict[str, dict], baseline_passes: set[str]) -> dict: doc_exact = complete_exact = inf_delta = regressions = 0 real_doc_delta = syn_doc_delta = 0 fixture_results = {} for fx in fixtures: name = fx["name"] if name not in gt: continue truth = gt[name] is_real = fx.get("source", "synthetic") == "real" docs = run_pipeline(fx["reads"], params) got_docs = len(docs) got_complete = sum(1 for d in docs if d.is_complete) got_inferred = sum(len(d.inferred_pages) for d in docs) d_doc = abs(got_docs - truth["doc_count"]) if is_real: passed = (d_doc == 0) if d_doc == 0: doc_exact += 5 else: real_doc_delta += d_doc else: d_comp = (got_docs == truth["doc_count"] and got_complete == truth["complete_count"]) d_inf = abs(got_inferred - truth["inferred_count"]) passed = (d_doc == 0 and d_comp) if d_doc == 0: doc_exact += 3 if d_comp: complete_exact += 2 syn_doc_delta += d_doc inf_delta += d_inf if name in baseline_passes and not passed: regressions += 1 fixture_results[name] = "pass" if passed else "fail" composite = (doc_exact + complete_exact - real_doc_delta * 3 - syn_doc_delta - inf_delta - regressions * 5) return { "doc_count_exact": doc_exact, "doc_count_delta": real_doc_delta + syn_doc_delta, "complete_count_exact": complete_exact, "inferred_delta": inf_delta, "regression_count": regressions, "composite_score": composite, "_fixture_results": fixture_results, } ``` -------------------------------- ### Coordinate Display Component in React Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-crop-selector.md Displays selected coordinate values (x_start, x_end, y_start, y_end) from a PDF selection tool. It formats the coordinates to three decimal places and shows a confirmation message when coordinates are captured. This component relies on a `selector` object and a `confirmed` boolean state. ```jsx
x_start
{selector.x_start.toFixed(3)}
x_end
{selector.x_end.toFixed(3)}
y_start
{selector.y_start.toFixed(3)}
y_end
{selector.y_end.toFixed(3)}
{confirmed && (
✓ Coordenadas capturadas
)}
``` -------------------------------- ### Zoom Controls Component in React Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-15-crop-selector.md Provides UI elements for adjusting the zoom level of a PDF viewer. It includes buttons to decrease and increase zoom, and a display showing the current zoom percentage. The zoom level is managed by a `zoomLevel` state variable, with defined minimum (0.5) and maximum (3) values. ```jsx
{Math.round(zoomLevel * 100)}%
``` -------------------------------- ### Commit evaluation changes Source: https://github.com/zapatok/pdfoverseer/blob/master/docs/superpowers/plans/2026-03-16-inference-tuning.md Git command to stage and commit the updated scoring logic with a descriptive message. ```bash git add eval/sweep.py eval/tests/test_sweep_scoring.py git commit -m "feat(eval): source-aware scoring — real fixtures +5/−3×delta, complete_count excluded" ``` -------------------------------- ### Remove PDF from Queue Source: https://context7.com/zapatok/pdfoverseer/llms.txt Removes a specific PDF from the processing queue by its file path and cleans up associated data. ```bash curl -X POST "http://localhost:8000/api/remove_pdf?pdf_path=/path/to/documento.pdf" ``` -------------------------------- ### Delete Historical Session (Bash) Source: https://context7.com/zapatok/pdfoverseer/llms.txt Deletes a specific saved session from the history. Requires a JSON payload containing the timestamp of the session to be deleted. Returns a success message. ```bash curl -X POST "http://localhost:8000/api/delete_session" \ -H "Content-Type: application/json" \ -d '{"timestamp": "20260316_091532"}' ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.