npm - medsci-skills - Versions diffs - 4.1.0 - Mend

medsci-skills 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (702) hide show

package/skills/academic-aio/references/schema_markup_templates/Dataset.jsonld ADDED Viewed

@@ -0,0 +1,36 @@
+{
+  "@context": "https://schema.org",
+  "@type": "Dataset",
+  "name": "<dataset name>",
+  "description": "<dataset description: modality, n cases, anatomy, task>",
+  "url": "https://doi.org/10.5281/zenodo.<id>",
+  "identifier": "10.5281/zenodo.<id>",
+  "license": "https://creativecommons.org/licenses/by/4.0/",
+  "creator": [
+    {
+      "@type": "Person",
+      "name": "<First Last>",
+      "identifier": "https://orcid.org/0000-0000-0000-0000"
+    }
+  ],
+  "datePublished": "YYYY-MM-DD",
+  "isPartOf": {
+    "@type": "ScholarlyArticle",
+    "@id": "https://doi.org/10.xxxx/yyyy"
+  },
+  "variableMeasured": [
+    {"@type": "PropertyValue", "name": "<measurement 1, e.g., AUC>"},
+    {"@type": "PropertyValue", "name": "<measurement 2, e.g., sensitivity>"}
+  ],
+  "distribution": {
+    "@type": "DataDownload",
+    "encodingFormat": "application/zip",
+    "contentUrl": "<direct download URL>",
+    "contentSize": "<bytes>"
+  },
+  "keywords": ["<task>", "<modality>", "<anatomy>", "<dataset family>"],
+  "spatialCoverage": "<country/region of provenance>",
+  "temporalCoverage": "YYYY/YYYY",
+  "citation": "<APA or Vancouver citation of the parent paper>",
+  "isAccessibleForFree": true
+}

package/skills/academic-aio/references/schema_markup_templates/Person.jsonld ADDED Viewed

@@ -0,0 +1,30 @@
+{
+  "@context": "https://schema.org",
+  "@type": "Person",
+  "name": "<First Last>",
+  "givenName": "<First>",
+  "familyName": "<Last>",
+  "identifier": "https://orcid.org/0000-0000-0000-0000",
+  "url": "<personal landing page URL>",
+  "jobTitle": "<Resident / Researcher / Faculty>",
+  "affiliation": [
+    {
+      "@type": "Organization",
+      "name": "<Department, Institution>",
+      "address": "<City, Country>"
+    }
+  ],
+  "alumniOf": {
+    "@type": "Organization",
+    "name": "<medical school or PhD institution>"
+  },
+  "knowsAbout": ["Radiology", "Medical AI", "Deep learning"],
+  "sameAs": [
+    "https://orcid.org/0000-0000-0000-0000",
+    "https://scholar.google.com/citations?user=<id>",
+    "https://www.semanticscholar.org/author/<id>",
+    "https://github.com/<username>",
+    "https://huggingface.co/<username>",
+    "https://www.linkedin.com/in/<username>"
+  ]
+}

package/skills/academic-aio/references/schema_markup_templates/README.md ADDED Viewed

