Getting started¶

This tutorial installs the VERA CLI, converts one PDF into a portable .vera archive, and searches it.

VERA is currently pre-1.0 and experimental. Preserve source documents and expect format or API changes before a stable release.

Requirements¶

Python 3.10 or newer
A local PDF
Windows, macOS, or Linux

Install from PyPI¶

Install the CLI and its dependencies:

python -m pip install "vera-cli>=0.2.2"

That installs vera-doc and vera-ingest as well. vera-ingest may not yet be published to PyPI; if the install fails because the package cannot be found, install from source instead. Add MCP support with:

python -m pip install "vera-cli[mcp]>=0.2.2"

Verify that the console script is available:

vera --help

If vera is not on PATH, invoke the same CLI as a Python module:

python -m vera_cli --help

Library-only installs¶

# Storage and search only
python -m pip install "vera-doc>=0.2.2"

# PDF conversion and viewer helpers
python -m pip install "vera-ingest>=0.2.2"

# MCP server package
python -m pip install "vera-mcp>=0.2.2"

vera-ingest may not yet be published to PyPI. If that package install fails because it cannot be found, use Install from source.

Install from source¶

Contributors can clone the repository and install workspace packages:

git clone https://github.com/dkylewillis/vera.git
cd vera
python -m pip install ./packages/vera-doc ./packages/vera-ingest ./packages/vera-cli

Or with uv:

uv sync --extra dev
uv run python -m vera_cli --help

Convert a PDF¶

vera convert "manual.pdf" "manual.vera"

The default hashing embedding model is local and has no machine-learning dependency. The resulting archive contains parsed pages, chunks, embeddings, the keyword index, citation metadata, figures, and the original PDF.

If the output path is omitted, VERA uses the input filename with a .vera suffix:

vera convert "manual.pdf"

VERA validates the completed archive before publishing it. Image-based pages with little or no native text are OCR-processed locally by default. English language data is bundled, so default OCR works offline without another installation. Selecting another language with --ocr-language requires its Tesseract data. Use --ocr off to disable recognition or --ocr force to process every page. A failed conversion does not replace an existing destination.

Inspect and validate¶

Inspect the archive:

vera inspect "manual.vera"

Validate integrity:

vera validate "manual.vera"

Both commands accept --json for machine-readable output.

Search with citations¶

vera search "manual.vera" "stormwater detention requirements" --top-k 5 --json

Each result includes page range and heading path for grounded citations. Add --figures, --regions, or --context-chunks 1 when you need visual or neighboring context.