Metadata-Version: 2.4
Name: docmirror
Version: 0.3.0
Summary: Universal document parsing engine with OCR, layout analysis, and table extraction
Project-URL: Homepage, https://github.com/valuemapglobal/docmirror
Project-URL: Documentation, https://valuemapglobal.github.io/docmirror
Project-URL: Repository, https://github.com/valuemapglobal/docmirror
Project-URL: Issues, https://github.com/valuemapglobal/docmirror/issues
Project-URL: Changelog, https://github.com/valuemapglobal/docmirror/blob/main/CHANGELOG.md
License: Apache-2.0
License-File: AUTHORS.md
License-File: LICENSE
Keywords: document-ai,document-parsing,layout-analysis,ocr,pdf,table-extraction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.10
Requires-Dist: filetype>=1.2
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Requires-Dist: fast-langdetect>=0.2; extra == 'all'
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: numpy>=1.24; extra == 'all'
Requires-Dist: opencv-python-headless>=4.8; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: pdfplumber>=0.10; extra == 'all'
Requires-Dist: pikepdf>=8.0; extra == 'all'
Requires-Dist: pymupdf>=1.23; extra == 'all'
Requires-Dist: python-docx>=1.0; extra == 'all'
Requires-Dist: python-multipart>=0.0.9; extra == 'all'
Requires-Dist: python-pptx>=0.6; extra == 'all'
Requires-Dist: rapid-latex-ocr>=0.0.6; extra == 'all'
Requires-Dist: rapid-layout>=0.1; extra == 'all'
Requires-Dist: rapid-table>=0.2; extra == 'all'
Requires-Dist: rapidocr-onnxruntime>=1.3; extra == 'all'
Requires-Dist: redis>=5.0; extra == 'all'
Requires-Dist: uvicorn>=0.23.0; extra == 'all'
Provides-Extra: cache
Requires-Dist: redis>=5.0; extra == 'cache'
Provides-Extra: dev
Requires-Dist: coverage>=7.4; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pre-commit>=3.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: external-ocr
Requires-Dist: requests>=2.28; extra == 'external-ocr'
Provides-Extra: formula
Requires-Dist: rapid-latex-ocr>=0.0.6; extra == 'formula'
Provides-Extra: langdetect
Requires-Dist: fast-langdetect>=0.2; extra == 'langdetect'
Provides-Extra: layout
Requires-Dist: rapid-layout>=0.1; extra == 'layout'
Provides-Extra: ocr
Requires-Dist: numpy>=1.24; extra == 'ocr'
Requires-Dist: opencv-python-headless>=4.8; extra == 'ocr'
Requires-Dist: rapidocr-onnxruntime>=1.3; extra == 'ocr'
Provides-Extra: office
Requires-Dist: openpyxl>=3.1; extra == 'office'
Requires-Dist: python-docx>=1.0; extra == 'office'
Requires-Dist: python-pptx>=0.6; extra == 'office'
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.10; extra == 'pdf'
Requires-Dist: pymupdf>=1.23; extra == 'pdf'
Provides-Extra: security
Requires-Dist: pikepdf>=8.0; extra == 'security'
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: python-multipart>=0.0.9; extra == 'server'
Requires-Dist: uvicorn>=0.23.0; extra == 'server'
Provides-Extra: table
Requires-Dist: rapid-table>=0.2; extra == 'table'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">📄 DocMirror</h1>
  <p align="center">
    <em>Universal Industrial-Grade Document Parsing Engine</em><br/>
    Extract highly-structured data from any document format with military-grade precision.
  </p>
  <p align="center">
    <a href="https://pypi.org/project/docmirror/"><img src="https://img.shields.io/pypi/v/docmirror?color=blue&style=for-the-badge" alt="PyPI"></a>
    <a href="https://pypi.org/project/docmirror/"><img src="https://img.shields.io/pypi/pyversions/docmirror?style=for-the-badge" alt="Python"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green?style=for-the-badge" alt="License"></a>
    <a href="https://github.com/valuemapglobal/docmirror/actions"><img src="https://github.com/valuemapglobal/docmirror/actions/workflows/ci.yml/badge.svg?style=for-the-badge" alt="CI"></a>
    <a href="https://codecov.io/gh/valuemapglobal/docmirror"><img src="https://codecov.io/gh/valuemapglobal/docmirror/branch/main/graph/badge.svg?style=for-the-badge" alt="Coverage"></a>
  </p>
</p>

---

**DocMirror** is a cutting-edge Python library built for the toughest document parsing environments. Go beyond simple text extraction. DocMirror combines computer vision, topological layout algorithms, and middleware intelligence to deliver pure, structured data and verifiable trust scores from messy, real-world documents.

## ⚡ The Killer Features

