spreadsheet-engine 0.1.1

Compile Excel workbooks into semantic blocks and machine-readable artifacts

spreadsheet-engine

Open-source Spreadsheet Understanding Engine (spreadsheet_engine). Compiles Excel workbooks into semantic blocks, compressed formulas, UI render models, and retrieval chunks—without dumping raw cell grids.

Install from PyPI:

pip install spreadsheet-engine
# optional LLM block enrichment
pip install "spreadsheet-engine[llm]"

Or from git:

pip install "spreadsheet-engine @ git+https://github.com/your-org/spreadsheet-engine.git"

Quick start

cd spreadsheet-engine
uv sync --extra dev

# Compile workbook → ./out
uv run spreadsheet-engine compile input_1.xlsx --out ./out

# Compile multiple workbooks into one merged artifact set
uv run spreadsheet-engine compile input_1.xlsx input_2.xlsx --out ./out

# Single sheet
uv run spreadsheet-engine compile input_1.xlsx --sheet Dashboard --out ./out

Artifact outputs (public contract)

These files are consumed by downstream tools (e.g. spreadsheet-agent):

File	Purpose
artifact.json	Semantic IR (blocks, tables, timelines)
artifact_ui.json	UI positioning + sparse cell runs
artifact_retrieval.jsonl	Embedding-ready chunks
artifact_values.jsonl	Resolved cell values for metric lookup

Each compile run produces a single set of these files. Multiple input workbooks are aggregated into one artifact set: artifact.json and artifact_ui.json hold a top-level files list (one entry per workbook, each tagged with workbook.file_name), and every .jsonl line carries a file_name field identifying its source workbook.

Optional: --enrich-llm (requires spreadsheet-engine[llm] and OPENAI_API_KEY).

Architecture

Workbook → SparseCellStore → BlockDetection → Table/Timeline/Formula analysis
         → Semantic enrichment → Retrieval + UI emitters

Tests

uv sync --extra dev
uv run pytest spreadsheet_engine/tests -q

Place input_1.xlsx at the repo root for e2e tests, or rely on skipped tests when absent.

Related projects

• spreadsheet-agent — LangGraph Q&A over compiled artifacts (pip install this package, compile to out/, then use the agent).

License

MIT — see LICENSE.