humanizar-es · Local AI text humanizer for Spanish and English

English · Español

humanizar-es takes a text written with ChatGPT, Claude, Gemini or DeepSeek and gives
it back saying the same thing, in prose that the three detectors we measured read as
human: 0% in Grammarly, 0% in ZeroGPT and 0% AI / 98% human in GPTZero, on the same
1,990-word essay that started at 45%. It runs on your own computer with an open model: no
API, no keys, no per-word fees, and your text never leaves your machine. Use it by hand or
as a skill for your coding agent (Claude Code, Codex, OpenCode, Antigravity).

It is not a synonym spinner, a "rewrite it in a human tone" prompt, or a typo generator.
It is a four-stage pipeline, and every stage exists because a controlled experiment showed
what a detector actually measures: one variable at a time, the same text in every
condition, and a human-written control and the AI original in every session.

Results

October 2026. The first essay keeps 24 of 24 key names, terms and figures, and its two
quotations of Aristotle word for word. Grammarly reads ~1,400 words, so it was measured in
halves. The Dragon Ball essay ran on an earlier version of the pipeline.

The method

 original ─► 1. rewrite ──► 2. fidelity ──► 3. rhythm ──► 4. selection ──► final
             base model     concepts,       blocks of      candidates,
             without chat   quotes, copy,   uneven         measured in the
             training       ≤3-word fixes   length         whole document

What the detectors measure

Three detectors, three different signals. The pipeline exists because each one was
taken apart with experiments:

1. Remove the chat-training fingerprint

Xu et al. (2026), Base Models Look Human To AI Detectors,
showed that text from a base model scores 97–99% human on GPTZero and Pangram, and the
same model after chat training 17–30%. Our tests agree: every rewrite we tried with a chat
model stayed between 64% and 100% in Grammarly. rewrite.py paraphrases with
Qwen3-4B-Base plus the paper's HIP adapter, through llama.cpp, on your CPU.

2. Keep it faithful, without putting the fingerprint back

Each paragraph gets one pass, and a try is rejected and retried when it:

• loses a concept you listed (names, terms, figures, key negations);
• changes a quotation of the original or adds a reference the original never had
  (on a test essay the model wrote «(De Anima, libro i, cap. vi)», which does not exist);
• copies the original: more than 60% of its words in runs of 8+ identical words;
• eats Spanish accents («comunio'n», «oraci n», «composicin», «Espiritu»);
• switches language mid-sentence («VER significa listening and understanding…»);
• drops the negations an idea rests on («el criterio no sería solo la asistencia» →
  «el criterio sería el de la asistencia»);
• invents a quotation or repeats a sentence it made up;
• comes out truncated or runs away.

check.py then compares concepts and negations, and a person fixes one to three words
at most. Anything bigger is regenerated by the model (--only), never written by hand and
never pasted back from the original: hand fixes of four or more words kept half an essay
at 3% in Grammarly; regenerating those paragraphs brought it to 0%.

3. Rebuild the rhythm

People write in bursts, some sentences long, some short. join.py --pauses 2 leaves two or
three periods per paragraph, in blocks of uneven length of at least two sentences,
cutting first where a sentence already opens with a discourse marker («Sin embargo»,
"For example", «Segundo»). Inside a block it links with "and" or ";". No content word is
touched.

4. Select by measurement

The base model is a sampler: the same paragraph comes out differently every time, and a
detector can score two samples 0% and 100%. So the paragraphs a detector still flags are
regenerated several times (--candidates), each candidate is joined and measured inside
the whole document (context changes the score), and the one that passes is adopted
(--take). All candidates come from the same base model, so selection adds no chat
fingerprint. Two findings made this work:

• The opening words matter. To keep writing in Spanish, the model starts each paragraph
  with the original's first two words. When those are a stock opening («Uno de los
  problemas más importantes…», «Aristóteles distingue…»), the model rebuilds the stock
  sentence and ZeroGPT flags it. Starting with other words (--lead "Desde la") fixed it:
  22 candidates of one paragraph with the original opening scored 100%; with another
  opening, 0%.
• Every edit is measured again. ZeroGPT is deterministic but brittle: a one-word fix
  took a paragraph from 0% to 62%.

The experiments behind each stage

Same essay, one change at a time.

The tension is real: Grammarly wants long sentences, ZeroGPT punishes a long sentence that
contains one textbook clause. Rhythm alone cannot satisfy both; rhythm plus selection does.
Every measurement: references/evidence.md.

How we measure

• Two controls in every session: a human text must come out human, and the AI original
  must come out as AI. A detector that fails either one does not count: QuillBot scored
  the AI original 100% human, and GPTZero, after many scans from one browser, scored a
  1914 text 100% AI.
• The reference is re-measured in the same session, never compared with a number from
  hours before.
• The final format is the one measured: with headings and bibliography, ZeroGPT can
  give a different score than for the bare text.

Install

With your agent (easiest)

git clone https://github.com/ervin-mo/humanizar-es.git
cd humanizar-es
python3 install.py          # on Windows: python install.py

Open a new session and ask: "humanize this text" (or «humaniza este texto»). The skill
walks the agent through every stage: install what's missing (it asks before downloading the
model), list with you what must not be lost, rewrite, show you every change, rebuild the
rhythm, and select candidates for whatever your detector still flags.

The model (once, ~4.6 GB)

You need Python 3.9+ (no extra packages) and llama.cpp:

The installer checks every file against its sha256 and resumes if the download is cut.
It runs on CPU: 8 GB of free RAM is enough, no GPU. On an M4 Mac it takes about 30–60
seconds per paragraph; on a few-years-old PC, 1 to 3 minutes.

Use it by hand

On Windows, type python where it says python3.

1. List what must not be lost in concepts.txt: full proper names, figures, terms.
One per line, variants with |, * for prefixes.

Aristotle
act and potency | act and potentiality
self-regulat*

2. Rewrite with the base model:

python3 scripts/rewrite.py my-text.txt -o rewritten.txt --concepts concepts.txt

3. Check, and fix one to three words at most. For anything bigger, regenerate that
paragraph:

python3 scripts/check.py my-text.txt rewritten.txt --concepts concepts.txt
python3 scripts/rewrite.py my-text.txt -o rewritten.txt --concepts concepts.txt --only 6,11

Don't ask ChatGPT to fix it: it puts back the fingerprint the base model removed.

4. Rebuild the rhythm (the language is detected automatically):

python3 scripts/join.py rewritten.txt -o final.txt --concepts concepts.txt --pauses 2

5. Measure the final text in your detector, in the format you will hand in, with a
human text as control (references/detectors.md).

6. Select, for what is still flagged. Generate candidates of those paragraphs, with
other opening words if the paragraph starts with a stock phrase:

python3 scripts/rewrite.py my-text.txt -o rewritten.txt --concepts concepts.txt \
        --only 4 --candidates 6 --lead "Desde la" --temperature 1.1

Join each candidate into the full text, measure, adopt the one that passes, and join again:

python3 scripts/rewrite.py my-text.txt -o rewritten.txt --take 4=rewritten.txt.candidates/p04-3.txt
python3 scripts/join.py rewritten.txt -o final.txt --concepts concepts.txt --pauses 2

Reread the adopted paragraph against the original: passing a detector is worth nothing if
it dropped an idea.

Before measuring, prepare what you paste: halves under 1,400 words, a check phrase that only
the final has, and the clipboard in UTF-8 (a plain pbcopy breaks accents):

python3 scripts/halves.py final.txt --original my-text.txt --copy 1

Worked examples, with every hand fix listed, are in examples/.

Languages

Other languages: the rewrite may work (the base model is multilingual), but join.py
only knows Spanish and English connectors. Adding one is a small dictionary in
scripts/join.py; pull requests welcome.

Detectors

Each detector runs its own model, so a version that passes one may not pass another; the
first essay passes all three at once. Measurements on more detectors and more kinds of
text are the contribution we need most.

FAQ

Is it free? Do I need an OpenAI key or any account?
Free and keyless. The model downloads once and runs on your computer.

Does it change what my text says?
It is built not to: tries that lose a concept, change a quote, invent a reference, eat
accents, switch language or drop key negations are rejected, check.py compares concepts and negations, and you reread every paragraph.

Does it add typos on purpose, like other "humanizers"?
No. It changes who wrote the sentences and their rhythm, not the spelling.

Are the results consistent?
Three of four essays reached 0% in Grammarly, and the latest one passes Grammarly, GPTZero
and ZeroGPT at once. The pieces that can be deterministic are (the joining is seeded;
ZeroGPT gives the same score for the same text), output that copies the original is
refused, and 48 tests run on every change on Ubuntu, macOS and Windows. Detectors drift
over time, which is why every session carries controls.

Does the selection step send my text anywhere?
The tool never does. Measuring is your step, in your detector, as with any text you check.

Do I need a GPU?
No. It runs on CPU, at low priority, so your computer stays usable.

Limits

1. GPTZero in English is the next milestone. Its newer English model (4.1o) reads
   base-model text from ~250 words on; three model families were tested
   (evidence). Emails, marketing and technical writing are not
   measured yet.
2. Rereading is not optional. The base model sometimes changes a detail or flips an
   idea. The pipeline catches lost concepts, changed quotes and invented references; a
   person catches the rest.
3. Selection costs time. Each candidate is a model run (30–60 s per paragraph on an M4).
4. Detectors change. This is a snapshot of October 2026.

Responsible use

Made for text you sign and answer for: brand content, outreach, documentation, emails,
drafts written with AI help. Don't use it to hand in graded work as your own where AI is
banned or must be disclosed. That problem isn't technical; it's academic honesty.

Project layout

humanizar-es/
├── SKILL.md                 the skill for agents
├── install.py               installs the skill (install.sh: shortcut for macOS/Linux)
├── scripts/
│   ├── install_model.py     downloads the model (once)
│   ├── rewrite.py           stages 1, 2 and 4: rewrite, guard fidelity, candidates
│   ├── check.py             stage 2: concepts and negations, original vs rewrite
│   └── join.py              stage 3: rebuild the rhythm of each paragraph
├── examples/                worked examples in Spanish and English
├── references/              every measurement, and how to measure
└── tests/                   48 tests on Ubuntu, macOS and Windows (no network, no model)

The old script names (hip.py, unir.py, verificar_fidelidad.py, instalar_hip.py)
still work.

Contributing

What's missing most is evidence: the pipeline measured on more texts, more languages
and more detectors, always with a human control and the AI original. Open an issue or a
PR with the numbers in references/evidence.md.

python3 -m unittest discover -s tests -v

Credits and license

Code and docs: MIT, © ervin-mo. The HIP method and adapter are by Xu et al.
(2026); the base model is Alibaba's Qwen3-4B-Base. Both are Apache-2.0 and downloaded
separately: see THIRD_PARTY.md. If you use this in your work, cite the
repo (CITATION.cff) and the HIP paper.