@@ -0,0 +1,43 @@
+# Schema.org JSON-LD Templates
+Embed-ready JSON-LD markup for academic-aio Section 5 (GitHub / CITATION.cff / Zenodo / Hugging Face) and Section 6 (author landing page). Schema.org markup is read by Google Scholar's structured-data parser, by AI overview engines, and by RAG systems that crawl repository pages.
+## Files
+- **`ScholarlyArticle.jsonld`** — embed in the paper landing page or repository README. Pairs each paper with DOI, PMID, abstract, license, OA flag, and citation graph anchors.
+- **`CodeRepository.jsonld`** — embed in the repository README or as `.well-known/scholarly.jsonld`. Links code to its parent article via `isPartOf`.
+- **`Dataset.jsonld`** — embed at the Zenodo or Hugging Face dataset landing page. Includes provenance, license, and variable-level metadata.
+- **`Person.jsonld`** — embed at the author landing page or institutional profile. Cross-links ORCID, Scholar, Semantic Scholar, GitHub, Hugging Face, LinkedIn.
+## How to embed
+### In a Markdown README (GitHub renders the HTML script tag inside HTML blocks)
+```html
+<script type="application/ld+json">
+{ ... contents of ScholarlyArticle.jsonld ... }
+</script>
+```
+### In a personal landing page
+Place the script tag in the `<head>` of the HTML page. For static-site generators (Hugo, Jekyll, Next.js), generate the JSON-LD at build time from frontmatter.
+### Validation
+Run `scripts/validate_schema.py path/to/file.jsonld` to verify syntactic validity and required-field presence before deploy.
+```bash
+python scripts/validate_schema.py references/schema_markup_templates/*.jsonld
+```
+## Anti-hallucination
+- Do not auto-fill placeholder values (`<First Last>`, `0000-0000-0000-0000`, `10.xxxx/yyyy`). Mark unknown fields as `null` or remove the field — partial fabricated identifiers are worse than missing ones.
+- Verify DOI format `10.{prefix}/{suffix}` and ORCID format before commit.
+## Related
+- `SKILL.md` Section 5 — README, CITATION.cff, Zenodo, Hugging Face
+- `SKILL.md` Section 6 — Authority and E-E-A-T signals
+- `SKILL.md` Section 7 — Citation-fabrication defense

package/skills/academic-aio/references/schema_markup_templates/ScholarlyArticle.jsonld ADDED Viewed

@@ -0,0 +1,55 @@
+{
+  "@context": "https://schema.org",
+  "@type": "ScholarlyArticle",
+  "headline": "<paper title verbatim>",
+  "alternativeHeadline": "<short version or subtitle, optional>",
+  "datePublished": "YYYY-MM-DD",
+  "author": [
+    {
+      "@type": "Person",
+      "name": "<First Last>",
+      "givenName": "<First>",
+      "familyName": "<Last>",
+      "identifier": "https://orcid.org/0000-0000-0000-0000",
+      "affiliation": {
+        "@type": "Organization",
+        "name": "<Department, Institution>",
+        "address": "<City, Country>"
+      }
+    }
+  ],
+  "publisher": {
+    "@type": "Organization",
+    "name": "<Journal publisher>"
+  },
+  "isPartOf": {
+    "@type": "PublicationVolume",
+    "name": "<Journal name>",
+    "volumeNumber": "<Volume>",
+    "issueNumber": "<Issue>",
+    "pageStart": "<start>",
+    "pageEnd": "<end>"
+  },
+  "identifier": [
+    {"@type": "PropertyValue", "propertyID": "DOI", "value": "10.xxxx/yyyy"},
+    {"@type": "PropertyValue", "propertyID": "PMID", "value": "<PMID>"},
+    {"@type": "PropertyValue", "propertyID": "PMC", "value": "PMC<id>"}
+  ],
+  "url": "https://doi.org/10.xxxx/yyyy",
+  "license": "https://creativecommons.org/licenses/by/4.0/",
+  "abstract": "<200-300 word abstract verbatim>",
+  "keywords": ["<MeSH term 1>", "<MeSH term 2>", "<RadLex term>", "<topic term>"],
+  "isAccessibleForFree": true,
+  "citation": [
+    {
+      "@type": "ScholarlyArticle",
+      "@id": "https://doi.org/10.xxxx/zzzz",
+      "name": "<seminal reference title>"
+    }
+  ],
+  "subjectOf": {
+    "@type": "Dataset",
+    "@id": "https://doi.org/10.5281/zenodo.<id>",
+    "name": "<companion dataset name>"
+  }
+}

