Skip to main content
Synced from the repo — do not edit here

Canonical source: docs/claude/chat-atlas-spec.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

Chat — Atlas integration spec (handoff to Atlas agent)

Last updated 2026-06-22.

Goal​

Add two Atlas capabilities to the in-app chat (clinic ↔ client async messaging):

  1. Clinician draft assist — when staff opens a client's chat in basisflow-web, Atlas suggests a draft response based on the patient's full context. Clinician edits + sends.
  2. Auto-categorize incoming patient messages — server-side classification of each new client message into one of: clinical_question / symptoms / refill / scheduling / admin / urgent. Label written to the message doc for staff filtering and routing.

Neither is patient-facing. Atlas should be invisible to clients (no badge, no disclosure). Patients see normal clinician responses.

Inputs available per request​

For draft assist​

  • The full chat thread (last 50 messages from chatsv2/{conversationId}/messages)
  • Patient's BasisUserV1 (name, DOB, gender, height)
  • Active clinic relationship (clinicsv2/{cid}/clinic_users/{uid} — membership, plan, status)
  • Recent labs (last 90 days from users/{uid}/healthSummaries where type=lab)
  • Active protocols (clinicsv2/{cid}/clinic_users/{uid}/protocols)
  • Upcoming appointments (clinicsv2/{cid}/scheduled filtered by attendee uid)
  • The clinician's role + name (for tone matching)

For categorization​

  • The new message content + last 10 messages for context

Outputs​

Draft assist​

{
  "draft": "Hi Sarah — your ApoB came in at 0.72, which is in the optimal range. Given your family history we discussed last month, let's keep tracking it quarterly. Anything else feeling off?",
  "tone": "warm-clinical",        // for telemetry
  "references_used": ["lab:apob-2026-06-15", "appointment:past-2026-05-04"]
}

Categorization​

{
  "category": "clinical_question",  // clinical_question | symptoms | refill | scheduling | admin | other
  "confidence": 0.92,
  "urgency": "normal",              // normal | high | urgent
  "rationale": "Patient asked follow-up about lab interpretation"  // for staff side, optional
}

Integration points​

Draft assist​

  • basisflow-web chat compose drawer (file: hybrid/basisflow-web/components/chat/* — Atlas agent needs to locate the exact composer file)
  • New button in compose toolbar: ✦ Draft with Atlas
  • Tap → calls new Cloud Function chat_draft_assist (to be added in basis-functions/functions/src/functions_chat.py)
  • Function gathers context, calls Atlas, returns draft text
  • Compose drawer populates the input with the draft; clinician edits + sends normally via existing send_message

Categorization​

  • Hook into the existing send_message Cloud Function in functions_chat.py
  • Only fires when author_role == USER (incoming patient message)
  • Async classification (don't block the send) — fire-and-forget; write the category onto the message doc as metadata.atlas_category / metadata.atlas_urgency after a few hundred ms
  • basisflow-web staff inbox reads these fields to render category badges + sort by urgency

Existing Atlas infrastructure to reuse​

Per docs/claude/copilot.md (basisflow-web already has Claude/Atlas integration):

  • Same Anthropic API key + model selection
  • Same prompt-template pattern
  • Same patient-context-builder pattern (the existing copilot service builds patient context for in-app questions — reuse that builder for draft-assist too)

Atlas agent should NOT build a new context resolver — extend the existing one.

Non-goals​

  • Atlas does NOT respond to clients directly — never replaces clinician
  • No automatic message sending without clinician review (drafts are inserted into the compose box; clinician must explicitly send)
  • No PHI sent for training (HIPAA — same constraints as existing copilot per CLAUDE.md HIPAA summary)
  • No patient-side disclosure that Atlas helped draft

Testing​

  • Draft assist: test fixture with 5 sample patient chat threads + known clinical contexts. Snapshot the drafts → human review for tone + accuracy.
  • Categorization: 50 sample messages with expected categories → measure accuracy. Target ≥85% category-correct.
  • Latency budget: draft assist < 3s, categorization < 1s.

Effort estimate​

  • Categorization: ~1 day (server-side only, async, lightweight prompt)
  • Draft assist: ~2 days (server function + basisflow-web compose UI hook + telemetry)

Open question for product​

  • Should clinicians be able to save preferred drafts (e.g., "use my usual approach for this patient")? Could be v2.
  • Should drafts cite their references in a small accessory line for the clinician's review? ("Drew on: ApoB result Jun 15, last appt May 4") — useful for trust + accuracy review.

Mark these as v2 — out of scope for the initial integration.