# DocumentHumanizer

Detects and removes AI writing indicators from documentation, making content sound more natural and human-written.

## Features

### 15 Detection Patterns

1. **Em-dashes**: Excessive use (>2 per paragraph)
2. **Corporate jargon**: leverage, robust, streamline, consolidation, strategic, ROI, optimal, synergy
3. **Passive voice**: "is built", "was created", "has been designed", "are used"
4. **Hedge phrases**: "appears to", "seems to", "might be", "could potentially"
5. **Buzzword clusters**: Multiple buzzwords in same sentence
6. **Transition phrases**: "Additionally", "Furthermore", "Moreover", "It's worth noting"
7. **Over-structuring**: Excessive bullets/lists (>5 consecutive)
8. **Redundancy**: Similar content in consecutive lines
9. **Success metrics**: ✅, "success metrics achieved", "100% complete"
10. **Stiff construction**: "This document outlines", "The system features"
11. **Acronyms without context**: AAC, ARIA, TTS without nearby definition
12. **Excessive dates**: Specific timestamps like "2025-11-21"
13. **Attribution**: "Made with Claude", "Generated by", "Claude assisted"
14. **Plural first person**: "we" → "I" (solo developer context)
15. **Formal metadata**: Excessive status fields, structured headers

## CLI Usage

### Scan for indicators
```bash
python /home/coolhand/shared/doc_humanizer.py scan file.md

# With custom threshold
python /home/coolhand/shared/doc_humanizer.py scan file.md --threshold 0.7
```

### Preview fixes (diff)
```bash
python /home/coolhand/shared/doc_humanizer.py diff file.md

# With custom confidence threshold
python /home/coolhand/shared/doc_humanizer.py diff file.md --confidence 0.8
```

### Apply fixes
```bash
# Dry run (preview only)
python /home/coolhand/shared/doc_humanizer.py fix file.md --dry-run

# Apply fixes
python /home/coolhand/shared/doc_humanizer.py fix file.md --confidence 0.85
```

### Batch processing
```bash
# Process multiple files
python /home/coolhand/shared/doc_humanizer.py batch file1.md file2.md file3.md

# Parallel processing
python /home/coolhand/shared/doc_humanizer.py batch *.md --parallel --max-workers 10
```

## Programmatic Usage

```python
from doc_humanizer import DocumentHumanizer, format_scan_results

# Create instance
humanizer = DocumentHumanizer()

# Scan a file
results = humanizer.scan_file('document.md')
print(format_scan_results(results))

# Apply transformations
with open('document.md', 'r') as f:
    original = f.read()

transformed = humanizer.apply_transforms(original, confidence_threshold=0.8)

# Generate diff
diff = humanizer.generate_diff(original, transformed)
print(diff)

# Batch process
file_list = ['doc1.md', 'doc2.md', 'doc3.md']
batch_results = humanizer.batch_process(file_list, parallel=True, max_workers=10)
```

## Transformation Rules

### Auto-fix (confidence >0.9)
- Remove attribution phrases (0.99)
- Remove success metrics ✅ (0.95)
- Replace em-dashes with colons (0.85-0.95)

### Suggest (0.7-0.9)
- Replace jargon with simpler alternatives (0.85)
- Convert "we" to "I" in solo context (0.85)
- Passive to active voice suggestions (0.75)
- Remove hedge phrases (0.80)

### Flag only (<0.7)
- Complex structural changes
- Ambiguous contexts

## Context Preservation

The module NEVER modifies:
- Code blocks (triple backticks)
- URLs
- Citations and references
- Technical specifications
- Files in clinical/ or specs/ directories

## Output

### Scan Results
```
🔍 Found 25 AI writing indicators:

JARGON (5 occurrences):
============================================================

Line 3 [████████] 85% confidence
  Text: This document outlines our robust approach...
  💡 Replace 'robust' with 'reliable'
```

### Confidence Levels
- `██████████` (1.0) = 100% confidence
- `█████████` (0.9) = 90% confidence
- `████████` (0.8) = 80% confidence
- `███████` (0.7) = 70% confidence

## Examples

### Before
```markdown
This document outlines our comprehensive approach to streamlining
the innovative ecosystem — leveraging robust solutions — designed
to optimize synergy.

Additionally, it's worth noting that we believe this represents
a paradigm shift. ✅ Success metrics achieved

Made with Claude AI assistance.
```

### After (--confidence 0.85)
```markdown
This document outlines my comprehensive approach to simplifying
the innovative ecosystem: leveraging reliable solutions: designed
to optimize collaboration.

It's worth noting that I believe this represents a paradigm shift.
Success metrics achieved
```

## Installation

No installation required - it's a standalone Python module.

Dependencies:
- Python 3.7+
- Standard library only (no external packages)

## Location

`/home/coolhand/shared/doc_humanizer.py`

## Author

Luke Steuber
