CleanPrompt User Guide#

CleanPrompt is the local privacy boundary in scikitplot.cleanprompt. It replaces values that its active detectors identify with stable placeholders (or, when explicitly requested, selected surrogate values) before text leaves your process, then restores the original values after a reply comes back.

The base tier is implemented with the Python standard library. Optional tiers add named-entity detection, a local web interface, and the Fernet vault cipher. The base package can therefore be imported and used without loading those third-party packages.

Important

CleanPrompt protects values that it detects or that you explicitly tell it to hide. It is not a proof that arbitrary text contains no sensitive information. Run doctor to see which detection surfaces are active and inspect when you need to review what a particular input would expose. What it protects, and what it does not lists what is and is not covered.

Read the first two pages in order; after that, go to the page for the job in front of you.

getting-started

how

python

cli

entity

files

agents

web

security

troubleshooting

The executable gallery, Cleanprompt, follows the same path with code you can run: basics, the command line, the Python API, notebooks, then moderate and advanced topics, recipes, packs and formats, and agents.

See also

The whole idea in one picture#

original text
    |
    v
detect -> assign stable labels -> rewrite
    |                              |
    |                              +---- safe text ----> model / tool / agent
    |
    +---- handle / vault stays local
                                   |
                        model reply v
                              restore
                                   |
                                   v
                            local clear text

Two kinds of state come out of every redaction, and they go to different places. The redacted text is meant to cross the model boundary. The vault (inside a Handle in the high-level API) holds the removed values; it is the authority to restore them and must not be sent with the prompt. Treat a Handle or Vault like a secret.

Thirty seconds#

from scikitplot.cleanprompt import encode, decode

encoded = encode("Mail ada@example.com about the Acme renewal", hide=["Acme"])
encoded.text
# 'Mail [EMAIL-1] about the [CUSTOM-1] renewal'
decode("I will contact [EMAIL-1] about [CUSTOM-1].", encoded.handle)
# 'I will contact ada@example.com about Acme.'

From a terminal, the same pair needs no paths at all:

python -m scikitplot.cleanprompt encode "Mail ada@example.com about the renewal"
python -m scikitplot.cleanprompt decode "I will contact [EMAIL-1]."

Which surface should I use?#

Goal

Start with

One prompt/reply exchange in Python

encode and decode (The Python API)

A multi-turn conversation with stable labels

Session or session

Full control over policy and detectors

Redactor, RedactionPolicy, DetectorRegistry

Paste text into a chat by hand

cleanprompt encode and cleanprompt decode (The command line)

Preview what would be removed

cleanprompt inspect

Fail CI when findings are present

cleanprompt scan

Names, organisations and places

the entity engines (Names, organisations and places)

Files, records, folders, Office documents, or archives

FluentCleanPrompt / cleanprompt batch (Files, records, packs and plans)

Put a privacy gate in front of a model client

Guard (Models, tools and agents)

Guard an arbitrary command-line model

cleanprompt ask --via "COMMAND"

Give an MCP agent a local redaction boundary

cleanprompt mcp

Pin team configuration and detect definition drift

cleanprompt plan

A browser page, locally or in a container

cleanprompt flask / cleanprompt docker (The web page and containers)

Check installation and optional capabilities

capabilities / cleanprompt doctor