occular-ocr 0.5.0__py3-none-win_amd64.whl

_occular_vcrt.py

@@ -0,0 +1,47 @@
+"""C++-рантайм Microsoft для onnxruntime/pyclipper/pymupdf на Windows x64 без Visual C++ Redistributable.
+
+Колесо occular-ocr для win_amd64 кладёт этот модуль и occular-vcrt.pth в site-packages; .pth выполняется
+при старте Python, поэтому рантайм на месте, даже если onnxruntime или fitz импортируют раньше occular.
+Если все 5 файлов есть в System32 (Redistributable стоит — так почти везде), ничего не делаем. Иначе
+грузим недостающие: сначала копию, которую находит Windows (например, рядом с python.exe), и только
+если её нет — нашу из occular/_vcrt. Ошибки глотаем: .pth не должен мешать запуску Python.
+"""
+import os
+import sys
+
+DLLS = ("vcruntime140.dll", "vcruntime140_1.dll", "msvcp140.dll", "msvcp140_1.dll",
+        "msvcp140_atomic_wait.dll")    # порядок важен: msvcp140 зависит от vcruntime140
+loaded_from_package = []
+
+
+def preload():
+    if sys.platform != "win32":
+        return
+    sys32 = os.path.join(os.environ.get("SystemRoot", r"C:\Windows"), "System32")
+    if all(os.path.exists(os.path.join(sys32, n)) for n in DLLS):
+        return
+    d = os.path.join(os.path.dirname(os.path.abspath(__file__)), "occular", "_vcrt")
+    if not os.path.isdir(d):
+        return
+    import ctypes
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    k32.GetModuleHandleW.restype = ctypes.c_void_p
+    for name in DLLS:
+        if name in loaded_from_package or k32.GetModuleHandleW(name):
+            continue
+        try:
+            ctypes.WinDLL(name)
+            continue
+        except OSError:
+            pass
+        try:
+            ctypes.WinDLL(os.path.join(d, name))
+            loaded_from_package.append(name)
+        except OSError:
+            pass
+
+
+try:
+    preload()
+except Exception:
+    pass

occular/__init__.py

