Return the encoded TARGET checklist spec: 39 scoreable leaf subitems (grouped into the 21 published items) with intent, assessor notes, signal terms, pairing links, and applicability rules. Pass a version id to pin; omit for the current default.

OPTIONAL in the review flow — introspection only. assess_manuscript already embeds the full per-leaf rubric (intents + verdict boundaries) in the prompt it returns, so calling both get_checklist and assess_manuscript for the same review duplicates the rubric payload. Use this when you want to inspect the spec on its own, not as a required step before assessing.

PRIMARY entry point: parse a manuscript into a SectionMap with character-offset, source-tagged section spans.

PASS citation=: the manuscript's full bibliographic reference in APA style (authors, year, title, journal, volume(issue), pages, DOI). It is carried into the assessment and displayed on every rendered checklist so the assessed publication is unambiguous — without it, renders can only show the short manuscript_id. You have the paper in hand; format the reference from its title page.

document is EITHER the raw manuscript text OR a file path — but the path must be readable on the SERVER host. If you are an agent whose uploaded files live on your own filesystem (a mounted upload dir, a sandbox), the server cannot see them: paste the manuscript TEXT instead, or use parse_pmcid for an open-access PMCID. Reach for a file path only when the file is on the same host as this server (server-local/batch use). A path-looking string that the server can't find raises rather than being silently ingested as its own text.

supplements is a list of server-readable file paths (PDF/docx/text) to merge as supplementary material — PASS IT WHEN YOU HAVE IT: TTE methods (estimand, identifying assumptions) frequently live in a supplementary protocol table, and without a supplement the verdicts on those leaves come back not_reported when the content was merely in an un-ingested appendix. When supplements are provided, supplement_status defaults to 'user_provided'. Pass supplement_status='none_exists' to assert the article has no supplement. section_hints is a LAST RESORT for a section the detector cannot find: {'introduction': 6543} splits whatever section contains that character offset. Some journals print no heading for a section (an introduction that simply follows the abstract) and interpose prose — a lay-summary box — that no structural rule can tell apart from the section itself; check the warnings for 'may have swallowed an unheaded introduction'. A hint never edits the text, so text_sha256 is unchanged and a hinted parse is the same document; the hinted section carries an empty heading because the paper prints none. Only supply an offset you established by READING the paper, and expect an error rather than silence if the hint cannot be applied.

Returns source-tagged section boundaries, protocol-table and flow-diagram detection over the combined text, supplement_status, and the text hash used to key later calls.

CONVENIENCE / BATCH entry point: retrieve an open-access article from Europe PMC by PMCID and parse it. Reach for this in the corpus/batch case (no file in hand) or to auto-fetch an open-access paper's supplement; for a single manuscript you were given, use parse_manuscript instead. Fetches JATS main text plus (if available) PMC-hosted supplementary files, merged into one source-tagged SectionMap. supplement_status is 'retrieved' when a supplement was obtained, else 'not_retrieved' (a supplement may still exist on the publisher site; absence of retrieval is not proof of absence). Raises if no open-access full text is available. Returns the same summary as parse_manuscript, including the text hash for assess_manuscript. An APA-style citation is auto-built from the article's JATS metadata and displayed on every rendered checklist; pass citation= to override it (e.g. when the auto-built reference is incomplete).

Assess a manuscript against all applicable TARGET leaves in one batched pass. document is a path, raw text, or a text_sha256 returned by parse_manuscript.

mode='scaffold' (default) is the path for reviewing a publication: you are the LLM in the loop, so the server returns the exact assessment prompt, the tool schema, and a prompt hash for YOU to execute — read the manuscript against the rubric, produce the verdicts, then call submit_scaffold_verdicts to validate them and get the stamped result (evidence resolved to spans, provenance, ready for render_checklist).

mode='judge' is for the headless/batch case where no LLM is in the loop (e.g. a corpus run). The server makes its own pinned-model API call (requires ANTHROPIC_API_KEY) so scoring is reproducible and caller- independent, and returns the full verdict matrix directly. Overkill when an agent is already reviewing the paper interactively.

