std.document

std.document separates what a report contains from how it is laid out. A model fills a typed Report struct — title, takeaways, sections, conclusion — and a pure function render turns it into markdown. Section and table placement is structural, so you never regex-repair freeform model markdown again.

from std.document import Report, render

Why it exists

The classic failure mode of “ask a model for a markdown report” is that the model controls the structure as well as the content, so you end up parsing and repairing its output. Codebases grow an assemble_basic_answer / _assemble_report layer for exactly this. std.document inverts the control: the model supplies typed fields, and rendering is a deterministic Sema function you own. This is the standard-library face of documentation-as-artifact (spec §5.47) — structure lives in the language, prose comes from the model.

The Report type

A Report is a flat struct of typed fields:

Field	Type	Meaning
title	str	Document title (rendered as #)
context	str	Italic lead-in under the title
confidence	f64	Confidence in [0,1]; < 0 omits the confidence section
rationale	str	Prose shown alongside the confidence
takeaways	list[str]	Bulleted key points
section_titles	list[str]	Table-of-contents entries
sections_text	str	The rendered body sections
conclusion	str	Closing section

Rendering

render(r, nl) produces the markdown. The second argument, nl, is the newline separator — parametrized so the same renderer emits real newlines for output or a single-line form for tests:

from std.document import Report, render

r = Report(
    title="Market Scan: Edge Inference",
    context="Prepared for the Q3 review.",
    confidence=0.87,
    rationale="Corroborated across three independent sources.",
    takeaways=["Latency is the dominant cost", "On-device wins for privacy"],
    section_titles=["Landscape", "Costs"],
    sections_text="## Landscape\n...\n## Costs\n...",
    conclusion="Edge inference is viable for the target latency budget.",
)

md = render(r, "\n")     # real newlines for output

Set confidence = -1.0 to drop the confidence block entirely — handy when a report is qualitative and a percentage would be misleading:

qualitative = Report(title="Notes", context="", confidence=-1.0, rationale="",
                     takeaways=["..."], section_titles=[], sections_text="",
                     conclusion="...")

Let a model fill it, not format it

Pair Report with a simulate def that returns the typed fields under a sem descriptor. The model reasons about content; render guarantees the layout. For the end-to-end pattern, see the Documents guide.

fmt1 for one-decimal display

The module also exposes fmt1, which formats a number to exactly one decimal place (e.g. 87.0 → "87.0"); render uses it to print the confidence percentage.

See the full field and function reference in the generated std.document API reference.