Skip to content
Back to search

exstruct

Conversion from Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines, and autonomous Excel reading/writing by AI agents via CLI and MCP integration.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/harumiWeb/exstruct with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/harumiWeb/exstruct'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/harumiweb--exstruct/badge.svg)](/listings/harumiweb--exstruct)

HTML

<a href="/listings/harumiweb--exstruct"><img src="/api/listings/harumiweb--exstruct/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install exstruct

Optional extras:

- Border-clustering acceleration: `pip install exstruct[fast]` (SciPy). Normal direct light extraction uses Python clustering. SciPy acceleration and `EXSTRUCT_BORDER_CLUSTER_BACKEND` selection apply to other modes and compatibility extraction; NumPy remains a core dependency. - YAML: `pip install pyyaml` - TOON: `pip install python-toon` - Rendering (PDF/PNG): Excel + `pip install pypdfium2 pillow` (`mode=libreoffice` is not supported) - Install these extras at once: `pip install exstruct[yaml,toon,render,fast]`

Platform note:

- On Debian/Ubuntu/WSL, install LibreOffice together with `python3-uno`. ExStruct probes a compatible system Python automatically for `mode=libreoffice`; if your environment needs an explicit interpreter, set `EXSTRUCT_LIBREOFFICE_PYTHON_PATH=/usr/bin/python3`. - LibreOffice Python detection now runs the bundled bridge in `--probe` mode before selection. An incompatible `EXSTRUCT_LIBREOFFICE_PYTHON_PATH` fails fast instead of surfacing a delayed bridge `SyntaxError` during extraction. - If the isolated temporary LibreOffice profile fails before the UNO socket becomes ready, ExStruct retries once with the shared/default LibreOffice profile as a compatibility fallback and reports per-attempt startup detail if both launches fail.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 741 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://harumiweb.github.io/exstruct/">
  3. <img width="600" alt="ExStruct Logo" src="https://github.com/user-attachments/assets/c1d4e616-890f-435c-9d53-fba054f861a8" />
  4. </a>
  5. </p>
  6. <p align="center">
  7. <em>Excel Structured Extraction Engine</em>
  8. </p>
  9. <div align="center">
  10. <a href="https://buymeacoffee.com/harumi" target="_blank">
  11. <img
  12. src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png"
  13. alt="Buy Me A Coffee"
  14. height="50"
  15. >
  16. </a>
  17. </div>
  18. <br>
  19. <div align="center" style="max-width: 600px; margin: auto;">
  20. [![PyPI version](https://badge.fury.io/py/exstruct.svg)](https://pypi.org/project/exstruct/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/exstruct?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/exstruct) ![Licence: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square) [![pytest](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml/badge.svg)](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e081cb4f634e4175b259eb7c34f54f60)](https://app.codacy.com/gh/harumiWeb/exstruct/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![codecov](https://codecov.io/gh/harumiWeb/exstruct/graph/badge.svg?token=2XI1O8TTA9)](https://codecov.io/gh/harumiWeb/exstruct) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/harumiWeb/exstruct) ![GitHub Repo stars](https://img.shields.io/github/stars/harumiWeb/exstruct) [![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-Sponsor-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/harumiWeb)
  21. </div>
  22. <p align="center">
  23. <a href="README.md">
  24. English
  25. </a>
  26. |
  27. <a href="README.ja.md">
  28. 日本語
  29. </a>
  30. </p>
  31. # ExStruct — Excel Structured Extraction Engine
  32. ExStruct reads Excel workbooks into structured data and applies patch-based
  33. editing workflows through a shared core. It provides extraction APIs, a
  34. JSON-first editing CLI, and an MCP server for host-managed integrations, with
  35. options tuned for LLM/RAG preprocessing, reviewable edit flows, and local
  36. automation.
  37. - In COM/Excel environments (Windows), it performs rich extraction.
  38. - In non-COM environments (Linux/macOS):
  39. - direct OOXML parsing extracts cells, shapes, charts, table candidates, and print areas on a best-effort basis
  40. - if the LibreOffice runtime is available, cells, table candidates, shapes, and charts are also extracted on a best-effort basis
  41. Detection heuristics, editing workflows, and output modes are adjustable for
  42. LLM/RAG pipelines and local automation.
  43. ## Main Features
  44. - **Excel -> structured JSON**: outputs cells, shapes, charts, SmartArt, table candidates, merged-cell ranges, print areas, and auto page-break areas by sheet or by area.
  45. - **Output modes**:
  46. - `light`: cells + table candidates + print areas + best-effort shapes/charts via direct OOXML for `.xlsx` / `.xlsm`
  47. - `libreoffice`: best-effort non-COM mode for `.xlsx/.xlsm`. When the LibreOffice runtime is available, it adds merged cells, shapes, connectors, and charts
  48. - `standard`: Excel COM mode with texted shapes + arrows, charts, SmartArt, and merged-cell ranges
  49. - `verbose`: outputs all shapes with width/height and also emits cell hyperlinks
  50. - **Formula extraction**: emits `formulas_map` (formula string -> cell coordinates) via OOXML or the selected openpyxl/COM path. It is enabled by default in `verbose` and can be controlled with `include_formulas_map`.
  51. - **Formats**: JSON (compact by default, `--pretty` for formatting), YAML, and TOON (optional dependencies).
  52. - **Workbook editing interfaces**: use the editing CLI for primary ExStruct edit flows, keep MCP for host-owned safety controls, and use `exstruct.edit` only when you need the same patch contract from Python.
  53. - **Table detection tuning**: heuristics can be adjusted dynamically through the API.
  54. - **Hyperlink extraction**: in `verbose` mode, or with `include_cell_links=True`, cell links are emitted in `links`.
  55. - **Safe fallback**: `light` uses direct OOXML for `.xlsx` / `.xlsm` without Excel COM or LibreOffice. Unsupported OOXML or `colors_map` requests restart the complete openpyxl compatibility pipeline with an `ooxml_compatibility` warning; partial results are discarded. A drawing failure isolated to one sheet remains best-effort.
  56. ## Installation
  57. Requires Python 3.11.5 or newer.
  58. ```bash
  59. pip install exstruct
  60. ```
  61. Optional extras:
  62. - Border-clustering acceleration: `pip install "exstruct[fast]"` (SciPy). Normal direct light extraction uses Python clustering. SciPy acceleration and `EXSTRUCT_BORDER_CLUSTER_BACKEND` selection apply to other modes and compatibility extraction; NumPy remains a core dependency.
  63. - YAML: `pip install pyyaml`
  64. - TOON: `pip install python-toon`
  65. - Rendering (PDF/PNG): Excel + `pip install "exstruct[render]"` (`mode=libreoffice` is not supported)
  66. - Install these extras at once: `pip install "exstruct[yaml,toon,render,fast]"`
  67. Platform note:
  68. - On Debian/Ubuntu/WSL, install LibreOffice together with `python3-uno`. ExStruct probes a compatible system Python automatically for `mode=libreoffice`; if your environment needs an explicit interpreter, set `EXSTRUCT_LIBREOFFICE_PYTHON_PATH=/usr/bin/python3`.
  69. - LibreOffice Python detection now runs the bundled bridge in `--probe` mode before selection. An incompatible `EXSTRUCT_LIBREOFFICE_PYTHON_PATH` fails fast instead of surfacing a delayed bridge `SyntaxError` during extraction.
  70. - If the isolated temporary LibreOffice profile fails before the UNO socket becomes ready, ExStruct retries once with the shared/default LibreOffice profile as a compatibility fallback and reports per-attempt startup detail if both launches fail.
  71. ## Quick Start CLI
  72. ```bash
  73. exstruct input.xlsx > output.json # compact JSON to stdout by default
  74. exstruct input.xlsx -o out.json --pretty # write pretty JSON to a file
  75. exstruct input.xlsx --format yaml # YAML (requires pyyaml)
  76. exstruct input.xlsx --format toon # TOON (requires python-toon)
  77. exstruct input.xlsx --sheets-dir sheets/ # write one file per sheet
  78. exstruct input.xlsx --auto-page-breaks-dir auto_areas/ # always shown; execution requires standard/verbose + Excel COM
  79. exstruct input.xlsx --alpha-col # output column keys as A, B, ..., AA
  80. exstruct input.xlsx --include-backend-metadata # include shape/chart backend metadata
  81. exstruct input.xlsx --mode light # cells + table candidates + best-effort OOXML shapes/charts
  82. exstruct input.xlsx --mode libreoffice # best-effort extraction of shapes/connectors/charts without COM
  83. exstruct input.xlsx --pdf --image # PDF and PNGs (Excel COM required)
  84. ```
  85. Auto page-break export is available from both the API and the CLI when Excel/COM is available. The CLI always exposes `--auto-page-breaks-dir`, but validates it at execution time.
  86. `mode=libreoffice` rejects `--pdf`, `--image`, and `--auto-page-breaks-dir` early, and `mode=light` also rejects `--auto-page-breaks-dir`. Use `standard` or `verbose` with Excel COM for those features.
  87. By default, the CLI keeps legacy 0-based numeric string column keys (`"0"`, `"1"`, ...). Use `--alpha-col` when you need Excel-style keys (`"A"`, `"B"`, ...).
  88. By default, serialized shape/chart output omits backend metadata (`provenance`, `approximation_level`, `confidence`) to reduce token usage. Use `--include-backend-metadata` or the corresponding Python/MCP option when you need it.
  89. ## Quick Start Editing CLI
  90. ```bash
  91. exstruct patch --input book.xlsx --ops ops.json --backend openpyxl
  92. exstruct patch --input book.xlsx --ops - --dry-run --pretty < ops.json
  93. exstruct make --output new.xlsx --ops ops.json --backend openpyxl
  94. exstruct ops list
  95. exstruct ops describe create_chart --pretty
  96. exstruct validate --input book.xlsx --pretty
  97. ```
  98. - `patch` and `make` print JSON `PatchResult` to stdout.
  99. - `ops list` / `ops describe` expose the public patch-op schema.
  100. - `validate` reports workbook readability (`is_readable`, `warnings`, `errors`).
  101. Recommended edit flow:
  102. 1. Build patch ops.
  103. 2. Run `exstruct patch --dry-run` and inspect `PatchResult`, warnings, and diff.
  104. 3. Pin `--backend openpyxl` when you want the dry run and the real apply to use the same engine.
  105. 4. If you keep `--backend auto`, inspect `PatchResult.engine`; on Windows/Excel hosts the real apply may switch to COM.
  106. 5. Re-run without `--dry-run` only after the result is acceptable.
  107. ## ExStruct CLI Skill
  108. ExStruct also ships one repo-owned Skill for agents that should follow the
  109. editing CLI safely instead of rediscovering the workflow each time.
  110. Canonical repo source:
  111. - `.agents/skills/exstruct-cli/`
  112. You can install it with the following single command:
  113. ```bash
  114. npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli
  115. ```
  116. If your runtime cannot use `npx skills add`, place the same folder manually
  117. into a local skill directory that discovers `SKILL.md`-based skills.
  118. Use this Skill when the agent needs help choosing between `patch`, `make`,
  119. `validate`, `ops list`, and `ops describe`, or when it should follow the safe
  120. `validate -> dry-run -> inspect -> apply -> verify` workflow.
  121. Example prompt for agents:
  122. > Use `$exstruct-cli` to choose the right ExStruct editing CLI command, follow a safe validate/dry-run/inspect workflow, and explain any backend constraints for this workbook task.
  123. ## MCP Server (stdio)
  124. MCP is the integration / compatibility layer around the same editing core. Use
  125. it when you need host-managed path restrictions, transport mapping, artifact
  126. mirroring, or approval-aware agent execution. For ordinary Python workbook
  127. editing, `openpyxl` / `xlwings` are usually a better fit. For local shell or
  128. agent workflows, prefer the editing CLI.
  129. ### Quick Start with `uvx` (recommended)
  130. You can run it directly without installation:
  131. ```bash
  132. uvx --from 'exstruct[mcp]' exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
  133. ```
  134. Benefits:
  135. - no `pip install` required
  136. - automatic dependency management
  137. - isolated environment
  138. - easy version pinning: `uvx --from 'exstruct[mcp]==0.4.4' exstruct-mcp`
  139. ### Traditional installation
  140. You can also install it with pip:
  141. ```bash
  142. pip install "exstruct[mcp]"
  143. exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
  144. ```
  145. Available tools:
  146. | Tool name | Description |
  147. | ------------------------------- | -------------------------------------- |
  148. | `exstruct_extract` | Extracts data from a workbook. |
  149. | `exstruct_capture_sheet_images` | Captures sheet images. |
  150. | `exstruct_make` | Creates a new workbook. |
  151. | `exstruct_patch` | Applies editing patches to a workbook. |
  152. | `exstruct_read_json_chunk` | Reads extracted JSON chunks. |
  153. | `exstruct_read_range` | Reads cells from a specified range. |
  154. | `exstruct_read_cells` | Reads data cell by cell. |
  155. | `exstruct_read_formulas` | Reads cell formulas. |
  156. | `exstruct_validate_input` | Validates input data. |
  157. For more details and API usage, see the documentation site:
  158. [MCP Server](https://harumiweb.github.io/exstruct/mcp/)
  159. ## Quick Start Python Extraction
  160. ```python
  161. from pathlib import Path
  162. from exstruct import extract, export, set_table_detection_params
  163. # Tune table detection (optional)
  164. set_table_detection_params(table_score_threshold=0.3, density_min=0.04)
  165. # Modes: "light" / "standard" / "verbose"
  166. wb = extract("input.xlsx", mode="standard") # standard does not emit links by default
  167. export(wb, Path("out.json"), pretty=False) # compact JSON
  168. export(wb, Path("out.json"), include_backend_metadata=True) # opt into backend metadata
  169. # Helpful model methods: iteration, indexing, and direct serialization
  170. first_sheet = wb["Sheet1"] # get a sheet with __getitem__
  171. for name, sheet in wb: # __iter__ yields (name, SheetData)
  172. print(name, len(sheet.rows))
  173. wb.save("out.json", pretty=True) # save WorkbookData based on extension
  174. first_sheet.save("sheet.json") # save SheetData the same way
  175. print(first_sheet.to_yaml()) # YAML string (requires pyyaml)
  176. print(first_sheet.to_json(include_backend_metadata=True)) # opt in when needed
  177. # ExStructEngine: per-instance configuration
  178. from exstruct import (
  179. DestinationOptions,
  180. ExStructEngine,
  181. FilterOptions,
  182. FormatOptions,
  183. OutputOptions,
  184. StructOptions,
  185. export_auto_page_breaks,
  186. )
  187. engine = ExStructEngine(
  188. options=StructOptions(mode="verbose"), # verbose includes hyperlinks by default
  189. output=OutputOptions(
  190. format=FormatOptions(pretty=True),
  191. filters=FilterOptions(
  192. include_shapes=False,
  193. include_backend_metadata=True,
  194. ), # opt into backend metadata when needed
  195. destinations=DestinationOptions(sheets_dir=Path("out_sheets")), # save per-sheet files
  196. ),
  197. )
  198. wb2 = engine.extract("input.xlsx")
  199. engine.export(wb2, Path("out_filtered.json"))
  200. # Enable hyperlinks in standard mode
  201. engine_links = ExStructEngine(options=StructOptions(mode="standard", include_cell_links=True))
  202. with_links = engine_links.extract("input.xlsx")
  203. # Export one file per print area
  204. from exstruct import export_print_areas_as
  205. export_print_areas_as(wb, "areas", fmt="json", pretty=True)
  206. # Extract / export auto page-break areas (COM only; raises if no auto breaks exist)
  207. engine_auto = ExStructEngine(
  208. output=OutputOptions(
  209. destinations=DestinationOptions(auto_page_breaks_dir=Path("auto_areas"))
  210. )
  211. )
  212. wb_auto = engine_auto.extract("input.xlsx") # includes SheetData.auto_print_areas
  213. engine_auto.export(wb_auto, Path("out_with_auto.json"))
  214. export_auto_page_breaks(wb_auto, "auto_areas", fmt="json", pretty=True)
  215. ```
  216. **Note (non-COM environments):** even when Excel COM is unavailable, cells + `table_candidates` are still returned, and `.xlsx` / `.xlsm` keep best-effort OOXML `shapes` / `charts` when available.
  217. ## Table Detection Parameters
  218. ```python
  219. from exstruct import set_table_detection_params
  220. set_table_detection_params(
  221. table_score_threshold=0.35, # raise it to be stricter
  222. density_min=0.05,
  223. coverage_min=0.2,
  224. min_nonempty_cells=3,
  225. )
  226. ```
  227. Higher values reduce false positives. Lower values reduce missed detections.
  228. ## Output Modes
  229. - **light**: direct OOXML cells + table candidates + print areas and best-effort shapes/connectors/charts for `.xlsx` / `.xlsm`. The normal path does not import openpyxl, pandas, SciPy, or xlwings.
  230. - **standard**: texted shapes + arrows, charts (when COM is available), and table candidates. Cell hyperlinks are emitted only when `include_cell_links=True`.
  231. - **verbose**: all shapes, charts, `table_candidates`, hyperlinks, and `colors_map`.
  232. ## Error Handling / Fallback
  233. - If Excel COM is unavailable, extraction falls back to cells + table candidates automatically; `.xlsx` / `.xlsm` still preserve best-effort OOXML shapes/charts when available.
  234. - A per-sheet drawing failure omits that sheet's affected drawing artifacts while preserving healthy sheets. An unsupported OOXML construct or failure in any other direct pipeline stage discards all partial OOXML data, restarts the complete openpyxl compatibility pipeline, and logs `ooxml_compatibility`.
  235. - The CLI writes errors to stdout/stderr and exits with a non-zero status on failure.
  236. ## Optional Rendering
  237. Excel and `pypdfium2` are required:
  238. ```bash
  239. exstruct input.xlsx --pdf --image --dpi 144
  240. ```
  241. This writes `<output>.pdf` and PNG files under `<output>_images/`.
  242. ## Example 1: Excel Structuring Demo
  243. To show how far exstruct can structure Excel, we parse an Excel workbook that combines the following three elements on a single sheet and show an LLM reasoning example based on the JSON output.
  244. - a table (sales data)
  245. - a line chart
  246. - a flowchart built only with shapes
  247. The image below is the actual sample Excel sheet.
  248. ![Sample Excel](docs/assets/demo_sheet.png)
  249. Sample Excel: `sample/sample.xlsx`
  250. ### 1. Input: Excel Sheet Overview
  251. This sample Excel contains the following data:
  252. ### 1) Table (sales data)
  253. | Month | Product A | Product B | Product C |
  254. | ------ | --------- | --------- | --------- |
  255. | Jan-25 | 120 | 80 | 60 |
  256. | Feb-25 | 135 | 90 | 64 |
  257. | Mar-25 | 150 | 100 | 70 |
  258. | Apr-25 | 170 | 110 | 72 |
  259. | May-25 | 160 | 120 | 75 |
  260. | Jun-25 | 180 | 130 | 80 |
  261. ### 2) Chart (line chart)
  262. - Title: Sales Data
  263. - Series: Product A / Product B / Product C (six months)
  264. - Y-axis: 0-200
  265. ### 3) Flowchart made with shapes
  266. The sheet includes the following flow:
  267. - Start / End
  268. - Format check
  269. - Loop (items remaining?)
  270. - Error handling
  271. - Yes/No decision for sending email
  272. ### 2. Output: structured JSON generated by exstruct (excerpt)
  273. Below is a shortened JSON output example from parsing the workbook above.
  274. ```json
  275. {
  276. "book_name": "sample.xlsx",
  277. "sheets": {
  278. "Sheet1": {
  279. "rows": [
  280. {
  281. "r": 3,
  282. "c": {
  283. "1": "月",
  284. "2": "製品A",
  285. "3": "製品B",
  286. "4": "製品C"
  287. }
  288. },
  289. ...
  290. ],
  291. "shapes": [
  292. {
  293. "id": 1,
  294. "text": "開始",
  295. "l": 148,
  296. "t": 220,
  297. "kind": "shape",
  298. "type": "AutoShape-FlowchartProcess"
  299. },
  300. {
  301. "id": 2,
  302. "text": "入力データ読み込み",
  303. "l": 132,
  304. "t": 282,
  305. "kind": "shape",
  306. "type": "AutoShape-FlowchartProcess"
  307. },
  308. {
  309. "l": 193,
  310. "t": 246,
  311. "kind": "arrow",
  312. "begin_arrow_style": 1,
  313. "end_arrow_style": 2,
  314. "begin_id": 1,
  315. "end_id": 2,
  316. "direction": "N"
  317. },
  318. ...
  319. ],
  320. "charts": [
  321. {
  322. "name": "Chart 1",
  323. "chart_type": "Line",
  324. "title": "売上データ",
  325. "y_axis_range": [
  326. 0.0,
  327. 200.0
  328. ],
  329. "series": [
  330. {
  331. "name": "製品A",
  332. "name_range": "Sheet1!$C$3",
  333. "x_range": "Sheet1!$B$4:$B$9",
  334. "y_range": "Sheet1!$C$4:$C$9"
  335. },
  336. ...
  337. ],
  338. "l": 377,
  339. "t": 25
  340. }
  341. ],
  342. "table_candidates": [
  343. "B3:E9"
  344. ]
  345. }
  346. }
  347. }
  348. ```
  349. ### 3. How AI (Copilot / LLM) interprets the JSON
  350. ````md
  351. Below is a Markdown reconstruction of the Excel workbook. It expresses the table, chart, and flowchart as separate structures.
  352. ---
  353. ## Sales Data Table
  354. | Month | Product A | Product B | Product C |
  355. | ---------- | --------- | --------- | --------- |
  356. | 2025-01-01 | 120 | 80 | 60 |
  357. | 2025-02-01 | 135 | 90 | 64 |
  358. | 2025-03-01 | 150 | 100 | 70 |
  359. | 2025-04-01 | 170 | 110 | 72 |
  360. | 2025-05-01 | 160 | 120 | 75 |
  361. | 2025-06-01 | 180 | 130 | 80 |
  362. ---
  363. ## Sales Data (Line Chart)
  364. - Chart title: **売上データ**
  365. - Chart type: line chart
  366. - Y-axis range: 0 to 200
  367. - Data series:
  368. - Product A: 120 -> 135 -> 150 -> 170 -> 160 -> 180
  369. - Product B: 80 -> 90 -> 100 -> 110 -> 120 -> 130
  370. - Product C: 60 -> 64 -> 70 -> 72 -> 75 -> 80
  371. ---
  372. ## Process Flow (Mermaid Flowchart)
  373. ```mermaid
  374. flowchart TD
  375. A[Start]
  376. B[Load input data]
  377. C{Is the format valid?}
  378. D[Process one item]
  379. E{Items remaining?}
  380. F[Generate output]
  381. G{Send email?}
  382. H[Show error]
  383. I[Send email]
  384. J[Finish]
  385. A --> B
  386. B --> C
  387. C -->|yes| D
  388. C --> H
  389. D --> E
  390. E --> F
  391. F --> G
  392. G -->|yes| I
  393. G -->|no| J
  394. H --> J
  395. I --> J
  396. ```
  397. ````
  398. ## Example 2: A General Application Form
  399. ### Excel data
  400. ![General application form Excel](docs/assets/demo_form.ja.png)
  401. ### ExStruct JSON
  402. (Truncated for brevity)
  403. ```json
  404. {
  405. "book_name": "ja_form.xlsx",
  406. "sheets": {
  407. "Sheet1": {
  408. "rows": [
  409. { "r": 1, "c": { "0": "介護保険負担限度額認定申請書" } },
  410. {
  411. "r": 3,
  412. "c": { "0": "(申請先)", "7": "     年    月    日" }
  413. },
  414. { "r": 4, "c": { "1": "X市長 " } },
  415. ...
  416. ],
  417. "table_candidates": ["B25:C26", "C37:D50"],
  418. "merged_cells": {
  419. "schema": ["r1", "c1", "r2", "c2", "v"],
  420. "items": [
  421. [55, 5, 55, 10, "申請者が被保険者本人の場合には、下記について記載は不要です。"],
  422. [54, 8, 54, 10, " "],
  423. [51, 5, 52, 6, "有価証券"],
  424. ...
  425. ]
  426. }
  427. }
  428. }
  429. }
  430. ```
  431. ### ExStruct JSON -> Markdown via LLM reasoning
  432. ```md
  433. # Long-Term Care Insurance Burden Limit Certification Application
  434. (Submitted to) Year Month Day
  435. Mayor of City X
  436. Attach the related documents below and apply for certification of the burden limit for food and housing expenses.
  437. ---
  438. ## Insured Person Information
  439. | Item | Value |
  440. | ---- | ----- |
  441. | Furigana | |
  442. | Name | |
  443. | Insured Person Number | |
  444. | Personal Number | |
  445. | Date of Birth | Meiji / Taisho / Showa Year Month Day |
  446. | Address | |
  447. | Contact | |
  448. ---
  449. ## Long-Term Care Facility Entered / Hospitalized In
  450. | Item | Value |
  451. | ---- | ----- |
  452. | Facility name / location | |
  453. | Contact | |
  454. | Date of entry / admission | Year Month Day |
  455. If the applicant has not entered a care insurance facility, or uses short stay only, this section is not required.
  456. ---
  457. ## Presence of a Spouse
  458. | Item | Value |
  459. | ---- | ----- |
  460. | Spouse | Yes / No |
  461. If "No", the following spouse section is not required.
  462. ---
  463. ## Spouse Information
  464. | Item | Value |
  465. | ---- | ----- |
  466. | Furigana | |
  467. | Name | |
  468. | Date of Birth | Meiji / Taisho / Showa Year Month Day |
  469. | Personal Number | |
  470. | Address | Postal code |
  471. | Contact | |
  472. | Address as of January 1 of this year (if different) | Postal code |
  473. | Tax status | Municipal resident tax: taxable / non-taxable |
  474. ---
  475. ## Declaration of Income and Other Status
  476. Check the applicable item below.
  477. - □ 1. Livelihood protection recipient
  478. - □ 2. Old-age welfare pension recipient in a household exempt from municipal resident tax
  479. - □ 3. Person exempt from municipal resident tax whose taxable pension income + survivor/disability pension + other income totals **800,000 JPY or less per year**
  480. - □ 4. Same as above, but **over 800,000 JPY up to 1,200,000 JPY**
  481. - □ 5. Same as above, but **over 1,200,000 JPY**
  482. Survivor pension includes widow's pension, widower's pension, mother's pension, quasi-mother's pension, and orphan's pension.
  483. ---
  484. ## Declaration of Deposits and Other Assets
  485. - □ The total amount of deposits, securities, and other assets is below the following threshold:
  486. - Category 2: 10 million JPY (20 million JPY for couples)
  487. - Category 3: 6.5 million JPY (16.5 million JPY for couples)
  488. - Category 4: 5.5 million JPY (15.5 million JPY for couples)
  489. - Category 5: 5 million JPY (15 million JPY for couples)
  490. - Second insured persons (ages 40-64): Categories 3-5 must be 10 million JPY or less (20 million JPY for couples)
  491. ### Asset breakdown
  492. | Item | Amount |
  493. | ---- | ------ |
  494. | Deposits | JPY |
  495. | Securities (estimated value) | JPY |
  496. | Other (including cash / debt) | JPY (describe) |
  497. ---
  498. ## Applicant Information (not required when the applicant is the insured person)
  499. | Item | Value |
  500. | ---- | ----- |
  501. | Applicant name | |
  502. | Contact (home / office) | |
  503. | Applicant address | |
  504. | Relationship to insured person | |
  505. ---
  506. ## Notes
  507. 1. In this application, "spouse" includes a spouse living separately and a common-law partner.
  508. 2. If you own multiple assets of the same kind, list all of them and attach copies of bankbooks or equivalent documents.
  509. 3. If there is not enough space, write on the margin or on a separate sheet and attach it.
  510. 4. If benefits are obtained through a false declaration, the paid amount and up to twice that amount as an additional charge may need to be repaid under Article 22, Paragraph 1 of the Long-Term Care Insurance Act.
  511. ```
  512. ## Discussion
  513. The result above shows the following clearly:
  514. **ExStruct JSON is already in a format that AI can understand semantically as-is.**
  515. Other LLM inference samples built with this library are available in the following directories:
  516. - [Basic Excel](sample/basic/)
  517. - [Flowchart](sample/flowchart/)
  518. - [Gantt Chart](sample/gantt_chart/)
  519. - [Application forms with many merged cells](sample/forms_with_many_merged_cells/)
  520. ### 4. Summary
  521. This benchmark demonstrates that the library can:
  522. - analyze tables, charts, and shapes (flowcharts) at the same time
  523. - convert Excel's semantic structure into JSON
  524. - let AI/LLMs read that JSON directly and reconstruct workbook content
  525. In short, **exstruct = "an engine that converts Excel into a format AI can understand."**
  526. ## Benchmark
  527. ![Benchmark Chart](benchmark/public/plots/markdown_quality.png)
  528. This repository includes benchmark reports focused on RAG/LLM preprocessing of Excel documents.
  529. We track two perspectives: (1) core extraction accuracy and (2) reconstruction utility for downstream structure queries (RUB).
  530. See `benchmark/REPORT.md` for the working summary and `benchmark/public/REPORT.md` for the public bundle.
  531. Current results are based on n=12 cases and will be expanded further.
  532. ## Notes
  533. - Default JSON is compact to reduce token usage. Use `--pretty` / `pretty=True` when readability matters.
  534. - The field name is `table_candidates` (replacing the old `tables`). Adjust downstream schemas accordingly.
  535. ## Enterprise Use
  536. ExStruct is intended primarily for **library** use, not as a service.
  537. - no official support or SLA is provided
  538. - long-term stability is prioritized over rapid feature growth
  539. - enterprise use is expected to involve forking or internal customization
  540. It is suitable for teams that:
  541. - need transparency instead of black-box tooling
  542. - are comfortable maintaining internal forks when needed
  543. ## Print Areas and Auto Page-Break Areas (PrintArea / PrintAreaView)
  544. - `SheetData.print_areas` contains print areas (cell coordinates) in `light` / `standard` / `verbose`.
  545. - `SheetData.auto_print_areas` contains Excel COM-computed auto page-break areas only when auto page-break extraction is enabled (COM only).
  546. - Use `export_print_areas_as(...)` or CLI `--print-areas-dir` to export one file per print area. If no print areas exist, nothing is written.
  547. - Use CLI `--auto-page-breaks-dir` (COM only), `DestinationOptions.auto_page_breaks_dir` (recommended), or `export_auto_page_breaks(...)` to export one file per auto page-break area. `export_auto_page_breaks(...)` raises `ValueError` when no auto page breaks exist.
  548. - `PrintAreaView` includes rows and table candidates inside the area, plus shapes/charts that intersect the area. When shape size is unknown, point-based overlap is used. With `normalize=True`, row/column indices are rebased to the area origin.
  549. ## Architecture
  550. ExStruct adopts a pipeline-oriented architecture that separates extraction strategy (Backend), orchestration (Pipeline), and semantic modeling.
  551. See: [dev-docs/architecture/pipeline.md](dev-docs/architecture/pipeline.md)
  552. ## Contributing
  553. If you plan to extend ExStruct internals, read the contributor architecture guide first.
  554. See: [dev-docs/architecture/contributor-guide.md](dev-docs/architecture/contributor-guide.md)
  555. ## Coverage Note
  556. The cell-structure inference logic (`cells.py`) depends on heuristic rules and Excel-specific behavior. Full coverage is intentionally not pursued, because exhaustive tests would not reflect real-world reliability.
  557. ## License
  558. BSD-3-Clause. See `LICENSE` for details.
  559. ## Documentation
  560. - API reference (GitHub Pages): https://harumiweb.github.io/exstruct/
  561. - JSON schemas are stored in `schemas/`, one file per model. Regenerate them with `python scripts/gen_json_schema.py` after model changes.
  562. ## Star History
  563. [![Star History Chart](https://api.star-history.com/image?repos=harumiWeb/exstruct&type=date&legend=top-left)](https://www.star-history.com/?repos=harumiWeb%2Fexstruct&type=date&legend=top-left)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.