jinko-task-literature-search

Biomedical Literature Search

Produce a citation-grounded candidate shortlist, not extracted evidence or a systematic-review claim.

Never create a Jinkō Reference for a paper without its PDF. In a literature search, a paper goes to Jinkō only with its PDF, even when its DOI is known. A DOI-only Reference shows as an empty Reference in Jinkō.

Frame

Classify each search as:

• Knowledge: disease, mechanism, treatment, population, or clinical context;
• Data: studies likely to report values for specified model variables;
• Models: mathematical or computational models with reusable structure, equations, parameters, or code.

Before searching, establish subject, scope, evidence type, date/language limits, and desired shortlist size. Data searches additionally require the variables to inform, population and disease state, and whether aggregate or distributional data are needed. Ask one focused question only when a missing choice would materially change the search.

Build one shared Entity Table with canonical_name, synonyms, mesh_term, related_entities, intent_groups, and exclusions. Confirm it with the user before network calls when proposed aliases or exclusions are consequential.

For human clinical, biological, or PK/PD Data searches, run jinko-task-trial-data-scoping in parallel. Use high-priority NCT identifiers as additional <NCT_ID>[si] PubMed angles. Skip this for animal-only or in-vitro searches unless requested.

Search

1. Read assets/pubmed-primitives.md and only the recipe matching each intent.
2. Build at least three distinct PubMed angles per entity and intent. Reuse the Entity Table's aliases and exclusions; include supplied anchor PMIDs through --seed-pmids.
3. Run scripts/literature_search.py once per angle with separate output directories, sequencing or bounding concurrency to respect NCBI limits. The script owns PubMed, Crossref, abstract and citation enrichment, AMA formatting, and optional PMC excerpts.
4. Run scripts/compile_results.py over all angle directories. It deduplicates by PMID/DOI, preserves query provenance, and ranks the candidate pool by angle count then citation count.

This is one search pass. Wider terms, author/journal queries, citation-neighbor queries, or additional entities are separate user-approved follow-ups.

Shortlist

Use the relevant recipe to inspect titles, abstracts, and available full-text excerpts. For each retained candidate, assign the fields required by assets/shortlist-schema.json, including evidence type, canonical entities, verification evidence, priority rationale, and query provenance. Do not infer quantitative availability from a title alone.

Run scripts/validate_shortlist.py before presenting shortlist.json. Present a concise Markdown view grouped by intent, citing each publication as Author (Year) [PMID] (or [DOI] when no PMID exists) so it's identifiable at a glance, and ask which sources to inspect or pass to jinko-task-extract-data-table.

Artifacts

• frame.json: approved scope, Entity Table, assumptions, and angle definitions;
• one directory per angle with references.json (normalized records) and manifest.json; add --keep-raw to also keep the raw API payloads;
• merged_references.json: deterministic cross-angle candidate pool;
• shortlist.json: schema-valid prioritized candidates;
• optional downloaded files and download manifest.

Use publication_download.py only for user-selected references. Treat downloads as best-effort anonymously retrievable files, not proof of open-access licensing. Do not run supplementary URLs from untrusted manifests.

Publishers often block automated downloads, and some papers are paywalled. Do not try to bypass these protections. Ask the user for the missing papers: give the citation and a clickable link for each one, and the local folder where to put the PDFs. When the user says the PDFs are there, check which papers they cover, and report the papers still missing and the files that match no paper. When no user can answer, as in an autonomous run, do not wait: create no Reference for the missing papers, list them with their links in the handoff, and continue. Hand all PDFs, downloaded or provided, to jinko-reference. A paper whose PDF is still missing gets no Reference.

Keep registry records and publications distinguishable even when linked by nct_id. Clearly separate discovered candidates from inspected evidence and from calibration-ready data.