veriscript 1.5.0__py3-none-any.whl

deva_crnn/__init__.py

@@ -0,0 +1 @@
+"""deva_crnn — small Devanagari line recognizer (CRNN+CTC) for the W1 fine-tune."""

deva_crnn/augment.py

@@ -0,0 +1,242 @@
+"""
+augment.py — print-degradation augmentation for line crops (local use).
+
+Kept out of `data.py` so the training path never imports OpenCV: the Vertex
+PyTorch container has torch/PIL/numpy but not cv2.
+
+`level="light"` is the attempt-1 augmentation (blur/noise/JPEG/brightness).
+`level="heavy"` adds the artifacts that actually separate a rendered line from
+a scanned one: ink spread/erosion, resolution loss (downscale-upscale), uneven
+illumination, stronger blur/noise/JPEG and a slight rotation.
+`level="xheavy"` is the stress set for few-shot real crops (N5 digit lines):
+affine + perspective + elastic geometry, local shadow fields, gamma and faded
+print, motion blur, salt-and-pepper and speckle noise, tighter crop jitter.
+Existing levels are frozen; new work extends by adding a level.
+"""
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+def augment_line(img_bgr: np.ndarray, rng: np.random.Generator,
+                 level: str = "light") -> np.ndarray:
+    """Deterministic print-degradation augmentation (given `rng`)."""
+    if level == "xheavy":
+        return _xheavy(img_bgr, rng)
+    if level == "heavy":
+        return _heavy(img_bgr, rng)
+    return _light(img_bgr, rng)
+
+
+def _light(img_bgr: np.ndarray, rng: np.random.Generator) -> np.ndarray:
+    """Cheap print-degradation augmentation (blur/noise/JPEG/brightness)."""
+    out = img_bgr.astype(np.float32)
+    if rng.random() < 0.5:
+        sigma = float(rng.uniform(0.4, 1.3))
+        out = cv2.GaussianBlur(out, (0, 0), sigmaX=sigma)
+    if rng.random() < 0.4:
+        out = out + rng.normal(0.0, float(rng.uniform(3, 12)), out.shape)
+    out = np.clip(out * float(rng.uniform(0.85, 1.15)) +
+                  float(rng.uniform(-12, 12)), 0, 255).astype(np.uint8)
+    if rng.random() < 0.5:
+        q = int(rng.integers(40, 85))
+        ok, enc = cv2.imencode(".jpg", out, [cv2.IMWRITE_JPEG_QUALITY, q])
+        if ok:
+            out = cv2.imdecode(enc, cv2.IMREAD_COLOR)
+    return out
+
+
+def _heavy(img_bgr: np.ndarray, rng: np.random.Generator) -> np.ndarray:
+    out = img_bgr.astype(np.float32)
+    h, w = out.shape[:2]
+
+    # Ink spread (heavy inking / letterpress bleed) or erosion (thin print).
+    if rng.random() < 0.55:
+        k = np.ones((2, 2), np.uint8)
+        if rng.random() < 0.5:
+            out = cv2.dilate(out, k, iterations=1).astype(np.float32)
+        else:
+            out = cv2.erode(out, k, iterations=1).astype(np.float32)
+
+    # Resolution loss: a 300-dpi scan of small print is not crisp.
+    if rng.random() < 0.5:
+        f = float(rng.uniform(0.45, 0.8))
+        small = cv2.resize(out, (max(4, int(w * f)), max(4, int(h * f))),
+                           interpolation=cv2.INTER_AREA)
+        out = cv2.resize(small, (w, h), interpolation=cv2.INTER_LINEAR)
+
+    # Anisotropic squeeze/stretch: detector boxes are tight around cells and
+    # long lines alike, so the recognizer must not assume a fixed aspect.
+    if rng.random() < 0.4:
+        fx = float(rng.uniform(0.65, 1.45))
+        out = cv2.resize(out, (max(4, int(w * fx)), h),
+                         interpolation=cv2.INTER_LINEAR)
+        h, w = out.shape[:2]
+
+    # Uneven illumination (page curvature / phone shadow).
+    if rng.random() < 0.4:
+        ramp = np.linspace(float(rng.uniform(0.72, 0.88)),
+                           float(rng.uniform(1.0, 1.12)), w,
+                           dtype=np.float32)
+        out = out * ramp[None, :, None]
+
+    if rng.random() < 0.8:
+        sigma = float(rng.uniform(0.5, 2.2))
+        out = cv2.GaussianBlur(out, (0, 0), sigmaX=sigma)
+    if rng.random() < 0.7:
+        out = out + rng.normal(0.0, float(rng.uniform(4, 20)), out.shape)
+    out = np.clip(out * float(rng.uniform(0.7, 1.2)) +
+                  float(rng.uniform(-20, 20)), 0, 255)
+
+    if rng.random() < 0.7:
+        q = int(rng.integers(28, 72))
+        ok, enc = cv2.imencode(".jpg", out.astype(np.uint8),
+                               [cv2.IMWRITE_JPEG_QUALITY, q])
+        if ok:
+            out = cv2.imdecode(enc, cv2.IMREAD_COLOR).astype(np.float32)
+
+    if rng.random() < 0.5:
+        ang = float(rng.uniform(-1.5, 1.5))
+        m = cv2.getRotationMatrix2D((w / 2.0, h / 2.0), ang, 1.0)
+        out = cv2.warpAffine(out, m, (w, h), flags=cv2.INTER_LINEAR,
+                             borderMode=cv2.BORDER_REPLICATE)
+    return np.clip(out, 0, 255).astype(np.uint8)
+
+
+def _motion_blur(img: np.ndarray, rng: np.random.Generator) -> np.ndarray:
+    """Random-angle linear motion blur (hand-held phone captures)."""
+    k = int(rng.integers(3, 8)) | 1
+    kernel = np.zeros((k, k), np.float32)
+    kernel[k // 2, :] = 1.0
+    angle = float(rng.uniform(0, 180))
+    m = cv2.getRotationMatrix2D((k / 2.0 - 0.5, k / 2.0 - 0.5), angle, 1.0)
+    kernel = cv2.warpAffine(kernel, m, (k, k))
+    total = float(kernel.sum())
+    if total <= 0:
+        return img
+    return cv2.filter2D(img, -1, kernel / total)
+
+
+def _elastic(img: np.ndarray, rng: np.random.Generator, alpha: float,
+             sigma: float) -> np.ndarray:
+    """Mild smooth displacement field (paper curl, lens distortion)."""
+    h, w = img.shape[:2]
+    dx = cv2.GaussianBlur(
+        rng.uniform(-1, 1, (h, w)).astype(np.float32), (0, 0),
+        sigmaX=sigma, sigmaY=sigma) * alpha
+    dy = cv2.GaussianBlur(
+        rng.uniform(-1, 1, (h, w)).astype(np.float32), (0, 0),
+        sigmaX=sigma, sigmaY=sigma) * alpha
+    xs = np.tile(np.arange(w, dtype=np.float32), (h, 1)) + dx
+    ys = np.tile(np.arange(h, dtype=np.float32)[:, None], (1, w)) + dy
+    return cv2.remap(img, xs, ys, cv2.INTER_LINEAR,
+                     borderMode=cv2.BORDER_REPLICATE)
+
+
+def _shadow_field(img: np.ndarray, rng: np.random.Generator) -> np.ndarray:
+    """Smooth local darkening (a hand/phone shadow across the page)."""
+    h, w = img.shape[:2]
+    low = rng.uniform(0.55, 1.0, (4, 6)).astype(np.float32)
+    field = cv2.resize(low, (w, h), interpolation=cv2.INTER_CUBIC)
+    field = cv2.GaussianBlur(field, (0, 0), sigmaX=max(2.0, w / 40.0))
+    return img * field[:, :, None]
+
+
+def _xheavy(img_bgr: np.ndarray, rng: np.random.Generator) -> np.ndarray:
+    """Stress augmentation for few-shot real crops (N5 digit lines).
+
+    Chain: geometry (affine/perspective/elastic) -> ink -> resolution ->
+    illumination (shadow fields, gamma, fade) -> optics (motion/gaussian
+    blur) -> sensor (gaussian/salt-pepper/speckle) -> JPEG last. Every step
+    is applied with its own probability and bounded so the label is
+    preserved: no flips, rotation <= 2.5 deg, displacement <= ~3 px.
+    """
+    out = img_bgr.astype(np.float32)
+    h, w = out.shape[:2]
+
+    # --- geometry ---
+    if rng.random() < 0.7:
+        ang = float(rng.uniform(-2.5, 2.5))
+        scale = float(rng.uniform(0.92, 1.08))
+        shear = float(rng.uniform(-0.035, 0.035))
+        m = cv2.getRotationMatrix2D((w / 2.0, h / 2.0), ang, scale)
+        m[0, 1] += shear
+        m[0, 2] += float(rng.uniform(-0.02, 0.02)) * w
+        m[1, 2] += float(rng.uniform(-0.02, 0.02)) * h
+        out = cv2.warpAffine(out, m, (w, h), flags=cv2.INTER_LINEAR,
+                             borderMode=cv2.BORDER_REPLICATE)
+    if rng.random() < 0.3:
+        j = 0.015
+        src = np.float32([[0, 0], [w, 0], [w, h], [0, h]])
+        dst = src + (rng.uniform(-j, j, src.shape).astype(np.float32)
+                     * np.float32([w, h]))
+        m = cv2.getPerspectiveTransform(src, dst)
+        out = cv2.warpPerspective(out, m, (w, h), flags=cv2.INTER_LINEAR,
+                                  borderMode=cv2.BORDER_REPLICATE)
+    if rng.random() < 0.3 and h >= 24 and w >= 40:
+        out = _elastic(out, rng, alpha=float(rng.uniform(1.5, 3.0)),
+                       sigma=float(rng.uniform(6.0, 9.0)))
+
+    # --- ink ---
+    if rng.random() < 0.6:
+        k = (np.ones((3, 3), np.uint8) if rng.random() < 0.4
+             else np.ones((2, 2), np.uint8))
+        if rng.random() < 0.5:
+            out = cv2.dilate(out, k, iterations=1).astype(np.float32)
+        else:
+            out = cv2.erode(out, k, iterations=1).astype(np.float32)
+
+    # --- resolution ---
+    if rng.random() < 0.55:
+        f = float(rng.uniform(0.4, 0.75))
+        small = cv2.resize(out, (max(4, int(w * f)), max(4, int(h * f))),
+                           interpolation=cv2.INTER_AREA)
+        out = cv2.resize(small, (w, h), interpolation=cv2.INTER_LINEAR)
+    if rng.random() < 0.45:
+        fx = float(rng.uniform(0.6, 1.5))
+        out = cv2.resize(out, (max(4, int(w * fx)), h),
+                         interpolation=cv2.INTER_LINEAR)
+        h, w = out.shape[:2]
+
+    # --- illumination ---
+    if rng.random() < 0.5:
+        out = _shadow_field(out, rng)
+    if rng.random() < 0.4:
+        ramp = np.linspace(float(rng.uniform(0.7, 0.9)),
+                           float(rng.uniform(1.0, 1.12)), w,
+                           dtype=np.float32)
+        out = out * ramp[None, :, None]
+    if rng.random() < 0.4:
+        gamma = float(rng.uniform(0.6, 1.6))
+        out = 255.0 * np.power(np.clip(out, 0, 255) / 255.0, gamma)
+    if rng.random() < 0.25:
+        out = out * 0.55 + 245.0 * 0.45  # faded print toward paper tone
+    out = np.clip(out * float(rng.uniform(0.7, 1.2)) +
+                  float(rng.uniform(-20, 20)), 0, 255)
+
+    # --- optics / sensor ---
+    if rng.random() < 0.3:
+        out = _motion_blur(out, rng)
+    if rng.random() < 0.8:
+        out = cv2.GaussianBlur(out, (0, 0),
+                               sigmaX=float(rng.uniform(0.4, 2.6)))
+    if rng.random() < 0.75:
+        out = out + rng.normal(0.0, float(rng.uniform(3, 22)), out.shape)
+    if rng.random() < 0.25:
+        p = float(rng.uniform(0.002, 0.012))
+        mask = rng.random((out.shape[0], out.shape[1]))
+        dark = (mask < p * 0.5)[:, :, None]
+        bright = ((mask >= p * 0.5) & (mask < p))[:, :, None]
+        out = np.where(dark, 0.0, np.where(bright, 255.0, out))
+    if rng.random() < 0.2:
+        out = out * (1.0 + rng.normal(0.0, 0.06, out.shape))
+    out = np.clip(out, 0, 255).astype(np.uint8)
+
+    # --- compression last ---
+    if rng.random() < 0.75:
+        q = int(rng.integers(20, 66))
+        ok, enc = cv2.imencode(".jpg", out, [cv2.IMWRITE_JPEG_QUALITY, q])
+        if ok:
+            out = cv2.imdecode(enc, cv2.IMREAD_COLOR)
+    return out

deva_crnn/charset.py

@@ -0,0 +1,31 @@
+"""
+charset.py — CTC charset for Devanagari line recognition.
+
+Characters come from the training labels; the blank is index 0 (CTC). Encoding
+is per-codepoint (no shaping - the image carries the shaping).
+"""
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Tuple
+
+BLANK = 0
+
+
+def build_charset(texts: Iterable[str]) -> List[str]:
+    chars = sorted({c for t in texts for c in t})
+    return ["\u0000"] + chars
+
+
+def encode(text: str, charset: List[str]) -> List[int]:
+    idx = {c: i for i, c in enumerate(charset)}
+    return [idx[c] for c in text if c in idx]
+
+
+def decode(ids: Iterable[int], charset: List[str]) -> str:
+    out: List[str] = []
+    prev = None
+    for i in ids:
+        if i != prev and i != BLANK:
+            out.append(charset[i])
+        prev = i
+    return "".join(out)

deva_crnn/data.py

@@ -0,0 +1,48 @@
+"""
+data.py — line-image dataset for the CRNN: npz export + torch Dataset.
+
+The npz format (`images` uint8 NxHxW, `texts` unicode array) is compact enough
+to ship inside the Vertex AI python package and fast to load.
+"""
+from __future__ import annotations
+
+import os
+from typing import Dict, List, Tuple
+
+import numpy as np
+from PIL import Image
+
+IN_H = 32
+IN_W = 256
+
+
+def normalize_line(img_bgr: np.ndarray, h: int = IN_H, w: int = IN_W) -> np.ndarray:
+    """Grayscale, height-normalized, right-padded line image (uint8).
+
+    PIL-only on purpose: the Vertex training container has no OpenCV.
+    """
+    if img_bgr.ndim == 3:
+        gray = np.asarray(Image.fromarray(img_bgr[:, :, ::-1]).convert("L"))
+    else:
+        gray = img_bgr
+    scale = h / gray.shape[0]
+    new_w = min(w, max(4, int(round(gray.shape[1] * scale))))
+    resized = np.asarray(Image.fromarray(gray).resize((new_w, h),
+                                                      Image.BILINEAR))
+    out = np.full((h, w), 255, dtype=np.uint8)
+    out[:, :new_w] = resized
+    return out
+
+
+def export_npz(images: List[np.ndarray], texts: List[str], path: str,
+               h: int = IN_H, w: int = IN_W) -> str:
+    os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+    arr = np.stack([normalize_line(im, h=h, w=w) for im in images])
+    np.savez_compressed(path, images=arr,
+                        texts=np.array(texts, dtype=object).astype(str))
+    return path
+
+
+def load_npz(path: str) -> Tuple[np.ndarray, List[str]]:
+    d = np.load(path, allow_pickle=False)
+    return d["images"], [str(t) for t in d["texts"]]

deva_crnn/gate.py

@@ -0,0 +1,97 @@
+"""
+gate.py — W1 adopt-if gate: line-level digit-exact + bagCER on frozen sets.
+
+Gate (pre-registered): digit-exact >= 0.75 on digit-bearing lines, bagCER not
+worse than the RapidOCR line baseline, <= +1 s/page. Sets:
+  * heiDATA frozen pages -> ALTO line crops (human GT)
+  * nepali_pdf_v2 anchor pages -> RapidOCR line boxes, Gemini anchor GT
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+from .data import normalize_line  # noqa: E402
+from veriscript.core.metrics import cer, cer_bag, digit_string, digit_tokens  # noqa: E402
+
+DIGIT_EXACT_BAR = 0.75
+
+
+def line_stats(gts: List[str], hyps: List[str]) -> Dict:
+    """Digit-exact rate over digit-bearing lines + mean CER/bagCER."""
+    pairs = [(g, h) for g, h in zip(gts, hyps) if g.strip()]
+    digit_pairs = [(g, h) for g, h in pairs if digit_tokens(g)]
+    exact = [1.0 if digit_string(g) == digit_string(h) else 0.0
+             for g, h in digit_pairs]
+    return {
+        "lines": len(pairs),
+        "digit_lines": len(digit_pairs),
+        "digit_exact": float(np.mean(exact)) if exact else None,
+        "cer": float(np.mean([cer(g, h) for g, h in pairs])) if pairs else None,
+        "bagcer": (float(np.mean([cer_bag(g, h) for g, h in pairs]))
+                   if pairs else None),
+    }
+
+
+def line_values(gts: List[str], hyps: List[str]) -> Dict[str, List[float]]:
+    """Per-line values for bootstrap CIs (digit-exact 0/1 + CER)."""
+    pairs = [(g, h) for g, h in zip(gts, hyps) if g.strip()]
+    digit_pairs = [(g, h) for g, h in pairs if digit_tokens(g)]
+    return {
+        "digit_exact": [1.0 if digit_string(g) == digit_string(h) else 0.0
+                        for g, h in digit_pairs],
+        "cer": [cer(g, h) for g, h in pairs],
+        "bagcer": [cer_bag(g, h) for g, h in pairs],
+    }
+
+
+def heidata_line_crops(data_dir: str, limit: int = 0) -> Tuple[List[str], List[np.ndarray]]:
+    """(texts, crops) from frozen heiDATA pages + ALTO line boxes."""
+    from veriscript.core import data as doc_data
+    manifest = doc_data.load_dataset(data_dir)
+    texts: List[str] = []
+    crops: List[np.ndarray] = []
+    for e in manifest["entries"]:
+        img = doc_data.imread_safe(e["_degraded_path"])
+        if img is None:
+            continue
+        boxes = json.load(open(e["_boxes_path"], encoding="utf-8"))
+        for b in boxes:
+            x0, y0, x1, y1 = b["bbox"]
+            pad = 4
+            crop = img[max(0, y0 - pad):y1 + pad, max(0, x0 - pad):x1 + pad]
+            if crop.size == 0:
+                continue
+            texts.append(b["text"])
+            crops.append(crop)
+        if limit and len(crops) >= limit:
+            break
+    return texts, crops
+
+
+def v2_anchor_pages(data_dir: str, readings_path: str,
+                    limit: int = 0) -> List[Dict]:
+    """Per anchor page: RapidOCR line boxes (image + crops) + Gemini GT."""
+    from veriscript.core import data as doc_data
+    from veriscript.document.ocr import ocr_page
+    manifest = doc_data.load_dataset(data_dir)
+    readings = {r["page"]: r["readings"]["gemini"]
+                for r in json.load(open(readings_path, encoding="utf-8"))["rows"]}
+    pages: List[Dict] = []
+    for e in manifest["entries"]:
+        img = doc_data.imread_safe(e["_degraded_path"])
+        if img is None or e["id"] not in readings:
+            continue
+        rec = ocr_page(img, backend="rapidocr", lang="ne")
+        crops = []
+        for t in rec.tokens:
+            x0, y0, x1, y1 = t.bbox
+            crops.append(img[max(0, y0 - 3):y1 + 3, max(0, x0 - 3):x1 + 3])
+        pages.append({"page": e["id"], "gt": readings[e["id"]],
+                      "boxes": [t.bbox for t in rec.tokens], "crops": crops})
+        if limit and len(pages) >= limit:
+            break
+    return pages

deva_crnn/model.py

@@ -0,0 +1,44 @@
+"""
+model.py — CRNN (CNN + BiLSTM + CTC) for Devanagari line crops.
+
+Input: grayscale 32 x W (padded to 256), output: log-probabilities over the
+charset per timestep. Small on purpose: trains on a single T4 in minutes and
+runs on CPU for inference.
+"""
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+class CRNN(nn.Module):
+    def __init__(self, n_classes: int, hidden: int = 256, in_h: int = 32):
+        super().__init__()
+        # GroupNorm, not BatchNorm: small-batch CTC training diverged to NaN
+        # with BN (measured), GroupNorm is stable at batch 8 and 64 alike.
+        def block(cin, cout):
+            return [nn.Conv2d(cin, cout, 3, padding=1),
+                    nn.GroupNorm(8, cout), nn.ReLU()]
+
+        # The stack must collapse the input height to exactly 1: 32 and 48 need
+        # a final (2,1) pool, 64 needs (4,1) (64 -> 32 -> 16 -> 8 -> 4 -> 1).
+        last_pool = (4, 1) if in_h >= 64 else (2, 1)
+        self.cnn = nn.Sequential(
+            *block(1, 32), nn.MaxPool2d(2),        # 16 x W/2
+            *block(32, 64), nn.MaxPool2d(2),       # 8 x W/4
+            *block(64, 128), nn.MaxPool2d((2, 1)),  # 4 x W/4
+            *block(128, 128), nn.MaxPool2d((2, 1)),  # 2 x W/4
+            *block(128, 256), nn.MaxPool2d(last_pool),  # 1 x W/4
+        )
+        self.rnn = nn.LSTM(256, hidden, num_layers=2, bidirectional=True,
+                           batch_first=True)
+        self.head = nn.Linear(2 * hidden, n_classes)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """x: (B, 1, H, W) -> log-probs (T, B, C) for CTCLoss."""
+        f = self.cnn(x)                            # B, 256, 1, W/4
+        b, c, h, w = f.shape
+        f = f.squeeze(2).permute(0, 2, 1)          # B, W/4, 256
+        out, _ = self.rnn(f)
+        logits = self.head(out)                    # B, T, C
+        return logits.log_softmax(-1).permute(1, 0, 2)

deva_crnn/predict.py

@@ -0,0 +1,127 @@
+"""
+predict.py — run a trained deva_crnn checkpoint on line crops.
+
+Usage:
+    python -m deva_crnn.predict --ckpt out/deva_crnn/ckpt.pt \
+        --images-dir data/doc_eval/heidata_lines/pages --out texts.tsv
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import List, Tuple
+
+import cv2
+import numpy as np
+import torch
+
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if BASE_DIR not in sys.path:
+    sys.path.insert(0, BASE_DIR)
+
+from deva_crnn.charset import decode
+from deva_crnn.data import normalize_line
+from deva_crnn.model import CRNN
+
+
+def load_model(ckpt_path: str, device: str = "cpu"):
+    ckpt = torch.load(ckpt_path, map_location=device, weights_only=False)
+    in_h = int(ckpt.get("in_h", 32))
+    in_w = int(ckpt.get("in_w", 256))
+    model = CRNN(n_classes=len(ckpt["charset"]), in_h=in_h)
+    model.load_state_dict(ckpt["model"])
+    model.eval()
+    model.to(device)
+    model.in_h = in_h  # recognized by recognize_lines for normalization
+    model.in_w = in_w
+    return model, ckpt["charset"]
+
+
+def beam_search_decode(log_probs: np.ndarray, charset: List[str],
+                       beam_width: int = 8) -> str:
+    """CTC prefix beam search over (T, C) log-probabilities.
+
+    Greedy argmax commits to one alignment per frame; on noisy letterpress
+    digits the second-best prefix is often the right one, and beam search
+    keeps those alternatives. `charset[0]` is the CTC blank.
+    """
+    beams = {(): (0.0, -np.inf)}  # prefix -> (p_blank, p_nonblank) log-probs
+    for t in range(log_probs.shape[0]):
+        lp = log_probs[t]
+        nxt: dict = {}
+        for prefix, (pb, pnb) in beams.items():
+            p_total = np.logaddexp(pb, pnb)
+            for c in range(lp.shape[0]):
+                p = lp[c]
+                if c == 0:  # blank: prefix stays
+                    cur = nxt.get(prefix, (-np.inf, -np.inf))
+                    nxt[prefix] = (np.logaddexp(cur[0], p_total + p), cur[1])
+                    continue
+                last = prefix[-1] if prefix else None
+                if c == last:  # repeat: only extend via a blank in between
+                    cur = nxt.get(prefix, (-np.inf, -np.inf))
+                    nxt[prefix] = (cur[0], np.logaddexp(cur[1], pnb + p))
+                    new_prefix = prefix + (c,)
+                    cur = nxt.get(new_prefix, (-np.inf, -np.inf))
+                    nxt[new_prefix] = (cur[0],
+                                       np.logaddexp(cur[1], pb + p))
+                else:
+                    new_prefix = prefix + (c,)
+                    cur = nxt.get(new_prefix, (-np.inf, -np.inf))
+                    nxt[new_prefix] = (cur[0],
+                                       np.logaddexp(cur[1], p_total + p))
+        beams = dict(sorted(nxt.items(),
+                            key=lambda kv: -np.logaddexp(kv[1][0], kv[1][1])
+                            )[:beam_width])
+    best = max(beams.items(), key=lambda kv: np.logaddexp(kv[1][0], kv[1][1]))
+    return "".join(charset[c] for c in best[0])
+
+
+def recognize_lines(model, charset: List[str], images_bgr: List[np.ndarray],
+                    device: str = "cpu", decode_mode: str = "greedy",
+                    beam_width: int = 8) -> List[str]:
+    if not images_bgr:
+        return []
+    in_h = int(getattr(model, "in_h", 32))
+    in_w = int(getattr(model, "in_w", 256))
+    batch = np.stack([normalize_line(im, h=in_h, w=in_w)
+                      for im in images_bgr]).astype(np.float32)
+    x = torch.from_numpy(batch / 255.0).unsqueeze(1)
+    x = ((x - 0.5) / 0.5).to(device)
+    with torch.no_grad():
+        logits = model(x)
+        if decode_mode == "beam":
+            log_probs = logits.log_softmax(-1).cpu().numpy()  # (T, B, C)
+            return [beam_search_decode(log_probs[:, b, :], charset,
+                                       beam_width=beam_width)
+                    for b in range(log_probs.shape[1])]
+        preds = logits.argmax(-1).permute(1, 0)
+    return [decode(p.tolist(), charset) for p in preds]
+
+
+def main():
+    ap = argparse.ArgumentParser(description="deva_crnn line inference")
+    ap.add_argument("--ckpt", required=True)
+    ap.add_argument("--images-dir", required=True)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--device", default="cpu")
+    ap.add_argument("--decode", choices=("greedy", "beam"), default="greedy")
+    ap.add_argument("--beam-width", type=int, default=8)
+    args = ap.parse_args()
+
+    model, charset = load_model(args.ckpt, args.device)
+    names = sorted(f for f in os.listdir(args.images_dir)
+                   if f.lower().endswith((".png", ".jpg", ".jpeg")))
+    imgs = [cv2.imread(os.path.join(args.images_dir, n)) for n in names]
+    keep = [(n, im) for n, im in zip(names, imgs) if im is not None]
+    texts = recognize_lines(model, charset, [im for _, im in keep], args.device,
+                            decode_mode=args.decode, beam_width=args.beam_width)
+    with open(args.out, "w", encoding="utf-8") as f:
+        for (n, _), t in zip(keep, texts):
+            f.write(f"{n}\t{t}\n")
+    print(f"wrote {args.out} ({len(keep)} lines)")
+
+
+if __name__ == "__main__":
+    main()