🪶 Humanizer

Transform robotic AI text into natural, authentic human prose.
Powered by Google Gemini, Wikipedia’s 33 anti-AI writing patterns, and real-time voice calibration.

---

📖 Table of Contents

• Overview
• Key Features
• Why Humanizer?
• The 33 Anti-AI Writing Patterns
• Architecture & How It Works
• Tone & Voice Calibration Studio
• Quick Start & Installation
  • Prerequisites
  • 1. Clone the Repository
  • 2. Install Dependencies
  • 3. Configure Environment Variables
  • 4. Start the Application
• Using the Web Interface
  • Dual-Pane Workspace
  • Live Visual Diff
  • Keyboard Shortcuts
• API Reference
  • GET /api/status
  • GET /api/skill-info
  • POST /api/analyze-patterns
  • POST /api/humanize/stream (SSE)
  • POST /api/humanize
  • POST /api/save-key
• Project Structure
• Configuration Options
• Contributing
• License

---

✨ Overview

Large Language Models (ChatGPT, Claude, Gemini, Copilot) frequently output predictable, sterile, and cliché-ridden text. From excessive em dashes (—), inflated significance ("stands as a testament to the evolving landscape"), formulaic rule-of-three triplets, to superficial -ing participle endings (", highlighting the importance of..."), AI text is easily spotted by readers and AI detectors alike.

Humanizer is a complete, full-stack writing engine and web application designed to strip away AI tells and reconstruct your text into clean, engaging, rhythmically varied, and authentic human writing.

Built on Wikipedia's "Signs of AI Writing" guide (maintained by WikiProject AI Cleanup) and codified in a modular rule engine (SKILL.md), Humanizer combines:

1. Instant Heuristic Pattern Detection: Scans text locally across 33 distinct AI clichés, scoring AI density in real-time.
2. Deep LLM Restructuring: Leverages Google Gemini (2.5 Flash / Pro) with strict zero-hallucination and voice-preservation system prompts.
3. Real-time Server-Sent Events (SSE) Streaming: Delivers live token streaming with instant side-by-side visual diffs.

---

🚀 Key Features

• 🔍 Real-Time 33-Pattern AI Cliché Scanner
  Instantly highlights significance inflation, promotional buzzwords, copula avoidance, em dash overuse, transition word stacking, and more as you type.
• ⚡ Zero Hallucination Guarantee
  Strict instructions ensure no dates, names, facts, or citations are fabricated during the rewriting process. Information is preserved; empty fluff is discarded.
• 🎙️ Voice Calibration Studio
  Provide 2–3 paragraphs of your own natural writing. Humanizer matches your unique vocabulary, sentence rhythms, paragraph cadence, and stylistic habits.
• 🎛️ 5 Curated Tone Profiles
  Switch seamlessly between Balanced (standard), Conversational (casual), Editorial (sharp publication prose), Punchy (ultra-concise), and Academic (rigorous and neutral).
• 🔄 2-Pass Audit Mode
  Generates Draft 1, performs an automated anti-AI audit, reviews remaining tells, and outputs the refined final prose.
• 📊 Visual Diff & Fluff Reduction Metrics
  Compare original AI text against the humanized output line-by-line with color-coded diffing and fluff reduction percentage calculations.
• 🌊 SSE Live Streaming
  Smooth, high-throughput streaming directly from the Gemini API into the dual-pane UI.
• 🎨 Glassmorphic Dark-Mode UI
  A modern, responsive, zero-dependency vanilla CSS/JS interface designed for high productivity.

---

🧠 Why Humanizer?

Most AI paraphrasers merely swap words with generic synonyms, leading to awkward phrasing that still reads like machine output. Humanizer tackles the problem at its structural and psychological core:

[ AI-Generated Input ]
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 1: Local Heuristic Analysis (33 Pattern Rules)       │
│  - Calculates AI Cliché Density Score (0 - 100%)            │
│  - Categorizes tells (Content, Language, Style, Structure)  │
└─────────────────────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 2: Prompt Synthesis with SKILL.md & Voice Sample     │
│  - Injects Wikipedia AI Cleanup System Rules                │
│  - Calibrates personal rhythm from author's sample          │
│  - Applies selected Tone Modifier                           │
└─────────────────────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 3: Gemini 2.5 Flash/Pro Restructuring                │
│  - Strips empty fluff & compresses low-signal padding       │
│  - Varies sentence lengths & paragraph cadence              │
│  - Streams results back in real-time via SSE                │
└─────────────────────────────────────────────────────────────┘
       │
       ▼
