Drug-Data Converter — One-Page Quick Reference

A printable cheat-sheet for the universal drug-data converter. Companion to drug-data-converter-prompt.txt (LLM-pasteable) and drug-data-converter-guide.md (full human walk-through).

1. State your intent

Pasting source text alone does not trigger conversion. Say one of:

"convert this for the drug guide" · "add this drug" · "fold this into the website" · "incorporate this into the clinical content" · "turn this into a drug entry" · "format this for the clinical drug guide"

Without an intent phrase the converter will ask first.

2. The output is always the same

{
  "name", "class", "subclass", "category",
  "accent": "#hex",
  "tag",
  "schedule": "UNSCHEDULED|S2|S3|S4|S5|S6|S7|S8|S9|S10",
  "stats":    [ { "label", "value", "cls?", "flag?" } ],   // up to 4
  "sections": [ { "title", "type", "rows": [ { "key", "val", "tags?" } ] } ],
  "quick":    [ { "label", "value" } ]                     // up to 11
}

15 section codes, in canonical order: summary · dose · form · ind · evid · risk · contra · inter · mon · pearl · spec · safe · sel · comp · src

Severity prefixes are clinical decision aids, not decoration. Use them only on risk | contra | inter | mon | spec | safe | dose rows, and use exact labels only: CRITICAL · ABSOLUTE · CONTRAINDICATED · AVOID · DO NOT USE · HIGH · MANDATORY · SEVERE · WARNING · CAUTION · MONITOR · MODERATE · LOW · MINIMAL · RARE · SAFE · NONE · BENEFICIAL · POPULATION · PREGNANCY · LACTATION · ELDERLY · FRAIL · RENAL · HEPATIC. The dash separator must be —, –, or - with spaces; -- is not parsed.

Badge rule: add a badge only when it helps clinical scanning or prescribing decisions. Do not badge source prose, role-in-therapy commentary, or repeated low-yield terms.

3. The seven accepted input shapes (mini examples)

A. Phase E / Phase G package (strict, legacy)

## 002. Buprenorphine + naloxone (opioid dependence)

### Buprenorphine + naloxone - Quick Prescribing Card
| Heading | Content |
| --- | --- |
| Class & Role | Partial mu-opioid agonist + naloxone deterrent ... |
... (exactly 11 rows)

### Buprenorphine + naloxone - Detailed Master Table
| Heading | Content |
| --- | --- |
| Class & Role | ... |
... (exactly 16 rows)

→ Strict path, byte-for-byte identical to v2 output.

B. TGA Product Information (Australian PI)

NAME OF THE MEDICINE: Atorvastatin (Lipitor)
DESCRIPTION:          HMG-CoA reductase inhibitor.
INDICATIONS:          Primary hypercholesterolaemia ...
DOSAGE AND ADMIN.:    10–80 mg orally once daily; max 80 mg/day.
PHARMACOLOGY:         Half-life ~14 h. CYP3A4 metabolism.
CONTRAINDICATIONS:    Active liver disease. Pregnancy. Lactation.
PRECAUTIONS:          Monitor LFTs. Myopathy risk ...
INTERACTIONS:         Strong CYP3A4 inhibitors raise exposure ...
ADVERSE EFFECTS:      Common — myalgia, headache, GI upset ...
POISON SCHEDULE:      S4

C. AMH / BNF monograph excerpt

ATORVASTATIN
Indications: Hypercholesterolaemia, CV prevention.
Mode of action: HMG-CoA reductase inhibitor.
Dose: 10–80 mg orally daily.
Adverse effects: Myalgia, raised LFTs, rare rhabdomyolysis.
Precautions: Hepatic impairment, pregnancy.
Contraindications: Active liver disease, pregnancy.
Interactions: CYP3A4 inhibitors, fibrates.
Practice points: Monitor LFTs at baseline.

D. Hospital prescribing protocol / clinical guideline

RPH Lipid Protocol — Atorvastatin
Eligible:        High CV-risk adults; secondary prevention post-MI.
Initial dose:    40 mg nocte.
Titrate to:      80 mg if LDL >1.8 mmol/L after 6 weeks.
Monitor:         LFTs at baseline, repeat if symptoms; CK if myalgia.
Hold/withdraw:   ALT > 3× ULN, CK > 5× ULN, pregnancy.

