Jade''s AI Humanizer

Zero-Backend, Client-Side AI Text Humanizer & REST Daemon
Powered by Google Gemini Flash Lite with minimal prompt token consumption, zero third-party telemetry, offline fallback, and markdown preservation.

---

Overview

Jade''s AI Humanizer is a zero-dependency-backend, completely local Python library, CLI, and standalone REST API daemon. It transforms rigid, repetitive AI-generated text into fluid, natural human writing while preserving document architecture, markdown formatting, code fences, and data tables.

Designed from the ground up for minimal token cost and maximum privacy:

• 100% Client-Side & Local: Runs directly on your machine. No proxy servers, no third-party tracking, no stored prompts.
• Minimal Token Consumption: Uses Google Gemini Flash Lite (gemini-2.5-flash-lite / gemini-2.0-flash-lite) with ultra-compact prompt engineering (<100 prompt tokens overhead in Budget mode).
• Offline Deterministic Fallback: Operates seamlessly even without an API key using local heuristic paraphrasing and guardrail sanitization.
• Pre-Built Standalone Windows Executable: Run dist/humanizer.exe with a single click—no Python installation required.
• REST & SSE Streaming Daemon: Built-in FastAPI/Uvicorn daemon with interactive Swagger UI (/docs) and Server-Sent Events (SSE) streaming.

---

Table of Contents

1. Features
2. Quickstart & Installation
3. Standalone Executable (humanizer.exe)
4. Python Library Usage
   • Synchronous (humanize)
   • Asynchronous (humanize_async)
   • Streaming (humanize_stream / humanize_stream_sync)
5. CLI Reference
6. REST & Streaming API Reference
   • GET /health
   • POST /v1/humanize
   • POST /v1/humanize/stream (SSE)
7. Engine Architecture & Quality Guardrails
8. Running Tests
9. License

---

Features

• Tiered Humanization Modes:
  • budget (default): Ultra-low token overhead (<100 tokens), compact single-pass prompt, cost-effective for high-volume pipelines.
  • deep: Multi-layered rewrite optimizing burstiness variation, perplexity shifts, and natural syntactic rhythms to minimize AI detection.
• Style Presets & Reading Levels:
  • Tone presets: neutral, casual, academic, professional.
  • Reading levels: general, middle_school, high_school, college.
