Prompt Guide

Write better prompts, get better healthcare responses — patterns and defaults for every Vaidya use case.

What this page is for

Better prompts → better responses. Here’s a repeatable structure for each request: objective, context, input data, output shape, and safety guardrails.

We call that meta-prompting — you’re giving the model a small spec every time.

Rules of thumb

Set the right case — it routes to the correct healthcare workflow.
Be specific — “analyze this report” without data is weak; paste values and say what you want back.
Define the output — sections, bullets, or JSON keys the model must follow.
Keep temperature low — about 0.2–0.3 for factual medical tasks.
facility_search — include city, locality, or pincode.
Lab tasks — include units and reference ranges when you have them.
Ask for separation — known facts vs assumptions / inferences.

Parameter cheat sheet

Parameter	What it does	Typical values	When to care
`case`	Routes the workflow	See case values	Every request
`temperature`	Randomness	`0.2`–`0.3` for medical accuracy	Lower = more deterministic
`max_tokens`	Hard cap on reply length	`400`–`1400` by case	Raise for long plans / lab summaries
`top_p`	Nucleus sampling	`0.9`–`1.0`	Rarely needs changing
`presence_penalty`	New topics	`0`–`0.2`	Long multi-turn chats
`frequency_penalty`	Less repetition	`0`–`0.3`	Verbose or repetitive outputs
`stream`	SSE token stream	`true` / `false`	Chat UIs
`stream_options.include_usage`	Token usage in stream	`true`	Billing / telemetry

Suggested defaults by `case`

Case	Temperature	Max Tokens
`symptom_qa`	0.3	450
`drug_lookup`	0.2	500
`facility_search`	0.2	550
`health_score`	0.2	900
`lab_report_text`	0.2	1000
`lab_report_pdf`	0.2	1200
`lab_report_image`	0.2	1300
`health_plan`	0.3	1400

Universal prompt template

Paste into messages[].content. Omit sections you don’t have.

Task:
<One-line objective>

User Profile:
- Age/Sex: <value or unknown>
- Known Conditions: <value>
- Current Medications: <value>
- Allergies: <value>

Context:
- Timeline: <onset, duration, trend>
- Relevant History: <short bullets>

Input Data:
<symptoms / meds / biomarkers / report text>

Output Contract:
1. <Section 1>
2. <Section 2>
3. <Section 3>
4. <Section 4>

Formatting Rules:
- Max <N> words
- Bullet points only
- No tables

Safety Rules:
- No invented values
- Explicitly list missing inputs
- Clearly mark assumptions
- Include urgent escalation red flags when relevant

Templates per `case`

1. Symptom Q&A (`symptom_qa`)

Task:
Triage symptoms and provide safe next steps.

User Profile:
- Age/Sex: <value>
- Known Conditions: <value>
- Current Medications: <value>
- Allergies: <value>

Context:
- Onset: <value>
- Duration/trend: <value>
- Severity: <mild/moderate/severe>

Input Data:
- Symptoms: <list>
- Vitals: <if available>

Output Contract:
1. Most likely causes (ranked)
2. Home care for next 24-48 hours
3. Red flags requiring urgent care
4. What to monitor and when to consult

Formatting Rules:
- <=220 words, bullets only.

Safety Rules:
- Not a confirmed diagnosis.
- List missing clinical inputs.

2. Drug / Medicine Lookup (`drug_lookup`)

Task:
Check medication compatibility and safety.

User Profile:
- Age/Sex: <value>
- Conditions: <value>
- Current meds/supplements: <list>
- Kidney/liver concerns: <value>

Input Data:
- Candidate medicine(s): <name + dose + frequency>

Output Contract:
1. Interaction risk summary
2. Common side effects
3. Contraindications/caution groups
4. Practical timing/spacing guidance
5. When clinician review is needed

Formatting Rules:
- Bullet points.
- Include confidence level: high/medium/low.

Safety Rules:
- Do not infer dose if missing.

3. Nearby Facility Search (`facility_search`)

Task:
Find relevant nearby care facilities.

Context:
- Location: <city/locality/pincode>
- Specialty/service: <value>
- Timing: <open now/today/tomorrow>
- Constraints: <distance/budget/language>

Output Contract:
1. Top options
2. Why each matches
3. What to verify before booking
4. Fallback option

Formatting Rules:
- If location is incomplete, ask for exact locality/pincode first.

4. Health Score Computation (`health_score`)

Task:
Compute health score and identify top priorities.

User Profile:
- Age/Sex: <value>
- Lifestyle constraints: <value>

Input Data:
- Biomarkers: <BP, HbA1c, lipids, etc>
- Behavior metrics: <sleep, steps, hydration, stress>

