Text Humanizer

A fully local AI text humanizer that converts AI-generated text into human-sounding writing. Supports English and Turkish. Works offline using Ollama for LLM inference; all rule-based modes require no network connection.

• Rule-based pipeline (Levels 1-2): fast, deterministic, no GPU required
• LLM pipeline (Levels 3-4): uses a local Ollama model for deeper rewriting
• Language support: English and Turkish (including Turkish formal suffix reduction and vowel harmony)
• Benchmark metrics: burstiness, lexical diversity, entropy, AI phrase density, readability grade, passive voice density, formal marker density, humanness score
• Streamlit GUI and Typer CLI
• File input: plain text (.txt), Word (.docx), PDF (.pdf)

Main interface — sidebar settings, original text input, humanized output, and benchmark score summary:

Benchmark panel — detailed metrics table (before/after/delta/target) and radar chart:

Sentence analysis — top AI-scored sentences with alternative suggestions:

• Python 3.10 or higher
• Ollama installed and running (required for Levels 3-4 only)
• Windows, macOS, or Linux

git clone https://github.com/Yukseltt/text-humanizer.git
cd text-humanizer

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

macOS / Linux:

python -m venv venv
source venv/bin/activate

pip install -r requirements.txt

python -c "import nltk; nltk.download('punkt_tab')"

Copy the example file and edit it:

cp .env.example .env

Edit .env:

OLLAMA_HOST=http://localhost:11434
HUMANIZER_MODEL=llama3.2:3b
CHUNK_SIZE=600

Model options by VRAM:

• llama3.2:3b — 2 GB, works on 4-6 GB VRAM (default)
• llama3.1:8b — 4.7 GB, works on 8 GB+ VRAM (better quality)
• mistral:7b — 4.1 GB, alternative for 8 GB+ VRAM

ollama pull llama3.2:3b

Two batch files are provided for one-click startup on Windows.

Step 1 — Start the Ollama server (required for Levels 3-4):

Double-click start_ollama.bat (or run the PowerShell script directly):

start_ollama.bat

What it does:

• Checks that Ollama is installed (%LOCALAPPDATA%\Programs\Ollama\ollama.exe)
• Detects whether port 11434 is already in use and offers to kill the existing process
• Starts ollama serve and keeps the window open
• Shuts down Ollama cleanly when the window is closed

Keep this window open while using the GUI.

Step 2 — Launch the GUI:

Double-click run_gui.bat (or the PowerShell equivalent):

run_gui.bat

What it does:

• Activates the venv environment
• Runs streamlit run app.py
• Prints the local URL in the terminal

The GUI opens at http://localhost:8501.

PowerShell equivalents:

PowerShell -ExecutionPolicy Bypass -File start_ollama.ps1
PowerShell -ExecutionPolicy Bypass -File run_gui.ps1

Manual start (any OS):

ollama serve          # terminal 1 — keep open
streamlit run app.py  # terminal 2

Humanize text directly:

python -m src.cli "Furthermore, it is important to note that this is comprehensive."

Humanize from file:

python -m src.cli --input input.txt --output result.txt

Rules only (no Ollama required):

python -m src.cli --no-ollama --input input.txt

With benchmark report:

python -m src.cli --benchmark --input input.txt

Standalone benchmark between two files:

python -m src.cli benchmark input.txt --humanized result.txt

pytest tests/ -v

All 118 tests should pass in under 5 seconds.

text-humanizer/
├── app.py                      # Streamlit GUI
├── config.py                   # Pydantic settings (reads .env)
├── requirements.txt
├── .env.example
├── start_ollama.bat            # Windows: start Ollama server (double-click)
├── start_ollama.ps1            # PowerShell: start Ollama server
├── run_gui.bat                 # Windows: launch Streamlit GUI (double-click)
├── run_gui.ps1                 # PowerShell: launch Streamlit GUI
│
├── src/
│   ├── cli.py                  # Typer CLI entry point
│   ├── humanizer/
│   │   ├── core.py             # Main humanization pipeline
│   │   ├── techniques.py       # Rule-based transforms
│   │   ├── preprocessor.py     # Text splitting, normalization, header detection
│   │   ├── analyzer.py         # Sentence AI scoring, entropy, references
│   │   ├── prompt.py           # Ollama prompt templates
│   │   └── file_handler.py     # .txt / .docx / .pdf reading
│   └── benchmark/
│       ├── metrics.py          # All metric calculations
│       ├── runner.py           # BenchmarkResult class
│       └── report.py          # Rich terminal report
│
├── data/
│   └── collocations.json       # EN and TR collocation replacement table
│
└── tests/
    ├── conftest.py
    ├── test_metrics.py
    ├── test_techniques.py
    ├── test_analyzer.py
    ├── test_preprocessor.py
    └── test_benchmark_runner.py

Levels 1-2 are offline and deterministic. Levels 3-4 require Ollama.

All settings are read from .env via config.py.

Ollama connection error: Start Ollama first with start_ollama.bat (Windows) or ollama serve (terminal), then launch the GUI. Check that OLLAMA_HOST in .env matches (http://localhost:11434).

Model not found: Run ollama pull <model-name> before using Level 3-4.

NLTK punkt not found: Run python -c "import nltk; nltk.download('punkt_tab')".

Streamlit port conflict: Run streamlit run app.py --server.port 8502.