Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /AmberLee2427_nancy-brain /nancy_brain /pdf_ocr.py
"""PDF OCR helpers with cache-aware markdown extraction."""
from __future__ import annotations
import hashlib
import json
import logging
import os
import shlex
import subprocess
import tempfile
import time
import tomllib
from dataclasses import dataclass
from importlib.util import find_spec
from pathlib import Path
from typing import Optional
logger = logging.getLogger(__name__)
DEFAULT_DEEPSEEK_MODEL = os.environ.get("NB_PDF_OCR_DEEPSEEK_MODEL", "deepseek-ai/DeepSeek-OCR")
DEFAULT_DEEPSEEK_PROMPT = os.environ.get(
"NB_PDF_OCR_DEEPSEEK_PROMPT",
"<image>\n<|grounding|>Convert the document to markdown.",
)
DEFAULT_RENDER_SCALE = float(os.environ.get("NB_PDF_OCR_RENDER_SCALE", "2.0"))
DEFAULT_BASE_SIZE = int(os.environ.get("NB_PDF_OCR_DEEPSEEK_BASE_SIZE", "1024"))
DEFAULT_IMAGE_SIZE = int(os.environ.get("NB_PDF_OCR_DEEPSEEK_IMAGE_SIZE", "640"))
DEFAULT_CROP_MODE = os.environ.get("NB_PDF_OCR_DEEPSEEK_CROP_MODE", "true").strip().lower() == "true"
DEFAULT_BACKEND = os.environ.get("NB_PDF_OCR_BACKEND", "auto").strip().lower() or "auto"
CACHE_VERSION = 1
DEEPSEEK_RUNTIME_MODULES = {
"addict": "addict",
"easydict": "easydict",
"einops": "einops",
"matplotlib": "matplotlib",
"torchvision": "torchvision",
}
PROJECT_OCR_WORKER_CONFIG_FILENAMES = ("ocr_worker.toml", "ocr-worker.toml")
def _normalize_quantization_mode(value: Optional[str]) -> Optional[str]:
raw = (value or "").strip().lower()
if raw in {"", "none", "off", "false", "fp16", "full", "16bit"}:
return None
if raw in {"4", "4bit", "int4", "nf4"}:
return "4bit"
if raw in {"8", "8bit", "int8"}:
return "8bit"
if raw == "auto":
return "auto"
return raw
def _quantization_threshold_gib(env_name: str, default: float) -> float:
raw = os.environ.get(env_name, "").strip()
if not raw:
return default
try:
return float(raw)
except Exception:
return default
def _configured_deepseek_quantization_mode() -> Optional[str]:
explicit = os.environ.get("NB_PDF_OCR_QUANTIZE", "")
if explicit.strip():
return _normalize_quantization_mode(explicit)
shared = os.environ.get("NB_QUANTIZE", "")
if shared.strip():
return _normalize_quantization_mode(shared)
return "auto"
def _resolve_deepseek_quantization_mode(torch_module) -> Optional[str]:
configured = _configured_deepseek_quantization_mode()
if configured != "auto":
return configured
cuda = getattr(torch_module, "cuda", None)
if cuda is None or not getattr(cuda, "is_available", lambda: False)():
return None
try:
current_device = getattr(cuda, "current_device", lambda: 0)()
props = cuda.get_device_properties(current_device)
total_memory_gib = props.total_memory / float(1024**3)
except Exception:
return None
four_bit_max = _quantization_threshold_gib("NB_PDF_OCR_AUTO_4BIT_MAX_GIB", 16.0)
eight_bit_max = _quantization_threshold_gib("NB_PDF_OCR_AUTO_8BIT_MAX_GIB", 24.0)
if total_memory_gib <= four_bit_max:
return "4bit"
if total_memory_gib <= eight_bit_max:
return "8bit"
return None
def _deepseek_attention_kwargs_candidates(quantization_mode: Optional[str]) -> list[dict]:
attn_impl = os.environ.get("NB_PDF_OCR_ATTN_IMPLEMENTATION")
if attn_impl is not None:
attn_impl = attn_impl.strip()
if attn_impl:
return [{"_attn_implementation": attn_impl}, {}]
return [{}]
if quantization_mode:
return [{}]
return [{"_attn_implementation": "flash_attention_2"}, {}]
@dataclass(frozen=True)
class PDFOCRBackendStatus:
"""Availability status for an OCR backend."""
name: str
available: bool
reason: Optional[str] = None
model: Optional[str] = None
@dataclass(frozen=True)
class PDFOCRResult:
"""OCR output for a single PDF."""
markdown: Optional[str]
backend: str
cached: bool
cache_key: str
status: str = "generated"
needs_ocr: bool = False
deferred: bool = False
model: Optional[str] = None
page_count: int = 0
warning: Optional[str] = None
def to_worker_record(
self,
pdf_path: Path | str,
*,
cache_dir: Optional[Path | str] = None,
) -> dict:
"""Return the machine-facing OCR worker payload.
The worker contract is limited to the OCR markdown cache entry:
it reports where the cache lives, but it does not touch embeddings
or summary artifacts.
"""
pdf_path = Path(pdf_path).resolve()
cache_root = (Path(cache_dir) if cache_dir is not None else default_pdf_ocr_cache_dir()).resolve()
cache_key = self.cache_key or None
cache_entry_dir = cache_root / cache_key if cache_key else None
content_path = cache_entry_dir / "content.md" if cache_entry_dir is not None else None
metadata_path = cache_entry_dir / "metadata.json" if cache_entry_dir is not None else None
return {
"pdf_path": str(pdf_path),
"cache_dir": str(cache_root),
"cache_key": cache_key,
"cache_entry_dir": str(cache_entry_dir) if cache_entry_dir is not None else None,
"content_path": str(content_path) if content_path is not None else None,
"metadata_path": str(metadata_path) if metadata_path is not None else None,
"backend": self.backend,
"status": self.status,
"cached": self.cached,
"needs_ocr": self.needs_ocr,
"deferred": self.deferred,
"model": self.model,
"page_count": self.page_count,
"warning": self.warning,
}
def build_pdf_ocr_worker_record(
pdf_path: Path | str,
*,
cache_dir: Optional[Path | str] = None,
backend: Optional[str] = None,
status: str = "error",
warning: Optional[str] = None,
result: Optional[PDFOCRResult] = None,
) -> dict:
"""Build a stable machine-facing OCR worker payload.
The returned schema matches successful and deferred worker results so
subprocess callers can rely on the same keys even during hard failures.
"""
pdf_path = Path(pdf_path).resolve()
cache_root = (Path(cache_dir) if cache_dir is not None else default_pdf_ocr_cache_dir()).resolve()
if result is not None:
payload = result.to_worker_record(pdf_path, cache_dir=cache_dir)
if payload.get("cache_key") is None:
payload["cache_entry_dir"] = None
payload["content_path"] = None
payload["metadata_path"] = None
return payload
cache_key = None
cache_entry_dir = None
content_path = None
metadata_path = None
return {
"pdf_path": str(pdf_path),
"cache_dir": str(cache_root),
"cache_key": cache_key,
"cache_entry_dir": cache_entry_dir,
"content_path": content_path,
"metadata_path": metadata_path,
"backend": backend or "worker",
"status": status,
"cached": False,
"needs_ocr": False,
"deferred": False,
"model": None,
"page_count": 0,
"warning": warning,
}
class DeepSeekOCRBackend:
"""DeepSeek OCR backend backed by the upstream transformers integration."""
name = "deepseek"
def __init__(
self,
*,
model_name: str = DEFAULT_DEEPSEEK_MODEL,
prompt: str = DEFAULT_DEEPSEEK_PROMPT,
render_scale: float = DEFAULT_RENDER_SCALE,
base_size: int = DEFAULT_BASE_SIZE,
image_size: int = DEFAULT_IMAGE_SIZE,
crop_mode: bool = DEFAULT_CROP_MODE,
) -> None:
self.model_name = model_name
self.prompt = prompt.rstrip()
self.render_scale = render_scale
self.base_size = base_size
self.image_size = image_size
self.crop_mode = crop_mode
self._tokenizer = None
self._model = None
def status(self) -> PDFOCRBackendStatus:
try:
import torch
except Exception as exc:
return PDFOCRBackendStatus(
name=self.name,
available=False,
reason=f"torch unavailable: {exc}",
model=self.model_name,
)
if not torch.cuda.is_available():
return PDFOCRBackendStatus(
name=self.name,
available=False,
reason="CUDA unavailable",
model=self.model_name,
)
try:
import transformers
from transformers import AutoModel, AutoTokenizer # noqa: F401
except Exception as exc:
return PDFOCRBackendStatus(
name=self.name,
available=False,
reason=f"transformers unavailable: {exc}",
model=self.model_name,
)
try:
from transformers.models.llama.modeling_llama import LlamaFlashAttention2 # noqa: F401
except Exception as exc:
tokenizers_version = "unknown"
try:
import tokenizers
tokenizers_version = getattr(tokenizers, "__version__", "unknown")
except Exception:
pass
return PDFOCRBackendStatus(
name=self.name,
available=False,
reason=(
"incompatible transformers stack for DeepSeek OCR "
f"(transformers {getattr(transformers, '__version__', 'unknown')}, "
f"tokenizers {tokenizers_version}): {exc}. "
"DeepSeek OCR upstream is tested on transformers==4.46.3 and tokenizers==0.20.3."
),
model=self.model_name,
)
missing_modules = [
package for module_name, package in DEEPSEEK_RUNTIME_MODULES.items() if find_spec(module_name) is None
]
if missing_modules:
return PDFOCRBackendStatus(
name=self.name,
available=False,
reason="missing DeepSeek OCR runtime deps: " + ", ".join(missing_modules),
model=self.model_name,
)
quantization_mode = _resolve_deepseek_quantization_mode(torch)
if quantization_mode and find_spec("bitsandbytes") is None:
return PDFOCRBackendStatus(
name=self.name,
available=False,
reason=f"missing DeepSeek OCR quantization runtime dep: bitsandbytes ({quantization_mode})",
model=self.model_name,
)
return PDFOCRBackendStatus(name=self.name, available=True, model=self.model_name)
def signature(self) -> dict:
quantization_mode = None
try:
import torch
quantization_mode = _resolve_deepseek_quantization_mode(torch)
except Exception:
quantization_mode = _configured_deepseek_quantization_mode()
return {
"backend": self.name,
"model": self.model_name,
"prompt": self.prompt,
"render_scale": self.render_scale,
"base_size": self.base_size,
"image_size": self.image_size,
"crop_mode": self.crop_mode,
"quantize": quantization_mode or "none",
"cache_version": CACHE_VERSION,
}
def ensure_loaded(self) -> None:
if self._model is not None and self._tokenizer is not None:
return
status = self.status()
if not status.available:
raise RuntimeError(status.reason or "DeepSeek OCR unavailable")
import torch
from transformers import AutoModel, AutoTokenizer
logger.info("Loading DeepSeek OCR tokenizer: model=%s", self.model_name)
self._tokenizer = AutoTokenizer.from_pretrained(self.model_name, trust_remote_code=True)
quantization_mode = _resolve_deepseek_quantization_mode(torch)
model_kwargs_candidates = _deepseek_attention_kwargs_candidates(quantization_mode)
logger.info(
"Loading DeepSeek OCR model: model=%s quantize=%s candidates=%s",
self.model_name,
quantization_mode or "none",
len(model_kwargs_candidates),
)
load_errors: list[str] = []
for extra_kwargs in model_kwargs_candidates:
try:
dtype = torch.bfloat16 if getattr(torch.cuda, "is_bf16_supported", lambda: False)() else torch.float16
common_kwargs = {
"trust_remote_code": True,
"use_safetensors": True,
**extra_kwargs,
}
attn_label = extra_kwargs.get("_attn_implementation", "default")
logger.info(
"Attempting DeepSeek OCR load: model=%s quantize=%s attention=%s",
self.model_name,
quantization_mode or "none",
attn_label,
)
if quantization_mode in {"4bit", "8bit"}:
from transformers import BitsAndBytesConfig
if quantization_mode == "4bit":
quantization_config = BitsAndBytesConfig(
load_in_4bit=True,
bnb_4bit_compute_dtype=dtype,
bnb_4bit_quant_type="nf4",
)
else:
quantization_config = BitsAndBytesConfig(load_in_8bit=True)
model = AutoModel.from_pretrained(
self.model_name,
quantization_config=quantization_config,
device_map="auto",
low_cpu_mem_usage=True,
**common_kwargs,
)
self._model = model.eval()
else:
model = AutoModel.from_pretrained(
self.model_name,
**common_kwargs,
)
self._model = model.eval().cuda().to(dtype)
_prepare_deepseek_generation_defaults(self._model, self._tokenizer)
logger.info(
"Loaded DeepSeek OCR model: model=%s quantize=%s attention=%s",
self.model_name,
quantization_mode or "none",
attn_label,
)
return
except Exception as exc:
label = extra_kwargs.get("_attn_implementation", "default")
if quantization_mode:
label = f"{quantization_mode}/{label}"
logger.warning(
"DeepSeek OCR load attempt failed: model=%s variant=%s error=%s", self.model_name, label, exc
)
load_errors.append(f"{label}: {exc}")
raise RuntimeError("failed to load DeepSeek OCR model: " + " | ".join(load_errors))
def ocr_images(self, image_paths: list[Path]) -> str:
self.ensure_loaded()
import torch
page_outputs: list[str] = []
total_pages = len(image_paths)
for page_num, image_path in enumerate(image_paths, start=1):
page_start = time.monotonic()
logger.info(
"DeepSeek OCR page start: model=%s page=%s/%s image=%s",
self.model_name,
page_num,
total_pages,
image_path,
)
with tempfile.TemporaryDirectory(prefix="nancy-deepseek-page-") as temp_dir:
output_dir = Path(temp_dir)
with torch.inference_mode():
infer_kwargs = {
"prompt": self.prompt,
"image_file": str(image_path),
"output_path": str(output_dir),
"base_size": self.base_size,
"image_size": self.image_size,
"crop_mode": self.crop_mode,
"save_results": True,
"test_compress": False,
"eval_mode": True,
}
try:
result = self._model.infer(self._tokenizer, **infer_kwargs)
except TypeError as exc:
if "eval_mode" not in str(exc):
raise
logger.warning(
"DeepSeek OCR infer() does not accept eval_mode; retrying without it: model=%s",
self.model_name,
)
infer_kwargs.pop("eval_mode", None)
result = self._model.infer(self._tokenizer, **infer_kwargs)
page_markdown = _coerce_deepseek_output(result, output_dir)
if page_markdown:
page_outputs.append(f"## Page {page_num}\n\n{page_markdown.strip()}")
logger.info(
"DeepSeek OCR page complete: model=%s page=%s/%s seconds=%.2f chars=%s",
self.model_name,
page_num,
total_pages,
time.monotonic() - page_start,
len(page_markdown.strip()),
)
else:
logger.warning("DeepSeek OCR returned no markdown for page %s (%s)", page_num, image_path)
return "\n\n".join(chunk for chunk in page_outputs if chunk)
_DEEPSEEK_BACKEND = DeepSeekOCRBackend()
def _token_id(tokenizer, attr_name: str) -> Optional[int]:
token_id = getattr(tokenizer, attr_name, None)
if token_id is not None:
return token_id
token_attr = attr_name.replace("_id", "")
token = getattr(tokenizer, token_attr, None)
if token is None:
return None
converter = getattr(tokenizer, "convert_tokens_to_ids", None)
if converter is None:
return None
try:
converted = converter(token)
except Exception:
return None
if not isinstance(converted, int):
return None
return converted if converted >= 0 else None
def _prepare_deepseek_generation_defaults(model, tokenizer) -> None:
"""Patch DeepSeek-OCR generation defaults omitted by upstream infer()."""
pad_token_id = _token_id(tokenizer, "pad_token_id")
eos_token_id = _token_id(tokenizer, "eos_token_id")
for config_attr in ("config", "generation_config"):
config = getattr(model, config_attr, None)
if config is None:
continue
if pad_token_id is not None and getattr(config, "pad_token_id", None) is None:
setattr(config, "pad_token_id", pad_token_id)
if eos_token_id is not None and getattr(config, "eos_token_id", None) is None:
setattr(config, "eos_token_id", eos_token_id)
if getattr(model, "_nancy_generation_defaults_patched", False):
return
original_generate = getattr(model, "generate", None)
if original_generate is None:
return
def generate_with_defaults(*args, **kwargs):
if kwargs.get("attention_mask") is None:
input_ids = kwargs.get("input_ids")
if input_ids is None and args:
input_ids = args[0]
if input_ids is not None and hasattr(input_ids, "new_ones"):
kwargs["attention_mask"] = input_ids.new_ones(input_ids.shape)
if kwargs.get("pad_token_id") is None and pad_token_id is not None:
kwargs["pad_token_id"] = pad_token_id
if kwargs.get("eos_token_id") is None and eos_token_id is not None:
kwargs["eos_token_id"] = eos_token_id
return original_generate(*args, **kwargs)
model.generate = generate_with_defaults
model._nancy_generation_defaults_patched = True
def default_pdf_ocr_cache_dir(project_root: Optional[Path] = None) -> Path:
env_override = os.environ.get("NB_PDF_OCR_CACHE_DIR", "").strip()
if env_override:
return Path(env_override)
if project_root is None:
project_root = _discover_pdf_ocr_project_root()
return project_root / "knowledge_base" / "cache" / "pdf_ocr"
def _discover_pdf_ocr_project_root() -> Path:
cwd = Path.cwd().resolve()
for candidate in [cwd, *cwd.parents]:
if (candidate / "knowledge_base").is_dir():
return candidate
if candidate.name == "knowledge_base":
return candidate.parent
for candidate in [cwd, *cwd.parents]:
if (candidate / "pyproject.toml").exists() or (candidate / ".git").exists():
return candidate
return cwd
def compute_pdf_content_hash(pdf_path: Path | str) -> str:
pdf_path = Path(pdf_path)
hasher = hashlib.sha256()
with pdf_path.open("rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
hasher.update(chunk)
return hasher.hexdigest()
def get_pdf_ocr_backend_status(preferred_backend: Optional[str] = None) -> PDFOCRBackendStatus:
backend_name = (preferred_backend or DEFAULT_BACKEND).strip().lower()
if backend_name in {"", "auto"}:
status = _DEEPSEEK_BACKEND.status()
if status.available:
return status
return PDFOCRBackendStatus(name="none", available=False, reason=status.reason, model=status.model)
if backend_name in {"none", "skip"}:
return PDFOCRBackendStatus(name="none", available=False, reason="OCR disabled by configuration")
if backend_name == "deepseek":
return _DEEPSEEK_BACKEND.status()
return PDFOCRBackendStatus(
name=backend_name,
available=False,
reason=f"unsupported OCR backend: {backend_name}",
)
def extract_pdf_markdown(
pdf_path: Path | str,
*,
cache_dir: Optional[Path | str] = None,
preferred_backend: Optional[str] = None,
worker_cmd: Optional[str | list[str]] = None,
allow_worker_spawn: bool = True,
) -> PDFOCRResult:
pdf_path = Path(pdf_path)
resolved_pdf_path = pdf_path.resolve(strict=False)
cache_root = Path(cache_dir) if cache_dir is not None else default_pdf_ocr_cache_dir()
cache_root.mkdir(parents=True, exist_ok=True)
cache_key = compute_pdf_content_hash(pdf_path)
cache_entry_dir = cache_root / cache_key
backend = _select_backend(preferred_backend)
if backend is None:
cached_result = _load_cached_result(cache_entry_dir, cache_key, preferred_backend=preferred_backend)
if cached_result is not None:
logger.info("OCR cache hit: pdf=%s cache_key=%s", resolved_pdf_path, cache_key)
return cached_result
if allow_worker_spawn and not _backend_is_cache_only(preferred_backend):
logger.info("OCR cache miss, delegating to worker: pdf=%s cache_key=%s", resolved_pdf_path, cache_key)
worker_result = _run_worker_subprocess(
pdf_path,
cache_root=cache_root,
cache_key=cache_key,
preferred_backend=preferred_backend,
worker_cmd=worker_cmd,
)
if worker_result is not None:
return worker_result
status = get_pdf_ocr_backend_status(preferred_backend)
logger.warning(
"OCR unavailable for PDF: pdf=%s backend=%s reason=%s",
resolved_pdf_path,
status.name,
status.reason or "unknown",
)
return PDFOCRResult(
markdown=None,
backend=status.name,
cached=False,
cache_key=cache_key,
status="needs_ocr",
needs_ocr=True,
deferred=True,
model=status.model,
warning=status.reason or "No OCR backend available",
)
cached_result = _load_cached_result(
cache_entry_dir,
cache_key,
preferred_backend=preferred_backend,
signature=backend.signature(),
)
if cached_result is not None:
logger.info("OCR cache hit: pdf=%s cache_key=%s", resolved_pdf_path, cache_key)
return cached_result
logger.info("OCR start: pdf=%s backend=%s cache_key=%s", resolved_pdf_path, backend.name, cache_key)
extraction_start = time.monotonic()
try:
with tempfile.TemporaryDirectory(prefix="nancy-pdf-pages-") as temp_dir:
logger.info("Rendering PDF for OCR: pdf=%s scale=%.2f", resolved_pdf_path, backend.render_scale)
image_paths = render_pdf_to_images(
pdf_path,
output_dir=Path(temp_dir),
scale=backend.render_scale,
)
logger.info("Rendered PDF pages: pdf=%s pages=%s", resolved_pdf_path, len(image_paths))
markdown = backend.ocr_images(image_paths)
except Exception as exc:
logger.exception("OCR failed for PDF: pdf=%s", resolved_pdf_path)
return PDFOCRResult(
markdown=None,
backend=backend.name,
cached=False,
cache_key=cache_key,
status="error",
model=backend.model_name,
warning=str(exc),
)
markdown = markdown.strip()
if not markdown:
return PDFOCRResult(
markdown=None,
backend=backend.name,
cached=False,
cache_key=cache_key,
status="error",
model=backend.model_name,
warning="OCR produced empty markdown",
)
result = PDFOCRResult(
markdown=markdown,
backend=backend.name,
cached=False,
cache_key=cache_key,
status="generated",
model=backend.model_name,
page_count=len(image_paths),
)
_write_cache_entry(cache_entry_dir, cache_key, backend.signature(), result)
logger.info(
"OCR complete: pdf=%s pages=%s cache_key=%s seconds=%.2f",
resolved_pdf_path,
len(image_paths),
cache_key,
time.monotonic() - extraction_start,
)
return result
def render_pdf_to_images(pdf_path: Path | str, *, output_dir: Path, scale: float = DEFAULT_RENDER_SCALE) -> list[Path]:
pdf_path = Path(pdf_path)
try:
import fitz
except Exception as exc:
raise RuntimeError(
"PyMuPDF is required for PDF OCR rendering. Install with `pip install nancy-brain[ocr]` "
"or `pip install nancy-brain[ocr-gpu]`."
) from exc
output_dir.mkdir(parents=True, exist_ok=True)
image_paths: list[Path] = []
logger.info("Rendering PDF pages to images: pdf=%s output_dir=%s scale=%.2f", pdf_path, output_dir, scale)
with fitz.open(str(pdf_path)) as document:
for page_index, page in enumerate(document, start=1):
pixmap = page.get_pixmap(matrix=fitz.Matrix(scale, scale), alpha=False)
image_path = output_dir / f"page-{page_index:04d}.png"
pixmap.save(str(image_path))
image_paths.append(image_path)
logger.info("Rendered PDF page images: pdf=%s pages=%s", pdf_path, len(image_paths))
return image_paths
def _select_backend(preferred_backend: Optional[str] = None) -> Optional[DeepSeekOCRBackend]:
status = get_pdf_ocr_backend_status(preferred_backend)
if not status.available:
return None
if status.name == "deepseek":
return _DEEPSEEK_BACKEND
return None
def _load_cached_result(
cache_entry_dir: Path,
cache_key: str,
preferred_backend: Optional[str] = None,
signature: Optional[dict] = None,
) -> Optional[PDFOCRResult]:
metadata_path = cache_entry_dir / "metadata.json"
markdown_path = cache_entry_dir / "content.md"
if not metadata_path.exists() or not markdown_path.exists():
return None
try:
metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
except Exception:
return None
cached_signature = metadata.get("signature") or {}
if metadata.get("pdf_sha256") != cache_key:
return None
if cached_signature.get("cache_version") != CACHE_VERSION:
return None
requested_backend = (preferred_backend or DEFAULT_BACKEND).strip().lower()
cached_backend = metadata.get("backend", "unknown")
if requested_backend not in {"", "auto", "skip", "none"} and requested_backend != cached_backend:
return None
if signature is not None and cached_signature != signature:
return None
try:
markdown = markdown_path.read_text(encoding="utf-8")
except Exception:
return None
return PDFOCRResult(
markdown=markdown,
backend=metadata.get("backend", "unknown"),
cached=True,
cache_key=cache_key,
status="cached",
model=metadata.get("model"),
page_count=int(metadata.get("page_count", 0)),
)
def _write_cache_entry(cache_entry_dir: Path, cache_key: str, signature: dict, result: PDFOCRResult) -> None:
cache_entry_dir.mkdir(parents=True, exist_ok=True)
markdown_path = cache_entry_dir / "content.md"
metadata_path = cache_entry_dir / "metadata.json"
temp_markdown_path = cache_entry_dir / "content.md.tmp"
temp_metadata_path = cache_entry_dir / "metadata.json.tmp"
temp_markdown_path.write_text(result.markdown or "", encoding="utf-8")
temp_metadata_path.write_text(
json.dumps(
{
"pdf_sha256": cache_key,
"backend": result.backend,
"status": result.status,
"model": result.model,
"page_count": result.page_count,
"signature": signature,
},
indent=2,
sort_keys=True,
),
encoding="utf-8",
)
temp_markdown_path.replace(markdown_path)
temp_metadata_path.replace(metadata_path)
logger.info(
"Wrote OCR cache entry: entry=%s cache_key=%s status=%s pages=%s",
cache_entry_dir,
cache_key,
result.status,
result.page_count,
)
def _coerce_deepseek_output(result, output_dir: Path) -> Optional[str]:
if isinstance(result, str):
return result
if isinstance(result, dict):
for key in ("markdown", "text", "result", "output", "content"):
value = result.get(key)
if isinstance(value, str) and value.strip():
return value
for key in ("data", "payload", "prediction", "pred_dict", "results"):
nested = _coerce_deepseek_output(result.get(key), output_dir)
if nested:
return nested
if isinstance(result, (list, tuple)):
parts = []
for value in result:
coerced = _coerce_deepseek_output(value, output_dir)
if coerced:
parts.append(coerced.strip())
if parts:
return "\n\n".join(parts)
for pattern in ("*.md", "*.markdown", "*.txt"):
candidates = sorted(output_dir.rglob(pattern))
if not candidates:
continue
contents = []
for candidate in candidates:
try:
text = candidate.read_text(encoding="utf-8").strip()
except Exception:
continue
if text:
contents.append(text)
if contents:
return "\n\n".join(contents)
return None
def warm_pdf_ocr_cache(
paths: list[Path | str],
*,
cache_dir: Optional[Path | str] = None,
preferred_backend: Optional[str] = None,
worker_cmd: Optional[str | list[str]] = None,
allow_worker_spawn: bool = True,
recursive: bool = True,
) -> list[PDFOCRResult]:
"""Warm OCR cache entries for the provided files or directories."""
pdf_paths: list[Path] = []
for item in paths:
path = Path(item)
if path.is_dir():
pattern = "**/*.pdf" if recursive else "*.pdf"
pdf_paths.extend(sorted(path.glob(pattern)))
elif path.is_file() and path.suffix.lower() == ".pdf":
pdf_paths.append(path)
logger.info("OCR warm scan complete: input_items=%s pdfs=%s recursive=%s", len(paths), len(pdf_paths), recursive)
backend = _select_backend(preferred_backend)
if backend is None and allow_worker_spawn and not _backend_is_cache_only(preferred_backend):
return _warm_pdf_ocr_cache_via_worker_batch(
pdf_paths,
cache_dir=cache_dir,
preferred_backend=preferred_backend,
worker_cmd=worker_cmd,
)
results: list[PDFOCRResult] = []
for pdf_path in pdf_paths:
results.append(
extract_pdf_markdown(
pdf_path,
cache_dir=cache_dir,
preferred_backend=preferred_backend,
worker_cmd=worker_cmd,
allow_worker_spawn=allow_worker_spawn,
)
)
return results
def _warm_pdf_ocr_cache_via_worker_batch(
pdf_paths: list[Path],
*,
cache_dir: Optional[Path | str] = None,
preferred_backend: Optional[str] = None,
worker_cmd: Optional[str | list[str]] = None,
) -> list[PDFOCRResult]:
cache_root = Path(cache_dir) if cache_dir is not None else default_pdf_ocr_cache_dir()
cache_root.mkdir(parents=True, exist_ok=True)
results_by_path: dict[Path, PDFOCRResult] = {}
cache_keys_by_path: dict[Path, str] = {}
worker_batch: list[Path] = []
for pdf_path in pdf_paths:
resolved_path = pdf_path.resolve(strict=False)
cache_key = compute_pdf_content_hash(resolved_path)
cache_keys_by_path[resolved_path] = cache_key
cache_entry_dir = cache_root / cache_key
cached_result = _load_cached_result(cache_entry_dir, cache_key, preferred_backend=preferred_backend)
if cached_result is not None:
results_by_path[resolved_path] = cached_result
else:
worker_batch.append(resolved_path)
logger.info(
"OCR warm batch prepared: total=%s cached=%s worker_batch=%s cache_dir=%s",
len(pdf_paths),
len(results_by_path),
len(worker_batch),
cache_root,
)
if worker_batch:
worker_results = _run_worker_batch_subprocess(
worker_batch,
cache_root=cache_root,
cache_keys_by_path=cache_keys_by_path,
preferred_backend=preferred_backend,
worker_cmd=worker_cmd,
)
results_by_path.update(worker_results)
ordered_results: list[PDFOCRResult] = []
for pdf_path in pdf_paths:
resolved_path = pdf_path.resolve(strict=False)
result = results_by_path.get(resolved_path)
if result is None:
ordered_results.append(
PDFOCRResult(
markdown=None,
backend="worker",
cached=False,
cache_key=cache_keys_by_path.get(resolved_path, ""),
status="error",
warning="OCR warm did not return a result for this PDF",
)
)
else:
ordered_results.append(result)
return ordered_results
def _backend_is_cache_only(preferred_backend: Optional[str]) -> bool:
backend_name = (preferred_backend or DEFAULT_BACKEND).strip().lower()
return backend_name in {"skip", "none"}
def _resolve_worker_command(
worker_cmd: Optional[str | list[str]] = None,
*,
project_path: Optional[Path | str] = None,
) -> Optional[list[str]]:
command, _warning = _resolve_worker_command_with_warning(worker_cmd, project_path=project_path)
return command
def _resolve_worker_command_with_warning(
worker_cmd: Optional[str | list[str]] = None,
*,
project_path: Optional[Path | str] = None,
) -> tuple[Optional[list[str]], Optional[str]]:
if os.environ.get("NB_IN_OCR_WORKER", "").strip():
return None, None
if worker_cmd is not None:
try:
parts = _normalize_worker_command_prefix(_coerce_worker_command(worker_cmd))
except Exception as exc:
return None, f"failed to parse explicit OCR worker command: {exc}"
if not parts:
return None, "explicit OCR worker command is empty after normalization"
return parts, None
env_cmd = os.environ.get("NB_OCR_WORKER_CMD", "").strip()
if env_cmd:
try:
parts = _normalize_worker_command_prefix(_coerce_worker_command(env_cmd))
except Exception as exc:
return None, f"failed to parse NB_OCR_WORKER_CMD: {exc}"
if not parts:
return None, "NB_OCR_WORKER_CMD is empty after normalization"
return parts, None
config_command, config_warning = _load_worker_command_from_project_config(project_path)
if config_command is not None:
return config_command, config_warning
if config_warning:
return None, config_warning
shared_command = _default_shared_worker_command()
if shared_command is not None:
return shared_command, None
return None, None
def _coerce_worker_command(worker_cmd: str | list[str]) -> list[str]:
if isinstance(worker_cmd, str):
return shlex.split(worker_cmd)
return [str(part).strip() for part in worker_cmd if str(part).strip()]
def _project_worker_config_paths(project_path: Optional[Path | str] = None) -> list[Path]:
search_roots = _project_config_search_roots(project_path)
config_paths: list[Path] = []
for root in search_roots:
for filename in PROJECT_OCR_WORKER_CONFIG_FILENAMES:
config_paths.append(root / "config" / filename)
return config_paths
def _load_worker_command_from_project_config(
project_path: Optional[Path | str] = None,
) -> tuple[Optional[list[str]], Optional[str]]:
for config_path in _project_worker_config_paths(project_path):
if not config_path.exists():
continue
try:
raw_config = tomllib.loads(config_path.read_text(encoding="utf-8"))
except Exception as exc:
return None, f"failed to read OCR worker config {config_path}: {exc}"
raw_command = raw_config.get("worker_cmd") or raw_config.get("command")
if raw_command is None and isinstance(raw_config.get("worker"), dict):
worker_section = raw_config["worker"]
raw_command = worker_section.get("worker_cmd") or worker_section.get("command") or worker_section.get("cmd")
if raw_command is None:
return None, f"OCR worker config {config_path} does not define worker_cmd"
try:
return _normalize_worker_command_prefix(_coerce_worker_command(raw_command)), None
except Exception as exc:
return None, f"failed to parse OCR worker command in {config_path}: {exc}"
return None, None
def _project_config_search_roots(project_path: Optional[Path | str] = None) -> list[Path]:
start = Path(project_path).resolve() if project_path is not None else Path.cwd().resolve()
if start.is_file():
start = start.parent
roots: list[Path] = []
current = start
while True:
roots.append(current)
if (current / "pyproject.toml").exists() or (current / ".git").exists():
break
if current.parent == current:
break
current = current.parent
return roots
def _default_shared_worker_command() -> Optional[list[str]]:
candidates: list[Path]
if os.name == "nt":
base = _windows_shared_worker_base()
candidates = [
base / "Scripts" / "nancy-brain.exe",
base / "Scripts" / "nancy-brain.cmd",
base / "Scripts" / "nancy-brain",
]
else:
base = Path.home() / ".local" / "share" / "nancy-brain" / "ocr-worker"
candidates = [base / "bin" / "nancy-brain", base / "bin" / "nancy-brain.exe"]
for candidate in candidates:
if candidate.exists() and (os.name == "nt" or os.access(candidate, os.X_OK)):
return [str(candidate)]
return None
def _windows_shared_worker_base() -> Path:
local_appdata = os.environ.get("LOCALAPPDATA", "").strip()
if local_appdata:
return Path(local_appdata) / "nancy-brain" / "ocr-worker"
return Path.home() / "AppData" / "Local" / "nancy-brain" / "ocr-worker"
def _normalize_worker_command_prefix(parts: list[str]) -> list[str]:
normalized = [part for part in parts if str(part).strip()]
while normalized and normalized[-1] in {"worker", "ocr"}:
normalized.pop()
return normalized
def _parse_worker_payload(stdout: str) -> Optional[dict]:
text = stdout.strip()
if not text:
return None
try:
return json.loads(text)
except Exception:
return None
def _parse_worker_payload_stream(stdout: str) -> list[dict]:
payloads: list[dict] = []
ignored_lines = 0
for line in stdout.splitlines():
text = line.strip()
if not text:
continue
try:
payload = json.loads(text)
except Exception:
ignored_lines += 1
continue
if isinstance(payload, dict):
payloads.append(payload)
else:
ignored_lines += 1
if ignored_lines:
logger.warning(
"Ignored non-NDJSON OCR worker stdout: lines=%s valid_payloads=%s",
ignored_lines,
len(payloads),
)
return payloads
def _result_from_worker_payload(
payload: Optional[dict],
*,
pdf_path: Path,
cache_root: Path,
cache_key: str,
preferred_backend: Optional[str],
fallback_warning: Optional[str] = None,
) -> PDFOCRResult:
if not payload:
return PDFOCRResult(
markdown=None,
backend="worker",
cached=False,
cache_key=cache_key,
status="error",
warning=fallback_warning or "OCR worker did not return a JSON payload",
)
status = str(payload.get("status", "error"))
warning = payload.get("warning")
backend_name = str(payload.get("backend") or "worker")
model = payload.get("model")
page_count = int(payload.get("page_count") or 0)
cache_entry_dir = cache_root / cache_key
if status == "needs_ocr":
return PDFOCRResult(
markdown=None,
backend=backend_name,
cached=False,
cache_key=cache_key,
status="needs_ocr",
needs_ocr=True,
deferred=True,
model=model,
page_count=page_count,
warning=warning or fallback_warning,
)
if status == "error":
return PDFOCRResult(
markdown=None,
backend=backend_name,
cached=False,
cache_key=cache_key,
status="error",
model=model,
page_count=page_count,
warning=warning or fallback_warning or "OCR worker reported an error",
)
cached_result = _load_cached_result(cache_entry_dir, cache_key, preferred_backend=preferred_backend)
if cached_result is None:
return PDFOCRResult(
markdown=None,
backend=backend_name,
cached=False,
cache_key=cache_key,
status="error",
model=model,
page_count=page_count,
warning=fallback_warning or "OCR worker completed successfully but cache entry was not written",
)
if status == "cached":
return cached_result
return PDFOCRResult(
markdown=cached_result.markdown,
backend=backend_name,
cached=False,
cache_key=cache_key,
status="generated",
model=model or cached_result.model,
page_count=page_count or cached_result.page_count,
warning=warning,
)
def _run_worker_subprocess(
pdf_path: Path,
*,
cache_root: Path,
cache_key: str,
preferred_backend: Optional[str],
worker_cmd: Optional[str | list[str]] = None,
) -> Optional[PDFOCRResult]:
try:
command, resolution_warning = _resolve_worker_command_with_warning(worker_cmd, project_path=pdf_path)
except ValueError as exc:
return PDFOCRResult(
markdown=None,
backend="worker",
cached=False,
cache_key=cache_key,
status="error",
warning=str(exc),
)
if not command:
if resolution_warning:
return PDFOCRResult(
markdown=None,
backend="worker",
cached=False,
cache_key=cache_key,
status="error",
warning=resolution_warning,
)
return None
pdf_path_abs = pdf_path.resolve(strict=False)
cache_root_abs = cache_root.resolve(strict=False)
invocation = [*command, "ocr", "worker", str(pdf_path_abs), "--cache-dir", str(cache_root_abs)]
backend_name = (preferred_backend or DEFAULT_BACKEND).strip().lower()
if backend_name not in {"", "auto", "skip", "none"}:
invocation.extend(["--backend", backend_name])
env = os.environ.copy()
env["NB_IN_OCR_WORKER"] = "1"
env["NB_OCR_WORKER_CMD"] = ""
logger.info("Launching OCR worker: pdf=%s command=%s", pdf_path_abs, shlex.join(invocation))
worker_start = time.monotonic()
try:
completed = subprocess.run(
invocation,
check=False,
stdout=subprocess.PIPE,
text=True,
env=env,
cwd=str(cache_root_abs),
)
except Exception as exc:
return PDFOCRResult(
markdown=None,
backend="worker",
cached=False,
cache_key=cache_key,
status="error",
warning=f"failed to launch OCR worker: {exc}",
)
logger.info(
"OCR worker finished: pdf=%s returncode=%s seconds=%.2f",
pdf_path_abs,
completed.returncode,
time.monotonic() - worker_start,
)
payload = _parse_worker_payload(completed.stdout)
warning = None
if completed.returncode != 0 and payload is not None:
warning = payload.get("warning")
if completed.returncode != 0 and not warning:
warning = (
(completed.stderr or "").strip()
or (completed.stdout or "").strip()
or f"OCR worker exited with code {completed.returncode}"
)
return _result_from_worker_payload(
payload,
pdf_path=pdf_path_abs,
cache_root=cache_root,
cache_key=cache_key,
preferred_backend=preferred_backend,
fallback_warning=warning,
)
def _run_worker_batch_subprocess(
pdf_paths: list[Path],
*,
cache_root: Path,
cache_keys_by_path: dict[Path, str],
preferred_backend: Optional[str],
worker_cmd: Optional[str | list[str]] = None,
) -> dict[Path, PDFOCRResult]:
if not pdf_paths:
return {}
try:
command, resolution_warning = _resolve_worker_command_with_warning(worker_cmd, project_path=pdf_paths[0])
except ValueError as exc:
return {
pdf_path: PDFOCRResult(
markdown=None,
backend="worker",
cached=False,
cache_key=cache_keys_by_path[pdf_path],
status="error",
warning=str(exc),
)
for pdf_path in pdf_paths
}
if not command:
if resolution_warning:
return {
pdf_path: PDFOCRResult(
markdown=None,
backend="worker",
cached=False,
cache_key=cache_keys_by_path[pdf_path],
status="error",
warning=resolution_warning,
)
for pdf_path in pdf_paths
}
return {}
cache_root_abs = cache_root.resolve(strict=False)
pdf_path_args = [str(pdf_path.resolve(strict=False)) for pdf_path in pdf_paths]
invocation = [*command, "ocr", "worker", *pdf_path_args, "--cache-dir", str(cache_root_abs)]
backend_name = (preferred_backend or DEFAULT_BACKEND).strip().lower()
if backend_name not in {"", "auto", "skip", "none"}:
invocation.extend(["--backend", backend_name])
env = os.environ.copy()
env["NB_IN_OCR_WORKER"] = "1"
env["NB_OCR_WORKER_CMD"] = ""
logger.info("Launching OCR worker batch: pdfs=%s command=%s", len(pdf_paths), shlex.join(invocation))
worker_start = time.monotonic()
try:
completed = subprocess.run(
invocation,
check=False,
stdout=subprocess.PIPE,
text=True,
env=env,
cwd=str(cache_root_abs),
)
except Exception as exc:
return {
pdf_path: PDFOCRResult(
markdown=None,
backend="worker",
cached=False,
cache_key=cache_keys_by_path[pdf_path],
status="error",
warning=f"failed to launch OCR worker: {exc}",
)
for pdf_path in pdf_paths
}
logger.info(
"OCR worker batch finished: pdfs=%s returncode=%s seconds=%.2f",
len(pdf_paths),
completed.returncode,
time.monotonic() - worker_start,
)
payloads = _parse_worker_payload_stream(completed.stdout)
payloads_by_path: dict[Path, dict] = {}
for payload in payloads:
payload_path = payload.get("pdf_path")
if not payload_path:
continue
payloads_by_path[Path(payload_path).resolve(strict=False)] = payload
fallback_warning = None
if completed.returncode != 0:
fallback_warning = (
(completed.stderr or "").strip()
or (completed.stdout or "").strip()
or f"OCR worker exited with code {completed.returncode}"
)
results: dict[Path, PDFOCRResult] = {}
for pdf_path in pdf_paths:
resolved_path = pdf_path.resolve(strict=False)
results[resolved_path] = _result_from_worker_payload(
payloads_by_path.get(resolved_path),
pdf_path=resolved_path,
cache_root=cache_root,
cache_key=cache_keys_by_path[resolved_path],
preferred_backend=preferred_backend,
fallback_warning=fallback_warning,
)
return results
__all__ = [
"PDFOCRBackendStatus",
"PDFOCRResult",
"build_pdf_ocr_worker_record",
"compute_pdf_content_hash",
"default_pdf_ocr_cache_dir",
"extract_pdf_markdown",
"get_pdf_ocr_backend_status",
"render_pdf_to_images",
"warm_pdf_ocr_cache",
]
"""PDF OCR helpers with cache-aware markdown extraction."""
from __future__ import annotations
import hashlib
import json
import logging
import os
import shlex
import subprocess
import tempfile
import time
import tomllib
from dataclasses import dataclass
from importlib.util import find_spec
from pathlib import Path
from typing import Optional
logger = logging.getLogger(__name__)
DEFAULT_DEEPSEEK_MODEL = os.environ.get("NB_PDF_OCR_DEEPSEEK_MODEL", "deepseek-ai/DeepSeek-OCR")
DEFAULT_DEEPSEEK_PROMPT = os.environ.get(
"NB_PDF_OCR_DEEPSEEK_PROMPT",
"<image>\n<|grounding|>Convert the document to markdown.",
)
DEFAULT_RENDER_SCALE = float(os.environ.get("NB_PDF_OCR_RENDER_SCALE", "2.0"))
DEFAULT_BASE_SIZE = int(os.environ.get("NB_PDF_OCR_DEEPSEEK_BASE_SIZE", "1024"))
DEFAULT_IMAGE_SIZE = int(os.environ.get("NB_PDF_OCR_DEEPSEEK_IMAGE_SIZE", "640"))
DEFAULT_CROP_MODE = os.environ.get("NB_PDF_OCR_DEEPSEEK_CROP_MODE", "true").strip().lower() == "true"
DEFAULT_BACKEND = os.environ.get("NB_PDF_OCR_BACKEND", "auto").strip().lower() or "auto"
CACHE_VERSION = 1
DEEPSEEK_RUNTIME_MODULES = {
"addict": "addict",
"easydict": "easydict",
"einops": "einops",
"matplotlib": "matplotlib",
"torchvision": "torchvision",
}
PROJECT_OCR_WORKER_CONFIG_FILENAMES = ("ocr_worker.toml", "ocr-worker.toml")
def _normalize_quantization_mode(value: Optional[str]) -> Optional[str]:
raw = (value or "").strip().lower()
if raw in {"", "none", "off", "false", "fp16", "full", "16bit"}:
return None
if raw in {"4", "4bit", "int4", "nf4"}:
return "4bit"
if raw in {"8", "8bit", "int8"}:
return "8bit"
if raw == "auto":
return "auto"
return raw
def _quantization_threshold_gib(env_name: str, default: float) -> float:
raw = os.environ.get(env_name, "").strip()
if not raw:
return default
try:
return float(raw)
except Exception:
return default
def _configured_deepseek_quantization_mode() -> Optional[str]:
explicit = os.environ.get("NB_PDF_OCR_QUANTIZE", "")
if explicit.strip():
return _normalize_quantization_mode(explicit)
shared = os.environ.get("NB_QUANTIZE", "")
if shared.strip():
return _normalize_quantization_mode(shared)
return "auto"
def _resolve_deepseek_quantization_mode(torch_module) -> Optional[str]:
configured = _configured_deepseek_quantization_mode()
if configured != "auto":
return configured
cuda = getattr(torch_module, "cuda", None)
if cuda is None or not getattr(cuda, "is_available", lambda: False)():
return None
try:
current_device = getattr(cuda, "current_device", lambda: 0)()
props = cuda.get_device_properties(current_device)
total_memory_gib = props.total_memory / float(1024**3)
except Exception:
return None
four_bit_max = _quantization_threshold_gib("NB_PDF_OCR_AUTO_4BIT_MAX_GIB", 16.0)
eight_bit_max = _quantization_threshold_gib("NB_PDF_OCR_AUTO_8BIT_MAX_GIB", 24.0)
if total_memory_gib <= four_bit_max:
return "4bit"
if total_memory_gib <= eight_bit_max:
return "8bit"
return None
def _deepseek_attention_kwargs_candidates(quantization_mode: Optional[str]) -> list[dict]:
Xet Storage Details
- Size:
- 50.9 kB
- Xet hash:
- 438a6dd4577a0e338eace160e742abe127c5dce13b729859855d757e8fe32ca5
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.