cyberdocextractor 0.1.0

Production-grade document-to-Markdown conversion library with hexagonal architecture.

CyberDocExtractor

Production-grade Python library for converting PDF, DOCX, XLSX and CSV documents to Markdown. Multiple precision levels, automatic fallback, LLM-assisted image descriptions, and a strict hexagonal core.

⚠️ Status: early development (Phase 1 / Foundation). The public API is not yet stable. The project skeleton, tooling, CI, and architectural guardrails are in place; domain/application/infra layers are under construction. See the project roadmap.

Why another document extractor?

Extraction tooling is a fragmented landscape — each upstream library (Docling, PyMuPDF, pdfplumber, python-docx, openpyxl, …) has its own model, error semantics, and failure modes. CyberDocExtractor wraps them behind a single typed domain model and applies:

• Hexagonal architecture — the domain doesn't know what PyMuPDF is.
• Pluggable extractors — swap, reorder, or add adapters without touching the core.
• Automatic fallback — if the preferred extractor fails, the next one in the policy chain is tried.
• Deterministic quality scoring — every conversion comes with a 0.0-1.0 score so downstream consumers can gate on confidence.
• Typed, immutable value objects everywhere.
• Strict CI: mypy strict, ruff with pydocstyle, import-linter architectural contracts, coverage floor of 90%, matrix tests on Linux + macOS × Python 3.11/3.12/3.13.

Installation

pip install cyberdocextractor            # core only
pip install cyberdocextractor[pdf]       # + PDF adapters
pip install cyberdocextractor[docx]      # + DOCX adapter
pip install cyberdocextractor[xlsx]      # + XLSX adapter
pip install cyberdocextractor[llm]       # + LLM image description
pip install cyberdocextractor[cli]       # + Typer CLI
pip install cyberdocextractor[all]       # everything

Quick start

from pathlib import Path
from cyberdocextractor import Document, PrecisionLevel, build_pipeline

pipeline = build_pipeline()

source = Path("report.pdf")
doc = Document.from_path(source, precision=PrecisionLevel.BALANCED)

result = pipeline.convert(doc)
print(result.markdown.text)
print(f"quality={result.markdown.quality_score:.2f}, extractor={result.extractor}")

CLI:

cyberdoc convert report.pdf --level 2 --output report.md
cyberdoc batch ./inputs ./outputs --pattern '*.pdf'
cyberdoc status
cyberdoc version

Architecture

┌──────────────────────────────────────┐
│               CLI                    │  cyberdoc convert …
├──────────────────────────────────────┤
│            Application               │  ConversionPipeline + stages
│  (extraction → metadata → profile   │
│   → image enrichment → render)       │
├──────────────────────────────────────┤
│            Infrastructure            │  PyMuPDF, pdfplumber, Docling,
│                                      │  openpyxl, Jinja2, OpenAI-compat
├──────────────────────────────────────┤
│              Domain                  │  Document, Block, NormalizedDoc,
│   (pure, zero-dependency core)       │  Extractor / Policy / Renderer
└──────────────────────────────────────┘
            ▲ depends on (↑ only)

import-linter enforces the arrows in CI. See docs/architecture/overview.md (coming in Phase 7) for the full write-up.

Precision levels

Level	Name	Typical extractor	Trade-off
1	FASTEST	chunked PyMuPDF	speed > fidelity, no table stats
2	BALANCED	pymupdf4llm	default; good text + table output
3	TABLE_OPTIMIZED	pdfplumber	best for structured tables
4	HIGHEST_QUALITY	Docling	OCR, images, layout — slowest

The SelectionPolicy picks the chain automatically from file size, MIME type, and hinted table presence, but callers can override with doc.precision = PrecisionLevel.HIGHEST_QUALITY.

Roadmap

Phase	Scope	Status
1	Tooling, CI, architectural scaffolding	✅ in progress
2	Domain layer (models, ports, rules)	⏳ next
3	Application layer + DI container	⏳
4	Infra adapters (extractors, LLM, Jinja)	⏳
5	CLI + public API	⏳
6	BDD scenarios	⏳
7	mkdocs-material site + ADRs	⏳
8	v0.1.0 release + PyPI publish	⏳

Development

just bootstrap   # install dev env
just check       # format + lint + types + arch + tests
just test        # tests with coverage gate
just docs-serve  # preview docs

See CONTRIBUTING.md for details.

Security

See SECURITY.md for the responsible disclosure policy.

License

MIT — see LICENSE.