spreadsheet-kit

spreadsheet-kit is the shared engine crate behind the spreadsheet-kit tool interaction service for agent-based spreadsheet work.

It powers:

• the asp / agent-spreadsheet stateless CLI
• the spreadsheet-mcp stateful MCP server
• the in-repo spreadsheet-kit-wasm wrapper
• shared verification, diff, session, and mutation logic

If the root project is the product surface, this crate is the semantic core.

What this crate contains

Shared workbook engine

• workbook loading and repository abstractions
• sheet metrics and region detection
• table reads, range reads, paging, and analysis tools
• diff and recalc pipelines
• formula-aware write helpers
• style / layout / rules / structure mutation logic

Shared contracts

• request/response models used across CLI, MCP, and WASM-facing work
• diagnostic types and formula parse policy types
• diff result models
• verification and warning models
• session/runtime abstractions

CLI binaries

This crate also builds the stateless CLI binaries:

• asp
• agent-spreadsheet

Those binaries are feature-gated on recalc support.

What this crate is good for

Use spreadsheet-kit directly when you want:

• Rust-native access to the shared spreadsheet engine
• direct workbook/session manipulation without going through MCP transport
• common semantic behavior across your own higher-level adapters
• reuse of the same diff, verification, and mutation core used by the CLI/MCP surfaces

Use companion packages instead when you want:

• CLI ergonomics -> agent-spreadsheet / asp
• MCP transport -> spreadsheet-mcp
• JS integration -> spreadsheet-kit-sdk

Highlights

Read and inspect

• workbook metadata and sheet summaries
• region detection and structured table reads
• targeted cell inspection
• layout-aware range rendering
• named range discovery

Analyze

• value and formula search
• formula tracing and volatility scans
• sheet/table profiling
• structural reference impact preview

Mutate safely

• shorthand cell edit normalization
• transform/style/structure/layout/rules batch helpers
• formula-only replace flows
• named range define/update/delete
• recalc-aware write paths

Verify and review

• grouped diff summaries
• post-edit proof surfaces
• explicit warnings and diagnostics

Stateful workflows

• session abstractions for staged operations, apply, replay, and materialization

Example

[dependencies]
spreadsheet-kit = "0.10"

use spreadsheet_kit::write::normalize_shorthand_edit;

let edit = normalize_shorthand_edit("A1=42").unwrap();
assert_eq!(edit.address, "A1");
assert_eq!(edit.value, "42");
assert!(!edit.is_formula);

let formula = normalize_shorthand_edit("B2==SUM(A1:A2)").unwrap();
assert_eq!(formula.address, "B2");
assert_eq!(formula.value, "SUM(A1:A2)");
assert!(formula.is_formula);

Important types and capabilities

Examples of notable shared types/functions exposed by this crate include:

• CellEdit
• CoreWarning
• FormulaParsePolicy
• FormulaParseDiagnostics
• validate_formula()
• diff/result models
• session/runtime traits and helpers
• edit normalization and workbook apply helpers

The exact surface evolves with the shared engine, but the theme is constant: one semantic spreadsheet core, many agent-facing surfaces.

Feature flags

Default builds include Formualizer-backed recalc.

What this crate intentionally does not contain

This crate is not the MCP transport/server layer.

For that, see spreadsheet-mcp.

It is also not the npm distribution wrapper or JS SDK surface.

Related packages

More documentation

• Root README: https://github.com/PSU3D0/spreadsheet-mcp#readme
• Packaging/versioning: https://github.com/PSU3D0/spreadsheet-mcp/blob/main/docs/PACKAGING.md
• Heuristics: https://github.com/PSU3D0/spreadsheet-mcp/blob/main/docs/HEURISTICS.md
• Recalc architecture: https://github.com/PSU3D0/spreadsheet-mcp/blob/main/docs/RECALC.md

License

Apache-2.0 — see LICENSE.