exegete 0.14.1a0.dev1__py3-none-any.whl

exegete/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Exegete: a qualitative analysis application you use in conversation
+with an AI assistant, compatible with QualCoder. An MCP server, formerly
+qualcoder-mcp."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .names import DISTRIBUTION
+
+try:
+    # Single source of truth: the installed package metadata (pyproject.toml).
+    # Not the old name: with the old name's package installed beside this
+    # one, version("qualcoder-mcp") would report that package's version.
+    __version__ = version(DISTRIBUTION)
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0+unknown"

exegete/coder_comparison.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Coder-comparison statistics (v0.12 B3, D2).
+
+QualCoder shows these numbers in two dialogs (`reports.py:820-1395` and
+`report_compare_coder_file.py:52-1143` at the pinned master 9bddf17).
+This module computes them from character sets rather than from segment
+counts, and reproduces QualCoder's own expressions exactly, in its own
+order, so that where the counts agree the values are bit-identical.
+
+Two names, deliberately. `kappa_qualcoder` is QualCoder's "Kappa" column
+reproduced from the same counts; it is NOT Cohen's kappa (its chance term
+is a product of four proportions over the coded characters only, and its
+own docstring at `reports.py:1124` describes a different formula from the
+one the code computes at `:1147`). `kappa_cohen` is the textbook
+statistic over every character in scope. Both are always present, so no
+reader has to guess which one they are looking at, and neither is ever
+called plain `kappa` for our own numbers.
+"""
+
+from typing import Any, Dict, List, Optional, Sequence
+
+# The undefined-value reasons. Never the string "zerodiv", which is what
+# QualCoder's dialog displays in the Kappa column (reports.py:1140,
+# :1006): a reason belongs in a field a reader can act on, not in a
+# number's place.
+NOTE_NO_CHARACTERS = "no characters in scope"
+NOTE_NO_VARIANCE = (
+    "undefined: neither coder applied this code in the selected scope "
+    "(no variance)")
+NOTE_BOTH_CODED_ALL = (
+    "kappa_cohen undefined: both coders coded every character in scope "
+    "(no variance); kappa_qualcoder is 1.0 by QualCoder's formula")
+MEAN_COHEN_FEWER_CODES_NOTE = (
+    "codes_included counts the codes behind kappa_qualcoder. kappa_cohen "
+    "is undefined for codes where both coders coded every character in "
+    "scope, so its mean is over codes_included_kappa_cohen codes "
+    "instead. The per-code rows say which.")
+
+
+def kappa_qualcoder(coded_a: int, coded_b: int, both: int) -> Optional[float]:
+    """QualCoder's "Kappa" column, expression for expression.
+
+    A verbatim transcription of `reports.py:1140-1151` (identical at
+    `report_compare_coder_file.py:818-830` and at
+    `3.8.2:reports.py:812-820`), including the order of the operations,
+    so the floating-point result is the same one the dialog shows. The
+    `ZeroDivisionError` branch fires only when neither coder applied the
+    code, which is the only undefined case here: the chance term is at
+    most 1/16, so `1 - Pe` is never zero.
+    """
+    try:
+        unique_codings = coded_a + coded_b - both
+        Po = both / unique_codings
+        Pyes = coded_a / unique_codings * coded_b / unique_codings
+        Pno = ((unique_codings - coded_a) / unique_codings
+               * (unique_codings - coded_b) / unique_codings)
+        Pe = Pyes * Pno
+        return round((Po - Pe) / (1 - Pe), 4)
+    except ZeroDivisionError:
+        return None
+
+
+def kappa_cohen(characters: int, coded_a: int, coded_b: int,
+                both: int) -> Optional[float]:
+    """Cohen's kappa on the 2x2 table over every character in scope.
+
+    Undefined exactly when there is no variance to correct for: both
+    coders coded nothing, or both coded everything. Sensitive to the
+    amount of uncoded text, which is the prevalence effect QualCoder's
+    author was reacting to when they wrote their own formula.
+    """
+    n = characters
+    if n <= 0:
+        return None
+    neither = n - coded_a - coded_b + both
+    Po = (both + neither) / n
+    Pe = (coded_a / n) * (coded_b / n) + ((n - coded_a) / n) * ((n - coded_b) / n)
+    if Pe == 1:
+        return None
+    return round((Po - Pe) / (1 - Pe), 4)
+
+
+def statistics(characters: int, coded_a: int, coded_b: int,
+               both: int) -> Dict[str, Any]:
+    """Every field of one comparison row, from four counts.
+
+    Percentages use QualCoder's expressions and its 2-decimal rounding;
+    the kappas use 4 decimals, as its own code does.
+    """
+    a_only = coded_a - both
+    b_only = coded_b - both
+    union = coded_a + coded_b - both
+    neither = characters - union
+    row: Dict[str, Any] = {
+        "characters": characters,
+        "coded_a": coded_a,
+        "coded_b": coded_b,
+        "both": both,
+        "a_only": a_only,
+        "b_only": b_only,
+        "neither": neither,
+    }
+    if characters <= 0:
+        row.update({
+            "agreement_pct": None, "dual_coded_pct": None,
+            "uncoded_pct": None, "disagreement_pct": None,
+            "agree_coded_only_pct": None,
+            "kappa_qualcoder": None, "kappa_cohen": None,
+            "kappa_note": NOTE_NO_CHARACTERS,
+        })
+        return row
+
+    agreement = round(100 * (both + neither) / characters, 2)
+    row["agreement_pct"] = agreement
+    row["dual_coded_pct"] = round(100 * both / characters, 2)
+    row["uncoded_pct"] = round(100 * neither / characters, 2)
+    row["disagreement_pct"] = round(100 - agreement, 2)
+    row["agree_coded_only_pct"] = (round(100 * both / union, 2)
+                                   if union else None)
+    row["kappa_qualcoder"] = kappa_qualcoder(coded_a, coded_b, both)
+    row["kappa_cohen"] = kappa_cohen(characters, coded_a, coded_b, both)
+    if union == 0:
+        row["kappa_note"] = NOTE_NO_VARIANCE
+    elif coded_a == coded_b == characters:
+        row["kappa_note"] = NOTE_BOTH_CODED_ALL
+    return row
+
+
+# ---------------------------------------------------------------------------
+# The GUI-divergence port (D2 3.8): QualCoder's own multiplicity counting
+# ---------------------------------------------------------------------------
+# This exists ONLY so a result can say what QualCoder's dialog would show
+# for the same data when a coder's own segments of one code overlap, and
+# so the parity tests can compare the two. It is never the headline
+# number. A verbatim port of the counting loop and statistics of
+# `reports.py:1061-1152` (cited also to `3.8.2:reports.py:705-822`).
+
+def qualcoder_report_values(text_length: int,
+                            spans_a: Sequence[Sequence[int]],
+                            spans_b: Sequence[Sequence[int]]) -> Dict[str, Any]:
+    """What QualCoder's Coder comparison report would show.
+
+    A verbatim port of `reports.py:1061-1108` at 9bddf17 (the same code at
+    `3.8.2:reports.py:705-765`), including the details that make it differ
+    from ours: ONE shared array is incremented once per coded character
+    PER SEGMENT for both coders, so two overlapping segments of the same
+    coder push a character to 2; "dual coded" is then literally `count ==
+    2`, so such a character is counted as agreement although only one
+    coder coded it, and a character covered by three segments is counted
+    as neither uncoded, single nor dual and vanishes from the
+    percentages. Characters beyond the end of the text are dropped by its
+    `IndexError` catch (`:1067-1073`).
+    """
+    coded0 = coded1 = 0
+    char_list = [0] * max(0, int(text_length))
+    for pos0, pos1 in spans_a:
+        for char in range(int(pos0), int(pos1)):
+            if 0 <= char < text_length:
+                char_list[char] += 1
+                coded0 += 1
+    for pos0, pos1 in spans_b:
+        for char in range(int(pos0), int(pos1)):
+            if 0 <= char < text_length:
+                char_list[char] += 1
+                coded1 += 1
+    uncoded = single_coded = dual_coded = 0
+    for char in char_list:
+        if char == 0:
+            uncoded += 1
+        if char == 1:
+            single_coded += 1
+        if char == 2:
+            dual_coded += 1
+    values: Dict[str, Any] = {"coded0": coded0, "coded1": coded1,
+                              "dual_coded": dual_coded,
+                              "single_coded": single_coded,
+                              "uncoded": uncoded,
+                              "characters": int(text_length)}
+    if text_length:
+        agreement = round(100 * (dual_coded + uncoded) / text_length, 2)
+        values["agreement_pct"] = agreement
+        values["dual_coded_pct"] = round(100 * dual_coded / text_length, 2)
+        values["uncoded_pct"] = round(100 * uncoded / text_length, 2)
+        values["disagreement_pct"] = round(100 - agreement, 2)
+        try:
+            values["agree_coded_only_pct"] = round(
+                100 * dual_coded / (dual_coded + single_coded), 2)
+        except ZeroDivisionError:
+            # Upstream shows the string "zero div" here; a reason belongs
+            # in a note, so ours is null and the note says why (D2 3.7).
+            values["agree_coded_only_pct"] = None
+    else:
+        values["agreement_pct"] = None
+        values["dual_coded_pct"] = None
+        values["uncoded_pct"] = None
+        values["disagreement_pct"] = None
+        values["agree_coded_only_pct"] = None
+    # The GUI's own column name, reproduced under the GUI's own name
+    # inside this disclosure block only (X3).
+    values["kappa"] = kappa_qualcoder(coded0, coded1, dual_coded)
+    return values
+
+
+SAME_CODER_OVERLAP_NOTE = (
+    "QualCoder's Coder comparison report counts a character once per "
+    "segment, so overlapping segments of the same code by the same coder "
+    "change its numbers; the values above are what QualCoder would show. "
+    "compare_coders counts each character once per coder.")

exegete/cursors.py

@@ -0,0 +1,218 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Deterministic keyset cursors for paged reads (v0.12, D4 3.2).
+
+A cursor is a POSITION, not a permission and not a stored result set. It
+carries the sort key of the last item a page returned, and the next page
+is computed by re-querying for the first item that sorts strictly after
+it. Nothing is stored anywhere: no server-side result set, no session
+file, no memory. A host that recycles the process between turns can hand
+the same cursor back and get the same continuation, and two hosts walking
+one project do not interfere.
+
+These tokens are deliberately NOT the authorisation tokens of
+`preview_tokens.py` (D4 3.11, H1). Those prove that a preview of a
+destructive operation was computed and are signed; these say "carry on
+from here" and are signed by nothing, because a caller who forges a
+position gets a page it could have asked for anyway (D4 5.4). The two
+prefixes, `c1.` and `qcp1.`, stay distinct so neither is ever mistaken
+for the other.
+
+The token is bound to the tool and to the call's other arguments through
+a fingerprint, so a cursor cannot be replayed against a different query,
+a different coder filter, or a different tool.
+"""
+
+import base64
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+CURSOR_PREFIX = "c1."
+# A key of five short values plus the fingerprint fits in well under 200
+# characters; the cap is a hostile-input bound, not a design limit.
+CURSOR_MAX_LENGTH = 1024
+
+# Tool tags. Short because the token travels in every paged result.
+TAG_SEARCH_FILES = "sf"
+# "sct2" since v0.14 (reads and exports, fix round 4): the key's file name
+# is its stored bytes as hex, where "sct" carried the name as text. Under
+# one tag a name made only of hex digits ("01", "2024", "beef") in a
+# cursor minted before the change was read as bytes, and the walk
+# repeated or skipped rows; with its own tag every earlier cursor gets
+# the one cursor refusal, and the search starts again.
+TAG_SEARCH_CODED_TEXT = "sct2"
+TAG_CODED_SEGMENTS = "gcs"
+
+CURSOR_TOO_LONG = "cursor is too long (limit 1024 characters)."
+# The running total a cursor carries is the caller's claim about the
+# pages BEFORE this one; nothing here can verify it, and it is reported
+# in the result as `returned_so_far`. Bound it so a tampered cursor
+# cannot put an arbitrary integer in front of a researcher as though
+# this server had counted it. The bound is far above any real walk: a
+# project with this many coded segments would exhaust the character
+# budget thousands of pages earlier (fix round 4).
+CURSOR_MAX_RETURNED_SO_FAR = 10_000_000
+
+DATABASE_CHANGED_NOTE = (
+    "The project database changed after this cursor was issued; positions "
+    "are recomputed on every page, but counts and ordering may differ from "
+    "the earlier pages.")
+
+
+class CursorError(ValueError):
+    """An unusable cursor. The message never echoes the token."""
+
+
+def cursor_invalid_message(tool_name: str) -> str:
+    """The one text every unusable cursor gets (D4 3.7).
+
+    Garbage, a token minted for another tool, a token minted for other
+    arguments and a token whose key has the wrong shape are one failure
+    from the caller's point of view, and the answer is the same: start
+    again without the cursor. The token is never echoed back, so a
+    tampered value cannot smuggle text into the conversation.
+    """
+    return (f"cursor is not valid for {tool_name} with these arguments. "
+            f"Call the tool again without cursor to start from the "
+            f"beginning.")
+
+
+def _canonical(obj: Any) -> str:
+    """The canonical JSON this module hashes and encodes."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=True)
+
+
+def fingerprint_arguments(tool: str, arguments: Dict[str, Any]) -> str:
+    """A 16-hex digest binding a cursor to this call's other arguments.
+
+    The caller passes the arguments already canonicalised (defaults
+    filled in, order-irrelevant lists sorted and de-duplicated, `coder`
+    normalised), so a call that means the same thing produces the same
+    fingerprint whatever order the host serialised it in. It carries no
+    authority: it decides only whether a cursor belongs to this query.
+    """
+    payload = {"t": tool, "a": arguments}
+    return hashlib.sha256(_canonical(payload).encode("utf-8")).hexdigest()[:16]
+
+
+def database_stamp(qda_path: Any) -> Optional[List[int]]:
+    """`(st_mtime_ns, st_size)` of data.qda, or None when unavailable.
+
+    Both values travel INSIDE the cursor and therefore into the
+    transcript; PRIVACY.md enumerates them, and `list_available_projects`
+    already reports the same two in plain form (fix round 4).
+
+    A HEURISTIC (D4 3.2.5) and labelled as one wherever it is reported:
+    mtime granularity, journal and WAL side files, and copy tools that
+    preserve timestamps all mean a changed database can look unchanged
+    and an unchanged one can look changed. Correctness never depends on
+    it; it only lets a page say that the ground may have moved.
+    """
+    try:
+        st = os.stat(str(qda_path))
+    except OSError:
+        return None
+    return [st.st_mtime_ns, st.st_size]
+
+
+def encode_cursor(tool_tag: str, fingerprint: str, key: Sequence[Any],
+                  returned_so_far: int,
+                  stamp: Optional[List[int]]) -> str:
+    """Mint a cursor for the item last returned."""
+    payload = {
+        "t": tool_tag,
+        "f": fingerprint,
+        "k": list(key),
+        "n": int(returned_so_far),
+        "d": list(stamp) if stamp else [],
+    }
+    raw = _canonical(payload).encode("utf-8")
+    return CURSOR_PREFIX + base64.urlsafe_b64encode(raw).decode(
+        "ascii").rstrip("=")
+
+
+def decode_cursor(token: Any, tool_tag: str, fingerprint: str,
+                  key_shape: Sequence[type]) -> Tuple[List[Any], int,
+                                                      Optional[List[int]]]:
+    """Read a cursor, or raise CursorError.
+
+    Every check is a refusal, never a repair: the prefix, the length, the
+    base64, the JSON shape, the exact key set, the tool tag, the
+    fingerprint of the current arguments, the shape of the sort key and a
+    non-negative count. A cursor that fails any of them is not a cursor
+    for this call.
+
+    Returns:
+        (key, returned_so_far, stamp)
+    """
+    if not isinstance(token, str):
+        raise CursorError("cursor must be a string")
+    token = token.strip()
+    if len(token) > CURSOR_MAX_LENGTH:
+        raise CursorError(CURSOR_TOO_LONG)
+    if not token.startswith(CURSOR_PREFIX):
+        raise CursorError("cursor has an unknown format")
+    body = token[len(CURSOR_PREFIX):]
+    padding = "=" * (-len(body) % 4)
+    try:
+        raw = base64.urlsafe_b64decode(body + padding)
+        data = json.loads(raw.decode("utf-8"))
+    except Exception as e:                       # noqa: BLE001 - any failure
+        raise CursorError("cursor could not be decoded") from e
+    if not isinstance(data, dict) or set(data) != {"t", "f", "k", "n", "d"}:
+        raise CursorError("cursor has the wrong shape")
+    if data["t"] != tool_tag:
+        raise CursorError("cursor belongs to another tool")
+    if not isinstance(data["f"], str) or data["f"] != fingerprint:
+        raise CursorError("cursor belongs to another query")
+    key = data["k"]
+    if not isinstance(key, list) or len(key) != len(key_shape):
+        raise CursorError("cursor key has the wrong shape")
+    for value, expected in zip(key, key_shape):
+        if expected is str:
+            if not isinstance(value, str):
+                raise CursorError("cursor key has the wrong shape")
+        elif expected is int:
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise CursorError("cursor key has the wrong shape")
+        elif expected is object:
+            # A nullable text column: a string or None
+            if value is not None and not isinstance(value, str):
+                raise CursorError("cursor key has the wrong shape")
+    n = data["n"]
+    if (not isinstance(n, int) or isinstance(n, bool) or n < 0
+            or n > CURSOR_MAX_RETURNED_SO_FAR):
+        raise CursorError("cursor count is not a count")
+    stamp = data["d"]
+    if not isinstance(stamp, list) or not all(
+            isinstance(v, int) and not isinstance(v, bool) for v in stamp):
+        raise CursorError("cursor stamp has the wrong shape")
+    return key, n, (stamp or None)
+
+
+def page_block(limit: int, returned: int, returned_so_far: int,
+               has_more: bool, next_cursor: Optional[str],
+               exhaustive: bool) -> Dict[str, Any]:
+    """The `page` block every paged result carries (D4 3.2.7).
+
+    `returned`, `has_more` and `exhaustive` are computed on this page.
+    `returned_so_far` is this page's `returned` added to the count the
+    CURSOR carried, so on any page but the first it rests on a value
+    the caller supplied and nothing here can check. It is bounded at
+    decode (CURSOR_MAX_RETURNED_SO_FAR) so a tampered cursor cannot put
+    an arbitrary integer in a result, and PRIVACY.md says plainly where
+    the number comes from; a stronger guarantee would mean signing
+    cursors, which D4 3.11 deliberately does not do, because a caller
+    who forges a POSITION only gets a page it could have asked for.
+    """
+    return {
+        "limit": limit,
+        "returned": returned,
+        "returned_so_far": returned_so_far,
+        "has_more": has_more,
+        "next_cursor": next_cursor,
+        "exhaustive": exhaustive,
+    }