ductus 0.0.2__tar.gz

ductus-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Permissions: the reusable workflow needs `contents: write` (version-bump
+# push-back, gh-pages branch push) and `pages: write` (Pages REST config).
+# Both default to read-only on personal-account callers, so they are granted
+# explicitly here.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Explicit pass-through (not `secrets: inherit`, which does not reliably
+    # propagate caller-repo secrets to a reusable workflow owned by a different
+    # account). ductus reads only the text it is given and makes no network calls, so
+    # PYPI_PASSWORD is the only secret it needs.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

ductus-0.0.2/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+.DS_Store
+.claude/handoffs/

ductus-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ductus-0.0.2/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: ductus
+Version: 0.0.2
+Summary: Gauge which parts of a text read as machine-written, and why, with the evidence anchored to exact characters
+Project-URL: Homepage, https://github.com/thorwhalen/ductus
+Project-URL: Repository, https://github.com/thorwhalen/ductus
+Project-URL: Issues, https://github.com/thorwhalen/ductus/issues
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,ai-detection,annotation,authorship,llm,machine-generated-text,mgt,provenance,stylometry,writing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Requires-Dist: cw<0.2,>=0.1.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: api
+Requires-Dist: httpx; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: torch; extra == 'local'
+Requires-Dist: transformers; extra == 'local'
+Description-Content-Type: text/markdown
+
+# ductus
+
+Gauge which parts of a text read as machine-written, and say why — with every finding anchored to the exact characters that carry it.
+
+```python
+from ductus import gauge
+
+report = gauge(open("draft.md").read())
+report.document.label  # 'mixed-signals'
+report.segments[3].lean  # +0.62  (-1 human … +1 machine)
+report.segments[3].signals[0].note
+# "a colon introducing a three-part parallel enumeration -- a textbook assistant construction"
+```
+
+```bash
+pip install ductus
+ductus gauge draft.md                                  # a readable diagnosis
+ductus gauge draft.md --format html --out report.html  # shaded, hover for the reason
+ductus gauge draft.md --format json                    # for a program
+```
+
+In palaeography the *ductus* is the characteristic manner and sequence of strokes by which a scribe's hand is recognised. This package looks for the equivalent in prose.
+
+## There is no percentage in this package, and that is the point
+
+Every detector on the market emits a number like "87% AI". That number reads as a calibrated probability, is not one, and is how people get falsely accused. What you get here instead is three things you can argue with: a **lean** in [-1, +1], an **evidence strength**, and a coarse **label**. Behind each of them is a list of signals, each with a direction, a weight, the detector that produced it, a plain-language reason, and the exact span it came from.
+
+Four things are true and belong in any report you make from this:
+
+- **Heavily-edited human writing and model-assisted writing look the same.** Re-reading a hard message ten times sands off exactly the irregularity that marks it as human.
+- **Detectors over-flag non-native English writers** — 61.3% false positives across seven commercial detectors on non-native TOEFL essays, against near-zero on native-speaker controls [1].
+- **Register contamination is real**: people who read model output all day start writing like it, unassisted.
+- **No detector survives a motivated adversary**, and that is a proven result rather than a gap in current tooling [2].
+
+So this package describes *text*. It does not make claims about *people*, and it should not be used to.
+
+## What it looks at
+
+Four detectors ship, all deterministic, all free, none needing a model or a key.
+
+| Detector | Finds | Example |
+|---|---|---|
+| `tells` | Catalogue phrases models overuse, tiered by confidence | "delve", "it's important to note", "In conclusion," |
+| `forensic` | Mechanical traces of how the text was produced | a hard line break mid-sentence, mixed straight-and-curly apostrophes, trailing whitespace, em-dash density |
+| `rhetoric` | Sentence *shapes* a phrase list cannot see | "not X but Y", a colon introducing a three-part parallel enumeration, concession-then-pivot |
+| `rhythm` | Burstiness — how much sentence length varies | metronomic paragraphs |
+
+Note that several of these argue *for* a human. A detector that can only ever accuse is not a measuring instrument. In practice the mechanical signals are often the most decisive thing in a file, in either direction.
+
+The deterministic pass finds phrases, artifacts and a few shapes. **It cannot find prose that is machine-written and bland** — for that a model has to read it, which is what the shipped agent skills are for.
+
+## Agent skills
+
+The primary surface. Two skills and a subagent ship inside the package and install with one command:
+
+```bash
+ductus install-skills --write          # links them into ~/.claude/skills
+```
+
+- **`ductus`** — what may and may not be claimed from a text, and which task is which.
+- **`ductus-gauge`** — the full reading: the deterministic scan, then a judgment pass with rubrics for the nine machine-leaning and six human-leaning *shapes* that regular expressions miss, then the write-up.
+- **`ductus-reader`** (subagent) — does the whole reading in its own context and returns a finished diagnosis.
+
+An agent's own reading folds back in beside the deterministic signals, anchored by quote:
+
+```bash
+ductus gauge draft.md --judgments judgments.json --format html --out report.html
+```
+
+A quote that no longer occurs is dropped rather than mis-anchored, so re-running after an edit is safe.
+
+## Seams
+
+Three, each one keyword argument, each defaulting to something that genuinely works:
+
+```python
+gauge(text, segmenter="sentence")  # or "paragraph", "document", or a callable
+gauge(
+    text, detectors=["forensic", "rhetoric"]
+)  # or your own (text, span) -> Iterator[Signal]
+gauge(text, aggregate=my_calibrated_scorer)  # replace the scoring model wholesale
+```
+
+A detector is a plain function `(text, span) -> Iterator[Signal]`. There is no base class and nothing to register. Adding Fast-DetectGPT, Binoculars or a vendor API means writing one more function of that shape — see [the roadmap](misc/docs/roadmap.md).
+
+For long documents, `iter_segments` is the streaming core and `gauge` is the batch facade over it.
+
+## Spans survive editing
+
+Every `Span` carries character offsets *and* the W3C Web Annotation redundant selectors (`quote`, `prefix`, `suffix`), because plain offsets do not survive an edit to the text. That is what lets a viewer re-find a finding after the document changed, and what a future edit-and-re-score UI is built on.
+
+## Relationship to `deslop`
+
+`ductus` is the read side: *where does this text read as machine-written, and why*. [`acquaint`](https://github.com/thorwhalen/acquaint)'s `deslop` is the write side: *make my draft not read that way, in my voice, calibrated to this reader*. They share this package's tells catalogue — `acquaint` imports it — and compose naturally: gauge, deslop the flagged spans, gauge again.
+
+They are separate packages because they have different inputs. `deslop` needs a model of the reader; `ductus` must work on a stranger's text with nothing but the text.
+
+## Install
+
+```bash
+pip install ductus              # the core: pyyaml and cw, nothing else
+pip install "ductus[local]"     # + model-based detectors, offline, no API key
+pip install "ductus[api]"       # + vendor detector adapters
+```
+
+## References
+
+[1] [Liang W, Yuksekgonul M, Mao Y, Wu E, Zou J. GPT detectors are biased against non-native English writers. *Patterns* 2023.](https://arxiv.org/abs/2304.02819)
+
+[2] [Sadasivan VS, Kumar A, Balasubramanian S, Wang W, Feizi S. Can AI-Generated Text be Reliably Detected?](https://arxiv.org/abs/2303.11156)
+
+[3] [Sanderson R, Ciccarese P, Young B. Web Annotation Data Model. W3C Recommendation, 2017.](https://www.w3.org/TR/annotation-model/)
+
+[4] [Tolstykh I, et al. LLMTrace: A Corpus for Classification and Fine-Grained Localization of AI-Written Text. arXiv:2509.21269.](https://arxiv.org/abs/2509.21269) — the ground-truth fixture in `tests/fixtures/` is a slice of this, Apache-2.0.

ductus-0.0.2/README.md

@@ -0,0 +1,114 @@
+# ductus
+
+Gauge which parts of a text read as machine-written, and say why — with every finding anchored to the exact characters that carry it.
+
+```python
+from ductus import gauge
+
+report = gauge(open("draft.md").read())
+report.document.label  # 'mixed-signals'
+report.segments[3].lean  # +0.62  (-1 human … +1 machine)
+report.segments[3].signals[0].note
+# "a colon introducing a three-part parallel enumeration -- a textbook assistant construction"
+```
+
+```bash
+pip install ductus
+ductus gauge draft.md                                  # a readable diagnosis
+ductus gauge draft.md --format html --out report.html  # shaded, hover for the reason
+ductus gauge draft.md --format json                    # for a program
+```
+
+In palaeography the *ductus* is the characteristic manner and sequence of strokes by which a scribe's hand is recognised. This package looks for the equivalent in prose.
+
+## There is no percentage in this package, and that is the point
+
+Every detector on the market emits a number like "87% AI". That number reads as a calibrated probability, is not one, and is how people get falsely accused. What you get here instead is three things you can argue with: a **lean** in [-1, +1], an **evidence strength**, and a coarse **label**. Behind each of them is a list of signals, each with a direction, a weight, the detector that produced it, a plain-language reason, and the exact span it came from.
+
+Four things are true and belong in any report you make from this:
+
+- **Heavily-edited human writing and model-assisted writing look the same.** Re-reading a hard message ten times sands off exactly the irregularity that marks it as human.
+- **Detectors over-flag non-native English writers** — 61.3% false positives across seven commercial detectors on non-native TOEFL essays, against near-zero on native-speaker controls [1].
+- **Register contamination is real**: people who read model output all day start writing like it, unassisted.
+- **No detector survives a motivated adversary**, and that is a proven result rather than a gap in current tooling [2].
+
+So this package describes *text*. It does not make claims about *people*, and it should not be used to.
+
+## What it looks at
+
+Four detectors ship, all deterministic, all free, none needing a model or a key.
+
+| Detector | Finds | Example |
+|---|---|---|
+| `tells` | Catalogue phrases models overuse, tiered by confidence | "delve", "it's important to note", "In conclusion," |
+| `forensic` | Mechanical traces of how the text was produced | a hard line break mid-sentence, mixed straight-and-curly apostrophes, trailing whitespace, em-dash density |
+| `rhetoric` | Sentence *shapes* a phrase list cannot see | "not X but Y", a colon introducing a three-part parallel enumeration, concession-then-pivot |
+| `rhythm` | Burstiness — how much sentence length varies | metronomic paragraphs |
+
+Note that several of these argue *for* a human. A detector that can only ever accuse is not a measuring instrument. In practice the mechanical signals are often the most decisive thing in a file, in either direction.
+
+The deterministic pass finds phrases, artifacts and a few shapes. **It cannot find prose that is machine-written and bland** — for that a model has to read it, which is what the shipped agent skills are for.
+
+## Agent skills
+
+The primary surface. Two skills and a subagent ship inside the package and install with one command:
+
+```bash
+ductus install-skills --write          # links them into ~/.claude/skills
+```
+
+- **`ductus`** — what may and may not be claimed from a text, and which task is which.
+- **`ductus-gauge`** — the full reading: the deterministic scan, then a judgment pass with rubrics for the nine machine-leaning and six human-leaning *shapes* that regular expressions miss, then the write-up.
+- **`ductus-reader`** (subagent) — does the whole reading in its own context and returns a finished diagnosis.
+
+An agent's own reading folds back in beside the deterministic signals, anchored by quote:
+
+```bash
+ductus gauge draft.md --judgments judgments.json --format html --out report.html
+```
+
+A quote that no longer occurs is dropped rather than mis-anchored, so re-running after an edit is safe.
+
+## Seams
+
+Three, each one keyword argument, each defaulting to something that genuinely works:
+
+```python
+gauge(text, segmenter="sentence")  # or "paragraph", "document", or a callable
+gauge(
+    text, detectors=["forensic", "rhetoric"]
+)  # or your own (text, span) -> Iterator[Signal]
+gauge(text, aggregate=my_calibrated_scorer)  # replace the scoring model wholesale
+```
+
+A detector is a plain function `(text, span) -> Iterator[Signal]`. There is no base class and nothing to register. Adding Fast-DetectGPT, Binoculars or a vendor API means writing one more function of that shape — see [the roadmap](misc/docs/roadmap.md).
+
+For long documents, `iter_segments` is the streaming core and `gauge` is the batch facade over it.
+
+## Spans survive editing
+
+Every `Span` carries character offsets *and* the W3C Web Annotation redundant selectors (`quote`, `prefix`, `suffix`), because plain offsets do not survive an edit to the text. That is what lets a viewer re-find a finding after the document changed, and what a future edit-and-re-score UI is built on.
+
+## Relationship to `deslop`
+
+`ductus` is the read side: *where does this text read as machine-written, and why*. [`acquaint`](https://github.com/thorwhalen/acquaint)'s `deslop` is the write side: *make my draft not read that way, in my voice, calibrated to this reader*. They share this package's tells catalogue — `acquaint` imports it — and compose naturally: gauge, deslop the flagged spans, gauge again.
+
+They are separate packages because they have different inputs. `deslop` needs a model of the reader; `ductus` must work on a stranger's text with nothing but the text.
+
+## Install
+
+```bash
+pip install ductus              # the core: pyyaml and cw, nothing else
+pip install "ductus[local]"     # + model-based detectors, offline, no API key
+pip install "ductus[api]"       # + vendor detector adapters
+```
+
+## References
+
+[1] [Liang W, Yuksekgonul M, Mao Y, Wu E, Zou J. GPT detectors are biased against non-native English writers. *Patterns* 2023.](https://arxiv.org/abs/2304.02819)
+
+[2] [Sadasivan VS, Kumar A, Balasubramanian S, Wang W, Feizi S. Can AI-Generated Text be Reliably Detected?](https://arxiv.org/abs/2303.11156)
+
+[3] [Sanderson R, Ciccarese P, Young B. Web Annotation Data Model. W3C Recommendation, 2017.](https://www.w3.org/TR/annotation-model/)
+
+[4] [Tolstykh I, et al. LLMTrace: A Corpus for Classification and Fine-Grained Localization of AI-Written Text. arXiv:2509.21269.](https://arxiv.org/abs/2509.21269) — the ground-truth fixture in `tests/fixtures/` is a slice of this, Apache-2.0.

ductus-0.0.2/ductus/__init__.py

@@ -0,0 +1,67 @@
+"""ductus -- gauge which parts of a text read as machine-written, and why.
+
+In palaeography the *ductus* is the characteristic manner and sequence of strokes
+by which a scribe's hand is recognised. This package looks for the equivalent in
+prose: not a verdict about who wrote something, but evidence about how it reads,
+attached to the exact characters that carry it.
+
+    >>> from ductus import gauge
+    >>> report = gauge("Great question! Let's delve into this robust tapestry.")
+    >>> report.document.label
+    'leans-machine'
+    >>> report.segments[0].signals[0].name
+    'chat-leftover'
+
+Every finding is a :class:`Signal` with a direction, a weight, the detector that
+produced it, a reason, and a :class:`Span` carrying both character offsets and
+W3C-style quote/prefix/suffix selectors, so highlights survive an edit.
+
+**There is no percentage anywhere in this package, and that is deliberate.** A
+number like "87% AI" reads as a calibrated probability, is not one, and is how
+people get falsely accused. What you get instead is a lean in [-1, +1], an
+evidence strength, and a coarse label you can argue with. See
+:mod:`ductus.score`.
+
+Three seams, each one keyword argument with a working default:
+``segmenter=`` (how the text is cut up), ``detectors=`` (what produces evidence),
+``aggregate=`` (how evidence becomes a lean).
+"""
+
+from ductus.base import (
+    LABELS,
+    SCHEMA_VERSION,
+    Report,
+    Segment,
+    Signal,
+    Span,
+)
+from ductus.core import gauge, iter_segments
+from ductus.detect import DETECTORS
+from ductus.render import to_html, to_json, to_markdown
+from ductus.score import aggregate
+from ductus.segment import SEGMENTERS
+from ductus.tells import TellMatch, TellRule, iter_tell_matches, load_rules
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "DETECTORS",
+    "LABELS",
+    "SCHEMA_VERSION",
+    "SEGMENTERS",
+    "Report",
+    "Segment",
+    "Signal",
+    "Span",
+    "TellMatch",
+    "TellRule",
+    "__version__",
+    "aggregate",
+    "gauge",
+    "iter_segments",
+    "iter_tell_matches",
+    "load_rules",
+    "to_html",
+    "to_json",
+    "to_markdown",
+]

ductus-0.0.2/ductus/__main__.py

@@ -0,0 +1,20 @@
+"""``python -m ductus`` -- the CLI, built from the same functions the library exposes.
+
+ductus gauge draft.md                      # a markdown diagnosis on stdout
+ductus gauge draft.md --format html --out report.html
+ductus gauge - --format json < draft.md    # from stdin, machine-readable
+ductus tells --tier E                      # what the catalogue enforces
+ductus install-skills --write              # link the skills into ~/.claude
+"""
+
+import cw
+
+from ductus.tools import _dispatch_funcs
+
+
+def main() -> int:
+    return cw.dispatch(_dispatch_funcs)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ductus-0.0.2/ductus/base.py

@@ -0,0 +1,168 @@
+"""The data model: where a finding lives, what it claims, and how much it weighs.
+
+Four types, and they are the whole contract every other module speaks in.
+
+A :class:`Span` says *where*. It carries character offsets **and** the W3C Web
+Annotation redundant selectors (quote, prefix, suffix) so a finding can be
+re-anchored after the text is edited, which plain offsets cannot survive.
+
+A :class:`Signal` is one piece of evidence: a direction, a weight, who produced
+it, and a human-readable reason. Signals are never merged or averaged away --
+the reason a passage scored the way it did is always recoverable.
+
+A :class:`Segment` is a unit of text plus the signals that landed on it and the
+lean derived from them. A :class:`Report` is the document-level roll-up.
+
+>>> text = "The cat sat. It was a fine evening."
+>>> span = Span.of(text, 4, 7)
+>>> span.quote, span.prefix
+('cat', 'The ')
+>>> Signal("test", "machine", 0.5, "demo", note="an example").direction
+'machine'
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "DIRECTIONS",
+    "LABELS",
+    "SCHEMA_VERSION",
+    "Report",
+    "Segment",
+    "Signal",
+    "Span",
+]
+
+#: Bumped when the serialized shape of a Report changes incompatibly.
+SCHEMA_VERSION = "1"
+
+#: What a signal can argue for. ``neutral`` records evidence that is real but
+#: does not discriminate -- it is kept because hiding it would be dishonest.
+DIRECTIONS = ("machine", "human", "neutral")
+
+#: The coarse vocabulary a segment is labelled with. Deliberately not a
+#: percentage: see ``docs/why-no-percentage.md``.
+LABELS = ("leans-machine", "leans-human", "mixed-signals", "uncertain", "no-evidence")
+
+#: How much text on each side of a span is kept for re-anchoring.
+CONTEXT_CHARS = 40
+
+
+@dataclass(frozen=True)
+class Span:
+    """A character range, with redundant selectors so it survives an edit.
+
+    ``start``/``end`` are a ``TextPositionSelector``; ``quote`` with ``prefix``
+    and ``suffix`` is a ``TextQuoteSelector``. Keeping both is what lets a
+    viewer re-find a finding after the text around it changed.
+
+    >>> s = Span.of("one two three", 4, 7, level="sentence")
+    >>> (s.start, s.end, s.quote, s.level)
+    (4, 7, 'two', 'sentence')
+    >>> s.length
+    3
+    """
+
+    start: int
+    end: int
+    quote: str
+    prefix: str = ""
+    suffix: str = ""
+    level: str = "segment"
+
+    @classmethod
+    def of(cls, text: str, start: int, end: int, *, level: str = "segment") -> Span:
+        """Build a span over ``text``, capturing its re-anchoring context.
+
+        >>> Span.of("abcdef", 2, 4).suffix
+        'ef'
+        """
+        return cls(
+            start=start,
+            end=end,
+            quote=text[start:end],
+            prefix=text[max(0, start - CONTEXT_CHARS) : start],
+            suffix=text[end : end + CONTEXT_CHARS],
+            level=level,
+        )
+
+    @property
+    def length(self) -> int:
+        return self.end - self.start
+
+    def contains(self, other: Span) -> bool:
+        """Whether ``other`` falls entirely inside this span.
+
+        >>> a, b = Span.of("abcdef", 0, 6), Span.of("abcdef", 2, 4)
+        >>> a.contains(b), b.contains(a)
+        (True, False)
+        """
+        return self.start <= other.start and other.end <= self.end
+
+
+@dataclass(frozen=True)
+class Signal:
+    """One piece of evidence about one span.
+
+    ``weight`` is how much this moves the needle, in ``0..1``. It is a weight,
+    not a probability: two 0.5 signals pointing the same way are stronger than
+    one, and nothing here claims to be calibrated.
+
+    >>> Signal("em-dash", "machine", 0.2, "forensic", value=3).name
+    'em-dash'
+    """
+
+    name: str
+    direction: str
+    weight: float
+    detector: str
+    value: Any = None
+    note: str = ""
+    span: Span | None = None
+
+    def __post_init__(self) -> None:
+        if self.direction not in DIRECTIONS:
+            raise ValueError(
+                f"direction must be one of {DIRECTIONS}, got {self.direction!r}"
+            )
+        if not 0.0 <= self.weight <= 1.0:
+            raise ValueError(f"weight must be in [0, 1], got {self.weight!r}")
+
+
+@dataclass(frozen=True)
+class Segment:
+    """A unit of text, the signals on it, and the lean they add up to.
+
+    ``lean`` runs from -1 (every signal argues human) to +1 (every signal argues
+    machine). ``strength`` is how much evidence there is at all -- a lean of
+    +1.0 from a single weak signal is not the same claim as +1.0 from six.
+    """
+
+    span: Span
+    signals: tuple[Signal, ...] = ()
+    lean: float = 0.0
+    strength: float = 0.0
+    label: str = "no-evidence"
+
+
+@dataclass(frozen=True)
+class Report:
+    """Everything a downstream consumer needs, and nothing it has to guess at."""
+
+    text_sha256: str
+    n_chars: int
+    document: Segment
+    segments: tuple[Segment, ...]
+    detectors: tuple[str, ...]
+    segmenter: str
+    schema_version: str = SCHEMA_VERSION
+    calibration: str = "uncalibrated"
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def signals(self) -> tuple[Signal, ...]:
+        """Every signal in the report, in document order."""
+        return tuple(s for seg in self.segments for s in seg.signals)