Best Practices

Guidance for system prompts, temperature, multi-turn chat, tokens, errors, security, and responsible use when building with Vaidya.

Always set a system prompt that matches your use case.
Include language preference, response format (bullets, structured sections, length), and tone (clinical, patient-friendly, etc.).
Example patterns and case-specific ideas live in the Prompt Guide and Chat Completions API examples.

Use case	Suggested `temperature`	Rationale
Emergency / clinical	0.2–0.3	Accuracy-focused, less randomness
Symptom checker	0.4–0.6	Balanced clarity and flexibility
Wellness plans	0.6–0.7	More personalized, varied wording
Admin summarization	0.2–0.4	Factual, consistent summaries

Tune per deployment; lower is safer when factual correctness matters most.

Pass the full conversation history in the messages array on every request.
The model has no memory between HTTP calls—only what you send in messages counts as context.
Include all relevant context (prior symptoms, constraints, user goals) in each turn when it affects the answer.

Monitor usage from the response usage object (prompt, completion, and total tokens when returned).
Set max_tokens per use case so answers are long enough to be useful but bounded.
Longer prompts and history mean more prompt tokens and higher cost—trim redundant turns when safe.

For account-level call volume, success rate, errors, plan limits, and Console alerts, see Monitoring Usage.

Implement retry logic with exponential backoff (and jitter) for transient failures.
Retry 429 (rate limit) and 5xx (server errors) gracefully; honor Retry-After when present.
Do not blindly retry 400 (bad request) or 401 (auth)—fix the payload or credentials first.

Keep API keys server-side only; never expose them in browsers or mobile apps without a backend.
Load keys from environment variables or a secrets manager in production.
Rotate keys periodically and after any suspected leak.
Use separate keys for development, staging, and production.

Always make clear that Vaidya is not a replacement for qualified medical professionals or emergency care.
Show disclaimers in user-facing UI wherever health guidance is shown.
For emergency-style assist flows, always instruct users to contact local emergency services when symptoms may be urgent or life-threatening.