Rules editor (S7)
The rules editor edits the validation rules of a validate node as cards, and the condition of a
branch node (and the applies_when of a rule) as groups of checks. It is registered in the Studio
slots validate.rules and branch.condition (web/src/features/rules/); the server side is
POST /v1/rules:validate, :estimate and :test (src/extractit/api/routers/rules.py) over the
engine of T09 (Validation rules).
Rules refer to fields by field_id
The fields a rule can use are those of the schemas of the extract nodes upstream of the node
being edited, read from the canvas store (model/subjects.ts). A rule stores the field_id
(fld_…) of each field it uses; the name is only for display. Renaming a field in the schema editor
therefore never breaks a rule:
{"id": "total-range", "kind": "deterministic",
"check": {"type": "range", "field": "fld_3nf5ktnyr2e60awvxpm8azew43", "min": 0, "max": 100000}}
A reference to a field that no longer exists upstream stays visible, marked, and the server reports
unknown_field_ref (with a suggestion when a name is close). In a CEL expression data.<name> is
accepted and canonicalized by the server to data.<field_id>; the suggestion list inserts ids.
Modes
| Mode | Component | What is saved |
|---|---|---|
| Assisted | AssistedBuilder, CheckForm, GroupBuilder |
one of the 11 deterministic checks — required, range, date, arithmetic, comparison, one_of, regex (RE2), checksum, confidence, evidence, row_count — each with its own typed form, combined with all_of, any_of and not up to three levels |
| CEL | CelEditor |
{"type": "expression", "cel": "..."}. A <textarea> with its own suggestion list (fields by name and field_id, and the functions num, sum, abs) and a legend field_id → name; syntax errors show their line and column |
| AI | AiRuleForm |
kind: "ai" with prompt and source_field_ids (the only fields the judge sees), and the estimated cost per document and in total before anything runs |
Every card also has a severity (error, warning, info), the blocking switch, what to do when the
rule cannot conclude, and applies_when (AppliesWhenEditor: the rule only runs when a condition
holds, otherwise its verdict is skipped). The condition editor (ConditionEditor) is the same
builder with the label If; for a branch node it also says that the false case follows the false
branch, and its output is a plain Check.
Each typed form serializes to the Check of research/06 §9. There is one golden JSON per type in
tests/golden/checks/ that the forms must produce (rules.test.tsx) and that the server accepts
(tests/studio_editors/).
Saving and errors
A card asks the server (POST /v1/rules:validate, 500 ms after the last change) and lists
exactly its errors[] (pointer, rule, message, and position for CEL). A rule with errors
is not saved: it stays in the editor, flagged, and the Studio's configuration keeps the last
version the server accepted. What the server accepts comes back with every reference as a field_id.
POST /v1/rules:validate {"rule": {...}, "context": {"schema": {...}}}
200 {"errors": [{"pointer": "/check", "rule": "invalid_range", "message": "...", "position": null}],
"rule": {...canonical...} | null}
rule codes: invalid_<check> for the model validators of T09 (invalid_range: min > max;
invalid_regex: not RE2), unknown_field_ref, ambiguous_field_ref, syntax_error,
too_short (an empty all_of or one_of), string_pattern_mismatch, invalid_rule
(the fields of the rule do not match its kind). A client-side check reports the same pointers and
codes for what it can see; the corpus tests/golden/invalid-corpus.json verifies the parity.
Testing on documents
Probar en N documentos (N ≤ 20) evaluates the saved rules on the stored results of the chosen
runs, without extracting again, and shows a document × rule table of pass, fail, inconclusive
(a missing field) and skipped (applies_when is false).
POST /v1/rules:test {"rules": [...], "run_ids": ["run_…"], "max_usd": 0.5}
200 {"results": [{"run_id","rule_id","status","detail","compared_values","cited_fields?","cost_usd?"}],
"cost_usd": 0.0123 | null, "estimated_usd": 0.02, "elapsed_ms": 80}
POST /v1/rules:estimate {"rules": [...], "n_documents": 20}
200 {"ai_rules", "documents", "calls", "input_tokens", "output_tokens",
"cost_usd" | null, "per_document_usd" | null, "model", "estimate": true}
Deterministic rules use the pure evaluator and take well under 3 s for 20 runs. AI rules call the
model gateway of the deployment; the document text reaches the prompt only as delimited data. The
estimate is the tokens of the prompt and of the cited fields (about 4 characters per token) times the
input price plus the maximum output times the output price of the capability registry, so it is an
estimate: the real cost comes with the results. When an AI rule would cost money (or the price is
unknown) the editor shows the estimate and asks for confirmation; if max_usd is below the estimate
the server answers 422 budget-exceeded before the first call and nothing is sent to a model.
:test needs workflow:write (it can spend); :validate and :estimate need workflow:read.
Keyboard
Cards reorder with the mouse (handle) and with Alt+↑/↓ in the card header (or the up and down
buttons), duplicate with a button, and delete only after a confirmation. The assisted builder and the
CEL list are operable without a mouse (arrows and Enter in the suggestions).