exegete 0.14.1a0.dev1__py3-none-any.whl

exegete/env_settings.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""The server's settings, read under both spellings (v0.14.1).
+
+Every setting this server reads from its environment is read here and
+nowhere else (tests/test_v0141_compat.py forbids any other environment
+read in the package). Each has a new spelling, starting EXEGETE_, and
+the earlier one, which is still read until v1.0 (names.SETTINGS). The
+one other read here is not a setting: Windows' own folder, SystemRoot,
+from which the transition check starts PowerShell by its full path.
+
+The rule when both spellings are set:
+
+- only the new one: used, silently;
+- only the earlier one: used, and the server's start-up log says once
+  which spelling to use instead, and until when the earlier one works;
+- both, saying the same thing: used, silently;
+- both, saying different things: the server does not start, and says
+  which two spellings disagree (never their values);
+- a workspace is required if either spelling of
+  EXEGETE_WORKSPACE_REQUIRED says 1.
+
+"The same thing" is judged after each value is tidied exactly as its
+read tidies it (spaces stripped where the read strips them, the tool set
+in lower case, a workspace path with `~` expanded, the two switches
+compared as "is it 1", the AI coder name after validate_coder_name), and
+a blank value counts as unset. The value then used is the raw text of
+the spelling chosen, so it behaves exactly as it did before the rename.
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Mapping, NamedTuple, Optional
+
+from . import names
+
+
+class Reading(NamedTuple):
+    """One setting as read: the raw value (None when neither spelling is
+    set), the spelling it came from (the new one when neither is set, so
+    a message has a name to give), whether only the earlier spelling was
+    set, and whether the two spellings disagree."""
+    value: Optional[str]
+    name: str
+    old_only: bool
+    conflict: bool
+
+
+def _blank(value: Optional[str]) -> bool:
+    return value is None or not value.strip()
+
+
+def _toolset(value: str) -> Any:
+    return value.strip().lower()
+
+
+def _coder_name(value: str) -> Any:
+    from .database import validate_coder_name     # no import cycle
+    try:
+        return validate_coder_name(value, "name")
+    except ValueError:
+        return ("not a valid coder name", value.strip())
+
+
+def _path(value: str) -> Any:
+    try:
+        return str(Path(value).expanduser())
+    except (RuntimeError, ValueError):
+        return ("not a path", value)
+
+
+def _required_switch(value: str) -> Any:
+    return value.strip() == "1"
+
+
+def _exact_switch(value: str) -> Any:
+    return value == "1"
+
+
+def _as_given(value: str) -> Any:
+    return value
+
+
+# How each read tidies its value today, which is how the two spellings
+# are compared.
+NORMALISE: Dict[str, Callable[[str], Any]] = {
+    "toolset": _toolset,
+    "ai_coder_name": _coder_name,
+    "workspace": _path,
+    "workspace_required": _required_switch,
+    "allow_unknown_schema": _exact_switch,
+    "project_path": _as_given,
+}
+
+
+def new_name(key: str) -> str:
+    return names.SETTINGS[key][0]
+
+
+def old_name(key: str) -> str:
+    return names.SETTINGS[key][1]
+
+
+def read(key: str, environ: Optional[Mapping[str, str]] = None) -> Reading:
+    """Setting `key` (a key of names.SETTINGS) from `environ`, by default
+    this process's environment."""
+    env = os.environ if environ is None else environ
+    new, old = names.SETTINGS[key]
+    new_raw, old_raw = env.get(new), env.get(old)
+    if not _blank(new_raw) and not _blank(old_raw):
+        normalise = NORMALISE[key]
+        new_value, old_value = normalise(new_raw), normalise(old_raw)
+        if key == "workspace_required":
+            # Required if either says so: the safer reading
+            if not new_value and old_value:
+                return Reading(old_raw, old, False, False)
+            return Reading(new_raw, new, False, False)
+        return Reading(new_raw, new, False, new_value != old_value)
+    if not _blank(old_raw):
+        return Reading(old_raw, old, True, False)
+    if not _blank(new_raw):
+        return Reading(new_raw, new, False, False)
+    # Neither says anything: a blank one is still handed on as it is, so
+    # a read that treats a blank value in its own way (a blank coder name
+    # stops the server) goes on doing so.
+    if new_raw is not None:
+        return Reading(new_raw, new, False, False)
+    if old_raw is not None:
+        return Reading(old_raw, old, False, False)
+    return Reading(None, new, False, False)
+
+
+def value(key: str, environ: Optional[Mapping[str, str]] = None
+          ) -> Optional[str]:
+    """Only the value of `read(key)`."""
+    return read(key, environ).value
+
+
+def conflicts(environ: Optional[Mapping[str, str]] = None) -> List[str]:
+    """The start-up refusal for every setting whose two spellings
+    disagree, in words that name the spellings and never the values."""
+    found = []
+    for key in names.SETTINGS:
+        if read(key, environ).conflict:
+            new, old = names.SETTINGS[key]
+            found.append(
+                f"{new} and {old} are both set and say different things. "
+                f"They are two spellings of one setting ({old} is the "
+                f"earlier one, read until {names.OLD_SPELLINGS_UNTIL}): "
+                f"remove one of them from the host's configuration, or "
+                f"make them the same.")
+    return found
+
+
+def old_spellings_in_use(environ: Optional[Mapping[str, str]] = None
+                         ) -> List[str]:
+    """One log line for each setting given only under its earlier
+    spelling."""
+    lines = []
+    for key in names.SETTINGS:
+        if read(key, environ).old_only:
+            new, old = names.SETTINGS[key]
+            lines.append(
+                f"{old} is the earlier spelling of {new}; it is read "
+                f"until {names.OLD_SPELLINGS_UNTIL}. Use {new} in the "
+                f"host's configuration instead.")
+    return lines
+
+
+def windows_system_root() -> str:
+    """Windows' own folder: SystemRoot, or C:\\Windows when it is unset
+    or not a full path (a relative one would be looked up from the
+    current folder)."""
+    root = os.environ.get("SystemRoot", "")
+    return root if os.path.isabs(root) else "C:\\Windows"

