PDFoverseer

https://github.com/zapatok/pdfoverseer
Admin
PDFoverseer is a PDF document analyzer that counts internal documents in lecture PDFs using OCR and...
Tokens:13,226
Snippets:90
Trust Score:3.6
Update:7 months ago
Show doc for...
Tokens:
Raw
### 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
          <div className="flex items-center space-x-4 text-sm text-gray-300">
            <button
              className="bg-panel hover:bg-surface px-3 py-1.5 rounded border border-[#313244] transition-colors"
              onClick={() => setCurrentPage(Math.max(1, currentPage - 1))}
              disabled={currentPage <= 1}
            >
              ← Anterior
            </button>
            <span className="font-mono">
              Página <input
                type="number"
                value={currentPage}
                onChange={(e) => 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}
            </span>
            <button
              className="bg-panel hover:bg-surface px-3 py-1.5 rounded border border-[#313244] transition-colors"
              onClick={() => setCurrentPage(Math.min(totalPages, currentPage + 1))}
              disabled={currentPage >= totalPages}
            >
              Siguiente →
            </button>
          </div>
```

--------------------------------

### 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
          <div className="flex items-center justify-end space-x-3 pt-2">
            <button
              className="bg-panel hover:bg-surface px-4 py-2 rounded border border-[#313244] transition-colors text-gray-300 text-sm"
              onClick={handleReset}
            >
              Limpiar
            </button>
            <button
              className="bg-panel hover:bg-surface px-4 py-2 rounded border border-[#313244] transition-colors text-gray-300 text-sm"
              onClick={handleCancel}
            >
              Cancelar
            </button>
            <button
              className="bg-accent hover:bg-accent/80 px-4 py-2 rounded transition-colors text-black font-bold text-sm"
              onClick={handleConfirm}
            >
              Seleccionar
            </button>
          </div>
```

--------------------------------

### 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
          <div className="bg-black/40 px-4 py-3 rounded font-mono text-sm text-gray-200 border border-white/5">
            <div className="grid grid-cols-4 gap-4">
              <div>
                <div className="text-gray-400 text-xs">x_start</div>
                <div className="font-bold text-accent">{selector.x_start.toFixed(3)}</div>
              </div>
              <div>
                <div className="text-gray-400 text-xs">x_end</div>
                <div className="font-bold text-accent">{selector.x_end.toFixed(3)}</div>
              </div>
              <div>
                <div className="text-gray-400 text-xs">y_start</div>
                <div className="font-bold text-accent">{selector.y_start.toFixed(3)}</div>
              </div>
              <div>
                <div className="text-gray-400 text-xs">y_end</div>
                <div className="font-bold text-accent">{selector.y_end.toFixed(3)}</div>
              </div>
            </div>
            {confirmed && (
              <div className="mt-2 text-green-400 text-xs font-bold">
                ✓ Coordenadas capturadas
              </div>
            )}
          </div>
```

--------------------------------

### 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
          <div className="flex items-center space-x-2">
            <button
              className="bg-panel hover:bg-surface px-3 py-1.5 rounded border border-[#313244] transition-colors text-sm"
              onClick={() => setZoomLevel(Math.max(0.5, zoomLevel - 0.25))}
            >
              − Zoom
            </button>
            <span className="text-sm text-gray-400 w-12 text-center">{Math.round(zoomLevel * 100)}%</span>
            <button
              className="bg-panel hover:bg-surface px-3 py-1.5 rounded border border-[#313244] transition-colors text-sm"
              onClick={() => setZoomLevel(Math.min(3, zoomLevel + 0.25))}
            >
              + Zoom
            </button>
          </div>
```

--------------------------------

### 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"}'
```
Tokens:
Raw