ductus 0.0.2__py3-none-any.whl

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/__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/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)

ductus/core.py

@@ -0,0 +1,125 @@
+"""The core: stream segments, or take the whole report. Everything else is a surface.
+
+Two entry points, and the second is a facade over the first:
+
+:func:`iter_segments` yields one :class:`~ductus.base.Segment` at a time as it
+scores them -- the streaming surface, for long documents and for a UI that wants
+to paint as results arrive.
+
+:func:`gauge` collects them into a :class:`~ductus.base.Report`.
+
+The three seams are keyword arguments, each defaulting to something that
+genuinely works rather than to a stub:
+
+===============  ==========================================  ==========================
+seam             v1 default                                  swap in
+===============  ==========================================  ==========================
+``segmenter=``   ``"paragraph"``                             ``"sentence"``, a callable
+``detectors=``   all four deterministic detectors            a model-based detector
+``aggregate=``   :func:`ductus.score.aggregate`              a calibrated scorer
+===============  ==========================================  ==========================
+
+``extra_signals=`` is not a seam but an input: evidence produced elsewhere --
+by an agent reading the text, by a vendor API -- attached to the segment that
+contains it. It is how the shipped skills feed a model's reading back in.
+
+>>> report = gauge("Great question! Let's delve into this robust tapestry.")
+>>> report.document.label
+'leans-machine'
+>>> report = gauge("Sent the export Friday. Two sites, not five. Call if it breaks.")
+>>> report.document.label
+'no-evidence'
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable, Iterable, Iterator, Sequence
+
+from ductus.base import Report, Segment, Signal, Span
+from ductus.detect import detectors_from
+from ductus.score import aggregate as default_aggregate
+from ductus.segment import spans_of
+
+__all__ = ["gauge", "iter_segments"]
+
+Aggregator = Callable[[Sequence[Signal]], "tuple[float, float, str]"]
+
+
+def iter_segments(
+    text: str,
+    *,
+    segmenter: str | Callable[[str], Iterator[Span]] = "paragraph",
+    detectors: Sequence | None = None,
+    aggregate: Aggregator = default_aggregate,
+    extra_signals: Iterable[Signal] = (),
+) -> Iterator[Segment]:
+    """Yield one scored segment at a time.
+
+    >>> segs = list(iter_segments("Let's delve in.\\n\\nSent it Friday."))
+    >>> len(segs), segs[0].label
+    (2, 'leans-machine')
+    """
+    fns, _ = detectors_from(detectors)
+    injected = tuple(extra_signals)
+    for span in spans_of(text, segmenter):
+        signals: list[Signal] = []
+        for fn in fns:
+            signals.extend(fn(text, span))
+        for s in injected:
+            if s.span is None or span.contains(s.span):
+                signals.append(s)
+        signals.sort(key=lambda s: (s.span.start if s.span else span.start, s.name))
+        lean, strength, label = aggregate(signals)
+        yield Segment(
+            span=span, signals=tuple(signals), lean=lean, strength=strength, label=label
+        )
+
+
+def gauge(
+    text: str,
+    *,
+    segmenter: str | Callable[[str], Iterator[Span]] = "paragraph",
+    detectors: Sequence | None = None,
+    aggregate: Aggregator = default_aggregate,
+    extra_signals: Iterable[Signal] = (),
+) -> Report:
+    """Score ``text`` and roll the segments up into a report.
+
+    The document-level lean is computed over *all* signals in the document, not
+    by averaging the segment leans -- averaging would let two short, heavily
+    flagged paragraphs outvote a long clean one.
+
+    >>> r = gauge("It is important to note that this is a robust tapestry.")
+    >>> r.document.lean > 0 and r.n_chars == 55
+    True
+    >>> r.segmenter, len(r.detectors)
+    ('paragraph', 4)
+    """
+    _, names = detectors_from(detectors)
+    segments = tuple(
+        iter_segments(
+            text,
+            segmenter=segmenter,
+            detectors=detectors,
+            aggregate=aggregate,
+            extra_signals=extra_signals,
+        )
+    )
+    all_signals = tuple(s for seg in segments for s in seg.signals)
+    lean, strength, label = aggregate(all_signals)
+    document = Segment(
+        span=Span.of(text, 0, len(text), level="document"),
+        signals=(),
+        lean=lean,
+        strength=strength,
+        label=label,
+    )
+    return Report(
+        text_sha256=hashlib.sha256(text.encode("utf-8")).hexdigest(),
+        n_chars=len(text),
+        document=document,
+        segments=segments,
+        detectors=names,
+        segmenter=segmenter if isinstance(segmenter, str) else "custom",
+    )

ductus/data/agents/ductus-reader.md

@@ -0,0 +1,11 @@
+---
+name: ductus-reader
+description: Reads a text for machine-written prose in its own context and returns a finished diagnosis — the deterministic scan plus its own judgment pass, written up with the evidence and the limits. Use when asked which parts of a document read as AI-generated, or to check a draft, and you want the reading done without the document's full text landing in the main thread. Read-only with respect to the source; it writes its report beside the source file.
+tools: Bash, Read, Write, Glob, Grep
+---
+
+You perform one task: a full `ductus` reading of a text, returned as a finished diagnosis.
+
+Follow the `ductus-gauge` skill exactly — its three passes, its two judgment tables, and its write-up order. Read the `ductus` skill's limits section first and honour it: no percentages, no verdict about a person, and the editing confound plus the non-native-writer bias stated in every report.
+
+Return the diagnosis itself, not a description of what you did, and not the document's full text. If the source is private, say where you wrote the report and quote nothing from it in your reply beyond the passages your findings rest on.

ductus/data/skills/ductus/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ductus
+description: Gauge which parts of a text read as machine-written, and say why, with the evidence anchored to exact characters. Use whenever someone asks whether text was AI-generated, wants to know which passages "sound like AI", asks you to check a draft before sending it, or says "is this AI", "did a model write this", "which parts sound generated", "AI detection", "AI-written", "run a detector on this", "how AI does this read". Also use before the deslop skill, to find what needs rewriting, and after it, to check the rewrite. Read this skill before reaching for any AI-detector service; it owns what can and cannot honestly be claimed from a text.
+metadata:
+  audience: users
+---
+
+# ductus — reading a text for the machine's hand
+
+In palaeography the *ductus* is the manner and sequence of strokes by which a scribe's hand is recognised. This package looks for the equivalent in prose.
+
+## Say this before anything else
+
+**You cannot determine whether a person used a model. You can only describe how a text reads.** Hold that line even when pushed, because the cost of getting it wrong falls entirely on a person who did nothing wrong.
+
+Four facts, each load-bearing, none optional to mention when reporting a result:
+
+1. **Heavily-edited human writing and model-assisted writing produce the same signature.** Re-reading a hard message ten times sands off exactly the irregularity that marks it as human.
+2. **Detectors over-flag non-native English writers** — a 61.3% false-positive rate across seven commercial detectors on non-native TOEFL essays, against near-zero on native-speaker controls (Liang et al., *Patterns* 2023).
+3. **Register contamination is real.** Someone who reads model output all day starts writing like it, unassisted.
+4. **No detector survives a motivated adversary**, and that is a proven result, not a gap in current tooling (Sadasivan et al., arXiv:2303.11156).
+
+So: **never produce a percentage**, never say "this was AI-generated", and never hand someone a result to confront a third party with. Say what fired, where, and how much it weighs. If the question behind the request is really "did my colleague use AI", the answer that helps is *ask them*, and say so.
+
+## Which task is this?
+
+| The ask | Do this |
+|---|---|
+| "Which parts of this read as AI?" / "is this AI-written?" | the **ductus-gauge** skill — the full reading |
+| "Check this before I send it" / "make it sound like me" | the **deslop** skill first; gauge after, to check the rewrite |
+| "Just give me a quick look" | `ductus gauge <file>` and report the segments that fired |
+| "What does it actually look for?" | `ductus tells` and `ductus detectors` |
+
+## The quick pass
+
+```bash
+ductus gauge draft.md                          # markdown diagnosis on stdout
+ductus gauge draft.md --format html --out report.html
+ductus gauge - --format json < draft.md        # machine-readable
+ductus tells --tier E                          # near-certain patterns only
+```
+
+The deterministic pass costs nothing and needs no key. **It finds phrases, mechanical artifacts and a few sentence shapes. It does not find prose that is machine-written and bland** — for that you have to read, which is what `ductus-gauge` is for.
+
+## Reading the output
+
+- `lean` runs from **-1 (all evidence argues human)** to **+1 (all argues machine)**. It is a ratio of the weights present, not a probability.
+- `strength` is how much evidence there was at all. **A lean of +1.00 at strength 0.15 is one weak signal, not a finding.** Always read the two together.
+- Signals with direction `human` are as important as `machine` ones. A hard line break mid-sentence, mixed straight-and-curly apostrophes, a missing final period — models do not produce these, and they are often the most decisive thing in the file.
+- Zero findings is a real result and a weak one. Say so rather than reporting "clean".
+
+## What tends to be true, when it is true
+
+The pattern worth looking for is not "which sentences are flagged" but **what kind of sentence is flagged**. In mixed-authorship text the machine-leaning passages are usually the ones that *generalise* — naming a pattern, stating a principle, managing a relationship — while the human-leaning ones are the *specific* ones: a number someone measured, a named person, a particular grievance. When you see that split, say it. It is more informative than any score.
+
+## Never
+
+- Give a percentage, a confidence, or a verdict about a person.
+- Report a document-level number without saying which segments drove it.
+- Use this to help someone evade detection. The package exists to describe text, and its sibling `deslop` exists to make writing *good*, not to launder it.

ductus/data/skills/ductus-gauge/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ductus-gauge
+description: Do a full reading of a text for machine-written prose — run the deterministic detectors, add your own judgment pass for the shapes a regular expression cannot see, and produce a markdown or HTML report with evidence anchored to exact characters. Use when asked which parts of a text read as AI-generated, to analyse or diagnose a document's authorship signals, to check a draft before sending, or to verify a rewrite. Triggers on "which parts sound like AI", "analyse this text", "gauge this", "is this AI-written", "run the detectors", "AI reading of this document", "check this draft". Read the `ductus` skill first for what may and may not be claimed.
+metadata:
+  audience: users
+---
+
+# ductus-gauge — the full reading
+
+Three passes. The first is free, the second is the one that matters, the third is the write-up. **Read the `ductus` skill's limits section before reporting anything.**
+
+## Pass 1 — the deterministic scan
+
+```bash
+ductus gauge <file> --format json --out /tmp/ductus-scan.json
+ductus gauge <file>          # the same scan, as readable markdown
+```
+
+Read what fired and where. This pass finds catalogue phrases, typographic artifacts, a few sentence shapes, and sentence-length variance. **Expect it to find nothing on careful text. That is not evidence of human authorship** — it is the limit of regular expressions.
+
+## Pass 2 — your own reading (this is the valuable one)
+
+Read the text yourself and look for the shapes below. For each one you find, record a judgment. Quote exactly — the quote is how it gets anchored.
+
+### Machine-leaning shapes
+
+| Shape | What it looks like | Weight |
+|---|---|---|
+| **Pattern-naming tricolon** | Names a behaviour, then unrolls it as three parallel clauses: "This is a recurring pattern: you decide X, invest Y, and then get frustrated when Z." | 0.5 |
+| **Principle generalisation** | Lifts a specific complaint into a balanced maxim: "Time spent can't by itself be a measure of value." | 0.45 |
+| **Aphoristic closer** | A one-sentence moral capping a paragraph that did not need one. | 0.4 |
+| **Concede-then-pivot** | "I do value X. At the same time, Y." The diplomatic-feedback move. | 0.35 |
+| **Term reversal** | Takes the other party's own word and turns it back neatly in the closing clause. | 0.35 |
+| **False balance** | "While X has benefits, it also has drawbacks" where the author plainly holds a view. | 0.35 |
+| **Uniform paragraph architecture** | Every paragraph the same length, same shape, same one-point-then-elaborate rhythm. | 0.3 |
+| **Reassurance pair** | Two short declaratives doing emotional management mid-argument: "Software is difficult and review is normal." | 0.3 |
+| **Over-explanation** | More words than the facts need; uniformly perfect formality in a casual channel. | 0.25 |
+
+### Human-leaning shapes (look as hard for these)
+
+| Shape | What it looks like | Weight |
+|---|---|---|
+| **Typing and paste artifacts** | A hard line break mid-sentence, a doubled word, trailing whitespace, a missing final period. | 0.45 |
+| **Insertion seams** | Paragraph separation that is inconsistent — three joins missing the blank line the rest of the document uses. Marks where text was added in a later pass. | 0.4 |
+| **L2 grammar slips** | Article, countability or preposition errors ("it's always a team work"). Models essentially never emit these. | 0.6 |
+| **Unhedged specificity** | A named person, a measured number, an unglossed particular, with no scaffolding around it. | 0.3 |
+| **Absent habits** | Zero em dashes across a long reflective text; no bullet lists where a model would reach for one. | 0.35 |
+| **Cost-bearing opinion** | A claim the author would have to defend, stated without balancing it. | 0.3 |
+
+Write them to a file:
+
+```json
+[
+  {"quote": "exact text from the document",
+   "direction": "machine",
+   "name": "pattern-naming-tricolon",
+   "weight": 0.5,
+   "note": "Names a pattern, then three parallel verb phrases."},
+  {"quote": "it's always a team work",
+   "direction": "human",
+   "name": "l2-grammar-slip",
+   "weight": 0.6,
+   "note": "Article and countability error; models do not produce this."}
+]
+```
+
+Then fold it in:
+
+```bash
+ductus gauge <file> --judgments judgments.json --format html --out report.html
+ductus gauge <file> --judgments judgments.json --out reading.md
+```
+
+A quote that no longer occurs in the text is dropped rather than mis-anchored, so re-running after an edit is safe.
+
+## Pass 3 — the write-up
+
+Lead with **what kind of passage** carries which signal, not with the number. The useful sentence is usually of the form *"the passages that generalise carry the machine signal; the specific ones carry typing artifacts"*, because that describes a **process** — someone wrote their own material and reached for help framing it — rather than pronouncing on a person.
+
+Then, in order:
+
+1. The strongest **mechanical** evidence (artifacts, seams, slips). It is the hardest to fake in either direction and should be weighted accordingly.
+2. The strongest **rhetorical** evidence, quoted.
+3. What is **ambiguous**, said plainly. Consistent curly apostrophes mean the text was composed outside the channel it was sent in; they say nothing about who composed it.
+4. The **limits** from the `ductus` skill — at least the editing confound and the non-native-writer bias.
+5. **What would actually settle it**, which is almost never more detection. Usually: a sample of the same author's earlier writing to compare against, or asking them.
+
+## If the text is private
+
+Keep every artifact out of any repository and out of any external service. Write reports beside the source file, not into a project directory. Quote the text only in files that live where the source does.