Pluggable document conversion for Python

[chavarera]

Project Documentation

Project Name

DocuSwitch — Pluggable document conversion for Python

One API. Multiple document engines. Switch converters without changing your application.

---

1. Overview

Modern document-processing libraries are highly specialized.

Some are optimized for:

• ⚡ speed
• 📄 PDF parsing
• 🔍 OCR
• 📊 table extraction
• 🧮 formula recognition
• 🧱 layout understanding
• 🤖 RAG pipelines
• 🌍 multilingual documents

But integrating multiple engines into one application is difficult because every library exposes a different API, configuration model, output format, and dependency stack.

DocuSwitch provides a common Python interface over multiple document conversion engines.

                    Your Application
                           │
                           ▼
                  ┌─────────────────┐
                  │    DocuSwitch   │
                  │   Unified API   │
                  └────────┬────────┘
                           │
             ┌─────────────┼─────────────┐
             │             │             │
             ▼             ▼             ▼
          Docling        MinerU      PaddleOCR
             │             │             │
             ├─────────────┼─────────────┤
             │             │             │
             ▼             ▼             ▼
        MarkItDown       AnyDoc     Unstructured

Your application doesn't need to know which engine is underneath.

---

2. Goals

Primary goals

• Provide a single Python API for document conversion.
• Support multiple conversion engines.
• Allow converters to be switched without application changes.
• Normalize converter output.
• Support automatic converter selection.
• Provide fallback converters.
• Expose converter capabilities.
• Measure performance.
• Keep heavyweight dependencies optional.
• Make adding a new converter simple.

Non-goals

DocuSwitch should not initially try to:

• replace the underlying conversion engines
• implement its own OCR engine
• implement its own PDF parser
• become a vector database
• become an entire RAG framework

It should remain an orchestration and abstraction layer.

---

3. Supported Engines

Initial adapters:

Converter	Primary Strength
Docling	Document structure + RAG
MinerU	Complex PDF extraction
PaddleOCR	OCR + tables + formulas
MarkItDown	Fast general conversion
AnyDoc	Fast document conversion
PDF Inspector	PDF detection/routing
Unstructured	Document ETL
OmniParse	Multimodal parsing

The project should treat these as plugins, not hard dependencies.

---

4. Architecture

                         ┌──────────────────────┐
                         │      Application     │
                         └───────────┬──────────┘
                                     │
                                     ▼
                         ┌──────────────────────┐
                         │     DocumentParser    │
                         │       Facade API      │
                         └───────────┬──────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    │                │                │
                    ▼                ▼                ▼
               Explicit          Automatic        Profile
               Converter           Router          Selection
                    │                │                │
                    └────────────────┼────────────────┘
                                     ▼
                         ┌──────────────────────┐
                         │   Converter Registry │
                         └───────────┬──────────┘
                                     │
       ┌──────────────┬──────────────┼───────────────┬──────────────┐
       ▼              ▼              ▼               ▼              ▼
   Docling         MinerU       PaddleOCR       MarkItDown       AnyDoc
       │              │              │               │              │
       └──────────────┴──────────────┼───────────────┴──────────────┘
                                     │
                                     ▼
                         ┌──────────────────────┐
                         │  Normalized Result   │
                         └──────────────────────┘

---

5. Core API

The main API should be deliberately small.

from docuswitch import DocumentParser

parser = DocumentParser()

result = parser.convert(
    "document.pdf",
    converter="docling",
)

print(result.markdown)

Switching engines:

result = parser.convert(
    "document.pdf",
    converter="mineru",
)

No application code needs to change.

---

6. Automatic Routing

The most powerful feature should be:

result = parser.convert(
    "document.pdf",
    converter="auto",
)

The router analyzes the document and chooses the appropriate engine.

Example:

                    document.pdf
                         │
                         ▼
                 ┌───────────────┐
                 │ Document      │
                 │ Analyzer      │
                 └───────┬───────┘
                         │
             ┌───────────┼───────────┐
             │           │           │
             ▼           ▼           ▼
          Native       Scanned     Complex
           PDF           PDF         PDF
             │           │           │
             ▼           ▼           ▼
        PDF Inspector PaddleOCR    MinerU

A future routing strategy could consider:

file type
file size
page count
OCR requirement
table density
formula density
language
layout complexity
available GPU
latency requirement
quality requirement