package/skills/academic-aio/scripts/batch_metadata_audit.py ADDED Viewed

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""
+batch_metadata_audit.py — Audit multiple medical-AI repos and Hugging Face cards
+for AIO compliance.
+Per repository:
+- README.md present, with DOI link / badge and a How-to-cite or Citation section
+- CITATION.cff present at root with title/authors/version + at least one ORCID
+- LICENSE present
+Per Hugging Face card (model or dataset):
+- YAML front matter present with license / library_name / tags
+- Required prose sections: intended use, training data, evaluation, limitations,
+  ethical considerations
+- No PHI patterns matched
+Usage:
+    python batch_metadata_audit.py /path/to/repo1 /path/to/repo2 \\
+        --hf-card model_card.md --output qc/aio_batch.json
+    python batch_metadata_audit.py --hf-card dataset_card.md --fail-on-issue
+"""
+from __future__ import annotations
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+PHI_PATTERNS = [
+    re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),                 # US SSN
+    re.compile(r"\b\d{6}-\d{7}\b"),                       # KR resident registration number
+    re.compile(r"MRN[:\s]*\d+", re.I),                    # medical record number
+    re.compile(r"\bpatient[\s_]?id[:\s]*\d+", re.I),      # patient id
+    re.compile(r"\b\d{4}-\d{2}-\d{2}\b.*\bDOB\b", re.I),  # DOB pattern
+]
+CITATION_CFF_REQUIRED = ("title", "authors", "version")
+HF_CARD_REQUIRED_YAML = ("license", "library_name", "tags")
+HF_CARD_REQUIRED_SECTIONS = (
+    "intended use",
+    "training data",
+    "evaluation",
+    "limitations",
+    "ethical considerations",
+)
+def _phi_hits(text: str) -> list[str]:
+    hits: list[str] = []
+    for pat in PHI_PATTERNS:
+        m = pat.search(text)
+        if m:
+            hits.append(f"Possible PHI pattern matched: {m.group(0)[:30]!r}")
+    return hits
+def check_readme(path: Path) -> dict:
+    if not path.exists():
+        return {"present": False, "issues": ["README.md missing"]}
+    text = path.read_text()
+    issues: list[str] = []
+    if "DOI" not in text and "doi.org" not in text.lower():
+        issues.append("No DOI badge or link in README")
+    if "## How to cite" not in text and "## Citation" not in text:
+        issues.append('No "How to cite" / "Citation" section')
+    if not any(s in text.lower() for s in ("quickstart", "getting started", "installation")):
+        issues.append("No quickstart / installation section")
+    return {"present": True, "issues": issues}
+def check_citation_cff(path: Path) -> dict:
+    if not path.exists():
+        return {"present": False, "issues": ["CITATION.cff missing at repo root"]}
+    text = path.read_text()
+    issues: list[str] = []
+    for key in CITATION_CFF_REQUIRED:
+        if f"{key}:" not in text:
+            issues.append(f"CITATION.cff missing key: {key}")
+    if "orcid" not in text.lower():
+        issues.append("CITATION.cff has no ORCID identifier(s)")
+    return {"present": True, "issues": issues}
+def check_license(path: Path) -> dict:
+    return {
+        "present": path.exists(),
+        "issues": [] if path.exists() else ["LICENSE missing"],
+    }
+def check_hf_card(path: Path) -> dict:
+    if not path.exists():
+        return {"present": False, "issues": ["HF card missing"]}
+    text = path.read_text()
+    issues: list[str] = []
+    if not text.startswith("---"):
+        issues.append("HF card missing YAML front matter")
+    else:
+        front_parts = text.split("---", 2)
+        front = front_parts[1] if len(front_parts) >= 3 else ""
+        for key in HF_CARD_REQUIRED_YAML:
+            if f"{key}:" not in front:
+                issues.append(f"HF card YAML missing key: {key}")
+    body_lower = text.lower()
+    for section in HF_CARD_REQUIRED_SECTIONS:
+        if section not in body_lower:
+            issues.append(f"HF card missing section: {section}")
+    issues.extend(_phi_hits(text))
+    return {"present": True, "issues": issues}
+def audit_repo(repo: Path) -> dict:
+    return {
+        "repo": str(repo),
+        "readme": check_readme(repo / "README.md"),
+        "citation_cff": check_citation_cff(repo / "CITATION.cff"),
+        "license": check_license(repo / "LICENSE"),
+    }
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Audit multiple repos and HF cards for AIO compliance."
+    )
+    parser.add_argument("paths", nargs="*", type=Path,
+                        help="Repository directories to audit.")
+    parser.add_argument("--hf-card", action="append", type=Path, default=[],
+                        help="Path to a Hugging Face model/dataset card markdown file.")
+    parser.add_argument("--output", type=Path, default=None,
+                        help="Write JSON report to this path (default: stdout).")
+    parser.add_argument("--fail-on-issue", action="store_true",
+                        help="Exit 1 if any issues are detected.")
+    args = parser.parse_args(argv)
+    if not args.paths and not args.hf_card:
+        parser.error("Provide at least one repo path or --hf-card.")
+    report: dict = {"repos": [], "hf_cards": []}
+    for path in args.paths:
+        if path.is_dir():
+            report["repos"].append(audit_repo(path))
+        else:
+            report["repos"].append({"repo": str(path),
+                                    "issues": ["Not a directory"]})
+    for card in args.hf_card:
+        report["hf_cards"].append({"path": str(card), **check_hf_card(card)})
+    out = json.dumps(report, indent=2, ensure_ascii=False)
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(out)
+    else:
+        print(out)
+    has_issues = any(
+        (r.get("readme", {}).get("issues") or
+         r.get("citation_cff", {}).get("issues") or
+         r.get("license", {}).get("issues") or
+         r.get("issues"))
+        for r in report["repos"]
+    ) or any(c.get("issues") for c in report["hf_cards"])
+    return 1 if (args.fail_on_issue and has_issues) else 0
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/academic-aio/scripts/validate_schema.py ADDED Viewed

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+validate_schema.py — JSON-LD validator for academic-aio schema markup files.
+Validates:
+- JSON-LD syntactic validity
+- @context = "https://schema.org"
+- @type matches one of the supported types
+- Required fields present (per schema.org minimal recommendations + medsci-skills policy)
+- Identifier format (DOI, ORCID)
+Usage:
+    python validate_schema.py path/to/file.jsonld [path/to/another.jsonld ...]
+    python validate_schema.py --strict references/schema_markup_templates/*.jsonld
+"""
+from __future__ import annotations
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+REQUIRED_BY_TYPE: dict[str, list[str]] = {
+    "ScholarlyArticle": ["headline", "datePublished", "author", "identifier", "url"],
+    "SoftwareSourceCode": ["name", "codeRepository", "license", "datePublished", "author"],
+    "Dataset": ["name", "description", "license", "creator", "datePublished"],
+    "Person": ["name", "identifier"],
+}
+DOI_RE = re.compile(r"^10\.\d{4,9}/[-._;()/:A-Za-z0-9]+$")
+ORCID_RE = re.compile(r"^https://orcid\.org/\d{4}-\d{4}-\d{4}-\d{3}[\dX]$")
+PLACEHOLDER_TOKENS = ("<", "xxxx", "yyyy", "0000-0000-0000-0000")
+def _is_placeholder(value: str) -> bool:
+    """Return True for template placeholder strings that should skip strict checks."""
+    if not isinstance(value, str):
+        return False
+    lowered = value.lower()
+    return any(tok in lowered for tok in PLACEHOLDER_TOKENS)
+def validate(path: Path) -> list[str]:
+    errors: list[str] = []
+    try:
+        data = json.loads(path.read_text())
+    except FileNotFoundError:
+        return [f"File not found: {path}"]
+    except json.JSONDecodeError as exc:
+        return [f"Invalid JSON: {exc}"]
+    ctx = data.get("@context")
+    if ctx != "https://schema.org":
+        errors.append(f'@context must be "https://schema.org" (got {ctx!r})')
+    typ = data.get("@type")
+    if typ not in REQUIRED_BY_TYPE:
+        errors.append(
+            f"@type {typ!r} not recognized "
+            f"(expected one of {sorted(REQUIRED_BY_TYPE)})"
+        )
+        return errors
+    for field in REQUIRED_BY_TYPE[typ]:
+        if field not in data or data[field] in (None, "", []):
+            errors.append(f"Missing required field: {field}")
+    ident = data.get("identifier")
+    if isinstance(ident, list):
+        for entry in ident:
+            if isinstance(entry, dict) and entry.get("propertyID") == "DOI":
+                value = entry.get("value", "")
+                if value and not _is_placeholder(value) and not DOI_RE.match(value):
+                    errors.append(f"DOI does not match canonical format: {value!r}")
+    if typ == "Person" and isinstance(ident, str):
+        if not _is_placeholder(ident) and not ORCID_RE.match(ident):
+            errors.append(f"Person identifier should be an ORCID URL (got {ident!r})")
+    authors = data.get("author") or data.get("creator") or []
+    if isinstance(authors, list):
+        for i, a in enumerate(authors):
+            if isinstance(a, dict) and not a.get("name"):
+                errors.append(f"author[{i}] missing 'name'")
+    return errors
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate academic-aio Schema.org JSON-LD markup files."
+    )
+    parser.add_argument("files", nargs="+", type=Path)
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit 1 on any error (default behaviour; flag retained for clarity).",
+    )
+    args = parser.parse_args(argv)
+    overall_ok = True
+    for path in args.files:
+        errors = validate(path)
+        if errors:
+            overall_ok = False
+            print(f"FAIL  {path}")
+            for e in errors:
+                print(f"  - {e}")
+        else:
+            print(f"PASS  {path}")
+    return 0 if overall_ok else 1
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/academic-aio/skill.yml ADDED Viewed

