Rewrite AI-generated text so it reads as human-authored.

Runs the configured pipeline of passes (preprocess, surface-tell substitution, watermark scrub, stylometric smoothing, optional paraphrase passes; see docs/ARCHITECTURE.md) and returns the final text. For diagnostic output (per-pass diff, before/after detector scores) use :func:humanize_and_verify instead.

Locate AI writing tells in the input text.

Reports surface signatures catalogued in research/02_ai_tells_catalog.md: excess vocabulary (the "delve" cluster), em-dash overuse, sentence-initial discourse markers, copular templates, conversational scaffolding, and parallel-structure overuse. Each tell carries a 1-indexed line number, character offsets, a 1-to-5 severity, and an optional substitution suggestion.

The intended use is diagnostic: surface what would be edited by :func:humanize so a writer can decide which tells to preserve and which to remove.

Score how AI-like the text reads to one or more open detectors.

Wraps the local detector adapters in benchmark/. The default detector list is ["roberta-base"] (the canonical academic baseline; see research/01_detector_landscape.md). Other adapters such as "fast_detect_gpt" and "binoculars" are added as the benchmark package matures.

Aggregate probability is the arithmetic mean of detector scores that returned successfully. If every detector failed, aggregate is -1.0 and the verdict is "unknown".

Apply a style preset to text without running humanization passes.

Useful when the caller wants pure register translation (formal to casual, academic to blog, etc.) without removing AI tells. The set of legal style names is whatever :func:list_styles returns.

List the names of all currently registered style presets.

Style presets are loaded from the styles/ package. If the package is unavailable an empty list is returned.

Returns

list of str Sorted list of preset names, e.g. ["academic", "blog", "casual", "esl", "neurodivergent", "preserve"].

Humanize, then iterate against detectors until a target score is met.

v0.2.0 (Bet 3): wraps :class:pipelines.IterativeHumanizer, which implements the Cheng et al. 2025 detector-guided loop (research/04 section 1.3). Each iteration:

1. Locates the worst-scoring paragraph in the current text.

2. Generates candidates_per_iteration stochastic paraphrase candidates of that paragraph (via ParaphrasePass.paraphrase_candidates).

3. Scores each candidate, keeps the lowest, splices it back in.

4. Re-scores the whole text. If at or below target_ai_score, returns.

This replaces the v0.1.0 loop, which re-ran the deterministic 9-pass pipeline at ramped intensities. As documented in docs/REVIEW_v0.1.0.md section 2.9, every pass except 9-heavy is idempotent on its own output, so iterations 2-3 of the old loop did no work. The new loop is meaningfully different because it depends on stochastic candidate generation: only non-deterministic search can converge on a lower score after a deterministic fixed point.

The function always returns a result, even if the target was not reached; callers should check target_reached to know.