From 00f8f89e67dfbf4ac0cd4f92ca3c4a042d0b6caa Mon Sep 17 00:00:00 2001 From: saridsa2 Date: Fri, 17 Apr 2026 10:56:34 +0530 Subject: [PATCH] docs: AI coaching panel design spec Three-zone panel (summary card + rule-driven suggestions + chat), structured AI responses, progressive suggestions, CallerContextService + rules engine pipeline. Replaces P360 tab toggle with single surface. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-04-17-ai-coaching-panel-design.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/specs/2026-04-17-ai-coaching-panel-design.md diff --git a/docs/specs/2026-04-17-ai-coaching-panel-design.md b/docs/specs/2026-04-17-ai-coaching-panel-design.md new file mode 100644 index 0000000..e705910 --- /dev/null +++ b/docs/specs/2026-04-17-ai-coaching-panel-design.md @@ -0,0 +1,188 @@ +# AI Coaching Panel — Design Spec + +## Goal + +Replace the current AI chat panel with a proactive coaching surface that shows structured patient summaries, rule-driven upsell/cross-sell/retention suggestions with clickable scripts, and a contextual chat — all in the existing 400px right-hand panel. + +## Architecture + +Single scrollable panel, three zones. No tabs or toggles. Caller context pre-fetched and cached in Redis (CallerContextService). Rules engine produces suggestion triggers. AI renders triggers into natural language scripts. Every AI response includes updated suggestions (progressive). + +## Panel Layout + +### Zone 1 — Summary Card (pinned top, ~120px) + +- Patient name, age, gender, patient type badge (NEW / RETURNING) +- 2-line AI summary (from `aiSummary` field on lead record) +- Campaign badge + source tag (e.g., "Cervical Cancer Screening Drive" / "Google") +- Compact appointment pills: next upcoming appointment (date + doctor), last completed (date + outcome) +- Renders from CallerContextService data — no AI call needed for this zone + +For new callers (no lead/patient): shows phone number, "New Caller" badge, and a prompt to collect name. + +### Zone 2 — Suggestions (collapsible, below summary) + +- 2-4 suggestion pills as compact cards +- Each pill: type icon (tag/arrow-up/rotate-cw), one-line title, priority dot (high/medium/low) +- Click expands inline with a 2-3 sentence ready-to-read script +- Expanded state has a "Tell me more" link that sends the suggestion as a chat message +- Suggestions refresh with every AI response (progressive) +- Collapse/expand toggle for the entire section ("Suggestions (3)") + +Suggestion types: +- **upsell** — premium packages, add-on services +- **crosssell** — related services in other departments +- **retention** — reschedule missed appointments, follow up on lapsed visits +- **operational** — fasting reminders, insurance docs, directions + +### Zone 3 — Chat (fills remaining space) + +- Streaming chat, same UX as today +- Agent types questions or clicks "Tell me more" from a suggestion +- Each AI response may include updated suggestions (Zone 2 refreshes) +- Quick action pills at bottom, contextual to conversation state +- Auto-fires patient summary on call connect (existing behavior, kept) + +## Structured AI Response Format + +Every AI response is structured JSON (not free-form text): + +```json +{ + "message": "Priya Sharma is a returning patient...", + "suggestions": [ + { + "id": "s1", + "type": "upsell", + "title": "Cardiac Wellness Package", + "script": "Since you're already seeing Dr. Lakshmi for cardiology, we have a comprehensive cardiac wellness package...", + "priority": "high" + }, + { + "id": "s2", + "type": "retention", + "title": "Reschedule missed appointment", + "script": "I see your last appointment on April 10th was rescheduled. Would you like me to book a new slot?", + "priority": "medium" + } + ] +} +``` + +The `message` field renders as a chat bubble in Zone 3. The `suggestions` array replaces the current set in Zone 2. If `suggestions` is empty or absent, Zone 2 retains the previous set. + +The initial auto-fired response includes the summary message + first set of suggestions. Subsequent responses update suggestions based on conversation context. + +## Rules Engine to AI Prompt Pipeline + +### Step 1: Rules evaluation + +CallerContextService already builds the caller facts (appointments, campaigns, call history, lead status, interested service). The rules engine evaluates these facts against configured suggestion rules. + +Each rule produces a raw trigger: +```json +{ + "type": "upsell", + "product": "cardiac-wellness-package", + "reason": "Patient has cardiology appointment, no wellness package booked", + "priority": "high" +} +``` + +### Step 2: Prompt injection + +Raw triggers are appended to the system prompt as a `SUGGESTION RULES` section: + +``` +SUGGESTION RULES (from business configuration): +Based on this caller's profile, the following suggestions should be offered. +Generate a natural, conversational script for each that the agent can read aloud. +Return them in the `suggestions` array of your JSON response. + +1. [upsell/high] Cardiac Wellness Package — patient has cardiology appointment, no wellness package booked +2. [retention/medium] Reschedule missed appointment — last appointment was rescheduled, no new booking +``` + +### Step 3: AI generates scripts + +The AI turns the raw triggers into conversational scripts using the caller's context (name, history, doctor, department). Scripts are personalized, not templated. + +### Step 4: Seeded rules + +Default suggestion rules seeded in the rules engine config: +- Package upsell by department (cardiology → cardiac wellness, ortho → physio package) +- Reschedule missed/cancelled appointments +- Cross-sell related departments (ortho → physio, cardio → dietician) +- First-visit patient: suggest health checkup package +- Returning patient with no recent visit: re-engagement prompt + +These rules are displayed read-only in Settings > Automations tab (same card pattern as existing automation rules — visible but not editable in v1). + +## Data Flow + +``` +Call arrives + -> CallerResolutionController.resolve() + -> CallerContextService.prewarm() (parallel fetch + Redis cache) + -> Frontend auto-fires AI chat + -> POST /api/ai/stream + -> buildCallerContext() — Redis cache hit + -> rulesEngine.evaluate(callerFacts) — produces suggestion triggers + -> buildSystemPrompt(KB + callerContext + suggestionRules + structuredOutputInstructions) + -> streamText() — AI returns structured JSON { message, suggestions } + -> Frontend parses response + -> Zone 1: summary card from CallerContextService (no AI needed) + -> Zone 2: suggestions from AI response + -> Zone 3: message as chat bubble + +Agent clicks "Tell me more" on a suggestion + -> Sent as chat message: "Tell me more about the Cardiac Wellness Package" + -> AI responds with detailed info + updated suggestions + -> Zone 2 refreshes with new suggestions + +Agent books appointment (via disposition/form) + -> System message injected into chat: "Agent booked appointment with Dr. Lakshmi on Apr 24" + -> Next AI response reflects the action + updates suggestions + (e.g., removes "reschedule" suggestion, adds "send appointment reminder via WhatsApp") +``` + +## Surface Area + +### Sidecar (helix-engage-server) + +| File | Change | +|------|--------| +| `ai-chat.controller.ts` | Add structured output instructions to system prompt. Add suggestion rules injection from rules engine. Parse/pass suggestion triggers. | +| `caller-context.service.ts` | Add rules evaluation method that runs caller facts against suggestion rules. Return triggers alongside context. | +| `rules-engine/` | Seed default suggestion rules (JSON config in Redis or file). | +| `config/ai.defaults.ts` | Update `ccAgentHelper` prompt template with structured output format instructions and suggestion generation rules. | + +### Frontend (helix-engage) + +| File | Change | +|------|--------| +| NEW: `ai-summary-card.tsx` | Zone 1 — patient profile card rendered from CallerContextService data | +| NEW: `ai-suggestions.tsx` | Zone 2 — suggestion pills with expand/collapse, script display, "Tell me more" | +| REWRITE: `ai-chat-panel.tsx` | Orchestrates all 3 zones. Parses structured JSON responses. Manages suggestion state. Passes "Tell me more" clicks as chat messages. | +| `context-panel.tsx` | Remove P360 tab toggle. Single surface — AI coaching panel is the only mode. | + +### No changes needed + +- `call-desk.tsx` — panel wrapper stays the same +- `app-shell.tsx` — no changes +- `CallerContextService` — already built, just add rules evaluation call +- Frontend build pipeline — no new dependencies + +## What this replaces + +- P360 context tab (appointments, call history, follow-ups tables) — replaced by AI summary card +- AI chat toggle — removed (single surface) +- Tool-based patient lookups during chat — replaced by pre-fetched context in KB +- Static quick action pills — replaced by rule-driven contextual suggestions + +## Out of scope for v1 + +- Editable suggestion rules UI (shown read-only in Settings) +- Supervisor AI coaching (different tool set, different panel) +- Real-time transcript-driven suggestions (requires live call transcription) +- Suggestion analytics (which suggestions agents click, conversion tracking)