docgun 0.2.1

Deterministic document ingestion for PDF, DOCX, Excel, and CSV with quality-aware recovery.

DocGun

Quality-aware document ingestion for Python and RAG pipelines.

Package name: docgun
Project name: DocGun
Install: pip install docgun
Import: from docgun import ingest

DocGun turns PDF, DOCX, Excel, and CSV files into a consistent typed document model. It combines deterministic parsing with extraction scoring, page-aware fallback, security limits, and explicit recovery states so incomplete scans do not silently look successful.

• Native PDF text, coordinates, tables, and page provenance with PyMuPDF.
• Ordered DOCX headings, paragraphs, lists, and tables.
• Bounded XLSX/XLSM and batched CSV extraction.
• Page-level Docling fallback with structured elements and provenance.
• Injectable OCR/VLM recovery for only the pages that need it.
• Measurable confidence reports and structured recovery attempts.
• ZIP/Open XML validation, encrypted-PDF detection, and ingestion limits.
• Python API, CLI, and FastAPI upload route.
• TXT, Markdown, HTML, JSON, XML, and PowerPoint support.
• Pluggable batched vectorization and bounded concurrent ingestion.

---

Before / After

from docgun import ingest

state = ingest("mixed-report.pdf")

print(state.status)
print(state.quality.confidence)
print(len(state.document.elements))

Example output:

completed
0.9142
47

When a scan cannot be recovered, DocGun returns recovery_required with page-level markers and diagnostics instead of presenting an empty page as successfully ingested.

---

Why Quality-Aware Ingestion?

Document parsers can return technically valid but incomplete output: a scanned page may yield only a footer, a fallback may omit pages, or a table detector may consume nearby text. DocGun makes those failure modes visible:

Input document
  -> Validate size, signature, archive safety, and encryption
  -> Inspect pages or workbook dimensions
  -> Route to a deterministic native parser
  -> Score content, structure, tables, and provenance
  -> Compare page-level fallback candidates
  -> Recover only weak pages with Docling or an OCR/VLM backend
  -> Return typed elements, status, quality, warnings, and diagnostics

Pipeline statuses are completed, partially_completed, recovery_required, and failed.

---

Install

pip install docgun

For Docling and the complete fallback toolset:

pip install "docgun[full]"

For development:

pip install -e ".[dev,full]"
pytest -q
python -m build

---

Quick Start

Ingest a Document

from docgun import ingest

state = ingest("annual-report.pdf")

for element in state.document.elements:
    print(element.type, element.text, element.location)

Inspect Recovery Diagnostics

for attempt in state.recovery_attempts:
    print(attempt.action, attempt.status, attempt.error_message)

Configure Page-Level Vision Recovery

Implement extract_batch(rendered_pages) in your OCR or VLM adapter and inject it into the pipeline:

from docgun.agents.recovery import RecoveryEngine
from docgun.agents.vision import VisionPageRecovery
from docgun.pipeline.graph import ingest

class MyVisionBackend:
    def extract_batch(self, pages):
        return vision_client.extract(pages)

engine = RecoveryEngine(VisionPageRecovery(MyVisionBackend()))
state = ingest("scan.pdf", recovery_engine=engine)

Each backend result may contain text, type, table, bbox, and confidence fields.

---

CLI

Ingest a file and print the complete pipeline state as JSON:

docgun report.pdf

Print a compact summary:

docgun report.pdf --summary

---

Supported Formats

Format	Native parser	Recovery
PDF	PyMuPDF	Docling, then configured page-level OCR/VLM
DOCX	python-docx	Explicit low-confidence status
XLSX/XLSM	openpyxl	Explicit low-confidence status
CSV	PyArrow	Explicit low-confidence status
TXT/Markdown/HTML/JSON/XML	Safe structured-text parser	Explicit low-confidence status
PPTX	python-pptx	Layout and reading-order inference

Vectorization and bulk ingestion

from docgun import discover_files, ingest_many, vectorize_document

for item in ingest_many(discover_files("documents"), workers=8):
    if item.state and item.state.document:
        records = vectorize_document(item.state.document)

vectorize_document uses deterministic local embeddings by default. Pass a callable embedding backend for production models.

The CLI accepts directories and uses concurrent workers:

docgun ./documents --workers 8 --summary

---

Architecture

src/docgun/
  __init__.py          # Public API
  cli.py               # Command-line interface
  agents/              # Inspection, routing, confidence, quality, recovery
  api/                 # FastAPI upload route
  chunking/            # Hierarchical and spreadsheet chunk helpers
  domain/              # Typed elements, inspections, and errors
  parsers/             # PDF, Docling, DOCX, Excel, and CSV parsers
  pipeline/            # Orchestration state and policies
  security/            # File limits and format validation
  storage/             # Document and vector storage interfaces
tests/                 # Unit and regression tests
.github/workflows/     # CI and trusted PyPI publishing
CHANGELOG.md            # Release history
pyproject.toml          # Package metadata and dependencies

---

FastAPI

The bundled route streams uploads to a bounded temporary file, maps ingestion errors to appropriate HTTP responses, and removes the temporary file after success or failure.

from fastapi import FastAPI
from docgun.api.routes import router

app = FastAPI()
app.include_router(router, prefix="/documents")

---

Development

pip install -e ".[dev,full]"
python -m pytest
python -m build
python -m twine check dist/*

---

License

MIT

---

Contributing

Contributions are welcome. Please include a representative document or minimal generated fixture, the expected elements, and a regression test for parser or recovery changes.

---

Citation

@software{DocGun2026,
  title={DocGun: Quality-Aware Document Ingestion for Python},
  author={Arkay92},
  url={https://github.com/Arkay92/DocGun},
  year={2026},
  version={0.2.0},
}

---

Acknowledgments

• PyMuPDF for fast native PDF extraction and rendering.
• Docling for layout-aware document conversion.
• python-docx and openpyxl for Office document parsing.
• Apache Arrow for batched CSV ingestion.