🔓 rehuman

Strip invisible AI watermarks from text through adversarial perturbation.

---

What is this?

AI text generators embed probabilistic watermarks—invisible statistical signatures baked into word choice, sentence rhythm, and transition patterns. When you run your own writing through an AI for polish, these watermarks tag your text as "synthetic." That's bullshit.

rehuman breaks those signatures. It perturbs text adversarially—restructuring syntax, swapping register, injecting human idiosyncrasies—while preserving meaning via Sentence-BERT semantic validation.

Raw AI-Polished Text  →  Parse → Detect → Perturb → Validate → Human-Grade Output
      AI-likelihood: 0.84                    AI-likelihood: 0.31

---

🚀 Quick Start

Setup

Linux / macOS:

git clone <repo>
cd rehuman
chmod +x scripts/setup_env.sh
./scripts/setup_env.sh
source venv/bin/activate

Windows:

git clone <repo>
cd rehuman
scripts\setup_env.bat
venv\Scripts\activate.bat

Manual (if scripts fail):

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
python -m spacy download en_core_web_md
python -m nltk.downloader punkt averaged_perceptron_tagger

Verify installation:

python -m unittest tests.test_engine

---

🎛️ CLI Usage

Basic

python -m cli.main input.txt -o output.txt

With Stats

python -m cli.main input.txt -o output.txt --stats

Output:

=== STATS ===
AI-likelihood (pre):  0.847
AI-likelihood (post): 0.312
Reduction:            0.535
Sentences processed:  12
Validation passed:    True

Aggression Levels

Low — Minimal changes, stays close to original:

python -m cli.main input.txt --aggression low

Medium — Balanced, default. Best for most use cases:

python -m cli.main input.txt --aggression medium --stats

High — Maximum disruption. More voice shift but stronger watermark breaking:

python -m cli.main input.txt --aggression high --diff

Reproducible Output

Same seed = same result:

python -m cli.main input.txt -s 42 -o clean.txt

JSON Report

python -m cli.main input.txt --json > report.json

Contains: original, perturbed, pre/post detection scores, validation results, seed.

Dry Run

Preview without writing:

python -m cli.main input.txt --dry-run --diff

Stdin Pipe

cat draft.txt | python -m cli.main --aggression high > clean.txt

---

🖥️ GUI Usage

python gui/app.py

1. Paste text into the left panel or click Open File
2. Select aggression level and threshold
3. Optionally set a seed for reproducibility
4. Click Process Text
5. View cleaned output in the right panel
6. Check stats bar for AI-likelihood reduction
7. Click Save Output to write to file

---

📊 Understanding Detection Scores

Metric	What it measures	AI typical	Human typical
Uniformity	Sentence length variance	High (0.8+)	Low (0.3-0.6)
Transition Pattern	Formal connector overuse	High (0.7+)	Low (0.1-0.3)
Vocabulary Richness (TTR)	Type-Token Ratio	Low (0.2-0.4)	High (0.5-0.8)
Hedge Density	Modal/qualifier frequency	High (0.5+)	Low (0.1-0.2)
Formality Index	Corporate buzzword density	High (0.6+)	Low (0.0-0.2)

Composite = weighted blend of all five. Target: < 0.35 for clean passage through detectors.

Score Breakdown

Uniformity Measures sentence length variance. AI tends to produce uniform-length sentences.

• High (0.8+) → Likely AI
• Low (0.3-0.6) → Likely human

Transition Pattern Counts formal connectors (furthermore, moreover, consequently...). AI overuses these.

• High (0.7+) → Likely AI
• Low (0.1-0.3) → Likely human

Vocabulary Richness (TTR) Type-Token Ratio. AI has lower lexical diversity.

• Low (0.2-0.4) → Likely AI
• High (0.5-0.8) → Likely human

Hedge Density Frequency of modal/qualifier words (may, might, potentially, arguably...).

• High (0.5+) → Likely AI
• Low (0.1-0.2) → Likely human

Formality Index Density of corporate buzzwords (leverage, utilize, robust, holistic...).

• High (0.6+) → Likely AI
• Low (0.0-0.2) → Likely human

---

🧪 Aggression Levels

Level	What it does	Use when...
low	Subtle synonym swaps, minimal restructuring	You need the text to stay very close to original
medium	Balanced disruption: syntax + lexicon + light idiosyncrasy	Default. Breaks Claude/ChatGPT signatures reliably
high	Heavy: fragments, comma splices, interjections, register mixing	Maximum watermark breaking; more voice shift

---

🎚️ Tuning

Semantic Threshold

Controls how strictly meaning is preserved. Default: 0.82.

Threshold	Behavior
0.90	Very conservative, minimal changes
0.82	Balanced (default)
0.70	Permissive, more aggressive perturbation
0.60	High risk of meaning drift

python -m cli.main input.txt -t 0.75 --stats

Custom Data

