A homunculus for personal health

1. Motivation

Most people don't know when a symptom deserves a doctor, an ER, or a good night's sleep. Search engines return anxiety-inducing worst-case reading; nurse hotlines are slow and rarely visual. We built Homunculus to sit in that gap — a private, always-on assistant that listens carefully, looks at photos, and speaks in plain language.

2. System overview

• Multimodal chat. Text + optional images go to a vision-capable LLM (Gemini 2.5 Flash) through the Lovable AI gateway.
• Triage prompt. A system prompt anchors the model to clinical caution, red-flag detection, and clear disclaimers.
• Severe-condition library. A curated dataset of high-urgency symptom patterns links directly into new chats.
• Persistent memory. Chats and messages are stored per account with row-level security so nobody sees anyone else's data.

3. Safety model

The assistant is designed to over-refer, not under-refer. When it detects red-flag patterns (chest pain radiating down the arm, sudden neurological deficit, anaphylaxis signs, severe abdominal rigidity, etc.) it stops the conversational funnel and points to emergency care. Every response ends with a reminder that this is not medical advice.

4. Roadmap

• On-device photo pre-processing for skin, eye, and wound analysis.
• Longitudinal symptom tracking with weekly digests.
• Optional clinician review layer for ambiguous cases.

5. Model architecture

We use a vision-language backbone (Gemini 2.5 Flash) with structured system prompting rather than fine-tuning. This lets us update triage logic instantly without retraining, and keeps the underlying weights general-purpose — reducing the risk of overconfident wrong answers on conditions the model has seen too many examples of.

• Retrieval layer. Severe-condition dataset injected as context when red-flag keywords match.
• Reasoning trace. The model is asked to enumerate differentials, then narrow with follow-up questions.
• Refusal policy. Diagnostic certainty is never claimed; recommendations are framed as possibilities.

6. Evaluation

We benchmark against a private set of 400 vignettes covering common primary-care presentations and 60 emergency-red-flag scenarios. Metrics we track: red-flag recall (must be near 100%), inappropriate reassurance rate, and Flesch-Kincaid grade level of responses (target: ≤ grade 8).

7. Limitations

• No physical exam, vitals, or lab access — pattern recognition only.
• Photo analysis is best on well-lit, close-up, focused images.
• Rare and pediatric conditions have thinner training coverage.
• Not a replacement for emergency services, urgent care, or a physician.

8. References

• Semigran HL et al. "Evaluation of symptom checkers for self-diagnosis and triage." BMJ 2015.
• Singhal K et al. "Large language models encode clinical knowledge." Nature 2023.
• NIH MedlinePlus, emergency symptom guidelines (accessed 2026).
• American Heart Association — 2020 Guidelines for CPR and ECC.

9. Prompting strategy

The system prompt is layered: a global preamble anchors the assistant's role and tone, a triage layer enumerates red-flag categories, and a formatting layer requires a structured response with sections for "what I'm hearing", "possibilities", "questions back to you", and "what to do next". This shape makes the output easier to scan on mobile and forces the model to distinguish observation from recommendation.

10. Vision pipeline

• Images are sent inline to the multimodal model; no separate CV pre-processing on the server.
• The model is instructed to describe what it sees before offering an interpretation.
• Low-quality or ambiguous photos trigger a request for a better image rather than a guess.
• Photos are stored per-user and never used for training.

11. Failure modes

• Anchoring. Early user framing can bias downstream turns; mitigated by re-summarising the case each response.
• Over-reassurance. Tracked as a headline evaluation metric.
• Hallucinated citations. The assistant is instructed not to fabricate paper titles or dosing.
• Locale gaps. Emergency numbers and drug names default to US; users should confirm locally.

12. Governance

Prompt changes are versioned and reviewed against the evaluation set before rollout. Any regression in red-flag recall blocks release. User-reported incidents feed a triage backlog reviewed weekly.