Skip to main content

parsosaur

Convert academic PDFs to JSON, TEI XML, and HTML.

Synopsis

parsosaur [OPTIONS] DIR ...

Description

Parsosaur extracts text, tables, figures, and bibliographic metadata from academic PDFs. Each input directory must contain exactly one PDF and at most one GROBID TEI file with a .tei or .tei.xml suffix. The TEI file supplies context for image interpretation and metadata for bibliographic merging.

New parses require Linux x86-64, Python 3.10–3.13, a CUDA GPU, and an OpenAI-compatible vision-model endpoint. Nemotron performs layout extraction locally. PDF crops and prompts are sent to the selected endpoint.

The NVIDIA runtime and model are downloaded from a fixed Hugging Face revision on first use. Allow several gigabytes of disk space for dependencies and model files.

Outputs are written to DIR/out/. Existing compatible results are reused; complete cached results require neither GPU inference nor endpoint requests. Use --force to regenerate results after changing inputs or options.

Installation

From a source checkout, install and run Parsosaur with uv:

uv sync --locked
uv run parsosaur --help

After publication to PyPI, run it without a checkout:

uvx parsosaur --help

Use uv tool install parsosaur to install a persistent parsosaur command. Alternatively, install it with pip install parsosaur.

After publication, uv run URL [OPTIONS] DIR ... can run the launcher at a raw URL for scripts/run_parsosaur.py. The launcher installs the library version specified in that file.

Options

  • -h, --help displays help and exits.
  • --base-url URL selects the vision-model endpoint. It defaults to LLM_BASE_URL, or https://openrouter.ai/api/v1 if that variable is unset. A URL without a path has /v1 appended.
  • --model MODEL selects the endpoint's model. It is required for OpenRouter. Other endpoints default to the first model returned by their model list.
  • --no-context omits TEI prose from image interpretation requests.
  • --no-merge skips merging bibliographic metadata from the TEI file.
  • --force deletes each input directory's out/ subdirectory and regenerates all results.

Environment

  • LLM_BASE_URL sets the default vision-model endpoint.
  • LLM_API_KEY supplies the endpoint's API key. OPENROUTER_API_KEY is used if LLM_API_KEY is unset. OpenRouter requires a key.
  • HF_HOME sets the Hugging Face cache directory.
  • HF_HUB_OFFLINE=1 restricts model and runtime loading to cached files. It does not disable requests to the vision-model endpoint.

Files

All generated files reside in DIR/out/.

  • document.json, metadata.json, and figures.json contain the structured extraction results.
  • document.tei.xml contains the document in TEI XML format.
  • index.html provides a reading view with source-page highlights.
  • viewer.html displays detected regions on the PDF.
  • pages/, crops/, and raw/ contain rendered pages, extracted images, and intermediate model outputs.
  • merge_report.json records bibliographic merge decisions when merging is enabled and a TEI file is supplied.

Examples

Parse one paper using a local vision-model endpoint:

uvx parsosaur paper/ --base-url http://localhost:8000

Parse several papers using the same endpoint:

export LLM_BASE_URL=http://localhost:8000
uvx parsosaur papers/*/

Exit status

Parsosaur exits with status zero on success and a nonzero status on error. During batch processing, individual paper failures are reported and processing continues with the remaining papers.

License

Parsosaur is distributed under the MIT license. NVIDIA's runtime and model are subject to their upstream license and notices.

Please note that this is experimental research software, and is likely to be rapidly iterated on with no backwards compatibility guarantees. You should also carefully check the outputs to ensure that they are suitable for your usecases.

Metadata

Release files for parsosaur 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for parsosaur 0.1.0
File Size Uploaded Provenance Actions
parsosaur-0.1.0.tar.gz 260.7 kB Without provenance Details for parsosaur-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for parsosaur 0.1.0
File Interpreter ABI Platform Actions
parsosaur-0.1.0-py3-none-any.whl Python 3 none any Details for parsosaur-0.1.0-py3-none-any.whl

Total release size: 341.2 kB

Release files / parsosaur-0.1.0.tar.gz

Download URL parsosaur-0.1.0.tar.gz
Size 260.7 kB
Tags Source
SHA-256 checksum
How to use checksums
993e1861472067b679cd65397c114f1dc2ad0f255366347fbb9909778052d1ce
BLAKE2b-256 checksum
How to use checksums
25d2d40635af5897d6892a50dab0dc6f896c17b5eda921f02c551d081881759d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / parsosaur-0.1.0-py3-none-any.whl

Download URL parsosaur-0.1.0-py3-none-any.whl
Size 80.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
72e24ca8a40c362dc0195c69c44b4914e3d3811e1d8aaf5dc0876c47d02649b2
BLAKE2b-256 checksum
How to use checksums
ceb783847eb45ad5dcec65cfb6bcb9ef117a80cf9ea23300686cacbebf185957
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for parsosaur 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page