# Citing an AI-assisted research tool safely (framing by use-class)

When a manuscript used an AI-assisted tool — a reference-verification / QA suite, a
statistical-analysis helper, or a generative drafting assistant — *where and how you
name it* changes how an editor or reviewer reads it. Under current journal wariness
about AI, a proud in-text citation of a **generative** use can invite suspicion or a
desk-reject, while the identical placement for a **verification** use reads as rigor
(the same way citing R, SPSS, or a reference manager does). The safe move is to frame
the mention by what the tool actually *did*, not to hide it.

This applies to any AI-assisted tool; it also applies to **self-citation** by a tool's
author (e.g. citing MedSci Skills in your own paper), which additionally requires a
conflict-of-interest disclosure.

## The three use-classes

| Use-class | What it covers | Where it belongs | Citable like software? |
|---|---|---|---|
| **Verification / QA** (rigor-signalling) | Reference/citation verification (DOI/PMID against PubMed/CrossRef), reporting-guideline compliance checks, deterministic integrity gates, numerical-consistency checks | **Software / Code-availability statement** (or Methods, as a named tool with version) | **Yes** — cite it plainly, like a reference manager or a linter. It signals rigor. |
| **Analysis** (neutral) | Statistical-analysis code, figure generation, data-transformation scripts | Methods (named, with version) and/or Code-availability | **Yes** — neutral and citable, like citing R/Python packages. |
| **Generative** (disclosure, not citation) | Drafting or rewriting prose, "humanizing", summarizing, idea generation | The journal's **AI-use disclosure field / statement** (per its policy), *not* a proud in-text citation | **No** — declare it in the disclosure field; do not farm it into the running text. |

## Rules of thumb

- **Prefer the deterministic, verifiable functions for the cleanest cite.** A tool's
  reproducible/verifiable capabilities (reference verification, compliance gates,
  analysis code) are the ones that read as rigor and are safest to name in a Software
  statement. Its generative capabilities belong in the disclosure field.
- **Match the placement to the use-class**, not to the tool. The *same* tool can be
  citable (its QA gate ran your references) *and* disclosure-only (its drafting helper
  touched your prose) in the *same* paper — split the mention accordingly.
- **Do not self-cite generatively.** If the paper did not materially use the generative
  parts, do not add a self-citation for them to inflate a citation count; cite only the
  functions the work actually used.
- **Pair a self-citation with a COI disclosure.** If you authored the tool, state the
  relationship (e.g. "Author X develops the cited toolkit") in the COI/competing-interests
  section — the same standard as any other intellectual/financial interest.
- **Honor the target journal's AI policy first.** Where a journal specifies *where* AI
  use must be declared (Methods vs Acknowledgements vs a dedicated field), that placement
  wins for the generative use-class; the Software-statement guidance above is for the
  verification/analysis classes, which are tool-use, not AI-authorship.

## Why this is guidance, not a deterministic gate (yet)

