Skip to content

K-Dense-AI/scientific-agent-skills / skills/clinical-reports

clinical-reports

Verified

Creates safety-bounded draft structures and runs local deterministic checks for clinical case, diagnostic, trial, safety, and aggregate research reports. Use only with synthetic, de-identified, or aggregate inputs and verified source-fact manifests; every output requires qualified review.

FileKindSize
SKILL.mdskill md15.5 KB
assets/adverse_event_aggregate_input_template.csvother120 B
assets/case_report_template.jsonconfig2.1 KB
assets/clinical_trial_csr_template.jsonconfig2.6 KB
assets/clinical_trial_results_template.jsonconfig3.8 KB
assets/clinical_trial_safety_aggregate_template.jsonconfig1.4 KB
assets/consistency_manifest_template.jsonconfig531 B
assets/deidentification_process_checklist.jsonconfig2.1 KB
assets/lab_report_template.jsonconfig1.7 KB
assets/pathology_report_template.jsonconfig1.7 KB
assets/provenance_manifest_template.jsonconfig560 B
assets/quality_review_checklist.jsonconfig1.7 KB
assets/radiology_report_template.jsonconfig1.5 KB
assets/research_summary_template.jsonconfig1.6 KB
assets/terminology_manifest_template.jsonconfig426 B
assets/trial_protocol_reporting_checklist.jsonconfig4.2 KB
references/README.mdmarkdown2.2 KB
references/case_report_guidelines.mdmarkdown3.3 KB
references/clinical_trial_reporting.mdmarkdown5.3 KB
references/data_presentation.mdmarkdown4.1 KB
references/diagnostic_reports_standards.mdmarkdown4.3 KB
references/medical_terminology.mdmarkdown4.2 KB
references/privacy_and_deidentification.mdmarkdown4.8 KB
references/professional_review.mdmarkdown4.2 KB
references/report_type_routing.mdmarkdown4.4 KB
references/safety_reporting.mdmarkdown6.8 KB
references/sources.mdmarkdown10.8 KB
scripts/_common.pyscript9.5 KB
scripts/check_deidentification.pyscript10.7 KB
scripts/consistency_checker.pyscript13.4 KB
scripts/format_adverse_events.pyscript16.0 KB
scripts/generate_report_template.pyscript3.9 KB
scripts/provenance_validator.pyscript9.2 KB
scripts/terminology_validator.pyscript10.0 KB
scripts/validate_case_report.pyscript9.4 KB
scripts/validate_trial_report.pyscript19.9 KB

scripts/terminology_validator.py

View on GitHub
#!/usr/bin/env python3
"""Check terminology-manifest schema and optional caller-supplied local dictionary."""

from __future__ import annotations

import argparse
import re
import sys
from typing import Any

sys.dont_write_bytecode = True

from _common import (  # noqa: E402
    ValidationError,
    error_report,
    load_json_object,
    parse_iso_date,
    require_bool,
    require_data_class,
    require_exact_keys,
    require_identifier,
    require_string,
    write_json_report,
)

TOOL = "terminology_validator"
CODE_PATTERNS = {
    "MedDRA": re.compile(r"^\d{8}$"),
    "LOINC": re.compile(r"^\d{1,7}-\d$"),
    "SNOMED_CT": re.compile(r"^[1-9]\d{5,17}$"),
    "ICD_10_CM": re.compile(r"^[A-Z][0-9A-Z]{2}(?:\.[0-9A-Z]{1,4})?$"),
    "UCUM": re.compile(r"^[A-Za-z0-9%.\[\]{}()/*^+'_-]{1,80}$"),
}
CODING_STATUSES = {"verified_by_qualified_reviewer", "unverified"}
TOP_LEVEL_FIELDS = {
    "schema_version",
    "artifact_kind",
    "manifest_status",
    "safety_notice",
    "data_classification",
    "authorized_purpose",
    "authorization_verified",
    "provenance_manifest",
    "entries",
}
ENTRY_FIELDS = {
    "system",
    "system_uri",
    "code",
    "display",
    "version",
    "language",
    "source_fact_id",
    "coding_status",
    "verified_by_role",
    "verified_at",
}