E. Free-form clinician's notes / bullet list

Atorvastatin — quick notes
- HMG-CoA inhibitor, lowers LDL.
- 10–80 mg PO nocte. Max 80.
- Watch for muscle pain, dark urine → check CK.
- Avoid in pregnancy and active liver disease.
- CYP3A4 — careful with clarithromycin / itraconazole.

F. Competitor drug-app page (HTML stripped to plain text)

Atorvastatin
Class: Statin · Schedule: S4 · Cardiovascular
Used for: Cholesterol, CV prevention
Dose: 10-80 mg once daily
Side effects: Muscle aches, raised liver enzymes, rare rhabdo
Interactions: Macrolides, azoles, fibrates
Avoid in: Liver disease, pregnancy

G. Word / Google-Docs export (markdown or plain text)

**Atorvastatin (Lipitor)**

Indications: hypercholesterolaemia, CV prevention.
Dose: 10–80 mg PO daily.
Half-life: ~14 h. CYP3A4.
Contraindications: liver disease, pregnancy.
Adverse: myalgia, raised LFTs.

Partial source (any of the above, missing topics)

If the source is silent on a topic, the converter writes "Content pending clinical update." in val (or omits the section). Never invents.

4. The mapping audit (always emitted, after the JSON)

MAPPING AUDIT — <drug name>
Source heading / chunk            → Section code
--------------------------------- ----------------
NAME OF THE MEDICINE              → name / class / subclass
POISON SCHEDULE                   → form (schedule)
INDICATIONS                       → ind
DOSAGE AND ADMINISTRATION         → dose, summary
PHARMACOLOGY / PK                 → evid (+ stats Half-life)
CONTRAINDICATIONS                 → contra
PRECAUTIONS                       → risk, spec
INTERACTIONS WITH OTHER MEDICINES → inter
ADVERSE EFFECTS                   → risk
(no source for monitoring)        → mon (placeholder)
(no source for sources)           → src (omitted)

PLACEHOLDERS USED: mon
SECTIONS OMITTED:  pearl, sel, comp, safe, src, quick

For STRICT-MODE input the audit collapses to one line:

MAPPING AUDIT — <drug name>: strict Phase E/G mapping (16-row Master Table
→ spine sections). PLACEHOLDERS USED: none. SECTIONS OMITTED: none.

5. Posting one drug to the API

curl -X POST http://localhost:8080/api/drugs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -d @one-drug.json

POST, PUT and DELETE on /api/drugs all require the bearer key. Only GET is unauthenticated.

6. Merge mode — updating an existing entry

Use merge mode when you have new source material for a drug that already exists in the guide and you want the converter to keep the best content from both sources rather than overwriting wholesale.

Merge intent phrases

"update this drug" · "update the guide entry" · "update <drug name>" · "improve this entry" · "improve the guide entry" · "enrich this drug" · "enrich the guide entry" · "merge this with the guide" · "merge this into the guide" · "update the guide"

Force a clean overwrite instead (skip DB lookup entirely):

"fresh conversion" · "force clean conversion" · "ignore existing entry"

What the converter emits in merge mode

Before the JSON array it prints:

BASELINE LOADED: Acamprosate (id=1, 13 sections, 4 stats, 11 quick rows)
FORMAT DETECTED: amh-bnf (auto-sniffed; override with "treat this as tga pi")

If no existing entry is found:

BASELINE: none — clean conversion

→ proceeds as a standard new-drug conversion (no MERGE AUDIT).

If the LLM has no network access it will ask you to paste the current JSON from GET /api/drugs/<slug>, or type "fresh conversion" to start clean.

The five appraisal outcomes

Outcome	Meaning
KEEP	Baseline row(s) kept exactly — incoming is vague or a placeholder
IMPROVE	Specific rows surgically updated; rest of section unchanged
REPLACE	Entire section replaced — incoming is clearly richer overall
MERGE	Best rows from both sources combined — each has unique detail
GAP-FILLED	Section was absent/placeholder in baseline; incoming fills it

The conservative default is KEEP — when in doubt, the baseline wins.

Appraisal engine mechanisms (quick summary)

