✨ Before → After

_{Excerpt from Example 01 — the full trace shows every intermediate step (Chinese → Japanese → Finnish → English).}

🚀 Quick start

git clone https://github.com/lynote-ai/humanize-text.git
cd humanize-text
pip install -r requirements.txt
cp config/config.example.toml config/config.toml   # add your LLM + Niutrans keys

python -m src.standard.pipeline --input "Your AI-generated text here"

--input takes either a text string or a path to a .txt file. Add --verbose to watch each step, or --json to get the full step-by-step trace as JSON.

Don't want to set up keys? Try the hosted version at lynote.ai — paste and go.

Why this project

• Open, not a black box. Most humanizers hide what they do behind marketing claims. Here every step is readable code, and every run can be traced.
• Runs end-to-end with your own keys. DeepSeek (default), OpenRouter, Atlas Cloud, OrcaRouter, LiteLLM, or any OpenAI-compatible endpoint.
• Three ways to run it. Python CLI, a no-code n8n workflow, or Docker.
• Research included. We also open-source the structure-first data pipeline we use to train our own rewrite model.

How it works

The open pipeline combines two LLM rewrites with two machine-translation hops across distant languages and different engines:

Why this chain works

1. Steps 1–2 (LLM rewrite): A high-temperature rewrite while translating breaks the statistical patterns typical of AI text. Step 2 carries Step 1 as conversation history to keep the text coherent.
2. Steps 3–4 (multi-engine translation): Two different translation engines introduce compounding structural changes, so no single engine's fingerprint survives.
3. Distant languages: Chinese → Japanese → Finnish maximizes linguistic distance at each hop before reconstructing English.

Tiers

Technical details: docs/pipeline.md · docs/techniques.md

Ways to run it

[api_keys]
deepseek_api_key = "sk-..."
niutrans_api_key = "your-key"

[llm]
provider = "deepseek"

[api_keys]
openrouter_api_key = "sk-or-..."
niutrans_api_key = "your-key"

[llm]
provider = "openrouter"
model = "deepseek/deepseek-chat"   # any OpenRouter model slug

[api_keys]
atlascloud_api_key = "ak-..."
niutrans_api_key = "your-key"

[llm]
provider = "atlascloud"
model = "qwen/qwen3.5-flash"

[api_keys]
orcarouter_api_key = "sk-orca-..."
niutrans_api_key = "your-key"

[llm]
provider = "orcarouter"
model = "deepseek/deepseek-chat"   # any OrcaRouter model slug

📊 Showcase — 5 real examples

We ran the open pipeline end-to-end on 5 real texts and saved every intermediate step.

Each example shows: original input → Step 1 → Step 2 → Step 3 → Step 4 (final). These are illustrative snapshots from one detector at one point in time, not a guarantee — see Responsible use & limitations.

Quality metrics

Expert evaluation on 50 text pairs:

Key information retention: 100% (50/50 pairs).

🔬 How we train our own model (research)

Style-only rewriting has a ceiling: recent research shows that what separates human from AI writing is largely discourse-level structure, not surface style (see our research notes on the StoryScope study, COLM 2026).

So for our own rewrite model we built a structure-first data pipeline, and we open-source it in training-data-pipeline/:

flowchart LR
    sources["Public crawl + private pairs"] --> gates["Quality + structure gates"]
    gates --> split["Deterministic stratified split"]
    split --> sft["SFT training pool"]
    sft --> reserve["Reserve a disjoint KTO pool"]
    reserve --> gen["6 candidate chains · temps 0.3-1.0"]
    gen --> select["Negative selection + structure-first 60/20/20 mix"]
    select --> review["Human review gate"] --> kto["Balanced KTO train / validation"]

• SFT → KTO. A supervised pass learns the rewrite task; a preference (KTO) pass teaches the model to prefer genuine structural rewrites over surface edits.
• Structure-first negatives. Rejected outputs are selected for under-editing, structural damage, semantic drift, over-rewriting, repetition, and refusal, in a fixed 60% / 20% / 20% mix.
• Deterministic & auditable. SHA-256 identity per pair, seeded splits, versioned YAML policies, two-layer validation, and a human review gate.
• What's included: code, policies, tests, and 50 demo records per stage. Model weights and full datasets are not included.

Docs: DATA_CONSTRUCTION.md · ARCHITECTURE.md · PROMPTS.md

Hosted version: Lynote.ai & API

If you'd rather not manage keys and infrastructure, Lynote.ai runs our own model trained with the structure-first method above, and automatically picks the right approach for each passage.

For developers — the Lynote Humanizer API: one synchronous REST call, Markdown and line breaks preserved, per-request Purpose and Readability controls, 80+ languages. Billing: 1 credit per input word (Chinese counts 1 character as 1 word); output is free.

curl https://api.lynote.ai/v1/humanize \
  -H "Authorization: Bearer $LYNOTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your AI-generated draft here", "readability": "University", "purpose": "Academic"}'

Plans, rate limits, and full docs: lynote.ai/ai-humanizer-api

Responsible use & limitations

This toolkit is for improving the readability and natural cadence of AI-assisted drafts. If you are writing in an academic setting, follow your institution's policies on AI use and disclosure. Please don't use it to misrepresent authorship.

• Detection is probabilistic. No rewriting method makes text reliably undetectable. Detectors update faster than pipelines do, and results vary by input length, subject matter, and detector. This project guarantees no particular classification.
• Translation costs precision. Technical terms and citations can drift, and deeper tiers trade more of your original voice for more restructuring. Where exact wording matters, review the output carefully.

See also SECURITY.md.

Documentation

• Installation · Configuration · n8n guide · API reference
• Pipeline technical details · 4 methodologies reference
• Research notes · Training-data pipeline
• Open source vs Lynote.ai · FAQ

src/                         # the open humanizer pipeline (runnable)
├── standard/                # Standard pipeline — 4-step chain, CLI entry
│   ├── pipeline.py
│   ├── llm_client.py        # OpenAI-compatible client
│   ├── llm_rewriter.py
│   └── translators.py       # Google + Niutrans engines
└── methodologies/           # four methodology reference implementations + FastAPI app

training-data-pipeline/      # structure-first SFT + KTO data pipeline (research)
├── code/                    # ordered stages a–f, harness, tests
├── configs/  data/demos/    # versioned policies + 50 demo records per stage
└── docs/                    # ARCHITECTURE, DATA_CONSTRUCTION, PROMPTS

examples/
├── example_usage.py         # minimal entry
├── showcase/                # 5 real samples with every intermediate step
└── legacy/                  # earlier examples + method comparison outputs

n8n/                         # no-code workflow
docker/                      # Dockerfile for the REST endpoint

Related projects

• AI Text Detector — our open-source detector · try it on Hugging Face
• Lynote AI Detector — sentence-level scoring, free

Contributing

Issues and PRs are welcome — new LLM providers, translation engines, language pairs, and evaluation scripts are especially useful. See CONTRIBUTING.md, or start a thread in Discussions.

License

MIT — see LICENSE.