Skip to content

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:

  1. Declare an intermediate struct. Each call site defines a Go struct whose fields carry both json and toon tags. For example, the compliance agent parses into ToonComplianceAnalysis, with the fields compliance_status, violations, audit_trail and spoken_response.
  2. Parse. ai.NewToonOutputParser[T]() returns a parser, and Parse returns a value of type T, not a pointer. The parser uses the toon-go library.
  3. 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]: or objects[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, columns and filter, 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_2d JSON. 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=true enables 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.