def _validate_entry(entry: Any, index: int) -> tuple[str, str, str, str, list[str]]:
    entry = require_exact_keys(entry, ENTRY_FIELDS, f"entries[{index}]")
    system = require_string(entry.get("system"), f"entries[{index}].system", max_length=32)
    if system not in CODE_PATTERNS:
        raise ValidationError(
            f"entries[{index}].system must be one of {sorted(CODE_PATTERNS)}"
        )
    require_string(
        entry.get("system_uri"),
        f"entries[{index}].system_uri",
        max_length=200,
    )
    code = require_string(entry.get("code"), f"entries[{index}].code", max_length=80)
    if not CODE_PATTERNS[system].fullmatch(code):
        raise ValidationError(f"entries[{index}].code fails {system} syntax")
    display = require_string(
        entry.get("display"),
        f"entries[{index}].display",
        max_length=500,
    )
    version = require_string(
        entry.get("version"),
        f"entries[{index}].version",
        max_length=80,
    )
    require_string(entry.get("language"), f"entries[{index}].language", max_length=32)
    require_identifier(
        entry.get("source_fact_id"),
        f"entries[{index}].source_fact_id",
    )
    status = entry.get("coding_status")
    if not isinstance(status, str) or status not in CODING_STATUSES:
        raise ValidationError(f"entries[{index}].coding_status is invalid")
    warnings: list[str] = []
    if status == "verified_by_qualified_reviewer":
        require_string(
            entry.get("verified_by_role"),
            f"entries[{index}].verified_by_role",
            max_length=100,
        )
        parse_iso_date(entry.get("verified_at"), f"entries[{index}].verified_at")
    else:
        warnings.append(f"entries[{index}] remains unverified")
    if system == "MedDRA" and not re.fullmatch(r"\d{1,2}\.\d", version):
        warnings.append(f"entries[{index}] MedDRA version has an unusual format")
    return system, version, code, display, warnings


def _load_dictionary(raw_path: str) -> dict[tuple[str, str, str], str]:
    _, data = load_json_object(raw_path)
    require_exact_keys(
        data,
        {"schema_version", "artifact_kind", "entries"},
        "dictionary",
    )
    if data.get("schema_version") != "2.0":
        raise ValidationError("dictionary schema_version must be 2.0")
    if data.get("artifact_kind") != "terminology_dictionary":
        raise ValidationError("dictionary artifact_kind must be terminology_dictionary")
    entries = data.get("entries")
    if not isinstance(entries, list) or not entries:
        raise ValidationError("dictionary entries must be a non-empty array")
    if len(entries) > 20_000:
        raise ValidationError("dictionary may contain at most 20,000 entries")
    dictionary: dict[tuple[str, str, str], str] = {}
    for index, entry in enumerate(entries):
        entry = require_exact_keys(
            entry,
            {"system", "version", "code", "display"},
            f"dictionary entries[{index}]",
        )
        system = require_string(
            entry.get("system"),
            f"dictionary entries[{index}].system",
            max_length=32,
        )
        version = require_string(
            entry.get("version"),
            f"dictionary entries[{index}].version",
            max_length=80,
        )
        code = require_string(
            entry.get("code"),
            f"dictionary entries[{index}].code",
            max_length=80,
        )
        display = require_string(
            entry.get("display"),
            f"dictionary entries[{index}].display",
            max_length=500,
        )
        key = (system, version, code)
        if key in dictionary and dictionary[key] != display:
            raise ValidationError(f"dictionary contains conflicting duplicate at index {index}")
        dictionary[key] = display
    return dictionary


