Metadata-Version: 2.5
Name: smart-excel-reader
Version: 0.7.0
Summary: Extract tables, charts, images, hyperlinks, and worksheet structure from Excel workbooks.
Author: Atreyo Chakrabarty
License-Expression: MIT
License-File: LICENSE
Keywords: business-intelligence,charts,data-extraction,excel,openpyxl,spreadsheet,tables,workbook,xlsm,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: pillow<13,>=10
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: ai
Requires-Dist: openai<3,>=1.50; extra == 'ai'
Provides-Extra: all
Requires-Dist: formualizer<1,>=0.13; extra == 'all'
Requires-Dist: google-genai<3,>=1.0; extra == 'all'
Requires-Dist: matplotlib<4,>=3.8; extra == 'all'
Requires-Dist: openai<3,>=1.50; extra == 'all'
Requires-Dist: pandas<4,>=2.2; extra == 'all'
Requires-Dist: pytesseract<1,>=0.3.10; extra == 'all'
Provides-Extra: data
Requires-Dist: pandas<4,>=2.2; extra == 'data'
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Provides-Extra: formula
Requires-Dist: formualizer<1,>=0.13; extra == 'formula'
Requires-Dist: google-genai<3,>=1.0; extra == 'formula'
Provides-Extra: gemini
Requires-Dist: google-genai<3,>=1.0; extra == 'gemini'
Provides-Extra: ocr
Requires-Dist: pytesseract<1,>=0.3.10; extra == 'ocr'
Provides-Extra: render
Requires-Dist: matplotlib<4,>=3.8; extra == 'render'
Description-Content-Type: text/markdown

# Smart Excel Reader

Smart Excel Reader is a Python library and command-line tool for inspecting and extracting structured information from Excel `.xlsx` and `.xlsm` workbooks. It inventories worksheets, detects candidate table regions, exports accepted table ranges to CSV, extracts native chart metadata to JSON, preserves embedded image assets, records hyperlinks, and writes a validated `manifest.json` bundle.

The core extraction path is local and deterministic; it does not require an API key. Optional Gemini or OpenAI integrations can classify layouts and create descriptions, summaries, and question-answering responses. AI features are opt-in; local extraction and local evidence-based Q&A do not require an API key. The package reads workbook formulas and cached results when available; the core extractor does **not** recalculate Excel formulas.

## Installation

Python 3.11 or newer is required.

```powershell
py -m pip install --upgrade pip
py -m pip install smart-excel-reader
```

Optional integrations are installed only when needed:

| Extra | Adds | Notes |
|---|---|---|
| `gemini` | Google Gemini SDK | Used for Gemini-assisted extraction, summaries, and Q&A. Requires an API key and internet access. |
| `ai` | OpenAI SDK | Enables OpenAI for AI-assisted extraction, summaries, and Q&A. |
| `data` | pandas | Enables the DataFrame helper API. |
| `ocr` | pytesseract | Also requires a separate local Tesseract executable. |
| `render` | Matplotlib | Supports the optional chart-preview helper module; chart previews are not exposed as a CLI flag in this version. |
| `formula` | Google Gemini SDK and Formualizer | Enables the companion formula-suggestion workflow in `formula_assistant.py`. |
| `all` | All optional integrations above | Larger install, including both AI providers and Formualizer's platform-specific wheel. |
| `dev` | pytest, coverage, build, and Twine | For tests and distribution building. |

Examples:

```powershell
py -m pip install "smart-excel-reader[gemini]"
py -m pip install "smart-excel-reader[formula]"
py -m pip install "smart-excel-reader[all,dev]"
```

In PowerShell, quote extras such as `"smart-excel-reader[gemini]"` to avoid shell interpretation issues.

## Use it as a Python library

```python
from excel_extract import extract_workbook

manifest = extract_workbook(
    "quarterly_report.xlsx",
    "outputs/quarterly_report",
)

print(manifest.model_dump_json(indent=2))
```

`extract_workbook(workbook_path, output_dir)` returns a Pydantic `Manifest`. The output directory contains `manifest.json`, `validation.json`, occupancy artifacts, accepted table CSV files, chart JSON, embedded image assets, cell sidecars, and RAG chunks. If the output directory already exists and is not empty, pass `overwrite=True` only when you intend to replace its contents.

For example:

```python
from excel_extract import extract_workbook

manifest = extract_workbook(
    "quarterly_report.xlsx",
    "outputs/quarterly_report",
    overwrite=True,
    infer_tables=True,
)
print(manifest.workbook.file_name)
print(len(manifest.sheets))
```

## Use the command line

After installation, run:

```powershell
excel-extract --help
```

If the installed command is not on `PATH`, use the module form:

```powershell
python -m excel_extract --help
```

### Inspect a workbook

```powershell
excel-extract inspect ".\quarterly_report.xlsx" --json
```

This prints worksheet and OOXML relationship information without creating an extraction bundle.

### Extract a workbook offline

```powershell
excel-extract extract ".\quarterly_report.xlsx" --out ".\outputs\quarterly_report"
```

Use `--overwrite` to reuse a non-empty output directory, `--no-infer-tables` to extract native Excel tables only, or `--max-cells 250000` to set a lower per-worksheet cell limit.

