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.
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.
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.
Revision
dataclass
¶
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 |
FlowError
|
a blank's model or agent call failed. |
BudgetExceeded
|
the run went over |
compose_sync(template, **options)
¶
compose() from sync code (it runs the coroutine on a private loop if one is running).