openmd-cli 0.1.0__py3-none-any.whl

openmd/interactive.py

@@ -0,0 +1,453 @@
+"""Single-link workflow with human prompts and a flat Markdown destination."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import json
+import re
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from uuid import uuid4
+
+from openmd.core.filename import safe_filename
+from openmd.core.package_validator import validate_package_or_raise
+from openmd.core.preferences import data_directory, load_preferences, save_preferences
+from openmd.core.secrets import sanitize_error_summary
+from openmd.runtime.tempdirs import owned_mkdtemp
+
+
+_GATE_OPTIONS = {"network": "enable_network_backends", "browser": "enable_browser_backends", "media_download": "enable_media_download", "asr": "enable_asr"}
+_GATE_LABELS = {"network": "读取公开网络", "browser": "使用浏览器读取", "media_download": "必要时下载媒体", "asr": "在本机转录", "cloud": "已明确允许的云服务"}
+
+
+def is_interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _ask(message: str) -> str:
+    return input(message).strip()
+
+
+def _say(args: argparse.Namespace, message: str) -> None:
+    print(message, file=sys.stderr if getattr(args, "json", False) else sys.stdout)
+
+
+def _prompt(args: argparse.Namespace, message: str) -> str:
+    if getattr(args, "json", False):
+        print(message, file=sys.stderr, end="", flush=True)
+        return _ask("")
+    return _ask(message)
+
+
+def display_backend(name: object) -> str:
+    """User-facing route name: the built-in browser reader is part of Openmd."""
+    text = str(name or "")
+    return "browser." + text[len("opencli."):] if text.startswith("opencli.") else text
+
+
+def _preview(args: argparse.Namespace, url: str) -> None:
+    if not getattr(args, "verbose", False):
+        return
+    from openmd.adapters.registry import create_default_registry
+    from openmd.core.detector import detect_platform
+    source = detect_platform(url)
+    chain = create_default_registry().backend_chain(source, args.backend)
+    _say(args, f"来源：{source}；候选工具：{' → '.join(display_backend(b) for b in chain)}")
+
+
+def _authorize(args: argparse.Namespace, url: str, *, tty: bool) -> bool:
+    # Open-source ease of use (user decision 2026-11-15): a non-interactive run
+    # that names a destination gets the same daily gates as the terminal flow.
+    # Explicit capability flags stay a narrow grant; cloud is never implied.
+    _preview(args, url)
+    explicit = [gate for gate, option in _GATE_OPTIONS.items() if getattr(args, option, False)]
+    if getattr(args, "enable_cloud_backends", False):
+        explicit.append("cloud")
+    if explicit:
+        # Explicit flags are the user's narrow grant; typing them is the confirmation.
+        return True
+    from openmd.adapters.registry import create_default_registry
+    from openmd.core.detector import detect_platform
+    from openmd.routing.loader import load_catalog
+    catalog = load_catalog()
+    chain = create_default_registry().backend_chain(detect_platform(url), args.backend)
+    needed = {gate for backend in chain for gate in catalog.capabilities.get(backend, {}).get("gates", [])}
+    # Daily interactive use (user decision 2026-11-07): public network, browser session reads,
+    # media download and local ASR start without any prompt. Cloud is never implied.
+    if getattr(args, "video", "note") in {"text", "file"}:
+        needed |= {"network", "media_download", "asr"}  # asking for the video text is the grant
+    requested = [gate for gate in ("network", "browser", "media_download", "asr") if gate in needed]
+    for gate in requested:
+        setattr(args, _GATE_OPTIONS[gate], True)
+    return True
+
+
+def _noninteractive_requirements(args: argparse.Namespace, url: str) -> str | None:
+    if args.save_to or args.out:
+        return None
+    return f"非交互运行需要保存目录（-o 或 --save-to），例如：\nopenmd {url} -o <目录>"
+
+
+class _StagingWorkspace:
+    def __init__(self) -> None:
+        self.path = Path(owned_mkdtemp(prefix="openmd-staging-"))
+        self.keep = False
+
+    def __enter__(self) -> Path:
+        return self.path
+
+    def __exit__(self, *_exc) -> None:
+        if not self.keep:
+            shutil.rmtree(self.path)
+
+
+def _relocate_references(root: Path, old_root: Path, new_root: Path, *, published: dict[Path, Path] | None = None, drop_unpublished: bool = False) -> None:
+    """Rewrite only structured local pointers, never source Markdown prose."""
+    old = str(old_root)
+    mapping = {str(before): str(after) for before, after in (published or {}).items()}
+
+    def mapped(text: str) -> str | None:
+        for before, after in mapping.items():
+            if text == before:
+                return after
+            for separator in ("\\", "/"):
+                if text.startswith(before + separator):
+                    return after + text[len(before):]
+        return None
+
+    def transform(value: object, *, key: str = "") -> object:
+        if isinstance(value, str):
+            replacement = mapped(value)
+            if replacement is not None:
+                return replacement
+            if key in {"artifact_ref", "output_path"} and not Path(value).is_absolute():
+                replacement = mapped(str(old_root / value))
+                if replacement is not None:
+                    return replacement
+                if drop_unpublished and (old_root / value).exists():
+                    return None
+            if value == old:
+                return str(new_root)
+            for prefix in (old + "\\", old + "/"):
+                if value.startswith(prefix):
+                    if key in {"artifact_ref", "output_path"} and drop_unpublished and not published:
+                        return None
+                    return str(new_root) + value[len(old):]
+            return value
+        if isinstance(value, list):
+            return [transform(v, key=key) for v in value]
+        if isinstance(value, dict):
+            return {k: transform(v, key=k) for k, v in value.items()}
+        return value
+
+    for path in root.rglob("*"):
+        if path.suffix == ".json":
+            value = json.loads(path.read_text(encoding="utf-8"))
+            path.write_text(json.dumps(transform(value), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        elif path.suffix == ".jsonl":
+            values = [transform(json.loads(line)) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+            path.write_text("".join(json.dumps(v, ensure_ascii=False) + "\n" for v in values), encoding="utf-8")
+
+
+def _preserve_records(stage: Path, *, published: dict[Path, Path] | None = None) -> Path:
+    target = data_directory() / "runs" / uuid4().hex
+    target.mkdir(parents=True, exist_ok=False)
+    if (stage / "runlog.jsonl").is_file():
+        shutil.copyfile(stage / "runlog.jsonl", target / "runlog.jsonl")
+    if (stage / "runs").is_dir():
+        shutil.copytree(stage / "runs", target / "runs")
+    # These directories only exist when the caller explicitly retained media.
+    for name in ("raw-media", "raw"):
+        if (stage / name).is_dir():
+            shutil.copytree(stage / name, target / name)
+    _relocate_references(target, stage, target, published=published, drop_unpublished=True)
+    return target
+
+
+def _preserve_failure_log(stage: Path) -> Path | None:
+    if not (stage / "runlog.jsonl").is_file():
+        return None
+    return _preserve_records(stage) / "runlog.jsonl"
+
+
+def _daily_filename(title: str) -> str:
+    value = safe_filename(title, max_length=100)
+    if re.fullmatch(r"(?:CON|PRN|AUX|NUL|COM[1-9¹²³]|LPT[1-9¹²³])", value.split(".", 1)[0], re.I):
+        value = "_" + value
+    return value
+
+
+def _save(stage: Path, destination: Path, *, title: str, package: bool = False, source: Path | None = None) -> Path:
+    destination = destination.expanduser().resolve()
+    if destination.exists() and not destination.is_dir():
+        raise ValueError("save_directory_required: 请输入保存文件夹")
+    destination.mkdir(parents=True, exist_ok=True)
+    if package:
+        target = destination / f"{_daily_filename(title)}-{uuid4().hex[:8]}"
+
+        def ignore_records(directory: str, names: list[str]) -> list[str]:
+            if Path(directory) == stage:
+                return [name for name in names if name in {".openmd-compact.lock", ".openmd-compact.guard", ".openmd-owner.json", "runlog.jsonl", "runs"}]
+            return []
+
+        shutil.copytree(stage, target, ignore=ignore_records)
+        _relocate_references(target, stage, target)
+        for path in target.rglob("*.openmd"):
+            validate_package_or_raise(path)
+        return target
+    if source is None:
+        matches = list(stage.rglob("*.md"))
+        if len(matches) != 1:
+            raise ValueError("go_single_markdown_required: 本次产生多份文件，请显式选择 --package 保存")
+        source = matches[0]
+    if source.suffix != ".md" or not source.resolve().is_relative_to(stage.resolve()):
+        raise ValueError("go_single_markdown_required: 未找到本次提取的 Markdown")
+    base = _daily_filename(title)
+    for attempt in range(100):
+        target = destination / f"{base}{'-' + uuid4().hex[:6] if attempt else ''}.md"
+        try:
+            handle = target.open("xb")
+        except FileExistsError:
+            continue
+        try:
+            with handle:
+                assets = source.parent / "assets"
+                if assets.is_dir():
+                    asset_target = destination / f"{target.stem}.assets-{uuid4().hex[:6]}"
+                    shutil.copytree(assets, asset_target)
+                    text = source.read_text(encoding="utf-8")
+                    text = re.sub(r"(!\[[^\]]*\]\(<?)assets/", lambda m: m.group(1) + asset_target.name + "/", text)
+                    handle.write(text.encode("utf-8"))
+                else:
+                    with source.open("rb") as original:
+                        shutil.copyfileobj(original, handle)
+            return target
+        except BaseException:
+            target.unlink(missing_ok=True)
+            raise
+    raise OSError("save_name_collision: 无法分配新文件名，请换一个保存目录")
+
+
+def _source_summary(stage: Path, result) -> tuple[str, list[dict[str, object]]]:
+    from openmd.core.renderer import source_level_label
+
+    runlog = stage / "runlog.jsonl"
+    rows = [json.loads(line) for line in runlog.read_text(encoding="utf-8").splitlines() if line.strip()] if runlog.is_file() else []
+    levels = [str(row["source_level"]) for row in rows if row.get("event_type") == "item" and row.get("source_level")]
+    if not levels:
+        levels = list(result.source_level_counts)
+    labels = list(dict.fromkeys(source_level_label(level) for level in levels))
+    return " / ".join(labels), rows
+
+
+def _failure_hint(rows: list[dict[str, object]]) -> str:
+    codes = " ".join(str(row.get("error_code") or "") for row in rows).lower()
+    if "browser_challenge_page" in codes:
+        return "被站点验证页拦截，未取得目标正文；请在浏览器中确认原链接可访问后重试。"
+    if "weixin_error_page" in codes:
+        return "公众号返回了错误页（链接失效、已删除或已过期），没有正文；请在微信或浏览器中打开确认。"
+    if "content_navigation_shell" in codes:
+        return "页面只有导航或图片，没有正文；链接可能不存在（软 404）或需要登录，请在浏览器中打开确认。"
+    attempts = [a for row in rows if isinstance(row.get("route_trace"), dict) for a in row["route_trace"].get("fallback_attempts") or []]
+    opencli_missing = any(str(a.get("backend", "")).startswith("opencli.") and a.get("error_code") in {"backend_exit_127", "backend_not_found"} for a in attempts)
+    content_verdict = any(word in codes for word in ("weixin_error_page", "not_found", "404"))
+    if opencli_missing and not content_verdict:
+        return "这个链接要用浏览器读取组件，但自动准备没有成功；检查网络（或设置 OPENMD_NPM_REGISTRY 使用 npm 镜像）后重试，运行 openmd doctor 查看详情。"
+    opencli_codes = {str(a.get("error_code")) for a in attempts if str(a.get("backend", "")).startswith("opencli.")}
+    if "backend_exit_69" in opencli_codes and not content_verdict:
+        return "这个链接要借用浏览器读取：请先运行 openmd browser-setup 装好 Openmd 浏览器插件，保持 Chrome / Edge 打开后重试。"
+    if "backend_exit_77" in opencli_codes and not content_verdict:
+        return "这个链接需要登录：请先在 Chrome / Edge 里登录该网站，再重试。"
+    if any(word in codes for word in ("model_missing", "asr_model", "worker")):
+        return "本机转录环境或模型尚未就绪；运行 openmd doctor --profile media 查看缺项。"
+    if any(word in codes for word in ("auth", "login", "cookie", "browser", "permission")):
+        return "当前读取方式需要浏览器或现有登录状态；确认浏览器可访问原链接后重试。"
+    if "backend_not_implemented" in codes:
+        return "当前读取路线尚未实现；可加 --verbose 查看具体路线。"
+    if any(word in codes for word in ("dependency", "not_installed", "not_registered")):
+        return "所需工具尚未就绪；运行 openmd doctor --profile tools 查看缺项。"
+    if any(word in codes for word in ("timeout", "network", "connection")):
+        return "连接超时或网络不可达；确认原链接可以打开后重试。"
+    return "没有取得可保存的正文；可加 --verbose 查看具体工具错误，或确认原链接能正常打开。"
+
+
+def issue_context(url: str, rows: list[dict[str, object]]) -> str:
+    """One pasteable line for the "链接提取失败" issue form; no paths, no secrets."""
+    import platform as host
+
+    from openmd import __version__
+    from openmd.core.detector import detect_platform
+
+    tried = []
+    for row in rows:
+        attempts = (row.get("route_trace") or {}).get("fallback_attempts") if isinstance(row.get("route_trace"), dict) else None
+        if attempts:
+            tried += [f"{display_backend(a.get('backend'))}={a.get('error_code')}" for a in attempts]
+        elif row.get("event_type") == "item" or row.get("error_code"):
+            tried.append(f"{display_backend(row.get('backend'))}={row.get('error_code') or row.get('status')}")
+    # Sanitize each attempt: one joined string would hit the summary length cap and lose the tail.
+    route = ", ".join(dict.fromkeys(str(sanitize_error_summary(part)) for part in tried)) or "无工具记录"
+    return f"openmd {__version__} · {host.system()} {host.release()} · Python {host.python_version()} · 平台 {detect_platform(url)} · {route}"
+
+
+def _emit_saved(args: argparse.Namespace, *, target: Path, outputs: list[str], records: Path | None) -> None:
+    if getattr(args, "json", False):
+        print(json.dumps({"ok": True, "command": "go", "saved_to": str(target), "outputs": outputs, "records": str(records) if records else None}, ensure_ascii=True))
+    else:
+        print(f"已保存：{target}")
+        if getattr(args, "verbose", False) and records:
+            print(f"运行记录：{records}")
+
+
+def _attach_video(args: argparse.Namespace, url: str, markdown: Path) -> None:
+    from openmd.post_video import append_video_section, applies_to
+
+    mode = getattr(args, "video", "note") or "note"
+    if not applies_to(url) or not getattr(args, "enable_network_backends", False):
+        return
+    if mode in {"text", "file"} and not (getattr(args, "enable_media_download", False) and getattr(args, "enable_asr", False)):
+        mode = "note"  # video text needs explicit media download plus local ASR
+    if mode != "note":
+        _say(args, "正在处理帖子里的视频（下载音频并在本机转文字）…")
+    try:
+        append_video_section(markdown, url, mode)
+    except OSError as exc:
+        print(f"视频部分未完成：{sanitize_error_summary(exc)}", file=sys.stderr)
+
+
+def cmd_go(args: argparse.Namespace) -> int:
+    from openmd.cli import _emit_result, _process_input, _start_compact_receipt
+    tty = is_interactive()
+    if any(getattr(args, option, False) for option in ("all", "overwrite", "update", "new_version")) or args.package_root:
+        print("openmd go: 批量与更新操作请使用 ingest/batch/collect 及明确输出目录", file=sys.stderr)
+        return 2
+    try:
+        url = args.url or (_prompt(args, "输入链接或本地文件：") if tty else "")
+        if url == "-":
+            if tty:
+                print("openmd go: 请直接粘贴链接", file=sys.stderr)
+                return 2
+            url = sys.stdin.readline().strip()
+        if not url:
+            print("openmd go: 需要一个链接或本地文件", file=sys.stderr)
+            return 2
+        from openmd.core.input_validation import INPUT_HINT, network_preflight, valid_daily_input
+
+        if not valid_daily_input(url):
+            print(INPUT_HINT, file=sys.stderr)
+            return 2
+        if not tty:
+            requirements = _noninteractive_requirements(args, url)
+            if requirements:
+                print(requirements, file=sys.stderr)
+                return 2
+        if not _authorize(args, url, tty=tty):
+            _say(args, "已取消。")
+            return 0
+        if args.backend != "mock" and getattr(args, "enable_network_backends", False) and url.startswith(("http://", "https://")):
+            failure = network_preflight(url)
+            if failure:
+                print(failure, file=sys.stderr)
+                return 1
+        workspace = _StagingWorkspace()
+        with workspace as temporary:
+            stage = Path(temporary)
+            requested_destination = args.save_to or args.out
+            run_args = argparse.Namespace(**vars(args))
+            run_args.out = str(stage)
+            run_args.url = url
+            run_args.package_root = None
+            run_args.runlog = None
+            run_args.command = "go"
+            start_error = _start_compact_receipt(run_args, "go")
+            if start_error:
+                raise ValueError(start_error)
+            try:
+                result = _process_input(url, run_args, command="go")
+                if run_args.receipt:
+                    with contextlib.redirect_stdout(io.StringIO()):
+                        receipt_code = _emit_result(run_args, result)
+                    if receipt_code and result.ok:
+                        raise ValueError("go_receipt_failed")
+                source_label, rows = _source_summary(stage, result)
+                if not result.ok or not result.outputs:
+                    print(f"处理失败：{_failure_hint(rows)}", file=sys.stderr)
+                    print(f"提 issue 请附上：{issue_context(url, rows)}", file=sys.stderr)
+                    if getattr(args, "verbose", False):
+                        for row in rows[-3:]:
+                            print(f"{display_backend(row.get('backend'))}: {row.get('error_code')}；{sanitize_error_summary(row.get('error_summary'))}", file=sys.stderr)
+                    retained = _preserve_failure_log(stage)
+                    if retained:
+                        print(f"错误记录：{retained}", file=sys.stderr)
+                    if getattr(args, "json", False):
+                        print(json.dumps({"ok": False, "command": "go", "error": sanitize_error_summary(result.message) or "extraction_failed", "records": str(retained) if retained else None}, ensure_ascii=True))
+                    return 1
+                for output in result.outputs:
+                    if Path(output).is_dir():
+                        validate_package_or_raise(Path(output))
+                first = Path(result.outputs[0])
+                if not args.package and len(result.outputs) != 1:
+                    workspace.keep = True
+                    raise ValueError(f"go_single_markdown_required: 本次产生多份文件；请使用 --package。已提取产物保留在：{stage}")
+                title = first.stem
+                if first.is_dir():
+                    meta = json.loads((first / "metadata.json").read_text(encoding="utf-8"))
+                    title = str(meta.get("title") or title)
+                if not args.package and first.suffix == ".md":
+                    _attach_video(args, url, first)
+                label = "已取得部分正文" if any(row.get("status") == "partial" for row in rows) else "已取得正文"
+                _say(args, f"{label}：{title}" + (f"；来源：{source_label}" if source_label else ""))
+                if getattr(args, "verbose", False):
+                    tools = ", ".join(dict.fromkeys(display_backend(row["backend"]) for row in rows if row.get("backend")))
+                    _say(args, f"工具：{tools}")
+                default_destination = str(load_preferences().get("last_save_directory") or Path.cwd() / "out")
+                destination_text = requested_destination
+                while True:
+                    if destination_text is None:
+                        destination_text = _prompt(args, f"保存在哪里？[回车用 {default_destination}；n 取消] ") or default_destination
+                    if destination_text.lower() in {"n", "no", "取消"}:
+                        _preserve_records(stage)
+                        _say(args, "已取消保存。")
+                        return 0
+                    try:
+                        destination = Path(destination_text.strip().strip('"')).expanduser().resolve()
+                        target = _save(stage, destination, title=title, package=args.package, source=None if args.package else first)
+                        break
+                    except (OSError, ValueError) as exc:
+                        if not tty or requested_destination:
+                            workspace.keep = True
+                            print(f"保存未完成，已提取产物保留在：{stage}", file=sys.stderr)
+                            raise
+                        print(f"保存失败：{sanitize_error_summary(exc)}", file=sys.stderr)
+                        destination_text = None
+                published = {Path(p): target / Path(p).relative_to(stage) if args.package else target for p in result.outputs}
+                outputs = [str(published[Path(p)]) for p in result.outputs]
+                records = None
+                try:
+                    records = _preserve_records(stage, published=published)
+                except (OSError, ValueError) as exc:
+                    workspace.keep = True
+                    print(f"正文已保存；运行记录暂留：{stage}（{sanitize_error_summary(exc)}）", file=sys.stderr)
+                if tty:
+                    try:
+                        save_preferences(last_save_directory=destination)
+                    except OSError as exc:
+                        print(f"正文已保存；未能记住保存目录：{sanitize_error_summary(exc)}", file=sys.stderr)
+                _emit_saved(args, target=target, outputs=outputs, records=records)
+                return 0
+            finally:
+                lock = getattr(run_args, "_compact_output_lock", None)
+                if lock is not None:
+                    lock.release()
+    except (EOFError, KeyboardInterrupt):
+        print("已取消。", file=sys.stderr)
+        return 130
+    except (OSError, ValueError) as exc:
+        print(f"openmd go: {sanitize_error_summary(exc)}", file=sys.stderr)
+        if getattr(args, "json", False):
+            print(json.dumps({"ok": False, "command": "go", "error": sanitize_error_summary(exc)}, ensure_ascii=True))
+        return 1

openmd/ocr/__init__.py

@@ -0,0 +1 @@
+"""Optional local OCR routing, with no import-time inference or downloads."""

openmd/ocr/breakers.py

@@ -0,0 +1,84 @@
+"""Image-only capacity and repetition checks, ported from the approved T2 run.
+
+No reference answer is read here. These checks detect loops and excess length,
+not isolated hallucinations, omissions or numeric errors.
+"""
+
+from __future__ import annotations
+
+import re
+import html
+
+
+def normalize_for_breaker(text: str) -> str:
+    # HTML table syntax/image placeholders are not visible characters. Counting
+    # tags against a pixel text budget falsely trips layout-crop fallback pages.
+    text = html.unescape(re.sub(r"<[^>]+>", " ", text))
+    text = re.sub(r"```.*?```", " ", text, flags=re.S)
+    text = re.sub(r"\s+", " ", text)
+    return re.sub(r"[#*_`|>$-]", "", text).strip()
+
+
+def formula_like(text: str) -> bool:
+    raw = text.strip()
+    if not raw:
+        return True
+    # Formula-only fragments are exempt; prose containing a formula is not.
+    prose = re.sub(r"\$\$.*?\$\$|\$[^$]*\$|\\\[.*?\\\]|\\\(.*?\\\)", "", raw, flags=re.S)
+    if len(re.findall(r"[\u3400-\u9fffA-Za-z]", prose)) >= 15 and prose != raw:
+        return False
+    if re.search(r"\\(?:frac|sum|int|sqrt|left|right|begin|end|mathbf|mathrm|cdot|times)|\$|\\\[|\\\(", raw):
+        return True
+    han = len(re.findall(r"[\u3400-\u9fff]", raw))
+    letters = len(re.findall(r"[A-Za-z]", raw))
+    operators = len(re.findall(r"[=+*/^_{}<>∑∫√×÷±]|\.\.\.|…", raw))
+    digits = len(re.findall(r"\d", raw))
+    if han == 0 and (operators >= 1 or digits >= 2) and len(raw) <= 160 and letters <= max(8, 2 * (operators + digits)):
+        return True
+    return han <= 2 and operators >= 2 and (operators + digits) >= max(3, letters // 2)
+
+
+def repetition_trip(text: str, config: dict) -> dict | None:
+    # Remove fenced/math-only blocks before splitting sentences.
+    clean = re.sub(r"```.*?```|\$\$.*?\$\$|\\\[.*?\\\]", " ", text, flags=re.S)
+    counts: dict[str, int] = {}
+    for piece in re.split(r"[。！？!?\n]|(?<=[a-z0-9])\.\s+", clean):
+        norm = normalize_for_breaker(piece)
+        if len(norm) < config["repeat_min_chars"] or formula_like(piece):
+            continue
+        counts[norm] = counts.get(norm, 0) + 1
+        if counts[norm] >= config["repeat_count"]:
+            # No recognized text enters a receipt (especially for private L3).
+            return {"rule": "repeat_sentence", "count": counts[norm], "chars": len(norm)}
+    return None
+
+
+def estimate_expected_chars(image, config: dict) -> dict:
+    import numpy as np
+    from PIL import Image, ImageOps
+
+    probe = image.copy()
+    probe.thumbnail((1400, 1400), Image.Resampling.LANCZOS)
+    dark = np.asarray(ImageOps.grayscale(probe), dtype=np.uint8) < 220
+    active = dark.mean(axis=1) > 0.012
+    bands, in_band = 0, False
+    for value in active:
+        if value and not in_band:
+            bands += 1
+        in_band = bool(value)
+    bands = bands or max(1, round(probe.height / 80))
+    width_chars = max(24, min(180, round(probe.width / 13)))
+    density = float(dark.mean())
+    density_factor = max(0.65, min(1.8, density / 0.055))
+    estimated = int(max(256, min(120000, bands * width_chars * density_factor * 1.75)))
+    return {"estimated_chars": estimated, "ink_rows": bands, "probe_size": list(probe.size), "ink_fraction": round(density, 5), "max_length_chars": int(estimated * config["length_multiplier"])}
+
+
+def breaker_reason(text: str, budget: dict, config: dict) -> dict | None:
+    repeated = repetition_trip(text, config)
+    if repeated:
+        return repeated
+    length = len(normalize_for_breaker(text))
+    if length > budget["max_length_chars"]:
+        return {"rule": "length_gt_image_estimate", "observed_chars": length, "estimated_chars": budget["estimated_chars"], "multiplier": config["length_multiplier"]}
+    return None

openmd/ocr/config.py

@@ -0,0 +1,54 @@
+"""One validated configuration for providers, workers and diagnostics."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+from importlib.resources import files
+from pathlib import Path
+
+from openmd.core.local_config import load_local_config
+
+from .endpoint import validate_ollama_url
+
+
+def settings() -> dict:
+    value = json.loads(files("openmd.ocr").joinpath("settings.json").read_text(encoding="utf-8"))
+    local = load_local_config()
+    overrides = local.get("ocr", {})
+    if not isinstance(overrides, dict) or set(overrides) - set(value):
+        raise ValueError("local_config_ocr_invalid")
+    value.update(overrides)
+    value["ovis_model"] = os.getenv("OPENMD_OCR_OVIS_MODEL") or value["ovis_model"]
+    value["minicpm_model"] = os.getenv("OPENMD_OCR_MINICPM_MODEL") or value["minicpm_model"]
+    for key, item in value.items():
+        if key.endswith("_model"):
+            if not isinstance(item, str) or not item.strip() or any(ord(c) < 32 for c in item):
+                raise ValueError(f"ocr_setting_invalid: {key}")
+        elif isinstance(item, bool) or not isinstance(item, (int, float)) or not math.isfinite(item) or item <= 0:
+            raise ValueError(f"ocr_setting_invalid: {key}")
+    for key in ("repeat_min_chars", "repeat_count", "num_predict", "num_ctx", "max_pixels", "tile_height", "pdf_dpi", "textlayer_min_chars", "office_sparse_chars"):
+        if not isinstance(value[key], int):
+            raise ValueError(f"ocr_setting_integer_required: {key}")
+    if not 0 < value["tile_overlap"] < 0.5 or not 0 < value["tile_search"] < 0.5:
+        raise ValueError("ocr_tile_settings_invalid")
+    if any(not 0 < value[key] <= 1 for key in ("layout_threshold", "textlayer_min_printable", "textlayer_image_coverage", "textlayer_hidden_ratio", "textlayer_background_delta")):
+        raise ValueError("ocr_ratio_setting_invalid")
+    url = (os.getenv("OPENMD_OLLAMA_URL") or local.get("ollama_url") or "http://127.0.0.1:11434").rstrip("/")
+    value["ollama_url"] = validate_ollama_url(url)
+    return value
+
+
+def layout_runtime() -> tuple[Path | None, Path | None]:
+    local = load_local_config()
+    python_value = os.getenv("OPENMD_OCR_PYTHON") or local.get("ocr_python")
+    python = Path(python_value).expanduser().resolve() if python_value else None
+    explicit = os.getenv("OPENMD_OCR_LAYOUT_MODEL")
+    if explicit:
+        candidates = [Path(explicit).expanduser()]
+    else:
+        roots = [*(Path(p).expanduser() for p in os.getenv("OPENMD_MODEL_ROOTS", "").split(os.pathsep) if p), *(Path(p).expanduser() for p in local.get("model_roots", []))]
+        candidates = [p for root in roots for p in (root / "layout", root / "PP-DocLayoutV3", root / "PaddlePaddle/PP-DocLayoutV3", root)]
+    model = next((p.resolve() for p in candidates if (p / "config.json").is_file() and any(p.glob("*.safetensors"))), None)
+    return python if python and python.is_file() else None, model