Output Contract:
1. Overall score (0-100)
2. Domain-wise breakdown
3. Top risk drivers
4. 14-day measurable improvement targets
5. Follow-up test suggestions

Formatting Rules:
- Mention assumptions if data is incomplete.

5. Lab Report Analysis — Text (`lab_report_text`)

Task:
Interpret the provided lab values.

Context:
- Report type/date: <value>
- Symptoms (if any): <value>

Input Data:
<markers with values, units, reference ranges>

Output Contract:
1. Abnormal markers with severity
2. Plain-language clinical meaning
3. Likely lifestyle contributors
4. Follow-up tests to discuss with doctor
5. Immediate 2-week action list

Formatting Rules:
- Separate facts vs assumptions.
- No tables.

6. Lab Report Analysis — PDF (`lab_report_pdf`)

Task:
Parse uploaded PDF and provide structured extraction + summary.

Context:
- Report date: <value>
- Symptoms: <value>

Output Contract:
1. JSON block:
   - biomarkers[]: {name, value, unit, ref_range, status}
   - critical_flags[]
2. Narrative summary
3. Follow-up test recommendations
4. Doctor discussion checklist

Formatting Rules:
- Include all extracted biomarkers.
- Mention parse confidence if uncertain.

7. Lab Report Analysis — Image/VLM (`lab_report_image`)

Task:
Read report image, extract values, and interpret.

Context:
- Image quality notes: <blur/glare/crop>

Output Contract:
1. Extracted values with units
2. Out-of-range markers
3. Interpretation summary
4. OCR uncertainty and retake guidance

Formatting Rules:
- Explicitly mark low-confidence extractions.

8. Personalized Health Plan (`health_plan`)

Task:
Build a practical personalized plan.

User Profile:
- Age/Sex: <value>
- Conditions: <value>
- Work/schedule constraints: <value>
- Diet preference: <value>

Input Data:
- Labs: <value>
- Lifestyle metrics: <value>
- Primary goal: <value>

Output Contract:
1. 30-day plan in weekly phases
2. Daily minimum actions
3. Tracking metrics with targets
4. Escalation criteria
5. Busy-day fallback plan

Formatting Rules:
- Specific and measurable actions only.

Pre-send checklist

case matches the task
Timeline + symptoms / meds / metrics included where relevant
Output shape is explicit (sections or JSON)
Asked for missing inputs / assumptions
temperature is low for factual work

Multi-turn chats

Keep clinically relevant turns in messages.
Preserve role order; don’t drop allergies, meds, or key history.
If the task changes, change case.
Long thread? Summarize into one compact user message to save tokens.

Good vs weak prompt

Task: Interpret annual labs and prioritize risk.
User Profile: 41/M, sedentary, family history of diabetes.
Context: no acute symptoms.
Input Data: HbA1c 6.1, LDL 156, HDL 36, TG 220, ALT 51.
Output Contract: ranked risk issues, plain-language interpretation, 14-day actions, follow-up tests, doctor checklist.
Formatting Rules: <=240 words, bullets only.
Safety Rules: no assumptions; list missing inputs.

Analyze this report.

Safety tips

Symptom flows: always ask for red flags / when to seek care.
Image/OCR: ask for confidence and what to re-shoot.
Ask for known vs inferred explicitly.
Prefer time-bound actions (“next 14 days”) over vague advice.

Full request examples

Standard text request

{
  "model": "Vaidya-v2",
  "case": "drug_lookup",
  "messages": [
    {
      "role": "user",
      "content": "Task: Check ibuprofen + paracetamol compatibility. User Profile: 32/M, no chronic disease. Input Data: ibuprofen 400 mg, paracetamol 650 mg. Output Contract: risk, spacing, side effects, stop conditions."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 500,
  "top_p": 0.95,
  "stream": false
}

Multimodal (PDF)

{
  "model": "Vaidya-v2",
  "case": "lab_report_pdf",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Task: Extract all biomarkers and summarize abnormalities in plain language."
        },
        {
          "type": "file_url",
          "file_url": {
            "url": "https://example.com/reports/checkup.pdf"
          }
        }
      ]
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1200
}

Streaming

{
  "model": "Vaidya-v2",
  "case": "symptom_qa",
  "messages": [
    {
      "role": "user",
      "content": "Task: Quick triage for sore throat + mild fever, with red flags."
    }
  ],
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "temperature": 0.3,
  "max_tokens": 400
}

Response shape

Non-streaming

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1761710000,
  "model": "Vaidya-v2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 145,
    "completion_tokens": 120,
    "total_tokens": 265
  }
}

