Metadata-Version: 2.5
Name: sheet-unmess
Version: 1.0.0
Summary: Forensic Messy-Excel & Dirty-CSV Ingestor with Tamper-Evident Audit Receipts and Native MCP Server
Project-URL: Homepage, https://github.com/sheet-unmess/sheet-unmess
Project-URL: Documentation, https://github.com/sheet-unmess/sheet-unmess#readme
Project-URL: Repository, https://github.com/sheet-unmess/sheet-unmess
Author: Sheet Unmess Contributors
License: MIT
Keywords: audit,claude,csv,cursor,data-cleaning,excel,llm-agent,mcp,mcp-server,pandas,windsurf
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: python-dateutil>=2.8.2
Provides-Extra: all
Requires-Dist: polars>=0.20.0; extra == 'all'
Provides-Extra: polars
Requires-Dist: polars>=0.20.0; extra == 'polars'
Description-Content-Type: text/markdown

# sheet-unmess

Forensic-style ingestion for messy Excel (`.xlsx`) and CSV files. It attempts to
identify headers, remove common non-data rows, normalize common number formats,
and produce a human-readable audit receipt.

> **Important:** automatic header/row classification is heuristic. Always inspect
> the output and reconciliation receipt before using cleaned data for financial,
> regulatory, or other high-stakes decisions. A receipt is an audit report, not a
> cryptographic signature or proof that no data was lost.

## Features

- Detects likely header rows and combines adjacent stacked headers.
- Propagates values from the top-left cell across merged Excel ranges.
- Classifies common title, blank, footnote, subtotal, and grand-total rows.
- Parses common US/EU number formats, accounting negatives, and percentages.
- Optionally returns a cleaning report with dropped-row details and total checks.
- Provides a CLI and a stdio MCP server for compatible AI clients.

## Install from source

Python 3.10 or newer is required.

```bash
python -m venv .venv
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -e .
```

## Quick start

```python
from sheet_unmess import read_messy

df = read_messy("quarterly_report.xlsx")
print(df.head())

report = read_messy("quarterly_report.xlsx", return_report=True)
print(report.data.head())
print(report.receipt.to_markdown())
```

For European day-first dates, pass `date_dayfirst=True`.

## CLI

```bash
sheet-unmess clean input.xlsx --out cleaned.csv --receipt audit.md
sheet-unmess clean input.csv --out cleaned.csv --dayfirst
sheet-unmess clean input.xlsx --sheet Financials --out cleaned.csv
sheet-unmess init-ai
```

`--out` writes CSV by default; use a `.parquet` extension for Parquet output
(and install a suitable Parquet engine such as `pyarrow`).

## Tests

```bash
python -m pip install -e ".[dev]"
python -m pytest
```

Or run the included test file directly:

```bash
python tests/test_sheet_unmess.py
```

## MCP server

The package exposes `sheet-unmess-mcp` and `sheet-unmess mcp`. Example generic
stdio MCP configuration:

```json
{
  "mcpServers": {
    "sheet-unmess": {
      "command": "python",
      "args": ["-m", "sheet_unmess.mcp_server"]
    }
  }
}
```

Ensure the `python` executable points to the environment where `sheet-unmess`
is installed. The `sheet-unmess init-ai` command writes project rules, a Cursor
MCP configuration, and attempts to update the Claude Desktop configuration.
Review generated configuration before using it.

## Current limitations

- `.xls` legacy Excel files are not supported by the current openpyxl loader.
- Header detection and row classification are heuristic and may need manual review.
- Reconciliation currently compares embedded totals against aggregated clean-row
  sums; nested subtotals and multiple independent sections can require more
  sophisticated grouping logic.
- Mixed ambiguous dates cannot be inferred reliably; use `date_dayfirst` when
  appropriate.
- The MCP server reads files by local path and therefore needs filesystem access
  to the file being processed.

## License

MIT
