Skip to content

Your first survey

This page walks through one survey from the command line. You need pydelity installed and your API key set, as in Install pydelity.

Open a terminal in the folder that holds your PDF and run:

Terminal window
pydelity document.pdf

If you know which languages the PDF is in, say so with --language (or -l), once per language. The tags are BCP-47 language tags, such as en for English or ar for Arabic:

Terminal window
pydelity document.pdf -l en -l ar

pydelity first opens and measures the PDF. Then it estimates what the model requests will cost and asks before sending anything. For a 6-page tax form, the output looked like this:

07:05:01 | INFO | Survey cost estimate: about $0.36, at most $2.90 (up to 3 requests to anthropic:claude-opus-5-5)
07:05:01 | INFO | Spent so far in this output folder: $0.00; max_cost: not set
Go ahead with the model requests? [y/N]:

The estimate gives a likely cost and a maximum. The maximum assumes every retry is used and every answer is as long as allowed, so most runs cost much less.

  • Type y and press Enter to go ahead.
  • Press Enter, or type n, to stop. Nothing is sent and nothing is spent. The measured facts are saved, and the next run reuses them.

To skip the question, for example in a script, add --yes. To cap what a PDF may cost, see Control costs.

The model reads the whole PDF in one request. That can take a few minutes for a long PDF. pydelity checks the answer, and if it fails a check, sends it back with the problems listed, up to two more times. Add --verbose to see each step as it happens.

When the run ends, pydelity prints a summary: how the run ended, what it cost, how many review issues it found with the first few listed, and where the output folder is.

The results go to pydelity-output/<PDF name>/ in the current folder, so document.pdf gives pydelity-output/document/. To choose another folder, use --output-dir.

The folder holds:

File What it holds
report.html The results as a page to open in a browser
pdf_facts.json What pydelity measured in the PDF before calling a model
pdf_survey.json The model’s checked answer: page numbers, rotation, regions
run.json How the run went, its settings, cost, warnings and review issues
cost.jsonl One line per model request, with its tokens and cost
uploads.json The PDF’s upload to the provider, so later runs can reuse it
report/pages/ The page images the report shows

Start with report.html. It shows the run and its cost, the review issues, the survey’s results, the measured facts and each page with the model’s regions and any form fields drawn on it. Read the outputs explains each file and what to check.

Running the same command again reuses the saved survey and costs nothing, as long as the PDF and the settings that affect the survey are unchanged. Rerun and resume explains when pydelity redoes the survey.