k-uncanny 0.1.1__tar.gz

k_uncanny-0.1.1/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: k-uncanny
+Version: 0.1.1
+Summary: CLI tool that detects AI-generated text with sentence-level scoring and multiple detection strategies
+Keywords: ai-detection,gpt,llm,text-analysis,cli
+Author: Frank Chan
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
+Requires-Dist: torch>=2.0 ; extra == 'ml'
+Requires-Dist: transformers>=4.30 ; extra == 'ml'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/kpihx-labs/uncanny
+Project-URL: Repository, https://github.com/kpihx-labs/uncanny
+Project-URL: Upstream, https://github.com/dunkinfrunkin/uncanny
+Project-URL: Issues, https://github.com/kpihx-labs/uncanny/issues
+Provides-Extra: dev
+Provides-Extra: ml
+Description-Content-Type: text/markdown
+
+# Uncanny
+
+## KpihX-Labs distribution
+
+This MIT-licensed adaptation retains Frank Chan's upstream implementation and history.
+Upstream: https://github.com/dunkinfrunkin/uncanny.
+The PyPI distribution is `k-uncanny`; the executable and Python import remain `uncanny`.
+Install with `uv tool install k-uncanny`, or use `make uv-link` from this checkout.
+Run `uncanny scan document.txt --format json` for structured output on stdout.
+Use `make check`, `make uv-build`, `make uv-publish`, and `make push`.
+`make puhsb` is an alias for `make push`, which pushes the current branch to both
+`github` and `gitlab`, never to `upstream`.
+This detector produces heuristic scores, not calibrated authorship probabilities.
+No score proves who wrote a document or whether plagiarism occurred.
+
+The remaining documentation describes the upstream tool. Install instructions naming
+the upstream PyPI package do not install this KpihX-Labs distribution.
+
+**Detect AI-generated text from your terminal.** Sentence-level scoring, multiple detection strategies, zero API calls. Runs locally, works offline.
+
+```
+$ uncanny scan proposal.md
+
+  Uncanny Analysis — proposal.md
+  ─────────────────────────────────────────────────
+
+  Overall Score: 0.73 (likely AI-generated)
+
+  ██████████████████████░░░░░░░░  73% AI probability
+
+  Sentence Breakdown:
+   0.91 │ The implementation of this feature requires careful
+        │ consideration of several architectural patterns.
+   0.42 │ I tried like three different approaches before
+        │ landing on this one, honestly.
+   0.88 │ By leveraging the existing infrastructure, we can
+        │ ensure seamless integration with minimal overhead.
+
+  Legend: ■ 0.8+ AI  ■ 0.5-0.8 mixed  ■ <0.5 human
+```
+
+## Why Uncanny?
+
+Every other AI detector is a SaaS that sends your text to someone else's server. Uncanny runs **entirely on your machine**. No API keys, no subscriptions, no data leaving your network.
+
+| Tool | Open Source | Offline | Sentence-level | Multi-method | CLI |
+|------|:----------:|:-------:|:--------------:|:------------:|:---:|
+| GPTZero | | | x | x | |
+| Originality.ai | | | x | x | |
+| Copyleaks | | | x | x | |
+| Sapling | | | x | | |
+| Zippy | x | x | | | x |
+| **Uncanny** | **x** | **x** | **x** | **x** | **x** |
+
+## Benchmarks
+
+Tested against 36 labeled samples (18 AI-generated, 18 human-written) across diverse genres: academic papers, Slack messages, code reviews, personal essays, Reddit posts, cover letters, tweets, and more.
+
+| Metric | Uncanny | Zippy | Random Baseline |
+|--------|:-------:|:-----:|:---------------:|
+| **Overall Accuracy** | **91.7%** | 80.6% | 50.0% |
+| AI Detected (true positive) | 88.9% | 100% | 100% |
+| Human Cleared (true negative) | **94.4%** | 61.1% | 0% |
+| **False Accusation Rate** | **5.6%** | 38.9% | 100% |
+| Speed (per sample) | 8ms | 1ms | 0ms |
+
+**Uncanny beats Zippy by 11 points on accuracy.** Zippy catches everything but wrongly flags 39% of human text as AI — that means 2 out of 5 human writers get falsely accused. Uncanny's false positive rate is 7x lower.
+
+> Run the benchmarks yourself: `uncanny bench --compare`
+
+### How we test
+
+The corpus includes adversarial cases:
+
+- **Casual AI** — LLM output prompted to sound informal ("Hey! So basically...")
+- **Formal humans** — Academic writing, technical docs, polished prose
+- **Short text** — 2-3 sentence samples where signal is weakest
+- **Edge cases** — LinkedIn posts, PR descriptions, commit messages, debug notes
+
+Accuracy is enforced in CI. Every PR must pass `test_bench.py` which gates on:
+- Overall accuracy >= 70%
+- False positive rate < 20%
+- Score separation > 0.10
+
+## Install
+
+```bash
+pip install uncanny
+```
+
+Or with Homebrew:
+
+```bash
+brew tap dunkinfrunkin/tap
+brew install uncanny
+```
+
+For ML-based analyzers (perplexity):
+
+```bash
+pip install "uncanny[ml]"
+```
+
+## Usage
+
+```bash
+# Scan a file
+uncanny scan report.md
+
+# Scan from stdin
+cat essay.txt | uncanny scan
+
+# Scan a string directly
+uncanny scan --text "The implementation of this feature..."
+
+# Output formats
+uncanny scan report.md --format json      # structured JSON
+uncanny scan report.md --format summary   # just the score
+
+# Speed vs depth
+uncanny scan report.md --fast             # compression only (~instant)
+uncanny scan report.md --deep             # all analyzers (requires uncanny[ml])
+uncanny scan report.md --analyzers compression,burstiness
+
+# CI integration — exit code 1 if score exceeds threshold
+uncanny scan report.md --threshold 0.7
+
+# Benchmarks
+uncanny bench                             # run accuracy benchmarks
+uncanny bench --compare                   # head-to-head vs competitors
+uncanny bench --compare --json            # machine-readable output
+```
+
+### JSON Output
+
+```json
+{
+  "source": "proposal.md",
+  "score": 0.73,
+  "label": "likely_ai",
+  "analyzers": {
+    "compression": { "score": 0.81, "method": "lzma+zlib" },
+    "burstiness": { "score": 0.71, "variance": 0.003 }
+  },
+  "sentences": [
+    {
+      "text": "The implementation of this feature requires...",
+      "score": 0.91,
+      "offset": { "start": 0, "end": 89 }
+    }
+  ]
+}
+```
+
+## How It Works
+
+Uncanny combines multiple detection strategies through an **ensemble scorer** with dynamic weighting:
+
+### Compression Analysis (primary signal)
+AI text is statistically predictable — it compresses better than human text. Uncanny cross-compresses your text against both an AI-generated prelude and a human-written prelude using LZMA and zlib. If your text shares compression patterns with the AI prelude, it scores higher. This is the fastest method (no model needed) and the most reliable single signal.
+
+### Burstiness Analysis (tiebreaker)
+Humans write with natural variation — short sentences mixed with long ones, simple ideas next to complex ones. AI text is uniformly smooth. Uncanny measures the variance in compression ratio and sentence length across a document. Low variance = AI-like uniformity. This signal gets dynamically weighted — it matters most when compression is ambiguous.
+
+### Perplexity Analysis (optional, requires `uncanny[ml]`)
+Measures how "surprised" GPT-2 is by each sentence. AI-generated text has low perplexity (the model predicted it easily). Human text has high perplexity (surprising word choices). Requires downloading a ~500MB model.
+
+### Ensemble Scoring
+Analyzers are combined with **confidence-aware dynamic weighting**. When compression is decisive (far from 0.5), it dominates. When compression is ambiguous, burstiness gets more influence. This avoids the classic problem of a weak signal overriding a strong one.
+
+## Design Principles
+
+1. **Offline-first** — No API calls. Everything runs locally. Models downloaded once.
+2. **Fast by default** — Default mode uses compression + burstiness (~8ms/sample). No model download needed.
+3. **Scores, not verdicts** — Uncanny reports probabilities, never binary "AI or human" labels. The tool informs, it doesn't judge.
+4. **Sentence-level granularity** — Not just "this doc is AI" — shows exactly which sentences triggered detection.
+5. **CI-friendly** — `--threshold` flag with exit codes. JSON output for parsing. Benchmarks in CI.
+
+## Limitations
+
+AI detection is an imperfect science. Be honest about it:
+
+- **No detector is 100% accurate.** False positives and false negatives happen.
+- **Short text is unreliable.** Confidence drops below ~250 words.
+- **Edited AI text is harder to detect.** A human editing AI output blurs the signal.
+- **Newer models are harder to detect.** As LLMs improve, statistical signals narrow.
+- **Technical writing may false-positive.** Formal, structured text can look AI-like.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome — especially new analyzers, corpus samples, and accuracy improvements.
+
+## License
+
+MIT

