API reference
This section is a lookup table, not a guide. Every type, field, constructor and function that the
Rules block puts on its public surface appears here with its exact signature. For how a capability is
used, follow the task pages: writing rules,
documents, the kis CLI and
rules.svc.
The two libraries
Section titled “The two libraries”The block is built from two independent libraries. Nothing in the first imports the second; the document surface reaches rules through a plugin.
| Library | What it holds | Where it surfaces |
|---|---|---|
| Rule engine | The Engine interface, the ruleset store, the execution cycle, and the in / out / findings / audit collectors a rule binds to | kis rules, POST /rule |
| Document library | The spatial type stack — box, word, line, block, page — plus OCR ingest, field and form extraction, tables, matching and confidence scoring | kis ocr, kis bbox, kis hocr2bbox, and the bbox rule namespace |
The rule engine is a thin wrapper over a pinned forward-chaining backend. The backend is named by the
literal string "grule", the rule language is GRL, and rule files carry a .grl extension — those
names are on the interface, so they appear here wherever you must type them.
How this reference is organised
Section titled “How this reference is organised”| Page | Covers |
|---|---|
| Engine | Engine, Config, Result, Plugin, the collectors and the transform registry |
| Findings | Finding, Findings, Severity, the pass/fail rule and the audit trail |
| Document model | Document, BoundingBox, Point, TextBlock, TextLine, geometry, regions, reading order, spatial queries |
| Extraction | Fields, forms, checkboxes, tables, repeaters, master-detail and spread layouts |
| Matching and confidence | Fuzzy matching, anchors, patterns, special regions, fonts, the confidence factor model |
| Text acquisition | ocr.Document and its loaders, text cleanup, domain packs |
The names a rule sees in when and then — in, out, findings, audit and the strings /
map / array / math / time / num namespaces — are enumerated on
Built-in functions.
Find it by task
Section titled “Find it by task”| Goal | Area |
|---|---|
| Know how a rule set is compiled and executed | Engine |
Know what a rule may call in when or then | Built-in functions |
| Read what a run produced | Result on Engine |
| Know the cycle limit and the ruleset version | Fixed limits |
| Turn OCR output into a document | Text acquisition |
| Walk words, lines and blocks; test coordinates | Document model |
| Read a labelled value off a page | Extraction |
| Pull rows out of a table or a grid section | Extraction |
| Match noisy OCR text, or score a result | Matching and confidence |
| Declare an extraction as data rather than code | Schema-driven extraction |
Conventions
Section titled “Conventions”Signatures
Section titled “Signatures”Signatures are copied from the declaration, including receivers and named results:
func (e *Engine) Execute(ctx context.Context, facts map[string]any, ruleset string, pluginData map[string]any) (*engine.Result, error)Names are qualified by the package that declares them — engine.Result, document.BoundingBox,
query.FieldResult. Import paths are omitted throughout.
Some names are Go type aliases rather than distinct types. The document library’s entry package re-exports its core types this way:
type Document = document.Documenttype BoundingBox = document.BoundingBoxAn alias and its target are the same type, so a method documented on one is available through the other. Where a page documents an alias, it names the target.
Errors
Section titled “Errors”Every fallible call returns a plain error as its last result. Errors are wrapped with the operation
that failed and the identifier involved — ruleset %s not found, plugin %s prepare — and carry no
code or type you can switch on. Test them with errors.Is against the wrapped cause, or match the
message.
Constructors that cannot fail return no error at all. Three calls panic instead of returning one:
MustLoadFromFile on the document binding, and the transform registry’s Register and
RegisterParser, which panic on an empty or already-registered name.
rules.svc converts a library error into its own HTTP response shape. The status codes and bodies are
on Errors and limits.
Configuration
Section titled “Configuration”Both libraries carry a Config, and on both documented surfaces every field holds its default. The
kis CLI and rules.svc construct the engine and the document analyser with the shipped defaults
and expose no flag, config key or request field that changes any of them. The cycle cap is 5000 and
the rule-set version is 1.0.0; both are fixed. Where a page lists a Config field, the default it
states is the effective value on every run.
What is left out
Section titled “What is left out”Command binaries, test helpers and the internal scripting-engine bindings are not documented. Where a symbol is exported but not reachable from any documented surface, the page that owns it says so rather than omitting it silently.