exstruct 0.4.2__tar.gz → 0.4.4__tar.gz

{exstruct-0.4.2 → exstruct-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.4.2
+Version: 0.4.4
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -43,9 +43,9 @@ Requires-Dist: pyyaml>=6.0.3 ; extra == 'all'
 Requires-Dist: python-toon>=0.1.3 ; extra == 'all'
 Requires-Dist: pypdfium2>=5.1.0 ; extra == 'all'
 Requires-Dist: pillow>=12.0.0 ; extra == 'all'
-Requires-Dist: mcp>=1.6.0,<2.0.0 ; extra == 'all'
+Requires-Dist: mcp>=1.25.0,<2.0.0 ; extra == 'all'
 Requires-Dist: httpx>=0.27,<1.0 ; extra == 'all'
-Requires-Dist: mcp>=1.6.0,<2.0.0 ; extra == 'mcp'
+Requires-Dist: mcp>=1.25.0,<2.0.0 ; extra == 'mcp'
 Requires-Dist: httpx>=0.27,<1.0 ; extra == 'mcp'
 Requires-Dist: pypdfium2>=5.1.0 ; extra == 'render'
 Requires-Dist: pillow>=12.0.0 ; extra == 'render'
@@ -65,7 +65,7 @@ Description-Content-Type: text/markdown
 
 # ExStruct — Excel Structured Extraction Engine
 
-[![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)
+[![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)
 
 ![ExStruct Image](docs/assets/icon.webp)
 
@@ -84,6 +84,15 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 - **CLI rendering** (Excel required): optional PDF and per-sheet PNGs.
 - **Graceful fallback**: if Excel COM is unavailable, extraction falls back to cells + table candidates without crashing.
 
+## Benchmark
+
+![Benchmark Chart](benchmark/public/plots/markdown_quality.png)
+
+This repository includes benchmark reports focused on RAG/LLM preprocessing of Excel documents.
+We track two perspectives: (1) core extraction accuracy and (2) reconstruction utility for downstream structure queries (RUB).
+See `benchmark/REPORT.md` for the working summary and `benchmark/public/REPORT.md` for the public bundle.
+Current results are based on n=12 cases and will be expanded.
+
 ## Installation
 
 ```bash
@@ -129,11 +138,13 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 Available tools:
 
 - `exstruct_extract`
+- `exstruct_patch`
 - `exstruct_read_json_chunk`
 - `exstruct_validate_input`
 
 Notes:
 
+- In MCP, `exstruct_extract` defaults to `options.alpha_col=true` (column keys: `A`, `B`, ...). Set `options.alpha_col=false` for legacy 0-based numeric string keys.
 - Logs go to stderr (and optionally `--log-file`) to avoid contaminating stdio responses.
 - On Windows with Excel, standard/verbose can use COM for richer extraction. On non-Windows, COM is unavailable and extraction uses openpyxl-based fallbacks.
 

{exstruct-0.4.2 → exstruct-0.4.4}/README.md

@@ -1,6 +1,6 @@
 # ExStruct — Excel Structured Extraction Engine
 
-[![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)
+[![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)
 
 ![ExStruct Image](docs/assets/icon.webp)
 
@@ -19,6 +19,15 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 - **CLI rendering** (Excel required): optional PDF and per-sheet PNGs.
 - **Graceful fallback**: if Excel COM is unavailable, extraction falls back to cells + table candidates without crashing.
 
+## Benchmark
+
+![Benchmark Chart](benchmark/public/plots/markdown_quality.png)
+
+This repository includes benchmark reports focused on RAG/LLM preprocessing of Excel documents.
+We track two perspectives: (1) core extraction accuracy and (2) reconstruction utility for downstream structure queries (RUB).
+See `benchmark/REPORT.md` for the working summary and `benchmark/public/REPORT.md` for the public bundle.
+Current results are based on n=12 cases and will be expanded.
+
 ## Installation
 
 ```bash
@@ -64,11 +73,13 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 Available tools:
 
 - `exstruct_extract`
+- `exstruct_patch`
 - `exstruct_read_json_chunk`
 - `exstruct_validate_input`
 
 Notes:
 
+- In MCP, `exstruct_extract` defaults to `options.alpha_col=true` (column keys: `A`, `B`, ...). Set `options.alpha_col=false` for legacy 0-based numeric string keys.
 - Logs go to stderr (and optionally `--log-file`) to avoid contaminating stdio responses.
 - On Windows with Excel, standard/verbose can use COM for richer extraction. On non-Windows, COM is unavailable and extraction uses openpyxl-based fallbacks.
 

{exstruct-0.4.2 → exstruct-0.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.4.2"
+version = "0.4.4"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -42,14 +42,14 @@ all = [
     "python-toon>=0.1.3",
     "pypdfium2>=5.1.0",
     "Pillow>=12.0.0",
-    "mcp>=1.6.0,<2.0.0",
+    "mcp>=1.25.0,<2.0.0",
     "httpx>=0.27,<1.0",
 ]
 yaml = ["pyyaml>=6.0.3"]
 toon = ["python-toon>=0.1.3"]
 render = ["pypdfium2>=5.1.0", "Pillow>=12.0.0"]
 mcp = [
-    "mcp>=1.6.0,<2.0.0",
+    "mcp>=1.25.0,<2.0.0",
     "httpx>=0.27,<1.0",
 ]
 
@@ -74,6 +74,7 @@ omit = [
 target-version = "py311"
 src = ["exstruct"]
 fix = true
+exclude = ["benchmark/**"]
 
 # 静的解析ルール
 [tool.ruff.lint]
@@ -113,6 +114,7 @@ max-complexity = 12
 [tool.mypy]
 packages = ["exstruct"]
 python_version = "3.11"
+exclude = "benchmark/.*"
 
 # 外部ライブラリの型情報がない場合は無視
 ignore_missing_imports = true
@@ -141,3 +143,8 @@ codecov-unit = "codecov-cli upload-process -f coverage.xml -F unit -C %CODECOV_S
 codecov-com = "codecov-cli upload-process -f coverage.xml -F com -C %CODECOV_SHA% -t %CODECOV_TOKEN%"
 docs = "mkdocs serve"
 build-docs = "mkdocs build && python scripts/gen_json_schema.py && python scripts/gen_model_docs.py"
+
+[tool.uv.workspace]
+members = [
+    "benchmark",
+]

{exstruct-0.4.2 → exstruct-0.4.4}/src/exstruct/__init__.py

@@ -41,6 +41,10 @@ from .models import (
     Shape,
     SheetData,
     WorkbookData,
+    col_index_to_alpha,
+    convert_row_keys_to_alpha,
+    convert_sheet_keys_to_alpha,
+    convert_workbook_keys_to_alpha,
 )
 from .render import export_pdf, export_sheet_images
 
@@ -82,19 +86,26 @@ __all__ = [
     "ColorsOptions",
     "serialize_workbook",
     "export_auto_page_breaks",
+    "col_index_to_alpha",
+    "convert_row_keys_to_alpha",
+    "convert_sheet_keys_to_alpha",
+    "convert_workbook_keys_to_alpha",
 ]
 
 
 ExtractionMode = Literal["light", "standard", "verbose"]
 
 
-def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> WorkbookData:
+def extract(
+    file_path: str | Path, mode: ExtractionMode = "standard", *, alpha_col: bool = False
+) -> WorkbookData:
     """
     Extracts an Excel workbook into a WorkbookData structure.
 
     Parameters:
         file_path (str | Path): Path to the workbook file (.xlsx, .xlsm, .xls).
         mode (ExtractionMode): Extraction detail level. "light" includes cells and table detection only (no COM, shapes/charts empty; print areas via openpyxl). "standard" includes texted shapes, arrows, charts (COM if available) and print areas. "verbose" also includes shape/chart sizes, cell link map, colors map, and formulas map.
+        alpha_col: When True, convert CellRow column keys to Excel-style ABC names (A, B, ..., Z, AA, ...) instead of 0-based numeric strings.
 
     Returns:
         WorkbookData: Parsed workbook representation containing sheets, rows, shapes, charts, and print areas.
@@ -108,6 +119,7 @@ def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> Workboo
             include_cell_links=include_links,
             include_colors_map=include_colors_map,
             include_formulas_map=include_formulas_map,
+            alpha_col=alpha_col,
         )
     )
     return engine.extract(file_path, mode=mode)
@@ -317,6 +329,8 @@ def process_excel(
     print_areas_dir: str | Path | None = None,
     auto_page_breaks_dir: str | Path | None = None,
     stream: TextIO | None = None,
+    *,
+    alpha_col: bool = False,
 ) -> None:
     """
     Convenience wrapper: extract -> serialize (file or stdout) -> optional PDF/PNG.
@@ -335,6 +349,8 @@ def process_excel(
         print_areas_dir: Directory to write per-print-area files (string or Path).
         auto_page_breaks_dir: Directory to write per-auto-page-break files (COM only).
         stream: IO override when output_path is None.
+        alpha_col: When True, convert CellRow column keys to Excel-style
+            ABC names (A, B, ...) instead of 0-based numeric strings.
 
     Raises:
         ValueError: If an unsupported format or mode is given.
@@ -353,7 +369,7 @@ def process_excel(
         >>> process_excel(Path("input.xlsx"), output_path=Path("out.json"), pdf=True)  # doctest: +SKIP
     """
     engine = ExStructEngine(
-        options=StructOptions(mode=mode),
+        options=StructOptions(mode=mode, alpha_col=alpha_col),
         output=OutputOptions(
             format=FormatOptions(fmt=out_fmt, pretty=pretty, indent=indent),
             filters=FilterOptions(

{exstruct-0.4.2 → exstruct-0.4.4}/src/exstruct/cli/main.py

@@ -109,6 +109,11 @@ def build_parser(
         availability if availability is not None else get_com_availability()
     )
     _add_auto_page_breaks_argument(parser, resolved_availability)
+    parser.add_argument(
+        "--alpha-col",
+        action="store_true",
+        help="Output column keys as Excel-style ABC names (A, B, ..., Z, AA, ...) instead of 0-based indices.",
+    )
     return parser
 
 
@@ -143,6 +148,7 @@ def main(argv: list[str] | None = None) -> int:
             sheets_dir=args.sheets_dir,
             print_areas_dir=args.print_areas_dir,
             auto_page_breaks_dir=getattr(args, "auto_page_breaks_dir", None),
+            alpha_col=args.alpha_col,
         )
         return 0
     except Exception as e:

{exstruct-0.4.2 → exstruct-0.4.4}/src/exstruct/engine.py

@@ -17,7 +17,7 @@ from .io import (
     save_sheets,
     serialize_workbook,
 )
-from .models import SheetData, WorkbookData
+from .models import SheetData, WorkbookData, convert_workbook_keys_to_alpha
 from .render import export_pdf, export_sheet_images
 
 ExtractionMode = Literal["light", "standard", "verbose"]
@@ -76,6 +76,8 @@ class StructOptions:
         include_merged_cells: Whether to extract merged cell ranges.
         include_merged_values_in_rows: Whether to keep merged values in rows.
         colors: Color extraction options.
+        alpha_col: When True, convert CellRow column keys to Excel-style
+            ABC names (A, B, ..., Z, AA, ...) instead of 0-based numeric strings.
     """
 
     mode: ExtractionMode = "standard"
@@ -88,6 +90,7 @@ class StructOptions:
     include_merged_cells: bool | None = None  # None -> auto: light=False, others=True
     include_merged_values_in_rows: bool = True
     colors: ColorsOptions = field(default_factory=ColorsOptions)
+    alpha_col: bool = False
 
 
 class FormatOptions(BaseModel):
@@ -314,6 +317,9 @@ class ExStructEngine:
             merged_cells=sheet.merged_cells
             if self.output.filters.include_merged_cells
             else None,
+            merged_ranges=sheet.merged_ranges
+            if self.output.filters.include_merged_cells
+            else [],
         )
 
     def _filter_workbook(
@@ -383,7 +389,7 @@ class ExStructEngine:
         )
         normalized_file_path = self._ensure_path(file_path)
         with self._table_params_scope():
-            return extract_workbook(
+            workbook = extract_workbook(
                 normalized_file_path,
                 mode=chosen_mode,
                 include_cell_links=self.options.include_cell_links,
@@ -396,6 +402,9 @@ class ExStructEngine:
                 include_merged_cells=self.options.include_merged_cells,
                 include_merged_values_in_rows=self.options.include_merged_values_in_rows,
             )
+        if self.options.alpha_col:
+            workbook = convert_workbook_keys_to_alpha(workbook)
+        return workbook
 
     def serialize(
         self,

{exstruct-0.4.2 → exstruct-0.4.4}/src/exstruct/errors.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from enum import Enum
+from enum import StrEnum
 
 
 class ExstructError(Exception):
@@ -37,7 +37,7 @@ class PrintAreaError(ExstructError, ValueError):
     """Raised when print-area specific processing fails (also a ValueError for compatibility)."""
 
 
-class FallbackReason(str, Enum):
+class FallbackReason(StrEnum):
     """Reason codes for extraction fallbacks."""
 
     LIGHT_MODE = "light_mode"

exstruct-0.4.4/src/exstruct/mcp/__init__.py

@@ -0,0 +1,125 @@
+"""MCP server integration for ExStruct."""
+
+from __future__ import annotations
+
+from .chunk_reader import (
+    ReadJsonChunkFilter,
+    ReadJsonChunkRequest,
+    ReadJsonChunkResult,
+    read_json_chunk,
+)
+from .extract_runner import (
+    ExtractOptions,
+    ExtractRequest,
+    ExtractResult,
+    WorkbookMeta,
+    run_extract,
+)
+from .io import PathPolicy
+from .patch_runner import (
+    FormulaIssue,
+    PatchDiffItem,
+    PatchErrorDetail,
+    PatchOp,
+    PatchRequest,
+    PatchResult,
+    PatchValue,
+    run_patch,
+)
+from .sheet_reader import (
+    CellReadItem,
+    FormulaReadItem,
+    ReadCellsRequest,
+    ReadCellsResult,
+    ReadFormulasRequest,
+    ReadFormulasResult,
+    ReadRangeRequest,
+    ReadRangeResult,
+    read_cells,
+    read_formulas,
+    read_range,
+)
+from .tools import (
+    ExtractToolInput,
+    ExtractToolOutput,
+    PatchToolInput,
+    PatchToolOutput,
+    ReadCellsToolInput,
+    ReadCellsToolOutput,
+    ReadFormulasToolInput,
+    ReadFormulasToolOutput,
+    ReadJsonChunkToolInput,
+    ReadJsonChunkToolOutput,
+    ReadRangeToolInput,
+    ReadRangeToolOutput,
+    ValidateInputToolInput,
+    ValidateInputToolOutput,
+    run_extract_tool,
+    run_patch_tool,
+    run_read_cells_tool,
+    run_read_formulas_tool,
+    run_read_json_chunk_tool,
+    run_read_range_tool,
+    run_validate_input_tool,
+)
+from .validate_input import (
+    ValidateInputRequest,
+    ValidateInputResult,
+    validate_input,
+)
+
+__all__ = [
+    "ExtractRequest",
+    "ExtractResult",
+    "ExtractOptions",
+    "ExtractToolInput",
+    "ExtractToolOutput",
+    "FormulaIssue",
+    "FormulaReadItem",
+    "PatchDiffItem",
+    "PatchErrorDetail",
+    "PatchOp",
+    "PatchRequest",
+    "PatchResult",
+    "PatchToolInput",
+    "PatchToolOutput",
+    "PatchValue",
+    "PathPolicy",
+    "ReadCellsRequest",
+    "ReadCellsResult",
+    "ReadCellsToolInput",
+    "ReadCellsToolOutput",
+    "ReadFormulasRequest",
+    "ReadFormulasResult",
+    "ReadFormulasToolInput",
+    "ReadFormulasToolOutput",
+    "ReadJsonChunkFilter",
+    "ReadJsonChunkRequest",
+    "ReadJsonChunkResult",
+    "ReadJsonChunkToolInput",
+    "ReadJsonChunkToolOutput",
+    "ReadRangeRequest",
+    "ReadRangeResult",
+    "ReadRangeToolInput",
+    "ReadRangeToolOutput",
+    "CellReadItem",
+    "ValidateInputRequest",
+    "ValidateInputResult",
+    "ValidateInputToolInput",
+    "ValidateInputToolOutput",
+    "WorkbookMeta",
+    "read_json_chunk",
+    "validate_input",
+    "run_extract",
+    "run_extract_tool",
+    "run_patch",
+    "run_patch_tool",
+    "read_cells",
+    "read_formulas",
+    "run_read_json_chunk_tool",
+    "read_range",
+    "run_read_cells_tool",
+    "run_read_formulas_tool",
+    "run_read_range_tool",
+    "run_validate_input_tool",
+]