---

7. Converter Profiles

Instead of selecting a specific engine, users can select a profile.

Fast

parser.convert(
    "document.pdf",
    profile="fast",
)

Possible routing:

Fast
 ├── AnyDoc
 ├── MarkItDown
 └── PDF Inspector

Quality

parser.convert(
    "document.pdf",
    profile="quality",
)

Possible routing:

Quality
 ├── MinerU
 ├── Docling
 └── PaddleOCR

OCR

parser.convert(
    "document.pdf",
    profile="ocr",
)

Auto

parser.convert(
    "document.pdf",
    profile="auto",
)

---

8. Unified Result

Every engine should return a common structure.

@dataclass
class ConversionResult:

    markdown: str

    converter: str

    metadata: dict

    pages: list

    tables: list

    images: list

    sections: list

    metrics: ConversionMetrics

Example:

result.markdown
result.converter
result.metadata
result.pages
result.tables
result.images
result.metrics

The underlying engine can still expose native output through:

result.raw

This is important because you don't want your abstraction to become a lowest-common-denominator API.

---

9. Capability System

Every adapter declares what it supports.

@dataclass
class Capabilities:

    pdf: bool
    docx: bool
    pptx: bool
    xlsx: bool
    images: bool

    ocr: bool
    tables: bool
    formulas: bool
    layout: bool

    multilingual: bool
    audio: bool
    video: bool

Example:

MinerU.capabilities = Capabilities(
    pdf=True,
    docx=False,
    pptx=False,
    xlsx=False,
    images=True,
    ocr=True,
    tables=True,
    formulas=True,
    layout=True,
    multilingual=True,
    audio=False,
    video=False,
)

This enables:

parser.convert(
    "invoice.pdf",
    requirements={
        "ocr": True,
        "tables": True,
        "layout": True,
    },
)

The router can then select an appropriate engine.

---

10. Fallback

Converters can fail.

For production systems, the library should support fallback chains.

parser.convert(
    "document.pdf",
    converters=[
        "docling",
        "mineru",
        "paddleocr",
    ],
)

Execution:

Docling
   │
   ├── SUCCESS ──► Result
   │
   └── FAILURE
          │
          ▼
        MinerU
          │
          ├── SUCCESS ──► Result
          │
          └── FAILURE
                 │
                 ▼
              PaddleOCR

The result should record this:

result.converter
# "paddleocr"

result.metrics.fallback_count
# 2

---

11. Performance Benchmarking

DocuSwitch should provide a standard benchmark interface.

docuswitch benchmark ./documents

Example:

DocuSwitch Benchmark
────────────────────────────────────────────

Dataset: 500 documents

Converter       Avg Time    Success    Quality
------------------------------------------------
AnyDoc          0.42 sec    99.8%      82.1%
MarkItDown      0.61 sec    99.9%      78.4%
Docling         2.31 sec    99.4%      94.7%
MinerU          3.12 sec    98.9%      96.2%
PaddleOCR       2.87 sec    99.1%      95.1%

Importantly, quality scores should be dataset-specific, rather than claiming that one parser is universally better.

---

12. Metrics

Every conversion should optionally collect:

@dataclass
class ConversionMetrics:

    processing_time: float

    input_size: int

    page_count: int

    converter: str

    success: bool

    cpu_time: float | None

    memory_usage: float | None

    gpu_used: bool

    fallback_count: int

    error: str | None

This makes it possible to answer:

Which converter performs best on my documents?

---

13. Optional Dependencies

This is critical.

Don't make users install every parser.

For example:

pip install docuswitch

Core only.

Then:

pip install docuswitch[docling]

pip install docuswitch[mineru]

pip install docuswitch[paddleocr]

pip install docuswitch[markitdown]

Or:

pip install docuswitch[all]

This keeps the base installation lightweight.

---

14. Plugin Architecture

Eventually, third-party developers should be able to create:

class MyConverter(Converter):

    name = "my-converter"

    capabilities = ...

    def convert(self, source, **kwargs):
        ...

Then register:

registry.register(MyConverter())

Long term, support Python entry points:

[project.entry-points."docuswitch.converters"]

my_converter = "my_package:MyConverter"

Then DocuSwitch can discover converters automatically.

---

15. CLI

The project should also provide a CLI.