A deterministic check ("flag an AI-tool citation placed in running-text Methods for a
*generative* use") would need both a maintained tool-name allowlist and a reliable
classifier of *which use-class* a given sentence describes — the latter is high false-
positive without context the grep cannot see. The reliable, low-FP part (a tool named in
a Software/Code-availability statement) is already the recommended state, so there is
nothing to flag. If a bounded, allowlist-driven placement check proves worthwhile on real
manuscripts, it can be added later; until then this stays advisory. (See
`~/.claude/rules/manuscript-style-classical.md` §7/§15 for AI-disclosure placement and the
self-applicability rule.)

---
schema_version: 1
last_updated: "2026-05-10"
purpose: |
  Templates for journal-specific summary boxes used in medical-AI manuscripts.
  Each entry mirrors the journal's Instructions for Authors (IFA) at the date
  shown. USER MUST VERIFY the current IFA before applying — journal policies
  change without notice.

verification_protocol: |
  Before applying any template:
  1. Open the journal's current IFA URL (ifa_url field).
  2. Compare structure / labels / word targets to this YAML.
  3. If any field has changed since `last_verified`, update this file before
     deriving the manuscript's box.
  4. Treat `last_verified` older than 6 months as STALE — re-verify before
     submission.

journals:
  - id: lancet-digital-health
    name: The Lancet Digital Health
    box_label: Research in context
    ifa_url: https://www.thelancet.com/journals/landig/about
    last_verified: "2026-05-10"
    placement: After Introduction in main text, or as Panel 1.
    structure:
      - id: evidence-before
        label: Evidence before this study
        word_target: 100-200
        notes: |
          Describe the systematic search method (databases, dates, terms) and
          what was known prior to this study.
      - id: added-value
        label: Added value of this study
        word_target: 100-200
        notes: |
          State the contribution and how it advances the field beyond the
          evidence summarized above.
      - id: implications
        label: Implications of all the available evidence
        word_target: 100-200
        notes: |
          How findings (combined with prior evidence) should change clinical
          practice, policy, or future research.
    user_must_verify: true

  - id: rsna-radiology
    name: Radiology (RSNA)
    box_label: Key Results
    ifa_url: https://pubs.rsna.org/page/radiology/author-instructions
    last_verified: "2026-05-10"
    placement: First page of article, after Abstract.
    structure:
      - id: key-results
        label: Key Results
        format: 3 bullets, claim-centric, one finding each
        notes: |
          Each bullet should state a primary outcome with point estimate and
          confidence interval where applicable. Avoid hedging language.
    user_must_verify: true

  - id: rsna-radiology-ai
    name: Radiology Artificial Intelligence (RSNA)
    box_label: Key Points
    ifa_url: https://pubs.rsna.org/page/ai/author-instructions
    last_verified: "2026-05-10"
    placement: After Abstract.
    structure:
      - id: key-points
        label: Key Points
        format: 3 bullets
        notes: |
          Same conventions as Radiology Key Results — claim-centric, numeric
          where possible.
    user_must_verify: true

  - id: npj-digital-medicine
    name: npj Digital Medicine
    box_label: Plain Language Summary
    ifa_url: https://www.nature.com/npjdigitalmed/submission-guidelines
    last_verified: "2026-05-10"
    placement: After Abstract; required for all primary research.
    structure:
      - id: pls
        label: Plain Language Summary
        word_target: 150-200
        reading_level: 8th-grade
        notes: |
          Avoid jargon, define acronyms inline, prefer everyday vocabulary.
          Should be readable by a non-specialist physician or informed lay
          reader. No quantitative thresholds; describe magnitude in plain terms.
    user_must_verify: true

  - id: nature-medicine
    name: Nature Medicine
    box_label: Editor's Summary
    ifa_url: https://www.nature.com/nm/for-authors
    last_verified: "2026-05-10"
    placement: Editorial-supplied at acceptance; not author-drafted in main text.
    structure:
      - id: editor-summary
        label: Editor's Summary
        word_target: 100-150
        notes: |
          Supplied by the editorial team after acceptance. Authors should
          proactively draft a 100–150 word version for the cover letter and
          post-acceptance launch materials, so the editor has anchor wording
          to refine.
    user_must_verify: true

  - id: jamia
    name: JAMIA (Journal of the American Medical Informatics Association)
    box_label: (none mandated; structured abstract used)
    ifa_url: https://academic.oup.com/jamia/pages/General_Instructions
    last_verified: "2026-05-10"
    placement: Structured abstract serves the role of summary box.
    structure:
      - id: structured-abstract
        label: Structured Abstract
        format: Objective / Materials and Methods / Results / Discussion / Conclusion
        notes: Treat each section as a chunk-friendly semantic block (≤ 3 sentences).
    user_must_verify: true

related:
  - skills/academic-aio/SKILL.md Section 2.1 (manuscript-level summary box)
  - skills/academic-aio/SKILL.md Section 1.6 (reporting-guideline anchor)

---
schema_version: 1
last_updated: "2026-05-10"
purpose: |
  Open-access compliance matrix for major funders that medical-AI researchers
  may encounter. Use to decide gold OA vs green OA vs preprint route per paper.
  Funder policies change; verify the policy_url before applying.

verification_protocol: |
  All funder policies change without notice.
  - Verify policy_url before applying decisions.
  - Treat `last_verified` older than 6 months as STALE.
  - When in doubt, contact the institution's research-administration office.

funders:
  - id: plan-s
    name: cOAlition S (Plan S)
    region: Europe (multiple national funders)
    policy_url: https://www.coalition-s.org/plan-s-principles/
    last_verified: "2026-05-10"
    requirement: Immediate OA on publication; no embargo allowed.
    accepted_routes:
      - Gold OA with CC-BY (preferred)
      - Green OA via repository deposit at publication (no embargo)
    apc_cap: ~ EUR 2,500 typical, varies by funder
    notes: Strict; transformative agreements widely available.
    user_must_verify: true

  - id: nih-public-access
    name: US NIH Public Access Policy
    region: United States
    policy_url: https://publicaccess.nih.gov/
    last_verified: "2026-05-10"
    requirement: |
      From 2025 onward NIH policy requires manuscript deposit in PMC at
      publication (no 12-month embargo). Earlier grants may still operate
      under the legacy 12-month rule.
    accepted_routes:
      - Gold OA (publisher deposits to PMC)
      - Green OA (author deposits AAM to PMC via NIHMS)
    apc_cap: No cap; APCs are eligible expenses on most grants.
    user_must_verify: true

  - id: ukri
    name: UK Research and Innovation (UKRI)
    region: United Kingdom
    policy_url: https://www.ukri.org/manage-your-award/publishing-your-research-findings/making-your-research-open/
    last_verified: "2026-05-10"
    requirement: Immediate OA; CC-BY preferred.
    accepted_routes:
      - Gold OA via transformative agreement (preferred)
      - Green OA in approved repository at publication
    user_must_verify: true

  - id: gates-foundation
    name: Bill & Melinda Gates Foundation
    region: Global
    policy_url: https://openaccess.gatesfoundation.org/
    last_verified: "2026-05-10"
    requirement: Immediate OA, CC-BY, no embargo.
    accepted_routes:
      - Gold OA (mandatory)
    notes: Strictest among major funders. Closed-access publication is non-compliant.
    user_must_verify: true

  - id: wellcome
    name: Wellcome Trust
    region: UK / global
    policy_url: https://wellcome.org/grant-funding/guidance/open-access-policy
    last_verified: "2026-05-10"
    requirement: Immediate OA, CC-BY, including for preprints.
    accepted_routes:
      - Gold OA (preferred)
      - Green OA at publication
    user_must_verify: true

  - id: nrf-korea
    name: National Research Foundation of Korea (NRF)
    region: South Korea
    policy_url: https://www.nrf.re.kr/
    last_verified: "2026-05-10"
    requirement: |
      No formal mandatory immediate-OA policy as of 2026-Q2. Gold OA is
      encouraged and APCs are eligible expenses on most grants.
    accepted_routes:
      - Gold OA (encouraged)
      - Green OA (acceptable)
    user_must_verify: true

  - id: hira-mohw
    name: Korean Ministry of Health & Welfare research grants
    region: South Korea
    policy_url: https://www.mohw.go.kr/
    last_verified: "2026-05-10"
    requirement: Public benefit / repository deposit encouraged; no strict immediate-OA mandate.
    accepted_routes:
      - Gold OA (encouraged)
      - Green OA (acceptable)
    user_must_verify: true

decision_tree:
  - step: 1
    question: Does any funder on this paper require immediate OA?
    yes_action: |
      Choose gold OA at a Plan-S compliant journal, OR green OA with
      repository deposit at publication. Closed-access is not allowed.
    no_action: Continue to step 2.
  - step: 2
    question: Is APC budget available (grant line, institutional waiver, or transformative agreement)?
    yes_action: |
      Gold OA preferred — lower friction, faster PMC deposit, cited
      30-50 % more by AI-search tools (Section 3.4).
    no_action: |
      Green OA via preprint at submission + AAM deposit at acceptance.
      Verify journal's green-OA timeline.
  - step: 3
    question: Does the target journal auto-deposit to PMC (Section 11.3)?
    yes_action: Confirm and proceed. Deposit window typically 4-6 weeks.
    no_action: |
      Plan green OA pathway and timeline. Budget the AAM submission step
      (NIHMS or Europe PMC).
  - step: 4
    question: Is a transformative agreement available via the institution?
    yes_action: Gold OA is effectively free for the author — use it.
    no_action: Apply APC budget directly or fall back to green OA.

related:
  - skills/academic-aio/SKILL.md Section 3.4 (open-access choice)
  - skills/academic-aio/SKILL.md Section 11.3 (PMC-auto-deposit journal preference)

# Reporting-Guideline ↔ AIO Rule Mapping

This table maps each AIO rule (sections 1-12 of `SKILL.md`) to the corresponding item(s) in the major medical-AI reporting guidelines. Use it to align the `/check-reporting` audit with the `/academic-aio` audit so the same evidence covers both.

## Core mapping

| AIO rule | TRIPOD+AI 2024 | CLAIM 2024 | STARD-AI 2025 | TRIPOD-LLM 2024 | DECIDE-AI 2022 | Notes |
|----------|----------------|-------------|----------------|-----------------|----------------|-------|
| §1.1 Title three-slot | item 1 (title) | item 1 (title and abstract) | item 1 (title) | item 1a (title) | — | All require keyword presence and study-type identification. |
| §1.2 Structured abstract | item 2 (abstract) | item 1 (title and abstract) | item 2 (abstract) | item 1b (abstract) | — | Each guideline mandates structured form. |
| §1.5 Quantified primary outcome with CI | item 16 (model performance) | items 28-30 (performance metrics) | items 23-26 (diagnostic estimates) | item 17 (performance with CI) | item 8 (clinical effect) | CI mandatory for all. |
| §1.6 Reporting-guideline anchor | (compliance declaration) | (compliance declaration) | (compliance declaration) | (compliance declaration) | (compliance declaration) | Cite guideline + checklist in Methods or supplement. |
| §2.4 Reproducibility block | item 24 (data sharing) + item 25 (code sharing) | items 33-34 (data and code availability) | item 28 (data and code) | items 22-23 (artifacts) | item 12 (artifacts) | All require explicit data/code statement. |
| §2.5 Limitations enumeration | item 23 (limitations) | item 41 (limitations) | item 27 (limitations) | item 19 (limitations) | item 11 (limitations) | Enumerate, do not narrate generally. |
| §10.4 Challenge statement | (implicit in Background) | item 4 (rationale) | item 5 (rationale) | item 4 (rationale) | item 4 (rationale) | "Why this is hard" overlaps with rationale items. |

## Workflow

1. Run `/check-reporting` first — produces a PRESENT/PARTIAL/MISSING audit per guideline item.
2. Run `/academic-aio` — produces the AIO PASS/PARTIAL/FAIL checklist.
3. For each AIO FAIL or PARTIAL row, check this mapping. If the underlying reporting-guideline item is also MISSING/PARTIAL, fix it once and both audits update.
4. Items present in `/check-reporting` audit but not in this mapping (e.g., randomization details for RCTs, domain-specific safety items) do not have an AIO consequence and can be addressed independently.

## When the two audits disagree

- AIO PASS + reporting-guideline MISSING — the manuscript looks discoverable but is not formally compliant. Reviewers may still reject. Always fix the reporting-guideline gap.
- AIO FAIL + reporting-guideline PRESENT — a rule was recorded in compliance form but rendered in a way that LLM extractors cannot parse (e.g., reporting CIs in supplementary instead of inline in the abstract). Move the content into a chunk-friendly location.

## Source

- TRIPOD+AI: Collins et al. BMJ 2024.
- CLAIM 2024: Tejani et al. Radiology: AI 2024, doi:10.1148/ryai.240300.
- STARD-AI 2025: Sounderajah et al. Nat Med 2025, doi:10.1038/s41591-025-03953-8.
- TRIPOD-LLM 2024: Gallifant et al. Nat Med 2024, doi:10.1038/s41591-024-03425-5.
- DECIDE-AI 2022: Vasey et al. Nat Med 2022, doi:10.1038/s41591-022-01772-9.

## Anti-hallucination

Item numbers above are derived from the most recent published version of each guideline. Verify against the EQUATOR Network entry before citing item numbers in a manuscript — guideline updates renumber items.

{
  "_comment": "Synthesis of PUBLIC, journal-documented structured-summary-box facts (bullet counts, sub-block labels, word bands) — NOT verbatim journal text. Mirrors the facts academic-aio/SKILL.md already states (Lancet 'Research in context' 3 sub-blocks; Radiology/RYAI 'Key Points' 3 one-claim bullets; npj 'Plain-language summary' 150-200 words). Verify current instructions-to-authors at the journal site before relying on a format; these are conventions, not guarantees.",
  "schema_version": 1,
  "formats": {
    "key_points": {
      "label": "Key Points",
      "bullets": 3,
      "one_claim_per_bullet": true,
      "journals": ["radiology", "radiology-ai", "ryai", "rsna"]
    },
    "research_in_context": {
      "label": "Research in context",
      "subblocks": [
        "Evidence before this study",
        "Added value of this study",
        "Implications of all the available evidence"
      ],
      "journals": ["lancet-digital-health", "lancet", "lancet-oncology"]
    },
    "plain_language_summary": {
      "label": "Plain-language summary",
      "word_min": 150,
      "word_max": 200,
      "journals": ["npj-digital-medicine", "npj"]
    }
  }
}

#!/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())

#!/usr/bin/env python3
"""Structured-summary-box conformance detector (academic-aio).

High-impact medical-AI journals require a structured summary box whose *format*
is journal-specific, and a production/technical check rejects the wrong one:

  - Radiology / Radiology:AI (RSNA): "Key Points" — exactly 3 bullets, one claim each.
  - Lancet family: "Research in context" — three labelled sub-blocks
    (Evidence before this study / Added value of this study / Implications of all
    the available evidence).
  - npj Digital Medicine: "Plain-language summary" — ~150-200 words.

academic-aio already *generates* these boxes; this detector makes the spec
deterministic so a wrong-bullet-count, missing-sub-block, or over/under-length
box is caught before submission instead of at the technical check. The spec is
read from references/summary_box_specs.json (public facts, journal-keyed).

INPUTS
  --manuscript   markdown file containing the summary box (required).
  --journal      journal stem to pick the format (e.g. radiology, lancet-digital-health,
                 npj-digital-medicine). Optional if --format is given.
  --format       force a format: key_points | research_in_context | plain_language_summary.
  --specs        path to summary_box_specs.json (default: alongside this script's skill).
  --out          write a JSON report here (default: qc/summary_box_report.json).
  --strict       exit 1 if the box is non-conformant.

VERDICT
  CONFORMANT          the box matches its format's spec.
  NONCONFORMANT       a hard rule failed (wrong bullet count, missing sub-block,
                      word count outside the band, box absent).
  ADVISORY            only soft rules fired (e.g. a bullet carries >1 claim).
  Exit: 0 conformant/advisory or report-only; 1 NONCONFORMANT under --strict;
        2 input/usage error.

Stdlib-only (csv-free: json / argparse / re / pathlib).
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path


def _default_specs() -> Path:
    return Path(__file__).resolve().parent.parent / "references" / "summary_box_specs.json"


def _err(msg: str) -> int:
    print(f"ERROR: {msg}", file=sys.stderr)
    return 2


def load_specs(path: Path) -> dict:
    data = json.loads(path.read_text(encoding="utf-8"))
    return data["formats"]


def pick_format(formats: dict, journal: str | None, fmt: str | None) -> str | None:
    if fmt:
        return fmt if fmt in formats else None
    if journal:
        j = journal.strip().lower()
        for key, spec in formats.items():
            if j in [x.lower() for x in spec.get("journals", [])]:
                return key
    return None


def extract_block(text: str, label: str) -> str | None:
    """Return the lines under a heading/bold label matching `label`, up to the
    next markdown heading or a blank-line-separated next bold label section."""
    lines = text.splitlines()
    label_re = re.compile(
        r"^\s*(?:#{1,6}\s*|\*\*\s*|\*\s*)?" + re.escape(label) + r"\b", re.IGNORECASE
    )
    start = None
    for i, ln in enumerate(lines):
        if label_re.search(ln):
            start = i
            break
    if start is None:
        return None
    out: list[str] = []
    for ln in lines[start + 1:]:
        if re.match(r"^\s*#{1,6}\s+\S", ln):  # next heading ends the block
            break
        out.append(ln)
    return "\n".join(out).strip()


def count_bullets(block: str) -> list[str]:
    bullets: list[str] = []
    for ln in block.splitlines():
        m = re.match(r"^\s*(?:[-*+]|\d+[.)])\s+(.*\S)", ln)
        if m:
            bullets.append(m.group(1).strip())
    return bullets


def multi_claim(bullet: str) -> bool:
    """Heuristic: a one-claim bullet should not pack two independent assertions.
    Flags a sentence-final period followed by a capitalized new sentence, or a
    semicolon joining two clauses."""
    if ";" in bullet:
        return True
    return bool(re.search(r"[.!?]\s+[A-Z0-9]", bullet.rstrip(".")))


def word_count(block: str) -> int:
    # strip the label line if it leaked in; count remaining words.
    return len(re.findall(r"\b[\w'-]+\b", block))


def check(text: str, fmt: str, spec: dict) -> dict:
    label = spec["label"]
    block = extract_block(text, label)
    findings: list[dict] = []
    if block is None:
        return {
            "format": fmt, "label": label, "verdict": "NONCONFORMANT",
            "findings": [{"rule": "box_present", "severity": "hard",
                          "detail": f"no '{label}' box found in the manuscript"}],
        }

    if fmt == "key_points":
        bullets = count_bullets(block)
        want = spec["bullets"]
        if len(bullets) != want:
            findings.append({"rule": "bullet_count", "severity": "hard",
                             "detail": f"found {len(bullets)} bullets, expected {want}"})
        if spec.get("one_claim_per_bullet"):
            for b in bullets:
                if multi_claim(b):
                    findings.append({"rule": "one_claim_per_bullet", "severity": "soft",
                                     "detail": f"bullet packs >1 claim: {b[:80]}"})
    elif fmt == "research_in_context":
        low = block.lower()
        for sub in spec["subblocks"]:
            if sub.lower() not in low:
                findings.append({"rule": "subblock_present", "severity": "hard",
                                 "detail": f"missing sub-block: '{sub}'"})
    elif fmt == "plain_language_summary":
        wc = word_count(block)
        lo, hi = spec["word_min"], spec["word_max"]
        if wc < lo or wc > hi:
            findings.append({"rule": "word_band", "severity": "hard",
                             "detail": f"{wc} words, expected {lo}-{hi}"})
    else:
        return {"format": fmt, "label": label, "verdict": "NONCONFORMANT",
                "findings": [{"rule": "unknown_format", "severity": "hard",
                              "detail": f"unknown format '{fmt}'"}]}

    hard = any(f["severity"] == "hard" for f in findings)
    verdict = "NONCONFORMANT" if hard else ("ADVISORY" if findings else "CONFORMANT")
    return {"format": fmt, "label": label, "verdict": verdict, "findings": findings}


def main() -> int:
    ap = argparse.ArgumentParser(description="Check a structured summary box against its journal format spec.")
    ap.add_argument("--manuscript", required=True)
    ap.add_argument("--journal")
    ap.add_argument("--format")
    ap.add_argument("--specs")
    ap.add_argument("--out")
    ap.add_argument("--strict", action="store_true")
    args = ap.parse_args()

    man = Path(args.manuscript)
    if not man.is_file():
        return _err(f"manuscript not found: {man}")
    specs_path = Path(args.specs) if args.specs else _default_specs()
    if not specs_path.is_file():
        return _err(f"specs not found: {specs_path}")

    formats = load_specs(specs_path)
    fmt = pick_format(formats, args.journal, args.format)
    if fmt is None:
        return _err("could not select a format — pass --format or a --journal listed in the specs")

    text = man.read_text(encoding="utf-8")
    report = check(text, fmt, formats[fmt])

    out_path = Path(args.out) if args.out else Path("qc") / "summary_box_report.json"
    out_path.parent.mkdir(parents=True, exist_ok=True)
    out_path.write_text(json.dumps({"detector": "check_summary_box", **report}, indent=2) + "\n", encoding="utf-8")

    print("=" * 41)
    print(" Summary-Box Conformance")
    print("=" * 41)
    print(f"format: {fmt}  ({report['label']})")
    print(f"verdict: {report['verdict']}")
    for f in report["findings"]:
        print(f"  [{f['severity']}] {f['rule']}: {f['detail']}")
    print(f"report: {out_path}")

    if report["verdict"] == "NONCONFORMANT" and args.strict:
        print("\nSUMMARY_BOX_NONCONFORMANT", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/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())

#!/usr/bin/env bash
# Regression test for academic-aio/scripts/batch_metadata_audit.py.
# Builds synthetic repos / HF cards (no committed data) and asserts: a clean
# repo reports no issues (exit 0), a repo missing README/CITATION/LICENSE fails
# under --fail-on-issue (exit 1), and an HF card carrying a PHI-shaped string is
# flagged. Stdlib-only (json/re), network-free, ASCII-only.
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/batch_metadata_audit.py"
TMP="$(mktemp -d -t aio_audit_XXXX)"
trap 'rm -rf "$TMP"' EXIT

fail=0
check_exit() { local label="$1" want="$2"; shift 2
    "$@" >/dev/null 2>&1; local got=$?
    if [[ "$got" -eq "$want" ]]; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s (exit %s, want %s)\n' "$label" "$got" "$want"; fail=$((fail+1)); fi
}
check() { local label="$1"; shift
    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
}

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: batch_metadata_audit.py missing" >&2; exit 2; }

# --- Clean repo: README (DOI + citation + quickstart), CITATION.cff, LICENSE ---
CLEAN="$TMP/clean_repo"; mkdir -p "$CLEAN"
cat > "$CLEAN/README.md" <<'MD'
# Synthetic Tool
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.0000000-blue)](https://doi.org/10.5281/zenodo.0000000)
## Installation
pip install synthetic-tool
## How to cite
See CITATION.cff.
MD
cat > "$CLEAN/CITATION.cff" <<'CFF'
cff-version: 1.2.0
title: Synthetic Tool
version: 1.0.0
authors:
  - family-names: Kim
    given-names: Alice
    orcid: https://orcid.org/0000-0002-1825-0097
CFF
echo "MIT License" > "$CLEAN/LICENSE"
check_exit "clean repo -> exit 0 (no issues, --fail-on-issue)" 0 \
    python3 "$SCRIPT" "$CLEAN" --fail-on-issue

# --- Broken repo: directory exists but empty (all three artifacts missing) ---
BROKEN="$TMP/broken_repo"; mkdir -p "$BROKEN"
check_exit "repo missing README/CITATION/LICENSE -> exit 1" 1 \
    python3 "$SCRIPT" "$BROKEN" --fail-on-issue
# Without --fail-on-issue the same audit still exits 0 (report-only).
check_exit "report-only mode -> exit 0 even with issues" 0 \
    python3 "$SCRIPT" "$BROKEN"

# --- HF card with a PHI-shaped string (KR resident registration number) ---
CARD="$TMP/model_card.md"
cat > "$CARD" <<'MD'
---
license: mit
library_name: transformers
tags:
  - medical
---
# Model
## Intended use
Research only.
## Training data
Synthetic records, e.g. subject 900101-1234567 was excluded.
## Evaluation
AUC reported.
## Limitations
Small sample.
## Ethical considerations
De-identified.
MD
JSON_OUT="$TMP/report.json"
python3 "$SCRIPT" --hf-card "$CARD" --output "$JSON_OUT" >/dev/null 2>&1
check "HF card report written" test -s "$JSON_OUT"
check "PHI pattern flagged in HF card" python3 -c "
import json
d=json.load(open('$JSON_OUT'))
issues=' '.join(d['hf_cards'][0]['issues'])
assert 'PHI' in issues, d['hf_cards'][0]['issues']"
check_exit "HF card with PHI -> exit 1 under --fail-on-issue" 1 \
    python3 "$SCRIPT" --hf-card "$CARD" --fail-on-issue

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"

#!/usr/bin/env bash
# Regression/challenge test for check_summary_box.py — deterministic, network-free,
# synthetic fixtures built at runtime. Covers each journal format + each hard rule.
set -u

HERE="$(cd "$(dirname "$0")" && pwd)"
SCRIPT="$HERE/../scripts/check_summary_box.py"
TMP="$(mktemp -d)"
trap 'rm -rf "$TMP"' EXIT

pass=0
fail=0
ck() {
  local label="$1" expected="$2" actual="$3"
  if [ "$expected" = "$actual" ]; then
    printf '  PASS  %-50s exit=%s\n' "$label" "$actual"
    pass=$((pass + 1))
  else
    printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
    fail=$((fail + 1))
  fi
}
run() { python3 "$SCRIPT" --out "$TMP/r.json" "$@" > /dev/null 2>&1; echo $?; }

# 1) conformant Key Points (3 one-claim bullets) -> exit 0
cat > "$TMP/kp_ok.md" <<'EOF'
## Key Points
- The model improved detection sensitivity in an internal test set.
- Specificity was preserved at the chosen operating threshold.
- External validation is still required before deployment.
EOF
ck "key_points conformant" 0 "$(run --manuscript "$TMP/kp_ok.md" --journal radiology --strict)"

# 2) wrong bullet count (2) -> NONCONFORMANT under --strict
cat > "$TMP/kp_bad.md" <<'EOF'
## Key Points
- The model improved detection sensitivity.
- Specificity was preserved.
EOF
ck "key_points wrong bullet count fails" 1 "$(run --manuscript "$TMP/kp_bad.md" --journal radiology --strict)"

# 3) Research in context missing a sub-block -> NONCONFORMANT
cat > "$TMP/ric_bad.md" <<'EOF'
## Research in context
**Evidence before this study** We searched PubMed for prior work.
**Added value of this study** This study adds an external cohort.
EOF
ck "research_in_context missing subblock fails" 1 "$(run --manuscript "$TMP/ric_bad.md" --journal lancet-digital-health --strict)"

# 4) Research in context complete -> CONFORMANT
cat > "$TMP/ric_ok.md" <<'EOF'
## Research in context
**Evidence before this study** We searched PubMed for prior work.
**Added value of this study** This study adds an external cohort.
**Implications of all the available evidence** Findings support a prospective trial.
EOF
ck "research_in_context complete conformant" 0 "$(run --manuscript "$TMP/ric_ok.md" --journal lancet-digital-health --strict)"

# 5) Plain-language summary over the band -> NONCONFORMANT
{ echo "## Plain-language summary"; for i in $(seq 1 260); do printf 'word '; done; echo; } > "$TMP/pls_bad.md"
ck "plain_language over-length fails" 1 "$(run --manuscript "$TMP/pls_bad.md" --journal npj-digital-medicine --strict)"

# 6) absent box -> NONCONFORMANT
echo "## Abstract" > "$TMP/none.md"
ck "absent box fails" 1 "$(run --manuscript "$TMP/none.md" --format key_points --strict)"

# 7) without --strict, a nonconformant box is reported but tolerated (exit 0)
ck "nonconformant tolerated without --strict" 0 "$(run --manuscript "$TMP/kp_bad.md" --journal radiology)"

echo "----"
echo "test_summary_box: $pass passed, $fail failed"
[ "$fail" -eq 0 ]

#!/usr/bin/env bash
# Regression test for academic-aio/scripts/validate_schema.py.
# Builds synthetic JSON-LD fixtures (no committed data) and asserts the
# validator's contract: a complete ScholarlyArticle passes; wrong @context,
# unknown @type, a missing required field, and a malformed DOI each fail.
# Stdlib-only (json/re), network-free, ASCII-only.
set -u

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT="$HERE/../scripts/validate_schema.py"
TMP="$(mktemp -d -t aio_schema_XXXX)"
trap 'rm -rf "$TMP"' EXIT

fail=0
check() { local label="$1" want="$2"; shift 2
    "$@" >/dev/null 2>&1; local got=$?
    if [[ "$got" -eq "$want" ]]; then printf '  PASS  %s\n' "$label"
    else printf '  FAIL  %s (exit %s, want %s)\n' "$label" "$got" "$want"; fail=$((fail+1)); fi
}

[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: validate_schema.py missing" >&2; exit 2; }

# Valid ScholarlyArticle (all required fields, canonical DOI).
cat > "$TMP/ok.jsonld" <<'JSON'
{
  "@context": "https://schema.org",
  "@type": "ScholarlyArticle",
  "headline": "Synthetic Diagnostic Study",
  "datePublished": "2026-01-01",
  "author": [{"@type": "Person", "name": "Alice Kim"}],
  "identifier": [{"@type": "PropertyValue", "propertyID": "DOI", "value": "10.1000/synthetic.2026.001"}],
  "url": "https://example.org/article"
}
JSON
check "valid ScholarlyArticle -> exit 0" 0 python3 "$SCRIPT" "$TMP/ok.jsonld"

# Wrong @context.
sed 's#https://schema.org#https://example.com#' "$TMP/ok.jsonld" > "$TMP/bad_ctx.jsonld"
check "wrong @context -> exit 1" 1 python3 "$SCRIPT" "$TMP/bad_ctx.jsonld"

# Unknown @type.
sed 's/ScholarlyArticle/UnicornType/' "$TMP/ok.jsonld" > "$TMP/bad_type.jsonld"
check "unknown @type -> exit 1" 1 python3 "$SCRIPT" "$TMP/bad_type.jsonld"

# Missing required field (no "url"; still valid JSON).
cat > "$TMP/missing.jsonld" <<'JSON'
{
  "@context": "https://schema.org",
  "@type": "ScholarlyArticle",
  "headline": "Synthetic Diagnostic Study",
  "datePublished": "2026-01-01",
  "author": [{"@type": "Person", "name": "Alice Kim"}],
  "identifier": [{"@type": "PropertyValue", "propertyID": "DOI", "value": "10.1000/synthetic.2026.001"}]
}
JSON
check "missing required field -> exit 1" 1 python3 "$SCRIPT" "$TMP/missing.jsonld"

# Malformed DOI.
sed 's#10.1000/synthetic.2026.001#not-a-doi#' "$TMP/ok.jsonld" > "$TMP/bad_doi.jsonld"
check "malformed DOI -> exit 1" 1 python3 "$SCRIPT" "$TMP/bad_doi.jsonld"

# Mixed batch (one bad file) still fails overall.
check "batch with one bad file -> exit 1" 1 python3 "$SCRIPT" "$TMP/ok.jsonld" "$TMP/bad_ctx.jsonld"

echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
exit "$fail"