From 275b2a62920627ab3e934845824f4d6b52519dab Mon Sep 17 00:00:00 2001 From: saridsa2 Date: Fri, 17 Apr 2026 11:06:48 +0530 Subject: [PATCH] =?UTF-8?q?docs:=20AI=20coaching=20panel=20implementation?= =?UTF-8?q?=20plan=20=E2=80=94=208=20tasks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers: suggestion rules engine, structured AI output, summary card, suggestions component, chat panel rewrite, context panel wiring, settings UI, deploy + test. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/plans/2026-04-17-ai-coaching-panel.md | 140 +++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/plans/2026-04-17-ai-coaching-panel.md diff --git a/docs/plans/2026-04-17-ai-coaching-panel.md b/docs/plans/2026-04-17-ai-coaching-panel.md new file mode 100644 index 0000000..8054822 --- /dev/null +++ b/docs/plans/2026-04-17-ai-coaching-panel.md @@ -0,0 +1,140 @@ +# AI Coaching Panel Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the AI chat panel with a three-zone coaching surface — structured summary card, rule-driven suggestions with scripts, and contextual chat with progressive suggestion updates. + +**Architecture:** CallerContextService (already built) pre-fetches caller data into Redis. Rules engine evaluates caller facts against seeded suggestion rules, producing triggers. AI system prompt includes caller context + suggestion triggers + structured output instructions. Every AI response returns `{ message, suggestions }` JSON. Frontend parses and renders across three zones. + +**Tech Stack:** React 19 + Tailwind (frontend), NestJS + Vercel AI SDK + json-rules-engine + Redis (sidecar), FontAwesome Pro icons + +--- + +## File Structure + +### Sidecar (helix-engage-server) + +| File | Responsibility | +|------|----------------| +| `src/rules-engine/suggestion-rules.ts` | NEW: Default suggestion rule definitions + evaluator function | +| `src/caller/caller-context.service.ts` | MODIFY: Add suggestion evaluation, render suggestions for prompt | +| `src/ai/ai-chat.controller.ts` | MODIFY: Inject suggestion rules into system prompt | +| `src/config/ai.defaults.ts` | MODIFY: Update ccAgentHelper prompt with structured JSON output format | + +### Frontend (helix-engage) + +| File | Responsibility | +|------|----------------| +| `src/components/call-desk/ai-summary-card.tsx` | NEW: Zone 1 patient profile card | +| `src/components/call-desk/ai-suggestions.tsx` | NEW: Zone 2 suggestion pills with expand/script/tell-me-more | +| `src/components/call-desk/ai-chat-panel.tsx` | REWRITE: Orchestrates 3 zones, parses structured JSON responses | +| `src/components/call-desk/context-panel.tsx` | MODIFY: Remove P360 tab toggle, single surface | +| `src/pages/rules-settings.tsx` | MODIFY: Display suggestion rules in Automations tab | + +--- + +## Task 1: Suggestion Rules Engine (Sidecar) + +**Files:** +- Create: `helix-engage-server/src/rules-engine/suggestion-rules.ts` +- Modify: `helix-engage-server/src/caller/caller-context.service.ts` + +- [ ] **Step 1:** Create `suggestion-rules.ts` with types (`SuggestionType`, `SuggestionPriority`, `SuggestionTrigger`), department-to-package mapping, cross-sell mapping, and `evaluateSuggestionRules(facts)` function that evaluates 5 default rules: (1) package upsell by department, (2) reschedule missed appointments, (3) cross-sell related departments, (4) first-visit health checkup, (5) returning patient re-engagement. Max 4 triggers returned. Also export `SUGGESTION_RULE_DEFINITIONS` array for Settings UI display. + +- [ ] **Step 2:** In `caller-context.service.ts`, add `suggestionTriggers: SuggestionTrigger[]` to the `CallerContext` type. Import `evaluateSuggestionRules`. Call it in the `build()` method after fetching all data, passing caller facts (isNew, appointments, calls, interestedService, contactAttempts, leadSource, utmCampaign). Add `renderSuggestionsForPrompt(triggers)` method that formats triggers for the AI system prompt. + +- [ ] **Step 3:** Build and verify: `npx tsc --noEmit` exits 0 + +- [ ] **Step 4:** Commit: `feat: suggestion rules engine + caller context evaluation` + +--- + +## Task 2: Structured Output in AI System Prompt (Sidecar) + +**Files:** +- Modify: `helix-engage-server/src/config/ai.defaults.ts` +- Modify: `helix-engage-server/src/ai/ai-chat.controller.ts` + +- [ ] **Step 1:** In `ai.defaults.ts`, append structured output instructions to `CC_AGENT_HELPER_DEFAULT` template. The AI must respond with valid JSON: `{"message": "...", "suggestions": [{"id", "type", "title", "script", "priority"}]}`. Rules: always include suggestions on first response, update on subsequent, no markdown in message field, max 4 suggestions, personalized scripts using caller's name/doctor/department. + +- [ ] **Step 2:** In `ai-chat.controller.ts` stream endpoint, after the caller context injection block, inject suggestion rules: `if (callerCtx.suggestionTriggers?.length) systemPrompt += this.callerContext.renderSuggestionsForPrompt(callerCtx.suggestionTriggers)` + +- [ ] **Step 3:** Build and verify: `npx tsc --noEmit` exits 0 + +- [ ] **Step 4:** Commit: `feat: structured JSON output + suggestion rules in AI system prompt` + +--- + +## Task 3: AI Summary Card Component (Frontend) + +**Files:** +- Create: `helix-engage/src/components/call-desk/ai-summary-card.tsx` + +- [ ] **Step 1:** Create Zone 1 component. Props: `caller: CallerSummary | null`. Renders: patient avatar + name + NEW/RETURNING badge, phone number, 2-line AI summary (line-clamped), source + campaign badges, compact appointment pills (next upcoming with green bg, last completed with gray bg). For null caller: centered placeholder text. Uses Badge component, FontAwesome icons (faUser, faCalendarCheck, faPhone). + +- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0 + +- [ ] **Step 3:** Commit: `feat: AI summary card component (Zone 1)` + +--- + +## Task 4: Suggestions Component (Frontend) + +**Files:** +- Create: `helix-engage/src/components/call-desk/ai-suggestions.tsx` + +- [ ] **Step 1:** Create Zone 2 component. Props: `suggestions: Suggestion[]`, `onTellMeMore: (suggestion) => void`. Exports `Suggestion` type (id, type, title, script, priority). Renders: collapsible section header "Suggestions (N)", list of compact pill cards. Each pill: type icon (faArrowUp/faTag/faRotate/faClipboardCheck), title, priority dot (red/yellow/green). Click toggles expand with script text + "Tell me more" link. Collapse/expand toggle for entire section. + +- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0 + +- [ ] **Step 3:** Commit: `feat: AI suggestions component (Zone 2)` + +--- + +## Task 5: Rewrite AI Chat Panel (Frontend) + +**Files:** +- Rewrite: `helix-engage/src/components/call-desk/ai-chat-panel.tsx` + +- [ ] **Step 1:** Rewrite to orchestrate 3 zones. New props: `callerSummary?: CallerSummary | null`. Adds `suggestions` state managed from parsed AI responses. `parseAiResponse(content)` extracts `{ message, suggestions }` from JSON, falls back to raw text on parse failure. Zone 1: AiSummaryCard (not shown for supervisor). Zone 2: AiSuggestions with `onTellMeMore` that appends "Tell me more about X" as chat message. Zone 3: chat with `displayMessages` that strips JSON wrapper showing only the message field. Auto-fire kept. Supervisor mode unchanged (quick actions, no summary/suggestions). Keep existing MessageContent + parseLine helpers. + +- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0 + +- [ ] **Step 3:** Commit: `feat: rewrite AI chat panel — 3-zone coaching surface` + +--- + +## Task 6: Wire Context Panel (Frontend) + +**Files:** +- Modify: `helix-engage/src/components/call-desk/context-panel.tsx` + +- [ ] **Step 1:** Remove P360 tab toggle (activeTab state, tab buttons, P360 sections — appointments list, call history list, follow-ups list). Build `callerSummary` object from `selectedLead` + `appointments` data: name, phone, isNew, aiSummary, leadSource, utmCampaign, nextAppointment (first SCHEDULED after now), lastAppointment (first COMPLETED). Pass `callerSummary` to AiChatPanel as new prop. Single surface — AiChatPanel is the only content. + +- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0 + +- [ ] **Step 3:** Commit: `feat: remove P360 toggle, single coaching surface` + +--- + +## Task 7: Settings UI — Suggestion Rules Display + +**Files:** +- Modify: `helix-engage/src/pages/rules-settings.tsx` + +- [ ] **Step 1:** Add `SUGGESTION_RULES` array (5 items: name, category, description, enabled) to the Automations tab. Render below existing automation rules with "AI Suggestions" subheading. Same card pattern: category badge, name, description, enabled/disabled dot. All enabled, read-only. + +- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0 + +- [ ] **Step 3:** Commit: `feat: display suggestion rules in Settings > Automations` + +--- + +## Task 8: Build, Deploy, Test + +- [ ] **Step 1:** Build sidecar: `cd helix-engage-server && npm run build` +- [ ] **Step 2:** Build frontend: `cd helix-engage && npm run build` +- [ ] **Step 3:** Deploy sidecar to ECR + pull on EC2 +- [ ] **Step 4:** Deploy frontend to EC2 via rsync + restart Caddy +- [ ] **Step 5:** Test on Tauri: rebuild frontend with Global URL, launch, trigger call. Verify: Zone 1 summary card, Zone 2 suggestions from rules, click expand shows script, "Tell me more" sends to chat, progressive suggestion updates, server logs show cache hits and no tool calls for patient data +- [ ] **Step 6:** Final commit and push both repos