pdf2md-tool 0.8.0__py3-none-any.whl

pdf2md/__init__.py

@@ -0,0 +1,8 @@
+"""pdf2md — conversor PDF→Markdown CPU-first com roteamento por intent.
+
+Núcleo CPU (pdftotext/PyMuPDF) offline e determinístico; capacidades pesadas
+(marker/GPU, pix2tex, OCR, VLM) são opcionais e detectadas em runtime via
+`pdf2md doctor`. CLI em `pdf2md.cli:app`.
+"""
+
+__version__ = "0.8.0"

pdf2md/_pix2tex_runner.py

@@ -0,0 +1,45 @@
+"""Runner standalone de pix2tex — executado pelo python de um venv EXTERNO (torch).
+
+NÃO importa pdf2md (o venv externo não tem o pacote). Só pix2tex + PIL + stdlib.
+O executor (pdf2md.executor) cropa as fórmulas no venv geral e chama:
+
+    <pix2tex_python> _pix2tex_runner.py <crop_dir> <out_json>
+
+Lê todos os PNGs de <crop_dir>, roda LatexOCR e escreve {filename: latex} em
+<out_json>. Mantém o torch fora do venv geral (ver feedback_venv_efemero_para_labs).
+"""
+import json
+import sys
+from pathlib import Path
+
+
+def main(argv) -> int:
+    if len(argv) != 2:
+        print("uso: _pix2tex_runner.py <crop_dir> <out_json>", file=sys.stderr)
+        return 2
+    crop_dir, out_json = Path(argv[0]), Path(argv[1])
+    crops = sorted(crop_dir.glob("*.png"))
+    if not crops:
+        out_json.write_text("{}", encoding="utf-8")
+        return 0
+    try:
+        from PIL import Image
+        from pix2tex.cli import LatexOCR
+    except ImportError as e:
+        print(f"[ERRO] runtime pix2tex ausente: {e}", file=sys.stderr)
+        return 3
+
+    model = LatexOCR()
+    out = {}
+    for png in crops:
+        try:
+            out[png.name] = model(Image.open(png))
+        except Exception as e:                       # uma fórmula ruim não derruba o lote
+            out[png.name] = ""
+            print(f"[warn] {png.name}: {e}", file=sys.stderr)
+    out_json.write_text(json.dumps(out, ensure_ascii=False, indent=2), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

pdf2md/_profiles.py

@@ -0,0 +1,130 @@
+"""Índice machine-readable dos perfis ativos — subconjunto *route-relevant*.
+
+Espelha o padrão de `corpus/registry.py` (dict Python puro, sem dependência):
+a fonte-de-verdade HUMANA são os YAML em `docs/profiles/ativo/`; este módulo é o
+recorte que o roteador (`pdf2md/routing.py`) consulta. Decisão registrada em
+T090 (decisão #1) — pyyaml não é dependência declarada, então não parseamos YAML
+em runtime.
+
+Campos por perfil:
+- role:        PRIMARY (extrator full-doc) | REFINER (recorte) | OPTIMIZER
+- hardware:    "cpu" | "gpu-required" | "gpu-optional"
+- needs:       requisitos externos além de hardware (ex. "marker_bin", "ollama")
+- granularity: "documento" | "recorte"
+- unit_speed_s + unit: custo medido por unidade (pg / formula / img)
+- vram_mb:     pico de VRAM medido (0 = CPU)
+- scan:        capacidade em scan — "none" | "printed" (Tesseract CPU) | "ocr-gpu" (Surya)
+- wins:        dimensões vencidas (do perfil)
+- measured_in: labs de origem
+
+Mantido em sincronia manual com docs/profiles/ativo/*.yaml. Se divergir, o YAML
+manda (é a fonte humana); atualizar aqui ao promover/remensurar um perfil.
+"""
+from __future__ import annotations
+
+PRIMARY = "PRIMARY"
+REFINER = "REFINER"
+OPTIMIZER = "OPTIMIZER"
+
+PROFILES: dict[str, dict] = {
+    # ---- PRIMARY (extrator full-doc; escolher 1) --------------------------
+    "marker": {
+        "role": PRIMARY,
+        "hardware": "gpu-required",
+        "needs": ["marker_bin"],
+        "granularity": "documento",
+        "unit_speed_s": 12.9, "unit": "pg",
+        "vram_mb": 3400, "ram_mb": 1500, "cold_s": 30,
+        "scan": "ocr-gpu",          # Surya OCR (único OCR full-doc; GPU)
+        "math": "nativo",           # Texify: math_display/inline forte
+        "wins": ["prose", "math", "livro", "paper", "riqueza", "estabilidade"],
+        "measured_in": ["e00", "e14"],
+    },
+    "pdftotext": {
+        "role": PRIMARY,
+        "hardware": "cpu",
+        "needs": [],
+        "granularity": "documento",
+        "unit_speed_s": 0.0205, "unit": "pg",
+        "vram_mb": 0, "ram_mb": 63, "cold_s": 0.1,
+        "scan": "none",             # text-layer only; scan vai p/ tesseract
+        "math": "cru",              # Unicode cru, sem LaTeX
+        "wins": ["velocidade", "ram", "offline", "alucinacao", "determinismo", "estabilidade"],
+        "measured_in": ["e19"],
+    },
+    "tesseract": {
+        "role": PRIMARY,
+        "hardware": "cpu",
+        "needs": ["tesseract_bin"],
+        "granularity": "documento",
+        "unit_speed_s": 2.74, "unit": "pg",  # @300dpi, e20
+        "vram_mb": 0, "ram_mb": 124, "cold_s": 0.5,
+        "scan": "printed",          # OCR CPU p/ scan impresso (e20 WER 0.052)
+        "math": "cru",
+        "wins": ["scan_cpu", "alucinacao", "determinismo", "offline"],
+        "measured_in": ["e20"],
+        "note": "scan impresso forte; manuscrito falha (honesto, sem alucinar).",
+    },
+
+    # ---- REFINER (recorte, componível) ------------------------------------
+    "pix2tex": {
+        "role": REFINER,
+        "hardware": "cpu",
+        "needs": ["pix2tex_runtime"],   # cropper agora é built-in (formula_cropper, e21);
+                                        # só falta o runtime torch (externo, venv próprio)
+        "granularity": "recorte",
+        "unit_speed_s": 6.5, "unit": "formula",
+        "vram_mb": 0, "ram_mb": 800, "cold_s": 11.9,
+        "refines": "math_display",
+        "math_quality": {"display_linha_unica": 0.80, "matriz": 0.50},  # e21 (N=6 / N=3)
+        "wins": ["math_semantico", "alucinacao", "offline", "cpu"],
+        "measured_in": ["e18", "e21"],
+        "note": "cropper CPU resolvido (e21); fronteira: linha-única 0.80, matriz 0.50.",
+    },
+    "gemma3-4b-small-image": {
+        "role": REFINER,
+        "hardware": "gpu-optional",
+        "needs": ["ollama"],
+        "granularity": "recorte",
+        "unit_speed_s": 45.9, "unit": "img",
+        "vram_mb": 3500, "ram_mb": 600, "cold_s": 5,
+        "refines": "logo",
+        "wins": ["logo"],
+        "measured_in": ["e16"],
+    },
+    "qwen3-vl-8b-small-image": {
+        "role": REFINER,
+        "hardware": "gpu-optional",
+        "needs": ["ollama"],
+        "granularity": "recorte",
+        "unit_speed_s": 112.0, "unit": "img",
+        "vram_mb": 5500, "ram_mb": 700, "cold_s": 5,
+        "refines": "logo",
+        "wins": ["logo"],
+        "measured_in": ["e16"],
+        "note": "fallback Apache-2.0 do gemma3-4b p/ logo.",
+    },
+
+    # ---- OPTIMIZER (pós-extração, universal) ------------------------------
+    "pdf2md-optimize": {
+        "role": OPTIMIZER,
+        "hardware": "cpu",
+        "needs": [],
+        "granularity": "recorte",
+        "unit_speed_s": 0.12, "unit": "img",
+        "vram_mb": 0, "ram_mb": 100, "cold_s": 0.1,
+        "wins": ["bytes", "determinismo", "universal"],
+        "measured_in": ["e04"],
+    },
+}
+
+
+def load_active_profiles() -> dict[str, dict]:
+    """Devolve os perfis ativos (route-relevant). Função p/ paridade com a API
+    do T090 e p/ permitir injeção/override em testes."""
+    return PROFILES
+
+
+def by_role(role: str, profiles: dict | None = None) -> dict[str, dict]:
+    p = profiles or PROFILES
+    return {k: v for k, v in p.items() if v["role"] == role}

pdf2md/aggregate.py

@@ -0,0 +1,407 @@
+"""Agrega múltiplos `_stats.json` (recursivos) em `_OVERVIEW.{md,json}`.
+
+Varre uma raiz, classifica cada doc (livro/paper/material/outro), e produz:
+- `_OVERVIEW.md`: relatório consolidado humano (resumo + tabelas por kind +
+  análise round-trip + multi-iteration + outliers + versões).
+- `_OVERVIEW.json`: dump agregado para máquina.
+
+Pode ser usado como módulo (`from pdf2md.aggregate import aggregate`) ou
+script standalone (compat com `python src/aggregate_stats.py ROOT --out DIR`).
+"""
+from __future__ import annotations
+
+import json
+import sys
+from collections import Counter
+from datetime import datetime
+from pathlib import Path
+
+
+def fmt_bytes(n: int) -> str:
+    """`1024` → `1.0 KB`. Para bytes humano-legíveis nas tabelas."""
+    n = float(n)
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024:
+            return f"{n:.1f} {unit}" if unit != "B" else f"{int(n)} B"
+        n /= 1024
+    return f"{n:.1f} TB"
+
+
+def classify_doc(stats: dict, path: Path) -> str:
+    """Heurística path-based: livro / paper / material / outro."""
+    parts = [p.lower() for p in path.parts]
+    if "livros" in parts:
+        return "livro"
+    if "papers" in parts:
+        return "paper"
+    if "material_aulas" in parts:
+        return "material"
+    return "outro"
+
+
+def load_multi_roundtrip(folder: Path) -> dict | None:
+    """Lê `_multi_roundtrip.json` ao lado do `_stats.json`, se existir."""
+    f = folder / "_multi_roundtrip.json"
+    if not f.exists():
+        return None
+    try:
+        return json.loads(f.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def collect_docs(root: Path) -> list[dict]:
+    """Varre `root` recursivamente, achata cada `_stats.json` num dict comum."""
+    docs: list[dict] = []
+    for stats_path in sorted(root.rglob("_stats.json")):
+        try:
+            data = json.loads(stats_path.read_text(encoding="utf-8"))
+        except Exception as e:
+            print(f"[WARN] {stats_path}: {e}", file=sys.stderr)
+            continue
+        rel = stats_path.parent.relative_to(root)
+        kind = classify_doc(data, stats_path)
+        out = data.get("output", {})
+        tot = out.get("totals", {}) or {}
+        src = data.get("source", {}) or {}
+        rt = data.get("roundtrip") or {}
+        mrt = load_multi_roundtrip(stats_path.parent)
+        docs.append({
+            "kind": kind,
+            "name": rel.name or str(rel),
+            "rel_path": str(rel).replace("\\", "/"),
+            "stats_path": str(stats_path),
+            "pages": src.get("pages"),
+            "pdf_size": src.get("size_bytes", 0),
+            "chapter_count": tot.get("chapter_count", 0),
+            "tokens": tot.get("tokens", 0),
+            "words": tot.get("words", 0),
+            "size_bytes": tot.get("size_bytes", 0),
+            "math_display": tot.get("math_display", 0),
+            "math_inline": tot.get("math_inline", 0),
+            "headers_total": tot.get("headers_total", 0),
+            "tables_rough": tot.get("tables_rough", 0),
+            "images_count": tot.get("images_count", 0),
+            "images_total_bytes": tot.get("images_total_bytes", 0),
+            "ligature_artifacts": tot.get("ligature_artifacts", 0),
+            "extraction_seconds": data.get("extraction_time_seconds"),
+            "similarity": rt.get("similarity"),
+            "divergences": rt.get("divergence_categories", {}),
+            "tools": data.get("tools", {}),
+            "generated_at": data.get("generated_at", "?"),
+            "multi_roundtrip": mrt,
+        })
+    return docs
+
+
+def render_overview(root: Path, docs: list[dict]) -> str:
+    """Formata os docs coletados como Markdown legível com tabelas e veredito."""
+    if not docs:
+        return f"# OVERVIEW — {root}\n\nNenhum `_stats.json` encontrado.\n"
+
+    by_kind = {"livro": [], "paper": [], "material": [], "outro": []}
+    for d in docs:
+        by_kind[d["kind"]].append(d)
+
+    lines = [
+        f"# OVERVIEW — `{root}`",
+        "",
+        f"*Gerado em: {datetime.now().isoformat(timespec='seconds')}*",
+        "",
+        "Visão consolidada de todas as extrações do conversor neste diretório.",
+        "Cada linha vem de um `_stats.json` produzido por `pdf2md stats`.",
+        "",
+    ]
+
+    total_pages = sum(d["pages"] or 0 for d in docs)
+    total_tokens = sum(d["tokens"] for d in docs)
+    total_words = sum(d["words"] for d in docs)
+    total_math = sum(d["math_display"] + d["math_inline"] for d in docs)
+    total_imgs = sum(d["images_count"] for d in docs)
+    total_md_bytes = sum(d["size_bytes"] for d in docs)
+    total_pdf_bytes = sum(d["pdf_size"] for d in docs)
+    total_img_bytes = sum(d["images_total_bytes"] for d in docs)
+
+    sims = [d["similarity"] for d in docs if d["similarity"] is not None]
+    sim_avg = sum(sims) / len(sims) if sims else None
+    sim_min = min(sims) if sims else None
+    sim_max = max(sims) if sims else None
+
+    agg_div: Counter = Counter()
+    for d in docs:
+        agg_div.update(d["divergences"])
+
+    lines += [
+        "## Resumo executivo",
+        "",
+        "| Métrica | Total |",
+        "|---|---:|",
+        f"| Documentos extraídos | **{len(docs)}** |",
+        f"| Livros | {len(by_kind['livro'])} |",
+        f"| Papers | {len(by_kind['paper'])} |",
+        f"| Materiais de aula | {len(by_kind['material'])} |",
+        f"| Páginas (PDF originais) | {total_pages:,} |",
+        f"| Tokens (MD output) | {total_tokens:,} |",
+        f"| Palavras | {total_words:,} |",
+        f"| Fórmulas | {total_math:,} |",
+        f"| Imagens | {total_imgs:,} |",
+        f"| Tamanho dos PDFs | {fmt_bytes(total_pdf_bytes)} |",
+        f"| Tamanho dos MDs | {fmt_bytes(total_md_bytes)} |",
+        f"| Tamanho das imagens | {fmt_bytes(total_img_bytes)} |",
+    ]
+    if total_pdf_bytes:
+        ratio_md = total_md_bytes / total_pdf_bytes * 100
+        ratio_full = (total_md_bytes + total_img_bytes) / total_pdf_bytes * 100
+        lines += [
+            f"| MD/PDF (apenas texto) | {ratio_md:.1f}% |",
+            f"| (MD+img)/PDF (transporte) | {ratio_full:.1f}% |",
+        ]
+    if sim_avg is not None:
+        lines += [
+            f"| Round-trip — média | **{sim_avg*100:.2f}%** |",
+            f"| Round-trip — min | {sim_min*100:.2f}% |",
+            f"| Round-trip — max | {sim_max*100:.2f}% |",
+        ]
+    lines.append("")
+
+    # Tabelas por kind
+    for kind, label in [("livro", "Livros"), ("paper", "Papers"), ("material", "Materiais de aula")]:
+        items = by_kind[kind]
+        if not items:
+            continue
+        lines += [
+            f"## {label}",
+            "",
+            "| Doc | Pgs | Seções | Tokens | Palavras | Fórmulas | Imgs | MD | Round-trip | Tempo |",
+            "|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|",
+        ]
+        for d in sorted(items, key=lambda x: x["rel_path"]):
+            sim_str = f"{d['similarity']*100:.1f}%" if d["similarity"] is not None else "—"
+            t_str = f"{d['extraction_seconds']:.0f}s" if d["extraction_seconds"] else "—"
+            formula_total = d["math_display"] + d["math_inline"]
+            lines.append(
+                f"| [{d['rel_path']}](./{d['rel_path']}/_stats.md) "
+                f"| {d['pages'] or '?'} "
+                f"| {d['chapter_count']} "
+                f"| {d['tokens']:,} "
+                f"| {d['words']:,} "
+                f"| {formula_total} "
+                f"| {d['images_count']} "
+                f"| {fmt_bytes(d['size_bytes'])} "
+                f"| {sim_str} "
+                f"| {t_str} |"
+            )
+        lines.append("")
+
+    if sims:
+        lines += [
+            "## Análise round-trip",
+            "",
+            f"Documentos com medição de round-trip: **{len(sims)}/{len(docs)}**.",
+            "",
+        ]
+        buckets = {"≥95%": 0, "90-95%": 0, "80-90%": 0, "<80%": 0}
+        for s in sims:
+            p = s * 100
+            if p >= 95:
+                buckets["≥95%"] += 1
+            elif p >= 90:
+                buckets["90-95%"] += 1
+            elif p >= 80:
+                buckets["80-90%"] += 1
+            else:
+                buckets["<80%"] += 1
+        lines += ["### Distribuição", "", "| Faixa | Documentos |", "|---|---:|"]
+        for k, v in buckets.items():
+            lines.append(f"| {k} | {v} |")
+        lines.append("")
+
+        if agg_div:
+            total_div = sum(agg_div.values())
+            lines += [
+                "### Divergências (agregadas em todos os docs com round-trip)",
+                "",
+                "| Categoria | Tokens divergentes | % |",
+                "|---|---:|---:|",
+            ]
+            for cat, n in agg_div.most_common():
+                pct = n / max(total_div, 1) * 100
+                lines.append(f"| `{cat}` | {n:,} | {pct:.1f}% |")
+            lines.append("")
+
+    if agg_div:
+        math_pct = agg_div.get("math", 0) / max(sum(agg_div.values()), 1) * 100
+        lines += [
+            "### Interpretação à luz da hierarquia de prioridades",
+            "",
+            f"`math` representa **{math_pct:.1f}%** das divergências agregadas. Isso é",
+            "consistente com **drift de notação LaTeX** (4ª prioridade — formatação),",
+            "não perda de conteúdo (1ª prioridade). O round-trip mede similaridade",
+            "byte-a-byte; uma fórmula re-renderizada com `\\rm` em vez de `\\mathrm`",
+            "conta como divergência mas preserva o conteúdo matemático.",
+            "",
+            "Para validar **preservação de conteúdo** (1ª prioridade), seria preciso",
+            "comparar AST math e contagem de fórmulas em vez de tokens — ver T410.",
+            "",
+        ]
+
+    multi_docs = [d for d in docs if d.get("multi_roundtrip")]
+    if multi_docs:
+        lines += [
+            "## Multi-iteration round-trip",
+            "",
+            "Documentos com teste de iteração MD → PDF → MD' → PDF → ... medindo",
+            "convergência ou drift do pipeline. Curva achatada = pipeline idempotente.",
+            "",
+        ]
+        for d in multi_docs:
+            mrt = d["multi_roundtrip"]
+            iters = mrt.get("iterations", [])
+            if not iters:
+                continue
+            lines += [
+                f"### `{d['rel_path']}` — {len(iters)} iterações",
+                "",
+                "| i | Tokens | Sim(MDᵢ, MD₀) | Sim(MDᵢ, MDᵢ₋₁) | Tempo |",
+                "|---:|---:|---:|---:|---:|",
+            ]
+            for it in iters:
+                if it.get("error"):
+                    lines.append(f"| {it['i']} | — | — | — | falha |")
+                    continue
+                sim_to_0 = f"{it['sim_to_md0']*100:.2f}%" if it.get("sim_to_md0") is not None else "—"
+                sim_to_prev = f"{it['sim_to_prev']*100:.2f}%" if it.get("sim_to_prev") is not None else "—"
+                lines.append(
+                    f"| {it['i']} | {it.get('tokens', 0):,} | "
+                    f"{sim_to_0} | {sim_to_prev} | {it.get('seconds', 0):.0f}s |"
+                )
+            sims_to_0 = [it["sim_to_md0"] for it in iters if it.get("sim_to_md0") is not None]
+            if len(sims_to_0) >= 2:
+                first, last = sims_to_0[0], sims_to_0[-1]
+                drift = (first - last) * 100
+                last_two_diff = abs(sims_to_0[-1] - sims_to_0[-2]) * 100
+                lines.append("")
+                if abs(drift) < 1.0:
+                    lines.append(f"**Veredito:** pipeline estável (drift {drift:.2f}% < 1%).")
+                elif drift > 0 and last_two_diff < 0.5:
+                    lines.append(f"**Veredito:** convergência logarítmica — perdeu {drift:.1f}% mas estabilizou (Δ últimas duas iterações: {last_two_diff:.2f}%).")
+                else:
+                    lines.append(f"**Veredito:** drift contínuo — perdeu {drift:.1f}% e ainda variando.")
+            lines.append("")
+            lines.append(f"Detalhes: [`{d['rel_path']}/_multi_roundtrip.md`](./{d['rel_path']}/_multi_roundtrip.md)")
+            lines.append("")
+
+    # Outliers
+    lines += ["## Outliers e atenção", ""]
+    critical: list[tuple[str, list[str]]] = []
+    notable: list[tuple[str, list[str]]] = []
+    for d in docs:
+        notes: list[str] = []
+        bucket: str | None = None
+        if d["similarity"] is not None:
+            sim_pct = d["similarity"] * 100
+            if sim_pct < 50:
+                notes.append(f"round-trip crítico ({sim_pct:.1f}%)")
+                bucket = "critical"
+            elif sim_pct < 70:
+                notes.append(f"round-trip moderado ({sim_pct:.1f}%) — provavelmente drift LaTeX")
+                bucket = "notable"
+        if d["ligature_artifacts"] > 0:
+            notes.append(f"{d['ligature_artifacts']} ligaduras quebradas")
+            bucket = bucket or "critical"
+        if d["tokens"] == 0:
+            notes.append("zero tokens (extração falhou?)")
+            bucket = "critical"
+        if not notes:
+            continue
+        if bucket == "critical":
+            critical.append((d["rel_path"], notes))
+        else:
+            notable.append((d["rel_path"], notes))
+
+    if critical:
+        lines += ["### Crítico (investigar)", ""]
+        for path, notes in critical:
+            lines.append(f"- `{path}` — {'; '.join(notes)}")
+        lines.append("")
+    if notable:
+        lines += ["### Notável (drift esperado, monitorar)", ""]
+        for path, notes in notable:
+            lines.append(f"- `{path}` — {'; '.join(notes)}")
+        lines.append("")
+    if not critical and not notable:
+        lines.append("Nenhum documento com flags de atenção.")
+        lines.append("")
+
+    # Versões
+    tool_versions: Counter = Counter()
+    for d in docs:
+        t = d["tools"]
+        sig = (
+            t.get("marker", "?"),
+            t.get("torch", "?"),
+            t.get("cuda_device", "CPU"),
+        )
+        tool_versions[sig] += 1
+    if tool_versions:
+        lines += [
+            "## Pipeline / versões",
+            "",
+            "| marker-pdf | torch | device | docs |",
+            "|---|---|---|---:|",
+        ]
+        for (mk, tc, dev), n in tool_versions.most_common():
+            lines.append(f"| `{mk}` | `{tc}` | `{dev}` | {n} |")
+        lines.append("")
+
+    return "\n".join(lines) + "\n"
+
+
+def aggregate(root: Path, out_dir: Path | None = None) -> tuple[Path, Path]:
+    """Pipeline completo: varre root, agrega, salva _OVERVIEW.md + .json.
+
+    Retorna `(md_path, json_path)`.
+    """
+    out_dir = out_dir or root
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    docs = collect_docs(root)
+
+    overview_md = out_dir / "_OVERVIEW.md"
+    overview_json = out_dir / "_OVERVIEW.json"
+
+    overview_md.write_text(render_overview(root, docs), encoding="utf-8")
+    overview_json.write_text(
+        json.dumps({
+            "generated_at": datetime.now().isoformat(timespec="seconds"),
+            "root": str(root),
+            "docs": docs,
+        }, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return overview_md, overview_json
+
+
+def _cli() -> int:
+    """CLI standalone (compat com `python src/aggregate_stats.py ROOT --out DIR`)."""
+    import argparse
+    p = argparse.ArgumentParser(description="Agrega _stats.json em _OVERVIEW.md")
+    p.add_argument("root", type=Path)
+    p.add_argument("--out", type=Path, default=None,
+                   help="Diretório de saída (default: <root>)")
+    args = p.parse_args()
+
+    if not args.root.is_dir():
+        print(f"[ERRO] Diretório não encontrado: {args.root}", file=sys.stderr)
+        return 1
+
+    md_path, json_path = aggregate(args.root, args.out)
+    docs = collect_docs(args.root)  # só para contagem (já chamado dentro de aggregate)
+    print(f"[INFO] {len(docs)} doc(s) com _stats.json em {args.root}")
+    print(f"[OK] {md_path}")
+    print(f"[OK] {json_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_cli())