Multi-step schemas¶
Some fields need other fields first: a summary needs the extracted facts, a
reply needs the customer's name. Declare that with depends_on:
"schema": {
"name": {"type": "string", "extract": true},
"intent": {"enum": ["new_claim", "check_status", "other"]},
"reply": {"type": "string", "free_form": true,
"depends_on": ["name", "intent"],
"instruction": "Reply politely in 1-2 sentences."}
}
Stages¶
The API orders the fields into stages:
- Fields without dependencies run first, all in parallel.
- A field runs as soon as everything it depends on is done. Fields that become ready together run in parallel.
- Cycles and unknown field names are rejected with HTTP 400.
In the example, name and intent run together (stage 1), then
reply (stage 2). The input document is read once for all stages.
What a field sees¶
A field's instruction is shown together with the values of the fields it depends on, directly or indirectly. Other fields are not shown, even if they already finished. This keeps unrelated values out of the answer: a field that should read a price from search results cannot copy a price from another field it does not depend on.
To keep a value out of later prompts even though it is a dependency (for
example an ID number used only as a gate), add a drop rule to it:
The value still appears in result.
Gates¶
A common pattern is a check that must pass before the rest runs:
"policy_number": {"type": "string", "nullable": true,
"on": [{"when": {"len_lt": 16}, "do": "reject"}, {"do": "drop"}]},
"name": {"type": "string", "depends_on": ["policy_number"]},
"reply": {"type": "string", "free_form": true, "depends_on": ["name"],
"on_reject": "The policy number must be 16 digits."}
A reject cancels its own stage
When a rule rejects the request, every field of the same stage gets
its on_reject value (default null), even if it was already filled.
Put the fields you want to keep in an earlier stage, or put the gate in
a later stage (for example on a computed field).
Streaming and stages¶
With streaming, each event carries a stage number, so you
can show progress stage by stage.