@@ -0,0 +1,36 @@
+schema_version: 2
+name: academic-aio
+layer: C
+owner_domain: manuscript_optimization
+when_to_use: "Optimize a medical-AI manuscript's title, abstract, and structured summary boxes for AI search engines and RAG tools, integrating TRIPOD+AI/CLAIM/STARD-AI reporting requirements."
+when_NOT_to_use: "Drafting a manuscript from scratch (use write-paper); removing AI writing tells (use humanize)."
+inputs:
+  - "draft manuscript / abstract / title (Markdown)"
+outputs:
+  - "AIO-optimized title, abstract, structured summary boxes"
+  - "visible pass/fail checklist"
+deterministic_scripts:
+  - scripts/validate_schema.py
+  - scripts/batch_metadata_audit.py
+side_effects:
+  - writes_project_artifacts
+downstream_consumers:
+  - self-review
+  - check-reporting
+forbidden_actions:
+  - silently_rewrite_without_user_review
+  - fabricate_reporting_guideline_compliance
+# v2.1 quality card
+purpose: "Make a medical-AI manuscript discoverable and citable by AI search/RAG tools without sacrificing reporting-guideline compliance."
+safety_boundaries:
+  - "Off by default in autonomous pipelines; rewrites require user review (no silent rewrite)."
+  - "Reporting-guideline claims are checked, never asserted without the underlying item being present."
+known_limitations:
+  - "GEO/AIO heuristics evolve with each engine; recommendations are point-in-time."
+  - "Does not draft new scientific content; optimizes existing approved text only."
+validation_commands:
+  - "python3 scripts/validate_schema.py <summary-box-file>"
+evidence_surface: bundled_script