k_uncanny-0.1.1/README.md

@@ -0,0 +1,195 @@
+# Uncanny
+
+## KpihX-Labs distribution
+
+This MIT-licensed adaptation retains Frank Chan's upstream implementation and history.
+Upstream: https://github.com/dunkinfrunkin/uncanny.
+The PyPI distribution is `k-uncanny`; the executable and Python import remain `uncanny`.
+Install with `uv tool install k-uncanny`, or use `make uv-link` from this checkout.
+Run `uncanny scan document.txt --format json` for structured output on stdout.
+Use `make check`, `make uv-build`, `make uv-publish`, and `make push`.
+`make puhsb` is an alias for `make push`, which pushes the current branch to both
+`github` and `gitlab`, never to `upstream`.
+This detector produces heuristic scores, not calibrated authorship probabilities.
+No score proves who wrote a document or whether plagiarism occurred.
+
+The remaining documentation describes the upstream tool. Install instructions naming
+the upstream PyPI package do not install this KpihX-Labs distribution.
+
+**Detect AI-generated text from your terminal.** Sentence-level scoring, multiple detection strategies, zero API calls. Runs locally, works offline.
+
+```
+$ uncanny scan proposal.md
+
+  Uncanny Analysis — proposal.md
+  ─────────────────────────────────────────────────
+
+  Overall Score: 0.73 (likely AI-generated)
+
+  ██████████████████████░░░░░░░░  73% AI probability
+
+  Sentence Breakdown:
+   0.91 │ The implementation of this feature requires careful
+        │ consideration of several architectural patterns.
+   0.42 │ I tried like three different approaches before
+        │ landing on this one, honestly.
+   0.88 │ By leveraging the existing infrastructure, we can
+        │ ensure seamless integration with minimal overhead.
+
+  Legend: ■ 0.8+ AI  ■ 0.5-0.8 mixed  ■ <0.5 human
+```
+
+## Why Uncanny?
+
+Every other AI detector is a SaaS that sends your text to someone else's server. Uncanny runs **entirely on your machine**. No API keys, no subscriptions, no data leaving your network.
+
+| Tool | Open Source | Offline | Sentence-level | Multi-method | CLI |
+|------|:----------:|:-------:|:--------------:|:------------:|:---:|
+| GPTZero | | | x | x | |
+| Originality.ai | | | x | x | |
+| Copyleaks | | | x | x | |
+| Sapling | | | x | | |
+| Zippy | x | x | | | x |
+| **Uncanny** | **x** | **x** | **x** | **x** | **x** |
+
+## Benchmarks
+
+Tested against 36 labeled samples (18 AI-generated, 18 human-written) across diverse genres: academic papers, Slack messages, code reviews, personal essays, Reddit posts, cover letters, tweets, and more.
+
+| Metric | Uncanny | Zippy | Random Baseline |
+|--------|:-------:|:-----:|:---------------:|
+| **Overall Accuracy** | **91.7%** | 80.6% | 50.0% |
+| AI Detected (true positive) | 88.9% | 100% | 100% |
+| Human Cleared (true negative) | **94.4%** | 61.1% | 0% |
+| **False Accusation Rate** | **5.6%** | 38.9% | 100% |
+| Speed (per sample) | 8ms | 1ms | 0ms |
+
+**Uncanny beats Zippy by 11 points on accuracy.** Zippy catches everything but wrongly flags 39% of human text as AI — that means 2 out of 5 human writers get falsely accused. Uncanny's false positive rate is 7x lower.
+
+> Run the benchmarks yourself: `uncanny bench --compare`
+
+### How we test
+
+The corpus includes adversarial cases:
+
+- **Casual AI** — LLM output prompted to sound informal ("Hey! So basically...")
+- **Formal humans** — Academic writing, technical docs, polished prose
+- **Short text** — 2-3 sentence samples where signal is weakest
+- **Edge cases** — LinkedIn posts, PR descriptions, commit messages, debug notes
+
+Accuracy is enforced in CI. Every PR must pass `test_bench.py` which gates on:
+- Overall accuracy >= 70%
+- False positive rate < 20%
+- Score separation > 0.10
+
+## Install
+
+```bash
+pip install uncanny
+```
+
+Or with Homebrew:
+
+```bash
+brew tap dunkinfrunkin/tap
+brew install uncanny
+```
+
+For ML-based analyzers (perplexity):
+
+```bash
+pip install "uncanny[ml]"
+```
+
+## Usage
+
+```bash
+# Scan a file
+uncanny scan report.md
+
+# Scan from stdin
+cat essay.txt | uncanny scan
+
+# Scan a string directly
+uncanny scan --text "The implementation of this feature..."
+
+# Output formats
+uncanny scan report.md --format json      # structured JSON
+uncanny scan report.md --format summary   # just the score
+
+# Speed vs depth
+uncanny scan report.md --fast             # compression only (~instant)
+uncanny scan report.md --deep             # all analyzers (requires uncanny[ml])
+uncanny scan report.md --analyzers compression,burstiness
+
+# CI integration — exit code 1 if score exceeds threshold
+uncanny scan report.md --threshold 0.7
+
+# Benchmarks
+uncanny bench                             # run accuracy benchmarks
+uncanny bench --compare                   # head-to-head vs competitors
+uncanny bench --compare --json            # machine-readable output
+```
+
+### JSON Output
+
+```json
+{
+  "source": "proposal.md",
+  "score": 0.73,
+  "label": "likely_ai",
+  "analyzers": {
+    "compression": { "score": 0.81, "method": "lzma+zlib" },
+    "burstiness": { "score": 0.71, "variance": 0.003 }
+  },
+  "sentences": [
+    {
+      "text": "The implementation of this feature requires...",
+      "score": 0.91,
+      "offset": { "start": 0, "end": 89 }
+    }
+  ]
+}
+```
+
+## How It Works
+
+Uncanny combines multiple detection strategies through an **ensemble scorer** with dynamic weighting:
+
+### Compression Analysis (primary signal)
+AI text is statistically predictable — it compresses better than human text. Uncanny cross-compresses your text against both an AI-generated prelude and a human-written prelude using LZMA and zlib. If your text shares compression patterns with the AI prelude, it scores higher. This is the fastest method (no model needed) and the most reliable single signal.
+
+### Burstiness Analysis (tiebreaker)
+Humans write with natural variation — short sentences mixed with long ones, simple ideas next to complex ones. AI text is uniformly smooth. Uncanny measures the variance in compression ratio and sentence length across a document. Low variance = AI-like uniformity. This signal gets dynamically weighted — it matters most when compression is ambiguous.
+
+### Perplexity Analysis (optional, requires `uncanny[ml]`)
+Measures how "surprised" GPT-2 is by each sentence. AI-generated text has low perplexity (the model predicted it easily). Human text has high perplexity (surprising word choices). Requires downloading a ~500MB model.
+
+### Ensemble Scoring
+Analyzers are combined with **confidence-aware dynamic weighting**. When compression is decisive (far from 0.5), it dominates. When compression is ambiguous, burstiness gets more influence. This avoids the classic problem of a weak signal overriding a strong one.
+
+## Design Principles
+
+1. **Offline-first** — No API calls. Everything runs locally. Models downloaded once.
+2. **Fast by default** — Default mode uses compression + burstiness (~8ms/sample). No model download needed.
+3. **Scores, not verdicts** — Uncanny reports probabilities, never binary "AI or human" labels. The tool informs, it doesn't judge.
+4. **Sentence-level granularity** — Not just "this doc is AI" — shows exactly which sentences triggered detection.
+5. **CI-friendly** — `--threshold` flag with exit codes. JSON output for parsing. Benchmarks in CI.
+
+## Limitations
+
+AI detection is an imperfect science. Be honest about it:
+
+- **No detector is 100% accurate.** False positives and false negatives happen.
+- **Short text is unreliable.** Confidence drops below ~250 words.
+- **Edited AI text is harder to detect.** A human editing AI output blurs the signal.
+- **Newer models are harder to detect.** As LLMs improve, statistical signals narrow.
+- **Technical writing may false-positive.** Formal, structured text can look AI-like.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome — especially new analyzers, corpus samples, and accuracy improvements.
+
+## License
+
+MIT

