Template documents¶
Write the document once with {{ name }} blanks, in Markdown, HTML, XML or plain text.
Each blank is filled by a model or an agent, independent blanks in parallel. Tables and
diagrams come back as data and the code draws them, so the document stays well formed.
An editor makes the wording fit, a verifier checks the result, and sources are cited
(Citations and token use).
Every snippet on this page comes from examples/report_template.py, which runs offline on
a stand-in model.
One line¶
facts = {"company": "Acme", "quarter": "Q3"}
quick = compose_sync(TEMPLATE, model=model, inputs=facts, sources=SOURCES, executor=executor)
print(quick.text.splitlines()[2]) # Revenue grew 12% in Q3 [1], led by Europe.
# a file works too: compose_sync("report.html", ...); in async code, await compose(...)
compose() is the async form. The template can be a file path (report.html,
report.xml, report.md, notes.txt), template text, or a Template.
The template¶
TEMPLATE = """# {{ company }}: {{ quarter }} report
{{ summary | "Summarise the quarter in two sentences." | words(40) }}
## Revenue by region
{{ regions | "Revenue by region, with a short note." | table(Region, Revenue, Note) }}
## How a deal closes
{{ pipeline | "The steps from a lead to a signed deal." | diagram(LR) }}
## Outlook
{{ outlook | "The outlook for next quarter." | words(60) | uses(summary, regions) }}
## Sources
{{ references }}
"""
SOURCES = [
{
"id": "q3-results",
"text": "Q3 revenue was 7.3M, up 12% on Q2. Europe grew fastest.",
"source": {"uri": "https://example.com/q3", "title": "Q3 results"},
},
{
"id": "eu-desk",
"text": "Three new partners in Europe signed in Q3; the pipeline doubled.",
"source": {"uri": "https://example.com/eu", "title": "Europe desk notes"},
},
]
A slot with a hint is a blank: {{ name | "what to write" | option ... }}. Any other
{{ name }} (here company and quarter) is an input you pass in inputs=.
| Option | Means |
|---|---|
"two sentences on the outcome" |
the blank's prompt |
list, number, table(A, B), diagram(LR) |
its kind (text by default) |
words(40) |
at most 40 words |
optional |
may stay empty |
uses(summary, regions) |
fills after those blanks and sees their text |
For more control, pass Blank(name, prompt, kind=, agent=, max_words=, sources=) objects
as blanks=; a prompt may then use {{ other_blank }} directly. A cycle, a bad name or a
bad option is refused when the template is built, with every problem listed together.
{{ references }} marks where the References list goes. \{{ keeps literal braces.
Formats¶
PAGE = """<!DOCTYPE html>
<html><body>
<h1>{{ company }}</h1>
<p>{{ summary | "Summarise the quarter." }}</p>
{{ regions | "Revenue by region." | table(Region, Revenue, Note) }}
{{ pipeline | "From lead to deal." | diagram(LR) }}
</body></html>"""
acme = {"company": "Acme & Co"}
html = compose_sync(PAGE, model=model, inputs=acme, sources=SOURCES, executor=executor)
print(html.format, html.ok, html.text.splitlines()[2]) # <h1>Acme & Co</h1>
FEED = """<?xml version="1.0"?>
<report><summary>{{ summary | "Summarise the quarter." }}</summary>
<regions>{{ regions | "Revenue by region." | table(Region, Revenue, Note) }}</regions></report>"""
xml = compose_sync(FEED, model=model, sources=SOURCES, executor=executor)
print(xml.format, xml.ok) # <cite ref="1">, <row><cell column="...">, <references>
ONE = '{{ summary | "Summarise the quarter." }}'
notes = compose_sync(ONE, model=model, format="text", sources=SOURCES, executor=executor)
print(notes.format, notes.text.splitlines()[0])
The format comes from the file extension or the content, or format=. Inputs and model
text are escaped for it, and blanks are told to write plain text for HTML, XML and text.
Lists, tables and diagrams are drawn per format: a pipe table or <table>, a Mermaid
fence or <pre class="mermaid">, and <item>, <row>, <cell>, <node> and <edge>
elements in XML.
A full run¶
def show(blank: BlankResult) -> None: # a live preview: a UI, a websocket, a log line
done = "edited" if blank.edited else "filled"
print(f"{done} {blank.name} ({blank.kind}, {'ok' if blank.ok else blank.problems})")
cached = executor.replace(cache=aa.MemoryCache())
sent.clear()
result = compose_sync(
TEMPLATE,
model=model,
inputs={"company": "Acme", "quarter": "Q3"},
sources=SOURCES,
editor=Editor(model, style="formal, short sentences", min_words=0), # edit a short draft
max_usd=1.00,
executor=cached,
thread_id="acme-q3", # blanks are cached per thread: a re-run reuses them
on_blank=show,
)
print(result.text)
for revision in result.revisions:
print(f"edited {revision.blank}: {revision.before!r} -> {revision.after!r}")
print("issues:", dict(result.issues) or "none")
ComposeResult field |
What it holds |
|---|---|
.text (.markdown) |
the finished document, in the template's format |
.blanks |
{name: BlankResult}: value, problems, attempts, cached, edited, cost_usd |
.citations |
Citation(number, source, blank, text) for every cited phrase |
.revisions |
every editor revision, accepted or not, with before and after |
.issues / .ok |
what is still wrong, by blank ("document" for the whole text) |
.usage / .cost |
calls, tokens and USD for blanks, editor and verifier |
Checks and the single retry¶
Each blank is checked as it fills: not empty (unless optional), within words, valid
JSON of the right shape, table rows with exactly the columns, diagram edges between known
nodes, and only the source ids it was shown. A failing blank is asked once more, alone,
with its answer and the problems. If it fails again it is kept and listed in issues;
the blanks after it still run.
The editor¶
On by default with the document's model; Editor(model, style="formal") sets the voice
and editor=False turns it off. It reads only the text blanks and returns only the ones
it changes; with one text blank, or under min_words=150 words, it is skipped. Tables,
lists and diagrams stay exactly as filled. A revision that changes which sources a blank
cites, or fails its checks, is rejected and recorded with accepted=False and its
problems.
The verifier¶
verifier = Verifier(model=small_model, rules=["Name the quarter."])
sent.clear()
checked = compose_sync(ONE, model=model, sources=SOURCES, verifier=verifier, executor=executor)
redone = len([r for r in sent if r.stage.endswith(".summary")])
print(f"verifier: {len(checks)} checks, summary written {redone} times, ", end="")
print(f"issues: {dict(checked.issues) or 'none'}")
On by default. Code checks always run: the document is well formed (XML parses, HTML tags
close, Markdown tables keep their shape), every blank is filled, every cited id is known
and the reference numbers match. With sources, the document's model also checks each
cited phrase against its source; Verifier(model=small_model, rules=[...]) uses another
model and adds rules. A flagged blank is written again once, alone, with the issue; what
is left goes to result.issues. verifier=False keeps only the code checks.
Per-blank agents¶
researcher = LoopAgent(model, registry.subset(names=["search_sales"]), instructions="Cite numbers.")
Blank("regions", "Revenue by region.", "table", columns=["Region", "Revenue"], agent=researcher)
Its tool calls run through the executor, so approvals, budgets, guards and the ledger
apply. Give the executor the agent's registry (aa.Executor(registry)).
Cache, preview and events¶
- With a cache on the executor and a
thread_id, each blank is cached by what it depends on: its settings, its model, the blanks and inputs it uses, and its sources. Change one blank and only it, the blanks that use it, the editor and the verifier run again.cache_scope="global"is for public data only;Noneturns caching off. on_blank(result)(sync or async) gets each blank as it fills, and again after an edit or a redo. A failing callback is logged, never raised.- Events:
compose.blank_started,compose.blank_filledandcompose.edited. Texts go only to sinks that capture content.agent-adapter uishows the document filling in.
Things to know¶
- The template compiles to a
Flow(aa_begin, a node per blank,aa_editor,aa_verify).concurrency=4caps blanks in flight;runner=FlowRunner(executor, checkpoints=...)adds checkpoints. Passctx=to compose inside a running tool. - A blank redone by the verifier does not re-run the blanks that used its earlier text.
See also: Citations and token use, Flows, Multi-agent, Caching, See your runs.