`bbox` — documents

bbox is the document surface. Almost every rule uses exactly one function on it — bbox.Doc() — and the rest of this page is the loading and construction surface around it.

If you are writing a rule that reads a document, you want Document, not this page.

Reaching a document

bbox.Doc(name?) → Doc

Returns the document as the curated rule-facing facade.

Parameter	Type	Meaning
name	string, optional	Which loaded document. Omit for the usual single-document case

The name is optional because it is ceremony. In the production corpus, 3,320 of 3,360 document lookups pass the same string — so the argument earns its place only when a rule genuinely works across more than one loaded document.

rule ClassifyByHeader "identify the form from its header band" salience 100 {
    when
        bbox.Doc().Top(10).Has("Closing Disclosure")
    then
        out.Set("docType", "closing_disclosure");
        Retract("ClassifyByHeader");
}

Everything a rule does with a document starts here and chains: a scope, a verb, a coercion. See Document for the 54 methods on the returned Doc.

bbox.Get(name) → Document

Returns a previously loaded document as the raw document object.

Parameter	Type	Meaning
name	string	The document name

Prefer bbox.Doc()

bbox.Get hands a rule the internal document object and all 344 of its exported methods. That was never a designed surface — it is simply everything the implementation happens to expose, and it changes as the implementation does.

It still works, so existing rules keep running. Write new rules against bbox.Doc(), which is the surface that is designed, documented and stable.

Loading a document

Most deployments hand documents to the engine before rules run, so a rule rarely loads one itself. These exist for rules that genuinely need to reach a second document — a prior version to compare against, a schedule referenced by the main form.

bbox.LoadFromFile(name, path) → Document, error

Loads an OCR document from a JSON file and analyses it.

Parameter	Type	Meaning
name	string	The name to register it under
path	string	Path to the JSON file

A sibling page image with the same basename — .png, .jpg, .jpeg — is attached automatically for single-page documents, which is what enables the visual checks such as Checked.

bbox.LoadFromBytes(name, data) → Document, error

Parameter	Type	Meaning
name	string	The name to register it under
data	bytes	The document JSON

bbox.LoadFromReader(name, r) → Document, error

Parameter	Type	Meaning
name	string	The name to register it under
r	reader	A stream of document JSON

bbox.LoadFromMap(name, data) → Document, error

Loads from a map, which is the shape a caller injecting a document through the CLI produces.

Parameter	Type	Meaning
name	string	The name to register it under
data	map	{"pages": [{"number": 1, "width": 612, "height": 792, "words": [...]}]}

bbox.LoadFromEnv(name, envVar) → Document, error

Loads from a path held in an environment variable.

Parameter	Type	Meaning
name	string	The name to register it under
envVar	string	The environment variable holding the path

bbox.GetOrLoad(name, path) → Document, error

Returns the document if already loaded, otherwise loads it from path.

Parameter	Type	Meaning
name	string	The document name
path	string	Where to load from if absent

The idempotent form, and the right one in a rule that may fire more than once.

bbox.MustLoadFromFile(name, path) → Document

Loads or panics.

Parameter	Type	Meaning
name	string	The name to register it under
path	string	Path to the JSON file

Intended for host initialisation, where a missing document means the run cannot proceed. In a rule, prefer GetOrLoad and branch on the result — a panic takes the whole execution down, including the findings already collected.

Managing what is loaded

bbox.Has(name) → bool

Whether a document with this name is loaded.

Parameter	Type	Meaning
name	string	The document name

rule ComparePriorVersion "only compare when a prior version was supplied" {
    when
        bbox.Has("prior") && bbox.Doc("prior").Has("Loan Amount")
    then
        out.Set("priorAmount", bbox.Doc("prior").Right("Loan Amount").Currency());
}

bbox.Names() → list of string

Every loaded document name. Diagnostic — log it when a named lookup returns nothing.

bbox.Remove(name)

Removes one document.

Parameter	Type	Meaning
name	string	The document to remove

bbox.Clear()

Removes every loaded document.

Both are host-lifecycle operations. A rule that removes the document other rules are about to read is a rule whose ordering now matters in a way nothing else expresses.

Geometry constructors

These build the coordinate and direction values the older document methods take. Rules written against bbox.Doc() need none of them — Top(10), Right("Label") and Region(...) take plain numbers and strings.

bbox.Box(x0, y0, x1, y1) → BoundingBox

Parameter	Type	Meaning
x0, y0, x1, y1	float64	The rectangle’s corners

bbox.Pt(x, y) → Point

Parameter	Type	Meaning
x, y	float64	The coordinates

bbox.Dir(name) → Direction

Parameter	Type	Meaning
name	string	"right", "left", "above" or "below"

bbox.RelDir(name) → RelativeDir

Same vocabulary, for the methods that take a relative direction.

Parameter	Type	Meaning
name	string	"right", "left", "above" or "below"

bbox.GeoBox(x0, y0, x1, y1) → Box · bbox.GeoDir(name) → Direction

The geometry-package forms, for the fuzzy-search methods.

Parameter	Type	Meaning
name	string	"right", "left", "up" or "down" — note up/down, not above/below

The vocabulary difference between Dir and GeoDir is a genuine trap: bbox.GeoDir("above") is not a direction this constructor knows.

Column-aligned sections

bbox.ExtractColumnAlignedSection(docName, sectionStart, sectionEnd, columnHeaders) → list of map

Extracts rows from a columnar form section: auto-detects column positions from the page header labels, finds the section boundaries by fuzzy match, and returns the rows between them.

Parameter	Type	Meaning
docName	string	The document name
sectionStart	string	The heading the section starts at
sectionEnd	string	The heading it ends at
columnHeaders	string	Pipe-delimited column labels

For anything new, prefer bbox.Doc().Rows(start, end) — it is the same capability on the curated facade, with per-column naming and typing, and it does not need the document name.

rule ExtractPaymentSchedule "pull the payment schedule rows" {
    when
        bbox.Doc().Has("Payment Schedule")
    then
        out.Set("schedule",
            bbox.ExtractColumnAlignedSection("page", "Payment Schedule", "Total",
                vocab.List("schedule_columns")));
}

Note vocab.List supplying the pipe-delimited headers — the two features are built to fit.

bbox.PostprocessRows(rows, key, fn) → list of map

Applies a named operation to the string value at key in every row.

Parameter	Type	Meaning
rows	list of map	The rows to clean
key	string	The column to operate on
fn	string	The operation

fn	Effect
trim	Strip leading and trailing whitespace
upper	Upper-case
lower	Lower-case
normalize_spaces	Collapse runs of whitespace to one space
trim_currency	Remove currency symbols and separators

Call it repeatedly to chain operations on the same column.

rule CleanScheduleAmounts "normalise the amount column before storing" {
    when
        out.Has("schedule")
    then
        out.Set("schedule",
            bbox.PostprocessRows(
                bbox.PostprocessRows(to.Rows(out.Get("schedule")), "amount", "trim"),
                "amount", "trim_currency"));
}

The nesting is the chaining — each call returns the rows for the next to take. Beyond two or three steps, a Rows read with typed columns is clearer.

See also

• Document — the 54 methods on what bbox.Doc() returns
• Values — what a document read gives back
• Tables and forms — the modern column-aligned surface
• The Document API — the same surface as a guide