Metadata-Version: 2.4
Name: cdisc-p21-triage
Version: 0.1.0
Summary: Triage layer for Pinnacle 21 Community validation reports: plain-English explanations, root-cause clustering, submission-risk mapping, and SDRG-ready export
Author: Giri
License: MIT
Keywords: cdisc,sdtm,adam,pinnacle21,validation,clinical,fda,pharma,sdrg
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl>=3.1
Dynamic: license-file

# p21-triage

Triage layer for **Pinnacle 21 Community** validation reports.

You run P21. It hands you an Excel report with 2,000 findings. p21-triage
reads that report and tells you, in plain English, what each finding means,
which ones share a root cause, which ones threaten your submission, and what
to do about each — then tracks your decisions run-over-run and writes your
SDRG summary.

This is **not a validator**: it never runs checks and never reads study
datasets. Its only input is the P21 Excel report.

## Install

```bash
pip install cdisc-p21-triage
```

(Requires Python 3.9+. Only dependency: `openpyxl`.)

## Quick start

```bash
# Explain and cluster a report's findings
p21-triage triage pinnacle21-report-2022-10-20T17-56-05-191.xlsx

# Record decisions (persisted in <report>.triage.json)
p21-triage disposition report.xlsx --key "SD1076|AE|AELAT" \
    --status document --note "AELAT added for laterality; permissible per SDTMIG"
p21-triage disposition report.xlsx --list

# Compare two runs
p21-triage diff old-report.xlsx new-report.xlsx

# Annotated Excel + SDRG-ready Markdown
p21-triage export report.xlsx --xlsx annotated.xlsx --md sdrg-section5.md

# Explain one rule
p21-triage explain report.xlsx --rule CT2001
```

Disposition statuses: `open` (default), `fix`, `document`, `waive`.
Carry decisions into the next run with `--disposition-file old-report.xlsx.triage.json`.

## Python API

```python
from p21_triage import (
    parse_report, cluster_findings, enrich_clusters,
    diff_reports, export_excel, export_markdown,
    save_disposition, apply_dispositions,
)

report = parse_report("pinnacle21-report-....xlsx")
clusters = enrich_clusters(cluster_findings(report), report.meta.engine)

for c in clusters:
    print(c.rule_id, c.domain, c.risk_level, c.record_count)
    print(" ", c.explanation)

# decisions persist in a JSON sidecar
save_disposition("report.xlsx", clusters[0].key, "waive", "sponsor decision")

# run-over-run
delta = diff_reports(parse_report("old.xlsx"), parse_report("new.xlsx"))
print(len(delta.added), "new clusters,", len(delta.resolved), "resolved")

export_excel(report, clusters, "annotated.xlsx", delta)
export_markdown(report, clusters, "sdrg.md", delta)
```

## How it works

1. **Parse** — tabs and columns are detected by *name* (alias lists cover
   version variants), never by position. Unknown format → clear error naming
   what's missing. See [FORMAT.md](FORMAT.md).
2. **Explain** — every finding gets a plain-English explanation: the report's
   own Rules tab first, then a built-in knowledge base of common rules
   (written in our own words from public rule docs), then an honest
   "not covered" fallback.
3. **Cluster** — findings collapse by `RULE_ID|DOMAIN|VARIABLES` into
   root-cause clusters. One missing codelist → one cluster, not 500 rows.
4. **Risk** — severity mapped to submission risk (FDA and PMDA semantics).
5. **Decide** — `fix` / `document` / `waive` per cluster, stored in a JSON
   sidecar; stable cluster keys carry decisions across runs.
6. **Diff** — run-over-run: new, resolved, and persistent clusters plus
   finding-level signature counts.
7. **Export** — annotated Excel (findings + clusters + rules + optional delta
   sheets) and SDRG Section 5–ready Markdown.

## Report format support

Built from public documentation of the P21 Community Excel report
(`Datasets Summary` / `Issue Summary` / `Details` / `Rules` tabs).
Version differences (renamed tabs/columns, missing Severity column in newer
versions) are handled by name-based detection — see [FORMAT.md](FORMAT.md)
for the spec and confidence levels.

## Clean-room note

Built only from Pinnacle 21's public report format and published rule
documentation. No proprietary code or data was used; all test reports are
synthetically generated in `tests/make_sample.py`.

## License

MIT — see [LICENSE](LICENSE).
