media-intelligence 0.1.0__tar.gz

media_intelligence-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: media_intelligence
+Version: 0.1.0
+Summary: Abstract Intelligence Platform — a unified, layered pipeline that turns raw media (PDFs, images, video) into structured, searchable, SEO-ready data.
+Author: AbstractEndeavors
+Keywords: ocr,pdf,video,transcription,summarization,seo,media,pipeline
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: core
+Requires-Dist: abstract_essentials; extra == "core"
+Provides-Extra: ingest
+Requires-Dist: abstract_webtools; extra == "ingest"
+Provides-Extra: ocr
+Requires-Dist: abstract_ocr; extra == "ocr"
+Provides-Extra: documents
+Requires-Dist: abstract_pdfs; extra == "documents"
+Provides-Extra: video
+Requires-Dist: abstract_videos; extra == "video"
+Provides-Extra: transcribe
+Requires-Dist: hugpy; extra == "transcribe"
+Provides-Extra: enrich
+Requires-Dist: hugpy; extra == "enrich"
+Provides-Extra: publish
+Requires-Dist: abstract_react; extra == "publish"
+Requires-Dist: abstract_nginx; extra == "publish"
+Provides-Extra: all
+Requires-Dist: abstract_webtools; extra == "all"
+Requires-Dist: abstract_ocr; extra == "all"
+Requires-Dist: abstract_pdfs; extra == "all"
+Requires-Dist: abstract_videos; extra == "all"
+Requires-Dist: hugpy; extra == "all"
+Requires-Dist: abstract_react; extra == "all"
+Requires-Dist: abstract_nginx; extra == "all"
+
+# media_intelligence — Abstract Intelligence Platform
+
+A unified, layered facade that turns raw media — **PDFs, images, and video** —
+into **structured, searchable, SEO-ready data**. It does not reimplement any
+engine: it selects the *best* function of each sibling package and exposes it
+behind one clean, lazy API, plus an orchestrated pipeline.
+
+```text
+Raw Media (PDF / Image / Video / URL)
+   │
+   ▼
+ingest  → extract → structure → enrich → persist → publish
+(webtools) (ocr/    (typed     (hugpy)  (FS / DB) (react/
+            pdfs/    metadata)                      nginx)
+            videos)
+```
+
+## Layers → canonical owners
+
+| Layer        | Owner package        | What it does                                   |
+|--------------|----------------------|------------------------------------------------|
+| `ingest`     | `abstract_webtools`  | scrape pages, download video (yt-dlp/ffmpeg)   |
+| `ocr`        | `abstract_ocr`       | layout-aware, multi-engine OCR                 |
+| `documents`  | `abstract_pdfs`      | PDF decomposition + manifests + HTML           |
+| `video`      | `abstract_videos`    | registry pipeline: download/frames/transcribe  |
+| `transcribe` | `hugpy` (→ `abstract_ocr` fallback) | Whisper speech-to-text          |
+| `enrich`     | `hugpy`              | summaries, keywords, vision captioning, SEO    |
+| `persist`    | filesystem (DB-pluggable) | typed JSON/JSONB manifests                |
+| `publish`    | `abstract_react` + `abstract_nginx` | SEO/OG metadata + static HTML   |
+
+Overlapping capabilities are resolved to **one owner** (Whisper → `hugpy`;
+video download → `webtools`; summarize/keywords → `hugpy`).
+
+## Install
+
+`media_intelligence` is *just this `src/` facade* — it contains none of the
+engines. Each layer's owner is its own PyPI package, declared as an **optional
+extra**, so you install only what you use:
+
+```bash
+pip install media_intelligence              # zero third-party deps — facade only
+pip install "media_intelligence[ocr,enrich]"  # just those layers
+pip install "media_intelligence[all]"       # the full platform
+```
+
+The package has **no required third-party dependencies**: importing it is cheap
+(~20 ms) and pulls **none** of the backing packages. Each sibling is imported
+**lazily**, only when its layer is actually called; a missing one raises a clear
+`MissingDependency` naming the extra to install.
+
+Check what's usable in the current environment without importing anything:
+
+```python
+import media_intelligence as mi
+mi.available()            # {'ingest': True, 'ocr': True, 'publish': False, ...}
+mi.available("enrich")    # True / False
+```
+
+## Usage
+
+### Direct namespace access
+
+```python
+import media_intelligence as mi
+
+text = mi.ocr.image_to_text("page.png")
+kw   = mi.enrich.keywords(text)
+mi.documents.process_pdf("doc.pdf")
+mi.ingest.download_video("https://site.com/v.mp4", download_directory="/data")
+```
+
+### Orchestrated pipeline (idempotent + resumable)
+
+```python
+from media_intelligence import MediaPipeline
+
+pipe = MediaPipeline("https://site.com/video.mp4", out_root="/data")
+pipe.ingest().extract().structure().enrich().persist().publish()
+print(pipe.report.summary)
+#   ... or simply:
+pipe.run()
+```
+
+The pipeline autodetects media kind, dispatches each stage accordingly, skips
+stages already satisfied (idempotent), and rehydrates from a prior manifest on
+re-run (resumable). Results land in `out_root/<media_id>/manifest.json`.
+
+### Persistence (DB-pluggable, two records)
+
+Each item is persisted as **two** records so indexing stays cheap while
+aggregation stays simple:
+
+- `manifest.json` — lean index: ids, counts, `text_chars`, summary, keywords,
+  SEO, asset pointers. (The JSONB metadata row.)
+- `document.json` — canonical content: full `text`, `pages`/segments,
+  `transcript`. The single source of truth for search / aggregation / LLM
+  datasets — one read per item, no re-stitching of per-owner on-disk files.
+
+```python
+store = mi.persist.FileStore("/data")
+store.save_manifest(item.media_id, manifest)   # lean index
+store.save_document(item.media_id, document)   # full body
+doc = store.load_document(item.media_id)        # aggregation reads this
+
+# later, identical interface, JSONB backend:
+# store = mi.persist.PgStore(dsn=...)   # planned (abstract_database)
+#   -> metadata in JSONB, body text in a full-text-indexed column
+```
+
+`MediaPipeline.persist()` writes both. On re-run, the body is rehydrated from
+`document.json`, so `extract`/`enrich` skip (no re-OCR / re-transcribe).
+```

media_intelligence-0.1.0/README.md

@@ -0,0 +1,112 @@
+# media_intelligence — Abstract Intelligence Platform
+
+A unified, layered facade that turns raw media — **PDFs, images, and video** —
+into **structured, searchable, SEO-ready data**. It does not reimplement any
+engine: it selects the *best* function of each sibling package and exposes it
+behind one clean, lazy API, plus an orchestrated pipeline.
+
+```text
+Raw Media (PDF / Image / Video / URL)
+   │
+   ▼
+ingest  → extract → structure → enrich → persist → publish
+(webtools) (ocr/    (typed     (hugpy)  (FS / DB) (react/
+            pdfs/    metadata)                      nginx)
+            videos)
+```
+
+## Layers → canonical owners
+
+| Layer        | Owner package        | What it does                                   |
+|--------------|----------------------|------------------------------------------------|
+| `ingest`     | `abstract_webtools`  | scrape pages, download video (yt-dlp/ffmpeg)   |
+| `ocr`        | `abstract_ocr`       | layout-aware, multi-engine OCR                 |
+| `documents`  | `abstract_pdfs`      | PDF decomposition + manifests + HTML           |
+| `video`      | `abstract_videos`    | registry pipeline: download/frames/transcribe  |
+| `transcribe` | `hugpy` (→ `abstract_ocr` fallback) | Whisper speech-to-text          |
+| `enrich`     | `hugpy`              | summaries, keywords, vision captioning, SEO    |
+| `persist`    | filesystem (DB-pluggable) | typed JSON/JSONB manifests                |
+| `publish`    | `abstract_react` + `abstract_nginx` | SEO/OG metadata + static HTML   |
+
+Overlapping capabilities are resolved to **one owner** (Whisper → `hugpy`;
+video download → `webtools`; summarize/keywords → `hugpy`).
+
+## Install
+
+`media_intelligence` is *just this `src/` facade* — it contains none of the
+engines. Each layer's owner is its own PyPI package, declared as an **optional
+extra**, so you install only what you use:
+
+```bash
+pip install media_intelligence              # zero third-party deps — facade only
+pip install "media_intelligence[ocr,enrich]"  # just those layers
+pip install "media_intelligence[all]"       # the full platform
+```
+
+The package has **no required third-party dependencies**: importing it is cheap
+(~20 ms) and pulls **none** of the backing packages. Each sibling is imported
+**lazily**, only when its layer is actually called; a missing one raises a clear
+`MissingDependency` naming the extra to install.
+
+Check what's usable in the current environment without importing anything:
+
+```python
+import media_intelligence as mi
+mi.available()            # {'ingest': True, 'ocr': True, 'publish': False, ...}
+mi.available("enrich")    # True / False
+```
+
+## Usage
+
+### Direct namespace access
+
+```python
+import media_intelligence as mi
+
+text = mi.ocr.image_to_text("page.png")
+kw   = mi.enrich.keywords(text)
+mi.documents.process_pdf("doc.pdf")
+mi.ingest.download_video("https://site.com/v.mp4", download_directory="/data")
+```
+
+### Orchestrated pipeline (idempotent + resumable)
+
+```python
+from media_intelligence import MediaPipeline
+
+pipe = MediaPipeline("https://site.com/video.mp4", out_root="/data")
+pipe.ingest().extract().structure().enrich().persist().publish()
+print(pipe.report.summary)
+#   ... or simply:
+pipe.run()
+```
+
+The pipeline autodetects media kind, dispatches each stage accordingly, skips
+stages already satisfied (idempotent), and rehydrates from a prior manifest on
+re-run (resumable). Results land in `out_root/<media_id>/manifest.json`.
+
+### Persistence (DB-pluggable, two records)
+
+Each item is persisted as **two** records so indexing stays cheap while
+aggregation stays simple:
+
+- `manifest.json` — lean index: ids, counts, `text_chars`, summary, keywords,
+  SEO, asset pointers. (The JSONB metadata row.)
+- `document.json` — canonical content: full `text`, `pages`/segments,
+  `transcript`. The single source of truth for search / aggregation / LLM
+  datasets — one read per item, no re-stitching of per-owner on-disk files.
+
+```python
+store = mi.persist.FileStore("/data")
+store.save_manifest(item.media_id, manifest)   # lean index
+store.save_document(item.media_id, document)   # full body
+doc = store.load_document(item.media_id)        # aggregation reads this
+
+# later, identical interface, JSONB backend:
+# store = mi.persist.PgStore(dsn=...)   # planned (abstract_database)
+#   -> metadata in JSONB, body text in a full-text-indexed column
+```
+
+`MediaPipeline.persist()` writes both. On re-run, the body is rehydrated from
+`document.json`, so `extract`/`enrich` skip (no re-OCR / re-transcribe).
+```

