Skip to content

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).