clinescope 1.0.1__py3-none-any.whl

clinescope/__init__.py

@@ -0,0 +1,9 @@
+"""clinescope — a Cline-native agentic-coding-trace eval harness.
+
+Package root. The thin path is load a World-A trace -> score tool selection ->
+render a report; see :mod:`clinescope.world_a`,
+:mod:`clinescope.tool_selection`, and :mod:`clinescope.report`,
+with :mod:`clinescope.__main__` as the CLI entry point.
+"""
+
+__version__ = "1.0.1"

clinescope/__main__.py

@@ -0,0 +1,152 @@
+"""Thin CLI for the walking skeleton: load -> score -> EMIT.
+
+Usage:
+    python -m clinescope <trace.json> --expected read_files [write_file ...] [--verbose]
+
+Loads a Cline World-A trace, scores tool selection against the expected tool
+names, renders the report, and prints it. The default is a one-line-per-scorer
+summary; ``--verbose`` emits the full per-scorer debug dump instead. The heavy
+lifting lives in
+:func:`clinescope.report.render_report` (a pure ``str``-returning
+function) so the report is testable WITHOUT a subprocess; this module is only
+argument parsing plus glue.
+
+The trace ``sessionId`` is not modelled on
+:class:`clinescope.world_a.Trace` (the loader discards it), so it is
+lifted here with one cheap read and passed through to the emitter.
+
+A trace that cannot be loaded (missing path, unsupported version, malformed or
+non-object JSON) prints a single ``error: ...`` line to stderr and exits 1 --
+never a raw Python traceback.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from clinescope.apply_recovery import score_apply_recovery
+from clinescope.diff_coherence import score_diff_coherence
+from clinescope.diff_minimality import score_diff_minimality
+from clinescope.report import render_report
+from clinescope.tool_selection import score_tool_selection
+from clinescope.tool_vocab import CLINE_WORLD_A_TOOLS, tool_vocab_check
+from clinescope.world_a import load_trace
+
+
+class _ListToolsAction(argparse.Action):
+    """--list-tools: print the known Cline tool vocabulary and exit 0.
+
+    A user should never have to GUESS what goes after --expected. This prints the
+    same pinned vocabulary --expected is validated against, and short-circuits
+    before ``trace`` is required (so ``clinescope --list-tools`` needs no trace).
+    """
+
+    def __call__(self, parser, namespace, values, option_string=None):  # type: ignore[no-untyped-def]
+        for name in sorted(CLINE_WORLD_A_TOOLS):
+            print(name)
+        parser.exit(0)
+
+
+def _read_session_id(path: Path) -> str | None:
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    session_id = raw.get("sessionId")
+    return session_id if isinstance(session_id, str) else None
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="clinescope")
+    parser.add_argument(
+        "trace", type=Path, help="Path to a Cline World-A messages.json trace"
+    )
+    parser.add_argument(
+        "--expected",
+        nargs="+",
+        default=None,
+        metavar="TOOL",
+        help=(
+            "Expected tool name(s), space-separated (e.g. --expected read_files "
+            "apply_patch). Omit to skip tool-selection scoring; run --list-tools "
+            "to see valid names."
+        ),
+    )
+    parser.add_argument(
+        "--list-tools",
+        action=_ListToolsAction,
+        nargs=0,
+        help="Print the known Cline tool names (for --expected) and exit",
+    )
+    parser.add_argument(
+        "--advice",
+        action="store_true",
+        help="Append per-failing-scorer coaching (what to change) to the summary",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Emit the full per-scorer debug dump instead of the one-line summary",
+    )
+    return parser.parse_args(argv)
+
+
+def _warn_unknown_expected(expected: list[str]) -> None:
+    # A misspelled --expected name would silently score as a MISSING tool -- a
+    # false negative that blames the agent for the user's typo. Warn (don't abort:
+    # a genuinely custom tool is legal) with a nearest-match suggestion.
+    for name, suggestion in tool_vocab_check(expected):
+        hint = f" - did you mean '{suggestion}'?" if suggestion else ""
+        print(f"warning: unknown tool '{name}'{hint}", file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+    # Opt-in tool_selection: distinguish "--expected was omitted" (None -> skip
+    # scoring it, show n/a) from "--expected with no names" so an omitted flag no
+    # longer prints a vacuous 100/100 PASS. Validate the given names for typos.
+    expected_provided = args.expected is not None
+    expected = args.expected if expected_provided else []
+    if expected_provided:
+        _warn_unknown_expected(expected)
+
+    # Load boundary: a bad path / bad version / malformed or non-object JSON must
+    # print a clean one-line error, NOT a raw Python traceback. The loader raises
+    # a whole family of failures beyond its own WorldATraceError: OSError from a
+    # missing/unreadable file, json.JSONDecodeError from bad JSON, and even an
+    # AttributeError/TypeError when JSON-parseable-but-structurally-invalid input
+    # trips the parser. Catch broadly here so every load failure normalizes to the
+    # same clean stderr line + exit 1 -- this is the deliberate load boundary (the
+    # sibling `clinescope.gate` CLI does the same), not swallowed application logic.
+    try:
+        trace = load_trace(args.trace)
+        session_id = _read_session_id(args.trace)
+    except Exception as err:  # noqa: BLE001 -- deliberate load-failure boundary (see above)
+        print(
+            f"error: could not load trace {args.trace}: {type(err).__name__}: {err}",
+            file=sys.stderr,
+        )
+        return 1
+
+    score = score_tool_selection(trace, set(expected))
+    diff_score = score_diff_coherence(trace)
+    minimality_score = score_diff_minimality(trace)
+    recovery_score = score_apply_recovery(trace)
+    print(
+        render_report(
+            trace,
+            score,
+            session_id=session_id,
+            diff_coherence=diff_score,
+            diff_minimality=minimality_score,
+            apply_recovery=recovery_score,
+            expected_provided=expected_provided,
+            advice=args.advice,
+            verbose=args.verbose,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

clinescope/_datafiles.py

@@ -0,0 +1,111 @@
+"""Locate clinescope's bundled data (``examples/`` + ``gold/``) from anywhere.
+
+The default-data features -- the real-trace corpus (:mod:`clinescope.corpus`), the gold
+set + judge cache (:mod:`clinescope.gold`, :mod:`clinescope.judge_run`) -- read committed
+files by a repo-relative path. From a source checkout that is the repo root (cwd). But a
+``pip install`` user has no repo: the files ship inside the wheel (via
+``[tool.hatch.build.targets.wheel.force-include]``), so a cwd-relative default resolves to
+nothing and the feature crashes.
+
+This module resolves the DATA ROOT -- the directory that contains ``examples/`` and
+``gold/`` -- independent of the current working directory, so those defaults work from a
+source checkout AND from an installed wheel. It does NOT change the public
+``repo_root=`` parameters (a caller may still point at any tree); it only supplies the
+DEFAULT base when the caller does not.
+
+**How it resolves (first hit wins):**
+
+1. The current working directory, if it already contains ``examples/`` + ``gold/`` --
+   preserves the historical "run from the repo root" behaviour byte-for-byte.
+2. The directory that ships alongside the installed package. With force-include the data
+   lands next to the ``clinescope`` package dir (``site-packages/examples``,
+   ``site-packages/gold``); in the src-layout dev tree it is two levels above the package
+   (``<repo>/examples``). Both candidates are probed via ``importlib.resources`` on the
+   package's anchor, falling back to ``__file__`` walking.
+
+If none contains the data, the resolver raises a clear :class:`DataFilesNotFound` naming
+what it looked for -- never a bare ``FileNotFoundError`` deep inside a loader.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+# The two directories that together mark a valid clinescope data root.
+_DATA_MARKERS = ("examples", "gold")
+
+
+class DataFilesNotFound(RuntimeError):
+    """The bundled ``examples/`` + ``gold/`` data root could not be located."""
+
+
+def datafiles_root() -> Path:
+    """Return the directory that contains clinescope's ``examples/`` + ``gold/`` data.
+
+    Tries the current working directory first (a source checkout), then the location the
+    data ships at alongside the installed package. Raises :class:`DataFilesNotFound` if
+    neither has the data.
+    """
+    for candidate in _datafiles_candidate_roots():
+        if _datafiles_is_root(candidate):
+            return candidate
+    tried = ", ".join(str(c) for c in _datafiles_candidate_roots())
+    raise DataFilesNotFound(
+        "could not locate clinescope's bundled data (an 'examples/' and 'gold/' "
+        f"directory). Looked in: {tried}. Run from a source checkout, or pass an "
+        "explicit path (e.g. `clinescope-corpus <manifest>`)."
+    )
+
+
+def datafiles_path(*parts: str) -> Path:
+    """Resolve a data-relative path (e.g. ``"gold", "diff_minimality.gold.jsonl"``).
+
+    Joins ``parts`` onto :func:`datafiles_root`. The returned path is NOT required to
+    exist (a caller may build a default that a loader then checks); it is only anchored to
+    the located data root.
+    """
+    return datafiles_root().joinpath(*parts)
+
+
+def _datafiles_candidate_roots() -> tuple[Path, ...]:
+    """Ordered candidate data roots: cwd first, then package-adjacent locations."""
+    candidates: list[Path] = [Path.cwd()]
+    candidates.extend(_datafiles_package_adjacent_roots())
+    # De-dupe while preserving order (cwd may coincide with a package root in dev).
+    seen: set[Path] = set()
+    unique: list[Path] = []
+    for candidate in candidates:
+        resolved = candidate.resolve()
+        if resolved not in seen:
+            seen.add(resolved)
+            unique.append(resolved)
+    return tuple(unique)
+
+
+def _datafiles_package_adjacent_roots() -> list[Path]:
+    """Candidate roots derived from where the ``clinescope`` package is installed.
+
+    force-include lands the data at ``site-packages/`` (one level ABOVE the package dir);
+    the src-layout dev tree keeps it two levels above (``<repo>/examples`` vs
+    ``<repo>/src/clinescope``). Probe both, via ``importlib.resources`` then ``__file__``.
+    """
+    roots: list[Path] = []
+    try:
+        anchor = resources.files("clinescope")
+        pkg_dir = Path(str(anchor))
+    except (
+        ModuleNotFoundError,
+        TypeError,
+    ):  # pragma: no cover - clinescope is importable
+        pkg_dir = Path(__file__).resolve().parent
+    # site-packages/clinescope -> site-packages (wheel force-include target)
+    roots.append(pkg_dir.parent)
+    # <repo>/src/clinescope -> <repo> (src-layout dev checkout)
+    roots.append(pkg_dir.parent.parent)
+    return roots
+
+
+def _datafiles_is_root(candidate: Path) -> bool:
+    """True iff ``candidate`` contains every data marker directory."""
+    return all((candidate / marker).is_dir() for marker in _DATA_MARKERS)

