Basic usage

This guide covers the common path: convert a PDF or Markdown file, inspect the archive, then search it from the CLI or Python.

Step 1 — Convert a PDF or Markdown file

vera convert manual.pdf manual.vera --model hashing
vera convert notes.md notes.vera --model hashing

Directory conversion writes each .vera beside its source file:

vera convert ./proposals --recursive

Step 2 — Inspect and validate

vera inspect manual.vera --json
vera validate manual.vera --json

Inspect JSON includes the pipeline ocr diagnostics bag (PyMuPDF ocr_pages, Docling recovery, or {} for Markdown). Text-mode vera inspect omits it.

Step 3 — Search from the CLI

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

Add --context-chunks 1 for neighboring text, --figures for table/chart metadata, or --regions for page bounding boxes.

For readable context instead of machine-readable JSON, use --pretty. It prints headings, source/page citations, complete matching text, requested neighboring chunks, and figure captions:

vera search manual.vera "stormwater detention requirements" --top-k 5 \
  --context-chunks 1 --pretty

Step 4 — Search from Python

from vera_doc import VeraDocument

with VeraDocument.open("manual.vera") as document:
    for result in document.search(
        "stormwater detention requirements",
        mode="hybrid",
        top_k=5,
        context_chunks=1,
    ):
        print(
            result.score,
            result.page_start,
            result.heading_path,
        )
        print(result.text[:200])

Use mode="write" with create() / add() / upsert() when you already have ready-made ChunkRecord objects and do not need PDF conversion.

Step 5 — Search a document library

For a folder of .vera files, build an index once and search the corpus:

vera convert "./library" --recursive
vera index build "./library" --recursive
vera search "./library" "detention requirements" --top-k 5 --json

from vera_doc import VeraCorpus, build_library_index

build_library_index("./library", recursive=True)

with VeraCorpus.open("./library") as corpus:
    results = corpus.search("detention requirements", top_k=5)