carloforte 0.1.0__tar.gz

carloforte-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.3
+Name: carloforte
+Version: 0.1.0
+Summary: Extract structured data from Excel files with minimal token usage
+Keywords: excel,xlsx,llm,extraction,json
+Author: Giovanni De Cillis
+Author-email: Giovanni De Cillis <giovanni.decillis@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pre-commit>=4.6.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# carloforte
+
+Extract structured data from Excel files with minimal token usage.
+
+carloforte uses an island-detection algorithm to convert Excel sheets into a compact intermediate representation (CSV, Markdown, or JSON), making it efficient to pass spreadsheet data to LLMs.
+
+## Installation
+TBC
+
+## Usage
+
+```python
+import carloforte
+
+# Extract all sheets as CSV (default)
+text = carloforte.extract("data.xlsx")
+
+# Extract specific sheets as Markdown
+text = carloforte.extract("data.xlsx", sheets=["Revenue", "Costs"], fmt="markdown")
+
+# Extract as JSON
+text = carloforte.extract("data.xlsx", fmt="json")
+```
+
+### Formats
+
+| Format | Best for |
+|--------|----------|
+| `csv` | Compact, low token count |
+| `markdown` | Readable, good for LLM prompts |
+| `json` | Structured output, programmatic use |
+
+### CLI
+
+```bash
+carloforte data.xlsx --fmt markdown
+carloforte data.xlsx --sheets Revenue Costs --fmt json
+```
+
+## How it works
+
+Excel sheets often contain multiple disconnected tables, empty rows, and metadata scattered around. carloforte detects each contiguous block of data ("island") independently and serialises only what matters — reducing token usage by 60–75% compared to passing raw Excel content to an LLM.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["📄 .xlsx file"] --> B["_reader\nload sheets"]
+    B --> C["dict[sheet → grid]"]
+    C --> D["_islands\nBFS detection"]
+    D --> E["dict[sheet → islands]"]
+    E --> F{"fmt?"}
+    F -->|csv| G["CSV"]
+    F -->|markdown| H["Markdown"]
+    F -->|json| I["JSON"]
+```
+
+## License
+
+MIT

carloforte-0.1.0/README.md

@@ -0,0 +1,60 @@
+# carloforte
+
+Extract structured data from Excel files with minimal token usage.
+
+carloforte uses an island-detection algorithm to convert Excel sheets into a compact intermediate representation (CSV, Markdown, or JSON), making it efficient to pass spreadsheet data to LLMs.
+
+## Installation
+TBC
+
+## Usage
+
+```python
+import carloforte
+
+# Extract all sheets as CSV (default)
+text = carloforte.extract("data.xlsx")
+
+# Extract specific sheets as Markdown
+text = carloforte.extract("data.xlsx", sheets=["Revenue", "Costs"], fmt="markdown")
+
+# Extract as JSON
+text = carloforte.extract("data.xlsx", fmt="json")
+```
+
+### Formats
+
+| Format | Best for |
+|--------|----------|
+| `csv` | Compact, low token count |
+| `markdown` | Readable, good for LLM prompts |
+| `json` | Structured output, programmatic use |
+
+### CLI
+
+```bash
+carloforte data.xlsx --fmt markdown
+carloforte data.xlsx --sheets Revenue Costs --fmt json
+```
+
+## How it works
+
+Excel sheets often contain multiple disconnected tables, empty rows, and metadata scattered around. carloforte detects each contiguous block of data ("island") independently and serialises only what matters — reducing token usage by 60–75% compared to passing raw Excel content to an LLM.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["📄 .xlsx file"] --> B["_reader\nload sheets"]
+    B --> C["dict[sheet → grid]"]
+    C --> D["_islands\nBFS detection"]
+    D --> E["dict[sheet → islands]"]
+    E --> F{"fmt?"}
+    F -->|csv| G["CSV"]
+    F -->|markdown| H["Markdown"]
+    F -->|json| I["JSON"]
+```
+
+## License
+
+MIT

carloforte-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "carloforte"
+version = "0.1.0"
+description = "Extract structured data from Excel files with minimal token usage"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Giovanni De Cillis", email = "giovanni.decillis@gmail.com" }
+]
+keywords = ["excel", "xlsx", "llm", "extraction", "json"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "loguru>=0.7.3",
+    "openpyxl>=3.1.5",
+    "pre-commit>=4.6.0",
+]
+
+[project.scripts]
+carloforte = "carloforte:main"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "commitizen>=4.16.4",
+    "pre-commit>=4.0",
+    "mypy>=1.16",
+    "openpyxl-stubs",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.1.0"
+version_files = ["pyproject.toml:version"]
+tag_format = "v$version"
+update_changelog_on_bump = true