Mechanism	What it does
Specificity Ladder	Levels 1–5 rank content: Level 1 = numeric threshold; Level 5 = placeholder. Lower level wins.
Same-key tie-breaking	Same row key in both sources: (A) lower level wins, (B) higher severity wins, (C) value with a number wins. Baseline wins any remaining tie.
Severity guard	Incoming cannot lower a severity prefix. Baseline severity is locked; discrepancy noted in Reason. Escalation is always allowed.
High-yield gate	Incoming row is only added in MERGE if it adds: a Level 1–2 value, a new population, a new severity callout, or a named drug/mechanism not in baseline.
Consistency pass	After per-section appraisal: dose ↔ contra, dose ↔ spec, dose ↔ mon, inter ↔ mon are checked. More specific value propagates to the paired section.
Summary synthesis	`summary` is always actively synthesised — Clinical Focus merges best safety statement from both sources regardless of section outcome.
Class-weight	5 high-risk buckets (OST, Anticoagulant, NTI, Clozapine, Insulin) have elevated sections. In those sections same-level ties prefer IMPROVE/MERGE over KEEP. Reason prefixed "[Elevated: <bucket>]".

MERGE AUDIT shape (after the MAPPING AUDIT)

MERGE AUDIT — <drug name>
Baseline: id=<id>, <N> sections, <S> stats, <Q> quick rows
Source:   <format code> (<sniff method>)

Section (type)              | Outcome    | Reason
----------------------------+------------+-----------------------------------------------
Rapid Summary (summary)     | IMPROVE    | summary — Clinical Focus: synthesised from both sources; incoming adds induction-window qualifier.
Dosing (dose)               | KEEP       | Baseline is Level 1 (4 numeric rows); incoming is Level 3 (no thresholds).
Formulation (form)          | KEEP       | Baseline is Level 2 (named strengths); incoming is Level 4 (omits strengths).
Indications (ind)           | MERGE      | Incoming adds PBS row (Level 2) — passes high-yield gate.
Mechanism (evid)            | KEEP       | …
Risk Profile (risk)         | IMPROVE    | Incoming upgrades CAUTION → HIGH on seizure row; severity escalation applied.
Contraindications (contra)  | KEEP       | Baseline is Level 1 (eGFR threshold); incoming is Level 3 — baseline wins.
Interactions (inter)        | MERGE      | Incoming adds named interaction class not in baseline — passes high-yield gate.
Monitoring (mon)            | GAP-FILLED | No baseline monitoring section existed; incoming provides N rows.
Clinical Pearls (pearl)     | KEEP       | …
Special Populations (spec)  | IMPROVE    | Incoming is Level 1 (eGFR threshold) vs baseline Level 3 (consistency pass: eGFR threshold propagated from dose).
Class Safety (safe)         | KEEP       | …
Best Uses (sel)             | KEEP       | …
Pros & Cons (comp)          | KEEP       | Baseline is Level 2; incoming is Level 4 — baseline wins.
Sources (src)               | MERGE      | Incoming adds new reference not in baseline — passes high-yield gate.

HEADER FIELDS CHANGED: <field> <old>→<new> or "none"
HEADER FIELDS UNCHANGED: <list>
STATS CHANGED: <description> or "none"
QUICK CARD: KEEP|IMPROVE|REPLACE|MERGE (<one-sentence reason>)

PUT this merged entry to: PUT /api/drugs/<id>
  curl -X PUT http://localhost:8080/api/drugs/<id> \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ADMIN_API_KEY" \
    -d @merged-drug.json

All 15 sections appear in the table (even those with KEEP) so the audit is a complete record of every editorial decision. The Reason column identifies the specific content difference that drove the decision, referencing specificity levels, severity changes, and any consistency-pass propagations. The merged JSON is a full drug object (not a diff) — use the printed PUT command to apply it.

7. Boundaries — what the converter will NOT do

Invent clinical facts. Missing topics → placeholder, never a guess.
Convert non-drug content (disease pages, calculators).
Read image-only PDFs. Extract text first.
Add new section codes, severity words, schedules, or palette colours.
Infer PBS or TGA tags from clinical wording alone. Regulatory tags need source-backed review evidence.
Run without an intent phrase.
Auto-POST the merged result — you review the JSON first, then PUT manually.

For the full extraction algorithm, the chunk-to-section keyword heuristic, both worked examples end-to-end, and the common-mistakes list, see drug-data-converter-guide.md. The LLM-pasteable contract itself lives in drug-data-converter-prompt.txt.