stylometric-transfer

Stylometric profiling + controllable author-style transfer for personal writing

stylometric-transfer constructs an explicit, interpretable stylometric style profile from an author’s corpus, then applies that profile to rewrite or generate new text in the same voice.

In practical terms, the system enables an LLM to apply a specified writing style to any text input. It performs stylometric profiling and humanization on writing samples, then uses constraint-guided author-style transfer for a target document. A style "fingerprint" is built from the writing corpus using classic stylometric measurements and graph structure, and that fingerprint is applied via an LLM to rewrite any text.

Unlike fine-tuning or opaque embeddings, the system uses an explicit, versionable JSON style model that can be inspected, edited, audited, and reused. A humanization-aware conflict-resolution layer integrates humanizer guidelines directly into the rewrite step, without violating the fingerprint’s style constraints.

This repository includes:

• fingerprint_style.py: extracts a style fingerprint (stylometric profile) from a writing archive
• apply_fingerprint.py: rewrites Markdown to match the fingerprint
• fingerprint_api.py: local HTTP API exposing make, apply, rate, and similarity methods
• fingerprint_api_harness.py: GUI demo harness for calling API endpoints
• show_fingerprint.py: generates a standalone HTML dashboard for a fingerprint JSON
• common.py: shared path/config/store/probability helpers used across entry points
• prompts.json: externalized prompt templates used by both scripts (edit here to adjust behaviour)
• api/swagger/openapi.yaml and api/swagger/openapi.json: API specifications
• scripts/: bash wrappers for invoking the Python entry points (including fingerprint_api_harness.sh)

Further details are available in Article-Teaching-Machines-to-Write-Like-You.md and Research-Paper.md.

Comments/contributions are encouraged and appreciated.

---

License

PolyForm Noncommercial License 1.0.0. This project is licensed under the PolyForm Noncommercial License 1.0.0 (see LICENSE.md).

Key points:

• Noncommercial only: Use, modification, and redistribution are permitted for noncommercial purposes.
• Commercial use requires permission: Any commercial use (including paid products or services incorporating this code) requires explicit permission from the author.
• Attribution required: Redistribution or use of substantial portions of this project must include clear credit and preserve the license/notice requirements described in LICENSE.md.

For commercial use, contact the author to discuss potential participation and/or licensing.

---

<p align="center"> <img src="media/fingerprint-example.png" width="800"> <br/> <em>An example fingerprint (output from show_fingerprint.py)</em> </p>

---

Table of Contents

• Overview
• Concepts & Terminology
• Features
• Architecture
• Installation
• Configuration
• Usage
  • 1. Build a Style Fingerprint
  • 2. Apply a Fingerprint
  • 3. Local HTTP API
  • 4. API GUI Harness
• Output Files
• Testing
• Style Model Schema
• Ethics & Intended Use
• Roadmap
• References

---

Overview

The project implements a two-stage pipeline:

1. Stylometric profiling
   Quantitative analysis of an author’s corpus to construct a structured style fingerprint (JSON)

2. Author-conditioned style transfer
   Rewriting new text to conform to that fingerprint while preserving meaning

The system integrates:

• Local statistical measurement (sentence length, punctuation rates, paragraph structure, etc.)
• LLM-based synthesis into an explicit style model
• Constraint-driven rewriting using that model

This is a practical implementation of:

Stylometric profiling + controlled author-style transfer

---

Concepts & Terminology

| Term | Meaning | |------|---------| | Stylometry | Quantitative analysis of writing style (measurable signals, not semantics). | | Stylometric profile | A feature-based summary of an author’s style derived from a corpus. | | Style fingerprint | The explicit JSON artifact that encodes style measurements, targets, and controls. | | Style transfer | Rewriting text to match a fingerprint while preserving meaning. | | Author‑conditioned generation | Generating new text guided by a fingerprint rather than a raw prompt alone. | | Measurements | Observed statistics from the corpus (e.g., sentence length histograms, punctuation rates). | | Targets | Desired ranges or qualitative goals derived from measurements (used in rewriting). | | Lexicon | Preferred/avoided words and phrases; soft or hard constraints. | | Templates | Rhetorical or syntactic patterns (openers, transitions, paragraph moves). | | Controls | Priority/strictness and rewrite policies that govern tradeoffs. | | Validators | Checks and weights used to score compliance or detect deviations. | | Deviations | Structured report of where the model could not comply or had to adjust. | | Control normalization | Deterministic de‑duplication of rewrite_policy clauses and token filtering for priority_order. | | Humanizer rules | General guidelines (from general-guidelines.md) filtered for conflicts with the fingerprint. | | Tunables | Runtime configuration (config.tunables.json) that shapes filtering, retries, chunking, and metrics. | | Entity blacklist | Names/places/orgs list used to suppress proper‑name phrases during phrase validation. | | Lexical avoidance list | Common words the author rarely uses (treated as soft avoids). | | Fiction vs non‑fiction | Classification that determines whether multi‑word quotes are rewritten or preserved. | | Chunking | Splitting large inputs to fit the model context, then reconciling outputs. | | Style retry | Optional delta‑feedback loop that re‑prompts if compliance score is low. | | Humanization metrics | Quantitative, research‑grounded signals used to score “human‑likeness.” |