Add your own synonym mappings in data/synonyms.json:

{
  "your_word": ["human_alt_1", "human_alt_2", "human_alt_3"]
}

Add human tics in data/idiosyncrasies.json:

{
  "asides": ["(your aside here)"],
  "fragments": ["Your fragment."],
  "interjections": ["Your interjection, "]
}

---

🏗️ Architecture

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Input Text    │────▶│   Parser     │────▶│  Sentence List  │
└─────────────────┘     └──────────────┘     └─────────────────┘
                                                      │
                                                      ▼
┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Reconstruct   │◀────│  Validator   │◀────│  Perturbation   │
│   (paragraphs)  │     │  (BERT)      │     │    Engine       │
└─────────────────┘     └──────────────┘     └─────────────────┘
                                                      │
                                               ┌──────┴──────┐
                                               ▼             ▼
                                         ┌─────────┐   ┌──────────┐
                                         │Syntactic│   │ Lexical  │
                                         └─────────┘   └──────────┘
                                         ┌─────────┐   ┌──────────┐
                                         │Idiosync.│   │ Smoothing│
                                         └─────────┘   └──────────┘

Pipeline Stages

1. Parse (parser.py) — spaCy segments sentences, POS tags, dependency trees
2. Detect (detector.py) — Scores 5 statistical markers for AI-likelihood
3. Perturb (perturbation/) — Four disruption modules applied sequentially:
   • Syntactic — Clause reordering, fragmentation, inversion
   • Lexical — Synonym substitution with connotation awareness
   • Idiosyncrasy — Human tics: asides, fragments, comma splices
   • Smoothing — Cross-sentence n-gram disruption, transition breaking
4. Validate (validator.py) — Sentence-BERT cosine similarity gate (default ≥0.82)
5. Reconstruct — Paragraph structure preserved, output delivered

---

📁 Project Structure

rehuman/
├── src/
│   ├── engine.py              # Pipeline orchestrator
│   ├── parser.py              # spaCy text parsing
│   ├── detector.py            # AI pattern detection
│   ├── validator.py           # Semantic similarity (BERT)
│   └── perturbation/
│       ├── syntactic.py       # Sentence restructuring
│       ├── lexical.py         # Synonym substitution
│       ├── idiosyncrasy.py    # Human tics & fragments
│       └── smoothing.py       # N-gram & transition breaking
├── cli/
│   └── main.py                # Click CLI
├── gui/
│   └── app.py                 # tkinter GUI
├── data/
│   ├── synonyms.json          # Curated synonym map
│   ├── idiosyncrasies.json    # Human tics database
│   └── stopwords.txt          # Custom stopword list
├── tests/                     # pytest/unittest suite
├── docs/
│   ├── architecture.md        # Deep-dive architecture
│   └── usage.md               # Extended usage guide
├── scripts/
│   ├── setup_env.sh           # Linux/macOS setup
│   └── setup_env.bat          # Windows setup
├── requirements.txt
├── pyproject.toml
├── README.md
├── CONTRIBUTING.md
└── CHANGELOG.md

---

🧪 Testing

# Run all tests
python -m unittest discover tests/

# Run specific module
python -m unittest tests.test_engine
python -m unittest tests.test_perturbation

---

🛠️ Extending

Add Custom Synonyms

Edit data/synonyms.json:

{
  "your_buzzword": ["human_alt_1", "human_alt_2", "human_alt_3"]
}

Add Custom Idiosyncrasies

Edit data/idiosyncrasies.json:

{
  "asides": ["(your aside here)"],
  "fragments": ["Your fragment."],
  "interjections": ["Your interjection, "]
}

Tune Detection Weights

Edit src/detector.py — the analyze() method contains the composite weighting:

composite = (
    scores["uniformity"] * 0.25 +
    scores["transition_pattern"] * 0.20 +
    (1.0 - scores["vocabulary_richness"]) * 0.20 +
    scores["hedge_density"] * 0.15 +
    scores["formality_index"] * 0.20
)

---

🐛 Troubleshooting

Error	Fix
No module named 'spacy'	pip install -r requirements.txt
Can't find model 'en_core_web_md'	python -m spacy download en_core_web_md
sentence-transformers not installed	pip install sentence-transformers
Output looks too different	Increase threshold: -t 0.90 or decrease aggression: -a low
Watermark still detected	Increase aggression: -a high or decrease threshold: -t 0.70. Run twice with different seeds.
GUI won't launch	Ensure customtkinter is installed: pip install customtkinter
Tests fail on first run	Ensure spaCy model is downloaded: python -m spacy download en_core_web_md

---

🤝 Contributing

See CONTRIBUTING.md for guidelines on adding perturbation strategies, detection metrics, and code style.

---

📜 Changelog

See CHANGELOG.md for version history.

---

License

MIT — do what you want. Build on it. Break things with it. Just don't be boring.

---

Built with cold coffee and zero patience for invisible control. ☕