| Capability | What makes it different? |
| :--- | :--- |
| **🛡️ Anti-Forgery & Tamper Detection** | Integrates Pixel Error Level Analysis (ELA) and Metadata Blacklisting. It doesn't just read documents; it tells you if the document was Photoshopped. |
| **🧠 Topological Divide-and-Conquer Layout** | Drops naive heuristics and uses spatial clustering (DBSCAN + X-Y Cuts) guided by DocLayout-YOLO to accurately reconstruct reading orders even on dense, multi-column financial reports. |
| **🏦 Bank-Grade CCB Table Repair** | Native algorithmic immunity against complex table structure anomalies (e.g., China Construction Bank staggered grids) doing what LLMs and basic vision models notoriously fail at. |
| **👁️ Dynamic Multi-Scale OCR** | RapidOCR core supercharged with dynamic color-slicing and contrast boosting to rescue faded, low-DPI scans. |
| **🧩 Zero-Friction Plugin Architecture** | Write custom Domain Plugins (`BankStatement`, `Invoice`) that magically bind unstructured output to your exact Pydantic entity schemas. |

## 🚀 Quick Start

### 1. Install (One-Liner)
```bash
# Get the engine, PDF vision drivers, and high-performance layout analyzers
pip install "docmirror[all]"
```

### 2. Awaken the Engine
Just point `perceive_document` at an image, PDF, Word doc, or Excel sheet. The **L0 Dispatcher** automatically infers the format, spins up the correct Adapter, parses the data, applies your middlewares, and returns a unified 4-layer topology.

```python
import asyncio
from docmirror import perceive_document

async def main():
    # One line to process ANY tricky document
    result = await perceive_document("suspicious_bank_statement.pdf")

    print(f"Status: {result.status} | Scene: {result.scene}")
    
    # Check if the document was forged
    if result.provenance.validation.is_forged:
        print(f"⚠️ FORGERY DETECTED: {result.provenance.validation.forgery_reasons}")
    
    # Zero in on extracted entities directly mapped from your plugins
    print(f"Entities: {result.content.entities}")

asyncio.run(main())
```

> **Pro-Tip**: Prefer the CLI? `python3 -m docmirror document.pdf --format json`

## 🏗️ The 4-Layer Architecture

DocMirror abandons monolithic parser designs in favor of a strict, highly observable pipeline. From the raw bytes reading to the final Python properties, every step is rigorously logged and structurally sound.

```mermaid
graph TD
    classDef orchestrator fill:#2b2b2b,stroke:#00f0ff,stroke-width:2px,color:#fff
    classDef adapter fill:#3a3a3a,stroke:#ffa500,stroke-width:2px,color:#fff
    classDef core fill:#444,stroke:#ff0055,stroke-width:2px,color:#fff
    classDef data fill:#1f2937,stroke:#a855f7,stroke-width:2px,color:#fff
    classDef none fill:none,stroke:none

    FILE[[Any Document\nPDF / Image / Excel]]:::none --> DISPATCH
    
    DISPATCH[L0 Dispatcher \n + Redis Cache]:::orchestrator --> ADAPTERS
    
    subgraph "Adapt & Physically Extract"
        ADAPTERS(Format Adapters):::adapter --> CORE{Core Engine \n OCR / Layout / Tables}:::core
        CORE --> BASERESULT[(BaseResult)]:::data
    end
    
    BASERESULT --> ORCHESTRATOR
    
    subgraph "Enhance Pipeline (Middlewares)"
        ORCHESTRATOR[Orchestrator]:::orchestrator --> SCENE[Scene Detection]
        SCENE --> ENTITY[Entity Extraction]
        ENTITY --> VALIDATE[Validation & Trust]
    end
    
    VALIDATE --> BUILDER((Builder)):::orchestrator
    
    BUILDER --> PR[(PerceptionResult \n 4-Layer Output Topology)]:::data
```

### The Output: `PerceptionResult`
DocMirror guarantees a standardized payload structure regardless of where the data came from.
- **Envelope/Status**: `success`, `confidence`, `timing`
- **Content**: Plain markdown `text`, localized geometric `blocks` (Tables, Paragraphs, Images), and `entities`.
- **Identity**: Domain-resolved logic via Aho-Corasick dictionary matching.
- **Trust**: `validation_scores`, `is_forged`, and subsystem execution times.

## 🤝 Community & Support

- **Documentation**: [Complete API & Guide](https://valuemapglobal.github.io/docmirror/)
- **Bug tracker**: [GitHub Issues](https://github.com/valuemapglobal/docmirror/issues)
- **Contribution**: We welcome Pull Requests! Make sure to `make test` (129+ E2E validations) before submitting.

## 📄 License & Authors

Created by **Adam Lin** and proudly maintained by **ValueMap Global**.  
Released under the [Apache 2.0 License](LICENSE).