[ Clean, Natural, Human Prose + Visual Diff ]

---

📚 The 33 Anti-AI Writing Patterns

Humanizer identifies and eliminates 33 specific writing tells defined by Wikipedia's AI Cleanup project across four core categories:

#	Category	Pattern Name	Typical AI Symptom
01	Content	Significance Inflation	"stands as a testament to", "pivotal moment", "evolving landscape"
02	Content	Notability Name-Dropping	Listing publications or follower counts without context
03	Content	Superficial -ing Analyses	", highlighting the importance of...", ", ensuring seamless..."
04	Content	Promotional Fluff	"nestled in", "boasts a vibrant", "rich tapestry", "breathtaking"
05	Content	Vague Attributions	"industry reports suggest", "experts argue", "observers note"
06	Content	Formulaic Sandwiches	"Despite challenges... continues to thrive", "Looking ahead, the future promises..."
07	Language	AI Buzzwords	"delve", "tapestry", "beacon", "multifaceted", "paramount", "foster"
08	Language	Copula Avoidance	Using "serves as", "features", "boasts" instead of simple "is" or "has"
09	Language	Negative Parallelisms	"It is not just X, it is Y", ", no guessing needed"
10	Language	Forced Rule of Three	Symmetrical triplets ("innovative, reliable, and scalable")
11	Language	Synonym Cycling	Stiff substitutions ("the aforementioned entity", "said individual")
12	Language	False Ranges	"from beginners to seasoned professionals" (when not a true continuum)
13	Language	Subjectless Fragments	"Allows for easy setup", "Enables users to seamlessly..."
14	Style	Em Dash Overuse	Relying on — or -- every two sentences as a synthetic pause crutch
15	Style	Boldface Overuse	Excessive **bold keywords** scattered across standard prose
16	Style	Inline-Header Bullet Lists	Forcing prose into - **Concept:** Explanation patterns
17	Style	Title Case Headings	Capitalizing Every Single Word In Section Titles
18	Style	Emoji Decoration	Inserting 🚀, 💡, 📌, 🔑 before headings and list items
19	Style	Curly Smart Quotes	Synthetic typesetter quotes (“ ” ‘ ’) instead of clean ASCII
20	Structure	Summary Restatements	Repetitive "In summary", "In essence", "All in all" endings
21	Structure	Unsolicited Definitions	Condescending explanations ("X, which refers to...")
22	Structure	Rhetorical Question Hooks	"Why does this matter?", "What does this mean for...?"
23	Structure	Symmetrical Pacing	Uniform 4-sentence paragraph blocks with identical length
24	Language	Transition Stacking	Starting consecutive sentences with "Furthermore,", "Moreover,", "Additionally,"
25	Content	Pseudo-Profundity	"tapestry of human experience", "catalyst for change", "journey of discovery"
26	Language	Hyphenated Jargon	"data-driven", "client-facing", "results-focused", "cutting-edge"
27	Communication	Authority Tropes	Patronizing phrases ("At its core", "What truly matters is", "Make no mistake")
28	Communication	Signposting	Announcing what will be said ("In this article, we will delve into...")
29	Communication	Generic Conclusions	"In conclusion, only time will tell as we move forward."
30	Communication	Fence-Sitting Balance	Robotic "While X has merits, Y also presents notable drawbacks."
31	Communication	Unnatural Hype	"Thrilled to announce!", "Exciting game-changing breakthrough!"
32	Communication	Boilerplate Disclaimers	"It is important to remember that...", "It is worth keeping in mind..."
33	Structure	Over-Bulletization	Converting narrative explanations into sterile bullet point lists

---

🏗️ Architecture & How It Works

Humanizer is structured with a lightweight, high-performance Node.js / Express backend and a responsive Vanilla JavaScript frontend:

┌─────────────────────────────────────────────────────────────┐
│                       Frontend (SPA)                        │
│  - Vanilla JS (app.js) + CSS3 Glassmorphic Dark Design      │
│  - SSE EventSource Consumer + Realtime Regex Cliché Scanner │
│  - Local Diff Engine & Voice Sample Storage (localStorage)  │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTP / SSE
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    Express.js Web Server                    │
│  - server/server.js (REST API & SSE streaming endpoints)    │
│  - server/pattern-detector.js (33 AI Regex Definitions)     │
│  - server/humanizer-engine.js (SKILL.md Parser & Gemini API)│
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTPS (v1beta REST / SSE)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                  Google Gemini AI Engine                    │
│       gemini-2.5-flash  /  gemini-2.5-pro  /  gemini-2.0    │
└─────────────────────────────────────────────────────────────┘

---

🎙️ Tone & Voice Calibration Studio

Personal Voice Calibration

Scrubbing AI tells is only half the battle—generic, sterilized text can feel just as robotic. Humanizer includes a dedicated Voice Calibration Studio:

1. Click Voice Studio in the navigation bar.
2. Paste 2–3 paragraphs of writing you've previously authored (e.g. an email, blog post, or essay).
3. The engine parses your cadence, average sentence length, punctuation preferences, and stylistic habits, instructing the model to match your natural voice.

5 Tailored Tone Modifiers

• Balanced (Standard): Natural, clear, grounded human voice that fits any general topic.
• Conversational (Casual): Friendly, approachable tone with natural phrasing and light touches.
• Editorial: Sharp, engaging, publication-ready prose suitable for essays and thought leadership.
• Punchy (Concise): Tight, direct sentences with zero fluff or wasted words.
• Academic: Precise, scholarly, objective prose without marketing jargon or empty filler.

---

🚀 Quick Start & Installation

Prerequisites

• Node.js v18.0.0 or higher (Download Node.js)
• Google Gemini API Key (Get a free key from Google AI Studio)

1. Clone the Repository

git clone https://github.com/ravindudil5han/humanizer.git
cd humanizer

2. Install Dependencies

npm install

3. Configure Environment Variables

Copy .env.example to .env:

cp .env.example .env

Open .env and add your Gemini API key:

PORT=3000
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-flash

(Note: You can also enter and save your API key directly inside the Settings UI in the browser!)

4. Start the Application

Development Mode (with auto-reload):

npm run dev

Production Mode:

npm start

Open your browser and navigate to:

http://localhost:3000

---

🖥️ Using the Web Interface

Dual-Pane Workspace

• Left Pane (AI Input):
  • Type or paste AI-generated text.
  • Use the Paste button or Upload (.txt / .md) button.
  • Try one of the built-in AI sample texts (Tech Startup Slop, Corporate PR Fluff, Academic Puffery).
  • Watch the AI Cliché Meter update in real-time with detected pattern tags.
• Right Pane (Humanized Output):
  • Watch live streaming token generation.
  • Toggle between Prose view and Visual Diff view.
  • Copy the result with one click or download as Markdown.
  • Swap the output back to the input if you want another refinement pass.

Live Visual Diff

Click the Visual Diff tab on the output pane to view an aligned, line-by-line comparison highlighting additions, deletions, and sentence contractions.

Keyboard Shortcuts

Shortcut	Action
Ctrl + Enter / Cmd + Enter	Trigger Humanize Prose rewrite
Esc	Close any open modal

---

🔌 API Reference

Humanizer provides a clean REST and Server-Sent Events (SSE) API that you can integrate into your own automation pipelines, scripts, or editor extensions.

GET /api/status

Returns the operational health, loaded model, API key configuration, and pattern count.

Response:

{
  "status": "ok",
  "version": "2.9.1",
  "model": "gemini-2.5-flash",
  "hasApiKey": true,
  "patternsCount": 33
}

---

GET /api/skill-info

Returns all 33 anti-AI pattern definitions with their category, severity, and description.

Response:

{
  "version": "2.9.1",
  "totalPatterns": 33,
  "patterns": [
    {
      "id": 1,
      "category": "Content",
      "name": "Significance Inflation & Broader Trends",
      "description": "Puffing up importance with phrases like 'pivotal moment', 'testament to'...",
      "severity": "high"
    }
  ]
}