media_intelligence-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "media_intelligence"
+version = "0.1.0"
+description = "Abstract Intelligence Platform — a unified, layered pipeline that turns raw media (PDFs, images, video) into structured, searchable, SEO-ready data."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "AbstractEndeavors" }]
+keywords = ["ocr", "pdf", "video", "transcription", "summarization", "seo", "media", "pipeline"]
+
+# The facade is a thin, pure-stdlib access layer with ZERO required third-party
+# deps: importing it pulls nothing. Each backing package is its own PyPI project,
+# imported lazily only when that layer is used. Install just the layers you need
+# via the extras below (or `[all]`). `abstract_essentials` is used opportunistically
+# by the filesystem store but has a stdlib fallback, so it's optional too.
+dependencies = []
+
+[project.optional-dependencies]
+# Each layer maps to one canonical owning package. Install only what you use.
+core      = ["abstract_essentials"]   # nicer atomic JSON I/O for FileStore (optional)
+ingest    = ["abstract_webtools"]
+ocr       = ["abstract_ocr"]
+documents = ["abstract_pdfs"]
+video     = ["abstract_videos"]
+transcribe= ["hugpy"]           # canonical ASR (falls back to abstract_ocr if absent)
+enrich    = ["hugpy"]           # canonical ML/NLP namespace (latest iteration)
+publish   = ["abstract_react", "abstract_nginx"]
+# Everything for the full end-to-end platform.
+all = [
+    "abstract_webtools",
+    "abstract_ocr",
+    "abstract_pdfs",
+    "abstract_videos",
+    "hugpy",
+    "abstract_react",
+    "abstract_nginx",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+media_intelligence = ["py.typed"]

media_intelligence-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

media_intelligence-0.1.0/src/media_intelligence/__init__.py

@@ -0,0 +1,158 @@
+"""media_intelligence — the Abstract Intelligence Platform facade.
+
+A unified, layered access layer that turns raw media (PDFs, images, video) into
+structured, searchable, SEO-ready data. It does not reimplement any engine; it
+selects the *best* function of each sibling package and exposes it behind one
+clean, lazy API.
+
+Two ways to use it
+------------------
+
+1. Direct namespace access — grab one tool::
+
+       import media_intelligence as mi
+       text  = mi.ocr.image_to_text("page.png")
+       kw    = mi.enrich.keywords(text)
+       mi.documents.process_pdf("doc.pdf")
+
+2. The orchestrated, idempotent/resumable pipeline::
+
+       from media_intelligence import MediaPipeline
+       pipe = MediaPipeline("https://site.com/video.mp4", out_root="/data")
+       pipe.ingest().extract().structure().enrich().persist().publish()
+       print(pipe.report.summary)
+       #  ... or just:  pipe.run()
+
+Layers map one-to-one onto canonical owning packages:
+
+    ingest    -> abstract_webtools   (scrape + yt-dlp video download)
+    ocr       -> abstract_ocr        (layout-aware multi-engine OCR)
+    documents -> abstract_pdfs       (PDF decomposition + HTML)
+    video     -> abstract_videos     (registry pipeline: download/frames/SEO)
+    transcribe-> hugpy               (Whisper ASR; abstract_ocr fallback)
+    enrich    -> hugpy               (summaries, keywords, vision, SEO)
+    persist   -> filesystem now, DB-pluggable interface
+    publish   -> abstract_react + abstract_nginx (SEO/OG + static HTML)
+
+Every backing package is imported lazily, so ``import media_intelligence`` is
+cheap and a missing optional package only errors when that layer is used.
+"""
+from __future__ import annotations
+
+import importlib
+import importlib.util
+from typing import TYPE_CHECKING
+
+from ._lazy import MediaIntelligenceError, MissingDependency
+from .schemas import (
+    MediaItem,
+    MediaKind,
+    PipelineReport,
+    Stage,
+    StageResult,
+    detect_media_kind,
+)
+
+__version__ = "0.1.0"
+
+# Submodules exposed as lazy namespaces via module __getattr__ below.
+_LAZY_SUBMODULES = {
+    "ingest",
+    "ocr",
+    "documents",
+    "video",
+    "transcribe",
+    "enrich",
+    "structure",
+    "persist",
+    "publish",
+}
+
+# Which backing package(s) each layer needs. ``persist`` is pure-stdlib (always
+# available); ``transcribe`` works if either hugpy or abstract_ocr is present.
+_LAYER_PACKAGES = {
+    "ingest": ("abstract_webtools",),
+    "ocr": ("abstract_ocr",),
+    "documents": ("abstract_pdfs",),
+    "video": ("abstract_videos",),
+    "transcribe": ("hugpy", "abstract_ocr"),   # any-of
+    "enrich": ("hugpy",),
+    "structure": (),
+    "persist": (),
+    "publish": ("abstract_react",),            # nginx HTML is an additional option
+}
+
+__all__ = [
+    "MediaPipeline",
+    "MediaItem",
+    "MediaKind",
+    "Stage",
+    "StageResult",
+    "PipelineReport",
+    "detect_media_kind",
+    "available",
+    "MediaIntelligenceError",
+    "MissingDependency",
+    "__version__",
+    *sorted(_LAZY_SUBMODULES),
+]
+
+
+def _installed(package: str) -> bool:
+    """Whether ``package`` is importable — without importing it."""
+    try:
+        return importlib.util.find_spec(package) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def available(layer: str | None = None):
+    """Report which layers are usable in this environment, without importing them.
+
+    >>> import media_intelligence as mi
+    >>> mi.available()            # {'ingest': True, 'ocr': True, 'publish': False, ...}
+    >>> mi.available("enrich")    # True / False
+
+    A layer is available if (any of) its backing package(s) are installed. The
+    pure-stdlib layers (``structure``, ``persist``) are always available.
+    """
+    def _ok(needed: tuple) -> bool:
+        return True if not needed else any(_installed(p) for p in needed)
+
+    if layer is not None:
+        if layer not in _LAYER_PACKAGES:
+            raise ValueError(f"unknown layer {layer!r}; choose from {sorted(_LAYER_PACKAGES)}")
+        return _ok(_LAYER_PACKAGES[layer])
+    return {name: _ok(pkgs) for name, pkgs in _LAYER_PACKAGES.items()}
+
+if TYPE_CHECKING:  # for type checkers / IDEs only — no runtime import cost
+    from . import (  # noqa: F401
+        documents,
+        enrich,
+        ingest,
+        ocr,
+        persist,
+        publish,
+        structure,
+        transcribe,
+        video,
+    )
+    from .pipeline import MediaPipeline  # noqa: F401
+
+
+def __getattr__(name: str):
+    """PEP 562 lazy attribute access.
+
+    Keeps the import graph flat: namespaces and the (heavier) pipeline module
+    are only imported when first referenced.
+    """
+    if name == "MediaPipeline":
+        module = importlib.import_module(".pipeline", __name__)
+        return module.MediaPipeline
+    if name in _LAZY_SUBMODULES:
+        return importlib.import_module(f".{name}", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(__all__) | set(globals()))

media_intelligence-0.1.0/src/media_intelligence/_lazy.py

@@ -0,0 +1,100 @@
+"""Lazy / soft import plumbing for the media_intelligence facade.
+
+The whole point of this package is to be a *thin* unified access layer over a
+set of heavy sibling packages (paddleocr, torch, yt-dlp, whisper, ...). Importing
+``media_intelligence`` must stay cheap, so every sibling package is imported
+lazily — at first *use*, never at module import time — and the result is cached.
+
+If an optional layer's backing package is not installed, we raise a single,
+actionable :class:`MissingDependency` error that names the extra to install
+rather than leaking a raw ``ModuleNotFoundError`` from deep inside a submodule.
+"""
+from __future__ import annotations
+
+import functools
+import importlib
+from types import ModuleType
+from typing import Any, Callable
+
+__all__ = [
+    "MediaIntelligenceError",
+    "MissingDependency",
+    "soft_import",
+    "require",
+    "lazy_namespace",
+]
+
+
+class MediaIntelligenceError(RuntimeError):
+    """Base error for the media_intelligence facade."""
+
+
+class MissingDependency(MediaIntelligenceError):
+    """A layer was used but its backing package is not installed."""
+
+
+# Which pip extra installs which backing package — used to build helpful errors.
+_EXTRA_FOR_PACKAGE = {
+    "abstract_essentials": "(core)",
+    "abstract_webtools": "ingest",
+    "abstract_ocr": "ocr",
+    "abstract_pdfs": "documents",
+    "abstract_videos": "video",
+    "hugpy": "enrich",
+    "abstract_react": "publish",
+    "abstract_nginx": "publish",
+}
+
+_MODULE_CACHE: dict[str, ModuleType] = {}
+
+
+def soft_import(package: str, *, layer: str | None = None) -> ModuleType:
+    """Import ``package`` lazily, caching the module.
+
+    Raises :class:`MissingDependency` (not ``ModuleNotFoundError``) with an
+    install hint if the package is absent.
+    """
+    cached = _MODULE_CACHE.get(package)
+    if cached is not None:
+        return cached
+    try:
+        module = importlib.import_module(package)
+    except ModuleNotFoundError as exc:
+        # Only translate a *missing backing package*; a genuine sub-import error
+        # inside an installed package should surface unchanged.
+        if exc.name and (exc.name == package or package.startswith(exc.name + ".")):
+            # Resolve the install hint against the *top-level* package, so a
+            # missing submodule (e.g. "abstract_nginx.generate_htmls") still
+            # points at the right extra.
+            top = package.split(".", 1)[0]
+            extra = _EXTRA_FOR_PACKAGE.get(top, top)
+            hint = f'pip install "media_intelligence[{extra}]"' if extra and extra != "(core)" \
+                else f"pip install {top}"
+            raise MissingDependency(
+                f"The '{layer or package}' layer needs '{package}', which is not "
+                f"installed. Install it with:  {hint}"
+            ) from exc
+        raise
+    _MODULE_CACHE[package] = module
+    return module
+
+
+def require(package: str, attr: str, *, layer: str | None = None) -> Any:
+    """Return ``attr`` from a soft-imported ``package``.
+
+    Raises a clear error if the package is installed but the symbol is gone
+    (e.g. an upstream rename) so failures point at the facade, not the user.
+    """
+    module = soft_import(package, layer=layer)
+    try:
+        return getattr(module, attr)
+    except AttributeError as exc:
+        raise MediaIntelligenceError(
+            f"'{package}.{attr}' is not available — the upstream API may have "
+            f"changed. The media_intelligence '{layer or package}' layer needs updating."
+        ) from exc
+
+
+def lazy_namespace(loader: Callable[[], ModuleType]) -> Callable[[], ModuleType]:
+    """Wrap a submodule loader so the import happens once and is memoised."""
+    return functools.lru_cache(maxsize=1)(loader)

media_intelligence-0.1.0/src/media_intelligence/documents.py

@@ -0,0 +1,119 @@
+"""Extraction + structuring layer (documents) — PDFs.
+
+Canonical owner: ``abstract_pdfs``. Page-level decomposition (text + images),
+manifest generation, OCR (delegating to ``abstract_ocr``), enrichment, and
+static HTML (viewer + gallery).
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Optional
+
+from ._lazy import require, soft_import
+
+_PKG = "abstract_pdfs"
+_LAYER = "documents"
+
+__all__ = [
+    "process_pdf",
+    "process_pdfs",
+    "process_all_pdfs",
+    "generate_pdf",
+    "pdf_pages",
+    "DocumentPipeline",
+    "SliceManager",
+]
+
+
+def process_pdf(pdf_path: str, **kwargs: Any) -> dict:
+    """Process every page of one PDF (image→text→info→metadata→html + gallery)."""
+    fn = require(_PKG, "process_pdf", layer=_LAYER)
+    return fn(pdf_path, **kwargs)
+
+
+def process_pdfs(pdf_paths: list[str], **kwargs: Any) -> list:
+    """Batch process many PDFs with two-level parallelism (PDFs × pages)."""
+    fn = require(_PKG, "process_pdfs", layer=_LAYER)
+    return fn(pdf_paths, **kwargs)
+
+
+def process_all_pdfs(directory: str, **kwargs: Any):
+    """Discover and process every ``.pdf`` under ``directory``."""
+    fn = require(_PKG, "process_all_pdfs", layer=_LAYER)
+    return fn(directory, **kwargs)
+
+
+def generate_pdf(pdf_path: str, **kwargs: Any) -> dict:
+    """One-call end-to-end: slice + OCR + enriched manifests + viewer HTML."""
+    mod = soft_import(_PKG + ".pipeline", layer=_LAYER)
+    fn = getattr(mod, "generate_pdf", None) or require(_PKG, "generate_pdf", layer=_LAYER)
+    return fn(pdf_path, **kwargs)
+
+
+def _resolve_pdf_dir(pdf_path: str) -> Optional[str]:
+    """Find the directory holding ``pages/`` for a processed PDF.
+
+    ``process_pdf`` relocates ``<dir>/foo.pdf`` into ``<dir>/foo/foo.pdf`` and
+    writes pages under ``<dir>/foo/pages/``. We check the relocated dir first,
+    then the original dir, so this works whether or not relocation happened.
+    """
+    p = os.path.abspath(pdf_path)
+    parent = os.path.dirname(p)
+    stem = os.path.splitext(os.path.basename(p))[0]
+    for candidate in (os.path.join(parent, stem), parent):
+        if os.path.isdir(os.path.join(candidate, "pages")):
+            return candidate
+    return None
+
+
+def pdf_pages(pdf_path: str) -> tuple[list[dict[str, Any]], Optional[str]]:
+    """Read back the per-page OCR'd text/info that ``process_pdf`` wrote to disk.
+
+    Returns ``(pages, full_text)`` where ``pages`` is a list of
+    ``{"index", "page", "text", "info"}`` dicts in page order, and ``full_text``
+    is the pages joined. Reads the cached ``pages/NNNN/text.txt`` + ``info.json``
+    layout directly — no re-OCR, no fragile deep imports. ``([], None)`` if the
+    PDF hasn't been processed yet.
+    """
+    base = _resolve_pdf_dir(pdf_path)
+    if base is None:
+        return [], None
+    pages_dir = os.path.join(base, "pages")
+    # zero-padded names (0001, 0002, ...) so lexical sort == page order
+    names = sorted(
+        d for d in os.listdir(pages_dir) if os.path.isdir(os.path.join(pages_dir, d))
+    )
+    pages: list[dict[str, Any]] = []
+    for i, name in enumerate(names):
+        pdir = os.path.join(pages_dir, name)
+        text_path = os.path.join(pdir, "text.txt")
+        info_path = os.path.join(pdir, "info.json")
+        text = ""
+        if os.path.isfile(text_path):
+            with open(text_path, "r", encoding="utf-8", errors="replace") as fh:
+                text = fh.read().strip()
+        info: dict[str, Any] = {}
+        if os.path.isfile(info_path):
+            try:
+                with open(info_path, "r", encoding="utf-8") as fh:
+                    info = json.load(fh)
+            except Exception:
+                info = {}
+        pages.append(
+            {"index": int(name) if name.isdigit() else i, "page": name, "text": text, "info": info}
+        )
+    full_text = "\n\n".join(p["text"] for p in pages if p["text"]).strip() or None
+    return pages, full_text
+
+
+def DocumentPipeline(*args: Any, **kwargs: Any):
+    """Construct the per-PDF ``DocumentPipeline`` orchestrator."""
+    cls = require(_PKG, "DocumentPipeline", layer=_LAYER)
+    return cls(*args, **kwargs)
+
+
+def SliceManager(*args: Any, **kwargs: Any):
+    """Construct the slice-aware multi-engine column OCR ``SliceManager``."""
+    cls = require(_PKG, "SliceManager", layer=_LAYER)
+    return cls(*args, **kwargs)