Parsing & Workbook Ingestion
Executive Summary
Key Takeaways
- ✓ FMAE loads every workbook twice — once for formula text, once for Excel's last cached values — because the engine reads what Excel last calculated rather than evaluating formulas itself.
- ✓ If a workbook has never been opened and recalculated in Excel, the cached-value pass returns no values at all; the engine detects and surfaces this rather than silently treating every cell as blank.
- ✓ Every worksheet is classified into one of seven structural roles using signals openpyxl can observe directly — no language model, no machine learning, no external calls.
- ✓ The output of this stage, the manifest, is the single structured representation every later pipeline stage reads from; nothing downstream re-parses the original workbook file.
What This Stage Does¶
Parsing & Workbook Ingestion is the first stage of the FMAE audit pipeline: it converts an uploaded
.xlsx file into a manifest — a single structured internal representation that every later stage
(dependency graph construction, rule execution, scoring, and reporting) reads from. No later stage
re-opens or re-parses the original workbook file.
The Two-Pass Load¶
FMAE cannot evaluate Excel formulas itself — no tool built without Excel's own calculation engine can. Instead, it reads what Excel itself last calculated and saved in the file. This requires loading the workbook twice:
- Formula pass — the workbook is loaded with formula text visible, so every formula cell's actual
calculation (
=C5*(1+$B$12), for example) is readable as text. - Cached-value pass — the same workbook is loaded again, this time with Excel's last-calculated values visible instead of formula text.
Combining both passes gives the engine, for every cell, both what the formula says and what it last evaluated to.
A workbook that has never been recalculated in Excel. If a workbook was generated or last saved by a script or a system that never triggered an Excel recalculation, the cached-value pass has nothing to read — every formula cell's cached value comes back empty. The engine checks for this directly, by sampling formula cells across the workbook: if every sampled cell shows no cached value, the workbook is flagged as never calculated, a real, disclosed limitation rather than a silent treatment of every formula cell as blank.
Worksheet Classification¶
Every worksheet in the workbook is classified into one of seven structural roles, using signals openpyxl can observe directly — no language model, no machine learning model, and no external service is involved at any point in this classification:
| Type | What it represents |
|---|---|
| Input | A dedicated assumption or input layer — data validation, constants, named ranges |
| Interface | A control panel, scenario manager, or dashboard sheet |
| Calculation | A formula-heavy logic sheet, typically with cross-sheet outbound references |
| Output | A results or reporting sheet, typically with aggregated inbound references |
| Lookup | A reference table — dense constants, named ranges, referenced by other sheets |
| Mixed | A worksheet whose signals are too balanced to assign one dominant type |
| Unknown | Too few cells to classify reliably |
Classification draws on the direction of cross-sheet formula references — whether other sheets' formulas reference cells on this sheet (inbound, suggesting Input or Lookup), or this sheet's formulas reference cells on other sheets (outbound, suggesting Calculation or Output) — alongside keyword signals in sheet names and structural density. The specific weighting and thresholds behind this classification are internal to the engine and not disclosed here; what is disclosed is that the classification is entirely deterministic and observable, not inferred by a model reading the sheet's content or purpose.
What the Manifest Contains¶
The output of this stage — the manifest — carries, at minimum: every non-empty cell as a structured node (sheet, address, formula text if any, cached value, value type, hardcode flag, error state if any), workbook-level metadata (calculation mode, iterative-calculation settings, external link references, defined names, merged-cell ranges, data validation ranges), and each worksheet's classification. This is the single representation every later stage — dependency graph construction, rule execution, scoring, and report generation — reads from.
Related Reading¶
- FMAE Audit Engine — Architecture Overview — where this stage sits in the overall pipeline.
- Rule Reference — several rules, including R002 (Broken Links), read facts this stage and the dependency-graph stage have already computed rather than re-deriving them.
How OXXON tests thisRun a free structural check with FMAE
Frequently Asked Questions
How does FMAE read an Excel file?
It loads the workbook twice with openpyxl — once with formulas visible as text, once with Excel's last-calculated cached values visible — then combines both passes into a single structured manifest that the rest of the pipeline reads from.
Can FMAE evaluate formulas itself?
No. Like any tool built on openpyxl, FMAE cannot execute Excel's calculation engine. It reads the last value Excel itself calculated and cached in the file. If a workbook was saved without ever being recalculated in Excel, no cached values exist to read.
What happens if a workbook was never opened in Excel before being saved (for example, one generated by a script)?
The engine samples formula cells across the workbook; if none of them carry a cached value, it flags the workbook as never calculated rather than silently treating every formula cell as blank or zero.
How does FMAE classify worksheets?
Into one of seven structural roles — Input, Interface, Calculation, Output, Lookup, Mixed, or Unknown — using deterministic signals openpyxl can observe directly (such as the direction formulas reference across sheets), not a language model or external service.
What is a manifest?
The single structured internal representation of a workbook that this stage produces — every formula cell, every hardcoded cell, workbook-level metadata (calculation mode, external links, defined names), and each worksheet's classification. Every later pipeline stage reads from the manifest; none re-parses the original file.
Related Articles
FMAE Audit Engine — Architecture Overview
The FMAE audit engine processes a workbook through five stages executed in a fixed order — parsing and workbook ingestion, dependency graph construction, rule engine execution, risk scoring, and report generation. Each stage consumes the previous stage's output and exposes nothing about how any later stage will use it, so the stages can be documented, tested, and read about independently. This page is the map; the detail behind each stage lives on its own Technical Documentation page as those pages are published.
FMAE Rule Taxonomy
Every rule in the FMAE structural rule pack declares a category attribute at the point it is defined in source — this is not a classification imposed on the rules afterward for documentation purposes, it is the classification the engine itself uses. Six categories cover all 26 rules — Structural (18 rules), Assumptions Governance (1), Integrity Controls (2), Structural Hygiene (1), Aggregation Logic (1), and Model Governance (3). This page publishes that taxonomy as the FMAE equivalent of a control catalog's classification scheme, cross-linked to the Rule Reference page for each member rule.