Download the PHP package ksanyok/text-humanize without Composer

Table of Contents

• Why TextHumanize?
• Proprietary Technologies
• Installation
• Quick Start
• Private Offline Workflow
• Before & After Examples
• Feature Matrix
• Comparison with Competitors
• Processing Pipeline
• AI Detection Engine
• API Reference
• Profiles & Presets
• Language Support
• NLP Infrastructure
• SEO Mode
• Readability Metrics
• Paraphrasing Engine
• Tone Analysis & Adjustment
• Watermark Detection & Cleaning
• Content Spinning
• Coherence Analysis
• Morphological Engine
• Stylistic Fingerprinting
• Auto-Tuner
• Plugin System
• Using Individual Modules
• CLI Reference
• REST API Server
• Async API
• Performance & Benchmarks
• Architecture
• TypeScript / JavaScript Port
• PHP Library
• Testing & Quality
• Security & Limits
• Responsible Use
• For Business & Enterprise
• FAQ & Troubleshooting
• What's New in v0.28.4
• Contributing
• Limitations
• Support the Project
• License & Pricing

TextHumanize is a pure-algorithmic text processing engine that transforms AI-generated drafts into clearer, more natural prose. Three proprietary technologies — PHANTOM™ (gradient-guided optimization against TextHumanize's own detector), ASH™ (adaptive signature humanization), and SentenceValidator™ (interstage quality control) — drive a 38-stage pipeline that reduces built-in AI-like style signals while preserving meaning. No neural networks, no API keys, no internet — just 235K+ lines of finely tuned rules, dictionaries, and statistical methods.

Honest note: TextHumanize is a style-normalization tool, not an AI-detection bypass tool. It reduces AI-like patterns (formulaic connectors, uniform sentence length, bureaucratic vocabulary) but does not guarantee that processed text will pass external AI detectors. Quality of humanization varies by language and text type. See Limitations below.

Built-in toolkit: AI Detection (3 detectors) · Paraphrasing · Tone Analysis · Watermark Cleaning · Content Spinning · Coherence Analysis · Readability Scoring · Stylistic Fingerprinting · Auto-Tuner · Perplexity Analysis · Plagiarism Detection · Grammar Check · Morphology Engine · Neural LM · Async API · SSE Streaming

Platforms: Python (full — 122 modules) · TypeScript/JavaScript (core) · PHP (full)

For business: SaaS integration · REST API with SSE streaming · Docker deployment · Bulk processing · Custom dictionaries · On-prem enterprise · White-label ready

Languages: 🇬🇧 EN · 🇷🇺 RU · 🇺🇦 UK · 🇩🇪 DE · 🇫🇷 FR · 🇪🇸 ES · 🇵🇱 PL · 🇧🇷 PT · 🇮🇹 IT · �🇱 NL · 🇸🇪 SV · 🇨🇿 CS · 🇷🇴 RO · 🇭🇺 HU · 🇩🇰 DA · 🇸🇦 AR · 🇨🇳 ZH · 🇯🇵 JA · 🇰🇷 KO · 🇹🇷 TR · 🇮🇳 HI · 🇻🇳 VI · 🇹🇭 TH · 🇮🇩 ID · 🇮🇱 HE · 🌍 any language via universal processor

🚀 Why TextHumanize?

Problem: Machine-generated text has uniform sentence lengths, bureaucratic vocabulary, formulaic connectors, and low stylistic diversity — reducing readability, engagement, and brand authenticity.

Solution: TextHumanize algorithmically normalizes text style while preserving meaning. Configurable intensity, deterministic output, full change reports. No cloud APIs, no rate limits, no data leaks.

� Proprietary Technologies

TextHumanize includes three original, proprietary technologies not found in any other open-source library:

PHANTOM™ — Gradient-Guided Text Optimization Engine

phantom.py — 2,943 lines | An open-source text naturalizer that uses numerical gradient optimization against TextHumanize's own AI detector.

• ORACLE computes numerical gradients through the MLP detector via central differences (~70 forward passes, ~1.4ms), producing per-feature contribution analysis and ranked gap reports
• SURGEON executes 32 feature-targeted surgical text operations guided by Oracle gradients — rank-based magnitude scheduling focuses effort on highest-impact features first
• FORGE runs an iterative optimization loop with combined score tracking, stall detection, adaptive budget escalation, text expansion limits, and post-iteration cleanup
• Result: 100% internal pass rate on TextHumanize's built-in detector benchmark (15/15 texts across EN, RU, UK). Processing time: 0.7–1.4s. External detectors use different models and are not guaranteed.

ASH™ — Adaptive Signature Humanization

ash_engine.py + signature_transfer.py + perplexity_sculptor.py | Statistically transforms text to match real human writing signatures.

• Human Profiles — statistical fingerprints of real human writing per language (sentence length distribution, vocabulary richness, burstiness patterns, punctuation habits)
• Signature Transfer — morphs AI text's statistical signature toward the target human profile
• Perplexity Sculpting — adjusts word-level perplexity to match human perplexity distribution curves
• Metric Gaps — identifies and systematically closes the gap between AI and human writing on 35+ features

SentenceValidator™ — Interstage Quality Gate

sentence_validator.py — 350 lines | Catches and eliminates artifacts between pipeline stages in real-time.

• 10 checks per sentence: duplicate words (the the), broken contractions (do n't), orphaned punctuation, double conjunctions (and and), dangling conjunctions, unterminated parentheses, triple+ character repeats, fragment chains, conjunction chains, empty sentences
• 7 validation checkpoints between pipeline stages — catches artifacts the moment they appear
• Language-aware — recognizes conjunctions in EN, RU, UK, DE, FR, ES
• Final sanitization — post-pipeline cleanup removes residual artifacts that survive all stages

�📦 Installation

From source:

Tip: Pin your version for production: pip install texthumanize==0.28.4

⚡ Quick Start

Private Offline Workflow

For privacy-sensitive content, use the local audit -> safe cleanup -> strict humanize -> audit pattern. It keeps processing offline, preserves critical terms, and records review metrics without using cloud APIs.

The example uses backend="local", quality_gate="strict", minimal=True, brand/identifier preservation, and a socket guard that raises if any code tries to open a network connection. See the full Private Offline Workflow guide.

All Features at a Glance

🔄 Before & After Examples

English

Before (AI-generated, AI score: 94%):

Furthermore, it is important to note that the implementation of cloud computing facilitates the optimization of business processes. Additionally, the utilization of microservices constitutes a significant advancement. Moreover, the integration of artificial intelligence into the workflow enhances decision-making processes and contributes to overall organizational efficiency.

After (TextHumanize, profile="web", intensity=60, AI score: 23%):

Also, importantly, the implementation of cloud computing helps the tuning of business processes. Up a major advancement, additionally, the use of microservices makes. And, the merge of artificial intelligence into the workflow enhances decision-making processes; and, contributes to overall organizational speed.

Russian

Before (AI score: 80%):

Необходимо отметить, что данная методология обеспечивает существенное повышение эффективности рабочих процессов. Кроме того, внедрение инновационных технологий способствует оптимизации функционирования организации. Более того, использование искусственного интеллекта позволяет значительно улучшить процесс принятия решений.

After (AI score: 5%):

Важно — что данная метод даёт существенное повышение эффективности рабочих процессов! Впрочем, смотрите, внедрение инновационных технологий помогает оптимизации функционирования организации, значительно, к тому же, использование искусственного интеллекта позволяет улучшить процесс принятия решений.

Ukrainian

Before (AI score: 75%):

Необхідно зазначити, що дана методологія забезпечує суттєве підвищення ефективності робочих процесів. Крім того, впровадження інноваційних технологій сприяє оптимізації функціонування організації. Більш того, використання штучного інтелекту дозволяє значно покращити процес прийняття рішень.

After (AI score: 17%):

Важливо, що ця метод дає суттєве підвищення ефективності робочих процесів; в принципі, впровадження інноваційних технологій веде до оптимізації функціонування організації. До того ж, використання штучного інтелекту дає змогу сильно покращити процес прийняття рішень.

AI Score Reduction Summary

Built-in AI detector scores. Results measured with TextHumanize's 3-layer ensemble (heuristic + statistical + MLP neural). External detectors may produce different results.

Profile Comparison (EN, intensity=50)

Input AI score: 94% — all profiles bring it below 35%.

🧩 Feature Matrix

⚔️ Comparison with Competitors

vs. Online Humanizers & GPT/LLM Rewriting

vs. Other Open-Source Libraries

vs. AI Detectors (GPTZero, Originality.ai)

🔧 Processing Pipeline (38 Stages)

Adaptive intensity: Auto-reduces processing for already-natural text. Graduated retry: Retries at lower intensity if change ratio exceeds the limit. SentenceValidator™: 7 interstage checkpoints catch artifacts between stages (10 checks per sentence). Tier system: Tier 1 languages (EN/RU/UK/DE) get all 38 stages. Tier 2 (FR/ES/IT/PL/PT/NL/SV/CS/RO/HU/DA) get ~30. Tier 3 (AR/ZH/JA/KO/TR/HI/VI/TH/ID/HE) get ~20 + universal.

🧠 AI Detection Engine

Three independent detectors combined into a single score:

Architecture

18 Heuristic Metrics

35-Feature Statistical Detector (Logistic Regression)

Neural MLP Detector

Feed-forward neural network entirely in pure Python (no PyTorch, no TensorFlow). Pre-trained weights shipped as compressed JSON (54 KB).

Verdicts

Detection Modes

📖 API Reference

humanize(text, lang, **kwargs) → HumanizeResult

Returns HumanizeResult:

Other Humanization Modes

detect_ai(text, lang) → dict

Other Core Functions

🎭 Profiles & Style Presets

Processing Profiles

Style Presets (5 Personas)

Intensity Levels

🌍 Language Support

Language Tiers

Dictionary Coverage

Universal processor works for any language using statistical methods — burstiness injection, perplexity normalization, sentence length variation, punctuation diversification.

🧬 NLP Infrastructure

TextHumanize includes a full NLP stack — all implemented in pure Python with zero external dependencies:

Total NLP infrastructure: ~8,800 lines of code, zero pip dependencies.

🔍 SEO Mode

TextHumanize includes a dedicated SEO workflow to humanize content without harming search rankings:

📊 Readability Metrics

full_readability() returns 6 reading metrics:

Grade interpretation:

✍️ Paraphrasing Engine

Rule-based syntactic paraphrasing — no LLM, no API, deterministic:

🎭 Tone Analysis & Adjustment

7-level formality scale with marker-based detection:

🛡️ Watermark Detection & Cleaning

Detects and removes 6 types of invisible text watermarks:

🔄 Content Spinning

Generate multiple unique variants with spintax support:

The spinner uses language-pack synonyms, contextual substitution, and sentence restructuring to produce each variant.

🔗 Coherence Analysis

Measure paragraph-level text flow:

🔠 Morphological Engine

Rule-based morphology for 4 languages — lemmatization, inflection, declension:

🎨 Stylistic Fingerprinting

Extract and compare author stylometric profiles:

Fingerprint dimensions: Mean sentence length, length variance, vocabulary richness, function word distribution, punctuation profile, discourse marker usage, passive voice ratio, average word length.

🎛️ Auto-Tuner (Feedback Loop)

Automatically optimize intensity and profile based on feedback:

The tuner uses Bayesian-like optimization to find ideal (intensity, profile) combinations for your content type.

🔌 Plugin System

Register custom hooks at any of 20 pipeline stages:

Available hook points: watermark → segmentation → typography → debureaucratization → structure → repetitions → liveliness → paraphrasing → syntax_rewriting → tone → universal → naturalization → paraphrase_engine → sentence_restructuring → entropy_injection → readability → grammar → coherence → validation → restore

🧪 Using Individual Modules

Every module is independently importable:

💻 CLI Reference

CLI Flags

🌐 REST API Server

Zero-dependency HTTP server with rate limiting and CORS:

For FastAPI deployments, see examples/fastapi_integration.py. It includes request body limits, text and batch size limits, per-request timeouts, structured error envelopes with request ids, and /v1/humanize/batch.

OpenAPI 3.1 schema is available at GET /openapi.json for client generation, contract tests, and API gateway import.

Endpoints

Rate limit: 10 req/s per IP, burst 20 · Max body: 5 MB

Example

Python Client

⚡ Async API

Native asyncio support for all public functions:

📈 Performance & Benchmarks

All benchmarks on Apple Silicon (M-series), Python 3.12, single thread, after warm-up. See the public Benchmark Methodology for corpus labels, quality dimensions, latency reporting rules, and detector limitations.

Speed

AI Score Reduction

Properties

Run benchmarks yourself:

🏗️ Architecture

Design principles:

🟦 TypeScript / JavaScript Port

Core TextHumanize functionality in TypeScript for Node.js and browsers:

🐘 PHP Library

Full-featured PHP port with Composer support:

✅ Testing & Quality

CI/CD: Every push triggers Python 3.9–3.13 + PHP 8.1–8.3 matrix, ruff lint, mypy type check, pytest with coverage ≥ 70%.

Core-language regressions: EN/RU/UK fixture packs verify protected tokens, cross-language leakage, and language-aware cleanup of over-humanized output.

Collocation guard: word-level replacements now keep strong local collocations intact, so natural phrases such as "heavy rain" are not weakened by context-free shorter synonyms.

Domain dictionaries: SaaS, ecommerce, fintech, legal, education, real estate, and healthcare terms are auto-detected or explicitly protected via preserve={"domains": [...]}.

🛡️ Security & Limits

Threat Model

Responsible Use

TextHumanize is built for style normalization, readability improvement, privacy-preserving audits, and internal AI-like/watermark risk checks. It does not guarantee passing external AI detectors, and its detector scores should be treated as internal quality signals rather than universal authorship verdicts.

Use it for content you own or are authorized to edit. Do not use it to misrepresent authorship, bypass required disclosure, remove provenance signals from third-party content, or submit work in contexts where AI assistance is prohibited.

Recommended production safeguards:

• show before/after diffs and change_ratio to reviewers;
• enable quality_gate="strict" for sensitive content;
• review metrics_after["anti_overhumanize"] when high-intensity profiles are used;
• use minimal=True / --only-flagged when only risky spans need edits;
• preserve brand terms, named entities, numbers, URLs, quotes, and code;
• require manual review for legal, medical, financial, academic, and policy content;
• use neutral customer-facing language: "internal style and watermark risk signals", not "guaranteed detector bypass".

See the full Responsible Use guide.

🏢 For Business & Enterprise

Processing Modes

Docker Deployment

❓ FAQ & Troubleshooting

Q: Does TextHumanize guarantee passing GPTZero / Originality.ai / Turnitin? No. TextHumanize is a style normalization tool. It reduces AI-like patterns but does not guarantee bypassing external AI detectors. See Limitations.

Q: What's the best profile for reducing AI-like style signals? chat with intensity 60–80 gives the largest reduction on TextHumanize's built-in detector benchmark. For professional content, try web at 70. External detector outcomes vary and should be verified separately.

Q: How do I preserve keywords (e.g., for SEO)? Use constraints={"keep_keywords": ["keyword1", "keyword2"]} or preserve={"brand_terms": ["BrandName"]}. By default, TextHumanize also protects URLs, email, code, Markdown/HTML, dates, prices, versions, order ids, exact quotes, and multi-token named entities.

Q: Can I use this for commercial projects? Yes, with a commercial license. See License & Pricing.

Q: Does it work offline? Does it send data to the internet? 100% offline. Zero network calls. Not even a health check ping. All processing is local.

Q: Why is the first call slower? The first call loads language packs and initializes caches. Subsequent calls are 11× faster via LRU cache.

Q: Can I train it on my own data? Yes — dict_trainer.py trains custom dictionaries from your corpus, and training.py can retrain the neural detector/LM.

Q: How do I add support for a new language? Create a language pack in texthumanize/lang/your_lang.py following the existing pattern (15 required sections). Or use the universal processor which works with any language automatically.

Q: Can I use individual modules (e.g., just POS tagger) without the full pipeline? Yes. Every module is independently importable. See Using Individual Modules.

Q: Is there a GUI? Try the Live Demo. For local use, the REST API + SSE streaming integrates easily with any frontend.

Q: How deterministic is it? 100% deterministic when using the same seed. Same input + same seed + same version = byte-identical output.

Q: What Python versions are supported? 3.9, 3.10, 3.11, 3.12, and 3.13 — all tested in CI.

🆕 What's New in v0.28.4

Explainable audit and safer humanization (0.28.4)

• Explainable AI detector reports — detect_ai_explain() returns calibrated score, confidence interval, metric contributions, highlighted spans, sentence report, mixed-content shares, and suggested actions.
• Unified watermark forensics — watermark_report() covers invisible Unicode, homoglyphs, fullwidth/math lookalikes, and statistical watermark hypotheses with p-value/z-score evidence.
• Promopilot-ready audit JSON — audit_report() combines AI and watermark findings in a stable schema for product integrations and batch workflows.
• Stricter quality controls — quality_gate="strict" can reject risky rewrites, while minimal=True / --only-flagged changes only flagged fragments.
• Anti-overhumanize final guard — high-intensity output now trims stacked fillers, repeated discourse markers, and excessive expressive punctuation before returning.
• Better short commercial copy coverage — golden-set regression tests now cover landing, product, and support copy patterns.
• CI and release hardening — GitHub CI is green across Python 3.9-3.13, PHP 8.1-8.3, TypeScript/JavaScript, and docs; local release coverage is 80.09%.

Previous release readiness (0.28.3)

• GitHub community checklist completed — added Code of Conduct, Security Policy, issue templates, quality-report template, and pull request template.
• Release metadata sync — Python, PHP, and TypeScript package versions are aligned for PyPI, Packagist, and source installs.
• Safer release verification — version checks now validate package manifests plus README/CHANGELOG release references before publication.

Previous patch fixes (0.28.2)

• PHP HTML wrapper compatibility — internal orphan cleanup no longer strips external wrapper tokens like THZ_APP_HTML_*, preventing broken restore in client wrappers.
• HTML + keep_keywords flows now humanize properly — THZ_KEYWORD_* / THZ_BRAND_* placeholders are treated as inline-safe, so structure/naturalization stages are not skipped.
• Connector replacement after protected tags — connector rewrites now work even when a line starts with inline placeholders.
• Ukrainian naturalization hardening — added dedicated uk replacements/boosters and removed English fallback for non-English naturalization to avoid mixed-language artifacts.

Previous highlights (0.28.0)

Web Platform — Auth, Payments & Freemium (NEW)

• User registration with email/password + Google OAuth 2.0
• Multi-tier pricing — Free / Starter $29 / Pro $79 / Business $199/month
• API key management — create, revoke, and group keys per plan (1 / 5 / 20 keys)
• Monobank Acquiring payment integration with webhook activation
• Admin panel — user management, plan overrides, payment history, usage stats
• Freemium gates — guests limited to 3 requests/day; text results blurred after 500 chars
• API authentication — Bearer token support with session-based guest quota tracking
• Expanded API docs — authentication guide, per-plan rate limits, PAYG billing docs, error codes (401/429)
• Competitor comparison table added to Pricing page (vs Quillbot, Undetectable.ai, StealthGPT)

SentenceValidator™ — Interstage Quality Gate (v0.28.0)

• sentence_validator.py (350 lines) — sentence-level artifact detection running at 7 checkpoints between pipeline stages
• 10 artifact checks per sentence: duplicate words, broken contractions, orphaned punctuation, double conjunctions, dangling conjunctions, unterminated parens, triple+ repeats, fragment chains, conjunction chains, empty sentences
• Final sanitization in run() method catches post-loop residual artifacts

Stats

• 2,105 tests · 122 modules · 235,000+ lines · 25 languages · 38-stage pipeline

🤝 Contributing

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

Areas for contribution: New language packs · Improved synonym dictionaries · Better grammar rules · Performance optimizations · Additional integrations

Starter tasks with acceptance criteria are listed in the Good First Issues guide.

See CONTRIBUTORS.md for the full list of contributors.

⚠️ Limitations

TextHumanize is a style normalization tool. Please be aware of realistic expectations:

What TextHumanize does well:

• ✅ Removes formulaic connectors ("furthermore", "it is important to note")
• ✅ Varies sentence length to add human-like burstiness
• ✅ Replaces bureaucratic vocabulary with simpler alternatives
• ✅ Deterministic, reproducible results with seed control
• ✅ 100% offline, no data leaks, zero dependencies
• ✅ Full audit trail with every call

What TextHumanize does NOT do:

• ❌ Guarantee passing external AI detectors (GPTZero, Originality.ai, Turnitin)
• ❌ Rewrite text at the semantic level (it's rule-based, not LLM-based)
• ❌ Handle domain-specific jargon (medical, legal, etc.) without custom dictionaries

💛 Support the Project

If TextHumanize saves you time or money, consider supporting development:

📄 License & Pricing

TextHumanize uses a dual license model:

All commercial licenses include full source code, all updates, priority email support, and access to PHANTOM™ + ASH™ proprietary technologies. 100% offline — no data leaves your server, no per-request fees, no cloud lock-in. Monthly billing, cancel any time.

[email protected]