diff --git a/dev/scripts/llm_golden.py b/dev/scripts/llm_golden.py index b16735a..db0d2f8 100644 --- a/dev/scripts/llm_golden.py +++ b/dev/scripts/llm_golden.py @@ -46,6 +46,7 @@ _EXPECTATION_KEYS = ( "forbid", "expect_events", "expect_dockets", + "expect_dossier", "min_eras", ) @@ -109,6 +110,10 @@ class Transcript: return e.get("events", []) return [] + @property + def dossier_events(self) -> list[dict]: + return [e for e in self.events if e.get("type") == "dossier"] + @property def error(self) -> str | None: for e in self.events: @@ -224,6 +229,21 @@ def check_dockets(transcript: Transcript, expect_dockets: list[str]) -> CheckRes return CheckResult("dockets", passed, detail) +def check_dossier(transcript: Transcript, expect: dict) -> CheckResult: + """A ``dossier`` event for the expected family arrived, and a source + with ``kind == "dossier"`` is present.""" + family = expect["family"] + got = any(e.get("family") == family for e in transcript.dossier_events) + linked = any(s.get("kind") == "dossier" for s in transcript.sources) + problems = [] + if not got: + problems.append(f"no dossier event for {family}") + if not linked: + problems.append("no dossier source") + passed = not problems + return CheckResult("dossier", passed, "ok" if passed else "; ".join(problems)) + + def _rule_year(source: dict) -> int: """The rule year a source belongs to: the docket id's embedded year for a comment, else the source's own date year — no imports, so this @@ -258,6 +278,8 @@ def evaluate(entry: dict, transcript: Transcript) -> list[CheckResult]: results.append(check_events(transcript, entry["expect_events"])) if "expect_dockets" in entry: results.append(check_dockets(transcript, entry["expect_dockets"])) + if "expect_dossier" in entry: + results.append(check_dossier(transcript, entry["expect_dossier"])) if "min_eras" in entry: results.append(check_eras(transcript, entry["min_eras"])) return results diff --git a/docs/docs/cli/api-serve.md b/docs/docs/cli/api-serve.md index 853d7f5..ccba74d 100644 --- a/docs/docs/cli/api-serve.md +++ b/docs/docs/cli/api-serve.md @@ -1,6 +1,6 @@ --- title: stack api serve -sidebar_position: 82 +sidebar_position: 95 --- # `stack api serve` diff --git a/docs/docs/cli/api.md b/docs/docs/cli/api.md index 2ecd2bd..5f6fe31 100644 --- a/docs/docs/cli/api.md +++ b/docs/docs/cli/api.md @@ -1,6 +1,6 @@ --- title: stack api -sidebar_position: 81 +sidebar_position: 94 --- # `stack api` diff --git a/docs/docs/cli/bib-attach-iom.md b/docs/docs/cli/bib-attach-iom.md index 98d3c97..0280ad5 100644 --- a/docs/docs/cli/bib-attach-iom.md +++ b/docs/docs/cli/bib-attach-iom.md @@ -1,6 +1,6 @@ --- title: stack bib attach-iom -sidebar_position: 37 +sidebar_position: 43 --- # `stack bib attach-iom` diff --git a/docs/docs/cli/bib-attach-oig.md b/docs/docs/cli/bib-attach-oig.md index 28da6b8..04b16a7 100644 --- a/docs/docs/cli/bib-attach-oig.md +++ b/docs/docs/cli/bib-attach-oig.md @@ -1,6 +1,6 @@ --- title: stack bib attach-oig -sidebar_position: 42 +sidebar_position: 48 --- # `stack bib attach-oig` diff --git a/docs/docs/cli/bib-backfill-comments.md b/docs/docs/cli/bib-backfill-comments.md index 73edde4..19491c2 100644 --- a/docs/docs/cli/bib-backfill-comments.md +++ b/docs/docs/cli/bib-backfill-comments.md @@ -1,6 +1,6 @@ --- title: stack bib backfill-comments -sidebar_position: 35 +sidebar_position: 41 --- # `stack bib backfill-comments` diff --git a/docs/docs/cli/bib-cfr-jump.md b/docs/docs/cli/bib-cfr-jump.md index 28c0135..2f1cdf9 100644 --- a/docs/docs/cli/bib-cfr-jump.md +++ b/docs/docs/cli/bib-cfr-jump.md @@ -1,6 +1,6 @@ --- title: stack bib cfr-jump -sidebar_position: 47 +sidebar_position: 53 --- # `stack bib cfr-jump` diff --git a/docs/docs/cli/bib-code-tags.md b/docs/docs/cli/bib-code-tags.md index 8207061..5a03b97 100644 --- a/docs/docs/cli/bib-code-tags.md +++ b/docs/docs/cli/bib-code-tags.md @@ -1,6 +1,6 @@ --- title: stack bib code-tags -sidebar_position: 48 +sidebar_position: 54 --- # `stack bib code-tags` diff --git a/docs/docs/cli/bib-discover-dmepos-rules.md b/docs/docs/cli/bib-discover-dmepos-rules.md new file mode 100644 index 0000000..bd37cde --- /dev/null +++ b/docs/docs/cli/bib-discover-dmepos-rules.md @@ -0,0 +1,23 @@ +--- +title: stack bib discover-dmepos-rules +sidebar_position: 33 +--- + +# `stack bib discover-dmepos-rules` + +``` +Usage: stack bib discover-dmepos-rules [OPTIONS] + + Walk the Federal Register API for every DMEPOS rule since a date. + + The benefit moved between the ESRD rule, a standalone HCPCS rule, + and the home health rule. A title filter keeps those vehicles and + drops a Physician Fee Schedule title that only mentions DMEPOS. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --since [default: 2017-01-01] │ +│ --until │ +│ --dry-run │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/bib-discover-ipps-rules.md b/docs/docs/cli/bib-discover-ipps-rules.md new file mode 100644 index 0000000..329e865 --- /dev/null +++ b/docs/docs/cli/bib-discover-ipps-rules.md @@ -0,0 +1,19 @@ +--- +title: stack bib discover-ipps-rules +sidebar_position: 31 +--- + +# `stack bib discover-ipps-rules` + +``` +Usage: stack bib discover-ipps-rules [OPTIONS] + + Walk the Federal Register API for every annual IPPS/LTCH rule. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --since [default: 2017-01-01] │ +│ --until │ +│ --dry-run │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/bib-discover-opps-rules.md b/docs/docs/cli/bib-discover-opps-rules.md new file mode 100644 index 0000000..61feec6 --- /dev/null +++ b/docs/docs/cli/bib-discover-opps-rules.md @@ -0,0 +1,19 @@ +--- +title: stack bib discover-opps-rules +sidebar_position: 32 +--- + +# `stack bib discover-opps-rules` + +``` +Usage: stack bib discover-opps-rules [OPTIONS] + + Walk the Federal Register API for every annual OPPS/ASC rule. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --since [default: 2017-01-01] │ +│ --until │ +│ --dry-run │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/bib-discover-pfs-rules.md b/docs/docs/cli/bib-discover-pfs-rules.md index b84c2f7..c11c4bb 100644 --- a/docs/docs/cli/bib-discover-pfs-rules.md +++ b/docs/docs/cli/bib-discover-pfs-rules.md @@ -11,7 +11,7 @@ Usage: stack bib discover-pfs-rules [OPTIONS] Walk the Federal Register API for every PFS rule since a date. Upserts each as a bib ``Rule`` record tagged ``module:pfs``, - ``source:federal-register``, ``rule:``. Cheap — the FR API + ``source:federal-register``, ``docket:``. Cheap — the FR API has no auth and no rate charge we can trigger at this scale (~20 rules since 2017). diff --git a/docs/docs/cli/bib-fetch-dmepos-comments.md b/docs/docs/cli/bib-fetch-dmepos-comments.md new file mode 100644 index 0000000..c71165f --- /dev/null +++ b/docs/docs/cli/bib-fetch-dmepos-comments.md @@ -0,0 +1,44 @@ +--- +title: stack bib fetch-dmepos-comments +sidebar_position: 39 +--- + +# `stack bib fetch-dmepos-comments` + +``` +Usage: stack bib fetch-dmepos-comments [OPTIONS] + + Discover every DMEPOS proposed rule since *since* and pull its comments. + + Combined ESRD and home-health vehicles come in whole: the comment + file is the docket's file, not a DMEPOS-only slice. Notices and final + rules are registered by ``discover-dmepos-rules`` and are not walked. + + No title needle is passed to regulations.gov. The agency's copy of a + long title is often truncated (``etc.``) or hyphenated differently + from the Federal Register, and the short display posting is then + the only document that still contains "DMEPOS". + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --since [default: 2017-01-01] │ +│ --until │ +│ --attachments │ +│ --per-docket-limit Cap comments fetched per docket. 0 = │ +│ unlimited. │ +│ [default: 0] │ +│ --sleep [default: 1.3] │ +│ --docket Only pull this reg.gov docket (e.g. │ +│ CMS-2026-2377). Filtered before any API │ +│ call ONLY once the docket is known (a │ +│ `dockets` row already exists for its CMS │ +│ id) — a CMS id with no `dockets` row yet │ +│ still costs one Federal Register │ +│ rule-metadata fetch plus one │ +│ resolve_docket call, because the reg.gov │ +│ docket id isn't known until those calls │ +│ resolve it. │ +│ --force Walk every docket from page 1, sealed or │ +│ not. Never unseals. │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/bib-fetch-docket-comments.md b/docs/docs/cli/bib-fetch-docket-comments.md index 0fca322..1d902f8 100644 --- a/docs/docs/cli/bib-fetch-docket-comments.md +++ b/docs/docs/cli/bib-fetch-docket-comments.md @@ -1,6 +1,6 @@ --- title: stack bib fetch-docket-comments -sidebar_position: 31 +sidebar_position: 34 --- # `stack bib fetch-docket-comments` diff --git a/docs/docs/cli/bib-fetch-ipps-comments.md b/docs/docs/cli/bib-fetch-ipps-comments.md new file mode 100644 index 0000000..370c5d3 --- /dev/null +++ b/docs/docs/cli/bib-fetch-ipps-comments.md @@ -0,0 +1,35 @@ +--- +title: stack bib fetch-ipps-comments +sidebar_position: 37 +--- + +# `stack bib fetch-ipps-comments` + +``` +Usage: stack bib fetch-ipps-comments [OPTIONS] + + Discover every annual IPPS/LTCH proposed rule and pull its comments. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --since [default: 2017-01-01] │ +│ --until │ +│ --attachments │ +│ --per-docket-limit Cap comments fetched per docket. 0 = │ +│ unlimited. │ +│ [default: 0] │ +│ --sleep [default: 1.3] │ +│ --docket Only pull this reg.gov docket (e.g. │ +│ CMS-2026-2377). Filtered before any API │ +│ call ONLY once the docket is known (a │ +│ `dockets` row already exists for its CMS │ +│ id) — a CMS id with no `dockets` row yet │ +│ still costs one Federal Register │ +│ rule-metadata fetch plus one │ +│ resolve_docket call, because the reg.gov │ +│ docket id isn't known until those calls │ +│ resolve it. │ +│ --force Walk every docket from page 1, sealed or │ +│ not. Never unseals. │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/bib-fetch-opps-comments.md b/docs/docs/cli/bib-fetch-opps-comments.md new file mode 100644 index 0000000..67e8c02 --- /dev/null +++ b/docs/docs/cli/bib-fetch-opps-comments.md @@ -0,0 +1,35 @@ +--- +title: stack bib fetch-opps-comments +sidebar_position: 38 +--- + +# `stack bib fetch-opps-comments` + +``` +Usage: stack bib fetch-opps-comments [OPTIONS] + + Discover every annual OPPS/ASC proposed rule and pull its comments. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --since [default: 2017-01-01] │ +│ --until │ +│ --attachments │ +│ --per-docket-limit Cap comments fetched per docket. 0 = │ +│ unlimited. │ +│ [default: 0] │ +│ --sleep [default: 1.3] │ +│ --docket Only pull this reg.gov docket (e.g. │ +│ CMS-2026-2377). Filtered before any API │ +│ call ONLY once the docket is known (a │ +│ `dockets` row already exists for its CMS │ +│ id) — a CMS id with no `dockets` row yet │ +│ still costs one Federal Register │ +│ rule-metadata fetch plus one │ +│ resolve_docket call, because the reg.gov │ +│ docket id isn't known until those calls │ +│ resolve it. │ +│ --force Walk every docket from page 1, sealed or │ +│ not. Never unseals. │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/bib-fetch-pfs-comments.md b/docs/docs/cli/bib-fetch-pfs-comments.md index f3a9afc..49b6e32 100644 --- a/docs/docs/cli/bib-fetch-pfs-comments.md +++ b/docs/docs/cli/bib-fetch-pfs-comments.md @@ -1,6 +1,6 @@ --- title: stack bib fetch-pfs-comments -sidebar_position: 33 +sidebar_position: 36 --- # `stack bib fetch-pfs-comments` diff --git a/docs/docs/cli/bib-fr-grab.md b/docs/docs/cli/bib-fr-grab.md index eb0ce37..9147875 100644 --- a/docs/docs/cli/bib-fr-grab.md +++ b/docs/docs/cli/bib-fr-grab.md @@ -1,6 +1,6 @@ --- title: stack bib fr-grab -sidebar_position: 45 +sidebar_position: 51 --- # `stack bib fr-grab` @@ -11,12 +11,17 @@ Usage: stack bib fr-grab [OPTIONS] Grab federalregister.gov paragraph/page anchor maps into bib (#634). One body-HTML fetch per rule; anchors persist in ``fr_anchors`` / - ``fr_anchor_docs`` for offline jump-link resolution. + ``fr_anchor_docs`` for offline jump-link resolution. A --force + re-grab moves the item's pincites, pin: tags, fr_links and note + links to the paragraphs holding the same text, and refuses (writing + nothing) when one has no confident home — add --map for those. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --key Grab one rule item by bib key. │ │ --all Backfill every rule item with an FR URL. │ │ --force Re-grab even if an anchor map already exists. │ +│ --map Place a pinned paragraph text matching cannot: │ +│ p-OLD=p-NEW (repeatable; --key only). │ │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ``` diff --git a/docs/docs/cli/bib-fr-jump.md b/docs/docs/cli/bib-fr-jump.md index 21c6b2b..10d2ba3 100644 --- a/docs/docs/cli/bib-fr-jump.md +++ b/docs/docs/cli/bib-fr-jump.md @@ -1,6 +1,6 @@ --- title: stack bib fr-jump -sidebar_position: 46 +sidebar_position: 52 --- # `stack bib fr-jump` diff --git a/docs/docs/cli/bib-import-zotero.md b/docs/docs/cli/bib-import-zotero.md index 993557d..a4e33a0 100644 --- a/docs/docs/cli/bib-import-zotero.md +++ b/docs/docs/cli/bib-import-zotero.md @@ -1,6 +1,6 @@ --- title: stack bib import-zotero -sidebar_position: 39 +sidebar_position: 45 --- # `stack bib import-zotero` diff --git a/docs/docs/cli/bib-ingest-iom.md b/docs/docs/cli/bib-ingest-iom.md index 9de5906..5811b90 100644 --- a/docs/docs/cli/bib-ingest-iom.md +++ b/docs/docs/cli/bib-ingest-iom.md @@ -1,6 +1,6 @@ --- title: stack bib ingest-iom -sidebar_position: 36 +sidebar_position: 42 --- # `stack bib ingest-iom` diff --git a/docs/docs/cli/bib-ingest-mail.md b/docs/docs/cli/bib-ingest-mail.md index a525b4b..05230c2 100644 --- a/docs/docs/cli/bib-ingest-mail.md +++ b/docs/docs/cli/bib-ingest-mail.md @@ -1,6 +1,6 @@ --- title: stack bib ingest-mail -sidebar_position: 34 +sidebar_position: 40 --- # `stack bib ingest-mail` diff --git a/docs/docs/cli/bib-ingest-oig.md b/docs/docs/cli/bib-ingest-oig.md index 4801f9f..a47aafa 100644 --- a/docs/docs/cli/bib-ingest-oig.md +++ b/docs/docs/cli/bib-ingest-oig.md @@ -1,6 +1,6 @@ --- title: stack bib ingest-oig -sidebar_position: 41 +sidebar_position: 47 --- # `stack bib ingest-oig` diff --git a/docs/docs/cli/bib-pull-open-dockets.md b/docs/docs/cli/bib-pull-open-dockets.md index eb231de..7d326f3 100644 --- a/docs/docs/cli/bib-pull-open-dockets.md +++ b/docs/docs/cli/bib-pull-open-dockets.md @@ -1,6 +1,6 @@ --- title: stack bib pull-open-dockets -sidebar_position: 32 +sidebar_position: 35 --- # `stack bib pull-open-dockets` diff --git a/docs/docs/cli/bib-refresh-iom.md b/docs/docs/cli/bib-refresh-iom.md index 4304224..58dad2f 100644 --- a/docs/docs/cli/bib-refresh-iom.md +++ b/docs/docs/cli/bib-refresh-iom.md @@ -1,6 +1,6 @@ --- title: stack bib refresh-iom -sidebar_position: 44 +sidebar_position: 50 --- # `stack bib refresh-iom` diff --git a/docs/docs/cli/bib-refresh-oig.md b/docs/docs/cli/bib-refresh-oig.md index 01bc7f3..fd366e7 100644 --- a/docs/docs/cli/bib-refresh-oig.md +++ b/docs/docs/cli/bib-refresh-oig.md @@ -1,6 +1,6 @@ --- title: stack bib refresh-oig -sidebar_position: 43 +sidebar_position: 49 --- # `stack bib refresh-oig` diff --git a/docs/docs/cli/bib-sync-zotero.md b/docs/docs/cli/bib-sync-zotero.md index 75bddde..03ca838 100644 --- a/docs/docs/cli/bib-sync-zotero.md +++ b/docs/docs/cli/bib-sync-zotero.md @@ -1,6 +1,6 @@ --- title: stack bib sync-zotero -sidebar_position: 40 +sidebar_position: 46 --- # `stack bib sync-zotero` diff --git a/docs/docs/cli/bib-watch-iom.md b/docs/docs/cli/bib-watch-iom.md index dc627bd..f27465a 100644 --- a/docs/docs/cli/bib-watch-iom.md +++ b/docs/docs/cli/bib-watch-iom.md @@ -1,6 +1,6 @@ --- title: stack bib watch-iom -sidebar_position: 38 +sidebar_position: 44 --- # `stack bib watch-iom` diff --git a/docs/docs/cli/bib.md b/docs/docs/cli/bib.md index 3edb975..36f401a 100644 --- a/docs/docs/cli/bib.md +++ b/docs/docs/cli/bib.md @@ -19,6 +19,12 @@ Usage: stack bib [OPTIONS] COMMAND [ARGS]... │ query Search the bibliography store. │ │ discover-pfs-rules Walk the Federal Register API for every PFS rule │ │ since a date. │ +│ discover-ipps-rules Walk the Federal Register API for every annual │ +│ IPPS/LTCH rule. │ +│ discover-opps-rules Walk the Federal Register API for every annual │ +│ OPPS/ASC rule. │ +│ discover-dmepos-rules Walk the Federal Register API for every DMEPOS rule │ +│ since a date. │ │ fetch-docket-comments Walk one docket's comments from its stored watermark; │ │ upsert as Source items. │ │ pull-open-dockets Pull and enrich every docket that is not sealed yet — │ @@ -26,6 +32,12 @@ Usage: stack bib [OPTIONS] COMMAND [ARGS]... │ fetch-pfs-comments Discover every PFS proposed rule since *since* and │ │ pull new comments │ │ on each docket from its stored watermark. │ +│ fetch-ipps-comments Discover every annual IPPS/LTCH proposed rule and │ +│ pull its comments. │ +│ fetch-opps-comments Discover every annual OPPS/ASC proposed rule and pull │ +│ its comments. │ +│ fetch-dmepos-comments Discover every DMEPOS proposed rule since *since* and │ +│ pull its comments. │ │ ingest-mail Pull UNSEEN mail from a mailbox via IMAPS, upsert as │ │ bib Sources. │ │ backfill-comments Enrich every reg-gov comment stub with body + │ diff --git a/docs/docs/cli/bls-ces.md b/docs/docs/cli/bls-ces.md index e6fa25d..fa0e109 100644 --- a/docs/docs/cli/bls-ces.md +++ b/docs/docs/cli/bls-ces.md @@ -1,6 +1,6 @@ --- title: stack bls ces -sidebar_position: 51 +sidebar_position: 57 --- # `stack bls ces` diff --git a/docs/docs/cli/bls-oews.md b/docs/docs/cli/bls-oews.md index ab2c4ac..ee777fd 100644 --- a/docs/docs/cli/bls-oews.md +++ b/docs/docs/cli/bls-oews.md @@ -1,6 +1,6 @@ --- title: stack bls oews -sidebar_position: 50 +sidebar_position: 56 --- # `stack bls oews` diff --git a/docs/docs/cli/bls.md b/docs/docs/cli/bls.md index 272dbd2..362aada 100644 --- a/docs/docs/cli/bls.md +++ b/docs/docs/cli/bls.md @@ -1,6 +1,6 @@ --- title: stack bls -sidebar_position: 49 +sidebar_position: 55 --- # `stack bls` diff --git a/docs/docs/cli/comments-dockets.md b/docs/docs/cli/comments-dockets.md index 4c078b2..d85b419 100644 --- a/docs/docs/cli/comments-dockets.md +++ b/docs/docs/cli/comments-dockets.md @@ -1,6 +1,6 @@ --- title: stack comments dockets -sidebar_position: 56 +sidebar_position: 62 --- # `stack comments dockets` diff --git a/docs/docs/cli/comments-extract-ocr.md b/docs/docs/cli/comments-extract-ocr.md index 4691470..7dfd8e6 100644 --- a/docs/docs/cli/comments-extract-ocr.md +++ b/docs/docs/cli/comments-extract-ocr.md @@ -1,6 +1,6 @@ --- title: stack comments extract-ocr -sidebar_position: 54 +sidebar_position: 60 --- # `stack comments extract-ocr` diff --git a/docs/docs/cli/comments-extract.md b/docs/docs/cli/comments-extract.md index e5c492a..10639fd 100644 --- a/docs/docs/cli/comments-extract.md +++ b/docs/docs/cli/comments-extract.md @@ -1,6 +1,6 @@ --- title: stack comments extract -sidebar_position: 53 +sidebar_position: 59 --- # `stack comments extract` diff --git a/docs/docs/cli/comments-seal.md b/docs/docs/cli/comments-seal.md index 2fe987f..6c95308 100644 --- a/docs/docs/cli/comments-seal.md +++ b/docs/docs/cli/comments-seal.md @@ -1,6 +1,6 @@ --- title: stack comments seal -sidebar_position: 57 +sidebar_position: 63 --- # `stack comments seal` diff --git a/docs/docs/cli/comments-stats.md b/docs/docs/cli/comments-stats.md index dc7e7c9..58c6bbc 100644 --- a/docs/docs/cli/comments-stats.md +++ b/docs/docs/cli/comments-stats.md @@ -1,6 +1,6 @@ --- title: stack comments stats -sidebar_position: 55 +sidebar_position: 61 --- # `stack comments stats` diff --git a/docs/docs/cli/comments-unseal.md b/docs/docs/cli/comments-unseal.md index f643fac..3bf70c0 100644 --- a/docs/docs/cli/comments-unseal.md +++ b/docs/docs/cli/comments-unseal.md @@ -1,6 +1,6 @@ --- title: stack comments unseal -sidebar_position: 58 +sidebar_position: 64 --- # `stack comments unseal` diff --git a/docs/docs/cli/comments.md b/docs/docs/cli/comments.md index dfe2fe5..1f67720 100644 --- a/docs/docs/cli/comments.md +++ b/docs/docs/cli/comments.md @@ -1,6 +1,6 @@ --- title: stack comments -sidebar_position: 52 +sidebar_position: 58 --- # `stack comments` diff --git a/docs/docs/cli/db-comment.md b/docs/docs/cli/db-comment.md index d4a3642..cf90169 100644 --- a/docs/docs/cli/db-comment.md +++ b/docs/docs/cli/db-comment.md @@ -1,6 +1,6 @@ --- title: stack db comment -sidebar_position: 75 +sidebar_position: 88 --- # `stack db comment` diff --git a/docs/docs/cli/db-inspect.md b/docs/docs/cli/db-inspect.md index 9b0f7f5..b0f5907 100644 --- a/docs/docs/cli/db-inspect.md +++ b/docs/docs/cli/db-inspect.md @@ -1,6 +1,6 @@ --- title: stack db inspect -sidebar_position: 76 +sidebar_position: 89 --- # `stack db inspect` diff --git a/docs/docs/cli/db.md b/docs/docs/cli/db.md index cd6ddd0..e16e9bb 100644 --- a/docs/docs/cli/db.md +++ b/docs/docs/cli/db.md @@ -1,6 +1,6 @@ --- title: stack db -sidebar_position: 74 +sidebar_position: 87 --- # `stack db` diff --git a/docs/docs/cli/docs-build.md b/docs/docs/cli/docs-build.md index f95c43c..389b762 100644 --- a/docs/docs/cli/docs-build.md +++ b/docs/docs/cli/docs-build.md @@ -1,6 +1,6 @@ --- title: stack docs build -sidebar_position: 78 +sidebar_position: 91 --- # `stack docs build` diff --git a/docs/docs/cli/docs-generate.md b/docs/docs/cli/docs-generate.md index d225628..a0656aa 100644 --- a/docs/docs/cli/docs-generate.md +++ b/docs/docs/cli/docs-generate.md @@ -1,6 +1,6 @@ --- title: stack docs generate -sidebar_position: 80 +sidebar_position: 93 --- # `stack docs generate` diff --git a/docs/docs/cli/docs-serve.md b/docs/docs/cli/docs-serve.md index 3d1bccb..2d50d48 100644 --- a/docs/docs/cli/docs-serve.md +++ b/docs/docs/cli/docs-serve.md @@ -1,6 +1,6 @@ --- title: stack docs serve -sidebar_position: 79 +sidebar_position: 92 --- # `stack docs serve` diff --git a/docs/docs/cli/docs.md b/docs/docs/cli/docs.md index a0b81ab..d816c21 100644 --- a/docs/docs/cli/docs.md +++ b/docs/docs/cli/docs.md @@ -1,6 +1,6 @@ --- title: stack docs -sidebar_position: 77 +sidebar_position: 90 --- # `stack docs` diff --git a/docs/docs/cli/lake-deploy.md b/docs/docs/cli/lake-deploy.md index d4545bc..698b19c 100644 --- a/docs/docs/cli/lake-deploy.md +++ b/docs/docs/cli/lake-deploy.md @@ -1,6 +1,6 @@ --- title: stack lake deploy -sidebar_position: 60 +sidebar_position: 66 --- # `stack lake deploy` diff --git a/docs/docs/cli/lake-load.md b/docs/docs/cli/lake-load.md index 9d185b3..3dc34ac 100644 --- a/docs/docs/cli/lake-load.md +++ b/docs/docs/cli/lake-load.md @@ -1,6 +1,6 @@ --- title: stack lake load -sidebar_position: 61 +sidebar_position: 67 --- # `stack lake load` diff --git a/docs/docs/cli/lake-parity.md b/docs/docs/cli/lake-parity.md index 9c4b143..4c20097 100644 --- a/docs/docs/cli/lake-parity.md +++ b/docs/docs/cli/lake-parity.md @@ -1,6 +1,6 @@ --- title: stack lake parity -sidebar_position: 63 +sidebar_position: 69 --- # `stack lake parity` diff --git a/docs/docs/cli/lake-validate.md b/docs/docs/cli/lake-validate.md index b94d2cb..e3fe9a4 100644 --- a/docs/docs/cli/lake-validate.md +++ b/docs/docs/cli/lake-validate.md @@ -1,6 +1,6 @@ --- title: stack lake validate -sidebar_position: 62 +sidebar_position: 68 --- # `stack lake validate` diff --git a/docs/docs/cli/lake.md b/docs/docs/cli/lake.md index 63c1c4b..1f64b0a 100644 --- a/docs/docs/cli/lake.md +++ b/docs/docs/cli/lake.md @@ -1,6 +1,6 @@ --- title: stack lake -sidebar_position: 59 +sidebar_position: 65 --- # `stack lake` diff --git a/docs/docs/cli/lead-explore.md b/docs/docs/cli/lead-explore.md new file mode 100644 index 0000000..090e95e --- /dev/null +++ b/docs/docs/cli/lead-explore.md @@ -0,0 +1,23 @@ +--- +title: stack lead explore +sidebar_position: 72 +--- + +# `stack lead explore` + +``` +Usage: stack lead explore [OPTIONS] + + Open the read-only explorer on the local public-data mirror. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --db Path to the local public-data mirror. │ +│ [default: │ +│ /home/kert/stack/data/lead/public.duc… │ +│ --port Port for the Streamlit server. │ +│ [default: 8502] │ +│ --headless --no-headless Do not open a browser. │ +│ [default: headless] │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/lead-ledger.md b/docs/docs/cli/lead-ledger.md new file mode 100644 index 0000000..74e8829 --- /dev/null +++ b/docs/docs/cli/lead-ledger.md @@ -0,0 +1,20 @@ +--- +title: stack lead ledger +sidebar_position: 74 +--- + +# `stack lead ledger` + +``` +Usage: stack lead ledger [OPTIONS] COMMAND [ARGS]... + + Evidence ledger. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ───────────────────────────────────────────────────────────────────╮ +│ status Print one status row per target. │ +│ export Export one project's Zotero rows into the evidence ledger. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/lead-load.md b/docs/docs/cli/lead-load.md new file mode 100644 index 0000000..9afdad5 --- /dev/null +++ b/docs/docs/cli/lead-load.md @@ -0,0 +1,21 @@ +--- +title: stack lead load +sidebar_position: 73 +--- + +# `stack lead load` + +``` +Usage: stack lead load [OPTIONS] + + Load local public files into DuckDB. This does not download or publish. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --db Path to the local DuckDB mirror. [required] │ +│ --manifest Enrichment manifest CSV. │ +│ --root Directory the manifest paths are under. │ +│ --strand5 Directory that holds files.tsv. │ +│ --actor Who loaded the rows. [default: stack] │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/lead-manifest.md b/docs/docs/cli/lead-manifest.md new file mode 100644 index 0000000..ede1b99 --- /dev/null +++ b/docs/docs/cli/lead-manifest.md @@ -0,0 +1,19 @@ +--- +title: stack lead manifest +sidebar_position: 75 +--- + +# `stack lead manifest` + +``` +Usage: stack lead manifest [OPTIONS] COMMAND [ARGS]... + + Public-release manifest. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ───────────────────────────────────────────────────────────────────╮ +│ load Record manifest rows. This does not download the files. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/lead-release.md b/docs/docs/cli/lead-release.md new file mode 100644 index 0000000..9a506d2 --- /dev/null +++ b/docs/docs/cli/lead-release.md @@ -0,0 +1,24 @@ +--- +title: stack lead release +sidebar_position: 76 +--- + +# `stack lead release` + +``` +Usage: stack lead release [OPTIONS] COMMAND [ARGS]... + + Review releases (BagIt bag + RO-Crate). + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ───────────────────────────────────────────────────────────────────╮ +│ build Write a release bag. Reads the ledger, labels and Zotero read-only. │ +│ publish Publish a verified bag: serve it at reach /releases (same SSO as │ +│ reach), archive it to rustfs, create the Gitea release, add a bib │ +│ item. │ +│ Refuses a bag that does not verify or a version already published. │ +│ verify Check a bag: BagIt manifests and Payload-Oxum, then the RO-Crate. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/lead-targets.md b/docs/docs/cli/lead-targets.md new file mode 100644 index 0000000..2632e3c --- /dev/null +++ b/docs/docs/cli/lead-targets.md @@ -0,0 +1,16 @@ +--- +title: stack lead targets +sidebar_position: 71 +--- + +# `stack lead targets` + +``` +Usage: stack lead targets [OPTIONS] + + Print every target ID, family, and name. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/lead.md b/docs/docs/cli/lead.md new file mode 100644 index 0000000..1492f4f --- /dev/null +++ b/docs/docs/cli/lead.md @@ -0,0 +1,25 @@ +--- +title: stack lead +sidebar_position: 70 +--- + +# `stack lead` + +``` +Usage: stack lead [OPTIONS] COMMAND [ARGS]... + + LEAD target registry, evidence ledger, and public-data mirror. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ───────────────────────────────────────────────────────────────────╮ +│ targets Print every target ID, family, and name. │ +│ explore Open the read-only explorer on the local public-data mirror. │ +│ load Load local public files into DuckDB. This does not download or │ +│ publish. │ +│ ledger Evidence ledger. │ +│ manifest Public-release manifest. │ +│ release Review releases (BagIt bag + RO-Crate). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/llm-eval-tags.md b/docs/docs/cli/llm-eval-tags.md index 97745de..9bb18ba 100644 --- a/docs/docs/cli/llm-eval-tags.md +++ b/docs/docs/cli/llm-eval-tags.md @@ -1,6 +1,6 @@ --- title: stack llm eval-tags -sidebar_position: 71 +sidebar_position: 84 --- # `stack llm eval-tags` @@ -8,26 +8,35 @@ sidebar_position: 71 ``` Usage: stack llm eval-tags [OPTIONS] - Score the theme tagger against the golden set (P35 gate, #577): per-theme - precision/recall, micro-F1 and the abstain rate, then the fan-out gate - (micro-F1 ≥ 0.70; no theme with support ≥ 5 under 0.5 precision). Default - reads the tags the last run stored on each item (no model calls); --live - re-tags each golden comment now. Exit 1 when the gate fails. + Score the theme tagger against the golden set: per-theme precision/recall, + micro-F1 and the abstain rate, per docket, then the gate. Default: golden v3 + (200 comments, 8 dockets), held-out half, micro-F1 ≥ 0.75 and no theme with + support ≥ 5 under 0.6 precision. Reads the tags the last run stored on each + item (no model calls); --live re-tags each golden comment now. Exit 1 when the + gate fails. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --golden Golden YAML (comment ids with expected │ │ themes). │ -│ [default: tests/llm/golden_themes.yaml] │ +│ [default: tests/llm/golden_themes_v3.yaml] │ │ --live Re-tag through the model instead of scoring │ │ what is stored on the items. │ │ --limit Score only the first N golden entries. │ │ [default: 0] │ -│ --top [default: 8] │ -│ --max-tags [default: 3] │ -│ --min-confidence [default: 0.6] │ +│ --top .tag_top │ +│ --max-tags .tag_max_tags │ +│ --min-confidence .tag_min_confidence │ │ --dump With --live: write every comment's │ │ shortlist, verdicts and confidences to this │ │ JSON file. │ +│ --split Golden half to score: heldout (the gate) | │ +│ tune | all. │ +│ [default: heldout] │ +│ --docket Score one docket's entries. │ +│ --min-f1 Gate: micro-F1 floor. [default: 0.75] │ +│ --min-precision Gate: per-theme precision floor (support >= │ +│ 5). │ +│ [default: 0.6] │ │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ``` diff --git a/docs/docs/cli/llm-hosts.md b/docs/docs/cli/llm-hosts.md index b721ee1..f4fc485 100644 --- a/docs/docs/cli/llm-hosts.md +++ b/docs/docs/cli/llm-hosts.md @@ -1,6 +1,6 @@ --- title: stack llm hosts -sidebar_position: 67 +sidebar_position: 80 --- # `stack llm hosts` diff --git a/docs/docs/cli/llm-index.md b/docs/docs/cli/llm-index.md index 30fb6b9..079f5cc 100644 --- a/docs/docs/cli/llm-index.md +++ b/docs/docs/cli/llm-index.md @@ -1,6 +1,6 @@ --- title: stack llm index -sidebar_position: 65 +sidebar_position: 78 --- # `stack llm index` diff --git a/docs/docs/cli/llm-prune-rules.md b/docs/docs/cli/llm-prune-rules.md index 60425ec..d4a8717 100644 --- a/docs/docs/cli/llm-prune-rules.md +++ b/docs/docs/cli/llm-prune-rules.md @@ -1,6 +1,6 @@ --- title: stack llm prune-rules -sidebar_position: 72 +sidebar_position: 85 --- # `stack llm prune-rules` diff --git a/docs/docs/cli/llm-restamp.md b/docs/docs/cli/llm-restamp.md index 1f8de25..1fb67b1 100644 --- a/docs/docs/cli/llm-restamp.md +++ b/docs/docs/cli/llm-restamp.md @@ -1,6 +1,6 @@ --- title: stack llm restamp -sidebar_position: 66 +sidebar_position: 79 --- # `stack llm restamp` diff --git a/docs/docs/cli/llm-serve.md b/docs/docs/cli/llm-serve.md index 699111c..72ee7d3 100644 --- a/docs/docs/cli/llm-serve.md +++ b/docs/docs/cli/llm-serve.md @@ -1,6 +1,6 @@ --- title: stack llm serve -sidebar_position: 68 +sidebar_position: 81 --- # `stack llm serve` diff --git a/docs/docs/cli/llm-stamp-themes.md b/docs/docs/cli/llm-stamp-themes.md index f162ab3..a4acc2f 100644 --- a/docs/docs/cli/llm-stamp-themes.md +++ b/docs/docs/cli/llm-stamp-themes.md @@ -1,6 +1,6 @@ --- title: stack llm stamp-themes -sidebar_position: 73 +sidebar_position: 86 --- # `stack llm stamp-themes` diff --git a/docs/docs/cli/llm-tag.md b/docs/docs/cli/llm-tag.md index db947da..bc36c32 100644 --- a/docs/docs/cli/llm-tag.md +++ b/docs/docs/cli/llm-tag.md @@ -1,6 +1,6 @@ --- title: stack llm tag -sidebar_position: 70 +sidebar_position: 83 --- # `stack llm tag` @@ -25,13 +25,11 @@ Usage: stack llm tag [OPTIONS] │ current. │ │ --dry-run Compute and print, write nothing. │ │ --top Themes shortlisted per comment before │ -│ judging. │ -│ [default: 8] │ -│ --max-tags Most themes written per comment. │ -│ [default: 3] │ -│ --min-confidence Shortlist similarity below which a │ -│ judged yes is not written. │ -│ [default: 0.0] │ +│ judging .tag_top. │ +│ --max-tags Most themes written per comment │ +│ .tag_max_tags. │ +│ --min-confidence Shortlist similarity a judged yes must │ +│ reach .tag_min_confidence. │ │ --verbose Print every comment's tags. │ │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ diff --git a/docs/docs/cli/llm-vocab.md b/docs/docs/cli/llm-vocab.md index f890269..d99a304 100644 --- a/docs/docs/cli/llm-vocab.md +++ b/docs/docs/cli/llm-vocab.md @@ -1,6 +1,6 @@ --- title: stack llm vocab -sidebar_position: 69 +sidebar_position: 82 --- # `stack llm vocab` diff --git a/docs/docs/cli/llm.md b/docs/docs/cli/llm.md index 1e5bbb3..284536a 100644 --- a/docs/docs/cli/llm.md +++ b/docs/docs/cli/llm.md @@ -1,6 +1,6 @@ --- title: stack llm -sidebar_position: 64 +sidebar_position: 77 --- # `stack llm` @@ -35,17 +35,17 @@ Usage: stack llm [OPTIONS] COMMAND [ARGS]... │ record state in the item's extra_json, and replace its llm: │ │ tags. │ │ Resumable — unchanged comments are skipped unless --force. │ -│ eval-tags Score the theme tagger against the golden set (P35 gate, │ -│ #577): │ -│ per-theme precision/recall, micro-F1 and the abstain rate, │ +│ eval-tags Score the theme tagger against the golden set: per-theme │ +│ precision/recall, micro-F1 and the abstain rate, per docket, │ │ then the │ -│ fan-out gate (micro-F1 ≥ 0.70; no theme with support ≥ 5 under │ -│ 0.5 │ -│ precision). Default reads the tags the last run stored on each │ -│ item │ -│ (no model calls); --live re-tags each golden comment now. Exit │ -│ 1 when │ -│ the gate fails. │ +│ gate. Default: golden v3 (200 comments, 8 dockets), held-out │ +│ half, │ +│ micro-F1 ≥ 0.75 and no theme with support ≥ 5 under 0.6 │ +│ precision. │ +│ Reads the tags the last run stored on each item (no model │ +│ calls); │ +│ --live re-tags each golden comment now. Exit 1 when the gate │ +│ fails. │ │ prune-rules Remove Federal Register rules from the corpus collection and │ │ stamp │ │ proposed/final/correction on their rules chunks. Rules are │ diff --git a/docs/docs/cli/mail-attach-smarthost.md b/docs/docs/cli/mail-attach-smarthost.md index 331a078..7836629 100644 --- a/docs/docs/cli/mail-attach-smarthost.md +++ b/docs/docs/cli/mail-attach-smarthost.md @@ -1,6 +1,6 @@ --- title: stack mail attach-smarthost -sidebar_position: 124 +sidebar_position: 152 --- # `stack mail attach-smarthost` diff --git a/docs/docs/cli/mail-dkim-export.md b/docs/docs/cli/mail-dkim-export.md index c4de462..ea8f94f 100644 --- a/docs/docs/cli/mail-dkim-export.md +++ b/docs/docs/cli/mail-dkim-export.md @@ -1,6 +1,6 @@ --- title: stack mail dkim-export -sidebar_position: 123 +sidebar_position: 151 --- # `stack mail dkim-export` diff --git a/docs/docs/cli/mail-dns.md b/docs/docs/cli/mail-dns.md index 315cdf7..84f6fe6 100644 --- a/docs/docs/cli/mail-dns.md +++ b/docs/docs/cli/mail-dns.md @@ -1,6 +1,6 @@ --- title: stack mail dns -sidebar_position: 122 +sidebar_position: 150 --- # `stack mail dns` diff --git a/docs/docs/cli/mail-down.md b/docs/docs/cli/mail-down.md index bd07e86..5f20c62 100644 --- a/docs/docs/cli/mail-down.md +++ b/docs/docs/cli/mail-down.md @@ -1,6 +1,6 @@ --- title: stack mail down -sidebar_position: 120 +sidebar_position: 148 --- # `stack mail down` diff --git a/docs/docs/cli/mail-provision.md b/docs/docs/cli/mail-provision.md index eb91482..3a6e091 100644 --- a/docs/docs/cli/mail-provision.md +++ b/docs/docs/cli/mail-provision.md @@ -1,6 +1,6 @@ --- title: stack mail provision -sidebar_position: 118 +sidebar_position: 146 --- # `stack mail provision` diff --git a/docs/docs/cli/mail-rotate-creds.md b/docs/docs/cli/mail-rotate-creds.md index b15e147..d49eb1a 100644 --- a/docs/docs/cli/mail-rotate-creds.md +++ b/docs/docs/cli/mail-rotate-creds.md @@ -1,6 +1,6 @@ --- title: stack mail rotate-creds -sidebar_position: 125 +sidebar_position: 153 --- # `stack mail rotate-creds` diff --git a/docs/docs/cli/mail-seed-mailboxes.md b/docs/docs/cli/mail-seed-mailboxes.md index 6693614..904b4c3 100644 --- a/docs/docs/cli/mail-seed-mailboxes.md +++ b/docs/docs/cli/mail-seed-mailboxes.md @@ -1,6 +1,6 @@ --- title: stack mail seed-mailboxes -sidebar_position: 126 +sidebar_position: 154 --- # `stack mail seed-mailboxes` diff --git a/docs/docs/cli/mail-status.md b/docs/docs/cli/mail-status.md index 6a3ca87..7a6caf6 100644 --- a/docs/docs/cli/mail-status.md +++ b/docs/docs/cli/mail-status.md @@ -1,6 +1,6 @@ --- title: stack mail status -sidebar_position: 121 +sidebar_position: 149 --- # `stack mail status` diff --git a/docs/docs/cli/mail-up.md b/docs/docs/cli/mail-up.md index 2d036c1..53d68d0 100644 --- a/docs/docs/cli/mail-up.md +++ b/docs/docs/cli/mail-up.md @@ -1,6 +1,6 @@ --- title: stack mail up -sidebar_position: 119 +sidebar_position: 147 --- # `stack mail up` diff --git a/docs/docs/cli/mail-wire-git.md b/docs/docs/cli/mail-wire-git.md index f929f8e..1221be6 100644 --- a/docs/docs/cli/mail-wire-git.md +++ b/docs/docs/cli/mail-wire-git.md @@ -1,6 +1,6 @@ --- title: stack mail wire-git -sidebar_position: 127 +sidebar_position: 155 --- # `stack mail wire-git` diff --git a/docs/docs/cli/mail.md b/docs/docs/cli/mail.md index 89c6644..b601ee7 100644 --- a/docs/docs/cli/mail.md +++ b/docs/docs/cli/mail.md @@ -1,6 +1,6 @@ --- title: stack mail -sidebar_position: 117 +sidebar_position: 145 --- # `stack mail` diff --git a/docs/docs/cli/nlm-fetch.md b/docs/docs/cli/nlm-fetch.md index f978012..16a979a 100644 --- a/docs/docs/cli/nlm-fetch.md +++ b/docs/docs/cli/nlm-fetch.md @@ -1,6 +1,6 @@ --- title: stack nlm fetch -sidebar_position: 130 +sidebar_position: 158 --- # `stack nlm fetch` diff --git a/docs/docs/cli/nlm-releases.md b/docs/docs/cli/nlm-releases.md index 9cf1832..99e15ab 100644 --- a/docs/docs/cli/nlm-releases.md +++ b/docs/docs/cli/nlm-releases.md @@ -1,6 +1,6 @@ --- title: stack nlm releases -sidebar_position: 129 +sidebar_position: 157 --- # `stack nlm releases` diff --git a/docs/docs/cli/nlm-vsac.md b/docs/docs/cli/nlm-vsac.md index e4dd6d0..4d849f8 100644 --- a/docs/docs/cli/nlm-vsac.md +++ b/docs/docs/cli/nlm-vsac.md @@ -1,6 +1,6 @@ --- title: stack nlm vsac -sidebar_position: 131 +sidebar_position: 159 --- # `stack nlm vsac` diff --git a/docs/docs/cli/nlm.md b/docs/docs/cli/nlm.md index 6f0bdfa..c3359a5 100644 --- a/docs/docs/cli/nlm.md +++ b/docs/docs/cli/nlm.md @@ -1,6 +1,6 @@ --- title: stack nlm -sidebar_position: 128 +sidebar_position: 156 --- # `stack nlm` diff --git a/docs/docs/cli/perf-show.md b/docs/docs/cli/perf-show.md index a988de5..c6555da 100644 --- a/docs/docs/cli/perf-show.md +++ b/docs/docs/cli/perf-show.md @@ -1,6 +1,6 @@ --- title: stack perf show -sidebar_position: 84 +sidebar_position: 97 --- # `stack perf show` diff --git a/docs/docs/cli/perf.md b/docs/docs/cli/perf.md index 7ee4a6f..6a26a05 100644 --- a/docs/docs/cli/perf.md +++ b/docs/docs/cli/perf.md @@ -1,6 +1,6 @@ --- title: stack perf -sidebar_position: 83 +sidebar_position: 96 --- # `stack perf` diff --git a/docs/docs/cli/pfs-cms-summaries.md b/docs/docs/cli/pfs-cms-summaries.md new file mode 100644 index 0000000..f918c3f --- /dev/null +++ b/docs/docs/cli/pfs-cms-summaries.md @@ -0,0 +1,24 @@ +--- +title: stack pfs cms-summaries +sidebar_position: 118 +--- + +# `stack pfs cms-summaries` + +``` +Usage: stack pfs cms-summaries [OPTIONS] + + CMS's own Comment:/Response: summaries (pfs.cms_comment_summary): CMS's + quantifier, the stance of the summarized comments and CMS's response action, + per pair a rule prints. Kept apart from our own commenter counts. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --family Curated family key. [required] │ +│ --no-llm Make no model calls; the finished ledger is │ +│ replayed. │ +│ --limit Cap new model calls (0 = all). [default: 0] │ +│ --retry-failed Re-run ledger entries that failed. │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-commenters.md b/docs/docs/cli/pfs-commenters.md new file mode 100644 index 0000000..fa0f021 --- /dev/null +++ b/docs/docs/cli/pfs-commenters.md @@ -0,0 +1,25 @@ +--- +title: stack pfs commenters +sidebar_position: 119 +--- + +# `stack pfs commenters` + +``` +Usage: stack pfs commenters [OPTIONS] + + Who wrote each family comment (pfs.commenter): organization, type, specialty, + form-letter campaign and the submitter name as the regulations.gov record + posts it (official public record). + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --family Curated family key. [required] │ +│ * --docket regulations.gov docket id. [required] │ +│ --limit Cap new model calls (0 = all). [default: 0] │ +│ --retry-failed Re-run ledger entries that failed. │ +│ --dry-run Count the family's comments and │ +│ regulations.gov categories; no model. │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-cpt-ingest.md b/docs/docs/cli/pfs-cpt-ingest.md index 474d8c8..6fdc048 100644 --- a/docs/docs/cli/pfs-cpt-ingest.md +++ b/docs/docs/cli/pfs-cpt-ingest.md @@ -1,6 +1,6 @@ --- title: stack pfs cpt-ingest -sidebar_position: 98 +sidebar_position: 114 --- # `stack pfs cpt-ingest` diff --git a/docs/docs/cli/pfs-dossier.md b/docs/docs/cli/pfs-dossier.md new file mode 100644 index 0000000..4a4027e --- /dev/null +++ b/docs/docs/cli/pfs-dossier.md @@ -0,0 +1,28 @@ +--- +title: stack pfs dossier +sidebar_position: 122 +--- + +# `stack pfs dossier` + +``` +Usage: stack pfs dossier [OPTIONS] + + Assemble a family's dossier (pfs.dossier): every stored fact with its resolved + citation, the computed gaps, and model prose that passes the sentence-level + citation check (template lines otherwise), through a resumable ledger. Prints + the fact count, the gaps, the stakeholder table and the check result; --write + stores it. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --family Curated family key. │ +│ --all Every curated family. │ +│ --no-llm Make no model calls; the finished prose ledger is │ +│ replayed. │ +│ --limit Cap new model calls (0 = all). [default: 0] │ +│ --dry-run Count facts and timeline events; no model calls, no │ +│ writes. │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-elements.md b/docs/docs/cli/pfs-elements.md index 9e1d540..6df1eac 100644 --- a/docs/docs/cli/pfs-elements.md +++ b/docs/docs/cli/pfs-elements.md @@ -1,6 +1,6 @@ --- title: stack pfs elements -sidebar_position: 90 +sidebar_position: 103 --- # `stack pfs elements` diff --git a/docs/docs/cli/pfs-exposure.md b/docs/docs/cli/pfs-exposure.md index e2d4308..b692967 100644 --- a/docs/docs/cli/pfs-exposure.md +++ b/docs/docs/cli/pfs-exposure.md @@ -1,6 +1,6 @@ --- title: stack pfs exposure -sidebar_position: 95 +sidebar_position: 108 --- # `stack pfs exposure` diff --git a/docs/docs/cli/pfs-families.md b/docs/docs/cli/pfs-families.md index c6945d8..99a6baf 100644 --- a/docs/docs/cli/pfs-families.md +++ b/docs/docs/cli/pfs-families.md @@ -1,6 +1,6 @@ --- title: stack pfs families -sidebar_position: 92 +sidebar_position: 105 --- # `stack pfs families` diff --git a/docs/docs/cli/pfs-guidance.md b/docs/docs/cli/pfs-guidance.md index aef2b8e..9cd98c3 100644 --- a/docs/docs/cli/pfs-guidance.md +++ b/docs/docs/cli/pfs-guidance.md @@ -1,6 +1,6 @@ --- title: stack pfs guidance -sidebar_position: 93 +sidebar_position: 106 --- # `stack pfs guidance` diff --git a/docs/docs/cli/pfs-guideline-facts.md b/docs/docs/cli/pfs-guideline-facts.md new file mode 100644 index 0000000..a893023 --- /dev/null +++ b/docs/docs/cli/pfs-guideline-facts.md @@ -0,0 +1,25 @@ +--- +title: stack pfs guideline-facts +sidebar_position: 117 +--- + +# `stack pfs guideline-facts` + +``` +Usage: stack pfs guideline-facts [OPTIONS] + + Guideline facts from the licensed CPT books (pfs.code_guideline_fact): + selection basis, MDM level, time threshold, add-on and deletion per code and + edition, scope points and the Panel action as paraphrases, each cited by + (edition, page). Book text is never stored. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --family Curated family key. [required] │ +│ --limit Cap new model calls (0 = all). [default: 0] │ +│ --no-llm Make no model calls; the finished ledger is │ +│ replayed. │ +│ --retry-failed Re-run ledger entries that failed. │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-impacts.md b/docs/docs/cli/pfs-impacts.md new file mode 100644 index 0000000..e303d8c --- /dev/null +++ b/docs/docs/cli/pfs-impacts.md @@ -0,0 +1,25 @@ +--- +title: stack pfs impacts +sidebar_position: 112 +--- + +# `stack pfs impacts` + +``` +Usage: stack pfs impacts [OPTIONS] + + CMS's estimated impact on total allowed charges by specialty + (pfs.specialty_impact): the 508 text files CMS posts with a rule and the table + printed in the 2012-2019 Federal Register texts. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --scan Every CMS 508 impact file in bib / │ +│ data/cms/pfs_final and every PFS rule whose FR text │ +│ prints the table. │ +│ --path One impact file or FR text. │ +│ --year Rule year, with --path. [default: 0] │ +│ --vintage final | proposed [default: final] │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-lineage.md b/docs/docs/cli/pfs-lineage.md index 4e638ec..5803ac5 100644 --- a/docs/docs/cli/pfs-lineage.md +++ b/docs/docs/cli/pfs-lineage.md @@ -1,6 +1,6 @@ --- title: stack pfs lineage -sidebar_position: 91 +sidebar_position: 104 --- # `stack pfs lineage` @@ -15,8 +15,11 @@ Usage: stack pfs lineage [OPTIONS] ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --code │ +│ --family A curated or registered family's codes. │ │ --all-payable Every A/R/T code in the newest RVU year, one │ │ inverted pass over fr_anchors. │ +│ --all-seen Every code ever seen in any RVU year or CPT │ +│ edition (incl. deleted codes). │ │ --limit Only the first N target codes (sorted) — for │ │ smoke runs with --all-payable. │ │ [default: 0] │ diff --git a/docs/docs/cli/pfs-origin.md b/docs/docs/cli/pfs-origin.md new file mode 100644 index 0000000..555ca3f --- /dev/null +++ b/docs/docs/cli/pfs-origin.md @@ -0,0 +1,29 @@ +--- +title: stack pfs origin +sidebar_position: 116 +--- + +# `stack pfs origin` + +``` +Usage: stack pfs origin [OPTIONS] + + Origin and formation rows per code (pfs.code_origin): the statute, regulation, + program, demonstration, CPT Editorial Panel action, G-code creation or + coverage rule behind them, from Federal Register paragraphs, the licensed CPT + Changes book (paraphrase + page only) and the guidance rows, through a + resumable local-model ledger. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --family Curated family key. [required] │ +│ --book Bib item of a licensed EPUB to read (default │ +│ 3ANRT854, CPT Changes 2023); repeatable. │ +│ --limit Cap new model calls (0 = all). [default: 0] │ +│ --dry-run Count candidates; no model calls, no writes. │ +│ --no-llm Make no model calls; the finished ledger is │ +│ replayed. │ +│ --retry-failed Re-run ledger entries that failed. │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-psps.md b/docs/docs/cli/pfs-psps.md new file mode 100644 index 0000000..5a48322 --- /dev/null +++ b/docs/docs/cli/pfs-psps.md @@ -0,0 +1,24 @@ +--- +title: stack pfs psps +sidebar_position: 110 +--- + +# `stack pfs psps` + +``` +Usage: stack pfs psps [OPTIONS] + + Medicare utilization by provider specialty for a family's codes + (pfs.utilization_specialty): the PSPS national totals per code, year and + specialty. --write pulls each (year, code) through the Data API, caches it + under data/cms/psps/ (never overwriting a cached file) and republishes; + without --write it prints what the replica holds. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --family Family key, e.g. HOME-VISITS. [required] │ +│ --year Calendar year(s); default every PSPS year. │ +│ --write Fetch data.cms.gov, load, cite, republish. │ +│ --offline With --write: use the cached JSON, no network. │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-reaction.md b/docs/docs/cli/pfs-reaction.md index 4d3d70a..6f061f9 100644 --- a/docs/docs/cli/pfs-reaction.md +++ b/docs/docs/cli/pfs-reaction.md @@ -1,6 +1,6 @@ --- title: stack pfs reaction -sidebar_position: 94 +sidebar_position: 107 --- # `stack pfs reaction` diff --git a/docs/docs/cli/pfs-review.md b/docs/docs/cli/pfs-review.md index 5664556..14aa32c 100644 --- a/docs/docs/cli/pfs-review.md +++ b/docs/docs/cli/pfs-review.md @@ -1,6 +1,6 @@ --- title: stack pfs review -sidebar_position: 97 +sidebar_position: 113 --- # `stack pfs review` diff --git a/docs/docs/cli/pfs-rounds.md b/docs/docs/cli/pfs-rounds.md new file mode 100644 index 0000000..d2208a9 --- /dev/null +++ b/docs/docs/cli/pfs-rounds.md @@ -0,0 +1,27 @@ +--- +title: stack pfs rounds +sidebar_position: 115 +--- + +# `stack pfs rounds` + +``` +Usage: stack pfs rounds [OPTIONS] + + Valuation rounds per code and rule (pfs.valuation_round): RUC recommendation + vs CMS proposal/final, from FR tables, regex over FR paragraphs, and the local + model through a resumable ledger. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --family Curated family key. [required] │ +│ --tables-only No model calls (as --no-llm); the finished │ +│ ledger is replayed. │ +│ --no-llm Make no model calls; the finished ledger is │ +│ replayed. │ +│ --limit Cap new model calls (0 = all). [default: 0] │ +│ --dry-run Count candidates; no model calls, no writes. │ +│ --retry-failed Re-run ledger entries that failed. │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-seats.md b/docs/docs/cli/pfs-seats.md new file mode 100644 index 0000000..7ea8486 --- /dev/null +++ b/docs/docs/cli/pfs-seats.md @@ -0,0 +1,33 @@ +--- +title: stack pfs seats +sidebar_position: 111 +--- + +# `stack pfs seats` + +``` +Usage: stack pfs seats [OPTIONS] + + Seats on the RUC or the CPT Editorial Panel by year (pfs.governance_seat), + parsed deterministically from the Internet Archive's copies of the AMA roster + page (R88). Each capture is saved under data/ama/rosters and cited as a bib + Download. A year with no capture, a refusal (403/429, bot page) or an + unrecognised layout is a gap line (and, with --write, an ingest_log row with + rows=0). + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --body RUC or CPT_PANEL. [required] │ +│ * --url The AMA roster page (live URL). [required] │ +│ --from First year to capture. [default: 2005] │ +│ --to Last year to capture. [default: 2026] │ +│ --limit Cap the snapshots read (0 = all). │ +│ [default: 0] │ +│ --dry-run List the archive's captures; fetch and parse │ +│ nothing. │ +│ --cross-check Also ask the pinned local model for the │ +│ organizations and log where it disagrees with │ +│ the parse (resumable ledger). │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-stance-eval.md b/docs/docs/cli/pfs-stance-eval.md new file mode 100644 index 0000000..3750dac --- /dev/null +++ b/docs/docs/cli/pfs-stance-eval.md @@ -0,0 +1,29 @@ +--- +title: stack pfs stance-eval +sidebar_position: 121 +--- + +# `stack pfs stance-eval` + +``` +Usage: stack pfs stance-eval [OPTIONS] + + Score a stance method against a hand-coded golden set: cell agreement, + presence agreement, firm-stance accuracy and a confusion matrix. The golden + items are classified through the stance ledger (resumable); nothing is written + to pfs.comment_stance. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --golden Golden stance JSON. [required] │ +│ --method multi or per-event. [default: multi] │ +│ --model instruct or large. [default: instruct] │ +│ --limit Cap new model calls (0 = all). [default: 0] │ +│ --retry-failed │ +│ --no-llm Make no model calls; the finished ledger is │ +│ replayed. │ +│ --no-relevance Skip the event-subject filter (R65). │ +│ --generation stance-v4 or stance-v5. │ +│ [default: stance-v5] │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-stance.md b/docs/docs/cli/pfs-stance.md new file mode 100644 index 0000000..8a86c6b --- /dev/null +++ b/docs/docs/cli/pfs-stance.md @@ -0,0 +1,43 @@ +--- +title: stack pfs stance +sidebar_position: 120 +--- + +# `stack pfs stance` + +``` +Usage: stack pfs stance [OPTIONS] + + Each commenter's stance (support / modify / oppose / unclear) on each family + event the docket's rule touched, with a reason and a verbatim quote + (pfs.comment_stance); --write also rolls the counts up into the docket's + pfs.code_reaction row. CMS's own summaries are never used. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ * --family Curated family key. [required] │ +│ * --docket regulations.gov docket id. [required] │ +│ --limit Cap new model calls (0 = all). [default: 0] │ +│ --retry-failed Re-run ledger entries that failed. │ +│ --dry-run Count commenters and events; no model. │ +│ --no-llm Make no model calls; the finished ledger is │ +│ replayed. │ +│ --method multi (one call per comment) or per-event. │ +│ [default: multi] │ +│ --model instruct or large (the pinned model). │ +│ [default: large] │ +│ --golden Tuning (in-sample) golden set --write │ +│ records as in_sample_record. │ +│ [default: │ +│ /home/kert/stack/src/pfs/golden/stance_hom… │ +│ --heldout Held-out golden sets; the primary one is │ +│ the stamped measurement. │ +│ [default: │ +│ /home/kert/stack/src/pfs/golden/stance_hom… │ +│ /home/kert/stack/src/pfs/golden/stance_hom… │ +│ --generation Prompt generation: stance-v4 or stance-v5 │ +│ (CPT guideline facts). │ +│ [default: stance-v5] │ +│ --write │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/pfs-utilization.md b/docs/docs/cli/pfs-utilization.md index 245c46c..721ca6b 100644 --- a/docs/docs/cli/pfs-utilization.md +++ b/docs/docs/cli/pfs-utilization.md @@ -1,6 +1,6 @@ --- title: stack pfs utilization -sidebar_position: 96 +sidebar_position: 109 --- # `stack pfs utilization` diff --git a/docs/docs/cli/pfs.md b/docs/docs/cli/pfs.md index 4ef7ab9..bc30615 100644 --- a/docs/docs/cli/pfs.md +++ b/docs/docs/cli/pfs.md @@ -1,6 +1,6 @@ --- title: stack pfs -sidebar_position: 89 +sidebar_position: 102 --- # `stack pfs` @@ -14,47 +14,135 @@ Usage: stack pfs [OPTIONS] COMMAND [ARGS]... │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ -│ elements Extract typed elements for codes into pfs.code_element (+ │ -│ review queue). │ -│ lineage Timeline of a code: RVU-file diffs and FR paragraphs, │ -│ cross-checked. │ -│ families Derive families from pfs.code_element / pfs.code_event / │ -│ pfs.rvu. │ -│ guidance CFR/IOM/MLN sub-regulatory crosswalk per code family │ -│ (pfs.code_guidance): which CFR sections and IOM manual chapters │ -│ the │ -│ family's FR paragraphs and the CPT manual cite, with FR │ -│ provenance. │ -│ reaction Public-reaction series per code family (pfs.code_reaction): │ -│ comment │ -│ counts per docket (share of the docket's commenters mentioning │ -│ the │ -│ family), an optional stance sample, and the FR │ -│ Comment:/Response: │ -│ pair counts per rule as the pre-2017 proxy. Always recomputed │ -│ live │ -│ from pgvector/bib — there is no persisted-table fallback to │ -│ read │ -│ without --write, so --write only adds persisting the result. │ -│ exposure The exposure calendar (pfs.code_exposure, #693): when each code │ -│ became payable, was revalued, changed payable status, ended, or │ -│ was │ -│ listed for telehealth — dated 1 January of the rule year (or │ -│ the │ -│ correction notice's date), anchored to the FR paragraph from │ -│ its │ -│ lineage, with the status and RVU-decile band a control set │ -│ matches on. │ -│ utilization Part B utilization per HCPCS (pfs.utilization, #694): the CMS │ -│ "Medicare Physician & Other Practitioners — by Geography and │ -│ Service" │ -│ national totals, one row per (year, code, place of service), │ -│ with │ -│ each year's dataset cited in bib and logged in cms.ingest_log. │ -│ review Element lines the classifier could not place. │ -│ cpt-ingest Parse CPT EPUB editions into │ -│ pfs.cpt_section/cpt_code/cpt_instruction/ │ -│ cpt_reference/cpt_crosswalk/cpt_list (docs/superpowers/specs/ │ -│ 2026-09-09-cpt-canonical-schema-design.md §3). │ +│ elements Extract typed elements for codes into pfs.code_element (+ │ +│ review queue). │ +│ lineage Timeline of a code: RVU-file diffs and FR paragraphs, │ +│ cross-checked. │ +│ families Derive families from pfs.code_element / pfs.code_event / │ +│ pfs.rvu. │ +│ guidance CFR/IOM/MLN sub-regulatory crosswalk per code family │ +│ (pfs.code_guidance): which CFR sections and IOM manual │ +│ chapters the │ +│ family's FR paragraphs and the CPT manual cite, with FR │ +│ provenance. │ +│ reaction Public-reaction series per code family (pfs.code_reaction): │ +│ comment │ +│ counts per docket (share of the docket's commenters │ +│ mentioning the │ +│ family), an optional stance sample, and the FR │ +│ Comment:/Response: │ +│ pair counts per rule as the pre-2017 proxy. Always │ +│ recomputed live │ +│ from pgvector/bib — there is no persisted-table fallback to │ +│ read │ +│ without --write, so --write only adds persisting the │ +│ result. │ +│ exposure The exposure calendar (pfs.code_exposure, #693): when each │ +│ code │ +│ became payable, was revalued, changed payable status, │ +│ ended, or was │ +│ listed for telehealth — dated 1 January of the rule year │ +│ (or the │ +│ correction notice's date), anchored to the FR paragraph │ +│ from its │ +│ lineage, with the status and RVU-decile band a control set │ +│ matches on. │ +│ utilization Part B utilization per HCPCS (pfs.utilization, #694): the │ +│ CMS │ +│ "Medicare Physician & Other Practitioners — by Geography │ +│ and Service" │ +│ national totals, one row per (year, code, place of │ +│ service), with │ +│ each year's dataset cited in bib and logged in │ +│ cms.ingest_log. │ +│ psps Medicare utilization by provider specialty for a family's │ +│ codes │ +│ (pfs.utilization_specialty): the PSPS national totals per │ +│ code, year │ +│ and specialty. --write pulls each (year, code) through the │ +│ Data API, │ +│ caches it under data/cms/psps/ (never overwriting a cached │ +│ file) and │ +│ republishes; without --write it prints what the replica │ +│ holds. │ +│ seats Seats on the RUC or the CPT Editorial Panel by year │ +│ (pfs.governance_seat), parsed deterministically from the │ +│ Internet │ +│ Archive's copies of the AMA roster page (R88). Each capture │ +│ is saved │ +│ under data/ama/rosters and cited as a bib Download. A year │ +│ with no │ +│ capture, a refusal (403/429, bot page) or an unrecognised │ +│ layout is a │ +│ gap line (and, with --write, an ingest_log row with │ +│ rows=0). │ +│ impacts CMS's estimated impact on total allowed charges by │ +│ specialty │ +│ (pfs.specialty_impact): the 508 text files CMS posts with a │ +│ rule and │ +│ the table printed in the 2012-2019 Federal Register texts. │ +│ review Element lines the classifier could not place. │ +│ cpt-ingest Parse CPT EPUB editions into │ +│ pfs.cpt_section/cpt_code/cpt_instruction/ │ +│ cpt_reference/cpt_crosswalk/cpt_list │ +│ (docs/superpowers/specs/ │ +│ 2026-09-09-cpt-canonical-schema-design.md §3). │ +│ rounds Valuation rounds per code and rule (pfs.valuation_round): │ +│ RUC │ +│ recommendation vs CMS proposal/final, from FR tables, regex │ +│ over FR │ +│ paragraphs, and the local model through a resumable ledger. │ +│ origin Origin and formation rows per code (pfs.code_origin): the │ +│ statute, │ +│ regulation, program, demonstration, CPT Editorial Panel │ +│ action, G-code │ +│ creation or coverage rule behind them, from Federal │ +│ Register │ +│ paragraphs, the licensed CPT Changes book (paraphrase + │ +│ page only) and │ +│ the guidance rows, through a resumable local-model ledger. │ +│ guideline-facts Guideline facts from the licensed CPT books │ +│ (pfs.code_guideline_fact): │ +│ selection basis, MDM level, time threshold, add-on and │ +│ deletion per code │ +│ and edition, scope points and the Panel action as │ +│ paraphrases, each cited │ +│ by (edition, page). Book text is never stored. │ +│ cms-summaries CMS's own Comment:/Response: summaries │ +│ (pfs.cms_comment_summary): │ +│ CMS's quantifier, the stance of the summarized comments and │ +│ CMS's │ +│ response action, per pair a rule prints. Kept apart from │ +│ our own │ +│ commenter counts. │ +│ commenters Who wrote each family comment (pfs.commenter): │ +│ organization, type, │ +│ specialty, form-letter campaign and the submitter name as │ +│ the │ +│ regulations.gov record posts it (official public record). │ +│ stance Each commenter's stance (support / modify / oppose / │ +│ unclear) on each │ +│ family event the docket's rule touched, with a reason and a │ +│ verbatim │ +│ quote (pfs.comment_stance); --write also rolls the counts │ +│ up into the │ +│ docket's pfs.code_reaction row. CMS's own summaries are │ +│ never used. │ +│ stance-eval Score a stance method against a hand-coded golden set: cell │ +│ agreement, │ +│ presence agreement, firm-stance accuracy and a confusion │ +│ matrix. The │ +│ golden items are classified through the stance ledger │ +│ (resumable); nothing │ +│ is written to pfs.comment_stance. │ +│ dossier Assemble a family's dossier (pfs.dossier): every stored │ +│ fact with its │ +│ resolved citation, the computed gaps, and model prose that │ +│ passes the │ +│ sentence-level citation check (template lines otherwise), │ +│ through a │ +│ resumable ledger. Prints the fact count, the gaps, the │ +│ stakeholder table │ +│ and the check result; --write stores it. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ``` diff --git a/docs/docs/cli/prisma-audit.md b/docs/docs/cli/prisma-audit.md new file mode 100644 index 0000000..02f33f1 --- /dev/null +++ b/docs/docs/cli/prisma-audit.md @@ -0,0 +1,16 @@ +--- +title: stack prisma audit +sidebar_position: 141 +--- + +# `stack prisma audit` + +``` +Usage: stack prisma audit [OPTIONS] + + Two passes of one model, then a 10% sample of agreed excludes. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/prisma-calibrate.md b/docs/docs/cli/prisma-calibrate.md new file mode 100644 index 0000000..6b4e400 --- /dev/null +++ b/docs/docs/cli/prisma-calibrate.md @@ -0,0 +1,16 @@ +--- +title: stack prisma calibrate +sidebar_position: 140 +--- + +# `stack prisma calibrate` + +``` +Usage: stack prisma calibrate [OPTIONS] + + Calibration gate: sensitivity ≥ 0.95 on 200 title/abstract and 50 full text. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/prisma-dedup.md b/docs/docs/cli/prisma-dedup.md new file mode 100644 index 0000000..7b0801b --- /dev/null +++ b/docs/docs/cli/prisma-dedup.md @@ -0,0 +1,18 @@ +--- +title: stack prisma dedup +sidebar_position: 139 +--- + +# `stack prisma dedup` + +``` +Usage: stack prisma dedup [OPTIONS] + + Tag DOI, PMID, and title duplicates. Near-matches stay untagged. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --db [default: data/zotero/data/zotero.sqlite] │ +│ --hold --no-hold [default: hold] │ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/prisma-eligible.md b/docs/docs/cli/prisma-eligible.md index 0000585..949e630 100644 --- a/docs/docs/cli/prisma-eligible.md +++ b/docs/docs/cli/prisma-eligible.md @@ -1,6 +1,6 @@ --- title: stack prisma eligible -sidebar_position: 111 +sidebar_position: 135 --- # `stack prisma eligible` diff --git a/docs/docs/cli/prisma-export.md b/docs/docs/cli/prisma-export.md index a057b0b..c984584 100644 --- a/docs/docs/cli/prisma-export.md +++ b/docs/docs/cli/prisma-export.md @@ -1,6 +1,6 @@ --- title: stack prisma export -sidebar_position: 108 +sidebar_position: 132 --- # `stack prisma export` diff --git a/docs/docs/cli/prisma-extract.md b/docs/docs/cli/prisma-extract.md index d333e30..01f197b 100644 --- a/docs/docs/cli/prisma-extract.md +++ b/docs/docs/cli/prisma-extract.md @@ -1,6 +1,6 @@ --- title: stack prisma extract -sidebar_position: 112 +sidebar_position: 136 --- # `stack prisma extract` diff --git a/docs/docs/cli/prisma-fetch.md b/docs/docs/cli/prisma-fetch.md index cf97bff..e948672 100644 --- a/docs/docs/cli/prisma-fetch.md +++ b/docs/docs/cli/prisma-fetch.md @@ -1,6 +1,6 @@ --- title: stack prisma fetch -sidebar_position: 114 +sidebar_position: 138 --- # `stack prisma fetch` diff --git a/docs/docs/cli/prisma-flow.md b/docs/docs/cli/prisma-flow.md index 2e3f3c5..65b101c 100644 --- a/docs/docs/cli/prisma-flow.md +++ b/docs/docs/cli/prisma-flow.md @@ -1,6 +1,6 @@ --- title: stack prisma flow -sidebar_position: 113 +sidebar_position: 137 --- # `stack prisma flow` diff --git a/docs/docs/cli/prisma-init.md b/docs/docs/cli/prisma-init.md index 5d9689b..bc34312 100644 --- a/docs/docs/cli/prisma-init.md +++ b/docs/docs/cli/prisma-init.md @@ -1,6 +1,6 @@ --- title: stack prisma init -sidebar_position: 107 +sidebar_position: 131 --- # `stack prisma init` diff --git a/docs/docs/cli/prisma-ping-llm.md b/docs/docs/cli/prisma-ping-llm.md index 228661a..5929f57 100644 --- a/docs/docs/cli/prisma-ping-llm.md +++ b/docs/docs/cli/prisma-ping-llm.md @@ -1,6 +1,6 @@ --- title: stack prisma ping-llm -sidebar_position: 109 +sidebar_position: 133 --- # `stack prisma ping-llm` diff --git a/docs/docs/cli/prisma-run.md b/docs/docs/cli/prisma-run.md index f421231..5b8ad72 100644 --- a/docs/docs/cli/prisma-run.md +++ b/docs/docs/cli/prisma-run.md @@ -1,6 +1,6 @@ --- title: stack prisma run -sidebar_position: 115 +sidebar_position: 142 --- # `stack prisma run` diff --git a/docs/docs/cli/prisma-screen.md b/docs/docs/cli/prisma-screen.md index bd06a21..8db5b35 100644 --- a/docs/docs/cli/prisma-screen.md +++ b/docs/docs/cli/prisma-screen.md @@ -1,6 +1,6 @@ --- title: stack prisma screen -sidebar_position: 110 +sidebar_position: 134 --- # `stack prisma screen` diff --git a/docs/docs/cli/prisma-search.md b/docs/docs/cli/prisma-search.md new file mode 100644 index 0000000..a0d22c7 --- /dev/null +++ b/docs/docs/cli/prisma-search.md @@ -0,0 +1,20 @@ +--- +title: stack prisma search +sidebar_position: 143 +--- + +# `stack prisma search` + +``` +Usage: stack prisma search [OPTIONS] COMMAND [ARGS]... + + Search logs and strand protocols. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ───────────────────────────────────────────────────────────────────╮ +│ protocols Print the starting PubMed query for each LEAD project. │ +│ due Print why a search is due. Prints nothing when it is current. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +``` diff --git a/docs/docs/cli/prisma-vpn.md b/docs/docs/cli/prisma-vpn.md index 3633a26..c148761 100644 --- a/docs/docs/cli/prisma-vpn.md +++ b/docs/docs/cli/prisma-vpn.md @@ -1,6 +1,6 @@ --- title: stack prisma vpn -sidebar_position: 116 +sidebar_position: 144 --- # `stack prisma vpn` diff --git a/docs/docs/cli/prisma.md b/docs/docs/cli/prisma.md index 7419d87..d01cb93 100644 --- a/docs/docs/cli/prisma.md +++ b/docs/docs/cli/prisma.md @@ -1,6 +1,6 @@ --- title: stack prisma -sidebar_position: 106 +sidebar_position: 130 --- # `stack prisma` @@ -14,17 +14,22 @@ Usage: stack prisma [OPTIONS] COMMAND [ARGS]... │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ -│ init Create (or re-load) the project's three Zotero anchor items: │ -│ criteria, extraction-template, and the reasons codebook. │ -│ export Dump one Zotero item as the LLM-ready markdown snapshot. │ -│ ping-llm Send a cheap ping through the configured provider. │ -│ screen Stage 2 — LLM-driven title/abstract screening pass. │ -│ eligible Stage 3 — LLM-driven full-text eligibility pass. │ -│ extract Stage 3+ — structured data extraction on included studies. │ -│ flow Emit the PRISMA 2020 flow diagram from current tag counts. │ -│ fetch Fetch PDFs for every non-excluded item lacking an attachment. │ -│ run Orchestrate all PRISMA stages in order. │ -│ vpn DigitalOcean SOCKS5 exit for fallback fetch (SSH tunnel, no sudo │ -│ needed). │ +│ init Create (or re-load) the project's three Zotero anchor items: │ +│ criteria, extraction-template, and the reasons codebook. │ +│ export Dump one Zotero item as the LLM-ready markdown snapshot. │ +│ ping-llm Send a cheap ping through the configured provider. │ +│ screen Stage 2 — LLM-driven title/abstract screening pass. │ +│ eligible Stage 3 — LLM-driven full-text eligibility pass. │ +│ extract Stage 3+ — structured data extraction on included studies. │ +│ flow Emit the PRISMA 2020 flow diagram from current tag counts. │ +│ fetch Fetch PDFs for every non-excluded item lacking an attachment. │ +│ dedup Tag DOI, PMID, and title duplicates. Near-matches stay untagged. │ +│ calibrate Calibration gate: sensitivity ≥ 0.95 on 200 title/abstract and 50 │ +│ full text. │ +│ audit Two passes of one model, then a 10% sample of agreed excludes. │ +│ run Orchestrate all PRISMA stages in order. │ +│ search Search logs and strand protocols. │ +│ vpn DigitalOcean SOCKS5 exit for fallback fetch (SSH tunnel, no sudo │ +│ needed). │ ╰──────────────────────────────────────────────────────────────────────────────╯ ``` diff --git a/docs/docs/cli/rec-list.md b/docs/docs/cli/rec-list.md index c4b62b6..fecab1f 100644 --- a/docs/docs/cli/rec-list.md +++ b/docs/docs/cli/rec-list.md @@ -1,6 +1,6 @@ --- title: stack rec list -sidebar_position: 86 +sidebar_position: 99 --- # `stack rec list` diff --git a/docs/docs/cli/rec-opps.md b/docs/docs/cli/rec-opps.md index 784dc16..2d10ed5 100644 --- a/docs/docs/cli/rec-opps.md +++ b/docs/docs/cli/rec-opps.md @@ -1,6 +1,6 @@ --- title: stack rec opps -sidebar_position: 88 +sidebar_position: 101 --- # `stack rec opps` diff --git a/docs/docs/cli/rec-pfs.md b/docs/docs/cli/rec-pfs.md index b8cb4a1..ff97a5c 100644 --- a/docs/docs/cli/rec-pfs.md +++ b/docs/docs/cli/rec-pfs.md @@ -1,6 +1,6 @@ --- title: stack rec pfs -sidebar_position: 87 +sidebar_position: 100 --- # `stack rec pfs` diff --git a/docs/docs/cli/rec.md b/docs/docs/cli/rec.md index d13632b..c9eceed 100644 --- a/docs/docs/cli/rec.md +++ b/docs/docs/cli/rec.md @@ -1,6 +1,6 @@ --- title: stack rec -sidebar_position: 85 +sidebar_position: 98 --- # `stack rec` diff --git a/docs/docs/cli/stack.md b/docs/docs/cli/stack.md index 04f8f2e..cdf652b 100644 --- a/docs/docs/cli/stack.md +++ b/docs/docs/cli/stack.md @@ -27,6 +27,7 @@ Usage: stack [OPTIONS] COMMAND [ARGS]... │ bls BLS occupation wages (OEWS) and health-care employment (CES). │ │ comments CMS rulemaking comment text extraction & analysis. │ │ lake Lakehouse schema and data. │ +│ lead LEAD target registry, evidence ledger, and public-data mirror. │ │ llm Local RAG — index, search, tag. │ │ db DuckDB utilities. │ │ docs Documentation generation. │ @@ -38,5 +39,7 @@ Usage: stack [OPTIONS] COMMAND [ARGS]... │ prisma LLM-driven PRISMA screening workflow. │ │ mail Maddy mail server (DO + Resend smarthost). │ │ nlm NLM terminology releases and VSAC value sets. │ +│ market Market and enrichment tier: exposed companies, prices, lobbying, │ +│ Congress. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ``` diff --git a/docs/docs/cli/zot-dump-schema.md b/docs/docs/cli/zot-dump-schema.md index 50896c7..19b1641 100644 --- a/docs/docs/cli/zot-dump-schema.md +++ b/docs/docs/cli/zot-dump-schema.md @@ -1,6 +1,6 @@ --- title: stack zot dump-schema -sidebar_position: 100 +sidebar_position: 124 --- # `stack zot dump-schema` diff --git a/docs/docs/cli/zot-fetch.md b/docs/docs/cli/zot-fetch.md index 2505e23..323b493 100644 --- a/docs/docs/cli/zot-fetch.md +++ b/docs/docs/cli/zot-fetch.md @@ -1,6 +1,6 @@ --- title: stack zot fetch -sidebar_position: 105 +sidebar_position: 129 --- # `stack zot fetch` diff --git a/docs/docs/cli/zot-fix-dates.md b/docs/docs/cli/zot-fix-dates.md index f000a84..484e6cd 100644 --- a/docs/docs/cli/zot-fix-dates.md +++ b/docs/docs/cli/zot-fix-dates.md @@ -1,6 +1,6 @@ --- title: stack zot fix-dates -sidebar_position: 101 +sidebar_position: 125 --- # `stack zot fix-dates` diff --git a/docs/docs/cli/zot-fix-fields.md b/docs/docs/cli/zot-fix-fields.md index 0a1d51e..5f84a65 100644 --- a/docs/docs/cli/zot-fix-fields.md +++ b/docs/docs/cli/zot-fix-fields.md @@ -1,6 +1,6 @@ --- title: stack zot fix-fields -sidebar_position: 103 +sidebar_position: 127 --- # `stack zot fix-fields` diff --git a/docs/docs/cli/zot-fix-keys.md b/docs/docs/cli/zot-fix-keys.md index af8efe9..2d7ed7c 100644 --- a/docs/docs/cli/zot-fix-keys.md +++ b/docs/docs/cli/zot-fix-keys.md @@ -1,6 +1,6 @@ --- title: stack zot fix-keys -sidebar_position: 102 +sidebar_position: 126 --- # `stack zot fix-keys` diff --git a/docs/docs/cli/zot-verify-parity.md b/docs/docs/cli/zot-verify-parity.md index e0989fa..e72bd79 100644 --- a/docs/docs/cli/zot-verify-parity.md +++ b/docs/docs/cli/zot-verify-parity.md @@ -1,6 +1,6 @@ --- title: stack zot verify-parity -sidebar_position: 104 +sidebar_position: 128 --- # `stack zot verify-parity` diff --git a/docs/docs/cli/zot.md b/docs/docs/cli/zot.md index 9708e34..5d69f1e 100644 --- a/docs/docs/cli/zot.md +++ b/docs/docs/cli/zot.md @@ -1,6 +1,6 @@ --- title: stack zot -sidebar_position: 99 +sidebar_position: 123 --- # `stack zot` diff --git a/tests/llm/golden_lineage.yaml b/tests/llm/golden_lineage.yaml index b260c16..8a27dfc 100644 --- a/tests/llm/golden_lineage.yaml +++ b/tests/llm/golden_lineage.yaml @@ -109,3 +109,18 @@ forbid: - pattern: '\$[0-9]' unless_label: 'Addendum B' + +- id: home-visits-history + question: What is the history of home visit coding and payment, and how did commenters react to the 2023 revaluation? + mode: timeline + expect_anchors: + - item_key: PETM225D + p_id: 1676 + - item_key: PETM225D + p_id: 1679 + expect_events: + - code: "99343" + kind: deleted|cpt_panel|disappeared + year: 2023 + expect_dossier: + family: HOME-VISITS diff --git a/tests/llm/test_golden.py b/tests/llm/test_golden.py index a5ce451..a2deaf4 100644 --- a/tests/llm/test_golden.py +++ b/tests/llm/test_golden.py @@ -163,6 +163,29 @@ def test_check_dockets_fail_missing_one(): # ── check_eras ─────────────────────────────────────────────────── +def test_check_dossier_pass(): + t = Transcript( + events=[ + {"type": "dossier", "family": "HOME-VISITS"}, + _sources({"kind": "dossier", "label": "x"}), + ] + ) + assert golden.check_dossier(t, {"family": "HOME-VISITS"}).passed + + +def test_check_dossier_fail_wrong_family_and_no_source(): + t = Transcript(events=[{"type": "dossier", "family": "CCM"}, _sources()]) + result = golden.check_dossier(t, {"family": "HOME-VISITS"}) + assert not result.passed + assert "no dossier event" in result.detail and "no dossier source" in result.detail + + +def test_evaluate_runs_dossier_check(): + t = Transcript(events=[{"type": "dossier", "family": "HOME-VISITS"}, _sources()]) + results = golden.evaluate({"expect_dossier": {"family": "HOME-VISITS"}}, t) + assert [r.name for r in results] == ["dossier"] and not results[0].passed + + def test_check_eras_pass(): t = Transcript( [ @@ -214,7 +237,7 @@ def test_evaluate_short_circuits_on_error_event(): def test_golden_set_loads_and_is_well_formed(): entries = golden.load_set(GOLDEN_SET) - assert len(entries) == 7 + assert len(entries) == 8 ids = [e["id"] for e in entries] assert len(ids) == len(set(ids)), "duplicate ids" for e in entries: @@ -232,6 +255,7 @@ def test_golden_set_expected_ids_present(): "g2211-commenters-2023-vs-2025", "99490-telehealth-steps", "g2064-g2065-to-99424-99426-rate", + "home-visits-history", } diff --git a/tests/pfs/test_dossier_golden.py b/tests/pfs/test_dossier_golden.py new file mode 100644 index 0000000..c78e890 --- /dev/null +++ b/tests/pfs/test_dossier_golden.py @@ -0,0 +1,90 @@ +"""Home-visit dossier golden: the same assertions over the canned fixture +(no network) and over the stored live dossier (skips without the replica).""" + +from __future__ import annotations + +import pytest + +from conf import connect +from pfs.citecheck import check_prose +from pfs.dossier import build_dossier, read_dossier + + +def _assert_golden(d) -> None: + r = {(x.code, x.item_key): x for x in d.rounds} + hv = r["99341", "PETM225D"] + assert ( + hv.rule_year, + hv.proposed_work_rvu, + hv.final_work_rvu, + hv.ruc_percentile, + hv.decision, + ) == (2023, 1.0, 1.0, "25th", "accept") + assert ( + r["99350", "PETM225D"].final_work_rvu, + r["99350", "PETM225D"].ruc_percentile, + ) == ( + 3.6, + "median", + ) + old = r["99343", "54GTKR5G"] + assert ( + old.rule_year, + old.source, + old.ruc_work_rvu, + old.final_work_rvu, + old.decision, + old.page, + ) == (2008, "fr-table", 2.27, 2.53, "refine", 66361) + facts = list(d.facts.values()) + cms = [f for f in facts if f.kind == "cms_summary"] + assert any( + f.cite.p_id == 1679 and "CMS's quantifier: a majority of commenters" in f.text + for f in cms + ) + assert any( + f.cite.p_id == 1681 and "CMS's quantifier: a few commenters" in f.text + for f in cms + ) + assert any( + f.kind == "event" + and f.text == "99343 was deleted for CY2023." + and f.cite.p_id == 1672 + for f in facts + ) + assert any( + f.kind == "link" + and "G2211 is replaced by modifiers" in f.text + and f.cite.item_key == "JCWARTJD" + and f.cite.p_id == 6666 + for f in facts + ) + assert {(f.kind, f.cite.item_key, f.cite.p_id) for f in facts} >= { + ("link", "JCWARTJD", 1168), + ("link", "JCWARTJD", 1205), + ("link", "NHRGIHGD", 1469), + ("link", "PETM225D", 1694), + } + assert {(p.code, p.year) for p in d.payment if p.code == "99343"} == { + ("99343", y) for y in range(2015, 2023) + } + assert check_prose(d.summary, d.facts) == [] and d.check_passed + assert any(g.startswith("Federal Register PFS rules before CY") for g in d.gaps) + + +def test_home_visit_dossier_golden(home_fixture): + d = build_dossier(*home_fixture[:3], ask=home_fixture[3]) + _assert_golden(d) + + +_REPLICA = connect._replica_path("aco") + + +@pytest.mark.skipif(not _REPLICA.exists(), reason="live replica") +def test_home_visit_dossier_live(): + d = read_dossier(connect.duckdb("aco", replica=True), "HOME-VISITS") + if d is None: + pytest.skip("no stored HOME-VISITS dossier") + _assert_golden(d) + for f in d.facts.values(): + assert f.cite.url or f.cite.locator, f