docmirror 0.2.0__tar.gz

docmirror-0.2.0/.dockerignore

@@ -0,0 +1,43 @@
+# Git
+.git
+.gitignore
+
+# Python caches
+__pycache__
+*.pyc
+*.pyo
+*.egg-info
+dist
+build
+.eggs
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# Testing & linting caches
+.pytest_cache
+.ruff_cache
+.mypy_cache
+htmlcov
+
+# Output artifacts & model caches
+output/
+model_cache/
+*.onnx
+
+# Docker
+Dockerfile
+docker-compose.yml
+
+# Documentation
+docs/
+*.md
+!README.md
+
+# Test fixtures (large binaries)
+tests/*.pdf
+tests/*.png
+tests/*.jpg

docmirror-0.2.0/.env.example

@@ -0,0 +1,9 @@
+# DocMirror — 示例环境变量（复制为 .env 后按需修改，勿提交 .env）
+# 使用方式: source .env  或  export $(grep -v '^#' .env | xargs)
+
+# ── 外部 OCR（低质量图片/扫描件走 外部OCR模型）──
+# 启用后，当图像质量分 < 阈值 时自动调用外部接口，否则用内置 RapidOCR
+DOCMIRROR_EXTERNAL_OCR_PROVIDER=docmirror.core.ocr.aistudio_provider:call_aistudio_layout_ocr
+DOCMIRROR_EXTERNAL_OCR_QUALITY_THRESHOLD=80
+DOCMIRROR_AISTUDIO_OCR_API_URL=https://XXXX.com/layout-parsing
+DOCMIRROR_AISTUDIO_OCR_TOKEN=your-token-here

docmirror-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,69 @@
+name: Bug Report
+description: Create a report to help us improve DocMirror parsing and robustness
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: input
+    id: version
+    attributes:
+      label: DocMirror Version
+      description: What version of DocMirror are you using? (e.g., 0.1.0 or main branch)
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: environment
+    attributes:
+      label: Environment
+      description: What environment are you running DocMirror in?
+      options:
+        - macOS
+        - Linux (Ubuntu/Debian)
+        - Linux (CentOS/RHEL)
+        - Windows
+        - Docker
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+      placeholder: "When parsing a PDF with X characteristics, the output completely skips table Y..."
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction Steps
+      description: How can we reproduce this? Please provide code snippets or CLI commands.
+      placeholder: |
+        1. Download this sample PDF: [Link]
+        2. Run `docmirror parse sample.pdf`
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs / Traceback
+      description: Paste any error logs, tracebacks, or terminal output here.
+      render: shell
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      options:
+        - label: I agree to follow this project's Code of Conduct
+          required: true

docmirror-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,33 @@
+name: Feature Request
+description: Suggest an idea for DocMirror (e.g., new formats, new AI models)
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        We love new ideas! Please provide as much context as possible.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem?
+      description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen. Do you have a specific AI model or library in mind?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context or screenshots about the feature request here.

docmirror-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Description
+
+Brief description of the changes.
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] My code follows the project's coding standards
+- [ ] I have added/updated tests for my changes
+- [ ] All new and existing tests pass (`pytest tests/ -v`)
+- [ ] Linting passes (`ruff check docmirror/`)
+- [ ] I have updated the documentation (if applicable)
+- [ ] I have added an entry to `CHANGELOG.md` (if applicable)
+
+## Related Issues
+
+Closes #

docmirror-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Run ruff check
+        run: ruff check docmirror/
+      - name: Run ruff format check
+        run: ruff format --check docmirror/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest]
+        include:
+          - python-version: "3.12"
+            os: macos-latest
+          - python-version: "3.12"
+            os: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+      - name: Run tests with coverage
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        run: |
+          pip install pytest-cov
+          pytest tests/ -v --cov=docmirror --cov-report=xml --cov-report=term-missing
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Verify package
+        run: |
+          pip install dist/*.whl
+          python -c "import docmirror; print(f'✅ docmirror {docmirror.__version__} imports successfully')"

docmirror-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "docmirror/**"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material mkdocstrings[python] pymdown-extensions
+          pip install -e ".[dev]"
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

docmirror-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Verify package
+        run: |
+          pip install dist/*.whl
+          python -c "import docmirror; print(f'✅ docmirror installed')"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

docmirror-0.2.0/.gitignore

@@ -0,0 +1,60 @@
+## General
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+## Environment
+.env
+.venv/
+venv/
+env/
+
+## IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+## OS
+.DS_Store
+Thumbs.db
+
+## Model weights & large files
+*.onnx
+*.pt
+*.pth
+*.bin
+*.safetensors
+models_cache/
+
+## Test artifacts
+*.pdf
+!tests/fixtures/*.pdf
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+## Parse output
+output/
+
+## Distribution
+*.whl
+*.tar.gz
+
+## Cache
+.mypy_cache/
+
+## Test fixtures (real documents)
+tests/fixtures/银行流水/
+tests/fixtures/*.zip
+tests/fixtures/*.jpg
+tests/fixtures/*.png
+tests/golden/

docmirror-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.3
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic>=2.0]

docmirror-0.2.0/AUTHORS.md

@@ -0,0 +1,13 @@
+# Authors and Contributors
+
+The **DocMirror** project was originally created and is primarily maintained by **ValueMap Global**.
+
+We are incredibly grateful to the developers, researchers, and community members who have contributed their time and expertise to make this open-source document parsing engine world-class.
+
+## Core Maintainer & Creator
+- **Adam Lin** <adamlin@valuemapglobal.com> - (Lead Architect & Core Engine Developer)
+
+## Contributors
+*(Alphabetical order. Please add your name here if you submit a significant PR!)*
+
+- **Antigravity** (Google DeepMind) - Extensive structural reform, traceability optimization, and architectural purification in Phase 1-15 (March 2026).

docmirror-0.2.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-11
+
+### Added
+- Initial open-source release of DocMirror
+- 8 format adapters: PDF, Image, Word, Excel, PowerPoint, Email, Web, Structured
+- Core extraction engine with PyMuPDF and pdfplumber backends
+- OCR support via RapidOCR (ONNX Runtime)
+- Layout analysis with DocLayout-YOLO and rule-based fallback
+- Multi-strategy table extraction (character-based, PDFPlumber, RapidTable, VLM)
+- Formula recognition via LaTeX-OCR
+- PDF forgery & tamper detection (ELA + metadata analysis)
+- VLM integration via Ollama HTTP API
+- Middleware pipeline: SceneDetector, EntityExtractor, ColumnMapper, Validator, Repairer
+- Redis-based parse result caching
+- `pyproject.toml` with modular optional dependencies
+- Test suite (28 tests) with pytest
+- GitHub Actions CI/CD (lint, test on Python 3.10-3.13, build)
+- Apache 2.0 license

docmirror-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,54 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**docmirror-conduct@googlegroups.com**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

docmirror-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing to DocMirror
+
+Thank you for your interest in contributing to DocMirror! This guide will help you get started.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/valuemapglobal/docmirror.git
+cd docmirror
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+# .venv\Scripts\activate   # Windows
+
+# Install with dev dependencies
+pip install -e ".[dev,all]"
+
+# Verify setup
+pytest tests/ -v
+```
+
+## Development Workflow
+
+1. **Fork** the repository and create a feature branch:
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. **Make changes** — follow the coding standards below.
+
+3. **Run checks** before committing:
+   ```bash
+   ruff check docmirror/        # Lint
+   ruff format docmirror/       # Format
+   pytest tests/ -v             # Test (110 cases)
+   ```
+
+4. **Commit** with [Conventional Commits](https://www.conventionalcommits.org/):
+   ```
+   feat: add new PDF table extraction strategy
+   fix: correct column alignment for merged cells
+   docs: update README with new configuration options
+   chore: update dependencies
+   ```
+
+5. **Submit a Pull Request** against `main`.
+
+## Coding Standards
+
+- **Python 3.10+** — use modern syntax (`match/case`, `X | Y` unions)
+- **Type hints** on all public functions
+- **English** for all comments, docstrings, and variable names
+- **Docstrings** in Google style for public API
+- **Line length** — 120 characters max (enforced by ruff)
+
+## Project Structure
+
+```
+docmirror/
+├── adapters/       # Format-specific adapters (PDF, Image, Office, ...)
+│   ├── pdf/        # PDF adapter with multi-strategy extraction
+│   ├── image/      # Image adapter with OCR
+│   ├── office/     # Word, Excel, PowerPoint adapters
+│   ├── web/        # HTML and Email adapters
+│   └── data/       # Structured data (JSON, XML, CSV)
+├── configs/        # Settings, pipeline registry, domain registry
+├── core/           # Core engines
+│   ├── extraction/ # Extraction, pre-analysis, quality routing
+│   ├── layout/     # Layout analysis (DocLayout-YOLO, graph router)
+│   ├── ocr/        # RapidOCR, formula recognition, seal detection
+│   ├── table/      # Multi-strategy table extraction
+│   ├── security/   # Forgery detection
+│   └── output/     # Markdown export, visualization
+├── framework/      # Dispatcher, orchestrator, cache, base classes
+├── middlewares/    # Pipeline middlewares
+│   ├── detection/  # Scene, institution, language detection
+│   ├── extraction/ # Entity extraction
+│   ├── alignment/  # Header alignment, amount splitting
+│   └── validation/ # Trust scoring, mutation analysis
+├── models/         # Data models
+│   ├── entities/   # PerceptionResult, EnhancedResult, domain models
+│   ├── construction/ # Builder pattern for result assembly
+│   └── tracking/   # Mutation tracking
+├── plugins/        # Domain plugins (bank_statement, ...)
+└── server/         # FastAPI server
+```
+
+## Adding a New Adapter
+
+1. Create `docmirror/adapters/your_format/your_format.py`
+2. Subclass `BaseParser` from `docmirror.framework.base`
+3. Implement `to_base_result(file_path) -> BaseResult`
+4. Register in the dispatcher's `_get_parser()` method
+5. Add tests in `tests/test_your_format.py`
+
+## Adding a New Middleware
+
+1. Create `docmirror/middlewares/your_category/your_middleware.py`
+2. Subclass `BaseMiddleware` from `docmirror.middlewares.base`
+3. Implement `process(result: EnhancedResult) -> EnhancedResult`
+4. Register in `docmirror/configs/pipeline_registry.py`
+5. Add tests
+
+## Reporting Issues
+
+- Use [GitHub Issues](https://github.com/valuemapglobal/docmirror/issues)
+- Include: Python version, OS, DocMirror version, minimal reproduction steps
+- For document parsing issues, include a sample file if possible (redact sensitive data)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).

docmirror-0.2.0/Dockerfile

@@ -0,0 +1,56 @@
+# Stage 1: Build & Dependencies
+FROM python:3.10-slim AS builder
+
+# Install system build dependencies required for compiling Python packages and OpenCV/ONNX
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy dependency files AND source code (required for editable/local wheel builds)
+COPY pyproject.toml README.md ./
+COPY docmirror/ docmirror/
+
+# Force pip to build wheels for the heavy dependencies locally (if needed)
+RUN pip install --upgrade pip
+RUN pip wheel --no-cache-dir --no-deps --wheel-dir /app/wheels \
+    ".[all,server]"
+
+# Stage 2: Runtime Environment
+FROM python:3.10-slim
+
+# Install runtime C++ libraries required by OpenCV (rapidocr) and ONNX Runtime
+# Also install curl for healthcheck
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglib2.0-0 \
+    libgomp1 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy the pre-built wheels from the builder stage
+COPY --from=builder /app/wheels /wheels
+
+# Copy the actual application source code
+COPY . .
+
+# Install the application and all its heavy dependencies (PDF, OCR, Layout, Table, Server)
+RUN pip install --no-cache-dir --find-links=/wheels ".[all,server]"
+
+# Expose the FastAPI default port
+EXPOSE 8000
+
+# Optional: define volume for model caching (speed up rapidocr models download)
+VOLUME ["/root/.cache"]
+
+# Healthcheck for container orchestration
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the Uvicorn ASGI server
+CMD ["uvicorn", "docmirror.server.api:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]