Skip to content

Template documents

A Markdown, HTML, XML or text template with typed blanks, filled by models or agents as a flow, cited, checked, cached per blank, edited and verified. Guide: Template documents.

Template documents: Markdown, HTML, XML or text with blanks, each filled by a model or agent.

Kind = Literal['text', 'list', 'number', 'table', 'diagram'] module-attribute

Blank dataclass

One {{ name }} of a template: the prompt that fills it and the shape of its answer.

kind is "text", "list", "number", "table" (rows with columns) or "diagram" (nodes and edges, drawn as Mermaid). agent fills it instead of the document's model: a model port, or a LoopAgent with tools. sources replaces the document's sources for it.

fingerprint()

What changes this blank's answer: its settings and who fills it (for the cache key).

problems()

What is wrong with this blank's definition (empty when it is fine).

BlankResult dataclass

One filled blank: its value, its Markdown and how the checks went.

ok property

True when the value passed every check.

Citation dataclass

One cited phrase: its number, its source, the blank it is in and the words it backs.

Citations dataclass

How cited words appear: a built-in style, or your own cite(words, source, number).

references adds a References list: None takes the style's default (numeric and footnote list them), True or False forces it, or a function (pairs) -> str writes it.

ComposeResult dataclass

The finished document (.text, in the template's format) and how it was made.

.issues lists what is still wrong after the checks and the verifier, by blank ("document" for the whole text); .usage gives calls, tokens and cost per stage.

markdown property

The document text (Markdown for a Markdown template).

ok property

True when nothing is left in issues.

problems property

The blanks that failed their checks, with why.

Editor dataclass

Rewords text blanks so they read as one voice; tables, lists and diagrams stay as filled.

style says how the document should read ("formal, short sentences"). The editor sees only the text blanks, returns only the ones it changes, and is skipped when there are fewer than two text blanks or under min_words words in all. A revision that changes which sources a blank cites, or fails the blank's checks, is rejected and recorded.

identity()

What changes the editor's answer (for the cache key).

revise(plan, state, ctx) async

The changed blank entries and every revision (accepted or not), as plain data.

texts(plan, entries)

The text blanks it would read, or nothing when editing is not worth a call.

Revision dataclass

One change the editor proposed: before, after, and whether the checks let it in.

from_dict(data) classmethod

A revision from to_dict() output.

to_dict()

The revision as plain data (kept in the flow state).

StageUsage dataclass

Model calls, tokens and USD for one stage: "blanks", "editor" or "verifier".

Template

A document (Markdown, HTML, XML or text) with blanks.

A slot with a hint ({{ summary | "two sentences" }}) or a Blank of that name is a blank; {{ references }} marks where the References list goes; any other name is an input given to compose. A blank's prompt may use other blanks: those fill first, and blanks that do not depend on each other fill in parallel. format is detected from the text when not given.

Raises:

Type Description
FlowDefinitionError

every problem found (bad names, duplicates, cycles), together.

layers()

Blank names grouped by depth: every blank in a layer can fill in parallel.

load(path, blanks=(), **options) classmethod

A template from a file; its format comes from the extension, its name from the stem.

missing_inputs(inputs)

The inputs the template uses that inputs does not give.

reading_order()

Blank names in the order they first appear in the text, then helper blanks.

render(rendered, inputs)

The document with blanks (already drawn) and inputs (escaped) filled in.

users(name)

The blanks whose prompts use name.

Verifier dataclass

Checks the finished document; on by default.

Code checks always run: the document is well formed, every blank is filled, every cited id is known and the reference numbers match. With a model (a small one will do), one call checks each cited phrase against about window characters of its source, and the rules; each blank with an issue is filled again once, alone, then checked again.

check(plan, state, ctx) async

Redone blank entries, and the issues still left after one redo.

claims(plan, entries, names)

Each cited phrase in names, with a short excerpt of the source it cites.

identity()

What changes the verifier's answer (for the cache key).

messages(plan, entries, names)

The one request for names, or no messages when there is nothing to ask.

review(plan, entries, names, ctx) async

The issues the model found, by blank.

check_value(blank, value, known=None)

Every problem with a blank's value; known are the source ids it may cite.

compose(template, *, model=None, inputs=None, sources=(), retriever=None, top_k=TOP_K, citations='numeric', editor=True, verifier=True, max_usd=None, blanks=(), format=None, executor=None, runner=None, ctx=None, thread_id='', concurrency=4, on_blank=None, cache_scope='thread', cache_ttl=None) async

Fill every blank (independent ones in parallel), edit, verify, and return the document.

template is a Template, a file path (format from the extension) or template text. model fills each blank with no agent of its own, and is the default editor and verifier. Each blank sees only its hint, the blanks it uses and the best top_k passages of sources (or of retriever); citations draws what it cites. max_usd stops the run once it costs that much. on_blank(result) (sync or async) gets each blank as it fills. Blanks are cached by what they depend on (cache_scope on the executor's cache; "thread" needs a thread_id).

Raises:

Type Description
ToolUsageError

an input is missing, a ctx has no run id, or a bad option.

FlowError

a blank's model or agent call failed.

BudgetExceeded

the run went over max_usd.

compose_sync(template, **options)

compose() from sync code (it runs the coroutine on a private loop if one is running).