Included plugins

Every name a rule can call comes from either the engine itself or a plugin. Five plugins are bound on every execution, by kis rules and by rules.svc alike. One more, the document surface, is loaded only by kis rules today. Nothing else needs installing.

Plugin	Binds	Loaded
util	util, num, strings, time, math, map, array, to, name, date, address	Every execution, every host
log	log	Every execution, every host
findings	findings	Every execution, every host
delivery	delivery	Every execution, every host
vocab	vocab	Every execution, every host
bbox	bbox	kis rules only, on a run that carries a document. rules.svc does not load it

in, out, audit, act and agenda are not plugins. The engine binds them directly on every execution.

Bound on every execution

These five are the batteries-included set. A rule can assume them without the caller configuring anything.

util

One plugin, eleven namespaces. It contributes the whole helper surface in a single registration: util, num, strings, time, math, map, array, to, name, date and address.

Signatures are on strings, map and array, to, num, math and time, and Functions for the rest.

A fact named like a helper

In kis rules and the bare engine, a top-level fact named like one of these namespaces (time, map, strings, …) replaces the helper for that execution, and the first call on it fails (function Len requires no argument). A fact named in, out, findings or audit is replaced by the collector instead, and the caller’s value is lost.

rules.svc refuses both before anything runs: 400 rules-facts-invalid, naming the reserved names (act, address, agenda, array, audit, date, delivery, findings, in, log, map, math, name, num, out, strings, time, to, util, vocab). Send such facts under other names.

log

Binds log, with Debug, Info, Warn and Error. Each takes a message and, optionally, alternating key/value pairs:

rule TraceAmount "log the amount the rules saw" salience 1 {
    when
        in.Has("invoice.total")
    then
        log.Debug("invoice total read", "total", in.Double("invoice.total", 0.0), "currency", in.Str("invoice.currency", ""));
}

Lines go to the host’s log: the terminal for kis rules (at the level --log-level sets, error by default), the service log for rules.svc. They are not part of the result. For a trail that comes back with the result, use audit.

findings

Binds findings, the severity-graded validation channel. Every parameter is a string; there is no struct to construct. rules.svc returns what the rules raised in every response. See Findings.

delivery

Binds delivery, which turns collected results into the shape a particular wire format expects. One method:

Call	Effect
delivery.ExplodeColumn(source, section, column, nameTemplate, count)	Writes one column of a table into exactly count numbered output fields

Parameter	Type	Meaning
source	map	An object holding the table under section, as {"<section>": {"rows": [...]}}
section	string	The key of the table in source
column	string	The column to take from each row. A {"value": …} cell is unwrapped
nameTemplate	string	The output key, with %d for the 1-based index; without one the index is appended after a space
count	int64	How many fields to write

It exists because a flat wire format cannot carry an array: a repeating group, ten alternate names, fourteen employers, has to become a fixed set of numbered scalar columns, and always exactly count of them so the receiving schema keeps a stable shape.

Template	First key produced
"Borrower 2 Name of Employer %d"	Borrower 2 Name of Employer 1
"Alternate Name"	Alternate Name 1

rule FlattenEmployers "three employer columns for the flat export" {
    when
        in.Has("extraction.employment")
    then
        delivery.ExplodeColumn(in.Map("extraction"), "employment", "employer", "Employer %d", 3);
}

facts

{ "extraction": { "employment": { "rows": [
  { "employer": "Acme Corp" },
  { "employer": { "value": "Globex", "confidence": 0.91 } }
] } } }

out

{ "Employer 1": "Acme Corp", "Employer 2": "Globex", "Employer 3": "" }

It writes straight to out; there is nothing to assign. A position past the end of the table is written as the empty string, so the field set is always complete.

Caution

Rows beyond count are dropped. The fixed wire schema is the reason: a stable column set cannot grow with the data. Size count to the largest repeating group the receiving format accepts, and count the rows first if silently losing the tail would matter.

delivery.ExplodeColumn replaces the deprecated out.UnwrapColumn and out.UnwrapColumnWithTemplate, which differed only in whether the name carried a %d.

vocab

Binds vocab: named phrase lists and lookup tables, loaded from the vocabulary files beside the rules. See vocab.

Documents: kis rules only

bbox

Binds bbox, the spatial document surface. rules.svc does not load it: a request carries no document, and a rule set whose rules name bbox does not load there. Document rules run through kis rules today.

kis rules flag	What it loads
--bbox [name=]path	One document, under name (default bbox). Repeatable
--with-bbox	The .bbox file beside each input, under --bbox-name (default page; doc in --mode doc)

bbox.Doc() with no name returns the only loaded document, or the one named page when several are loaded.

bbox is bound only on a run that carries a document. A rule that names bbox on a run that carried none aborts with non existent key bbox, and because a failed evaluation aborts the execution, everything else is discarded with it. Pass a document on every run of a rule set that queries one.

The surface itself is on bbox, Document, Values and Tables and forms.

See also

• Rule API reference: the full list of what is bound
• Functions: every helper signature
• Documents in rules: how a document reaches a rule
• The rules service: what a request carries