Convert

docuswitch convert document.pdf

Specific converter

docuswitch convert document.pdf --converter docling

Automatic

docuswitch convert document.pdf --converter auto

Profile

docuswitch convert document.pdf --profile quality

List available converters

docuswitch converters

Output:

Available converters:

✓ docling
✓ mineru
✓ paddleocr
✓ markitdown
✓ anydoc
✓ pdf-inspector
✓ unstructured
✓ omniparse

---

16. Project Structure

docuswitch/
│
├── pyproject.toml
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── SECURITY.md
│
├── src/
│   └── docuswitch/
│       │
│       ├── __init__.py
│       │
│       ├── core/
│       │   ├── converter.py
│       │   ├── result.py
│       │   ├── capabilities.py
│       │   ├── metrics.py
│       │   └── exceptions.py
│       │
│       ├── converters/
│       │   ├── docling.py
│       │   ├── mineru.py
│       │   ├── paddleocr.py
│       │   ├── markitdown.py
│       │   ├── anydoc.py
│       │   ├── pdf_inspector.py
│       │   ├── unstructured.py
│       │   └── omniparse.py
│       │
│       ├── registry/
│       │   ├── registry.py
│       │   └── discovery.py
│       │
│       ├── router/
│       │   ├── router.py
│       │   ├── strategy.py
│       │   └── capability.py
│       │
│       ├── detection/
│       │   ├── mime.py
│       │   ├── pdf.py
│       │   └── document.py
│       │
│       └── cli/
│           └── main.py
│
└── tests/
    ├── unit/
    ├── integration/
    ├── converters/
    └── benchmarks/

---

17. Roadmap

Phase 1 — Core

• Common Converter interface
• ConversionResult
• Converter registry
• Explicit converter selection
• Optional dependencies
• Unit tests

Phase 2 — Adapters

• MarkItDown
• AnyDoc
• Docling
• MinerU
• PaddleOCR
• Unstructured
• PDF Inspector
• OmniParse

Phase 3 — Intelligence

• File type detection
• PDF classification
• Capability-based routing
• Automatic converter selection
• Fallback chains
• Converter health checks

Phase 4 — Observability

• Processing metrics
• Performance benchmarking
• Memory tracking
• GPU utilization
• Structured logs
• OpenTelemetry integration

Phase 5 — Production

• Async API
• Batch processing
• Parallel conversion
• Job queues
• REST API
• Docker image
• Kubernetes support

Phase 6 — Ecosystem

• Third-party plugins
• Plugin marketplace/catalog
• Community converters
• Benchmark datasets
• Web dashboard

---

18. Future Architecture

Eventually this can evolve from a simple Python wrapper into:

                         DocuSwitch
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
      Python SDK            CLI               REST API
          │                   │                   │
          └───────────────────┼───────────────────┘
                              │
                              ▼
                       Intelligent Router
                              │
                 ┌────────────┼────────────┐
                 ▼            ▼            ▼
              Fast         Balanced      Quality
                 │            │            │
                 ▼            ▼            ▼
             AnyDoc        Docling       MinerU
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
                PaddleOCR          Custom Plugin

---

19. Why This Project?

The ecosystem has many excellent document-processing engines, but applications often become tightly coupled to one implementation.

For example:

# Application
docling.convert(...)

Later you discover:

MinerU produces better tables.

Now changing the parser requires modifying application code.

With DocuSwitch:

parser.convert(
    document,
    converter="mineru",
)

The application remains unchanged.

This makes the parser an implementation detail.

---

20. Key Design Principle

The project should follow this rule:

Don't standardize the engines. Standardize the contract.

Each engine should remain free to expose its unique capabilities.

The abstraction should provide:

Common interface
       +
Common result
       +
Capability discovery
       +
Routing
       +
Fallback
       +
Metrics
       =
Portable document conversion

---

Recommended MVP

I wouldn't start with all eight adapters.

Start with:

v0.1

Core API
   │
   ├── MarkItDown
   ├── Docling
   ├── MinerU
   └── PaddleOCR

Then add:

v0.2

AnyDoc
PDF Inspector
Unstructured
OmniParse

Then build the feature that can make the project genuinely differentiated:

Auto Router + Benchmark Engine

That is what turns it from "a wrapper around existing libraries" into a useful infrastructure project.