chunksmith-cli 0.4.0__py3-none-any.whl

chunksmith_cli/core/paths.py

@@ -0,0 +1,869 @@
+"""Path helpers for the CLI (normalization, ``cli/data`` archives)."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+from chunksmith_cli.core.artifact_layout import ArtifactLayout
+
+ARTIFACT_SUBDIR_JSON = "json"
+ARTIFACT_SUBDIR_IMAGE = "image"
+ARTIFACT_SUBDIR_TEXT = "text"
+
+
+def normalize_path_string(raw: str) -> Path:
+    """
+    Turn raw user input into a ``Path``: strip whitespace, matching outer quotes,
+    expand ``~``, and map common ``file://`` forms on Windows.
+    """
+    s = (raw or "").strip()
+    if (s.startswith('"') and s.endswith('"')) or (s.startswith("'") and s.endswith("'")):
+        s = s[1:-1].strip()
+    if s.lower().startswith("file:"):
+        parsed = urlparse(s)
+        path_part = unquote(parsed.path or "")
+        # Windows: file:///D:/x -> /D:/x
+        if os.name == "nt" and len(path_part) >= 3 and path_part[0] == "/" and path_part[2] == ":":
+            path_part = path_part.lstrip("/")
+        s = path_part or s
+    return Path(s).expanduser()
+
+
+def resolve_pdf_candidate(p: Path, *, cwd: Path | None = None) -> Path:
+    """
+    If ``p`` is not an existing file, try ``cwd / p`` when ``p`` is relative.
+    Does not guarantee the result exists.
+    """
+    if p.is_file():
+        return p
+    base = cwd or Path.cwd()
+    if not p.is_absolute():
+        alt = (base / p).resolve()
+        if alt.is_file():
+            return alt
+    return p.resolve() if p.exists() else p
+
+
+def _cli_package_dir() -> Path:
+    """``cli/`` package root (parent of ``core/``)."""
+    return Path(__file__).resolve().parent.parent
+
+
+def cli_data_dir() -> Path:
+    """Runtime data root: ``cli/data`` (legacy flat JSON + per-run artifact folders)."""
+    return _cli_package_dir() / "data"
+
+
+def cli_runs_dir() -> Path:
+    """Per-run artifact roots: ``cli/data/runs/{doc-stem}/`` with ``json/``, ``image/``, etc."""
+    return cli_data_dir() / "runs"
+
+
+def cli_json_storage_dir() -> Path:
+    """Legacy flat JSON archive: ``cli/data/legacy`` (no ``json/`` subfolder)."""
+    return cli_data_dir() / "legacy"
+
+
+def ensure_cli_storage() -> Path:
+    """Create ``cli/data`` layout and return the legacy flat archive directory."""
+    for d in (cli_data_dir(), cli_json_storage_dir(), cli_runs_dir()):
+        d.mkdir(parents=True, exist_ok=True)
+    return cli_json_storage_dir()
+
+
+def _storage_search_dirs(storage: Path) -> list[Path]:
+    """Directories to search for saved indexes (legacy flat + ``runs/**``)."""
+    storage = storage.resolve()
+    data = cli_data_dir().resolve()
+    legacy = cli_json_storage_dir().resolve()
+    runs = cli_runs_dir().resolve()
+    roots: list[Path] = [storage]
+    if storage in {legacy, data}:
+        if runs.is_dir():
+            roots.append(runs)
+        if storage == legacy and data.is_dir():
+            roots.append(data)
+    return list(dict.fromkeys(roots))
+
+
+@dataclass(frozen=True)
+class ResolvedAgentIndex:
+    """Paths passed to ``build_document_index_from_saved``."""
+
+    pageindex_path: Path | None
+    canonical_bundle_path: Path | None
+    label: str
+    artifact_root: Path | None = None
+
+
+def default_project_logs_dir() -> Path | None:
+    """Legacy ``python/logs`` or ``logs/`` next to the CLI package, when it exists."""
+    logs = _cli_package_dir().parent / "logs"
+    return logs.resolve() if logs.is_dir() else None
+
+
+def _artifact_json_dir(root: Path) -> Path | None:
+    """Directory containing ``*_canonical_bundle.json`` (artifact ``json/`` or flat)."""
+    if not root.is_dir():
+        return None
+    resolved = root.resolve()
+    if resolved.name == ARTIFACT_SUBDIR_JSON:
+        return resolved if any(resolved.glob("*_canonical_bundle.json")) else None
+    nested = resolved / ARTIFACT_SUBDIR_JSON
+    if nested.is_dir() and any(nested.glob("*_canonical_bundle.json")):
+        return nested
+    if any(resolved.glob("*_canonical_bundle.json")):
+        return resolved
+    return None
+
+
+def _artifact_root_from_json_dir(json_dir: Path) -> Path:
+    if json_dir.name == ARTIFACT_SUBDIR_JSON:
+        return json_dir.parent.resolve()
+    return json_dir.resolve()
+
+
+def _discover_canonical_bundles(json_dir: Path) -> list[Path]:
+    return sorted(
+        json_dir.glob("*_canonical_bundle.json"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+
+
+def _resolved_from_canonical_bundle(
+    cb: Path,
+    *,
+    artifact_root: Path | None = None,
+) -> ResolvedAgentIndex:
+    stem = cb.name[: -len("_canonical_bundle.json")]
+    json_dir = cb.parent
+    pi = json_dir / f"{stem}_pageindex.json"
+    ar = artifact_root or _artifact_root_from_json_dir(json_dir)
+    if pi.is_file():
+        return ResolvedAgentIndex(pi.resolve(), cb.resolve(), stem, ar)
+    outline = json_dir / f"{stem}.json"
+    if outline.is_file() and _json_has_outline_shape(outline):
+        return ResolvedAgentIndex(outline.resolve(), cb.resolve(), stem, ar)
+    return ResolvedAgentIndex(None, cb.resolve(), stem, ar)
+
+
+def resolve_artifact_root_input(root: Path) -> ResolvedAgentIndex | None:
+    """
+      Resolve a multimodal artifact folder (``logs``, ``logs/json``, etc.) to the newest
+    ``*_canonical_bundle.json`` and optional sibling pageindex.
+    """
+    json_dir = _artifact_json_dir(root)
+    if json_dir is None:
+        return None
+    bundles = _discover_canonical_bundles(json_dir)
+    if not bundles:
+        return None
+    return _resolved_from_canonical_bundle(
+        bundles[0].resolve(),
+        artifact_root=_artifact_root_from_json_dir(json_dir),
+    )
+
+
+def _canonical_bundle_sibling(pageindex_path: Path) -> Path | None:
+    name = pageindex_path.name
+    if name.endswith("_pageindex.json"):
+        stem = name[: -len("_pageindex.json")]
+        sibling = pageindex_path.parent / f"{stem}_canonical_bundle.json"
+        return sibling if sibling.is_file() else None
+    if name.endswith(".json"):
+        stem = Path(name).stem
+        sibling = pageindex_path.parent / f"{stem}_canonical_bundle.json"
+        return sibling if sibling.is_file() else None
+    return None
+
+
+def _json_has_outline_shape(path: Path) -> bool:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return isinstance(data, dict) and isinstance(data.get("structure"), list)
+
+
+def resolve_agent_index_input(
+    raw: str,
+    *,
+    storage: Path,
+    cwd: Path | None = None,
+) -> ResolvedAgentIndex | None:
+    """
+    Resolve user input to index JSON paths.
+
+    Accepts a full/relative path, ``file://…``, a file under ``cli/data``,
+    a multimodal artifact folder (e.g. ``logs`` with ``json/`` + ``image/``),
+    a ``*_pageindex.json`` path, outline JSON with ``structure``, a
+    ``*_canonical_bundle.json`` (with or without a sibling pageindex), or a stem.
+    """
+    s = (raw or "").strip()
+    if not s:
+        return None
+
+    base = cwd or Path.cwd()
+    candidates: list[Path] = []
+
+    norm = normalize_path_string(s)
+    dir_candidates: list[Path] = []
+    if not norm.is_absolute():
+        dir_candidates.append((base / norm).resolve())
+    try:
+        dir_candidates.append(norm.resolve())
+    except OSError:
+        pass
+    for resolved_dir in dir_candidates:
+        if resolved_dir.is_dir():
+            from_dir = resolve_artifact_root_input(resolved_dir)
+            if from_dir is not None:
+                return from_dir
+
+    p = resolve_pdf_candidate(norm, cwd=base)
+    candidates.append(p)
+    candidates.append((storage / p.name).resolve())
+    if not Path(s).is_absolute():
+        candidates.append((storage / s).resolve())
+
+    stem = s.strip().strip('"').strip("'")
+    logs = default_project_logs_dir()
+    if logs is not None and stem.lower() != "logs":
+        candidates.append(logs / s)
+        json_dir = logs / ARTIFACT_SUBDIR_JSON
+        if json_dir.is_dir() and not stem.lower().endswith(".json"):
+            candidates.append(json_dir / f"{stem}_canonical_bundle.json")
+            for hit in sorted(json_dir.glob(f"{stem}*_canonical_bundle.json"), reverse=True):
+                candidates.append(hit)
+    elif logs is not None and stem.lower() == "logs":
+        # Prefer cwd-relative ``logs/``; fall back to legacy ``python/logs`` when missing.
+        rel_logs = (base / "logs").resolve()
+        if not rel_logs.is_dir():
+            candidates.append(logs)
+            json_dir = logs / ARTIFACT_SUBDIR_JSON
+            if json_dir.is_dir():
+                for hit in sorted(json_dir.glob("*_canonical_bundle.json"), reverse=True):
+                    candidates.append(hit)
+
+    # Bare stem (no .json): try storage artifacts (legacy flat + runs/**/json/)
+    if not stem.lower().endswith(".json"):
+        for root in _storage_search_dirs(storage):
+            for pattern in (f"{stem}_pageindex.json", f"{stem}.json"):
+                candidates.append(root / pattern)
+            for hit in sorted(root.glob(f"**/{stem}*_pageindex.json"), reverse=True):
+                candidates.append(hit)
+
+    seen: set[Path] = set()
+    for cand in candidates:
+        try:
+            key = cand.resolve()
+        except OSError:
+            continue
+        if key in seen:
+            continue
+        seen.add(key)
+        if not key.is_file():
+            continue
+        if key.name.endswith("_canonical_bundle.json"):
+            return _resolved_from_canonical_bundle(key.resolve())
+        if not _json_has_outline_shape(key):
+            continue
+        cb = _canonical_bundle_sibling(key)
+        label = key.stem.replace("_pageindex", "")
+        ar = _artifact_root_from_json_dir(key.parent) if key.parent.name == ARTIFACT_SUBDIR_JSON else None
+        return ResolvedAgentIndex(
+            key.resolve(),
+            cb.resolve() if cb else None,
+            label,
+            ar,
+        )
+
+    return None
+
+
+def cli_archive_stamp() -> str:
+    """UTC timestamp suffix shared by JSON artifacts from one CLI run."""
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def archive_cli_json(
+    storage_root: Path,
+    pdf_stem: str,
+    json_text: str,
+    *,
+    stamp: str | None = None,
+    suffix: str = "",
+) -> Path:
+    """
+    Write ``{stem}_{stamp}{suffix}.json`` under ``storage_root`` and return the file path.
+
+    ``suffix`` is inserted before ``.json`` (e.g. ``_canonical_bundle``).
+    """
+    stamp = stamp or cli_archive_stamp()
+    path = storage_root / f"{pdf_stem}_{stamp}{suffix}.json"
+    path.write_text(json_text, encoding="utf-8")
+    return path
+
+
+def archive_cli_json_object(
+    storage_root: Path,
+    pdf_stem: str,
+    data: object,
+    *,
+    stamp: str | None = None,
+    suffix: str = "",
+) -> Path:
+    """Pretty-print ``data`` as UTF-8 JSON via :func:`archive_cli_json`."""
+    import json
+
+    text = json.dumps(data, ensure_ascii=False, indent=2)
+    return archive_cli_json(storage_root, pdf_stem, text, stamp=stamp, suffix=suffix)
+
+
+def _bundle_json_disk_shape(bundle: dict[str, object]) -> dict[str, object]:
+    """
+    Slim canonical bundle for ``json/`` (matches V3-style separation).
+
+    Omits ``coded_formate`` (see ``text/*.txt``) and ``unstructured_elements`` (sibling JSON).
+    """
+    return {k: v for k, v in bundle.items() if k not in ("coded_formate", "unstructured_elements")}
+
+
+def _stamp_from_canonical_bundle_path(path_str: str | None) -> str | None:
+    """Parse ``{stem}_{stamp}_canonical_bundle.json`` → stamp."""
+    if not path_str:
+        return None
+    name = Path(path_str).name
+    marker = "_canonical_bundle.json"
+    if not name.endswith(marker):
+        return None
+    stem_part = name[: -len(marker)]
+    if "_" not in stem_part:
+        return None
+    return stem_part.rsplit("_", 1)[-1]
+
+
+# Bulky linear tags live under ``text/`` (see ``path_coded_text``, ``path_compressed_tree_text``).
+_MULTIMODAL_TEXT_ONLY_KEYS = frozenset({"coded_formate", "compressed_tree_string"})
+_PAGEINDEX_JSON_OMIT_KEYS = frozenset({"canonical_bundle", "coded_formate", "compressed_tree_string"})
+
+
+def _multimodal_pageindex_disk_shape(out: dict[str, object]) -> dict[str, object]:
+    """Outline JSON only (no nested bundle, no coded strings), slim ``structure`` like V3."""
+    from chunksmith_v3.outline_tree import (
+        slim_outline_bundle_for_export,
+        strip_redundant_page_fields,
+        strip_text_from_structure,
+    )
+
+    pageindex = {k: v for k, v in out.items() if k not in _PAGEINDEX_JSON_OMIT_KEYS}
+    st = pageindex.get("structure")
+    if isinstance(st, list):
+        pageindex["structure"] = strip_redundant_page_fields(strip_text_from_structure(st))
+    ob = pageindex.get("outline_bundle")
+    if isinstance(ob, dict):
+        pageindex["outline_bundle"] = slim_outline_bundle_for_export(ob)
+    return pageindex
+
+
+def _write_multimodal_text_artifacts_flat(
+    storage_root: Path,
+    pdf_stem: str,
+    *,
+    stamp: str,
+    bundle: dict[str, object] | None,
+    out: dict[str, object],
+    pageindex: dict[str, object],
+) -> None:
+    """Legacy flat ``cli/data/legacy`` text files (not under artifact ``text/``)."""
+    if isinstance(bundle, dict):
+        coded = bundle.get("coded_formate")
+        if isinstance(coded, str) and coded.strip():
+            p = storage_root / f"{pdf_stem}_{stamp}_coded.txt"
+            p.write_text(coded, encoding="utf-8")
+            bundle["path_coded_text"] = str(p.resolve())
+    cts = out.get("compressed_tree_string")
+    if isinstance(cts, str) and cts.strip():
+        tp = storage_root / f"{pdf_stem}_{stamp}_compressed_tree.txt"
+        tp.write_text(cts, encoding="utf-8")
+        pageindex["path_compressed_tree_text"] = str(tp.resolve())
+
+
+def _write_multimodal_text_artifacts(
+    layout: ArtifactLayout,
+    *,
+    stamp: str,
+    bundle: dict[str, object],
+    out: dict[str, object],
+    pageindex: dict[str, object],
+) -> None:
+    """Persist ``coded_formate`` / ``compressed_tree_string`` under ``text/`` once; set path refs on JSON dicts."""
+    coded = bundle.get("coded_formate")
+    coded_path_ref = bundle.get("path_coded_text")
+    if isinstance(coded_path_ref, str) and Path(coded_path_ref).is_file():
+        bundle["path_coded_text"] = str(Path(coded_path_ref).resolve())
+    elif isinstance(coded, str) and coded.strip():
+        coded_path = layout.coded_text_path(stamp=stamp)
+        coded_path.write_text(coded, encoding="utf-8")
+        bundle["path_coded_text"] = str(coded_path.resolve())
+    cts = out.get("compressed_tree_string")
+    if isinstance(cts, str) and cts.strip():
+        tree_path = layout.compressed_tree_text_path(stamp=stamp)
+        if not tree_path.is_file():
+            tree_path.write_text(cts, encoding="utf-8")
+        pageindex["path_compressed_tree_text"] = str(tree_path.resolve())
+
+
+def _multimodal_out_json_disk_shape(out: dict[str, object]) -> dict[str, object]:
+    o = {k: v for k, v in out.items() if k not in _MULTIMODAL_TEXT_ONLY_KEYS}
+    cb = o.get("canonical_bundle")
+    if isinstance(cb, dict):
+        o["canonical_bundle"] = _bundle_json_disk_shape(cb)  # type: ignore[assignment]
+    return o
+
+
+def archive_multimodal_cli_outputs(
+    storage_root: Path,
+    pdf_stem: str,
+    out: dict[str, object],
+    *,
+    stamp: str | None = None,
+    artifact_root: Path | None = None,
+) -> dict[str, Path]:
+    """
+    Write JSON files for one multimodal run (single stamp, one file per role).
+
+    When ``artifact_root`` is set, this is the **only** writer for ``json/`` (coding step writes
+    pickle, ``image/``, and ``text/`` only). Layout matches V3: canonical bundle + unstructured
+    + pageindex.
+
+    Otherwise writes flat files under ``storage_root`` (legacy ``cli/data/legacy``).
+    """
+    import json
+
+    from chunksmith_cli.core.artifact_layout import ensure_artifact_layout
+
+    bundle = out.get("canonical_bundle")
+    if stamp is None and isinstance(bundle, dict):
+        stamp = _stamp_from_canonical_bundle_path(str(bundle.get("path_canonical_bundle_json") or ""))
+    stamp = stamp or cli_archive_stamp()
+
+    pageindex = _multimodal_pageindex_disk_shape(out)
+    out_disk = _multimodal_out_json_disk_shape(out)  # type: ignore[arg-type]
+    paths: dict[str, Path] = {}
+
+    if artifact_root is not None:
+        layout = ensure_artifact_layout(artifact_root, pdf_stem)
+        cb_path = layout.canonical_bundle_json_path(stamp=stamp)
+        uj_path = layout.unstructured_json_path(stamp=stamp)
+        pi_path = layout.pageindex_json_path(stamp=stamp)
+
+        bundle_for_paths = dict(bundle) if isinstance(bundle, dict) else {}
+        _write_multimodal_text_artifacts(
+            layout,
+            stamp=stamp,
+            bundle=bundle_for_paths,
+            out=out,
+            pageindex=pageindex,
+        )
+
+        if isinstance(bundle, dict):
+            cb_path.write_text(
+                json.dumps(_bundle_json_disk_shape(bundle_for_paths), ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+            paths["canonical_bundle"] = cb_path.resolve()
+            uels = bundle.get("unstructured_elements")
+            if isinstance(uels, list) and uels:
+                uj_path.write_text(json.dumps(uels, ensure_ascii=False, indent=2), encoding="utf-8")
+                paths["unstructured_elements"] = uj_path.resolve()
+        pi_path.write_text(json.dumps(pageindex, ensure_ascii=False, indent=2), encoding="utf-8")
+        paths["pageindex"] = pi_path.resolve()
+        paths["artifact_root"] = layout.root.resolve()
+        return paths
+
+    bundle_flat = dict(bundle) if isinstance(bundle, dict) else {}
+    _write_multimodal_text_artifacts_flat(
+        storage_root,
+        pdf_stem,
+        stamp=stamp,
+        bundle=bundle_flat,
+        out=out,
+        pageindex=pageindex,
+    )
+
+    paths["full"] = archive_cli_json_object(storage_root, pdf_stem, out_disk, stamp=stamp)
+    if isinstance(bundle, dict):
+        paths["canonical_bundle"] = archive_cli_json_object(
+            storage_root,
+            pdf_stem,
+            _bundle_json_disk_shape(bundle_flat),  # type: ignore[arg-type]
+            stamp=stamp,
+            suffix="_canonical_bundle",
+        )
+        uels = bundle.get("unstructured_elements")
+        if isinstance(uels, list) and uels:
+            paths["unstructured_elements"] = archive_cli_json_object(
+                storage_root,
+                pdf_stem,
+                uels,
+                stamp=stamp,
+                suffix="_unstructured_elements",
+            )
+    paths["pageindex"] = archive_cli_json_object(
+        storage_root,
+        pdf_stem,
+        pageindex,
+        stamp=stamp,
+        suffix="_pageindex",
+    )
+    return paths
+
+
+def _v3_index_disk_shape(data: dict[str, object]) -> dict[str, object]:
+    """Omit bulky/duplicate fields from saved V3 JSON (``text``, extra page keys, ``image_base64``)."""
+    from chunksmith_v3.outline_tree import (
+        omit_top_level_elements_for_export,
+        redistribute_top_level_elements_to_media,
+        slim_outline_bundle_for_export,
+        strip_redundant_page_fields,
+        strip_text_from_structure,
+    )
+
+    out = dict(data)
+    st = out.get("structure")
+    if isinstance(st, list):
+        out["structure"] = strip_redundant_page_fields(strip_text_from_structure(st))
+    ob = out.get("outline_bundle")
+    if isinstance(ob, dict):
+        out["outline_bundle"] = slim_outline_bundle_for_export(ob)
+    media = out.get("media_by_node")
+    top_els = out.get("elements")
+    if isinstance(media, dict) and isinstance(st, list):
+        needs_media_els = not any(isinstance(nm, dict) and nm.get("elements") for nm in media.values())
+        if needs_media_els:
+            from chunksmith_v3.parsed_document import build_parsed_document_from_elements
+
+            parsed_doc = None
+            artifact_root = out.get("artifact_root")
+            if isinstance(artifact_root, str):
+                json_dir = Path(artifact_root) / "json"
+                if json_dir.is_dir():
+                    uj_candidates = sorted(
+                        json_dir.glob("*_unstructured_elements.json"),
+                        key=lambda p: p.stat().st_mtime,
+                        reverse=True,
+                    )
+                    if uj_candidates:
+                        raw = json.loads(uj_candidates[0].read_text(encoding="utf-8"))
+                        if isinstance(raw, list):
+                            parsed_doc = build_parsed_document_from_elements(
+                                str(out.get("doc_name") or "document.pdf"),
+                                [e for e in raw if isinstance(e, dict)],
+                            )
+            if parsed_doc is None and isinstance(top_els, list) and top_els:
+                parsed_doc = build_parsed_document_from_elements(
+                    str(out.get("doc_name") or "document.pdf"),
+                    [e for e in top_els if isinstance(e, dict)],
+                )
+            if parsed_doc is not None:
+                out["media_by_node"] = redistribute_top_level_elements_to_media(
+                    structure=st,
+                    media_by_node=media,
+                    parsed=parsed_doc,
+                    doc_name=str(out.get("doc_name") or "document.pdf"),
+                )
+    if isinstance(media, dict) or isinstance(out.get("media_by_node"), dict):
+        slim_media: dict[str, object] = {}
+        for nid, nm in (out.get("media_by_node") or media).items():  # type: ignore[union-attr]
+            if not isinstance(nm, dict):
+                continue
+            row = dict(nm)
+            imgs = row.get("images")
+            if isinstance(imgs, list):
+                row["images"] = [
+                    {k: v for k, v in im.items() if k != "image_base64"} if isinstance(im, dict) else im for im in imgs
+                ]
+            slim_media[str(nid)] = row
+        out["media_by_node"] = slim_media
+    return omit_top_level_elements_for_export(out)
+
+
+def archive_v3_cli_outputs(
+    storage_root: Path,
+    pdf_stem: str,
+    index_dict: dict[str, object],
+    *,
+    stamp: str | None = None,
+    artifact_root: Path | None = None,
+) -> dict[str, Path]:
+    """
+    Write JSON for one V3 run (same timestamp).
+
+    When ``artifact_root`` is set, all JSON goes under ``{artifact_root}/json/`` only
+    (``persist_v3_artifacts`` does not write these files).
+
+    Otherwise writes flat files under ``storage_root`` (``cli/data/legacy``).
+    """
+    from chunksmith_cli.core.artifact_layout import ensure_artifact_layout
+
+    stamp = stamp or cli_archive_stamp()
+    slim = _v3_index_disk_shape(index_dict)
+    pageindex = {
+        "doc_name": slim.get("doc_name"),
+        "structure": slim.get("structure"),
+        "doc_description": slim.get("doc_description"),
+        "indexing_mode": slim.get("indexing_mode"),
+    }
+
+    if artifact_root is not None:
+        layout = ensure_artifact_layout(artifact_root, pdf_stem)
+        v3_path = layout.json_dir / f"{pdf_stem}_{stamp}_v3_index.json"
+        pi_path = layout.json_dir / f"{pdf_stem}_{stamp}_pageindex.json"
+        v3_path.write_text(json.dumps(slim, ensure_ascii=False, indent=2), encoding="utf-8")
+        pi_path.write_text(json.dumps(pageindex, ensure_ascii=False, indent=2), encoding="utf-8")
+        return {
+            "v3_index": v3_path.resolve(),
+            "pageindex": pi_path.resolve(),
+            "artifact_root": layout.root.resolve(),
+            "artifact_v3_index": v3_path.resolve(),
+        }
+
+    paths: dict[str, Path] = {
+        "v3_index": archive_cli_json_object(
+            storage_root,
+            pdf_stem,
+            slim,
+            stamp=stamp,
+            suffix="_v3_index",
+        ),
+    }
+    paths["pageindex"] = archive_cli_json_object(
+        storage_root,
+        pdf_stem,
+        pageindex,
+        stamp=stamp,
+        suffix="_pageindex",
+    )
+    return paths
+
+
+def _title_index_disk_shape(data: dict[str, object]) -> dict[str, object]:
+    """Slim title-index JSON for disk (coded string stored separately when large)."""
+    out = dict(data)
+    coded = out.pop("title_coded_formate", None)
+    if coded:
+        out["title_coded_formate_chars"] = len(str(coded))
+    return out
+
+
+def archive_title_cli_outputs(
+    storage_root: Path,
+    pdf_stem: str,
+    index_dict: dict[str, object],
+    *,
+    stamp: str | None = None,
+    artifact_root: Path | None = None,
+) -> dict[str, Path]:
+    """Persist title-indexer run artifacts (index, chunk_nodes, coded text, pageindex)."""
+    import json
+
+    from chunksmith_cli.core.artifact_layout import ensure_artifact_layout
+
+    stamp = stamp or cli_archive_stamp()
+    slim = _title_index_disk_shape(index_dict)
+    pageindex: dict[str, object] = {
+        "doc_name": slim.get("doc_name"),
+        "structure": slim.get("structure"),
+        "doc_description": slim.get("doc_description"),
+        "indexing_mode": slim.get("indexing_mode"),
+    }
+    ob = index_dict.get("outline_bundle")
+    if isinstance(ob, dict) and isinstance(ob.get("pageindex"), dict):
+        pi = ob["pageindex"]
+        for key in ("extraction_warnings", "outline_thinking", "outline_verification"):
+            if key in pi:
+                pageindex[key] = pi[key]
+
+    paths: dict[str, Path] = {}
+    coded = index_dict.get("title_coded_formate")
+    chunk_nodes = index_dict.get("chunk_nodes")
+    elements = index_dict.get("elements")
+
+    if artifact_root is not None:
+        layout = ensure_artifact_layout(artifact_root, pdf_stem)
+        ti_path = layout.json_dir / f"{pdf_stem}_{stamp}_title_index.json"
+        pi_path = layout.pageindex_json_path(stamp=stamp)
+        ti_path.parent.mkdir(parents=True, exist_ok=True)
+        ti_path.write_text(json.dumps(slim, ensure_ascii=False, indent=2), encoding="utf-8")
+        paths["title_index"] = ti_path.resolve()
+        pi_path.write_text(json.dumps(pageindex, ensure_ascii=False, indent=2), encoding="utf-8")
+        paths["pageindex"] = pi_path.resolve()
+        if isinstance(coded, str) and coded:
+            coded_path = layout.text_dir / f"{pdf_stem}_{stamp}_title_coded_formate.txt"
+            coded_path.parent.mkdir(parents=True, exist_ok=True)
+            coded_path.write_text(coded, encoding="utf-8")
+            paths["title_coded_formate"] = coded_path.resolve()
+        if isinstance(chunk_nodes, list):
+            cn_path = layout.json_dir / f"{pdf_stem}_{stamp}_chunk_nodes.json"
+            cn_path.write_text(json.dumps(chunk_nodes, ensure_ascii=False, indent=2), encoding="utf-8")
+            paths["chunk_nodes"] = cn_path.resolve()
+        if isinstance(elements, list) and elements:
+            uj_path = layout.unstructured_json_path(stamp=stamp)
+            uj_path.write_text(json.dumps(elements, ensure_ascii=False, indent=2), encoding="utf-8")
+            paths["unstructured_elements"] = uj_path.resolve()
+        paths["artifact_root"] = layout.root.resolve()
+        return paths
+
+    paths["title_index"] = archive_cli_json_object(storage_root, pdf_stem, slim, stamp=stamp, suffix="_title_index")
+    paths["pageindex"] = archive_cli_json_object(storage_root, pdf_stem, pageindex, stamp=stamp, suffix="_pageindex")
+    if isinstance(coded, str) and coded:
+        text_path = storage_root / f"{pdf_stem}_{stamp}_title_coded_formate.txt"
+        text_path.write_text(coded, encoding="utf-8")
+        paths["title_coded_formate"] = text_path.resolve()
+    if isinstance(chunk_nodes, list):
+        paths["chunk_nodes"] = archive_cli_json_object(
+            storage_root, pdf_stem, chunk_nodes, stamp=stamp, suffix="_chunk_nodes"
+        )
+    if isinstance(elements, list) and elements:
+        paths["unstructured_elements"] = archive_cli_json_object(
+            storage_root, pdf_stem, elements, stamp=stamp, suffix="_unstructured_elements"
+        )
+    return paths
+
+
+def _multi_index_disk_shape(data: dict[str, object]) -> dict[str, object]:
+    """Slim multi-index JSON (coded markup stored as separate text file)."""
+    out = dict(data)
+    if "title_coded_formate_chars" in out:
+        pass
+    for key in ("flat_rows_toon", "structure_toon"):
+        if key in out and len(str(out.get(key) or "")) > 50000:
+            out[key] = f"(omitted on disk — {len(str(data.get(key) or ''))} chars; see run artifacts)"
+    return out
+
+
+def archive_multi_indexing_cli_outputs(
+    storage_root: Path,
+    pdf_stem: str,
+    index_dict: dict[str, object],
+    *,
+    elements: list[dict[str, object]] | None = None,
+    title_coded_formate: str | None = None,
+    title_outline: dict[str, object] | None = None,
+    mapper_output: dict[str, object] | None = None,
+    stamp: str | None = None,
+    artifact_root: Path | None = None,
+) -> dict[str, Path]:
+    """Persist one multi-indexing CLI run (json/, pickle/, image/, text/)."""
+    import json
+
+    from chunksmith_cli.pipelines.multi_indexing_storage import persist_multi_indexing_artifacts
+
+    stamp = stamp or cli_archive_stamp()
+    slim = _multi_index_disk_shape(index_dict)
+    pageindex: dict[str, object] = {
+        "doc_name": slim.get("doc_name"),
+        "structure": slim.get("structure"),
+        "doc_description": slim.get("doc_description"),
+        "llm_context_format": slim.get("llm_context_format"),
+        "indexer_options": slim.get("indexer_options"),
+        "outline_thinking": slim.get("outline_thinking"),
+    }
+    paths: dict[str, Path] = {}
+
+    if artifact_root is not None:
+        binary_paths = persist_multi_indexing_artifacts(
+            artifact_root=artifact_root,
+            pdf_stem=pdf_stem,
+            stamp=stamp,
+            elements=elements,
+            title_coded_formate=title_coded_formate,
+            title_outline=title_outline if isinstance(title_outline, dict) else None,
+        )
+        paths.update(binary_paths)
+        layout_json = artifact_root.resolve() / ARTIFACT_SUBDIR_JSON
+        layout_json.mkdir(parents=True, exist_ok=True)
+        mi_path = layout_json / f"{pdf_stem}_{stamp}_multi_index.json"
+        pi_path = layout_json / f"{pdf_stem}_{stamp}_pageindex.json"
+        if "title_coded_formate" in binary_paths:
+            slim = dict(slim)
+            slim["path_coded_text"] = str(binary_paths["title_coded_formate"])
+        mi_path.write_text(json.dumps(slim, ensure_ascii=False, indent=2), encoding="utf-8")
+        pi_path.write_text(json.dumps(pageindex, ensure_ascii=False, indent=2), encoding="utf-8")
+        paths["multi_index"] = mi_path.resolve()
+        paths["pageindex"] = pi_path.resolve()
+        if isinstance(mapper_output, dict) and mapper_output:
+            mp = layout_json / f"{pdf_stem}_{stamp}_mapper.json"
+            mp.write_text(json.dumps(mapper_output, ensure_ascii=False, indent=2), encoding="utf-8")
+            paths["mapper"] = mp.resolve()
+        return paths
+
+    paths["multi_index"] = archive_cli_json_object(storage_root, pdf_stem, slim, stamp=stamp, suffix="_multi_index")
+    paths["pageindex"] = archive_cli_json_object(storage_root, pdf_stem, pageindex, stamp=stamp, suffix="_pageindex")
+    if isinstance(elements, list) and elements:
+        paths["unstructured_elements"] = archive_cli_json_object(
+            storage_root, pdf_stem, elements, stamp=stamp, suffix="_unstructured_elements"
+        )
+    if isinstance(title_coded_formate, str) and title_coded_formate.strip():
+        coded_path = storage_root / f"{pdf_stem}_{stamp}_title_coded_formate.txt"
+        coded_path.write_text(title_coded_formate, encoding="utf-8")
+        paths["title_coded_formate"] = coded_path.resolve()
+        slim = dict(slim)
+        slim["path_coded_text"] = str(paths["title_coded_formate"])
+        paths["multi_index"].write_text(
+            json.dumps(slim, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+    if isinstance(mapper_output, dict) and mapper_output:
+        paths["mapper"] = archive_cli_json_object(storage_root, pdf_stem, mapper_output, stamp=stamp, suffix="_mapper")
+    return paths
+
+
+def archive_pageindex_cli_outputs(
+    storage_root: Path,
+    pdf_stem: str,
+    outline: dict[str, object],
+    *,
+    stamp: str | None = None,
+    artifact_root: Path | None = None,
+    tagged_pages: str | None = None,
+) -> dict[str, Path]:
+    """Persist a standalone PageIndexer CLI run (pageindex JSON + optional tagged pages text)."""
+    import json
+
+    from chunksmith_cli.core.artifact_layout import ensure_artifact_layout
+
+    stamp = stamp or cli_archive_stamp()
+    pageindex: dict[str, object] = {
+        "doc_name": outline.get("doc_name"),
+        "structure": outline.get("structure"),
+        "doc_description": outline.get("doc_description"),
+        "indexing_mode": "chunksmith_pageindex",
+    }
+    paths: dict[str, Path] = {}
+
+    if artifact_root is not None:
+        layout = ensure_artifact_layout(artifact_root, pdf_stem)
+        pi_path = layout.pageindex_json_path(stamp=stamp)
+        pi_path.write_text(json.dumps(pageindex, ensure_ascii=False, indent=2), encoding="utf-8")
+        paths["pageindex"] = pi_path.resolve()
+        paths["artifact_root"] = layout.root.resolve()
+        if isinstance(tagged_pages, str) and tagged_pages.strip():
+            tagged_path = layout.text_dir / f"{pdf_stem}_{stamp}_tagged_pages.txt"
+            tagged_path.write_text(tagged_pages, encoding="utf-8")
+            paths["tagged_pages"] = tagged_path.resolve()
+        return paths
+
+    paths["pageindex"] = archive_cli_json_object(storage_root, pdf_stem, pageindex, stamp=stamp, suffix="_pageindex")
+    if isinstance(tagged_pages, str) and tagged_pages.strip():
+        text_path = storage_root / f"{pdf_stem}_{stamp}_tagged_pages.txt"
+        text_path.write_text(tagged_pages, encoding="utf-8")
+        paths["tagged_pages"] = text_path.resolve()
+    return paths