How Gentle Pills Uses AI: A Technical Overview of Our Clinical Assistant Architecture

Gentle Pills is a clinical workspace for homeopathic doctors, and AI is wired into it as a specific, narrow kind of assistant: it drafts structure, surfaces relevant knowledge, and explains relationships in the classical materia medica — but it never writes to a patient record on its own, and it never makes the prescribing decision. This is a technical description of how that boundary is implemented, not just stated.

The request path

Every AI feature in the product follows the same pipeline, from the button a doctor clicks to the row that ends up in the database:

Contextual UI button (e.g. "Suggest rubrics" on a case)
  → runAiAction (Next.js server action)
    → task runner (src/lib/ai/tasks.ts)
        - builds case context: consultation notes, structured symptoms, prior analyses
        - retrieves relevant knowledge and/or rubrics for this specific case
    → getProvider(tier)
        - picks the Azure OpenAI deployment appropriate for this task's tier
    → provider.complete()
        - OpenAI-compatible Chat Completions API call
        - the expected output shape is embedded in the prompt as a JSON Schema,
          not described in prose
    → Zod schema validation of the model's structured output
    → persisted as an AiAnalysis row, with any cited passages stored as
      AiEvidence rows
  → result rendered back to the doctor as a labeled, pending suggestion

Nothing in this chain writes to a Patient, Case, Symptom, or Prescription table directly. The AI task runner only ever produces an AiAnalysis — a separate, clearly-AI-attributed record that sits next to the clinical data until a doctor explicitly acts on it. Accepting an analysis is a distinct, logged action; the AI pipeline itself has no path that bypasses it.

Why every suggestion stays a suggestion

Three properties hold for every AI output in the product, by construction:

• Labeled. The UI never presents an AI result as if it were doctor-entered data. It is visually and structurally distinct — a separate card, a separate table, a separate color treatment — for as long as it exists.
• Editable and dismissible. A doctor can discard an AI suggestion with no trace left in the clinical record, or edit it before accepting anything from it.
• Gated behind explicit confirmation. Nothing an AI task produces becomes part of the permanent record until a doctor takes a separate, deliberate action to accept it. For example, accepting a structure_notes analysis is what converts its candidate symptoms into doctor-confirmed Symptom rows — the AI's output alone is inert data sitting in an AiAnalysis record until that happens.

This is not a UI convention layered on top of a system that could technically write directly — there is no code path from the AI task runner to clinical tables that skips the confirmation step. The constraint is structural, not just visual.

Why the output shape comes from a schema, not a description

Early on, a task's prompt described its expected output in prose — "respond with a list of rubric suggestions" — and relied on the model inferring sensible field names. That worked with one model family and broke silently when we changed which deployment handled that task: the replacement model produced a plausible-but-different JSON shape, and validation rejected every response. The fix was structural: every task now generates its expected output shape directly from the same Zod schema used to validate the response (via z.toJSONSchema()), and includes that JSON Schema verbatim in the prompt. The model is told the exact shape it's being checked against — the contract isn't restated twice in two different words that can drift apart. (This is covered in depth in a dedicated article on schema-derived prompting.)

The nine tasks

Each AI-assisted action in the product maps to one of nine tasks, each routed to a model tier chosen by how costly a wrong answer would be — not by how "hard" the task feels:

• structure_notes (fast) — extracts candidate structured symptoms from free-text consultation notes, preserving the doctor's original wording.
• match_prognostic_observation (fast) — matches a case's follow-up pattern against Kent's twelve observations on the direction of cure.
• summarize_case (mid) — produces a case summary: key symptoms, chronology, and open gaps in the picture.
• followup_summary (mid) — summarizes how a case has evolved since treatment began.
• suggest_rubrics (mid) — suggests repertory rubrics relevant to a case, limited strictly to the loaded repertory corpus.
• remedy_relationship_narrative (mid) — turns a terse classical remedy relationship (complementary, follow-well, antidote) into a case-aware explanation.
• research_knowledge (reasoning) — synthesizes a grounded answer to a knowledge question, citing retrieved passages.
• compare_remedies (reasoning) — produces an evidence-based comparison across candidate remedies for a case.
• isolate_miasmatic_layers (reasoning) — surfaces candidate miasmatic layers present in a case's symptom picture, for the doctor to evaluate against Kent's classical framework.

Fast-tier tasks are deterministic-checkable classification or extraction against a fixed structure — a wrong answer is cheap to catch because the doctor is reviewing it before anything is saved. Reasoning-tier tasks involve open clinical judgment and multi-source synthesis, where the strongest available model earns its latency and cost. This tiering is covered in its own article; the point here is that the choice of model is a per-task engineering decision, not a single global setting.

What this is, and what it deliberately isn't

Gentle Pills' AI layer is built to be clinical decision support for a licensed homeopathic doctor who already has a patient in front of them — not an autonomous prescriber, and not a general-purpose chatbot. It has no path to diagnose on its own, no path to generate a prescription that reaches a patient without a doctor's explicit action, and no mechanism to modify a clinical record silently. Every one of the nine tasks above produces a draft a doctor can accept, edit, or discard — never a fait accompli. The architecture exists to make that true at the code level, not just as a stated policy.