Structured output
Every exchange between a model and the FACE backend is TOON (Token-Oriented Object Notation), with one documented exception for vision detection. FACE uses no JSON-schema wrappers and no LLM orchestration framework.
Why TOON
TOON is an indentation-based object notation with compact tabular arrays. For record-shaped answers, such as a list of violations, findings or scenarios, the column names are declared once in a header rather than repeated per row. That takes fewer tokens to generate and gives the model less structure to get wrong. It matters on a sovereign, often CPU-bound model plane, where generation time is the dominant cost.
compliance_status: Warning
violations[2]{category,severity,description,related_rule_id,remediation}:
PII,HIGH,Email column in orders needs masking,R-12,Apply masking policy
Retention,MEDIUM,No retention rule on audit table,R-31,Define a retention window
spoken_response: Two compliance findings need attention.From reply to typed struct
Replies are never unmarshalled straight into generated protobuf messages. The flow has three steps:
- Declare an intermediate struct. Each call site defines a Go struct whose fields
carry both
jsonandtoontags. For example, the compliance agent parses intoToonComplianceAnalysis, with the fieldscompliance_status,violations,audit_trailandspoken_response. - Parse.
ai.NewToonOutputParser[T]()returns a parser, andParsereturns a value of typeT, not a pointer. The parser uses thetoon-golibrary. - Map by hand. The call site maps the struct field by field onto the protobuf response. The model’s output never becomes a wire message without passing through code that names each field.
What the parser tolerates
Small models make predictable formatting mistakes. Model output is parsed into typed records, and the parser repairs common formatting slips without changing any data. Anything that does not parse is not shown as a result.
What the parser refuses
- An empty completion is a failure, not an empty result. If nothing is left after
stripping, which includes a reply that was only a reasoning block, the parser
returns
TOON_PARSE_FAILURE: empty model completion. A model that said nothing is never read as a model that found nothing. - An explicitly empty array is a valid answer.
rules[0]:orobjects[0]{label,material}:means the model found nothing, and that is how a correctly empty frame or rule set is reported. - Ambiguous nesting is refused. If sibling branches disagree about depth, the document is rejected rather than having a structure guessed for it.
Each call site decides what a parse failure means for its own output. Where a failure would otherwise look like a clean result, it surfaces as an error or a stated absence. The compliance agent, for example, doesn’t report “no violations” when the model gave no usable answer.
The Ask answer’s layout: references, never values
The twins call, the one that writes the spoken answer and the action cards, also
writes layout: which blocks the Ask answer shows for the
question, in order. It is a few extra TOON rows in the same answer, not another model
call:
layout[3]{kind,ref,columns,filter}:
table,tracking_exceptions,id carrier delay_hours,late
map,routes,,
answer,,,The prompt lists the references this run holds: the figures its board measured and the rules it measured, its row sources and their columns, its series, its route plan, the decisions whose options were compared, its attachments. The model copies a reference from that list. It never writes a number, a label or a sentence into the layout.
FACE then resolves each block from the run’s own records:
- A reference the run does not hold drops its block. The block is left out and the reason is kept with the layout. Nothing takes its place, least of all the model’s text.
- A layout that carries a value is refused whole. A number in any field, a field
other than
kind,ref,columnsandfilter, or a figure written into a reference (1200,$1,200,at_risk=3) refuses the layout, and the standard layout stands in. A digit inside an id (card-12,attachment:2) is a reference, not a number. - Present, empty and unreadable are three states. A source that was read and holds nothing says why; a source that could not be read says so. Neither is a zero.
- The answer comes first. The first block is one that resolved to something, and never the evidence or what was not checked.
- The spoken answer is still checked. It is the twins answer after the grounding guard: a sentence stating something the data does not hold was already removed.
The layout field is parsed loosely on purpose: a row that carries a number reaches the layout’s own check and is refused there, rather than failing the parse of the whole answer. The resolved layout is stored with the run, so reopening the run reads it back and asks no model.
The one exception: vision detection
One call departs from TOON: cctv.locateInstances, the class-conditioned object
detection step of the vision pipeline. It asks the vision model for boxes in the
model’s own fine-tuned bbox_2d JSON idiom.
The exception exists because of measurements recorded in the repository, not preference. On a photo of five separable pallet stacks:
- The grading question, whether asked in TOON or JSON, with corner or width/height coordinates, returned one box covering 79–96% of the frame. That’s a scene-level classification with a rectangle around it.
- Two changes together produced per-instance boxes. The first was naming the
class, in the singular (“detect each individual pallet stack”, not “every distinct
object”). The second was asking in
bbox_2dJSON. Class-conditioned TOON got part of the way, then degenerated into repeated rows with pinned coordinates.
The scope of the exception is narrow:
- It covers one detection primitive. The reply is matched by a regular expression and parsed into FACE’s own structs immediately.
- Every verdict still travels as TOON. Grading, material, damage grade and severity all come from the TOON grading call.
- It is off by default (
VISION_DETECT_INSTANCES=trueenables it) because it roughly doubles vision time per frame. The recorded measurement on a CPU inference tier was about 20 s for grading plus about 50 s for detection.
See Vision & CCTV for the full pipeline and coordinate handling.
Reading the results
- A successful parse proves shape, not truth. The repairs above keep formatting from discarding an answer. They say nothing about whether the answer is right.
- TOON limits what a model can express; it doesn’t constrain what it says. Boundaries on content are set elsewhere: the determination/expression split on Evidence documents, and the guardrails and judging ladder on Agents & oversight.