sheetspec 0.1.2

Contract-based validation for spreadsheets created by AI agents.

SheetSpec

English | 简体中文

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:

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

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, no installation or repository clone is required:

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:

pip install sheetspec

To run the complete broken/fixed demo:

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:

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

Agent Gate

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

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

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:

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:

uvx sheetspec mcp

Generic configuration:

{
  "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.

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:

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.

• Contributing
• Changelog
• Release process
• Security policy

License: MIT