Workbook Intelligence Platform

Analyzes Excel workbooks and produces structured metadata — sheet inventory, formula analysis, cross-sheet wiring, and sheet-role classification — as JSON and Markdown. The goal is a deterministic, rule-based foundation that AI agents can later use to generate workbook documentation and knowledge packs. There is no AI/ML in this repo today; see CLAUDE.md for the full list of Non Goals.

Current version: 0.2.2

Quick Start

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Analyze input/sample.xlsx -> output/workbook_profile.json
python3 src/workbook_inventory.py

# Render output/workbook_profile.json -> output/workbook_summary.md
python3 src/documentation_generator.py

The input file is currently hardcoded to input/sample.xlsx (see roadmap.md Risk 2 — CLI arguments are a planned increment, not yet built).

What It Extracts

• Workbook metadata, sheet inventory, hidden sheets, row/column counts
• Formula counts, formula examples, function usage, formula-pattern analysis
• Excel table inventory
• Cross-sheet formula references (dependency_analyzer.py)
• Deterministic sheet-role classification — inputs / calculations / outputs / lookups / hiddenTechnical (sheet_classifier.py)

Full scope and schema rules live in CLAUDE.md. Delivery history and the prioritized next-increments list live in roadmap.md.

Architecture

The pipeline is split into an extraction layer and an interpretation layer, and that boundary is a hard rule, not a convention:

• Extraction (workbook_reader.py, formula_analyzer.py, table_analyzer.py, dependency_analyzer.py, workbook_inventory.py) is the only code allowed to touch the openpyxl workbook/worksheet/cell objects. workbook_inventory.py orchestrates all of it, including build_wiring_signals, which scans formulas once to compute cross-sheet reference and lookup-usage signals.
• Interpretation (sheet_classifier.py) consumes only structured data — the sheet-info dicts and wiring signals already built by the extraction layer — and turns them into the sheetClassification rule output. It has no openpyxl dependency.
• Output (json_writer.py, documentation_generator.py) serializes the profile to output/workbook_profile.json and renders it to output/workbook_summary.md. Neither infers business meaning; both are mechanical renderers over already-computed data.

Output Files

File	Produced by	Contents
output/workbook_profile.json	workbook_inventory.py	Full structured profile (fixed schema, additive-only changes)
output/workbook_summary.md	documentation_generator.py	Human-readable Markdown rendering of the profile

Testing

python3 -m unittest discover -s tests -v

Includes a golden-master integration test (test_golden_output.py) that runs the full pipeline against input/sample.xlsx and diffs the result against tests/fixtures/golden_workbook_profile.json, plus isolated unit tests per module.

Project Docs

• CLAUDE.md — scope, schema rules, Non Goals, coding standards (source of truth for what this project will and won't do)
• roadmap.md — delivery history, architectural risks, and prioritized next increments