Settings and config files
Every pydelity setting can be given in three places:
- as a command-line option, such as
--modelor--max-cost - as a keyword argument to a Python function, such as
model=ormax_cost= - in a JSON or YAML config file
The Configuration reference lists every setting with its type, default and meaning.
Start from an example file
Section titled “Start from an example file”The repository’s
examples/ folder
holds config.yaml and config.json. Each lists every setting at its default
value, with the YAML file explaining each one in a comment. Copy one next to
your PDFs, delete the settings you don’t need to change and edit the rest.
A small config file might look like this:
pdf: reports/annual-report-2025.pdflanguages: [en, fr]max_cost: 5instructions: >- The appendix tables run sideways on landscape pages.Then run:
pydelity --config survey.yamlThe file must end in .json, .yaml or .yml. A setting pydelity does not
know, such as a misspelled name, is an error rather than being ignored.
Which setting wins
Section titled “Which setting wins”When a setting is given in more than one place, the most specific one wins:
- A command-line option or Python keyword argument.
- The config file.
- pydelity’s default.
For example, pydelity other.pdf --config survey.yaml surveys other.pdf, not
the PDF named in the file, and keeps the file’s other settings. The same holds
inside advanced: a Python keyword argument that sets one advanced setting
keeps the file’s other advanced settings.
Relative paths
Section titled “Relative paths”The pdf and output_dir settings are paths.
- In a config file, a relative path is relative to the folder that holds the config file, not the folder you run pydelity from. This lets you keep a config file next to its PDFs and run it from anywhere.
- On the command line or in Python, a relative path is relative to the current folder.
A path starting with ~ means your home folder in both cases.
When output_dir is not set, the output goes to pydelity-output/<PDF name>/
in the current folder, where <PDF name> is the PDF’s file name without .pdf.
Invalid settings
Section titled “Invalid settings”pydelity checks every setting before it opens the PDF or calls a model, and lists all the problems at once:
07:05:40 | ERROR | 2 invalid settings:- max_cost: Input should be greater than 0 (got -1)- modle: not a setting pydelity knowsThe command then exits with code 2. In Python, the same problems raise
pydelity.ConfigError.
Advanced settings
Section titled “Advanced settings”Settings under advanced: tune how pydelity talks to the model. Most runs never
need them.
| Setting | Default | What it changes |
|---|---|---|
advanced.provider_retries |
2 |
Retries after a temporary provider failure, such as a timeout |
advanced.survey.check_retries |
2 |
How often the model may try again after failing the survey checks |
advanced.survey.effort |
high |
How hard the model thinks: low, medium or high |
advanced.survey.max_output_tokens |
32000 |
The longest answer the model may give, thinking included |
advanced.survey.request_timeout_seconds |
900 |
How long to wait for one model request |
advanced.uploads.expiry_hours |
not set | How long the provider keeps the uploaded PDF |
advanced.models |
none | Your own prices for a model |
Lowering effort or check_retries makes a run cheaper and faster, and can
make the answer less reliable. Models and providers
covers retries and uploads, and Control costs covers prices.
On the command line, advanced settings can only come from a config file. In Python, pass them as a nested mapping:
import pydelity
# Only the settings given here change; the rest keep their defaults.result = pydelity.run( "document.pdf", advanced={"survey": {"effort": "medium"}, "provider_retries": 4},)