Tablewise

Spreadsheet-grade document conversion to Markdown, with provenance. PDF, Word, Excel and PowerPoint in; clean, citable Markdown out — built for RAG, LLM ingestion and audit trails.

Every output file starts with a header that tells your retrieval layer where the text came from:

---
source: "2026-budget.xlsx"
engine: "excel"
converted: 2026-10-22
---

Three front ends, one decision engine:

• tablewise CLI — one document in, one .md out. Scripts, agents, batches.
• Desktop app (Tkinter) — for people who do not live in a terminal.
• Hosted API — POST /v1/convert, per-month plans, no install. See PRICING.md.

The problem it solves

Most converters flatten a financial table into something no model can use. A three-level header (Hotel · 2026 · Real/Budget · Jan..Dec) comes out as 70 columns named Unnamed: 12, formulas vanish, and a percentage becomes 0.8769. A RAG built on that answers with the wrong number and no way to prove it.

Tablewise routes spreadsheets to an engine that reads the sheet as a sheet:

| Hotel | 2026 | 2026 | 2026 | | | Real | Budget | Last year | | | Jan | Feb | Jan | | ADR | 120.50 | 110 | 105.25 | | Occupancy | 87.69% | | |

• Merged cells and multi-level headers preserved as a real Markdown table.
• Dates as YYYY-MM-DD, percentages with their format, -0.00 never appears.
• Hidden sheets kept but labelled (hidden sheet).
• A formula that was never recalculated says (formula not calculated) instead of an empty cell that a model reads as zero.
• Deterministic: no AI, no network, same bytes in → same Markdown out.

Quickstart

pip install -e .            # installs the `tablewise` command
tablewise report.pdf                    # -> ~/md-repo/report.md
tablewise budget.xlsx -o ~/md-repo -n "2026 budget"
tablewise contract.docx --dry-run       # print the engine command, do not run it

The desktop app:

python tablewise_app.py

The API:

curl -X POST https://api.tablewise.dev/v1/convert \
  -H "Authorization: Bearer $TABLEWISE_API_KEY" \
  -F "file=@budget.xlsx"

Why not just MarkItDown / Docling?

They are good engines and Tablewise uses both. The difference is the routing, the table fidelity and the provenance — not a new parser.

Engine routing

Each extension has exactly one owner:

• .xlsx .xlsm .xltx .xltm → motor_excel.py (openpyxl, local, no AI)
• .pdf .docx .pptx → motor_docling.py (Docling, local, no AI)
• .doc .rtf .odt → textutil (macOS) → HTML → motor_docling.py
• .xls .ppt (Office 97-2003) → LibreOffice → .xlsx/.pptx → motor_excel.py / motor_docling.py
• everything else (CSV, HTML, EPUB, …) → MarkItDown

The two own engines are motor_excel.py and motor_docling.py. A format without an available engine is refused with an explicit message, never silently degraded.

CLI reference

tablewise DOCUMENT [-o DIR] [-n NAME] [--python PATH] [--markitdown PATH]
                   [--force] [--dry-run] [-q] [--version]

• Never overwrites an existing .md without --force.
• Exit codes: 0 ok · 1 the engine produced no file · 2 invalid input.
• --python / TABLEWISE_PYTHON: interpreter that carries docling/openpyxl.
• --markitdown / TABLEWISE_MARKITDOWN: MarkItDown executable.

Hosted API

The API is the same engine behind HTTP, for teams that cannot install anything:

One unit = one PDF page, one spreadsheet sheet, one slide, or one document. Overage $0.015/unit. Annual −20%. The full contract (quota, DPA, refunds) is in PRICING.md and on the website.

Development

Runner: pytest, using the engines virtualenv (it carries openpyxl and PyYAML):

.venv/bin/python3 -m pytest -q              # 432 tests
.venv/bin/python3 -m pytest server/tests -q # 46 API tests

No test uses real documents.

Limits and security

• Upload limit 25 MB and 2,000 units per request (configurable).
• Engines run as subprocesses with a timeout; a hung converter cannot take the worker down.
• API keys are stored as SHA-256 hashes and shown once.
• No document content is logged. See web/privacy.html and web/dpa.html.
• macOS-only pieces: textutil (.doc/.rtf/.odt) and the Tkinter app. LibreOffice is needed for .xls/.ppt.

License

MIT. See LICENSE.

Spanish engineering log, kept for continuity: README.es.md.