carloforte-0.1.0/src/carloforte/__init__.py

@@ -0,0 +1,41 @@
+import argparse
+from loguru import logger
+from ._reader import load_workbook_sheets
+from ._islands import find_islands
+from ._serialiser import serialise
+
+logger.disable("carloforte")
+
+_FORMATS = ("csv", "markdown", "json")
+
+
+def extract(
+    path: str,
+    sheets: list[str] | None = None,
+    fmt: str = "csv",
+) -> str:
+    if fmt not in _FORMATS:
+        raise ValueError(f"Unknown format {fmt!r}. Choose: {_FORMATS}")
+    logger.debug(
+        "Loading {path}, sheets={sheets}, fmt={fmt}", path=path, sheets=sheets, fmt=fmt
+    )
+    grids = load_workbook_sheets(path, sheets)
+    logger.debug("Loaded {n} sheet(s)", n=len(grids))
+    sheet_islands = {name: find_islands(grid) for name, grid in grids.items()}
+    logger.debug(
+        "Found islands: { {name: len(isl)} for name, isl in sheet_islands.items() }"
+    )
+    return serialise(path, sheet_islands, fmt)
+
+
+def main() -> None:
+    logger.enable("carloforte")
+    parser = argparse.ArgumentParser(prog="carloforte")
+    parser.add_argument("file", help="Path to the Excel file")
+    parser.add_argument("--sheets", nargs="+", help="Sheet names to process")
+    parser.add_argument("--fmt", default="csv", choices=_FORMATS, help="Output format")
+    args = parser.parse_args()
+    print(extract(args.file, sheets=args.sheets, fmt=args.fmt))
+
+
+__all__ = ["extract"]

carloforte-0.1.0/src/carloforte/_islands.py

@@ -0,0 +1,70 @@
+from collections import deque
+from ._models import Island, CellValue
+
+CellGrid = list[list[CellValue]]
+
+
+def detect_header_row(cells: list[list[CellValue]]) -> int:
+    for i, row in enumerate(cells):
+        non_null = [v for v in row if v is not None]
+        if non_null and all(isinstance(v, str) for v in non_null):
+            return i
+    return 0
+
+
+def find_islands(grid: CellGrid) -> list[Island]:
+    if not grid:
+        return []
+
+    max_row = len(grid)
+    max_col = max((len(row) for row in grid), default=0)
+
+    for row in grid:
+        while len(row) < max_col:
+            row.append(None)
+
+    visited = [[False] * max_col for _ in range(max_row)]
+    islands: list[Island] = []
+
+    for start_r in range(max_row):
+        for start_c in range(max_col):
+            if visited[start_r][start_c] or grid[start_r][start_c] is None:
+                visited[start_r][start_c] = True
+                continue
+
+            component: set[tuple[int, int]] = set()
+            queue: deque[tuple[int, int]] = deque()
+            queue.append((start_r, start_c))
+            visited[start_r][start_c] = True
+
+            while queue:
+                r, c = queue.popleft()
+                component.add((r, c))
+                for dr, dc in ((-1, 0), (1, 0), (0, -1), (0, 1)):
+                    nr, nc = r + dr, c + dc
+                    if (
+                        0 <= nr < max_row
+                        and 0 <= nc < max_col
+                        and not visited[nr][nc]
+                        and grid[nr][nc] is not None
+                    ):
+                        visited[nr][nc] = True
+                        queue.append((nr, nc))
+
+            min_r = min(r for r, _ in component)
+            max_r = max(r for r, _ in component)
+            min_c = min(c for _, c in component)
+            max_c = max(c for _, c in component)
+
+            islands.append(
+                Island(
+                    top_row=min_r + 1,
+                    left_col=min_c + 1,
+                    cells=[
+                        [grid[r][c] for c in range(min_c, max_c + 1)]
+                        for r in range(min_r, max_r + 1)
+                    ],
+                )
+            )
+
+    return islands

carloforte-0.1.0/src/carloforte/_models.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+CellValue = str | int | float | bool | None
+
+
+@dataclass
+class Island:
+    top_row: int  # 1-indexed (Excel convention)
+    left_col: int  # 1-indexed
+    cells: list[list[CellValue]]
+
+    @property
+    def height(self) -> int:
+        return len(self.cells)
+
+    @property
+    def width(self) -> int:
+        return len(self.cells[0]) if self.cells else 0