clinescope/advice.py

@@ -0,0 +1,120 @@
+"""Rule-based advice/coach layer (deterministic, zero-LLM).
+
+Clinescope scores a run, then leaves the developer with bare numbers -- a real
+user's reaction was "it scored... now what?". This module turns a FAILING scorer
+into (1) a short failure-taxonomy label and (2) concrete "what to do" guidance
+(usually a prompt fix), keyed to that scorer's EXISTING evidence fields. It
+RECOMPUTES nothing and changes no score: every advice string reads fields the
+scorers already surfaced (missing tools, gate violations, blind-rewrite counts,
+unrecovered files). Off by default; the CLI renders it only under ``--advice``.
+
+The taxonomy labels are the minimal first slice of the charter's roadmap metric
+#7 (failure taxonomy): a fixed enum, one label selected per failing scorer from
+its evidence -- NOT a learned classifier and NOT an LLM. A scorer that PASSED or
+ABSTAINED yields no advice (``None``), so a clean run stays quiet.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from clinescope.apply_recovery import ApplyRecoveryScore
+from clinescope.diff_coherence import DiffCoherenceScore
+from clinescope.diff_minimality import DiffMinimalityScore
+from clinescope.tool_selection import ToolSelectionScore
+
+
+class FailureLabel(Enum):
+    """A fixed, pre-defined failure category per scorer (roadmap metric #7, v1)."""
+
+    MISSING_TOOLS = "missing_tools"
+    MALFORMED_PATCH = "malformed_patch"
+    BLIND_REWRITE = "blind_rewrite"
+    NO_APPLY_RECOVERY = "no_apply_recovery"
+
+
+@dataclass(frozen=True, slots=True)
+class ScorerAdvice:
+    """One failing scorer's taxonomy label + human-readable guidance lines.
+
+    ``lines`` quote the scorer's OWN evidence (a missing tool name, a violation
+    string, a count, a file path) -- never a recomputed value.
+    """
+
+    label: FailureLabel
+    lines: tuple[str, ...]
+
+
+def advice_for_tool_selection(score: ToolSelectionScore) -> ScorerAdvice | None:
+    """Advise when expected tools were not used; ``None`` when all were."""
+    if not score.missing:
+        return None
+    tools = ", ".join(sorted(score.missing))
+    return ScorerAdvice(
+        label=FailureLabel.MISSING_TOOLS,
+        lines=(
+            f"The agent never called: {tools}.",
+            "Add to your prompt an instruction to use the right tool for the task "
+            "(e.g. 'Always read a file with read_files before you patch it').",
+        ),
+    )
+
+
+def advice_for_diff_coherence(score: DiffCoherenceScore) -> ScorerAdvice | None:
+    """Advise when the apply_patch grammar is malformed; ``None`` at a perfect score.
+
+    diff_coherence never abstains (no apply_patch is a hard 0.0), so any score below
+    1.0 is a real malformed-patch signal worth coaching.
+    """
+    if score.score == 1.0:
+        return None
+    reason = score.violations[0] if score.violations else "malformed apply_patch"
+    return ScorerAdvice(
+        label=FailureLabel.MALFORMED_PATCH,
+        lines=(
+            f"The patch is malformed: {reason}.",
+            "The model is emitting invalid apply_patch grammar. Add a few-shot "
+            "example of a correct '*** Begin Patch' block to your prompt, or try a "
+            "stronger model.",
+        ),
+    )
+
+
+def advice_for_diff_minimality(score: DiffMinimalityScore) -> ScorerAdvice | None:
+    """Advise when hunks are blind whole-block rewrites; ``None`` when clean/abstaining.
+
+    Abstains (``applicable=False``) and perfect scores yield no advice. A hard-zero
+    (mis-shaped patch) is a coherence problem, not a minimality one, so it is left to
+    diff_coherence; here we only coach the genuine blind-rewrite signal.
+    """
+    if not score.applicable or score.score == 1.0:
+        return None
+    if score.blind_rewrite_hunks == 0:
+        return None
+    return ScorerAdvice(
+        label=FailureLabel.BLIND_REWRITE,
+        lines=(
+            f"{score.blind_rewrite_hunks} of {score.hunks_with_body} edited hunks "
+            "are blind whole-block rewrites (delete the whole block, retype it).",
+            "Prompt the agent to change only the lines that must change and keep "
+            "the surrounding lines as context.",
+        ),
+    )
+
+
+def advice_for_apply_recovery(score: ApplyRecoveryScore) -> ScorerAdvice | None:
+    """Advise when a failed patch was never recovered; ``None`` when clean/abstaining."""
+    if not score.applicable or score.score == 1.0:
+        return None
+    files = ", ".join(score.failed_target_paths) if score.failed_target_paths else "-"
+    return ScorerAdvice(
+        label=FailureLabel.NO_APPLY_RECOVERY,
+        lines=(
+            f"The agent failed a patch and did not recover it "
+            f"({score.confirmed_recovered_pairs}/{score.total_failed_pairs} "
+            f"recovered; unrecovered files: {files}).",
+            "Add a retry instruction: after a failed apply_patch, re-read the file "
+            "and try a corrected patch instead of giving up.",
+        ),
+    )

clinescope/agreement.py

@@ -0,0 +1,270 @@
+"""Cohen's-kappa agreement harness -- judge-validation, segment 1 (zero-LLM stats).
+
+The credibility layer for the charter's criterion 3: once an LLM judge and a small
+HUMAN gold set label the same items, this reports their chance-corrected agreement
+as Cohen's kappa WITH a confidence interval -- the "prove the evaluator is correct"
+number an eval reader looks for. This module is the pure statistics ONLY: it takes
+two aligned label lists and returns kappa + a CI. The judge, the gold set, and the
+end-to-end wiring are LATER segments; nothing here calls an LLM, reads a file, or
+imports a scorer.
+
+    kappa = (p_o - p_e) / (1 - p_e)
+
+where ``p_o`` is observed agreement (fraction of items both raters labeled the same)
+and ``p_e`` is expected/chance agreement (sum over each category ``k`` of
+``P(rater_a = k) * P(rater_b = k)``, i.e. the product of the two marginals). Source:
+Wikipedia "Cohen's kappa"; scikit-learn ``cohen_kappa_score`` (identical definition).
+
+**Deliberate decisions (each a stated choice, not undefined behaviour):**
+
+* Two raters, one nominal label per item (binary is the segment-1 case, but the
+  kappa itself is category-agnostic: it works for any hashable label set). Weighted
+  kappa / Krippendorff's alpha (for ORDINAL labels) are a LATER segment -- not built
+  for a label scale that does not exist yet (two-implementation rule).
+* Degenerate ``p_e == 1`` (both raters put every item in ONE category, so chance
+  agreement is already total) makes ``kappa = 0/0`` mathematically UNDEFINED. We
+  follow scikit-learn: return ``kappa = NaN`` with ``defined = False`` (and NaN CI
+  bounds), NEVER a silent ``0.0`` or ``1.0`` and never a crash. "Perfect raw
+  agreement but kappa undefined" is a real signal (degenerate marginals -- the
+  base-rate paradox), so it is surfaced honestly, not laundered into a number. This
+  IS the current clinescope corpus (every minimality score is 1.0 -> one class).
+* The CI is a BOOTSTRAP PERCENTILE interval, NOT the asymptotic (Wald) ``kappa +/-
+  1.96*SE``. For the small gold sets this targets (N ~ 20-50), the sampling
+  distribution of kappa is skewed and the symmetric Wald interval is a poor fit that
+  can even spill past +/-1 (Fleiss & Cicchetti 1978); the percentile bootstrap
+  respects the ``[-1, 1]`` bounds and the asymmetry. Honest caveat: at small N the
+  interval is WIDE (McHugh 2012: N < 30 gives an interval so wide "no agreement" can
+  fall inside it) -- that width is a feature, it tells the reader not to over-trust
+  a point estimate from few items.
+* The bootstrap is SEEDED (``seed`` param, default fixed) and uses stdlib
+  ``random.Random`` so the CI is fully DETERMINISTIC and reproducible: same inputs +
+  same seed -> byte-identical bounds, which every clinescope test and the whole
+  repo's determinism posture rely on. ``n_boot`` (resample count) is also a param.
+* ZERO runtime dependency (the project invariant): kappa is a handful of counts and
+  the bootstrap is stdlib ``random`` + a percentile pick -- no numpy/scipy/sklearn.
+
+Primary sources: Wikipedia "Cohen's kappa" (formula, the 0.4 worked example, the
+p_e=1 undefined case); McHugh ML (2012) Biochem Med 22(3):276-282, PMC3900052 (SE/CI
+worked example, N>=30 guidance); scikit-learn ``cohen_kappa_score`` (NaN convention).
+
+The functions are pure: no I/O, no LLM, deterministic under a fixed seed.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from collections import Counter
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Hashable
+
+# Percentile bounds for the 95% bootstrap CI (2.5th and 97.5th).
+_CI_LOW_PCT = 2.5
+_CI_HIGH_PCT = 97.5
+
+
+@dataclass(frozen=True, slots=True)
+class CohenKappaResult:
+    """Result of :func:`cohen_kappa`.
+
+    Invariants:
+
+    * ``n`` is the number of paired items (``len(labels_a) == len(labels_b)``).
+    * ``p_observed`` is the fraction of items both raters labeled identically;
+      ``p_expected`` is the chance-agreement sum of marginal products. Both in
+      ``[0.0, 1.0]``.
+    * ``defined`` is ``False`` IFF ``p_expected == 1.0`` (the degenerate one-class
+      case, ``kappa = 0/0``). When ``defined`` is ``False``, ``kappa``, ``ci_low``
+      and ``ci_high`` are all ``NaN`` -- honestly undefined, never a silent number.
+    * When ``defined`` is ``True``, ``kappa = (p_observed - p_expected) /
+      (1 - p_expected)`` in ``[-1.0, 1.0]`` (``1.0`` = perfect, ``0.0`` = chance,
+      ``< 0`` = worse than chance).
+    * ``ci_low <= kappa <= ci_high`` is the 95% BOOTSTRAP PERCENTILE interval
+      (``_CI_LOW_PCT`` / ``_CI_HIGH_PCT``), computed by resampling the ``n`` paired
+      items with replacement ``n_boot`` times under ``seed``. Deterministic for a
+      fixed ``(inputs, seed)``. Wider at smaller ``n`` (it reflects sample size).
+      A bootstrap resample that is itself degenerate contributes a ``NaN`` kappa and
+      is dropped from the percentile pool (only defined resamples form the interval).
+    * ``n_boot`` echoes the requested resample count. ``n_boot_effective`` is how many
+      resamples were actually NON-degenerate and thus formed the percentile pool --
+      it is ``<= n_boot`` and drops sharply on a near-degenerate (skewed base-rate)
+      input, where many resamples collapse to one class. A large gap between the two
+      means the interval rests on a THIN, conditionally-biased pool (only resamples
+      that happened to retain both classes) -- read it as a "trust the CI less" flag,
+      surfaced rather than hidden. ``0`` (with ``defined`` still ``True``) means every
+      resample was degenerate and the CI bounds are ``NaN`` despite a defined point
+      estimate. Both are ``0`` when the point estimate itself is undefined.
+    """
+
+    kappa: float
+    defined: bool
+    p_observed: float
+    p_expected: float
+    ci_low: float
+    ci_high: float
+    n: int
+    n_boot: int
+    n_boot_effective: int
+
+
+def cohen_kappa(
+    labels_a: Sequence[Hashable],
+    labels_b: Sequence[Hashable],
+    *,
+    n_boot: int = 2000,
+    seed: int = 12345,
+) -> CohenKappaResult:
+    """Cohen's kappa + a seeded bootstrap 95% CI for two raters over paired labels.
+
+    Args:
+        labels_a: Rater A's label per item.
+        labels_b: Rater B's label per item, aligned 1:1 with ``labels_a``.
+        n_boot: Bootstrap resample count for the CI (default 2000).
+        seed: Seed for the bootstrap RNG, so the CI is reproducible (default fixed).
+
+    Raises:
+        TypeError: If either argument is a ``str`` -- a bare string would be iterated
+            character-by-character as if each char were an item's label and return a
+            plausible-but-wrong kappa, so this one silent-wrong-answer case is guarded.
+        ValueError: If the two label lists differ in length, or are empty (kappa is
+            undefined with no items to agree on).
+    """
+    _agreement_guard_inputs(labels_a, labels_b)
+
+    a = list(labels_a)
+    b = list(labels_b)
+    n = len(a)
+
+    p_observed, p_expected, kappa = _agreement_kappa(a, b)
+    if math.isnan(kappa):
+        nan = math.nan
+        return CohenKappaResult(
+            kappa=nan,
+            defined=False,
+            p_observed=p_observed,
+            p_expected=p_expected,
+            ci_low=nan,
+            ci_high=nan,
+            n=n,
+            n_boot=n_boot,
+            n_boot_effective=0,
+        )
+
+    ci_low, ci_high, n_boot_effective = _agreement_bootstrap_ci(
+        a, b, n_boot=n_boot, seed=seed
+    )
+    return CohenKappaResult(
+        kappa=kappa,
+        defined=True,
+        p_observed=p_observed,
+        p_expected=p_expected,
+        ci_low=ci_low,
+        ci_high=ci_high,
+        n=n,
+        n_boot=n_boot,
+        n_boot_effective=n_boot_effective,
+    )
+
+
+def _agreement_guard_inputs(
+    labels_a: Sequence[Hashable], labels_b: Sequence[Hashable]
+) -> None:
+    # str AND the bytes-like siblings are all "scalar sequences": iterating them
+    # yields per-CHARACTER / per-BYTE items, not per-item labels, so a caller who
+    # passes one gets a plausible-but-wrong kappa with no error (e.g. b"YY" vs
+    # ["Y","Y"] scores perfect agreement as total DISagreement, because list(b"YY")
+    # is [89, 89] ints that never equal the strings). Reject all of them loudly.
+    if isinstance(labels_a, (str, bytes, bytearray, memoryview)) or isinstance(
+        labels_b, (str, bytes, bytearray, memoryview)
+    ):
+        raise TypeError(
+            "labels_a/labels_b must be sequences of per-item labels, not a "
+            "str/bytes/bytearray/memoryview; those iterate character/byte-wise and "
+            "score wrongly -- pass a list/tuple of one label per item"
+        )
+    if len(labels_a) != len(labels_b):
+        raise ValueError(
+            f"labels_a and labels_b must have equal length "
+            f"({len(labels_a)} != {len(labels_b)})"
+        )
+    if len(labels_a) == 0:
+        raise ValueError("cohen_kappa needs at least one paired item, got none")
+
+
+def _agreement_kappa(
+    a: list[Hashable], b: list[Hashable]
+) -> tuple[float, float, float]:
+    """Return ``(p_observed, p_expected, kappa)`` for aligned label lists.
+
+    ``kappa`` is ``NaN`` when ``p_expected == 1`` (the degenerate one-class case;
+    ``0/0``). Nominal / category-agnostic: works for any hashable label set.
+    """
+    n = len(a)
+    agree = sum(1 for la, lb in zip(a, b) if la == lb)
+    p_observed = agree / n
+
+    count_a = Counter(a)
+    count_b = Counter(b)
+    # sorted(..., key=repr) fixes the summation order so the float p_expected is
+    # bit-identical regardless of set-iteration order (the module's whole selling
+    # point is determinism); key=repr keeps it total-orderable for any hashable label.
+    categories = sorted(set(count_a) | set(count_b), key=repr)
+    p_expected = sum((count_a[k] / n) * (count_b[k] / n) for k in categories)
+
+    if p_expected >= 1.0:
+        return p_observed, p_expected, math.nan
+    kappa = (p_observed - p_expected) / (1.0 - p_expected)
+    return p_observed, p_expected, kappa
+
+
+def _agreement_bootstrap_ci(
+    a: list[Hashable], b: list[Hashable], *, n_boot: int, seed: int
+) -> tuple[float, float, int]:
+    """Seeded percentile bootstrap 95% CI for kappa over the paired items.
+
+    Resamples the ``n`` item INDICES with replacement ``n_boot`` times, recomputes
+    kappa on each resample, drops resamples whose kappa is undefined (a degenerate
+    resample -- all-one-class), and returns the 2.5/97.5 percentiles of the rest.
+
+    Returns ``(ci_low, ci_high, n_boot_effective)`` where ``n_boot_effective`` is the
+    number of NON-degenerate resamples that formed the percentile pool (``<= n_boot``);
+    it is surfaced so a caller can see when the interval rests on a thin/biased pool.
+    A ``0`` effective count (every resample degenerate) yields ``NaN`` bounds.
+    """
+    n = len(a)
+    rng = random.Random(seed)
+    kappas: list[float] = []
+    for _ in range(n_boot):
+        idx = [rng.randrange(n) for _ in range(n)]
+        ra = [a[i] for i in idx]
+        rb = [b[i] for i in idx]
+        _, _, k = _agreement_kappa(ra, rb)
+        if not math.isnan(k):
+            kappas.append(k)
+
+    if not kappas:
+        return math.nan, math.nan, 0
+    kappas.sort()
+    return (
+        _agreement_percentile(kappas, _CI_LOW_PCT),
+        _agreement_percentile(kappas, _CI_HIGH_PCT),
+        len(kappas),
+    )
+
+
+def _agreement_percentile(sorted_values: list[float], pct: float) -> float:
+    """Linear-interpolated percentile of an already-sorted list (``pct`` in 0..100).
+
+    Matches the common ``numpy.percentile`` 'linear' method so the interval is a
+    standard percentile bootstrap, implemented in stdlib to keep zero dependencies.
+    """
+    if len(sorted_values) == 1:
+        return sorted_values[0]
+    rank = (pct / 100.0) * (len(sorted_values) - 1)
+    lower = math.floor(rank)
+    upper = math.ceil(rank)
+    if lower == upper:
+        return sorted_values[lower]
+    frac = rank - lower
+    return sorted_values[lower] * (1.0 - frac) + sorted_values[upper] * frac