Configuration

Configure the model endpoint, scientific context, and concurrency used to extract knowledge from research PDFs. The runner uses one OpenAI-compatible Chat Completions endpoint with image support. Pages within each document stay ordered; workers limits concurrent documents. Unknown settings are rejected.

Settings

Setting	Default	Purpose
base_url, model	Required	API root and served model ID
api_key_env	OPENAI_API_KEY	Environment variable containing the bearer key; null disables bearer authentication
workers	1	Concurrent documents
temperature	Omitted	Sampling temperature, when supported
reasoning_effort	Omitted	Provider reasoning level, such as low
extra_body	{}	Additional JSON fields merged into the HTTP request body
extra_query	{}	Non-secret query parameters, such as an API version
extra_headers	{}	Non-secret HTTP headers explicitly required by your endpoint
extra_headers_env	{}	Header names mapped to environment variable names, for secret header values
cost_path	Omitted	Object-key path to a numeric request cost in USD in the response, e.g. ["usage", "cost_usd"]
timeout	180	Maximum seconds for one model request
api_retries, format_retries	3, 1	Additional attempts
grobid_url, grobid_timeout	http://127.0.0.1:8070, 180	Service and request timeout
context_chars	12000	Maximum characters of earlier facts supplied while extracting a later page
glossary_chars	6000	Maximum characters of term definitions supplied to the extraction and entity stages
selection_chars	40000	Target maximum characters in each entity-selection request
evidence_snippets	5	Maximum supporting excerpts collected for each entity candidate

Context budgets

As Distils moves through a paper, it reuses some of the information it has already extracted. This helps the model interpret a later page consistently without sending the entire document again. The context settings limit how much of that supporting text is included in each model request.

Earlier facts: context_chars

When extracting a page, Distils can show the model facts found on earlier pages. It starts with the most recent facts and includes as many complete facts as fit within context_chars. A fact is either included in full or left out; Distils does not cut it in the middle to fill the remaining space.

The current page image is still sent separately and is not counted in this limit. Set context_chars to 0 if earlier facts should not be supplied to later pages.

Term definitions: glossary_chars

The glossary is built by the model while it reads the paper; it is not supplied in the input configuration. Its purpose is to keep the meaning and naming of paper-specific terms consistent from one page to the next.

It develops in this order:

1. Distils starts the first page with an empty glossary.
2. While extracting facts, equations, and visual findings from that page, the model can define a term used in those records. A definition contains the term, a short display label, and its scientific meaning.
3. Distils saves these definitions in the document's shared glossary.
4. When the next page is processed, Distils sends the accumulated glossary with the new page image. The model can reuse an existing canonical term and add a new definition when the page introduces one.
5. This repeats page by page, so the glossary grows with the paper. After page extraction, the same glossary helps the entity stages use consistent names and meanings. The entity-identification stage may also add a missing definition.

glossary_chars limits how much of this accumulated glossary is sent in any one model request. Distils includes only complete entries: it never cuts a definition in the middle. When the full glossary is larger than the limit, the most recently added entries are considered first. The complete glossary is still kept in document.json; this setting limits the context sent to the model, not the saved output.

Entity selection: selection_chars and evidence_snippets

After all pages have been processed, Distils reviews the entity candidates found throughout the paper. Each candidate includes its name, type, page numbers, optional glossary definition, and supporting excerpts. evidence_snippets limits the number of excerpts collected for one candidate.

If all candidates do not fit in one request, selection_chars divides them into several batches. A candidate always stays together with its evidence. Distils never splits one candidate between two requests, so a single unusually large candidate can make a batch exceed the target limit.

All four settings count characters, not model tokens. They control selected parts of a request rather than the model's full context window, which also contains instructions, document metadata, and, for page extraction, the current page image.

Endpoint compatibility

No model-specific reasoning or sampling settings are sent by default. Add only options supported by your endpoint. For example, "extra_body": {"max_completion_tokens": 4096} sets an output limit.

The client expects non-streaming Chat Completions with system/user messages, inline JPEG images via image_url, and a text answer with finish_reason: "stop". A model must support these inputs and follow the extraction record format. APIs with different request or response contracts need an adapter. Truncated answers and refusals remain rejected.

Cost reporting

Cost reporting is optional because Chat Completions has no standard dollar-cost field. Set cost_path only when the selected response value is a per-request amount in USD. Token counts use the standard usage.prompt_tokens and usage.completion_tokens fields. Missing or invalid measurements remain unknown (null), including aggregate costs if any request lacks a cost.