Metadata-Version: 2.4
Name: sheetspec
Version: 0.1.2
Summary: Contract-based validation for spreadsheets created by AI agents.
Project-URL: Homepage, https://github.com/helloo1568/SheetSpec
Project-URL: Repository, https://github.com/helloo1568/SheetSpec
Project-URL: Issues, https://github.com/helloo1568/SheetSpec/issues
Project-URL: Changelog, https://github.com/helloo1568/SheetSpec/blob/main/CHANGELOG.md
Author: SheetSpec Contributors
License: MIT
License-File: LICENSE
Keywords: ai-agent,contract-testing,data-quality,excel,mcp,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: jinja2<4,>=3.1.6
Requires-Dist: mcp<2,>=1.28
Requires-Dist: openpyxl<4,>=3.1.5
Requires-Dist: pydantic<3,>=2.13
Requires-Dist: pyyaml<7,>=6.0.3
Requires-Dist: typer<1,>=0.27
Description-Content-Type: text/markdown

# SheetSpec

<!-- mcp-name: io.github.helloo1568/sheetspec -->

**English** | [简体中文](README.zh-CN.md)

[![CI](https://github.com/helloo1568/SheetSpec/actions/workflows/test.yml/badge.svg)](https://github.com/helloo1568/SheetSpec/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/sheetspec.svg)](https://pypi.org/project/sheetspec/)
[![Python](https://img.shields.io/pypi/pyversions/sheetspec.svg)](https://pypi.org/project/sheetspec/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> **Contract testing and quality gates for spreadsheets created by AI agents.**

Agents create spreadsheets. SheetSpec decides whether those spreadsheets satisfy the
acceptance rules declared by the user.

SheetSpec is not an Excel chatbot and does not silently repair workbooks. It is an
independent, deterministic, repeatable delivery gate:

```text
user requirements
  → acceptance contract
  → agent creates or edits Excel
  → SheetSpec validates
  → structured repair issues
  → agent repairs and revalidates
  → deliver only after passing
```

![Agent Gate Demo](docs/agent-gate-demo.gif)

![SheetSpec Architecture](docs/architecture.svg)

![Validation Report Preview](docs/validation-report-preview.svg)

## Why SheetSpec?

An agent can generate a workbook that looks correct while still containing hidden
delivery failures:

- missing worksheets or columns;
- numeric values stored as text;
- duplicate identifiers;
- missing formulas;
- inconsistent formula references;
- totals that do not match their source ranges;
- unauthorized changes to protected template regions.

SheetSpec does not claim to understand every business requirement. It validates only
the explicit contract supplied by the user and reports issues at worksheet, cell, or
range level.

## 60-second quick start

SheetSpec supports Python 3.11–3.14. With
[uv](https://docs.astral.sh/uv/), no installation or repository clone is required:

```bash
uvx sheetspec --version
uvx sheetspec inspect report.xlsx --format json
uvx sheetspec init report.xlsx --output report.spec.yaml
uvx sheetspec check report.xlsx --spec report.spec.yaml --format json
```

Or install it permanently:

```bash
pip install sheetspec
```

To run the complete broken/fixed demo:

```bash
git clone https://github.com/helloo1568/SheetSpec.git
cd SheetSpec
uv sync
uv run python examples/create_demo.py

uv run sheetspec check examples/sales-report-broken.xlsx \
  --spec examples/sales-report.spec.yaml \
  --format text

uv run sheetspec check examples/sales-report-fixed.xlsx \
  --spec examples/sales-report.spec.yaml \
  --format json
```

Expected result for the fixed workbook:

```text
status: passed
checks: 12
passed: 12
errors: 0
warnings: 0
```

## Agent Gate

```mermaid
flowchart LR
  A["Describe requirements"] --> B["draft_workbook_spec"]
  B --> C["Review contract"]
  C --> D["sheetspec lock"]
  D --> E["Agent creates or edits Excel"]
  E --> F["validate_workbook"]
  F -->|failed| G["Read structured issues and repair"]
  G --> F
  F -->|passed| H["Deliver workbook and report"]
```

The contract lock stores SHA-256 hashes for the normalized contract and optional
baseline workbook. It detects changes; Git history, review, and CI remain the security
boundary.

## Contract example

```yaml
version: "0.1"
name: Annual sales report acceptance
baseline: sales-report-template.xlsx

checks:
  - id: required-sheets
    type: required_sheets
    sheets: [Raw Data, Monthly Summary]

  - id: order-id-unique
    type: unique_values
    sheet: Raw Data
    range: A2:A500

  - id: amount-formulas
    type: formulas_required
    sheet: Raw Data
    range: F2:F500

  - id: annual-total
    type: total_equals_sum
    sheet: Monthly Summary
    total_cell: N2
    source_range: B2:M2
    tolerance: 0.01

  - id: protect-summary-header
    type: unchanged_ranges
    sheet: Monthly Summary
    ranges: [A1:N1]
    compare: both
```

### Included rules

| Rule | Purpose |
| --- | --- |
| `required_sheets` | Require worksheets |
| `required_columns` | Require exact column names |
| `required_cells` | Require non-empty cells or exact values |
| `no_blank_values` | Reject blank cells in a range |
| `unique_values` | Require unique values |
| `allowed_values` | Restrict values to an allowlist |
| `data_type` | Validate numbers, text, dates, booleans, or formulas |
| `formulas_required` | Require formulas |
| `formula_consistency` | Detect structural formula outliers |
| `total_equals_sum` | Compare a total with the numeric source range |
| `unchanged_ranges` | Protect baseline values and formulas |

## CLI

```bash
sheetspec --version
sheetspec inspect report.xlsx --format json
sheetspec init report.xlsx --output report.spec.yaml
sheetspec lock report.spec.yaml --output report.spec.lock.json
sheetspec check report.xlsx --spec report.spec.yaml --format json
sheetspec diff before.xlsx after.xlsx --format json
sheetspec report report.xlsx --spec report.spec.yaml --output report.html
sheetspec mcp
```

Exit codes:

```text
0  validation passed
1  one or more error-level rules failed
2  invalid file, contract, baseline, or lock
3  internal error
```

## MCP

Start the local STDIO MCP server:

```bash
uvx sheetspec mcp
```

Generic configuration:

```json
{
  "mcpServers": {
    "sheetspec": {
      "command": "uvx",
      "args": ["sheetspec", "mcp"]
    }
  }
}
```

Tools:

- `inspect_workbook`
- `draft_workbook_spec`
- `validate_workbook`
- `compare_workbooks`
- `generate_validation_report`

Copy-paste configurations for Codex, Claude Code, Cursor, and OpenCode are available
in the [Agent integration guide](docs/agent-integrations.md).

The test suite launches a real STDIO subprocess, initializes an MCP client session,
lists all tools, and calls workbook inspection and validation end to end.

## Agent Skill

Install `skills/sheetspec/` in the agent's skill directory and use:

```text
inspect → draft/review → lock → create/edit → validate
→ repair ERROR → validate again → deliver
```

The skill prevents the agent from changing the contract merely to pass validation,
editing the workbook during validation, or claiming success while error-level issues
remain.

## Technical boundaries

- `.xlsx` workbooks are read-only; SheetSpec does not modify the source workbook.
- `openpyxl` does not recalculate arbitrary Excel formulas.
- Complex external formulas, VBA, Power Query, and pivot-table semantics are outside
  the v0.1 scope.
- `passed` means all declared checks passed, not that the entire business model is
  universally correct.
- Workbooks above 50 MB and rules covering more than 100,000 cells are rejected.
- Results expose at most 500 visible issues while preserving the total issue count.

## Roadmap

- `0.2`: optional LibreOffice recalculation, JUnit/SARIF output, and rule plugins;
- `0.3`: more templates, interactive MCP reports, and constrained repair helpers;
- long term: a standard quality gate for spreadsheet-producing agents.

## Open source

SheetSpec uses an original validation engine and depends on `openpyxl`, Pydantic,
PyYAML, Typer, Jinja2, and the MCP Python SDK. See
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)
- [Release process](docs/releasing.md)
- [Security policy](SECURITY.md)

```text
License: MIT
```