### Enable Gemini or OpenAI

Install only the provider you plan to use:

```powershell
py -m pip install "smart-excel-reader[gemini]"
# OR
py -m pip install "smart-excel-reader[ai]"
```

Set the matching API key in PowerShell. These examples apply to the current terminal session; do not hard-code keys into scripts or commit them to files.

```powershell
# Gemini
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"

# OR OpenAI
$env:OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"
```

Use the provider explicitly for predictable behavior:

```powershell
# Ask from an existing extraction bundle with Gemini
excel-extract ask ".\outputs\quarterly_report\manifest.json" "Summarize the workbook" --provider gemini

# Ask with OpenAI
excel-extract ask ".\outputs\quarterly_report\manifest.json" "Summarize the workbook" --provider openai

# Local Q&A: no cloud API key or network request
excel-extract ask ".\outputs\quarterly_report\manifest.json" "Which worksheets contain charts?" --provider local

# Optional model override; choose a model enabled for your API account
excel-extract ask ".\outputs\quarterly_report\manifest.json" "Summarize the workbook" --provider openai --model "gpt-4o-mini"
```

For AI-assisted extraction and chart/image interpretation:

```powershell
excel-extract extract ".\quarterly_report.xlsx" --out ".\outputs\quarterly_report_ai" --provider gemini
# Or use OpenAI:
excel-extract extract ".\quarterly_report.xlsx" --out ".\outputs\quarterly_report_ai_openai" --provider openai
```

The legacy `--ai` flag is retained as a compatibility alias for enabling AI mode. `--provider auto` selects Gemini if a Gemini key is set, otherwise OpenAI if an OpenAI key is set, and otherwise local mode. For reproducible scripts, specify `--provider local`, `--provider gemini`, or `--provider openai` explicitly. `--model` overrides the provider's default model. Gemini uses `GEMINI_API_KEY` (or `GOOGLE_API_KEY`); OpenAI uses `OPENAI_API_KEY`.

**Privacy and cost:** When Gemini or OpenAI is selected, relevant workbook evidence and/or occupancy images may be sent to that provider's API. Review sensitive workbooks before enabling AI. Provider API usage may incur charges and is subject to provider quotas. Local mode keeps question answering on the machine and does not call a cloud LLM.

### Validate an extraction bundle

```powershell
excel-extract validate ".\outputs\quarterly_report\manifest.json"
```

### Formula suggestions (optional companion tool)

Install the extra that provides Gemini suggestions and Formualizer-based recalculation support:

```powershell
py -m pip install "smart-excel-reader[formula]"
$env:GEMINI_API_KEY = "YOUR_API_KEY"
python -m formula_assistant ".\quarterly_report.xlsx" --question "Suggest formulas for totals and averages."
```

By default, the formula assistant reports validated suggestions and does not modify the source workbook. Adding `--apply` writes approved formulas to a separate workbook and invokes Formualizer to recalculate it; review the report and generated files before using them.

## CLI reference

| Command | Purpose |
|---|---|
| `inspect WORKBOOK [--json]` | Inspect worksheet names, states, and workbook relationships. |
| `extract WORKBOOK --out DIR` | Extract workbook artifacts and write a manifest. |
| `validate MANIFEST` | Validate the manifest and referenced artifacts. |
| `summarize MANIFEST [--provider auto\|local\|gemini\|openai]` | Write a report with optional AI insights. |
| `ask MANIFEST QUESTION [--provider auto\|local\|gemini\|openai]` | Ask a question using extracted evidence and return citations. |

The accepted `extract` options are `--out`, `--overwrite`, `--no-infer-tables`, `--max-cells`, `--ai`, `--provider`, and `--model`. Run `excel-extract COMMAND --help` for command-specific options. Some lower-level helpers (such as DataFrame conversion and approximate chart rendering) are available as Python APIs, but this release does not expose dedicated `dataframes`, `occupancy`, or `--render-charts` CLI options.

## Supported formats and limitations

- Supported workbook formats: `.xlsx` and `.xlsm`.
- Not supported: legacy `.xls`, binary `.xlsb`, password-protected workbooks, and macro execution.
- `openpyxl` does not calculate formulas. Formula values depend on cached values saved by Excel or another calculation engine; stale or missing caches can limit interpretation.
- Inferred table boundaries are heuristic and should be reviewed when a worksheet contains irregular layouts or touching tables.
- Gemini and OpenAI features require a compatible API key, network access, and the corresponding optional dependency. When enabled, bounded workbook content can be sent to the configured model; do not enable AI mode for workbooks that must remain entirely local.
- OCR requires both the Python `pytesseract` wrapper and a separately installed Tesseract executable.
- Matplotlib chart previews, when called through the helper API, are approximations and are not pixel-faithful Excel renderings.

## Development and release

For local testing, building wheels/source distributions, and publishing manually to PyPI without Git hosting, see [`PYPI_PUBLISHING.md`](PYPI_PUBLISHING.md).

```powershell
py -m pip install -e ".[dev]"
python -m pytest
python -m build
python -m twine check dist/*
```

## License

Smart Excel Reader is distributed under the MIT License. See [`LICENSE`](LICENSE).