package/skills/academic-aio/templates/aio_audit_checklist.md.j2 ADDED Viewed

@@ -0,0 +1,108 @@
+{# Jinja2 template — render with `aio_audit_checklist.md.j2` + variables.
+Variables expected:
+  artifact_path : str           absolute path of the artifact under audit
+  artifact_type : str           manuscript | preprint | readme | citation_cff | hf_card | dataset_card
+  artifact_phase : str          pre-draft | drafting | pre-submission | post-acceptance | post-publication
+  journal_target : str | None   optional journal id from journal_summarybox_templates.yaml
+  audit_date : str              YYYY-MM-DD
+  reviewer : str                short name of the auditor
+  items : list[dict]            loaded from references/checklists/AIO_GENERAL.md "items" list (schema v2)
+  reporting_guideline_pending : bool
+  numerical_audit_pending : bool
+  humanize_pending : bool
+Render hint (Python):
+    from jinja2 import Environment, FileSystemLoader
+    env = Environment(loader=FileSystemLoader("templates"))
+    tpl = env.get_template("aio_audit_checklist.md.j2")
+    rendered = tpl.render(artifact_path="...", artifact_type="manuscript",
+                          artifact_phase="pre-submission", ...)
+#}
+# AIO Audit — {{ artifact_path }}
+**Artifact type**: {{ artifact_type }}
+**Phase**: {{ artifact_phase }}
+{% if journal_target -%}
+**Journal target**: {{ journal_target }}
+{% endif -%}
+**Audit date**: {{ audit_date }}
+**Reviewer**: {{ reviewer }}
+{# Filter: artifact_type in applies_to, artifact_phase in applies_to_phase #}
+{% set in_scope = items
+   | selectattr('applies_to', 'contains', artifact_type)
+   | selectattr('applies_to_phase', 'contains', artifact_phase)
+   | list -%}
+{% set deferred = in_scope | selectattr('defers_to', 'defined') | list -%}
+{% set actionable = in_scope | rejectattr('defers_to', 'defined') | list -%}
+{# Sort actionable by expected_lift: high → medium → low #}
+{% set high = actionable | selectattr('expected_lift', 'equalto', 'high') | list -%}
+{% set med  = actionable | selectattr('expected_lift', 'equalto', 'medium') | list -%}
+{% set low  = actionable | selectattr('expected_lift', 'equalto', 'low') | list -%}
+## Top 5 — ranked by expected_lift (high → medium → low)
+| Rank | ID | Rule | Lift | Status | Reason | Suggested edit |
+|------|----|------|------|--------|--------|----------------|
+{% set ordered = (high + med + low)[:5] -%}
+{% for item in ordered -%}
+| {{ loop.index }} | {{ item.id }} | {{ item.rule }} | {{ item.expected_lift }} |  |  |  |
+{% endfor %}
+## Full applicable checklist
+| ID | Rule | Lift | Priority | Status | Reason | Suggested edit |
+|----|------|------|----------|--------|--------|----------------|
+{% for item in (high + med + low) -%}
+| {{ item.id }} | {{ item.rule }} | {{ item.expected_lift }} | {{ item.priority }} |  |  |  |
+{% endfor %}
+## Deferred items (audit elsewhere)
+| ID | Rule | Status | Defers to |
+|----|------|--------|-----------|
+{% for item in deferred -%}
+| {{ item.id }} | {{ item.rule }} |  | {{ item.defers_to }} |
+{% endfor %}
+## Out-of-phase items (NA — surface only if phase changes)
+{% set out_of_scope = items
+   | selectattr('applies_to', 'contains', artifact_type)
+   | rejectattr('applies_to_phase', 'contains', artifact_phase)
+   | list -%}
+{% if out_of_scope -%}
+| ID | Rule | Applies in phase |
+|----|------|------------------|
+{% for item in out_of_scope -%}
+| {{ item.id }} | {{ item.rule }} | {{ item.applies_to_phase | join(', ') }} |
+{% endfor %}
+{% else -%}
+None.
+{% endif %}
+## Summary
+- PASS: __ / {{ actionable | length }} actionable items
+- Deferred items: {{ deferred | length }} (status only, detail elsewhere)
+- Out-of-phase NA: {{ out_of_scope | length }}
+- Top 5 fixes (ranked by expected_lift):
+  1.
+  2.
+  3.
+  4.
+  5.
+## Cross-skill follow-up
+{% if reporting_guideline_pending -%}
+- [ ] Run `/check-reporting` (Section 1.6 anchor not yet verified). See `references/reporting_guideline_mapping.md` for the AIO ↔ guideline crosswalk.
+{% endif -%}
+{% if numerical_audit_pending -%}
+- [ ] Run numerical-claim audit (data-integrity rule).
+{% endif -%}
+{% if humanize_pending -%}
+- [ ] Run `/humanize` before submission (AI-pattern check).
+{% endif %}