def validate_terminology_manifest(
    data: dict[str, Any],
    dictionary: dict[tuple[str, str, str], str] | None = None,
) -> dict[str, Any]:
    """Validate schema and optional exact tuple matches."""
    errors: list[str] = []
    warnings: list[str] = []
    try:
        require_exact_keys(data, TOP_LEVEL_FIELDS, "manifest")
        if data.get("schema_version") != "2.0":
            raise ValidationError("schema_version must be 2.0")
        if data.get("manifest_status") != "BLOCKED_INCOMPLETE":
            raise ValidationError("manifest_status must remain BLOCKED_INCOMPLETE")
        require_string(data.get("safety_notice"), "safety_notice", max_length=1000)
        require_string(data.get("authorized_purpose"), "authorized_purpose")
        if not require_bool(data.get("authorization_verified"), "authorization_verified"):
            raise ValidationError("authorization_verified must be true")
        require_string(data.get("provenance_manifest"), "provenance_manifest")
    except ValidationError as exc:
        errors.append(str(exc))
    if data.get("artifact_kind") != "terminology_manifest":
        errors.append("artifact_kind must be terminology_manifest")
    try:
        require_data_class(data.get("data_classification"))
    except ValidationError as exc:
        errors.append(str(exc))

    entries = data.get("entries")
    if not isinstance(entries, list) or not entries:
        errors.append("entries must be a non-empty array")
        entries = []
    if len(entries) > 5_000:
        errors.append("entries may contain at most 5,000 items")

    seen: set[tuple[str, str, str]] = set()
    verified_count = 0
    dictionary_match_count = 0
    for index, entry in enumerate(entries[:5_000]):
        try:
            system, version, code, display, entry_warnings = _validate_entry(
                entry,
                index,
            )
            warnings.extend(entry_warnings)
            key = (system, version, code)
            if key in seen:
                errors.append(f"entries[{index}] duplicates a prior system/version/code")
            seen.add(key)
            if entry.get("coding_status") == "verified_by_qualified_reviewer":
                verified_count += 1
            if dictionary is not None:
                expected_display = dictionary.get(key)
                if expected_display is None:
                    errors.append(f"entries[{index}] is absent from the supplied dictionary")
                elif expected_display != display:
                    errors.append(
                        f"entries[{index}] display does not match the supplied dictionary"
                    )
                else:
                    dictionary_match_count += 1
        except ValidationError as exc:
            errors.append(str(exc))

    if dictionary is None:
        warnings.append(
            "No local dictionary supplied; code existence, currency, and display were not checked."
        )
        success_status = "SCHEMA_VALID_SYNTAX_ONLY_REVIEW_REQUIRED"
    else:
        success_status = "SCHEMA_AND_LOCAL_DICTIONARY_MATCH_REVIEW_REQUIRED"

    return {
        "tool": TOOL,
        "status": "BLOCKED" if errors else success_status,
        "entry_count": len(entries),
        "qualified_reviewer_verified_count": verified_count,
        "local_dictionary_match_count": dictionary_match_count,
        "errors": errors,
        "warnings": warnings,
        "limitations": [
            "Syntax or local-dictionary matching does not establish clinical correctness.",
            "Caller is responsible for dictionary authority, version, license, and completeness.",
        ],
        "review_required": True,
        "authorizes_clinical_use_or_submission": False,
    }


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description=(
            "Check a bounded terminology JSON manifest. Optional dictionary comparison "
            "uses a caller-supplied local JSON file and never calls a network service."
        )
    )
    parser.add_argument("input_file", help="Local terminology manifest (.json)")
    parser.add_argument("--dictionary", help="Optional authorized local dictionary (.json)")
    parser.add_argument("-o", "--output", help="Optional local JSON report")
    parser.add_argument("--overwrite", action="store_true")
    return parser


def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    try:
        _, data = load_json_object(args.input_file)
        dictionary = _load_dictionary(args.dictionary) if args.dictionary else None
        report = validate_terminology_manifest(data, dictionary)
    except (OSError, ValidationError) as exc:
        report = error_report(TOOL, exc)
    try:
        write_json_report(report, args.output, overwrite=args.overwrite)
    except (OSError, ValidationError) as exc:
        print(str(exc), file=sys.stderr)
        return 2
    return 0 if report["status"].startswith("SCHEMA_") else 1


if __name__ == "__main__":
    raise SystemExit(main())
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall