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/provenance_validator.py

View on GitHub
#!/usr/bin/env python3
"""Validate source-fact-to-claim traceability without opening source records."""

from __future__ import annotations

import argparse
import re
import sys
from typing import Any

sys.dont_write_bytecode = True

from _common import (  # noqa: E402
    SHA256_RE,
    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 = "provenance_validator"
LOCAL_LOCATOR_RE = re.compile(r"^local:[A-Za-z0-9_./:-]{1,280}$")
SOURCE_KINDS = {
    "synthetic_record",
    "deidentified_record",
    "aggregate_output",
    "protocol",
    "statistical_analysis_plan",
    "published_source",
    "authorized_system_record",
}
FACT_FIELDS = {
    "fact_id",
    "source_record_kind",
    "record_locator",
    "field_path",
    "value_hash_sha256",
    "verification_status",
    "verified_by_role",
    "verified_at",
    "source_version",
}
CLAIM_FIELDS = {
    "claim_id",
    "artifact_field_path",
    "fact_ids",
    "support_status",
}
TOP_LEVEL_FIELDS = {
    "schema_version",
    "artifact_kind",
    "manifest_status",
    "safety_notice",
    "data_classification",
    "authorized_purpose",
    "authorization_verified",
    "facts",
    "claims",
    "review",
}


def validate_provenance(data: dict[str, Any]) -> dict[str, Any]:
    """Validate bounded metadata links while preserving source separation."""
    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)
    except ValidationError as exc:
        errors.append(str(exc))
    if data.get("artifact_kind") != "provenance_manifest":
        errors.append("artifact_kind must be provenance_manifest")
    try:
        require_data_class(data.get("data_classification"))
        require_string(data.get("authorized_purpose"), "authorized_purpose")
        if not require_bool(data.get("authorization_verified"), "authorization_verified"):
            errors.append("authorization_verified must be true")
    except ValidationError as exc:
        errors.append(str(exc))

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

    fact_ids: set[str] = set()
    for index, fact in enumerate(facts[:10_000]):
        try:
            fact = require_exact_keys(fact, FACT_FIELDS, f"facts[{index}]")
        except ValidationError as exc:
            errors.append(str(exc))
            continue
        try:
            fact_id = require_identifier(fact.get("fact_id"), f"facts[{index}].fact_id")
            if fact_id in fact_ids:
                errors.append(f"duplicate fact_id: {fact_id}")
            fact_ids.add(fact_id)
            if (
                not isinstance(fact.get("source_record_kind"), str)
                or fact.get("source_record_kind") not in SOURCE_KINDS
            ):
                errors.append(f"facts[{index}].source_record_kind is invalid")
            locator = require_string(
                fact.get("record_locator"),
                f"facts[{index}].record_locator",
                max_length=286,
            )
            if not LOCAL_LOCATOR_RE.fullmatch(locator):
                errors.append(
                    f"facts[{index}].record_locator must be a local: locator"
                )
            require_string(
                fact.get("field_path"),
                f"facts[{index}].field_path",
                max_length=300,
            )
            value_hash = require_string(
                fact.get("value_hash_sha256"),
                f"facts[{index}].value_hash_sha256",
                max_length=64,
            )
            if not SHA256_RE.fullmatch(value_hash):
                errors.append(f"facts[{index}].value_hash_sha256 is invalid")
            if fact.get("verification_status") != "verified":
                errors.append(f"facts[{index}] is not verified")
            require_string(
                fact.get("verified_by_role"),
                f"facts[{index}].verified_by_role",
                max_length=100,
            )
            parse_iso_date(fact.get("verified_at"), f"facts[{index}].verified_at")
            require_string(
                fact.get("source_version"),
                f"facts[{index}].source_version",
                max_length=100,
            )
        except ValidationError as exc:
            errors.append(str(exc))

    claim_ids: set[str] = set()
    referenced_facts: set[str] = set()
    for index, claim in enumerate(claims[:10_000]):
        try:
            claim = require_exact_keys(claim, CLAIM_FIELDS, f"claims[{index}]")
        except ValidationError as exc:
            errors.append(str(exc))
            continue
        try:
            claim_id = require_identifier(
                claim.get("claim_id"),
                f"claims[{index}].claim_id",
            )
            if claim_id in claim_ids:
                errors.append(f"duplicate claim_id: {claim_id}")
            claim_ids.add(claim_id)
            require_string(
                claim.get("artifact_field_path"),
                f"claims[{index}].artifact_field_path",
                max_length=300,
            )
            links = claim.get("fact_ids")
            if not isinstance(links, list) or not links:
                errors.append(f"claims[{index}].fact_ids must be a non-empty array")
                links = []
            for linked in links:
                linked_id = require_identifier(linked, f"claims[{index}].fact_ids")
                referenced_facts.add(linked_id)
                if linked_id not in fact_ids:
                    errors.append(
                        f"claims[{index}] references unknown fact_id {linked_id}"
                    )
            if claim.get("support_status") != "supported_by_verified_facts":
                errors.append(f"claims[{index}] is not marked supported_by_verified_facts")
        except ValidationError as exc:
            errors.append(str(exc))

    unused = sorted(fact_ids - referenced_facts)
    if unused:
        warnings.append(f"{len(unused)} verified facts are not linked to a claim")

    review = data.get("review")
    try:
        review = require_exact_keys(
            review,
            {
                "source_owner_review",
                "quality_review",
                "privacy_review",
                "release_authorized",
            },
            "review",
        )
        for field in ("source_owner_review", "quality_review", "privacy_review"):
            if review.get(field) != "completed":
                warnings.append(f"review.{field} remains required")
        if review.get("release_authorized") is not False:
            errors.append("review.release_authorized must remain false")
    except ValidationError as exc:
        errors.append(str(exc))

    return {
        "tool": TOOL,
        "status": "BLOCKED" if errors else "TRACEABILITY_COMPLETE_REVIEW_REQUIRED",
        "fact_count": len(facts),
        "claim_count": len(claims),
        "linked_fact_count": len(referenced_facts),
        "errors": errors,
        "warnings": warnings,
        "limitations": [
            "Source records were not opened and hash values were not recomputed.",
            "Traceability metadata does not establish source truth or clinical correctness.",
        ],
        "review_required": True,
        "authorizes_clinical_use_or_submission": False,
    }


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description=(
            "Check bounded local source-fact traceability metadata. "
            "Does not open source records or copy clinical content."
        )
    )
    parser.add_argument("input_file", help="Local provenance manifest (.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)
        report = validate_provenance(data)
    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"] == "TRACEABILITY_COMPLETE_REVIEW_REQUIRED" 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