diff --git a/pyproject.toml b/pyproject.toml index cbbb3bd..59e0e9e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -279,6 +279,6 @@ link-mode = "copy" python-preference = "managed" [tool.uv.build-backend] -module-name = ["aco", "api", "bcda", "bib", "bls", "ccw", "cli", "cms", "conf", "lead", "llm", "mail", "nlm", "opps", "perf", "pfs", "prisma", "qpp", "rec", "rex", "sem"] +module-name = ["aco", "api", "bcda", "bib", "bls", "ccw", "cli", "cms", "conf", "focus", "lead", "llm", "mail", "nlm", "opps", "perf", "pfs", "prisma", "qpp", "rec", "rex", "sem"] namespace = true source-exclude = ["compose.yml","infra/**","data/**","notebooks/**","tuva/**","assets/**","docs/**","dev/**","bundle/**","cloud/**"] diff --git a/src/focus/__init__.py b/src/focus/__init__.py new file mode 100644 index 0000000..09ea9e5 --- /dev/null +++ b/src/focus/__init__.py @@ -0,0 +1,5 @@ +"""Deep-focus review: protocols now, annotations and tags beside them.""" + +from focus.protocols import Label, Protocol, available, load + +__all__ = ["Label", "Protocol", "available", "load"] diff --git a/src/focus/protocols/__init__.py b/src/focus/protocols/__init__.py new file mode 100644 index 0000000..c0169a6 --- /dev/null +++ b/src/focus/protocols/__init__.py @@ -0,0 +1,171 @@ +"""Review protocols are YAML label sets. ``protocols/*.yaml`` is the source. + +``prisma-screen.yaml`` carries ``from: lead.review.codes`` instead of a +label list. :func:`load` expands that marker from the live LEAD codebooks +so a codebook edit shows up here without a copied list. + +A ``protocols.py`` module cannot sit next to this directory, so the loader +lives in the package. ``from focus.protocols import load`` is unchanged. +""" + +from __future__ import annotations + +import re +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +import yaml + +_ID = re.compile(r"^[a-z0-9-]+$") +_KEYS = "1234567890abcdefghijklmnopqrstuvwxyz" +_FROM = "lead.review.codes" + +ROOT = Path(__file__).parent + + +@dataclass(frozen=True) +class Label: + """One keyboard-selectable label. ``tag`` drives the bib ``hl:`` tag.""" + + id: str + text: str + key: str + tag: str + + +@dataclass(frozen=True) +class Protocol: + """A versioned label set. ``version`` is the number stored on an annotation.""" + + name: str + version: int + title: str + scope: str + labels: tuple[Label, ...] + + def label(self, label_id: str) -> Label | None: + """The label with this id, or ``None``.""" + for item in self.labels: + if item.id == label_id: + return item + return None + + +def available() -> list[str]: + """Protocol names, sorted, from the YAML files next to this module.""" + return sorted(path.stem for path in ROOT.glob("*.yaml")) + + +def load(name: str) -> Protocol: + """Load and validate one protocol. A bad file raises ``ValueError`` + whose message contains the filename.""" + path = ROOT / f"{name}.yaml" + if not path.is_file(): + raise ValueError(f"{path.name}: no such protocol") + try: + data = yaml.safe_load(path.read_text(encoding="utf-8")) + except yaml.YAMLError as exc: + raise ValueError(f"{path.name}: invalid YAML: {exc}") from exc + try: + return _protocol(name, data) + except ValueError as exc: + raise ValueError(f"{path.name}: {exc}") from exc + + +def _protocol(name: str, data: Any) -> Protocol: + if not isinstance(data, dict): + raise ValueError("protocol is not a mapping") + got = data.get("name") + if not isinstance(got, str) or not got: + raise ValueError("name is missing") + if got != name: + raise ValueError(f"name {got!r} does not match the file") + version = data.get("version") + if type(version) is not int: + raise ValueError("version must be an int") + title = _text(data, "title") + scope = _text(data, "scope") + marker = data.get("from") + if marker is not None and "labels" in data: + raise ValueError("from and labels are both set") + if marker is not None: + if marker != _FROM: + raise ValueError(f"from must be {_FROM}") + raw_labels = _reason_labels() + else: + raw_labels = data.get("labels") + if not isinstance(raw_labels, list) or not raw_labels: + raise ValueError("labels must be a non-empty list") + return Protocol( + name=name, + version=version, + title=title, + scope=scope, + labels=_labels(name, raw_labels), + ) + + +def _text(data: dict, field: str) -> str: + value = data.get(field) + if not isinstance(value, str) or not value: + raise ValueError(f"{field} is missing") + return value + + +def _reason_labels() -> list[dict[str, str]]: + """Union of ``reason_codes`` across the LEAD projects, codebook order, + first project's sentence kept when a code repeats. Keys are assigned + here because the codebook does not carry shortcuts.""" + from lead.review.codes import PROJECTS, reason_choices, reason_codes + + sentences: dict[str, str] = {} + ordered: list[str] = [] + seen: set[str] = set() + for project in PROJECTS: + for code, sentence in reason_choices(project): + sentences.setdefault(code, sentence) + for code in reason_codes(project): + if code not in seen: + seen.add(code) + ordered.append(code) + if len(ordered) > len(_KEYS): + raise ValueError("more labels than single-character keys") + missing = [code for code in ordered if code not in sentences] + if missing: + raise ValueError(f"reason code has no sentence: {missing[0]}") + return [ + {"id": code, "text": sentences[code], "key": _KEYS[i]} + for i, code in enumerate(ordered) + ] + + +def _labels(protocol: str, raw: list[Any]) -> tuple[Label, ...]: + found: list[Label] = [] + ids: set[str] = set() + keys: set[str] = set() + for item in raw: + if not isinstance(item, dict): + raise ValueError("label is not a mapping") + label_id = item.get("id") + text = item.get("text") + key = item.get("key") + if not isinstance(label_id, str) or not _ID.fullmatch(label_id): + raise ValueError(f"id {label_id!r} must match {_ID.pattern}") + if not isinstance(text, str) or not text: + raise ValueError(f"label {label_id} is missing text") + if not isinstance(key, str) or len(key) != 1: + raise ValueError(f"key for {label_id} must be one character") + if label_id in ids: + raise ValueError(f"duplicate label id {label_id!r}") + if key in keys: + raise ValueError(f"duplicate key {key!r}") + ids.add(label_id) + keys.add(key) + tag = item.get("tag", None) + if tag is None: + tag = f"hl:{protocol}:{label_id}" + elif not isinstance(tag, str) or not tag: + raise ValueError(f"tag for {label_id} must be a non-empty string") + found.append(Label(id=label_id, text=text, key=key, tag=tag)) + return tuple(found) diff --git a/src/focus/protocols/cms-disposition.yaml b/src/focus/protocols/cms-disposition.yaml new file mode 100644 index 0000000..a7463e4 --- /dev/null +++ b/src/focus/protocols/cms-disposition.yaml @@ -0,0 +1,17 @@ +name: cms-disposition +version: 1 +title: CMS disposition +scope: How CMS disposed of the point in the final rule. +labels: + - id: finalized-as-proposed + text: Finalized as proposed + key: "1" + - id: finalized-with-modifications + text: Finalized with modifications + key: "2" + - id: considered-for-future-rulemaking + text: Considered for future rulemaking + key: "3" + - id: other + text: Other + key: "4" diff --git a/src/focus/protocols/code-family.yaml b/src/focus/protocols/code-family.yaml new file mode 100644 index 0000000..3d52880 --- /dev/null +++ b/src/focus/protocols/code-family.yaml @@ -0,0 +1,24 @@ +# Placeholder. pfs.elements.ElementType (actor, time, period, ...) is a +# descriptor vocabulary, not the span labels of a family biography, and +# the dossier design does not name a closed set. These five stand in +# until that set is settled. +name: code-family +version: 1 +title: Code family +scope: A span in a source for a code family. Placeholder labels. +labels: + - id: code + text: Code + key: "1" + - id: descriptor-change + text: Descriptor change + key: "2" + - id: payment-change + text: Payment change + key: "3" + - id: rationale + text: Rationale + key: "4" + - id: other + text: Other + key: "5" diff --git a/src/focus/protocols/comment-stance.yaml b/src/focus/protocols/comment-stance.yaml new file mode 100644 index 0000000..2b981d1 --- /dev/null +++ b/src/focus/protocols/comment-stance.yaml @@ -0,0 +1,14 @@ +name: comment-stance +version: 1 +title: Comment stance +scope: A commenter's position on the proposal being read. +labels: + - id: support + text: Support + key: "1" + - id: support-with-modifications + text: Support with modifications + key: "2" + - id: do-not-support + text: Do not support + key: "3" diff --git a/src/focus/protocols/prisma-screen.yaml b/src/focus/protocols/prisma-screen.yaml new file mode 100644 index 0000000..b3870e8 --- /dev/null +++ b/src/focus/protocols/prisma-screen.yaml @@ -0,0 +1,7 @@ +name: prisma-screen +version: 1 +title: PRISMA screen +scope: > + Evidence for an include or exclude on a LEAD screening item. + Labels expand at load from lead.review.codes, one per reason code. +from: lead.review.codes diff --git a/tests/focus/__init__.py b/tests/focus/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/focus/test_protocols.py b/tests/focus/test_protocols.py new file mode 100644 index 0000000..33ee399 --- /dev/null +++ b/tests/focus/test_protocols.py @@ -0,0 +1,311 @@ +"""Review protocols: YAML label sets, validation, and PRISMA expansion.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest +import yaml + +from focus import protocols +from lead.review.codes import PROJECTS, reason_choices, reason_codes + +_KEYS = "1234567890abcdefghijklmnopqrstuvwxyz" + + +def _write(directory: Path, name: str, body: str) -> None: + (directory / f"{name}.yaml").write_text(body, encoding="utf-8") + + +def _base(**overrides: object) -> dict: + data: dict = { + "name": "sample", + "version": 1, + "title": "Sample", + "scope": "A test protocol.", + "labels": [ + {"id": "alpha", "text": "Alpha", "key": "1"}, + {"id": "beta", "text": "Beta", "key": "2", "tag": "custom:beta"}, + ], + } + data.update(overrides) + return data + + +def _dump(directory: Path, name: str, data: dict) -> None: + _write(directory, name, yaml.safe_dump(data)) + + +def test_available_lists_shipped_names(): + assert protocols.available() == [ + "cms-disposition", + "code-family", + "comment-stance", + "prisma-screen", + ] + + +def test_comment_stance_labels_and_default_tags(): + proto = protocols.load("comment-stance") + assert proto.name == "comment-stance" + assert proto.version == 1 + assert proto.title == "Comment stance" + assert proto.scope + assert [(lb.id, lb.key) for lb in proto.labels] == [ + ("support", "1"), + ("support-with-modifications", "2"), + ("do-not-support", "3"), + ] + assert [lb.tag for lb in proto.labels] == [ + "hl:comment-stance:support", + "hl:comment-stance:support-with-modifications", + "hl:comment-stance:do-not-support", + ] + assert proto.label("support") == proto.labels[0] + assert proto.label("missing") is None + + +def test_cms_disposition_labels(): + proto = protocols.load("cms-disposition") + assert [lb.id for lb in proto.labels] == [ + "finalized-as-proposed", + "finalized-with-modifications", + "considered-for-future-rulemaking", + "other", + ] + assert all(lb.tag == f"hl:cms-disposition:{lb.id}" for lb in proto.labels) + + +def test_code_family_placeholder_labels(): + """Element names for a family biography are not a closed label set. + These five are the plan's placeholder.""" + proto = protocols.load("code-family") + assert [lb.id for lb in proto.labels] == [ + "code", + "descriptor-change", + "payment-change", + "rationale", + "other", + ] + + +def test_prisma_screen_expands_real_reason_codes(): + proto = protocols.load("prisma-screen") + expected: list[str] = [] + seen: set[str] = set() + sentences: dict[str, str] = {} + for project in PROJECTS: + for code, sentence in reason_choices(project): + sentences.setdefault(code, sentence) + for code in reason_codes(project): + if code not in seen: + seen.add(code) + expected.append(code) + assert [lb.id for lb in proto.labels] == expected + assert {lb.id for lb in proto.labels} == { + code for project in PROJECTS for code in reason_codes(project) + } + assert [lb.text for lb in proto.labels] == [sentences[i] for i in expected] + assert [lb.key for lb in proto.labels] == list(_KEYS[: len(expected)]) + assert all(lb.tag == f"hl:prisma-screen:{lb.id}" for lb in proto.labels) + + +def test_explicit_tag_is_kept(tmp_path: Path, monkeypatch: pytest.MonkeyPatch): + monkeypatch.setattr(protocols, "ROOT", tmp_path) + _dump(tmp_path, "sample", _base()) + proto = protocols.load("sample") + assert proto.labels[0].tag == "hl:sample:alpha" + assert proto.labels[1].tag == "custom:beta" + assert protocols.available() == ["sample"] + + +def test_missing_protocol_names_the_file(): + with pytest.raises(ValueError, match=r"missing\.yaml"): + protocols.load("missing") + + +@pytest.mark.parametrize( + "mutate", + [ + "duplicate-id", + "duplicate-key", + "long-key", + "empty-key", + "int-key", + "bad-id", + "empty-id", + "missing-text", + "label-not-mapping", + "missing-labels", + "empty-labels", + "name-mismatch", + "version-str", + "version-bool", + "missing-title", + "title-not-str", + "missing-scope", + "scope-not-str", + "not-a-mapping", + "bad-from", + "from-and-labels", + "empty-tag", + "tag-not-str", + "missing-name", + ], +) +def test_bad_file_raises_with_filename( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, mutate: str +): + monkeypatch.setattr(protocols, "ROOT", tmp_path) + data = _base() + raw: str | None = None + if mutate == "duplicate-id": + data["labels"][1]["id"] = "alpha" + elif mutate == "duplicate-key": + data["labels"][1]["key"] = "1" + elif mutate == "long-key": + data["labels"][0]["key"] = "ab" + elif mutate == "empty-key": + data["labels"][0]["key"] = "" + elif mutate == "int-key": + data["labels"][0]["key"] = 1 + elif mutate == "bad-id": + data["labels"][0]["id"] = "Bad_Id" + elif mutate == "empty-id": + data["labels"][0]["id"] = "" + elif mutate == "missing-text": + del data["labels"][0]["text"] + elif mutate == "label-not-mapping": + data["labels"][0] = "alpha" + elif mutate == "missing-labels": + del data["labels"] + elif mutate == "empty-labels": + data["labels"] = [] + elif mutate == "name-mismatch": + data["name"] = "other" + elif mutate == "version-str": + data["version"] = "1" + elif mutate == "version-bool": + data["version"] = True + elif mutate == "missing-title": + del data["title"] + elif mutate == "title-not-str": + data["title"] = 1 + elif mutate == "missing-scope": + del data["scope"] + elif mutate == "scope-not-str": + data["scope"] = 1 + elif mutate == "not-a-mapping": + raw = "- just\n- a\n- list\n" + elif mutate == "bad-from": + del data["labels"] + data["from"] = "somewhere.else" + elif mutate == "from-and-labels": + data["from"] = "lead.review.codes" + elif mutate == "empty-tag": + data["labels"][0]["tag"] = "" + elif mutate == "tag-not-str": + data["labels"][0]["tag"] = 3 + elif mutate == "missing-name": + del data["name"] + else: + raise AssertionError(mutate) + if raw is None: + _dump(tmp_path, "sample", data) + else: + _write(tmp_path, "sample", raw) + with pytest.raises(ValueError, match=r"sample\.yaml"): + protocols.load("sample") + + +def test_invalid_yaml_names_the_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch): + monkeypatch.setattr(protocols, "ROOT", tmp_path) + _write(tmp_path, "sample", "name: [\n") + with pytest.raises(ValueError, match=r"sample\.yaml"): + protocols.load("sample") + + +def test_expansion_rejects_more_labels_than_keys( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + monkeypatch.setattr(protocols, "ROOT", tmp_path) + _dump( + tmp_path, + "wide", + { + "name": "wide", + "version": 1, + "title": "Wide", + "scope": "too many", + "from": "lead.review.codes", + }, + ) + codes = [f"c{i}" for i in range(len(_KEYS) + 1)] + monkeypatch.setattr( + "lead.review.codes.PROJECTS", + ("only",), + ) + monkeypatch.setattr( + "lead.review.codes.reason_codes", + lambda _project: tuple(codes), + ) + monkeypatch.setattr( + "lead.review.codes.reason_choices", + lambda _project: tuple((code, f"{code}.") for code in codes), + ) + with pytest.raises(ValueError, match=r"wide\.yaml"): + protocols.load("wide") + + +def test_expansion_rejects_a_code_with_no_sentence( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + monkeypatch.setattr(protocols, "ROOT", tmp_path) + _dump( + tmp_path, + "wide", + { + "name": "wide", + "version": 1, + "title": "Wide", + "scope": "no sentence", + "from": "lead.review.codes", + }, + ) + monkeypatch.setattr("lead.review.codes.PROJECTS", ("only",)) + monkeypatch.setattr("lead.review.codes.reason_codes", lambda _p: ("orphan",)) + monkeypatch.setattr("lead.review.codes.reason_choices", lambda _p: ()) + with pytest.raises(ValueError, match=r"wide\.yaml"): + protocols.load("wide") + + +def test_expansion_failure_names_the_file( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + monkeypatch.setattr(protocols, "ROOT", tmp_path) + _dump( + tmp_path, + "wide", + { + "name": "wide", + "version": 1, + "title": "Wide", + "scope": "boom", + "from": "lead.review.codes", + }, + ) + + def _boom(_project: str) -> tuple[str, ...]: + raise ValueError("codebook mismatch") + + monkeypatch.setattr("lead.review.codes.reason_codes", _boom) + with pytest.raises(ValueError, match=r"wide\.yaml"): + protocols.load("wide") + + +def test_available_skips_non_yaml(tmp_path: Path, monkeypatch: pytest.MonkeyPatch): + monkeypatch.setattr(protocols, "ROOT", tmp_path) + _dump(tmp_path, "b", _base(name="b")) + _dump(tmp_path, "a", _base(name="a")) + (tmp_path / "notes.txt").write_text("nope", encoding="utf-8") + assert protocols.available() == ["a", "b"]