🚀 New: the Lynote Humanizer API is live. Need humanization inside your own app, workflow, or SaaS? Call Lynote's production humanizer with one REST request — no pipeline to host. Get an API key → lynote.ai/ai-humanizer-api

---

Most humanizers are a black box with marketing claims attached. This one is open source, so you can read what it actually does.

The current method is a structure-first data pipeline that trains the model to rewrite structure, not just launder surface style — the full implementation is in training-data-pipeline/. The original translation-chain approach is kept below as a runnable reference.

How it works

The current method is a structure-first data pipeline that builds the SFT + preference (KTO) training data for our own AI→human rewrite model — it teaches the model to rewrite structure, not just launder surface style. Full implementation, policies, tests, and 50 demo records per stage live 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 KTO (preference) pass teaches it to prefer genuine structural rewrites over surface edits.
• Structure-first negatives. Undesirable responses are selected for under-editing, structural damage, semantic drift, over-rewriting, repetition, and refusal — an exact 60% under-edit / 20% source-copy / 20% severe-failure mix.
• Controlled prompt diversity. A pool of equivalent instruction wordings is sampled with a fixed seed, so the model generalizes across phrasings, not one command style.
• Deterministic & auditable. SHA-256 identity per pair, seeded splits, versioned YAML policies, two-layer validation, and a human review gate. No weights, endpoints, or performance claims are shipped.

Full method: DATA_CONSTRUCTION.md · ARCHITECTURE.md · PROMPTS.md

---

Legacy reference: v1.x translation chain

The translation chain below is our earlier open exploration. It still runs and is kept as a readable reference — the current method is the structure-first pipeline above.

Step-by-Step Pipeline

Why This Chain Works

1. Steps 1–2 (LLM Rewrite): Configurable LLM provider (DeepSeek default, OpenRouter optional) at temperature 1.3 rewrites while translating, breaking AI statistical fingerprints with creative variation. Step 2 carries Step 1 as conversation history for coherent humanization.
2. Steps 3–4 (Multi-Engine Translation): Two different NMT engines (Google → Niutrans) introduce compounding structural changes. No single-engine fingerprint survives.
3. Distant Languages: Chinese → Japanese → Finnish maximizes linguistic distance at each hop, ensuring thorough restructuring before reconstruction to 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 API key
python -m src.standard.pipeline --input draft.txt

Tiers

Note on intended use. 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.

Important: Detector scores are probabilistic. This project does not guarantee that rewritten text will be classified as human, and it should not be used to misrepresent authorship or evade institutional policies.

Where this repo fits. The pipeline here is our team's open exploration from early 2026 — the most effective approach we'd found at the time, released so anyone can read it, run it, and build on it. We've since moved well beyond it: Lynote.ai now runs proprietary detect + humanize models we trained ourselves, using a structure-first SFT + KTO data pipeline (the method in training-data-pipeline/) on curated, high-quality datasets.

Against this repo's open-source chain, Lynote.ai's current humanizer raises the detector-bypass rate by ~30% and rates ~50% higher on output quality — both are relative gains over this chain. The detection side draws on the latest research into what actually separates human from AI writing — not surface style, but discourse-level narrative structure (e.g. the StoryScope study, UMD & Google DeepMind, COLM 2026). Style-only rewriting no longer tells the whole story — which is exactly why this open chain has a ceiling.

This repo stays a faithful, runnable reference. For the current best results, try Lynote.ai.

---

Lynote.ai — Beyond Standard

The Standard pipeline above is one of three tiers available. Each has different trade-offs:

Lynote.ai combines all three tiers and automatically selects the optimal approach for each text passage:

• Intelligent Tier Selection — Analyzes text and picks Standard, Advanced, or Focus per-passage
• Adaptive Combination — Can mix tiers within a single document
• 80+ Languages — English, Chinese, Japanese, Korean, Spanish, French, German, and more
• Paste & Go — No setup, no API keys, no configuration

Lynote Humanizer API — for developers

Running this repo's pipeline means juggling LLM keys, translation engines, and your own infrastructure. If you just want humanization inside your product, the Lynote Humanizer API gives you the same engine that powers Lynote.ai through a single endpoint:

• One synchronous REST call — send text, get the rewrite back as JSON. No polling, job queues, or webhooks.
• Per-request controls — 10+ Purpose options, Readability level, and Detection Bypass settings.
• Formatting preserved — Markdown and line breaks carry through to the output.
• 80+ languages — strongest in English, Chinese, Spanish, Portuguese, and French.
• Simple billing — 1 credit per input word (Chinese is counted per character: 1 character = 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

---

Ways to run it

Python

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
# Fill in your API keys in config.toml (see examples below)
python -m src.standard.pipeline --input "Your AI-generated text here"

DeepSeek (default):

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

[llm]
provider = "deepseek"

OpenRouter:

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

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

Atlas Cloud:

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

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

OrcaRouter:

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

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

Override the API endpoint with base_url in [llm], or via LLM_BASE_URL / LLM_API_KEY environment variables. Full reference: docs/configuration.md.

n8n Workflow

1. Import n8n/humanize_standard.json into your n8n instance
2. Configure the LLM API key and URL in the HTTP Request nodes (defaults to DeepSeek; point at OpenRouter's https://openrouter.ai/api/v1/chat/completions to use OpenRouter)
3. Run — input text goes in, humanized text comes out

---

Showcase — 5 Real Examples with Step-by-Step Outputs

Results below are from the legacy v1.x translation-chain scheme, not the current structure-first pipeline.

We ran the pipeline end-to-end on 5 real input texts and saved every intermediate step. On these samples, all five final outputs were classified as human by the detector we tested. These are illustrative traces from the open chain, not a guarantee — detection is probabilistic and varies by detector and version (see the note at the top of this README).

Each example shows: original input → Step 1 (中文改写) → Step 2 (日语改写) → Step 3 (一轮翻译) → Step 4 (二轮翻译, final). See examples/showcase/ for full traces.

---

Quality Metrics

Tested on 50 text pairs with expert evaluation:

• Key Information Retention: 100% (50/50 pairs)
• All texts preserved original key information without distortion

These scores evaluate the legacy v1.x translation-chain output only — a static measure of the old scheme, not the current structure-first method or the Lynote.ai figures referenced at the top.

---

Comparison with Other Tiers

---

Documentation

• Standard Pipeline Technical Details — v1.5 production pipeline
• 4 Methodologies Reference — v1.0 underlying methods
• Research Notes — why style-only humanization has a ceiling (StoryScope, COLM 2026)
• Training-Data Pipeline — the current structure-first SFT + KTO data method
• Configuration Guide
• n8n Workflow Guide
• Lynote.ai vs Open Source Comparison
• FAQ

Repo Structure

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

src/                         # legacy v1.x translation-chain reference (runnable)
├── standard/                # Standard Pipeline (4-step chain, CLI entry)
│   ├── pipeline.py          # 4-step chain, CLI entry
│   ├── llm_client.py        # OpenAI-compatible client (DeepSeek / OpenRouter)
│   ├── llm_rewriter.py      # LLM humanization rewrite
│   └── translators.py       # Google + Niutrans engines
│
└── methodologies/           # v1.0 four-methodology reference implementations
    ├── humanizer.py         # v1.0 dispatcher + FastAPI app
    ├── translation_chain.py # Method 1
    ├── llm_rewriter.py      # Method 2
    ├── detection_pipeline.py# Method 3
    ├── mixed_engine.py      # Method 4
    ├── postprocess.py
    ├── detectors/           # Method 3 detectors
    └── utils/

examples/
├── example_usage.py         # ★ v1.5.1 minimal entry
├── showcase/                # ★ 5 real samples with intermediate-step outputs
└── legacy/                  # v1.0 examples + 4-method comparison outputs

---

Limitations

Round-trip translation costs precision. Technical terminology and citations can drift, and the deeper tiers trade more of your original voice for more restructuring. If you're working with anything where exact wording matters, read the output carefully rather than trusting the pipeline.

No rewriting method makes text reliably undetectable. Detectors update faster than pipelines do, and results vary by input length, subject matter, and which detector you're facing. Treat the showcase/ results as a snapshot, not a guarantee.

Related

• Lynote AI Detector — sentence-level scoring, free
• Lynote AI Humanizer — hosted version of this pipeline
• Lynote Humanizer API — the hosted humanizer as a REST API for your own products
• Hugging Face Space — try it without installing anything

License

MIT License. See LICENSE for details.

---

Support & Contact

⭐ Star this repository if this all-in-one text humanization toolkit helps you.

🌐 Visit official website lynote.ai to unlock full premium features.

🔌 Need an API? Visit lynote.ai/ai-humanizer-api to get your Humanizer API key.

💬 Have questions, feature requests or usage troubles? Feel free to start a discussion in Discussions.