Values

Every directional read, cell read and pattern read returns a Value. It is either a hit or a miss, it knows why it missed, and it carries the provenance of the hit.

out.Set("loanAmount", bbox.Doc().Right("Loan Amount").Currency());
//                      read                          coercion

Hit or miss

Found() → bool · Missing() → bool

Whether a value was extracted.

rule LoanAmountPresent "the amount must be readable" salience 20 {
    when
        bbox.Doc().Right("Loan Amount").Missing()
    then
        findings.Critical("LoanAmountPresent", "extraction",
            strings.Sprintf("Loan amount not found: %s",
                bbox.Doc().Right("Loan Amount").Reason()));
}

Reason() → string

Explains a miss: which stage failed, rather than an empty string that could mean any of four things, label not found, label found but nothing beside it, value found but the coercion rejected it, or scope excluded it.

This is the first thing to put in a finding when an extraction fails, and the first thing to log when a rule silently produces nothing.

Why() → string

Renders the provenance of a hit: what text matched as the label, on which page, at what distance.

Reason explains a failure; Why explains a success. When a rule extracted the wrong value, matched the label in the footer rather than the body, Why is what tells you.

rule TraceAmountRead "record where the amount came from" salience 5 {
    when
        bbox.Doc().Right("Loan Amount").Found()
    then
        log.Debug("loan amount provenance",
            "why", bbox.Doc().Right("Loan Amount").Why());
}

Reading the value

Str() → string

The extracted text, or "".

Num() → float64

The value as a number, or 0.

Thousands separators and a leading currency sign are stripped before parsing, so a bare "$1,234" reads as 1234 rather than as zero.

Coercions

Each returns another Value, so they compose with Found(), Or() and Str().

Currency() → Value

Strips currency symbols and thousands separators, leaving a bare number. Accounting parentheses are handled.

Replaces a hand-escaped regular expression that the production corpus repeated 328 times.

rule CaptureLoanAmount "the amount, as a bare number" {
    when
        bbox.Doc().Right("Loan Amount").Found()
    then
        out.Set("loanAmount", bbox.Doc().Right("Loan Amount").Currency());
}

Number() → Value

Extracts the first number in the value.

Percent() → Value

Extracts a percentage as a bare number.

A %-suffixed number is preferred wherever it sits in the value; only when the value contains no % does the first bare number win. That ordering matters on a line like "Rate 6.125% (APR 6.310%)".

Date() → Value

Normalises to YYYY-MM-DD.

A value that does not parse is a miss, not a zero date. The corpus guarded dates with != "0001-01-01" in seven places before this existed; with a miss there is no sentinel to compare against, ask Found().

YesNo() → Value

Normalises an affirmative or negative to "Yes" or "No".

Single-letter forms count: a form’s answer column is routinely a lone Y or N.

TitleCase() → Value

Title-cases the value.

Text() → Value

Trims the value. Present for symmetry, reads already trim, so a chain can be written uniformly.

Match(pattern) → Value

Keeps only the first substring matching the pattern.

Parameter	Type	Meaning
pattern	string	A regular expression

The last resort, kept so the coercion set above can stay closed. Reaching for it repeatedly is a signal that a coercion is missing, worth reporting rather than working around.

Fallbacks

Or(fallback) → Value

Substitutes a fallback when the read missed.

Parameter	Type	Meaning
fallback	string	The value to use instead

The result is found, but it carries no confidence, because it was supplied rather than extracted. That distinction survives into the output, so a downstream consumer can still tell a default from a reading.

rule PropertyTypeWithDefault "unstated property type is single family" {
    when
        in.Has("application")
    then
        out.Set("propertyType",
            bbox.Doc().Right("Property Type").Or("Single Family"));
}

Use it where the absence has a defined meaning. Where absence is a problem, raise a finding instead, a default quietly papers over a document you could not read.

Confidence and metadata

Confidence() → float64

The computed extraction confidence, from 0 to 1.

A real score, not a constant: label edit distance, value OCR confidence, alignment and proximity all contribute. It is worth gating on.

rule LowConfidenceAmount "the amount was read, but not clearly" {
    when
        bbox.Doc().Right("Loan Amount").Found() &&
        bbox.Doc().Right("Loan Amount").Confidence() < 0.8
    then
        findings.Warn("LowConfidenceAmount", "extraction",
            strings.Sprintf("Loan amount read at %s confidence",
                to.Fixed(bbox.Doc().Right("Loan Amount").Confidence(), 2)));
}

Attributes() → map

The metadata a delivery profile may surface, the engine never inspects these; they ride along with out.Set and a profile decides which reach the caller.

EngineValue() → any

Lets the engine carry the extracted text without a conversion at the call site.

A miss becomes null, which is what makes out.Set skip it, so writing a missing value does not put an empty string in your output where a consumer would read it as data. You rarely call this directly; it is why out.Set(path, someRead) behaves correctly.

The pattern worth keeping

A read that missed and a read that found an empty string are different, and the API keeps them different at every step: Missing() distinguishes them, Reason() explains which stage failed, Or() marks a supplied value as unscored, and EngineValue() keeps a miss out of the output entirely.

The one thing that collapses the distinction is Str(), a miss and an empty hit both give "". Guard with Found() before Str() whenever the difference matters.

See also

• Document: the reads that produce a Value
• Tables and forms: cells and fields are Values too
• to: conversion, converting after the coercion