@@ -0,0 +1,349 @@
+"""
+Occular OCR Package
+
+# Для чайников (4 строки):
+    from occular import ocr
+    text = ocr("photo.png")
+    print(text)
+
+# Для продвинутых:
+    from occular import OCRPipeline
+    pipeline = OCRPipeline()
+    results = pipeline.process_pdf("doc.pdf", dpi=300, workers=8)
+
+# CLI:
+    ocr photo.png
+    ocr document.pdf --workers 4
+"""
+
+__version__ = "0.5.0"
+
+import os
+from typing import Union, List, Dict, Optional
+from pathlib import Path
+
+from . import _envcheck
+_envcheck.check()          # конфликтующие сборки onnxruntime / opencv в одном модуле — предупредить сразу
+
+from .registry import Registry
+from .pipeline import OCRPipeline as _OCRPipelineBase, get_optimal_workers
+from .model_files import (model_info, download_reading_order, reading_order_ready, WEIGHTS_DIR,
+                          download_layout, layout_ready)
+from .layout import LayoutDetector, LayoutRegion, LayoutResult, LAYOUT_LABELS
+from .settings import Settings
+
+
+# ============================================================================
+# Регистрация компонентов
+# ============================================================================
+
+# Все модели — ONNX (CPU или CUDA через onnxruntime).
+from .dbnet_detector_onnx import DBNetDetectorONNX
+from .recognizer_onnx import CRNNRecognizerONNX
+from .multilingual import MultilingualRecognizer, ALL_LANGS, CYR12_LANGS
+Registry.register_detector("dbnet-onnx", DBNetDetectorONNX)
+Registry.register_recognizer("crnn-onnx", CRNNRecognizerONNX)
+# Мультиязычный роутер (русская ru/en + 12 кир-языков), выбирается через ocr(..., languages=[...]).
+Registry.register_recognizer("multilingual", MultilingualRecognizer)
+
+
+def TableRecognizer(*args, **kwargs):
+    """Распознавание таблиц (детекция + структура + объединённые ячейки). Ленивая обёртка —
+    модели грузятся только при вызове. См. occular.tables.TableRecognizer."""
+    from .tables import TableRecognizer as _TR
+    return _TR(*args, **kwargs)
+
+
+def _ensure_registered():
+    """Для совместимости — компоненты уже зарегистрированы при импорте"""
+    pass
+
+
+# ============================================================================
+# Простой API для чайников
+# ============================================================================
+
+def _normalize_languages(languages, arch=None):
+    """None/[] → русская модель по умолчанию (быстрый путь, обратная совместимость).
+    Непустой список или 'auto' → мультиязычный роутер; вернуть (recognizer_name, recognizer_kwargs).
+    arch — архитектура распознавателя ('svtr_lcnet' по умолчанию, 'svtr_t' — крупная)."""
+    extra = {"arch": arch} if arch else {}
+    if not languages:
+        return "crnn-onnx", (extra or None)
+    if isinstance(languages, str):
+        if languages.lower() == "auto":
+            return "multilingual", {"languages": None, **extra}   # авто-роутинг среди всех 14 языков
+        languages = [languages]
+    return "multilingual", {"languages": list(languages), **extra}
+
+
+def _build_pipeline(deskew, lm, num_threads, gpu, reading_order=False, languages=None,
+                    orientation=False, arch=None, tables=False):
+    """Собрать конвейер. languages=None → русский распознаватель (ru/en) по умолчанию;
+    список языков или 'auto' → мультиязычный роутер (русская + 12 кир-языков)."""
+    _ensure_registered()
+    rec_name, rec_kwargs = _normalize_languages(languages, arch)
+    return _OCRPipelineBase(detector_name="dbnet-onnx", recognizer_name=rec_name,
+                            recognizer_kwargs=rec_kwargs,
+                            deskew=deskew, reading_order=reading_order, lm=lm,
+                            num_threads=num_threads, gpu=gpu, orientation=orientation, tables=tables)
+
+
+def ocr(file_path: str, *, deskew: bool = True, lm: bool = True,
+        num_threads: Optional[int] = None, gpu: bool = False,
+        languages=None, orientation: bool = False, recognizer: Optional[str] = None,
+        tables: bool = False) -> Union[str, List[str]]:
+    """
+    Распознать текст из изображения или PDF.
+
+    Args:
+        file_path: путь к файлу (изображение или PDF)
+        deskew: выпрямлять наклон скана (по умолчанию True)
+        lm: beam-CTC + языковая модель для декодирования (по умолчанию True; False = быстрый greedy)
+        num_threads: потоков на страницу (None = min(доступные, 8))
+        gpu: исполнять на GPU/CUDA (нужен пакет onnxruntime-gpu; иначе CPU)
+        orientation: определять поворот страницы (0/90/180/270°) и выпрямлять (по умолчанию False)
+        recognizer: архитектура распознавателя — 'svtr_lcnet' (по умолчанию) или 'svtr_t' (крупная)
+        tables: находить таблицы; в тексте они выводятся Markdown-таблицами на своём месте (по умолчанию False)
+        languages: язык(и) текста. None (по умолчанию) — русская модель (ru/en). Список кодов —
+            мультиязычный роутер: один кир-язык (напр. ['uk']) читается им, несколько (напр.
+            ['ru','kk','uk']) — построчным определением языка. 'auto' — авто среди всех 14.
+            Кир-языки: ba be bg cv kk ky mk mn sr tg tt uk.
+
+    Returns:
+        Для изображения: строка с распознанным текстом
+        Для PDF: список строк (по одной на страницу)
+
+    Example:
+        >>> from occular import ocr
+        >>> text = ocr("photo.png")                 # русский/английский
+        >>> text = ocr("doc_uk.png", languages=["uk"])   # украинский
+        >>> print(text)
+        Привет мир
+    """
+    from .tables import compose_text
+    pipeline = _build_pipeline(deskew, lm, num_threads, gpu, languages=languages,
+                               orientation=orientation, arch=recognizer, tables=tables)
+
+    path = Path(file_path)
+    if path.suffix.lower() == '.pdf':
+        results = pipeline.process_pdf(file_path)
+        # Текст по страницам, строки сверху вниз (таблицы — Markdown на месте первой строки)
+        return [compose_text(sorted(page["results"], key=lambda r: r["quad"][0][1]), page.get("tables"))
+                for page in results]
+    else:
+        results = pipeline.process_image(file_path)
+        return compose_text(sorted(results, key=lambda r: r["quad"][0][1]), getattr(results, "tables", None))
+
+
+def ocr_detailed(file_path: str, *, deskew: bool = True, lm: bool = True,
+                 num_threads: Optional[int] = None, gpu: bool = False,
+                 languages=None, orientation: bool = False, recognizer: Optional[str] = None,
+                 tables: bool = False) -> List[Dict]:
+    """
+    Распознать текст с полной информацией (координаты, confidence).
+
+    Args:
+        file_path: путь к файлу
+        deskew: выпрямлять наклон скана (по умолчанию True)
+        lm: beam-CTC + языковая модель для декодирования (по умолчанию True; False = быстрый greedy)
+        num_threads: потоков на страницу (None = min(доступные, 8))
+        gpu: исполнять на GPU/CUDA (нужен пакет onnxruntime-gpu; иначе CPU)
+        orientation: определять поворот страницы (0/90/180/270°) и выпрямлять (по умолчанию False)
+        recognizer: архитектура распознавателя — 'svtr_lcnet' (по умолчанию) или 'svtr_t' (крупная)
+        languages: язык(и) текста (см. ocr()). None — русская модель (ru/en); список кодов или
+            'auto' — мультиязычный роутер (русская + 12 кир-языков).
+        tables: находить таблицы (по умолчанию False): строкам в таблице добавляются ключи 'table' и
+            'cell', структура таблиц — в атрибуте .tables результата (для PDF — ключ 'tables' страницы)
+
+    Returns:
+        Список словарей {"quad": [...], "text": str, "confidence": float}
+        Для PDF: список страниц с результатами
+
+    Example:
+        >>> results = ocr_detailed("photo.png")
+        >>> for r in results:
+        ...     print(f"{r['text']} ({r['confidence']:.2f})")
+    """
+    pipeline = _build_pipeline(deskew, lm, num_threads, gpu, languages=languages,
+                               orientation=orientation, arch=recognizer, tables=tables)
+
+    path = Path(file_path)
+    if path.suffix.lower() == '.pdf':
+        return pipeline.process_pdf(file_path)
+    else:
+        return pipeline.process_image(file_path)
+
+
+# ============================================================================
+# Продвинутый API
+# ============================================================================
+
+class OCRPipeline:
+    """
+    OCR Pipeline для продвинутых пользователей.
+
+    Настройки — через объект Settings или отдельные kwargs (deskew, reading_order, num_threads).
+
+    Example:
+        >>> pipeline = OCRPipeline()
+        >>> results = pipeline.process_image("photo.png")
+        >>> text = pipeline.get_text("photo.png")
+    """
+
+    def __init__(
+        self,
+        settings: Optional[Settings] = None,
+        *,
+        deskew: bool = True,
+        reading_order: bool = False,
+        lm: bool = True,
+        num_threads: Optional[int] = None,
+        gpu: bool = False,
+        detector: Optional[str] = None,
+        recognizer: Optional[str] = None,
+        languages=None,
+        orientation: bool = False,
+        unwarp=None,
+        unwarp_gate=True,
+        unwarp_margin: float = 1.05,
+        experimental_layout_order: bool = False,
+        layout_order_method: str = "model",
+        tables: bool = False
+    ):
+        _ensure_registered()
+
+        # Единые настройки: можно передать объект Settings, либо отдельные kwargs (совместимость).
+        if settings is None:
+            settings = Settings(deskew=deskew, reading_order=reading_order, lm=lm,
+                                num_threads=num_threads, gpu=gpu, orientation=orientation,
+                                detector=detector, recognizer=recognizer, languages=languages,
+                                unwarp=unwarp, unwarp_gate=unwarp_gate, unwarp_margin=unwarp_margin,
+                                experimental_layout_order=experimental_layout_order,
+                                layout_order_method=layout_order_method, tables=tables)
+        self.settings = settings
+        s = settings
+
+        # Порядок чтения (layout) — опционально, ВЫКЛ по умолчанию. Модель качается с HuggingFace.
+        self.reading_order = s.reading_order
+        if s.reading_order and not reading_order_ready():
+            raise RuntimeError(
+                "reading_order=True, but the reading-order model is not downloaded.\n"
+                "Download it:  from occular import download_reading_order; download_reading_order()\n"
+                "Or check the status:  from occular import model_info; model_info()"
+            )
+
+        detector = s.detector or "dbnet-onnx"
+        # s.recognizer — обычно АРХИТЕКТУРА ('svtr_lcnet' | 'svtr_t'); имя из реестра
+        # ('crnn-onnx', 'multilingual') тоже принимается для обратной совместимости.
+        from .recognizer_onnx import RECOGNIZER_ARCHS
+        if s.recognizer and s.recognizer not in RECOGNIZER_ARCHS:
+            recognizer, rec_kwargs = s.recognizer, None            # старое: имя в реестре
+        else:
+            recognizer, rec_kwargs = _normalize_languages(s.languages, s.recognizer)
+
+        self._pipeline = _OCRPipelineBase(
+            detector_name=detector,
+            recognizer_name=recognizer,
+            recognizer_kwargs=rec_kwargs,
+            deskew=s.deskew,
+            orientation=s.orientation,
+            reading_order=s.reading_order,
+            lm=s.lm,
+            num_threads=s.num_threads,
+            gpu=s.gpu,
+            unwarp=s.unwarp,
+            unwarp_gate=s.unwarp_gate,
+            unwarp_margin=s.unwarp_margin,
+            experimental_layout_order=s.experimental_layout_order,
+            layout_order_method=s.layout_order_method,
+            tables=s.tables
+        )
+
+    def process_image(self, image_path: str) -> List[Dict]:
+        """
+        Обработать изображение.
+
+        Returns:
+            Список {"quad": [...], "text": str, "confidence": float}; при Settings(tables=True) у строк в
+            таблицах есть ключи 'table' и 'cell', а у списка — атрибут .tables (структура таблиц)
+        """
+        return self._pipeline.process_image(image_path)
+
+    def process_pdf(
+        self,
+        pdf_path: str,
+        *,
+        dpi: int = 300,
+        force_ocr: bool = False,
+        workers: Optional[int] = None
+    ) -> List[Dict]:
+        """
+        Обработать PDF.
+
+        Args:
+            pdf_path: путь к PDF
+            dpi: разрешение рендеринга (default: 300)
+            force_ocr: принудительно OCR даже для векторных PDF
+            workers: сколько страниц параллельно, отдельными процессами (None = авто по ядрам и памяти,
+                до 16; 1 = последовательно). Нужен `if __name__ == "__main__":` в главном скрипте —
+                иначе потоки (до 8)
+
+        Returns:
+            Список страниц с результатами
+        """
+        return self._pipeline.process_pdf(
+            pdf_path,
+            dpi=dpi,
+            force_ocr=force_ocr,
+            workers=workers
+        )
+
+    def get_text(self, file_path: str, **kwargs) -> Union[str, List[str]]:
+        """
+        Получить только текст (без координат).
+
+        Returns:
+            Для изображения: строка
+            Для PDF: список строк по страницам
+        """
+        from .tables import compose_text
+        path = Path(file_path)
+        if path.suffix.lower() == '.pdf':
+            results = self.process_pdf(file_path, **kwargs)
+            return [compose_text(page["results"], page.get("tables")) for page in results]
+        else:
+            results = self.process_image(file_path)
+            return compose_text(results, getattr(results, "tables", None))
+
+
+# ============================================================================
+# Экспорт
+# ============================================================================
+
+__all__ = [
+    # Простой API
+    "ocr",
+    "ocr_detailed",
+    # Продвинутый API
+    "OCRPipeline",
+    "Settings",
+    # Таблицы (детекция + структура)
+    "TableRecognizer",
+    # Модели: где лежат и как скачать порядок чтения (для чайников)
+    "model_info",
+    "download_reading_order",
+    "reading_order_ready",
+    # Layout-регионы (D-FINE-S): координаты, score, метка, размер страницы
+    "LayoutDetector",
+    "LayoutRegion",
+    "LayoutResult",
+    "LAYOUT_LABELS",
+    "download_layout",
+    "layout_ready",
+    "WEIGHTS_DIR",
+    # Утилиты
+    "get_optimal_workers",
+    # Низкоуровневый доступ
+    "Registry",
+]