Scaffold-mode completion: validate verdicts produced by the calling agent (leaf coverage, verdict vocabulary, mandatory verbatim evidence quotes resolved to spans) and return the stamped assessment TOGETHER WITH the finished, rendered deliverable. items is the verdict array from the forced tool call — one object per leaf with id, verdict, confidence, rationale, and (for reported/partial) evidence_quotes.

THE ARTIFACT OF RECORD is in the returned report (by default the HTML form), carrying a provenance stamp bound to the ingested text and prompt. That stamped render is the ONLY canonical output — present it as the completed checklist. Need another format? Do NOT hand-assemble one: call render_checklist (markdown) or render_checklist_docx (.docx bytes) to re-render the same stamped artifact, or pass report_formats (any of 'html', 'markdown', 'docx') to include them here. The default is HTML only because every extra format flows through your context window. The items verdicts are an intermediate object; do NOT hand-assemble your own checklist document and present it as the assessment, because it will lack the stamp and cannot be verified. You MAY additionally write an analytic memo (prioritized gaps, an estimand-first reading), but label it as commentary and cite the stamp — never let it stand in for, or inherit the authority of, the stamped form.

Set render=false to skip rendering (verdicts only). The parse cache does not survive a server restart; if text_sha256 is no longer cached, pass document (the same path or text) to re-parse transparently.

Render a finalized assessment as the completed TARGET checklist form: the 21 published items (39 leaf rows, in checklist order) with the published item wording and a Location-reported column derived from the resolved evidence spans. The default enriched view adds, per leaf, the instrument's verdict and the verbatim evidence quote that justifies the location; view='official' strips to the published form's columns (Item / Checklist item / Location reported). Returns structured rows, a completeness tally, and a ready-to-display Markdown table. Pass either a full assessment object or the manuscript_id of one assessed earlier this session. This is a pure projection — no re-scoring.

Write the completed TARGET checklist to a Word (.docx) file and return it. Same content as render_checklist (published item wording + a Location-reported column from the resolved evidence spans; enriched view adds verdict and evidence), serialized as a submission-ready landscape table, one per manuscript section. Pass a full assessment object or the manuscript_id of one assessed this session. view='official' strips to the published form's three columns.

RETRIEVING THE FILE: the return carries the document bytes as base64 in content_base64 (with content_type and filename) — decode and save these to get the deliverable. The file is ALSO written to path on the server host, but that filesystem is not the caller's: if you are an agent whose files live elsewhere, use content_base64, not path. path defaults to a writable temp dir and is only directly useful for server-local/batch runs.

logo=True heads the document with the published TARGET banner, but ONLY on view='official' (the author's self-report form); on the enriched view it is ignored and the returned logo_applied is False, because the official mark on a machine-generated assessment would imply an endorsement the instrument does not carry. Default off.

Render the completed TARGET checklist as a self-contained HTML page — same content as render_checklist, styled to the Black Swan Causal Labs identity (canvas ground, one aligned table, verdict pills), viewable in any browser on any host. Returns the HTML string in html (show it inline or publish it as an artifact) and the same bytes as base64 in content_base64 (decode and save as an .html file). Carries the provenance stamp. Pass a full assessment object or the manuscript_id of one assessed this session; view='official' strips to the published form's three columns.

Roll up many assessments into per-item completeness rates plus coverage denominators (supplement-retrieval status, full-text availability, evidence- resolution rate). Pass an array of assessment objects as assessments, or use_session=true to aggregate every assessment produced this session. The completeness rates are only as valid as the sample and are not yet gold-standard calibrated.

Emit blank per-paper coding sheets for human gold-standard coding: one row per applicable leaf with its intent and verdict boundaries and empty verdict/evidence/note fields. blind=true (default) withholds the instrument's verdict so coders are not anchored — use blind coding for the primary reference standard. Pass assessments or use_session=true.

Compute per-leaf agreement between instrument assessments and human gold-standard codings: raw agreement, Cohen's kappa, Gwet's AC1, and binary (reported-vs-rest) sensitivity/specificity with the human coding as the reference standard, plus a span-keyed disagreement list for adjudication. Agreement is reported PER LEAF; the pooled figure is orientation only. Both arguments are arrays of assessment/coding objects sharing manuscript ids and spec version.