sheetsmith

# Sheetsmith

## Overview
Sheetsmith is a lightweight pandas wrapper that keeps the focus on working with CSV/Excel files: previewing, describing, filtering, transforming, and converting them in one place. The CLI lives at `skills/sheetsmith/scripts/sheetsmith.py`, and it automatically loads any CSV/TSV/Excel file, reports structural metadata, runs pandas expressions, and writes the results back safely.

## Quick start
1. Place the spreadsheet (CSV, TSV, or XLS/XLSX) inside the workspace or reference it via a full path.
2. Run `python3 skills/sheetsmith/scripts/sheetsmith.py <command> <path>` with the command described below.
3. When you modify data, either provide `--output new-file` to save a copy or pass `--inplace` to overwrite the source file.
4. Check `references/usage.md` for extra sample commands and tips.

## Commands
### summary
Prints row/column counts, dtype breakdowns, columns with missing data, and head/tail previews. Use `--rows` to control how many rows are shown after the summary and `--tail` to preview the tail instead of the head.

### describe
Runs `pandas.DataFrame.describe(include='all')` (customizable with `--include`) so you instantly see numeric statistics, cardinality, and frequency information. Supply `--percentiles` to add additional percentile lines.

### preview
Shows a quick tabulated peek at the first (`--rows`) or last (`--tail`) rows so you can sanity-check column order or formatting before taking actions.

### filter
Enter a pandas query string via `--query` (e.g., `state == 'CA' and population > 1e6`). The command can either print the filtered rows or, when you also pass `--output`, write the filtered table to a new CSV/TSV/XLSX file. Add `--sample` to inspect a random subset instead of the entire result.

### transform
Compose new columns, rename or drop existing ones, and immediately inspect the resulting table. Provide one or more `--expr` expressions such as `total = quantity * price`. Use `--rename old:new` and `--drop column...

# Sheetsmith

Sheetsmith is the pandas-based CSV/TSV/Excel assistant for OpenClaw. It gives you one CLI for:

- Inspecting spreadsheets (`summary`, `describe`, `preview`)
- Filtering or sampling rows via pandas queries (`filter`)
- Transforming columns with expressions, renames, drops, and safe writes (`transform`)
- Converting between CSV, TSV, and Excel formats (`convert`)

The script lives at `skills/sheetsmith/scripts/sheetsmith.py` and is the single source of truth for all operations, so you never have to re-write pandas boilerplate.

## Dependencies (already installed)

Sheetsmith relies on the Debian-packaged stack:

- `python3-pandas` (dataframes + Excel/CSV readers)
- `python3-openpyxl` + `python3-xlrd` (Excel file support)
- `python3-tabulate` (pretty Markdown previews)

Because these are installed system-wide, you can run the CLI without building a virtualenv.

## Usage

1. **Place the file** somewhere under the workspace (e.g., `workspace/inputs/my-data.xlsx`).
2. **Run a command:** `python3 skills/sheetsmith/scripts/sheetsmith.py <command> <path>` plus any flags listed below.
3. **Inspect the output** (Markdown tables are provided for previews) and, when you write data, use `--output new.xlsx` or `--inplace` to persist it.

### Common commands

| Command | Description | Example |
|---------|-------------|---------|
| `summary` | Print shape/dtypes, missing-value info, and a Markdown preview of the first/last rows | `... summary inputs/sales.csv --rows 5 --tail` |
| `describe` | Run `DataFrame.describe()` with optional `--include`/`--percentiles` | `... describe data.xlsx --include all --percentiles 10 90` |
| `preview` | Show only head/tail rows without any analysis | `... preview report.tsv --tail --rows 3` |
| `filter` | Apply a pandas query string and optionally sample/write results | `... filter data.csv --query "state == 'CA'" --output outputs/ca.csv` |
| `transform` | Add/rename/drop columns via pandas expressions, then preview or save | `... tran...