Skip to content

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 &amp; 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; None turns 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_filled and compose.edited. Texts go only to sinks that capture content. agent-adapter ui shows the document filling in.

Things to know

  • The template compiles to a Flow (aa_begin, a node per blank, aa_editor, aa_verify). concurrency=4 caps blanks in flight; runner=FlowRunner(executor, checkpoints=...) adds checkpoints. Pass ctx= 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.