occular/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m occular`"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

occular/_beam.py

@@ -0,0 +1,195 @@
+# Beam search adapted from pyctcdecode 0.5.0 (decoder.py, language_model.py), Copyright 2021-present
+# Kensho Technologies, LLC, licensed under the Apache License 2.0; see LICENSE-pyctcdecode.
+# Changes: only the configuration occular uses is kept (character alphabet, n-gram LM, no hotwords,
+# no history pruning, no multiprocessing); word-frame bookkeeping is dropped (it never affects scores).
+"""CTC beam search with shallow n-gram LM fusion — pure Python + numpy, no third-party decoder.
+
+Scores, tie-breaking and output are identical to ``pyctcdecode.BeamSearchDecoderCTC.decode_beams``
+with the same model; kept in-tree so the package does not inherit pyctcdecode's ``numpy<2`` pin.
+"""
+import heapq
+import math
+
+import numpy as np
+
+# pyctcdecode defaults (decoder parameters occular relies on)
+UNK_LOGP_OFFSET = -10.0
+BEAM_PRUNE_LOGP = -10.0
+TOKEN_MIN_LOGP = -5.0
+AVG_TOKEN_LEN = 6                          # expected characters per word (for OOV prefix scoring)
+MIN_TOKEN_CLIP_P = 1e-15
+LOG_BASE_CHANGE_FACTOR = 1.0 / math.log10(math.e)    # n-gram scores are log10, beam works in ln
+
+
+def _log_softmax(x, axis):
+    """Logarithm of softmax (as in scipy.special / pyctcdecode)."""
+    x_max = np.amax(x, axis=axis, keepdims=True)
+    if x_max.ndim > 0:
+        x_max[~np.isfinite(x_max)] = 0
+    elif not np.isfinite(x_max):
+        x_max = 0
+    tmp = x - x_max
+    exp_tmp = np.exp(tmp)
+    with np.errstate(divide="ignore"):
+        s = np.sum(exp_tmp, axis=axis, keepdims=True)
+        out = np.log(s)
+    return tmp - out
+
+
+def _sum_log_scores(s1, s2):
+    if s1 >= s2:
+        return s1 + math.log(1 + math.exp(s2 - s1))
+    return s2 + math.log(1 + math.exp(s1 - s2))
+
+
+def _merge_tokens(token_1, token_2):
+    if len(token_2) == 0:
+        return token_1
+    if len(token_1) == 0:
+        return token_2
+    return token_1 + " " + token_2
+
+
+# beam: (text, next_word, word_part, last_char, logit_score)
+def _merge_beams(beams):
+    """Merge beams that read the same (text, partial word, last char); sum their probabilities."""
+    beam_dict = {}
+    for text, next_word, word_part, last_char, logit_score in beams:
+        key = (_merge_tokens(text, next_word), word_part, last_char)
+        prev = beam_dict.get(key)
+        if prev is None:
+            beam_dict[key] = (text, next_word, word_part, last_char, logit_score)
+        else:
+            beam_dict[key] = (text, next_word, word_part, last_char,
+                              _sum_log_scores(prev[-1], logit_score))
+    return list(beam_dict.values())
+
+
+class LanguageModel:
+    """Shallow-fusion scorer over an n-gram model through the interface of ``_pylm.Model``."""
+
+    def __init__(self, model, state_cls, unigrams, prefix_checker, alpha, beta,
+                 unk_score_offset=UNK_LOGP_OFFSET, score_boundary=True):
+        self._model = model
+        self._state_cls = state_cls
+        self._unigram_set = set(unigrams)
+        self._char_trie = prefix_checker
+        self.alpha = alpha
+        self.beta = beta
+        self.unk_score_offset = unk_score_offset
+        self.score_boundary = score_boundary
+
+    @property
+    def order(self):
+        return self._model.order
+
+    def get_start_state(self):
+        st = self._state_cls()
+        if self.score_boundary:
+            self._model.BeginSentenceWrite(st)
+        else:
+            self._model.NullContextWrite(st)
+        return st
+
+    def _get_raw_end_score(self, start_state):
+        if self.score_boundary:
+            return self._model.BaseScore(start_state, "</s>", self._state_cls())
+        return 0.0
+
+    def score_partial_token(self, partial_token):
+        is_oov = int(self._char_trie.has_node(partial_token) == 0)
+        unk_score = self.unk_score_offset * is_oov
+        if len(partial_token) > AVG_TOKEN_LEN:
+            unk_score = unk_score * len(partial_token) / AVG_TOKEN_LEN
+        return unk_score
+
+    def score(self, prev_state, word, is_last_word=False):
+        end_state = self._state_cls()
+        lm_score = self._model.BaseScore(prev_state, word, end_state)
+        # same precedence as pyctcdecode: (known-set non-empty and word unknown) or word not in model
+        if len(self._unigram_set) > 0 and word not in self._unigram_set or word not in self._model:
+            lm_score += self.unk_score_offset
+        if is_last_word:
+            lm_score = lm_score + self._get_raw_end_score(end_state)
+        lm_score = self.alpha * lm_score * LOG_BASE_CHANGE_FACTOR + self.beta
+        return lm_score, end_state
+
+
+class BeamSearchDecoder:
+    """CTC beam search over a character alphabet (index 0 = blank ``""``, word separator ``" "``)."""
+
+    def __init__(self, labels, language_model):
+        labels = list(labels)
+        if "" not in labels:
+            raise ValueError("alphabet must contain the CTC blank ''")
+        if len(labels) != len(set(labels)):
+            raise ValueError("alphabet contains duplicate entries")
+        self._idx2vocab = dict(enumerate(labels))
+        self._lm = language_model
+
+    def _get_lm_beams(self, beams, cached_lm_scores, cached_partial_token_scores, is_eos=False):
+        """Beams with combined score appended: (text, '', word_part, last_char, logit, combined)."""
+        lm = self._lm
+        new_beams = []
+        for text, next_word, word_part, last_char, logit_score in beams:
+            new_text = _merge_tokens(text, next_word)
+            cache_key = (new_text, is_eos)
+            if cache_key not in cached_lm_scores:
+                prev_raw_lm_score, start_state = cached_lm_scores[(text, False)]
+                score, end_state = lm.score(start_state, next_word, is_last_word=is_eos)
+                cached_lm_scores[cache_key] = (prev_raw_lm_score + score, end_state)
+            lm_score = cached_lm_scores[cache_key][0]
+            if len(word_part) > 0:
+                if word_part not in cached_partial_token_scores:
+                    cached_partial_token_scores[word_part] = lm.score_partial_token(word_part)
+                lm_score += cached_partial_token_scores[word_part]
+            new_beams.append((new_text, "", word_part, last_char, logit_score, logit_score + lm_score))
+        return new_beams
+
+    def _decode_logits(self, logits, beam_width, beam_prune_logp, token_min_logp):
+        cached_lm_scores = {("", False): (0.0, self._lm.get_start_state())}
+        cached_p_lm_scores = {}
+        beams = [("", "", "", None, 0.0)]
+        idx2vocab = self._idx2vocab
+        for logit_col in logits:
+            max_idx = logit_col.argmax()
+            # set iteration order matters for merge/tie-breaking — keep pyctcdecode's construction
+            idx_list = set(np.where(logit_col >= token_min_logp)[0]) | {max_idx}
+            new_beams = []
+            for idx_char in idx_list:
+                p_char = logit_col[idx_char]
+                char = idx2vocab[idx_char]
+                for text, next_word, word_part, last_char, logit_score in beams:
+                    if char == "" or last_char == char:          # blank or repeated char
+                        new_beams.append((text, next_word, word_part, char, logit_score + p_char))
+                    elif char == " ":                            # word boundary
+                        new_beams.append((text, word_part, "", char, logit_score + p_char))
+                    else:                                        # continue the current word
+                        new_beams.append((text, next_word, word_part + char, char, logit_score + p_char))
+            new_beams = _merge_beams(new_beams)
+            scored = self._get_lm_beams(new_beams, cached_lm_scores, cached_p_lm_scores)
+            max_score = max([b[-1] for b in scored])
+            scored = [b for b in scored if b[-1] >= max_score + beam_prune_logp]
+            beams = [b[:-1] for b in heapq.nlargest(beam_width, scored, key=lambda x: x[-1])]
+
+        # close the last word, score end of sentence
+        new_beams = [(text, word_part, "", None, logit_score)
+                     for text, _, word_part, _, logit_score in beams]
+        new_beams = _merge_beams(new_beams)
+        scored = self._get_lm_beams(new_beams, cached_lm_scores, cached_p_lm_scores, is_eos=True)
+        max_score = max([b[-1] for b in scored])
+        scored = [b for b in scored if b[-1] >= max_score + beam_prune_logp]
+        trimmed = heapq.nlargest(beam_width, scored, key=lambda x: x[-1])
+        return [(" ".join(text.split()), logit_score, combined_score)
+                for text, _, _, _, logit_score, combined_score in trimmed]
+
+    def decode_beams(self, logits, beam_width=100, beam_prune_logp=BEAM_PRUNE_LOGP,
+                     token_min_logp=TOKEN_MIN_LOGP):
+        """logits [T, C] -> beams sorted best-first: (text, acoustic_logit_score, combined_score)."""
+        if logits.ndim != 2 or logits.shape[-1] != len(self._idx2vocab):
+            raise ValueError(f"logits must be (time, {len(self._idx2vocab)}), got {logits.shape}")
+        if math.isclose(logits.sum(axis=1).mean(), 1):          # probabilities -> log probs
+            logits = np.log(np.clip(logits, MIN_TOKEN_CLIP_P, 1))
+        else:
+            logits = np.clip(_log_softmax(logits, axis=1), np.log(MIN_TOKEN_CLIP_P), 0)
+        return self._decode_logits(logits, beam_width, beam_prune_logp, token_min_logp)