exegete/memo_privacy.py

@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Memo privacy: QualCoder's '#####' personal-note convention.
+
+QualCoder 4.0 lets researchers keep the tail of any memo private from
+the AI: everything from the first '#####' marker onward is never shown
+to the model, and AI memo updates preserve that private suffix
+verbatim (upstream src/qualcoder/ai_memo.py:28-59 at pin 9bddf17,
+applied to tool results in ai_mcp_server.py:210-223). This server
+honours the same convention on every memo it returns to the client and
+on every memo it writes, so a project touched by both tools keeps the
+same promise to the researcher.
+
+PERSONAL_NOTE_MARK, _SEPARATOR_CHARS, split_public_private_memo,
+extract_ai_memo and merge_public_memo are QualCoder's own code, copied
+from ai_memo.py:28-59 at 9bddf17 (author Kai Dröge) statement for
+statement, with local names changed, so that the behaviour is upstream's
+exactly; NOTICE lists them.
+neutralize_marker, rewrite_public_memo and strip_private_memos are this
+project's own. The behaviour the copied functions give:
+
+- Split: the FIRST marker wins; the private suffix starts AT the
+  marker, marker included. Text with no marker is entirely public.
+  A marker at position 0 makes the whole memo private. A marker with
+  nothing after it still creates a (marker-only) private suffix.
+- Extract: the public part is returned byte-for-byte, including any
+  whitespace that preceded the marker. No annotation is added: the
+  strip is silent by owner ruling.
+- Merge (AI writes): the AI-provided text is itself reduced to its
+  public part first, so an AI write can never create a private zone,
+  and never reads, replaces, or deletes an existing one. An existing
+  private suffix is preserved verbatim, re-joined with the whitespace
+  run that separated the old public text from the marker. Writing an
+  empty public text against a memo with a private suffix leaves just
+  the suffix (the row keeps the researcher's private note).
+
+The one deliberate exception, ruled by the owner for parity with
+QualCoder's own exports: file exports (REFI-QDA, codebook files,
+report and CSV files) carry FULL memos, marker and suffix included.
+Export tools disclose this in their descriptions; tools that return
+memo content into the AI conversation always strip.
+"""
+
+import re
+from typing import Any, Callable, Optional, Tuple
+
+# The marker QualCoder 4.0 documents for private memo tails
+# (upstream ai_memo.py:28).
+PERSONAL_NOTE_MARK = "#####"
+
+# Any run of five or more hashes contains the marker. neutralize_marker
+# collapses the whole run: a plain .replace("#####", "####") would turn
+# "######" into "#####" and re-form the marker it meant to remove.
+_MARKER_RUN_RE = re.compile(r"#{5,}")
+
+# Payload keys treated as memo text by strip_private_memos. Journal
+# entries are exposed under 'content' by this server and are stripped
+# at their build site instead ('content' also names file fulltext, so
+# it cannot be a blanket key here).
+_MEMO_KEYS = frozenset({"memo"})
+
+# The whitespace characters upstream treats as the public/private
+# separator when re-joining a preserved suffix (ai_memo.py:57).
+_SEPARATOR_CHARS = " \t\r\n"
+
+
+def split_public_private_memo(memo: Any) -> Tuple[str, str]:
+    """Split a memo into (public_text, private_suffix).
+
+    The private suffix starts at the FIRST marker and includes it;
+    it is empty when no marker is present. None is treated as ''.
+    """
+    text = "" if memo is None else str(memo)
+    mark = text.find(PERSONAL_NOTE_MARK)
+    if mark < 0:
+        return text, ""
+    return text[:mark], text[mark:]
+
+
+def extract_ai_memo(memo: Any) -> str:
+    """The part of a memo that may be shown to the AI (public text)."""
+    public, _private = split_public_private_memo(memo)
+    return public
+
+
+def neutralize_marker(text: Any) -> str:
+    """Make a non-memo string safe to embed in a memo's public zone.
+
+    Code and category names and owner strings are written verbatim into
+    merge provenance blocks. They carry no privacy semantics of their
+    own, so a '#####' inside one would otherwise plant a private zone in
+    the target memo and hide everything after it (including the merged
+    source memo) from every AI read. Every run of five or more hashes is
+    collapsed to four; text without such a run is returned unchanged.
+    None is treated as ''.
+    """
+    return _MARKER_RUN_RE.sub("####", "" if text is None else str(text))
+
+
+def merge_public_memo(existing_memo: Any, new_public_memo: Any) -> str:
+    """Replace a memo's public text, preserving any private suffix.
+
+    The new text is reduced to its own public part first (an AI write
+    cannot smuggle a marker in). With no existing suffix this is a
+    plain replace; with one, the suffix survives verbatim, joined by
+    the whitespace run that preceded the old marker.
+    """
+    existing_public, private_suffix = split_public_private_memo(existing_memo)
+    public = extract_ai_memo(new_public_memo)
+    if private_suffix == "":
+        return public
+    if public == "":
+        return private_suffix
+    trimmed = existing_public.rstrip(_SEPARATOR_CHARS)
+    separator = existing_public[len(trimmed):]
+    return public + separator + private_suffix
+
+
+def rewrite_public_memo(stored: Any,
+                        rewrite: Callable[[str], str]) -> Optional[str]:
+    """Apply `rewrite` to the public part of a note; the private part is
+    carried across verbatim and never read.
+
+    The public part is a PREFIX of the stored text
+    (`split_public_private_memo` returns `text[:mark]`), so an offset in
+    the public part is an offset in the stored note and the two halves
+    concatenate back without a separator. Returns the new stored text,
+    or None when the note would not read back with the rewritten public
+    part: the rewrite made a marker inside the public part, or across its
+    boundary with the private part (a pseudonym ending in a hash, written
+    just before the marker, moves the marker earlier; Brief 2 fix round
+    1, QA-B2-3). Writing it would hide part of the researcher's note
+    from every later AI read, or move a pseudonym behind the marker, so
+    the caller leaves that note as it is and counts it.
+
+    Not `merge_public_memo`, on purpose. That function re-adds the
+    whitespace run that preceded the old marker, and a rewrite that
+    substitutes names never touches that run (a surface form cannot
+    begin or end with whitespace), so the rewritten public part already
+    ends in it: merging would double it. Concatenation gives, byte for
+    byte, what `merge_public_memo(stored, new_public.rstrip(" \\t\\r\\n"))`
+    gives, and `merge_public_memo` itself stays matched to upstream
+    (the pseudonymisation tool's note rewrite, v0.13 Brief 2, 4.3).
+    The old public part can never contain a marker (it ends where the
+    first one begins), so a marker in the new one was MADE by the
+    rewrite: hashes already in the note meeting a pseudonym, or two
+    pseudonyms meeting across a character that is not a word character.
+    One test covers both places: the new stored text, split again, must
+    give back exactly the new public part.
+    """
+    public, private = split_public_private_memo(stored)
+    new_public = rewrite(public)
+    new_stored = new_public + private
+    if split_public_private_memo(new_stored)[0] != new_public:
+        return None
+    return new_stored
+
+
+def strip_private_memos(value: Any) -> Any:
+    """Recursively strip private suffixes from a result payload.
+
+    Walks dicts, lists and tuples; every string under a 'memo' key is
+    reduced to its public part (upstream's payload sanitiser contract,
+    ai_mcp_server.py:210-223). Everything else passes through
+    unchanged. Returns a new structure; the input is not mutated.
+    """
+    if isinstance(value, dict):
+        cleaned = {}
+        for key, item in value.items():
+            if key in _MEMO_KEYS and isinstance(item, str):
+                cleaned[key] = extract_ai_memo(item)
+            else:
+                cleaned[key] = strip_private_memos(item)
+        return cleaned
+    if isinstance(value, list):
+        return [strip_private_memos(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(strip_private_memos(item) for item in value)
+    return value
+
+
+# What every tool that writes the assistant's text into a memo, a note or
+# a journal entry says of that text, in its description (v0.14, the
+# claims audit's item 4).
+MARKER_REFUSED_DESCRIPTION = (
+    "Text containing '#####', QualCoder's private-note marker, is refused "
+    "before anything is written or backed up: what follows the marker is "
+    "the researcher's own, written in QualCoder.")
+
+
+def private_marker_refusal(text: Any, field: str) -> Optional[str]:
+    """The refusal for assistant-supplied text that holds the private-note
+    marker, or None when it holds none (v0.14, the claims audit's item 4).
+
+    QualCoder's own AI server reduces such text to its public part and
+    writes that, silently (`merge_public_memo`, from ai_memo.py). Here that
+    silence destroyed notes: "##### Researcher note" has an empty public
+    part, so update_annotation deleted the annotation, set_memo emptied
+    the memo, and a journal entry lost everything after the marker with
+    no word said. A researcher who knows QualCoder 4.0's convention and
+    asks the assistant to "make this note private" meets exactly that.
+    So this server refuses instead, and every tool that writes the
+    assistant's text into a memo, a note or an entry checks before its
+    backup. The departure from QualCoder is deliberate, for that reason.
+
+    The refusal does not spell the marker out: this server's answers stay
+    free of it, so that a marker in any answer always means a leak.
+    """
+    if not isinstance(text, str) or PERSONAL_NOTE_MARK not in text:
+        return None
+    return (f"{field} contains QualCoder's private-note marker (five hash "
+            f"signs in a row); nothing was written. What follows that "
+            f"marker is the researcher's private note, written in QualCoder "
+            f"and never shown to the assistant, so this server does not "
+            f"write it: send the text without the marker. A note the "
+            f"researcher wants to keep private is written in QualCoder.")

exegete/names.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Every name this program goes by, typed once.
+
+The project was called qualcoder-mcp until 0.14.0-alpha and is called
+Exegete from 0.14.1-alpha. The code reads its runtime names from here,
+messages included, so that each is typed in one place (a name that is
+also part of a path or an import appears there too: the package folder
+`src/exegete`, and `exegete.server:main` in pyproject.toml).
+"""
+
+# The PyPI distribution, the command it installs and the Python package.
+DISTRIBUTION = "exegete"
+COMMAND = "exegete"
+PACKAGE = "exegete"
+
+# The old names, still answered: the old name's package on PyPI carries
+# the command `qualcoder-mcp`, and a two-file stand-in package
+# `qualcoder_mcp` (src/qualcoder_mcp, and its copy under
+# packaging/pypi-old-name) hands over to exegete.server:main, so that
+# `qualcoder-mcp` and `python -m qualcoder_mcp.server` start Exegete.
+OLD_DISTRIBUTION = "qualcoder-mcp"
+OLD_COMMAND = "qualcoder-mcp"
+OLD_PACKAGE = "qualcoder_mcp"
+
+# The server's settings (environment variables), each under its new
+# spelling and the earlier one, which is still read until v1.0: one
+# table, read only through env_settings.read (a test forbids any other
+# environment read in the package). When both spellings are set they
+# must agree, or the server does not start.
+ENV_PREFIX = "EXEGETE_"
+SETTINGS = {
+    "toolset": ("EXEGETE_TOOLSET", "QUALCODER_MCP_TOOLSET"),
+    "ai_coder_name": ("EXEGETE_AI_CODER_NAME",
+                      "QUALCODER_MCP_AI_CODER_NAME"),
+    "workspace": ("EXEGETE_WORKSPACE", "QUALCODER_MCP_WORKSPACE"),
+    "workspace_required": ("EXEGETE_WORKSPACE_REQUIRED",
+                           "QUALCODER_MCP_WORKSPACE_REQUIRED"),
+    "allow_unknown_schema": ("EXEGETE_ALLOW_UNKNOWN_SCHEMA",
+                             "QUALCODER_MCP_ALLOW_UNKNOWN_SCHEMA"),
+    "project_path": ("EXEGETE_PROJECT_PATH", "QUALCODER_PROJECT_PATH"),
+}
+# Until when the earlier spellings are read, as messages say it.
+OLD_SPELLINGS_UNTIL = "v1.0"
+
+# The state folder in the home folder, and the one it is moved from once,
+# whole, at the first real start, with a link left under the old name (a
+# junction on Windows).
+STATE_FOLDER = ".exegete"
+OLD_STATE_FOLDER = ".qualcoder_mcp"
+
+# The workspace inside the Documents folder: where copies and new projects
+# go when no workspace is set (installs from PyPI or from the source; the
+# desktop extension always sets one, `~/QualCoder projects`). The earlier
+# one is never moved or emptied, and the project listing still finds its
+# projects (it walks ~/Documents).
+WORKSPACE_FOLDER = "Exegete projects"
+OLD_WORKSPACE_FOLDER = "Qualcoder MCP Projects"
+
+# The resources' address scheme; the earlier one is still answered, and
+# no longer listed, until v1.0. (QualCoder's own
+# MCP server uses `qualcoder://`, hence the departure.)
+RESOURCE_SCHEME = "exegete"
+OLD_RESOURCE_SCHEME = "qualcoder"
+
+# The server's own name: in the MCP handshake, in what it says, in the
+# `about` of the projects it creates and as the producer of its exports.
+# Fixed by the owner's ruling (29 September 2026).
+SERVER_NAME = "Exegete"