Documentation

Mapping review

The tagging ladder (rules, then the model step) classifies what it can agree on. Everything else is left as a mapping proposal. Ops → Mapping review (ui/mapping.html) is where a person answers proposals. Extracted facts are proposals and a person confirms them: the same pattern as Cx spec items.

How much of the building Baler understands

The page opens with a count of points by state:

State	Meaning
By a naming convention	A site naming convention settled it.
By a rule	A rule in `rules/haystack_to_brick.yaml` matched.
By a site rule	A pattern a person approved here; see below.
By memory	The nearest confirmed examples agreed (memory).
By the model step	Both model asks agreed, and nothing vetoed it.
By a person	Accepted here, or the class was edited by hand (`record_edits`).
Proposed	Waiting for a person.
Escalated	Waiting for a specialist.
Unmapped	No class and no proposal. Run `python -m baler.autotag`.

"Understood" is the share of points classified by a rule, a site rule, memory, the model or a person. The counts come from GET /ops/mapping/summary and are scoped to your sites.

The queue

GET /ops/mapping/proposals groups the open proposals by naming pattern: digits become {n}, and the marker tags and unit must match. One answer can then cover all 41 points like VAV-{n}-DA-T. Groups are ranked by impact:

A fault rule needs it. A rule's topic_glob matches a member, or one of its candidate classes is a class a brick_class rule targets.
The site has an active Cx project. It isn't archived.
Everything else.

Within a tier, bigger groups come first.

Each group shows:

the candidates, with their source (model, ranker or site rule) and reason;
the evidence the model step saw: label, marker and valued tags, value stats, and the points on the same equipment;
what each model ask said, including names it gave that aren't Brick classes;
why it wasn't auto-accepted;
a 24 h sparkline of the first member, from GET /ingest/history.

The nearest confirmed examples from memory are listed with their similarity and whether they came from this site or the org. Windrow doesn't send the BACnet description or object type yet (Windrow#19). When it does, they show up here as tags.

Answers

POST /ops/mapping/decide takes {ids, action, ...}, either for one proposal or for a whole group. It needs the operator role.

Accept a candidate, or type any other Brick class.
- The name is checked against the vendored Brick ontology. An unknown name is a 400.
- The class is written the same way as a hand edit (record_edit) and logged in record_edits with action mapping. The point's PROJ: or TD:UnmappedPoint type is removed.
- For a group, Save as a site rule stores the pattern in mapping_site_rules. From then on the model step gives every new point with that pattern this class without asking a model, unless the unit or value veto objects.
Escalate to a specialist: the site's controls contractor, the MSI, or our own expert.
- The proposals stay in the queue, marked with who was asked.
- Every webhook in the registry with no filter, or filtered to rule_id mapping, gets a mapping.escalated event. It carries the proposals, the assignee and a link back here, with the same SSRF rules as fault webhooks. Baler has no email path, so webhooks are the notification.
- The specialist answers on this same page. A later autotag run refreshes an escalated proposal's evidence, but never opens a second one or closes it.
Needs a site visit is a valid answer.
- It records that the points can't be identified without going there.
- It opens a Cx issue ("Site visit: identify N point(s) like ...") on the newest active Cx project covering the points, with the candidates and your note.
- With no such project, the answer is still recorded and the page says no issue was opened.

An answered proposal can't be answered again (409). The API only acts on proposals on your sites; for anyone else's it answers 404.

Equipment relationships

Proposed equipment groupings and feeds edges from equipment inference are listed in their own section, with the evidence. Accept writes the edges (and creates the equipment for a grouping); Reject closes the proposal.

Training data

Every accepted proposal is also written to mapping_examples, with the evidence the person saw, their answer, and the org and site it belongs to. Memory learns from it, and it never leaves that org.

Last modified on November 8, 2026

The model step Naming conventions

How much of the building Baler understands

The page opens with a count of points by state:

State

Meaning

By a naming convention

A site naming convention settled it.

By a rule

A rule in rules/haystack_to_brick.yaml matched.

By a site rule

A pattern a person approved here; see below.

By memory

The nearest confirmed examples agreed (memory).

By the model step

Both model asks agreed, and nothing vetoed it.

By a person

Accepted here, or the class was edited by hand (record_edits).

Proposed

Waiting for a person.

Escalated

Waiting for a specialist.

Unmapped

No class and no proposal. Run python -m baler.autotag.

"Understood" is the share of points classified by a rule, a site rule, memory, the model or a person. The counts come from GET /ops/mapping/summary and are scoped to your sites.

The queue

A fault rule needs it. A rule's topic_glob matches a member, or one of its candidate classes is a class a brick_class rule targets.

The site has an active Cx project. It isn't archived.

Everything else.

Within a tier, bigger groups come first.

Each group shows:

the candidates, with their source (model, ranker or site rule) and reason;

the evidence the model step saw: label, marker and valued tags, value stats, and the points on the same equipment;

what each model ask said, including names it gave that aren't Brick classes;

why it wasn't auto-accepted;

a 24 h sparkline of the first member, from GET /ingest/history.

Answers

POST /ops/mapping/decide takes {ids, action, ...}, either for one proposal or for a whole group. It needs the operator role.

Accept a candidate, or type any other Brick class.

The name is checked against the vendored Brick ontology. An unknown name is a 400.
The class is written the same way as a hand edit (record_edit) and logged in record_edits with action mapping. The point's PROJ: or TD:UnmappedPoint type is removed.
For a group, Save as a site rule stores the pattern in mapping_site_rules. From then on the model step gives every new point with that pattern this class without asking a model, unless the unit or value veto objects.

Escalate to a specialist: the site's controls contractor, the MSI, or our own expert.

The proposals stay in the queue, marked with who was asked.
Every webhook in the registry with no filter, or filtered to rule_id mapping, gets a mapping.escalated event. It carries the proposals, the assignee and a link back here, with the same SSRF rules as fault webhooks. Baler has no email path, so webhooks are the notification.
The specialist answers on this same page. A later autotag run refreshes an escalated proposal's evidence, but never opens a second one or closes it.

Needs a site visit is a valid answer.

It records that the points can't be identified without going there.
It opens a Cx issue ("Site visit: identify N point(s) like ...") on the newest active Cx project covering the points, with the candidates and your note.
With no such project, the answer is still recorded and the page says no issue was opened.

An answered proposal can't be answered again (409). The API only acts on proposals on your sites; for anyone else's it answers 404.