Streaming (SSE chunk)

{
  "id": "chatcmpl_stream_123",
  "object": "chat.completion.chunk",
  "created": 1761710100,
  "model": "Vaidya-v2",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "...partial text..."
      },
      "finish_reason": null
    }
  ]
}

Stream terminates with data: [DONE].

Examples

{
  "model": "Vaidya-v2",
  "case": "symptom_qa",
  "messages": [
    {
      "role": "user",
      "content": "Task: Triage sore throat and fever. User Profile: 29/F, no chronic disease, penicillin allergy. Context: onset 36h, moderate pain, no breathlessness. Input Data: temp 100.8 F, dry cough. Output Contract: causes, home care, red flags, consult triggers."
    }
  ],
  "temperature": 0.3,
  "max_tokens": 450
}

{
  "model": "Vaidya-v2",
  "case": "drug_lookup",
  "messages": [
    {
      "role": "user",
      "content": "Task: Interaction check. User Profile: 34/F, allergic rhinitis. Input Data: current cetirizine 10 mg nightly; candidate montelukast 10 mg. Output Contract: interaction risk, side effects, cautions, timing, clinician review triggers."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 500
}

{
  "model": "Vaidya-v2",
  "case": "facility_search",
  "messages": [
    {
      "role": "user",
      "content": "Task: Find same-day internal medicine clinics. Context: Andheri East, Mumbai; after 7 PM; within 5 km. Output Contract: top options, why fit, pre-booking checks."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 550
}

{
  "model": "Vaidya-v2",
  "case": "health_score",
  "messages": [
    {
      "role": "user",
      "content": "Task: Compute score and 14-day targets. Input Data: BP 134/86, HbA1c 5.9, LDL 152, HDL 39, TG 205, sleep 5.7 h, steps 4300/day, BMI 28. Output Contract: overall score, domain breakdown, top risk drivers, measurable actions."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 900
}

{
  "model": "Vaidya-v2",
  "case": "lab_report_text",
  "messages": [
    {
      "role": "user",
      "content": "Task: Interpret annual panel. Input Data: HbA1c 6.2, LDL 148, HDL 38, TG 210, Vitamin D 19, ALT 52. Output Contract: abnormalities, meaning, follow-up tests, 2-week actions, doctor questions."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1000
}

{
  "model": "Vaidya-v2",
  "case": "lab_report_pdf",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Task: Parse this PDF and output biomarker JSON + plain-language summary with severity and reference ranges."
        },
        {
          "type": "file_url",
          "file_url": {
            "url": "https://example.com/reports/annual-checkup.pdf"
          }
        }
      ]
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1200
}

{
  "model": "Vaidya-v2",
  "case": "lab_report_image",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Task: Read this report image, extract values with units, flag abnormalities, and mark uncertain OCR fields."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/reports/lab-photo.jpg"
          }
        }
      ]
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1300
}

{
  "model": "Vaidya-v2",
  "case": "health_plan",
  "messages": [
    {
      "role": "user",
      "content": "Task: Build 30-day plan for prediabetes risk reduction. User Profile: 39/M, vegetarian, desk job, 30 min/day exercise window. Input Data: HbA1c 6.1, BMI 29, sleep 6h, steps 3800/day. Output Contract: weekly phases, daily actions, tracking, escalation, fallback plan."
    }
  ],
  "temperature": 0.3,
  "max_tokens": 1400
}

{
  "model": "Vaidya-v2",
  "case": "symptom_qa",
  "messages": [
    {
      "role": "user",
      "content": "Task: Quick triage for mild fever and sore throat with red flags."
    }
  ],
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "temperature": 0.3,
  "max_tokens": 350
}

{
  "model": "Vaidya-v2",
  "case": "lab_report_text",
  "messages": [
    {
      "role": "user",
      "content": "Return ONLY valid JSON with keys: abnormal_markers, likely_implications, follow_up_tests, action_plan_14_days. Input: HbA1c 6.2, LDL 148, HDL 38, TG 210, Vitamin D 19."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 900
}

Minimal Working Request Template

{
  "model": "Vaidya-v2",
  "case": "symptom_qa",
  "messages": [
    {
      "role": "user",
      "content": "Task: Triage sore throat with mild fever. User Profile: adult, no known chronic disease. Context: onset 2 days, no breathlessness. Input Data: fever 100.4 F, dry cough. Output Contract: causes, home care, red flags, consult triggers. Formatting Rules: <=180 words, bullets. Safety Rules: no assumptions, list missing inputs."
    }
  ],
  "temperature": 0.3,
  "max_tokens": 450
}