scrub.bot

ScrubBot is deterministic data cleaning for records, free text and files: spreadsheets and JSON, pasted text, PDFs and Office documents, images and audio. Its rule-based handlers trim and fix casing, standardize dates and phone numbers, repair broken encoding, strip HTML, mask PII, validate emails and remove duplicates, so the same input always gives the same output. It never invents a value; anything it can't fix with certainty is flagged with a reason. Every run returns the cleaned data, a log of every change, and a list of what it couldn't resolve. Use it in the browser, from the command line, over an API, or from AI agents through MCP; scrub serve runs the whole engine on your machine. Model-based handlers (OCR, transcription, classification) are an opt-in extra and are labeled as such.

The package contains the scrub command and the engine behind it. scrub serve starts the engine with SQLite and no other services, so nothing leaves your computer. The same CLI can also point at a hosted or self-hosted ScrubBot API. AI model handlers are an optional extra: pip install "scrub.bot[ai]".

Install

pip install scrub.bot

Requires Python 3.12 or newer. If pip reports "No matching distribution found" (older Python, such as the 3.9 that ships with macOS) or "externally-managed-environment" (Homebrew or system Python), install it as an isolated tool instead:

uv tool install scrub.bot      # or: pipx install scrub.bot

Installs two commands that are the same program: scrub (short, for daily use) and scrubbot (explicit, for docs and scripts).

Start the engine

scrub serve                      # local API on http://127.0.0.1:8000, prints a key

In another terminal:

export SCRUBBOT_API_URL=http://127.0.0.1:8000
scrub api doctor                 # check key, endpoint, and version
curl -sO https://www.scrub.bot/demo/contacts.csv
scrub clean/text/whitespace contacts.csv -o contacts.clean.csv

The CLI provisions its own key against a local server. To use a hosted or self-hosted ScrubBot API instead, set SCRUBBOT_API_URL and SCRUBBOT_API_KEY. Hosted accounts are not open yet.

Run a handler

scrub handlers pii                              # search the catalog
scrub handlers clean/pii                        # show one handler and its config
scrub clean/pii customers.csv --config strategy=mask
scrub clean/text/whitespace notes.csv
scrub runs                                      # recent run history

scrub clean/pii file.csv is shorthand for scrub run clean/pii file.csv. Input can be CSV, JSON, or inline text. Output goes to stdout or --output.

Run a pipeline

prep.yaml:

name: customer_prep
handlers:
  - handler: clean/text/whitespace
    config: {}
  - handler: clean/pii
    config: {strategy: mask}
  - handler: validate/format/email
    config: {}

scrub pipeline prep.yaml customers.csv

Python

import scrubbot

c = scrubbot.Client(api_key="sk_...", base_url="https://api.scrub.bot")

result = c.run_handler("clean/pii", data=[{"email": "a@b.com"}], config={"strategy": "mask"})
print(result["records"], result["changes"])

for event in c.stream_pipeline(
    record_chunks=[[{"text": "  hi  "}]],
    handlers=[{"handler": "clean/text/whitespace", "config": {}}],
):
    print(event)

Errors raise scrubbot.ApiError (HTTP status and payload) or scrubbot.ApiConnectionError (unreachable or timed out). The package also ships the generated, fully typed client classes (scrubbot.HandlersApi, scrubbot.PipelineApi, scrubbot.JobsApi, and so on) for callers who want a model per endpoint.

Environment variables

Self-hosting and license

The server is in the same repository and runs with Docker Compose. It is source-available under the Business Source License 1.1 and converts to Apache 2.0 on 2030-01-01. Internal use is permitted; offering it as a hosted service to third parties needs a commercial license. This client package follows the same license.

Docs: https://www.scrub.bot/docs. Bugs and feature requests: https://github.com/scrubbot/scrub.bot/issues.