carloforte-0.1.0/src/carloforte/_reader.py

@@ -0,0 +1,21 @@
+import openpyxl
+from ._models import CellValue
+
+CellGrid = list[list[CellValue]]
+
+
+def load_workbook_sheets(
+    path: str,
+    sheets: list[str] | None = None,
+) -> dict[str, CellGrid]:
+    wb = openpyxl.load_workbook(path, read_only=True, data_only=True)
+    names = sheets if sheets is not None else list(wb.sheetnames)
+    result: dict[str, CellGrid] = {}
+    for name in names:
+        if name not in wb.sheetnames:
+            wb.close()
+            raise KeyError(f"Sheet '{name}' not found in {path!r}")
+        ws = wb[name]
+        result[name] = [list(row) for row in ws.iter_rows(values_only=True)]
+    wb.close()
+    return result

carloforte-0.1.0/src/carloforte/_serialiser.py

@@ -0,0 +1,91 @@
+import csv
+import io
+import json
+import re
+from ._models import Island, CellValue
+from ._islands import detect_header_row
+
+CellGrid = list[list[CellValue]]
+
+
+def col_letter(n: int) -> str:
+    result = ""
+    while n > 0:
+        n, remainder = divmod(n - 1, 26)
+        result = chr(65 + remainder) + result
+    return result
+
+
+def range_str(island: Island) -> str:
+    top_left = f"{col_letter(island.left_col)}{island.top_row}"
+    bottom_right = f"{col_letter(island.left_col + island.width - 1)}{island.top_row + island.height - 1}"
+    return f"{top_left}:{bottom_right}"
+
+
+def _cell(v: CellValue) -> str:
+    return "" if v is None else str(v)
+
+
+def _safe_id(name: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9]", "_", name)
+
+
+def _to_csv(sheet_islands: dict[str, list[Island]]) -> str:
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    for sheet_name, islands in sheet_islands.items():
+        for island in islands:
+            buf.write(f"# {sheet_name} · {range_str(island)}\n")
+            for row in island.cells:
+                writer.writerow([_cell(v) for v in row])
+            buf.write("\n")
+    return buf.getvalue()
+
+
+def _to_markdown(path: str, sheet_islands: dict[str, list[Island]]) -> str:
+    def md_cell(v: CellValue) -> str:
+        return _cell(v).replace("|", "\\|")
+
+    filename = __import__("pathlib").Path(path).name
+    sections = [f"# {filename}\n"]
+    for sheet_name, islands in sheet_islands.items():
+        sections.append(f"## Sheet: {sheet_name}\n")
+        if not islands:
+            sections.append("_No data islands found._\n")
+            continue
+        for idx, island in enumerate(islands):
+            table_id = f"{_safe_id(sheet_name)}_t{idx}"
+            header_idx = detect_header_row(island.cells)
+            headers = [md_cell(v) for v in island.cells[header_idx]]
+            # rows before the header (pre-header data) + rows after
+            pre_header = island.cells[:header_idx]
+            rows = pre_header + island.cells[header_idx + 1 :]
+            sections.append(f"### {table_id} · {range_str(island)}")
+            sections.append("| " + " | ".join(headers) + " |")
+            sections.append("| " + " | ".join("---" for _ in headers) + " |")
+            for row in rows:
+                padded = list(row) + [None] * (len(headers) - len(row))
+                sections.append("| " + " | ".join(md_cell(v) for v in padded) + " |")
+            sections.append("")
+    return "\n".join(sections)
+
+
+def _to_json(sheet_islands: dict[str, list[Island]]) -> str:
+    result = {}
+    for sheet_name, islands in sheet_islands.items():
+        result[sheet_name] = [{"range": range_str(i), "rows": i.cells} for i in islands]
+    return json.dumps(result, default=str)
+
+
+def serialise(
+    path: str,
+    sheet_islands: dict[str, list[Island]],
+    fmt: str,
+) -> str:
+    if fmt == "csv":
+        return _to_csv(sheet_islands)
+    if fmt == "markdown":
+        return _to_markdown(path, sheet_islands)
+    if fmt == "json":
+        return _to_json(sheet_islands)
+    raise ValueError(f"Unknown format {fmt!r}. Choose: 'csv', 'markdown', 'json'")