---

POST /api/analyze-patterns

Analyzes any given text locally without calling external LLMs, returning detected patterns, word counts, and an AI density score.

Request Body:

{
  "text": "This platform serves as a testament to the evolving landscape, highlighting the paramount importance of synergy."
}

Response:

{
  "score": 75,
  "totalMatches": 4,
  "detectedPatterns": [
    {
      "id": 1,
      "name": "Significance Inflation & Broader Trends",
      "category": "Content",
      "severity": "high",
      "count": 2,
      "samples": ["serves as a testament", "evolving landscape"]
    },
    {
      "id": 3,
      "name": "Superficial -ing Analyses",
      "category": "Content",
      "severity": "high",
      "count": 1,
      "samples": [", highlighting"]
    },
    {
      "id": 7,
      "name": "AI Vocabulary Buzzwords",
      "category": "Language",
      "severity": "high",
      "count": 1,
      "samples": ["paramount"]
    }
  ],
  "stats": {
    "words": 16,
    "chars": 113,
    "sentences": 1
  }
}

---

POST /api/humanize/stream (SSE)

Live streaming rewrite endpoint via Server-Sent Events.

Request Body:

{
  "text": "In today's fast-paced digital landscape, this groundbreaking tool serves as a testament to innovation.",
  "tone": "standard",
  "voiceSample": "I like simple, punchy sentences. I don't use buzzwords.",
  "includeAudit": false,
  "apiKey": "optional_override_key",
  "model": "gemini-2.5-flash"
}

Stream Events:

• data: {"type":"start", "preAnalysis":{...}}
• data: {"type":"chunk", "text":"This "}
• data: {"type":"chunk", "text":"tool "}
• data: {"type":"done", "fullText":"This tool is a practical example of innovation.", "postAnalysis":{...}}

---

POST /api/humanize

Synchronous rewrite endpoint (non-streaming).

Request Body:

{
  "text": "In today's fast-paced digital landscape...",
  "tone": "editorial"
}

Response:

{
  "text": "The platform simplifies workflow management across distributed teams.",
  "preAnalysis": { "score": 82, "totalMatches": 5 },
  "postAnalysis": { "score": 0, "totalMatches": 0 }
}

---

POST /api/save-key

Saves your Gemini API key and preferred model directly into the server's .env file from the settings UI.

Request Body:

{
  "apiKey": "AIzaSy...",
  "model": "gemini-2.5-flash"
}

---

📁 Project Structure

humanizer/
├── .env.example               # Template for environment configuration
├── .gitignore                 # Standard git ignores (node_modules, .env)
├── LICENSE                    # MIT License
├── package.json               # Project manifest and scripts
├── SKILL.md                   # Complete rule definition & system instructions (v2.9.1)
├── public/                    # Frontend client assets
│   ├── css/
│   │   └── style.css          # Glassmorphic dark design system & responsive layout
│   ├── js/
│   │   └── app.js             # Client SPA logic, SSE handling, diffing & UI state
│   └── index.html             # Main dual-pane web application
└── server/                    # Backend Node.js service
    ├── humanizer-engine.js    # Gemini API client, SSE streaming & prompt synthesis
    ├── pattern-detector.js    # 33 regex/heuristic anti-AI pattern definitions
    └── server.js              # Express app, static routing, and REST/SSE endpoints

---

⚙️ Configuration Options

You can configure the server through environment variables or via the Web UI Settings:

Variable	Default	Description
PORT	3000	The port on which the Express server listens.
GEMINI_API_KEY	""	Your Google Gemini API Key from Google AI Studio.
GEMINI_MODEL	gemini-2.5-flash	Gemini model to use (gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash, gemini-1.5-flash).

---

🤝 Contributing

Contributions, issues, and feature suggestions are very welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/awesome-pattern)
3. Commit your changes (git commit -m 'feat: add detection for new AI buzzword pattern')
4. Push to the branch (git push origin feature/awesome-pattern)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

I give the copyright for skill.md to blader. Thank you.

---

Built with ❤️ for clear, authentic, and human writing.