feat(focus): review protocols as YAML label sets
This commit is contained in:
@@ -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/**"]
|
||||
|
||||
5
src/focus/__init__.py
Normal file
5
src/focus/__init__.py
Normal file
@@ -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"]
|
||||
171
src/focus/protocols/__init__.py
Normal file
171
src/focus/protocols/__init__.py
Normal file
@@ -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)
|
||||
17
src/focus/protocols/cms-disposition.yaml
Normal file
17
src/focus/protocols/cms-disposition.yaml
Normal file
@@ -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"
|
||||
24
src/focus/protocols/code-family.yaml
Normal file
24
src/focus/protocols/code-family.yaml
Normal file
@@ -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"
|
||||
14
src/focus/protocols/comment-stance.yaml
Normal file
14
src/focus/protocols/comment-stance.yaml
Normal file
@@ -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"
|
||||
7
src/focus/protocols/prisma-screen.yaml
Normal file
7
src/focus/protocols/prisma-screen.yaml
Normal file
@@ -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
|
||||
0
tests/focus/__init__.py
Normal file
0
tests/focus/__init__.py
Normal file
311
tests/focus/test_protocols.py
Normal file
311
tests/focus/test_protocols.py
Normal file
@@ -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"]
|
||||
Reference in New Issue
Block a user