linexcel

Data lineage analysis for Excel workbooks.

Extracts every formula, groups stretched patterns (R1C1 canonicalization), builds a dependency graph (cells, ranges, defined names, VBA), decomposes composite functions with step-by-step evaluation, and optionally documents calculations via the AI provider of your choice.

Install

uv add linexcel               # pip install linexcel
uv add linexcel[ai]           # + AI documentation (optional)

Note: linexcel depends on formualizer, a Rust-based spreadsheet engine. Prebuilt wheels are available for Linux, macOS, and Windows. If no wheel matches your platform, a Rust toolchain is required to build from source.

Usage

Command line

No install needed — uvx fetches and runs it in one step:

uvx linexcel analyze workbook.xlsx           # -> workbook_lineage.html
uvx linexcel analyze workbook.xlsx --json graph.json --no-html

The default is deterministic: lineage only, no network, no key. --ai-docs opts in, and needs the ai extra plus an OpenAI-compatible endpoint:

uvx --from "linexcel[ai]" linexcel analyze workbook.xlsx --ai-docs \
    --base-url http://localhost:11434/v1 --model laguna-xs-2.1 --language fr

--base-url, --model and --api-key also read LINEXCEL_AI_BASE_URL, LINEXCEL_AI_MODEL and LINEXCEL_AI_API_KEY. Run linexcel analyze --help for the full list, including --token-budget to cap what a run may cost.

Python

from linexcel import analyze

result = analyze("workbook.xlsx")
result                        # interactive graph in marimo / Jupyter
result.save_html("out.html")  # standalone offline HTML viewer
result.stats                  # {totalFormulas, totalNodes, ...}
result.warnings               # list[str]

Everything above is local and needs no key. AI documentation is optional, and you choose the provider — nothing is sent anywhere until you name one:

# A local runtime keeps the workbook on your machine and costs nothing
docs = result.document(base_url="http://localhost:11434/v1", model="laguna-xs-2.1")
overview = result.document_workbook(base_url="http://localhost:11434/v1", model="laguna-xs-2.1")
result.save_html("out.html", docs=docs, workbook_doc=overview, language="en")

Any OpenAI-compatible endpoint works the same way — a local Ollama or vLLM runtime, a gateway such as OpenRouter, a vendor's own API — and provider= takes any callable for anything else. See Choosing an AI provider.

Features

• Formula extraction via formualizer (Rust engine)
• Stretched pattern grouping — 1000 identical formulas → 1 node
• Dependency graph — cells, ranges, defined names, VBA procedures
• Step-by-step evaluation — each operator/function evaluated individually
• Standalone HTML viewer — Cytoscape.js embedded, fully offline, keyboard-navigable, light by default with a dark toggle
• Values you can check — each figure states whether it was read from the workbook or recalculated by linexcel, and shows both side by side when the file disagrees
• Workbook context — sheet previews, comments, merged ranges, frozen panes and hidden columns, plus optional LibreOffice-rendered screenshots
• AI documentation — vendor-neutral, grounded in deterministic lineage, with token accounting and a spend ceiling
• Nine interface languages — for both the report and the AI prompts
• Command line — uvx linexcel analyze workbook.xlsx, no install required

Roadmap

Shipped:

• Deterministic lineage — formula extraction, stretched-pattern grouping, dependency graph, VBA
• Step-by-step evaluation, with every value checked against the one stored in the file
• Standalone offline HTML viewer, in nine languages
• Workbook context and LibreOffice-rendered sheet screenshots
• AI documentation — any OpenAI-compatible endpoint, token accounting, spend ceiling
• Command-line interface, installable-free through uvx

Planned:

• Power Query lineage (#34) — queries are invisible today, so a workbook fed by Get & Transform shows the range the data landed in and nothing about where it came from. Everything needed sits in the file, so this is a gap to close rather than a limit of the format.
• Vision (#46) — let a multimodal model read the sheet screenshots. Colour conventions such as blue inputs against black formulas, conditional formatting, charts and block layout are invisible to a text dossier, however complete it is.
• formulas as a fallback (#37) — a second parser for the workbooks formualizer cannot read, so an unsupported construct degrades the graph instead of failing the analysis.

Documentation

Sample output

Every image below is captured from a real report by scripts/capture_viewer.py, so they cannot drift from the viewer without the readme-shots commit hook noticing.

A node, documented

Formula, step-by-step evaluation, precedents and dependents, and the AI card written from that same deterministic dossier.

Workbook overview

Sheet context

Each sheet rendered whole, over a grid of its first cells, alongside its comments, frozen panes, merged ranges and hidden columns.

Security

Analysis is entirely local. AI documentation sends dossiers only to the provider you configure — see Data handling.

Please report vulnerabilities privately according to SECURITY.md. Do not include sensitive workbooks or credentials in public issues.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.