In research terms, the system performs:

• Feature-based stylometric profiling from real corpus statistics
• Interpretable, constraint‑driven rewriting/generation
• Conflict‑aware humanization aligned with explicit style constraints

---

Features

• Accepts .zip / .tar* archives of writing corpora
• Reads .txt, .md, .rst, .html, .docx (via python-docx)
• Computes statistical measurements locally:
  • Sentence length distributions
  • Paragraph structure
  • Punctuation rates
  • Contraction and dash usage
  • US vs Canadian spelling heuristic (English-only)
  • Common n-grams
  • Function-word profile and stance signals (hedging/boosting/pronouns)
  • Sentence-opener and transition templates (top patterns)
  • Rare-word signals (words the author rarely uses)
  • One-sentence paragraph rate / paragraph rhythm
  • Rhetorical move rates (claim/evidence/counterpoint/concession/synthesis)
  • Paragraph cadence (opening/closing sentence length stats)
  • Epistemic stance bands (speculative/probabilistic/assertive/directive)
  • Syntax texture (subordinate/parenthetical/appositive rates)
  • Discourse marker positions (start vs mid-sentence)
  • Repetition signals (bigram/trigram repeat rates)
• Produces a comprehensive JSON style profile
• Rewrites Markdown with:
  • Meaning preservation
  • Structural fidelity
  • Deviation reporting
  • Optional style-compliance retry with delta feedback
  • Deterministic normalization of verbose rewrite policies and noisy priority orders before use
• Filters out blockquotes, reference sections, footnotes, citation markers, and boilerplate notices (copyright/terms/privacy) from style measurements and excerpts, preserving them verbatim during rewrite
• Strips embedded BASE64 images before sending prompts to the LLM and re-embeds them in output
• Exposes a local HTTP API (make/apply/rate) backed by GUID-tracked fingerprint files
  • Includes a fingerprint-to-fingerprint similarity method for profile comparison diagnostics
• Compatible with OpenAI (works with OpenAI, Azure OpenAI, vLLM, etc.)
• Interpretable, editable, versionable style models

---

Architecture

corpus.tar.gz
      │
      ▼
[fingerprint_style.py]
      │
      ├─ local statistical analysis
      ├─ representative excerpts
      └─ LLM synthesis
      │
      ▼
style_fingerprint.json
      │
      ▼
[apply_fingerprint.py]
      │
      ├─ local measurement of input
      ├─ constraint-driven rewriting
      └─ deviation audit
      │
      ▼
rewritten_text.styled.md

HTTP text
      │
      ▼
[fingerprint_api.py]
      │
      ├─ POST /make  -> fingerprint_style.py + GUID store
      ├─ POST /apply -> apply_fingerprint.py
      └─ POST /rate  -> local probabilistic style scoring
         POST /similarity -> local fingerprint similarity scoring

---

Installation

Requirements

• Python 3.9+
• requests
• python-docx (optional, for .docx corpora)

pip install requests python-docx

---

Configuration

Create config.llm.json in the project root (used by default):

{
  "api_key": "YOUR_OPENAI_KEY",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4.1-mini",
  "max_tokens": 6000,
  "max_prompt_tokens": 6000,
  "temperature": 0.2,
  "timeout_seconds": 300,
  "max_retries": 6,
  "backoff_base_seconds": 2.0,
  "backoff_max_seconds": 20.0
}

Notes:

• Default lookup for config.llm.json: current working directory first, then the directory containing the Python scripts
• Optional config.llm.roster.json (same lookup path) de