OneOffTech Parxy

Parxy is a document processing gateway providing a unified interface to interact with multiple document parsing services, exposing a unified flexible document model suitable for different levels of text extraction granularity.

• Unified API to parse documents with different providers
• Unified flexible hierarchical document model (page → block → line → span → character)
• Supports both local libraries (e.g., PyMuPDF, Unstructured) and remote services (e.g., LlamaParse, LLMWhisperer, PdfAct)
• Extensible: easily integrate new parsers in your own code
• Trace the execution for debug purposes
• Pair with evaluation utilities to compare extraction results (coming soon)

Note

Parxy is being rewritten from the ground up. Versions 0.6 and below are preserved in the legacy branch for historical purposes. The main branch contains the rewrite, which focuses on library and CLI usage. If you still need the HTTP API, continue using version 0.6.

Requirements

• Python 3.12 or above (Python 3.10 and 3.11 are supported on best-effort).

Next steps

• Getting started
  • The Parxy CLI
  • Install the library in your application
• Supported document processing services
• Personalize drivers

Getting started

Parxy is available as a standalone command line and a library. The quickest way to try out Parxy is via command line using uvx.

Use with minimal footprint (fewer drivers supported):

uvx parxy --help

Use all supported drivers:

uvx parxy[all] --help

See Supported services for the list of included drivers and their extras for the installation.

Use on the command line

to be documented

Use as a library in your project

to be documented

1. Install, all or the driver you need

2. Add the env variables when needed

3. Call the driver

from parxy_core.facade import Parxy

# Using the default driver, usually pymupdf
Parxy.parse('path/to/document.pdf')

# Using a specific driver
Parxy.driver(Parxy.LLAMAPARSE).parse('path/to/document.pdf')

Supported services

Service or Library	Support status	Extra	Local file	Remote file
PyMuPDF	Live	-	✅	✅
PdfAct	Live	-	✅	✅
Unstructured library	Preview	unstructured_local	✅	✅
LlamaParse	Preview	llama	✅	✅
LLMWhisperer	Preview	llmwhisperer	✅	✅
Unstructured.io cloud service	Planned
Chunkr	Planned
Docling	Planned

...and more can be added via the live extension!

Live extension

Live Extension allow to add new drivers or create custom configuration of the current drivers directly in your app code.

1. Create a class that inherits from Driver

from parxy_core.drivers import Driver
from parxy_core.models import Document

class CustomDriverExample(Driver):
    """Example custom driver for testing."""

    def _handle(self, file, level="page") -> Document:
        return Document(pages=[])

2. Register it in Parxy using the extend method

Parxy.extend(name='my_parser', callback=lambda: CustomDriverExample())

3. Use it

Parxy.driver('my_parser').parse('path/to/document.pdf')

Contributing

Thank you for considering contributing to Parxy! You can find how to get started in our contribution guide.

Development

Parxy uses UV as package and project manager.

1. Clone the repository
2. Sync all dependencies with uv sync --all-extras

All Parxy code is located in the src directory:

• parxy_core contains the drivers implementations, the models and the facade and factory to access Parxy features
• parxy_cli contains the module providing the command line interface

Optional Dependencies vs Dependency Groups

Parxy uses optional dependencies to track user oriented dependencies that enhance functionality. Dependency groups are reserved for development purposes. When supporting a new driver consider defining it's dependencies as optional to reduce Parxy's footprint.

The question What’s the difference between optional-dependencies and dependency-groups in pyproject.toml? give a nice overview of the differences.

Testing

Parxy is tested using Pytest. Tests, located under tests folder, run for each commit and pull request.

To execute the test suite run:

uv run pytest

You can run type checking and linting via:

uv run ruff check

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Supporters

The project is provided and supported by OneOff-Tech (UG) and Alessio Vertemati.

Licence and Copyright

Parxy is licensed under the GPL v3 licence.

• Copyright (c) 2025-present Alessio Vertemati, @avvertix
• Copyright (c) 2025-present Oneoff-tech UG, www.oneofftech.de
• All contributors