Metadata-Version: 2.4
Name: chatsee-redact
Version: 0.3.0
Summary: Fully-offline JSON/JSONL/CSV log redaction using ChatSee's redaction rules.
Maintainer: ChatSee
Maintainer-email: contact@chatsee.ai
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-python
Dynamic: summary

# chatsee-redact

Redact PII in your own **JSON / JSONL / CSV log files** locally — **fully offline.**

**Nothing ever leaves your machine, and the tool never contacts ChatSee (or any
network host) at runtime.** The redaction rules ship *inside* the package as a
frozen snapshot, the redaction engine is vendored, and there are **no runtime
dependencies** — not even the ChatSee SDK. Input is read from, and output written
to, local files only. No telemetry, no uploads, no network calls. Air-gap safe.

The masking engine is a byte-for-byte copy of the ChatSee pipeline's engine, so
the redaction you get here is identical to what the pipeline would apply.

## Install

```bash
pip install chatsee-redact
```

Zero dependencies. Works with no internet access after install (and the install
itself pulls nothing beyond the package).

## Usage

```bash
# Redact one file; writes ./redacted/app.json
chatsee-redact app.json --out ./redacted/

# Default output is alongside the input: app.redacted.json
chatsee-redact app.json

# Multiple files into one folder
chatsee-redact logs/*.jsonl --out ./redacted/
```

Input → output:

```
app.json          -->  ./redacted/app.json      (all string values masked)
```

## What gets redacted

By default **every string value** in the document is scanned and masked
(recursively, through nested objects and arrays). Non-string values
(numbers, booleans, null) are left untouched.

To restrict redaction to specific top-level keys (or CSV columns):

```bash
chatsee-redact app.json --fields user_message,bot_message,email
```

## Formats

| Input | Handling |
|-------|----------|
| `.json`            | Whole-document: JSON array, object, or scalar. |
| `.jsonl` / `.ndjson` | JSON Lines — streamed one record per line (safe for large logs). |
| `.csv`             | Per-row, streamed; header preserved. `--fields` selects columns. |
| other extension    | Treated as JSONL. Override with `--format`. |

Force a format with `--format {auto,json,jsonl,csv}`.

## Inspecting the rules (`dump-rules`)

Print the bundled classifier documents (the exact regexes that will run) so you
can audit them before trusting the tool — offline:

```bash
chatsee-redact dump-rules              # prints the bundled rules JSON to stdout
chatsee-redact dump-rules -o rules.json
```

## The rules

The classifier rules (credit card, Aadhaar, PAN, phone, email — with Luhn /
Verhoeff / phone validators) are **frozen into the package** as
`chatsee_redact/data/classifiers.json`. They update only when a new version of
this package is released — there is no runtime fetch.

To run with your own/alternate rule set (still fully offline), pass a local
classifiers JSON file:

```bash
chatsee-redact app.json --rules my_rules.json --out ./redacted/
chatsee-redact dump-rules --rules my_rules.json
```

*(Maintainers: refresh the bundled snapshot with `python tools/regenerate_rules.py
--env qa`, then bump the version and publish. `tools/` is the only code that ever
contacts ChatSee and is not shipped in the package.)*

## Options

| Flag | Default | Description |
|------|---------|-------------|
| `-o, --out DIR`   | alongside input | Output directory (created if missing). |
| `--out-file PATH` | —       | Explicit output path (single input only). |
| `--rules PATH`    | bundled | Use a local classifiers JSON instead of the bundled snapshot (offline). |
| `--fields A,B,C`  | all strings | Restrict redaction to these top-level keys / CSV columns. |
| `--format`        | `auto`  | `auto` \| `json` \| `jsonl` \| `csv`. |
| `--indent N`      | `2`     | JSON output indent (`-1` = compact). |
| `-q, --quiet`     | off     | Only log warnings/errors. |

## Behaviour

The original file is never modified and is never overwritten. If no rules can
be loaded (e.g. a corrupt `--rules` file), the tool **refuses to write** an
unredacted copy and exits non-zero, rather than silently passing data through.

## Exit codes

| Code | Meaning |
|------|---------|
| `0`  | Success. |
| `1`  | One or more files failed to redact (I/O or parse error). |
| `2`  | Bad invocation (missing input, refused source overwrite, `--out-file` with multiple inputs). |
| `3`  | No redaction rules available (bundled snapshot missing/corrupt, or empty `--rules`). |