k_uncanny-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["uv_build>=0.10.3,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "k-uncanny"
+version = "0.1.1"
+description = "CLI tool that detects AI-generated text with sentence-level scoring and multiple detection strategies"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Frank Chan" }]
+urls = { Homepage = "https://github.com/kpihx-labs/uncanny", Repository = "https://github.com/kpihx-labs/uncanny", Upstream = "https://github.com/dunkinfrunkin/uncanny", Issues = "https://github.com/kpihx-labs/uncanny/issues" }
+keywords = ["ai-detection", "gpt", "llm", "text-analysis", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "typer>=0.9",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+ml = [
+    "torch>=2.0",
+    "transformers>=4.30",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.scripts]
+uncanny = "uncanny.cli:app"
+
+[tool.uv.build-backend]
+module-name = "uncanny"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

k_uncanny-0.1.1/src/uncanny/__init__.py

@@ -0,0 +1,5 @@
+"""Uncanny - AI text detection CLI with sentence-level scoring."""
+
+from importlib.metadata import version
+
+__version__ = version("k-uncanny")

k_uncanny-0.1.1/src/uncanny/__init__.py~

@@ -0,0 +1,3 @@
+# """Uncanny - AI text detection CLI with sentence-level scoring."""
+#
+# __version__ = "0.1.0"

k_uncanny-0.1.1/src/uncanny/__main__.py

@@ -0,0 +1,3 @@
+from uncanny.cli import app
+
+app()

k_uncanny-0.1.1/src/uncanny/analyzers/__init__.py

@@ -0,0 +1,13 @@
+from uncanny.analyzers.base import Analyzer
+from uncanny.analyzers.compression import CompressionAnalyzer
+from uncanny.analyzers.burstiness import BurstinessAnalyzer
+
+__all__ = ["Analyzer", "CompressionAnalyzer", "BurstinessAnalyzer"]
+
+# Perplexity analyzer requires optional ML dependencies
+try:
+    from uncanny.analyzers.perplexity import PerplexityAnalyzer  # noqa: F401
+
+    __all__.append("PerplexityAnalyzer")
+except ImportError:
+    pass

k_uncanny-0.1.1/src/uncanny/analyzers/base.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from uncanny.types import AnalyzerResult
+
+
+class Analyzer(ABC):
+    """Base class for all detection analyzers."""
+
+    name: str
+
+    @abstractmethod
+    def analyze(self, text: str) -> AnalyzerResult:
+        """Analyze text and return a result with overall + sentence scores."""
+        ...

k_uncanny-0.1.1/src/uncanny/analyzers/burstiness.py

@@ -0,0 +1,121 @@
+"""
+Burstiness-based AI detection.
+
+Measures variance in sentence complexity across a document.
+Humans write with natural variation (short/long sentences, simple/complex ideas).
+AI text is uniformly smooth.
+
+Uses zlib compression ratio per-sentence as a proxy for complexity.
+"""
+
+from __future__ import annotations
+
+import math
+import zlib
+
+from uncanny.analyzers.base import Analyzer
+from uncanny.tokenizer import split_sentences
+from uncanny.types import AnalyzerResult, SentenceScore
+
+
+def _compress_ratio(data: bytes) -> float:
+    """Compression ratio using zlib."""
+    if len(data) == 0:
+        return 1.0
+    return len(zlib.compress(data, level=6)) / len(data)
+
+
+def _variance(values: list[float]) -> float:
+    if len(values) < 2:
+        return 0.0
+    mean = sum(values) / len(values)
+    return sum((v - mean) ** 2 for v in values) / (len(values) - 1)
+
+
+def _burstiness_to_score(variance: float, length_cv: float) -> float:
+    """Convert burstiness metrics to AI probability score.
+
+    Low variance + low length CV = uniform = AI-like = high score.
+    High variance + high length CV = bursty = human-like = low score.
+
+    Calibrated from corpus:
+      AI:    ratio_var mean=0.020, length_cv mean=0.41
+      Human: ratio_var mean=0.041, length_cv mean=0.62
+    """
+    # Compression ratio variance signal
+    # AI: 0.001-0.070, mean 0.020. Human: 0.003-0.079, mean 0.041.
+    # Use sigmoid centered around 0.030 (midpoint)
+    rv_centered = (variance - 0.030) * 60.0
+    ratio_signal = 1.0 / (1.0 + math.exp(rv_centered))
+
+    # Sentence length CV signal
+    # AI: 0.17-1.12, mean 0.41. Human: 0.22-0.89, mean 0.62.
+    # Use sigmoid centered around 0.50 (midpoint)
+    lcv_centered = (length_cv - 0.50) * 4.0
+    length_signal = 1.0 / (1.0 + math.exp(lcv_centered))
+
+    return 0.55 * ratio_signal + 0.45 * length_signal
+
+
+class BurstinessAnalyzer(Analyzer):
+    """Detects AI text by measuring uniformity of sentence complexity."""
+
+    name = "burstiness"
+
+    def analyze(self, text: str) -> AnalyzerResult:
+        sentences = split_sentences(text)
+
+        if len(sentences) < 3:
+            return AnalyzerResult(
+                name=self.name,
+                score=0.5,
+                sentence_scores=[
+                    SentenceScore(s, 0.5, start, end) for s, start, end in sentences
+                ],
+                metadata={"variance": 0.0, "note": "too few sentences"},
+            )
+
+        # Compression ratio per sentence as complexity proxy
+        ratios: list[float] = []
+        for sent_text, _, _ in sentences:
+            if len(sent_text.strip()) < 10:
+                continue
+            ratios.append(_compress_ratio(sent_text.encode("utf-8")))
+
+        if len(ratios) < 3:
+            return AnalyzerResult(
+                name=self.name,
+                score=0.5,
+                sentence_scores=[
+                    SentenceScore(s, 0.5, start, end) for s, start, end in sentences
+                ],
+                metadata={"variance": 0.0, "note": "too few analyzable sentences"},
+            )
+
+        # Sentence length variance
+        lengths = [len(s.split()) for s, _, _ in sentences]
+        mean_length = sum(lengths) / len(lengths)
+        length_cv = math.sqrt(_variance(lengths)) / max(mean_length, 1)
+
+        ratio_var = _variance(ratios)
+        overall_score = _burstiness_to_score(ratio_var, length_cv)
+
+        # Per-sentence: deviation from mean indicates human-like variety
+        mean_ratio = sum(ratios) / len(ratios)
+        sentence_scores: list[SentenceScore] = []
+        ratio_idx = 0
+        for sent_text, start, end in sentences:
+            if len(sent_text.strip()) < 10:
+                sentence_scores.append(SentenceScore(sent_text, 0.5, start, end))
+                continue
+            deviation = abs(ratios[ratio_idx] - mean_ratio)
+            sent_score = max(0.0, min(1.0, 1.0 - deviation * 15))
+            sentence_scores.append(SentenceScore(sent_text, sent_score, start, end))
+            ratio_idx += 1
+
+        return AnalyzerResult(
+            name=self.name,
+            score=overall_score,
+            sentence_scores=sentence_scores,
+            metadata={"variance": round(ratio_var, 6), "length_cv": round(length_cv, 3)},
+        )