• Zero-Tolerance AI Buzzword Sanitizer: Automatically scrubs overused AI clichés ("delve into", "tapestry of", "testament to", "in conclusion", "moreover", "foster", "multifaceted") replacing them with natural synonyms.
• Plain-Language Anti-Jargon & Geometric Deflation Engine: Strips dramatic modifiers ("escalating challenges" → "growing problems"), textbook jargon ("impermeable surfaces" → "concrete and asphalt", "solar radiation" → "heat", "ambient temperatures" → "temperatures"), clinical/geometric over-descriptions ("essential rectangular geometry" → "basic rectangular shape", "expansive glass walls" → "large glass walls"), and rare Latinate words ("mitigate", "exacerbate", "commence").
• Grammar & Syntax Post-Processor: Fixes double spaces, punctuation spacing, capitalization errors, and duplicate words while preserving list and quote indentations.
• Flesch Readability Scoring: Automatically calculates and reports Flesch Reading Ease and Flesch-Kincaid Grade Level for before/after comparison.
• Markdown & Code Invariance: Safely protects inline code (`code`), fenced code blocks (``` / ~~~), math expressions ($formula$), URLs/hyperlinks, and GFM tables without token corruption.

---

Quickstart & Installation

Option A: Install from PyPI (Recommended)

Once published to PyPI, install with standard pip:

pip install jades-ai-humanizer

Option B: Install Directly from GitHub

pip install git+https://github.com/JustJade2007/Jade-s-AI-Humanizer.git

Option C: From Source / Local Development

# Clone or navigate to the repository
cd "Jade's AI Humanizer"

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate  # Linux/macOS

# Install dependencies in editable mode
pip install -e .

Option D: Use in Another Python Project (Zero Manual Copying)

You do not need to copy any code. You can integrate humanizer into any other project using either of these ways:

Method 1: PyPI / GitHub

pip install jades-ai-humanizer
# or directly from GitHub:
pip install git+https://github.com/JustJade2007/Jade-s-AI-Humanizer.git

Method 2: Editable Local Install (For Local Multi-Project Dev)

In your other project's terminal / virtual environment, run:

pip install -e "c:\Users\jacob\OneDrive\Desktop\Coding\Jade's AI Humanizer"

Any future updates made to Jade's AI Humanizer are immediately available in your other project without reinstalling.

Method 3: Local REST API / Microservice (Language Agnostic)

Run the local daemon or dist/humanizer.exe, and call it from any project (Python, Node.js, Go, etc.) over HTTP:

import requests

res = requests.post("http://127.0.0.1:8000/v1/humanize", json={"text": "Your text here..."})
print(res.json()["humanized_text"])

Option C: Configure Gemini API Key

Set your Google Gemini API key as an environment variable (optional, enables Gemini Flash Lite):

# Windows PowerShell
$env:GEMINI_API_KEY="your-gemini-api-key"

# Windows Command Prompt
set GEMINI_API_KEY=your-gemini-api-key

# Linux/macOS
export GEMINI_API_KEY="your-gemini-api-key"

Note: If no API key is set, the humanizer automatically activates its built-in offline deterministic mock engine, allowing full offline development and testing.

---

---

Standalone Executable (humanizer.exe) & Web UI

A standalone portable Windows executable is provided in dist/humanizer.exe (and launchable via launch.bat in the project root). It bundles Python, FastAPI, Uvicorn, CA certificates, and all required runtime libraries into a single self-contained binary that can run on any modern 64-bit Windows PC (Windows 10, 11, Server) without requiring Python or developer tools.

Launching the Application

1. One-Click Web GUI (Recommended):

   • Double-click launch.bat or dist/humanizer.exe in Windows Explorer.
   • The app automatically launches the local daemon, dynamically detects an available port if port 8000 is occupied, and automatically opens your default browser to http://127.0.0.1:8000/.
   • Use the embedded interface to paste text, configure Gemini API keys (optional), adjust tone, choose reading levels, and humanize in real time.

2. Command Line Humanizer (CLI Mode): Humanize text directly without opening a server or browser:

   dist\humanizer.exe humanize "It is crucial to delve into the tapestry of AI."
   

   Or via the batch launcher:

   launch.bat humanize "In conclusion, this shows modern engineering."
   

3. Background / Headless Daemon Mode: Run the local daemon without popping up a browser window:

   dist\humanizer.exe serve --no-browser --port 8000
   

4. Rebuilding the Executable: To rebuild the standalone executable at any time:

   .venv\Scripts\python.exe packaging\build_exe.py
   

---

Python Library Usage

Synchronous (humanize)

from humanizer import Humanizer

client = Humanizer(api_key="your-api-key")  # or reads GEMINI_API_KEY env var

text = """
It is crucial to delve into the intricate tapestry of modern machine learning.
Moreover, this framework serves as a testament to automated efficiency.
"""

result = client.humanize(
    text=text,
    mode="budget",              # "budget" or "deep"
    tone="neutral",             # "neutral", "casual", "academic", "professional"
    reading_level="general",    # "general", "middle_school", "high_school", "college"
    preserve_markdown=True,
)

print("Humanized:\n", result.text)
print("Tokens Used:", result.usage.total_tokens)
print("Flesch Score:", result.readability.flesch_reading_ease)
print("Replaced Clichés:", result.buzzwords_replaced)

Asynchronous (humanize_async)

import asyncio
from humanizer import Humanizer

async def main():
    client = Humanizer()
    result = await client.humanize_async(
        text="Furthermore, one must remember that technology is constantly evolving.",
        mode="deep",
        tone="casual"
    )
    print(result.text)

asyncio.run(main())

Streaming

Stream tokens in real time as they are generated:

Asynchronous Streaming:

import asyncio
from humanizer import Humanizer

async def main():
    client = Humanizer()
    async for chunk in client.humanize_stream(
        "It is imperative to delve into the underlying mechanics.",
        mode="budget"
    ):
        print(chunk, end="", flush=True)

asyncio.run(main())

Synchronous Streaming:

from humanizer import Humanizer

client = Humanizer()
for chunk in client.humanize_stream_sync("Delve into the possibilities."):
    print(chunk, end="", flush=True)

---

CLI Reference

The CLI entrypoint is humanizer:

# Check version
humanizer --version

# View all options
humanizer --help

# Start the local REST API daemon (defaults to 127.0.0.1:8000)
humanizer serve --port 8000

# Humanize direct text string
humanizer humanize "It is crucial to delve into the tapestry of AI." --mode deep --tone casual

# Humanize from a markdown file
humanizer humanize -f document.md --mode budget > humanized_document.md

# Pipe through stdin
cat input.txt | humanizer humanize --mode budget

---

REST & Streaming API Reference

Start the local server daemon:

humanizer serve --port 8000

Interactive OpenAPI / Swagger docs are live at http://127.0.0.1:8000/docs.

GET /health

Returns daemon health status and active engine configuration.

Request:

curl http://127.0.0.1:8000/health

Response (200 OK):

{
  "status": "healthy",
  "version": "1.2.1",
  "engine": "gemini-2.5-flash-lite",
  "api_key_configured": true,
  "is_offline": false,
  "default_mode": "budget"
}

POST /v1/humanize

Rewrites text using specified mode and presets.

Request:

curl -X POST http://127.0.0.1:8000/v1/humanize \
  -H "Content-Type: application/json" \
  -d '{
    "text": "It is crucial to delve into the tapestry of digital innovation.",
    "mode": "budget",
    "tone": "neutral",
    "reading_level": "general",
    "preserve_markdown": true,
    "api_key": "optional-gemini-key-override"
  }'

Response (200 OK):

{
  "humanized_text": "It's crucial to explore the blend of digital innovation.",
  "original_text": "It is crucial to delve into the tapestry of digital innovation.",
  "mode": "budget",
  "tone": "neutral",
  "reading_level": "general",
  "prompt_tokens": 54,
  "completion_tokens": 9,
  "total_tokens": 63,
  "buzzwords_replaced": ["delve into", "tapestry of"],
  "flesch_reading_ease": 93.0,
  "is_offline": false,
  "engine": "gemini-2.5-flash-lite",
  "api_tokens_used": 63
}

POST /v1/humanize/stream (SSE)

Real-time Server-Sent Events (SSE) streaming endpoint.

Request:

curl -N -X POST http://127.0.0.1:8000/v1/humanize/stream \
  -H "Content-Type: application/json" \
  -d '{
    "text": "It is crucial to delve into modern software architecture.",
    "mode": "budget"
  }'

SSE Output Stream:

data: {"chunk": "It's"}

data: {"chunk": " crucial"}

data: {"chunk": " to"}

data: {"chunk": " explore"}

data: {"chunk": " modern"}

data: {"chunk": " software"}

data: {"chunk": " architecture."}

data: [DONE]

---

Engine Architecture & Quality Guardrails

Raw Input Text
      │
      ▼
┌───────────────────────────────────────┐
│ 1. Markdown & Token Masking Parser    │
│    - Extracts & isolates code blocks  │
│    - Masks URLs, Math ($), GFM Tables │
└──────────────────┬────────────────────┘
                   │
                   ▼
┌───────────────────────────────────────┐
│ 2. Semantic Chunking                  │
│    - Splits on paragraph boundaries   │
│    - Handles oversized paragraphs     │
└──────────────────┬────────────────────┘
                   │
                   ▼
┌───────────────────────────────────────┐
│ 3. Gemini Flash Lite Engine           │
│    - Compact prompt (<70 tokens)      │
│    - Budget / Deep Paraphraser        │
│    - Offline Mock Fallback Engine     │
└──────────────────┬────────────────────┘
                   │
                   ▼
┌───────────────────────────────────────┐
│ 4. Quality & Vocabulary Guardrails    │
│    - 0-Tolerance AI Buzzword Filter   │
│    - Punctuation & Spacing Sanitizer  │
│    - Readability Scoring Engine       │
└──────────────────┬────────────────────┘
                   │
                   ▼
┌───────────────────────────────────────┐
│ 5. Reconstruction & Unmasking         │
│    - Reintegrates untouched blocks    │
│    - Restores exact indentation       │
└──────────────────┬────────────────────┘
                   │
                   ▼
Humanized Output Text

---

Running Tests

The test suite includes unit tests, end-to-end integration tests, adversarial stress tests, and token overhead benchmarks:

# Run all 301 tests
.venv\Scripts\pytest tests/

# Run benchmark tests
.venv\Scripts\pytest tests/benchmarks/

# Run adversarial stress tests
.venv\Scripts\pytest tests/unit/test_markdown_stress.py

---

License

MIT License. Designed and built for seamless integration into any project.