| name | infer-report-structure |
| description | Stage 1 of the report-regeneration HTML pipeline. Parses an HTML template into a schema-valid Report Structure Graph (RSG): per-node stable anchor, role, rebind class, confidence, provenance, plus the deterministic non-inference data-shaped-literal detector that drives the earned-frozen rule. Stdlib-only, runs on Python 3.9. |
infer-report-structure
The first stage of the report-regeneration HTML pipeline. It reads an HTML report
template and emits a Report Structure Graph (RSG) — a format-neutral ordered tree that
downstream stages (binding-manifest generation, surgical rebind, the fidelity harness) address
and verify against. The RSG is an addressing-and-verification structure, NEVER a generator
(knowledge/core-architecture-spec.md §2).
What it produces
infer.py walks the template in document order (order is load-bearing — the V2 frozen-
complement diff and V3 re-inference isomorphism both depend on it) and emits one RSG node per
element. Each node validates against knowledge/rsg.schema.json
and carries:
| Field | Source |
|---|
anchor | a stable node identity — element_id when the element has an id, else a css_selector built from nth-of-type steps anchored at the nearest id-bearing ancestor. Never a raw char-offset (RT1-F10). |
role | rule-based semantic role (kpi-value/table-cell/narrative/chart/image/period-label/heading/metadata/static-chrome/unknown). |
class | rebind class (frozen/surgical/regenerate/needs-review). |
confidence | 0–1; sub-threshold ⇒ needs-review. |
provenance | method (native-parse/rule-based/llm-labeled), source, source_period, and pbi_route (xmla/rest/screenshot/null) for Power-BI-sourced nodes. |
data_shaped_literal | output of the pinned, non-inference, deterministic detector. |
The load-bearing detector — data_shaped_literal
detect_data_shaped_literal(text) flags currency / number / date / percent / unit /
known-entity shapes deterministically. It is intentionally blind to meaning: it cannot tell
100% the marketing tagline from 100% the KPI, or Fiscal Year 2024 the static citation from a
data-bound period — and it must not try. That is exactly why it is the right tool for the
earned-frozen rule (§4): any data-shaped literal in a candidate-frozen node force-demotes
it to needs-review, regardless of classifier confidence. It is independent of the LLM-accuracy
ceiling.
The two SPEC hard rules (override any annotation or confidence)
- Construction rule (§4/§6.4) — a node that renders as a raster or carries an
embedded binary/data cache is FORCED to
regenerate (a transplanted binary cannot be
proven data-free). This holds even when the fixture annotates the image data-role="frozen"
(e.g. the header logo, the Power BI screenshot).
- Earned-frozen rule (§4) — a data-shaped literal in a candidate-
frozen node FORCE-DEMOTES
it to needs-review.
Semantic role/class labeling here is a rule-based STUB (method: "rule-based") that reads the
fixture's explicit annotation scheme (data-role / data-bind / data-shape / data-period /
data-section-role / data-source). There is no live LLM call — the model-assisted slot
labeling of §2 lands in a later stage.
Usage
# From the repo root (paths are relative + path-guarded, or an in-repo absolute path):
python3 plugins/report-regeneration/skills/infer-report-structure/infer.py \
--in tests/fixtures/report-regeneration/sample-report.html \
--out tests/fixtures/report-regeneration/_out/rsg.sample.json
# JSON summary on stdout (exit-coded: 0 ok, 2 usage/path/parse/schema error):
python3 .../infer.py --in <template.html> --out <rsg.json> --format json
Flags: --in, --out (required), --template-id (default: input filename stem),
--confidence-threshold (default 0.6), --format {text,json}.
Companion fixture
tests/fixtures/report-regeneration/new-data.sample.json
holds plausible NEW-period (Q2 2025) values keyed to every data-bind in the corpus, so the
downstream rebind/harness stages and the acceptance test share one consistent new dataset.
Constraints
Stdlib-only (argparse/html.parser/json/re/os/sys), runs on Python 3.9.6 with no pip
installs; lxml/selectolax are optional acceleration via a graceful try/import that changes
nothing when absent. No network, no subprocess. Path-guarded (rejects .. and repo-escape,
mirroring svg-report-lint.py). The emitted RSG is validated against rsg.schema.json before it
is written — an invalid build refuses to write and exits 2.
Tests
tests/test_infer.py asserts the sample report parses, the RSG validates
against the schema, every data-bind node is found, the detector flags the tricky cases (a year,
a percent-shaped tagline), the earned-frozen demotion fires, and the companion new-data fixture
covers every binding. Runs under pytest or as a plain script (python3 tests/test_infer.py)
so it needs no third-party test runner.
