Python API
import pydelity gives these functions and classes. estimate, measure,
run and survey also have async forms, named with an a prefix, to await in
code that runs an event loop.
Functions
Section titled “Functions”estimate
Section titled “estimate”def estimate( pdf: str | PathLike[str] | None = None, *, config: ConfigSource | None = None, **settings: object,) -> CostEstimateEstimate what a run on a PDF would cost (the sync version of aestimate).
Parameters
pdf: The PDF. Overrides apdfinconfig.config: A JSON or YAML config file, apydelity.config.schemas.Config, or a mapping of settings.**settings: Settings by name. They overrideconfig.
Returns
CostEstimate: The expected and largest cost, the output folder’s spend so far, and whether the run would go overmax_cost.
Raises
ConfigError: Listing every invalid setting, or naming a config file that cannot be read.PdfError: If the PDF is empty, password-protected or cannot be opened.RuntimeError: If called while an event loop is running, as in Jupyter or async code. Useawait pydelity.aestimate(...)there instead.
aestimate
Section titled “aestimate”async def aestimate( pdf: str | PathLike[str] | None = None, *, config: ConfigSource | None = None, **settings: object,) -> CostEstimateEstimate what a run on a PDF would cost, writing nothing and calling no model.
The saved facts are used when they match, and otherwise the PDF is measured without saving them. A survey that would be reused costs nothing. No API key is needed.
Parameters
pdf: The PDF. Overrides apdfinconfig.config: A JSON or YAML config file, apydelity.config.schemas.Config, or a mapping of settings.**settings: Settings by name, such asmodel="openai:gpt-6.2-astra". They overrideconfig.
Returns
CostEstimate: The expected and largest cost, the output folder’s spend so far, and whether the run would go overmax_cost.
Raises
ConfigError: Listing every invalid setting, or naming a config file that cannot be read.PdfError: If the PDF is empty, password-protected or cannot be opened.
def load(output_dir: str | PathLike[str]) -> RunResultRead an output folder back as Python objects.
It calls no model, needs no API key and writes nothing, so it works anywhere, including in a running event loop.
Parameters
output_dir: The output folder of an earlierrun,surveyormeasure.
Returns
RunResult: The folder’srun.json,pdf_facts.json,pdf_survey.jsonandcost.jsonl. A part isNone, or an empty ledger, when its file is absent.
Raises
OutputError: If the folder does not exist, holds none of those files, or holds one that is not valid JSON, does not match its schema or has another major schema version.
measure
Section titled “measure”def measure( pdf: str | PathLike[str] | None = None, *, config: ConfigSource | None = None, **settings: object,) -> PdfFactsMeasure a PDF and save pdf_facts.json (the sync version of ameasure).
Parameters
pdf: The PDF. Overrides apdfinconfig.config: A JSON or YAML config file, apydelity.config.schemas.Config, or a mapping of settings.**settings: Settings by name. They overrideconfig.
Returns
PdfFacts: The facts, as saved inpdf_facts.json.
Raises
ConfigError: Listing every invalid setting, or naming a config file that cannot be read.PdfError: If the PDF is empty, password-protected or cannot be opened.RuntimeError: If called while an event loop is running, as in Jupyter or async code. Useawait pydelity.ameasure(...)there instead.
ameasure
Section titled “ameasure”async def ameasure( pdf: str | PathLike[str] | None = None, *, config: ConfigSource | None = None, **settings: object,) -> PdfFactsMeasure a PDF and save pdf_facts.json, or reuse the saved facts.
No API key is needed and no model is called. Only the pdf, output_dir and
overwrite settings matter, though every setting is checked.
Parameters
pdf: The PDF. Overrides apdfinconfig.config: A JSON or YAML config file, apydelity.config.schemas.Config, or a mapping of settings.**settings: Settings by name, such asoutput_dir="out/w9". They overrideconfig.
Returns
PdfFacts: The facts, as saved inpdf_facts.json.
Raises
ConfigError: Listing every invalid setting, or naming a config file that cannot be read.PdfError: If the PDF is empty, password-protected or cannot be opened.
def run( pdf: str | PathLike[str] | None = None, *, allow_over_max_cost: bool = False, config: ConfigSource | None = None, **settings: object,) -> RunResultRun pydelity on a PDF (the sync version of arun).
Parameters
pdf: The PDF to process. Overrides apdfinconfig.allow_over_max_cost: Whether to continue, with a warning, when the run could exceedmax_cost. If false, such a run raisesBudgetExceededErrorinstead.config: A JSON or YAML config file, apydelity.config.schemas.Config, or a mapping of settings.**settings: Settings by name, such asmodel="openai:gpt-6.2-astra"oradvanced={"survey": {"effort": "medium"}}. They overrideconfig.
Returns
RunResult: The run’s record, facts, survey and the output folder’s ledger.
Raises
BudgetExceededError: If the run could go overmax_costandallow_over_max_costis not set.ConfigError: Listing every invalid setting, or naming a config file that cannot be read.MissingApiKeyError: If the selected provider’s API key is not set.PdfError: If the PDF is empty, password-protected or cannot be opened.ProviderError: If the provider rejects the upload for an invalid API key or as too large, or a request fails after the provider retries.RuntimeError: If called while an event loop is running, as in Jupyter or async code. Useawait pydelity.arun(...)there instead.SurveyError: If the model refuses, runs out of output tokens, or never gives an answer that matches the survey’s answer format.
async def arun( pdf: str | PathLike[str] | None = None, *, allow_over_max_cost: bool = False, config: ConfigSource | None = None, **settings: object,) -> RunResultRun pydelity on a PDF.
The run validates the settings, opens the PDF and measures it, or reuses the
facts saved in pdf_facts.json in the output folder. It then reuses the survey
saved in pdf_survey.json when its inputs are unchanged. Otherwise it checks
the provider’s API key and the cost estimate against max_cost, uploads the PDF
(or reuses its upload from uploads.json), asks the model to survey it and
saves pdf_survey.json. It records the run in run.json and report.html,
also when it fails or stops, and does not prompt for input.
Parameters
pdf: The PDF to process. Overrides apdfinconfig.allow_over_max_cost: Whether to continue, with a warning, when the run could exceedmax_cost. If false, such a run raisesBudgetExceededErrorinstead.config: A JSON or YAML config file, apydelity.config.schemas.Config, or a mapping of settings.**settings: Settings by name, such asmodel="openai:gpt-6.2-astra"oradvanced={"survey": {"effort": "medium"}}. They overrideconfig.
Returns
RunResult: The run’s record, facts, survey and the output folder’s ledger.
Raises
BudgetExceededError: If the run could go overmax_costandallow_over_max_costis not set.ConfigError: Listing every invalid setting, or naming a config file that cannot be read.MissingApiKeyError: If the selected provider’s API key is not set.PdfError: If the PDF is empty, password-protected or cannot be opened.ProviderError: If the provider rejects the upload for an invalid API key or as too large, or a request fails after the provider retries.SurveyError: If the model refuses, runs out of output tokens, or never gives an answer that matches the survey’s answer format.
survey
Section titled “survey”def survey( pdf: str | PathLike[str] | None = None, *, allow_over_max_cost: bool = False, config: ConfigSource | None = None, **settings: object,) -> PdfSurveyRun the survey step alone (the sync version of asurvey).
Parameters
pdf: The PDF. Overrides apdfinconfig.allow_over_max_cost: Whether to continue, with a warning, when the survey could exceedmax_cost. If false, such a survey raisesBudgetExceededErrorinstead.config: A JSON or YAML config file, apydelity.config.schemas.Config, or a mapping of settings.**settings: Settings by name. They overrideconfig.
Returns
PdfSurvey: The survey, as saved inpdf_survey.json.
Raises
BudgetExceededError: If the survey could go overmax_costandallow_over_max_costis not set.ConfigError: Listing every invalid setting, or naming a config file that cannot be read.MissingApiKeyError: If the selected provider’s API key is not set.PdfError: If the PDF is empty, password-protected or cannot be opened.ProviderError: If the provider rejects the upload for an invalid API key or as too large, or a request fails after the provider retries.RuntimeError: If called while an event loop is running, as in Jupyter or async code. Useawait pydelity.asurvey(...)there instead.SurveyError: If the model refuses, runs out of output tokens, or never gives an answer that matches the survey’s answer format.
asurvey
Section titled “asurvey”async def asurvey( pdf: str | PathLike[str] | None = None, *, allow_over_max_cost: bool = False, config: ConfigSource | None = None, **settings: object,) -> PdfSurveyRun the survey step alone and save pdf_survey.json, or reuse the saved one.
It writes pdf_facts.json, pdf_survey.json and the ledger lines of its
requests, but no run.json and no report. It does not prompt for input.
Parameters
pdf: The PDF. Overrides apdfinconfig.allow_over_max_cost: Whether to continue, with a warning, when the survey could exceedmax_cost. If false, such a survey raisesBudgetExceededErrorinstead.config: A JSON or YAML config file, apydelity.config.schemas.Config, or a mapping of settings.**settings: Settings by name, such asmodel="openai:gpt-6.2-astra". They overrideconfig.
Returns
PdfSurvey: The survey, as saved inpdf_survey.json.
Raises
BudgetExceededError: If the survey could go overmax_costandallow_over_max_costis not set.ConfigError: Listing every invalid setting, or naming a config file that cannot be read.MissingApiKeyError: If the selected provider’s API key is not set.PdfError: If the PDF is empty, password-protected or cannot be opened.ProviderError: If the provider rejects the upload for an invalid API key or as too large, or a request fails after the provider retries.SurveyError: If the model refuses, runs out of output tokens, or never gives an answer that matches the survey’s answer format.
Classes and errors
Section titled “Classes and errors”BudgetExceededError: A run would go overmax_costand the caller did not allow it.Config: All the settings for a pydelity run.ConfigError: One or more settings are invalid.CostEstimate: A run’s likely and maximum cost, estimated before it spends anything.MissingApiKeyError: The API key for the selected model provider is missing or empty.OutputError: An output folder, or a file in it, cannot be read back.PdfError: The PDF is empty, password-protected or cannot be opened.PdfFacts: The contents ofpdf_facts.json: the measured facts and their summary.PdfSurvey: The contents ofpdf_survey.json: the checked survey of one PDF.ProviderError: A model provider failed or rejected a request after its retries.PydelityError: Base class for every error pydelity raises deliberately.PydelityWarning: A problem the user should know about that does not stop the run.RunRecord: The contents ofrun.json: one run on one PDF.RunResult: What a run left in its output folder, read back as Python objects.SurveyError: The survey step could not produce a usable answer.