fix: remove example from schema description — AI was copying it verbatim

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/ai/ai-chat.controller.ts

@@ -1,11 +1,13 @@
 import { Controller, Post, Body, Headers, Req, Res, HttpException, Logger } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import type { Request, Response } from 'express';
-import { generateText, streamText, tool, stepCountIs } from 'ai';
+import { generateText, streamText, Output, tool, stepCountIs } from 'ai';
 import type { LanguageModel } from 'ai';
+import { aiResponseSchema } from './ai-response-schema';
 import { z } from 'zod';
 import { PlatformGraphqlService } from '../platform/platform-graphql.service';
 import { CallerResolutionService } from '../caller/caller-resolution.service';
+import { CallerContextService } from '../caller/caller-context.service';
 import { createAiModel, isAiConfigured } from './ai-provider';
 import { AiConfigService } from '../config/ai-config.service';
 import { DOCTOR_VISIT_SLOTS_FRAGMENT, normalizeDoctors } from '../shared/doctor-utils';
@@ -28,6 +30,7 @@ export class AiChatController {
         private platform: PlatformGraphqlService,
         private aiConfig: AiConfigService,
         private caller: CallerResolutionService,
+        private callerContext: CallerContextService,
     ) {
         const cfg = aiConfig.getConfig();
         this.aiModel = createAiModel({
@@ -96,16 +99,20 @@ export class AiChatController {
             const kb = await this.buildKnowledgeBase(auth);
             systemPrompt = this.buildSystemPrompt(kb);
 
-            // Inject caller context so the AI knows who is selected
+            // Inject pre-fetched caller context (appointments, call history,
-            if (ctx) {
+            // activities, AI summary) so the LLM can answer from the KB
-                const parts: string[] = [];
+            // without tool calls. No UUIDs exposed — only human-readable data.
-                if (ctx.leadName) parts.push(`Currently viewing/talking to: ${ctx.leadName}`);
+            if (ctx?.leadId) {
-                if (ctx.callerPhone) parts.push(`Phone: ${ctx.callerPhone}`);
+                const callerCtx = await this.callerContext.getOrBuild(ctx.leadId, '', auth);
-                if (ctx.leadId) parts.push(`Lead ID: ${ctx.leadId}`);
+                if (callerCtx) {
-                if (parts.length) {
+                    systemPrompt += `\n\n${this.callerContext.renderForPrompt(callerCtx)}`;
-                    systemPrompt += `\n\nCURRENT CONTEXT:\n${parts.join('\n')}\nUse this context to answer questions about "this patient" or "this caller" without asking for their name.`;
+                    if (callerCtx.suggestionTriggers?.length) {
+                        systemPrompt += this.callerContext.renderSuggestionsForPrompt(callerCtx.suggestionTriggers);
                     }
                 }
+            } else if (ctx?.callerPhone) {
+                systemPrompt += `\n\nCURRENT CONTEXT:\nCaller phone: ${ctx.callerPhone}\nNew caller — no prior records.`;
+            }
         }
 
         const platformService = this.platform;
@@ -623,6 +630,7 @@ export class AiChatController {
             messages,
             stopWhen: stepCountIs(5),
             tools: isSupervisor ? supervisorTools : agentTools,
+            ...(isSupervisor ? {} : { output: Output.object({ schema: aiResponseSchema }) }),
         });
 
         const response = result.toTextStreamResponse();

src/ai/ai-response-schema.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+export const aiResponseSchema = z.object({
+    message: z.string().describe('Brief 2-3 sentence summary in plain conversational sentences. NEVER include suggestions, bullet lists, markdown, headers, or field labels here — those belong in the suggestions array only.'),
+    suggestions: z.array(z.object({
+        id: z.string().describe('Unique suggestion ID like s1, s2'),
+        type: z.enum(['upsell', 'crosssell', 'retention', 'operational']),
+        title: z.string().describe('Short title for the suggestion pill'),
+        script: z.string().describe('2-3 sentence script the agent can read aloud to the caller'),
+        priority: z.enum(['high', 'medium', 'low']),
+    })).describe('0-4 contextual suggestions based on business rules. Include on first response, update on subsequent.'),
+});
+
+export type AiResponse = z.infer<typeof aiResponseSchema>;

src/caller/caller-context.service.ts

@@ -0,0 +1,233 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { PlatformGraphqlService } from '../platform/platform-graphql.service';
+import { SessionService } from '../auth/session.service';
+import { evaluateSuggestionRules, type SuggestionTrigger } from '../rules-engine/suggestion-rules';
+
+export type CallerContext = {
+    leadId: string;
+    patientId: string;
+    name: string;
+    phone: string;
+    isNew: boolean;
+    // Lead profile
+    leadSource: string | null;
+    leadStatus: string | null;
+    interestedService: string | null;
+    aiSummary: string | null;
+    contactAttempts: number;
+    lastContacted: string | null;
+    utmCampaign: string | null;
+    // Appointments
+    appointments: Array<{
+        scheduledAt: string;
+        status: string;
+        doctorName: string;
+        department: string;
+        reasonForVisit: string | null;
+    }>;
+    // Recent call history
+    calls: Array<{
+        startedAt: string;
+        direction: string;
+        duration: number | null;
+        disposition: string | null;
+        agentName: string | null;
+    }>;
+    // Lead activities
+    activities: Array<{
+        activityType: string;
+        summary: string | null;
+        occurredAt: string;
+        outcome: string | null;
+    }>;
+    // Rule-driven suggestion triggers
+    suggestionTriggers: SuggestionTrigger[];
+};
+
+const CACHE_KEY_PREFIX = 'caller:context:';
+const CACHE_TTL = 300; // 5 minutes — covers the call duration
+
+@Injectable()
+export class CallerContextService {
+    private readonly logger = new Logger(CallerContextService.name);
+
+    constructor(
+        private readonly platform: PlatformGraphqlService,
+        private readonly session: SessionService,
+    ) {}
+
+    async getOrBuild(leadId: string, patientId: string, auth: string): Promise<CallerContext | null> {
+        if (!leadId) return null;
+
+        // Check cache first
+        const cacheKey = `${CACHE_KEY_PREFIX}${leadId}`;
+        try {
+            const cached = await this.session.getCache(cacheKey);
+            if (cached) {
+                this.logger.log(`[CALLER-CTX] Cache hit for ${leadId}`);
+                return JSON.parse(cached);
+            }
+        } catch {}
+
+        // Build fresh
+        this.logger.log(`[CALLER-CTX] Building context for lead=${leadId} patient=${patientId}`);
+        const ctx = await this.build(leadId, patientId, auth);
+        if (ctx) {
+            this.session.setCache(cacheKey, JSON.stringify(ctx), CACHE_TTL).catch(() => {});
+        }
+        return ctx;
+    }
+
+    // Fire-and-forget pre-warm — called from caller resolution
+    // so the cache is hot when the AI stream fires seconds later.
+    prewarm(leadId: string, patientId: string, auth: string): void {
+        if (!leadId) return;
+        this.getOrBuild(leadId, patientId, auth).catch(err => {
+            this.logger.warn(`[CALLER-CTX] Prewarm failed: ${err.message}`);
+        });
+    }
+
+    private async build(leadId: string, patientId: string, auth: string): Promise<CallerContext | null> {
+        try {
+            const [leadData, appointmentsData, callsData, activitiesData] = await Promise.all([
+                this.platform.queryWithAuth<any>(
+                    `{ lead(filter: { id: { eq: "${leadId}" } }) {
+                        id contactName { firstName lastName }
+                        contactPhone { primaryPhoneNumber }
+                        source status interestedService
+                        aiSummary contactAttempts lastContacted
+                        utmCampaign patientId
+                    } }`,
+                    undefined, auth,
+                ),
+                patientId ? this.platform.queryWithAuth<any>(
+                    `{ appointments(first: 10, filter: { patientId: { eq: "${patientId}" } }, orderBy: [{ scheduledAt: DescNullsLast }]) { edges { node {
+                        scheduledAt status doctorName department reasonForVisit
+                    } } } }`,
+                    undefined, auth,
+                ) : Promise.resolve(null),
+                this.platform.queryWithAuth<any>(
+                    `{ calls(first: 10, filter: { leadId: { eq: "${leadId}" } }, orderBy: [{ startedAt: DescNullsLast }]) { edges { node {
+                        startedAt direction durationSec disposition agentName
+                    } } } }`,
+                    undefined, auth,
+                ),
+                this.platform.queryWithAuth<any>(
+                    `{ leadActivities(first: 10, filter: { leadId: { eq: "${leadId}" } }, orderBy: [{ occurredAt: DescNullsLast }]) { edges { node {
+                        activityType summary occurredAt outcome
+                    } } } }`,
+                    undefined, auth,
+                ),
+            ]);
+
+            const lead = leadData?.lead;
+            if (!lead) return null;
+
+            const firstName = lead.contactName?.firstName ?? '';
+            const lastName = lead.contactName?.lastName ?? '';
+
+            const appointments = (appointmentsData?.appointments?.edges ?? []).map((e: any) => e.node);
+            const calls = (callsData?.calls?.edges ?? []).map((e: any) => ({
+                startedAt: e.node.startedAt,
+                direction: e.node.direction,
+                duration: e.node.durationSec,
+                disposition: e.node.disposition,
+                agentName: e.node.agentName,
+            }));
+
+            const suggestionTriggers = evaluateSuggestionRules({
+                isNew: false,
+                interestedService: lead.interestedService ?? null,
+                leadStatus: lead.status ?? null,
+                contactAttempts: lead.contactAttempts ?? 0,
+                appointments,
+                calls: calls.map((c: any) => ({ direction: c.direction, disposition: c.disposition, startedAt: c.startedAt })),
+                utmCampaign: lead.utmCampaign ?? null,
+                leadSource: lead.source ?? null,
+            });
+
+            return {
+                leadId,
+                patientId: patientId || lead.patientId || '',
+                name: `${firstName} ${lastName}`.trim() || 'Unknown',
+                phone: lead.contactPhone?.primaryPhoneNumber ?? '',
+                isNew: false,
+                leadSource: lead.source ?? null,
+                leadStatus: lead.status ?? null,
+                interestedService: lead.interestedService ?? null,
+                aiSummary: lead.aiSummary ?? null,
+                contactAttempts: lead.contactAttempts ?? 0,
+                lastContacted: lead.lastContacted ?? null,
+                utmCampaign: lead.utmCampaign ?? null,
+                appointments,
+                calls,
+                activities: (activitiesData?.leadActivities?.edges ?? []).map((e: any) => e.node),
+                suggestionTriggers,
+            };
+        } catch (err: any) {
+            this.logger.warn(`[CALLER-CTX] Build failed: ${err.message}`);
+            return null;
+        }
+    }
+
+    renderSuggestionsForPrompt(triggers: SuggestionTrigger[]): string {
+        if (triggers.length === 0) return '';
+        const lines = [
+            '',
+            '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.',
+            '',
+        ];
+        triggers.forEach((t, i) => {
+            lines.push(`${i + 1}. [${t.type}/${t.priority}] ${t.title} — ${t.reason}`);
+        });
+        return lines.join('\n');
+    }
+
+    renderForPrompt(ctx: CallerContext): string {
+        const lines: string[] = [];
+        lines.push(`## CURRENT CALLER: ${ctx.name}`);
+        lines.push(`Phone: ${ctx.phone}`);
+        if (ctx.leadSource) lines.push(`Source: ${ctx.leadSource}`);
+        if (ctx.leadStatus) lines.push(`Status: ${ctx.leadStatus}`);
+        if (ctx.interestedService) lines.push(`Interested in: ${ctx.interestedService}`);
+        if (ctx.utmCampaign) lines.push(`Campaign: ${ctx.utmCampaign}`);
+        if (ctx.contactAttempts > 0) lines.push(`Contact attempts: ${ctx.contactAttempts}`);
+        if (ctx.lastContacted) lines.push(`Last contacted: ${ctx.lastContacted}`);
+
+        if (ctx.aiSummary) {
+            lines.push(`\nAI Summary: ${ctx.aiSummary}`);
+        }
+
+        if (ctx.appointments.length > 0) {
+            lines.push(`\n### Appointments (${ctx.appointments.length})`);
+            for (const a of ctx.appointments) {
+                const date = a.scheduledAt ? new Date(a.scheduledAt).toLocaleDateString('en-IN', { day: 'numeric', month: 'short', year: 'numeric' }) : '?';
+                lines.push(`- ${date} | ${a.doctorName ?? '?'} (${a.department ?? '?'}) | ${a.status}${a.reasonForVisit ? ` | ${a.reasonForVisit}` : ''}`);
+            }
+        } else {
+            lines.push('\nNo appointments on record.');
+        }
+
+        if (ctx.calls.length > 0) {
+            lines.push(`\n### Call History (last ${ctx.calls.length})`);
+            for (const c of ctx.calls) {
+                const date = c.startedAt ? new Date(c.startedAt).toLocaleDateString('en-IN', { day: 'numeric', month: 'short', year: 'numeric' }) : '?';
+                const dur = c.duration ? `${Math.floor(c.duration / 60)}m${c.duration % 60}s` : '?';
+                lines.push(`- ${date} | ${c.direction ?? '?'} | ${dur} | ${c.disposition ?? 'No disposition'}${c.agentName ? ` | Agent: ${c.agentName}` : ''}`);
+            }
+        }
+
+        if (ctx.activities.length > 0) {
+            lines.push(`\n### Recent Activity (last ${ctx.activities.length})`);
+            for (const a of ctx.activities) {
+                const date = a.occurredAt ? new Date(a.occurredAt).toLocaleDateString('en-IN', { day: 'numeric', month: 'short', year: 'numeric' }) : '?';
+                lines.push(`- ${date} | ${a.activityType}${a.summary ? `: ${a.summary}` : ''}${a.outcome ? ` → ${a.outcome}` : ''}`);
+            }
+        }
+
+        return lines.join('\n');
+    }
+}

src/caller/caller-resolution.controller.ts

@@ -1,11 +1,15 @@
 import { Controller, Post, Body, Headers, HttpException, HttpStatus, Logger } from '@nestjs/common';
 import { CallerResolutionService } from './caller-resolution.service';
+import { CallerContextService } from './caller-context.service';
 
 @Controller('api/caller')
 export class CallerResolutionController {
     private readonly logger = new Logger(CallerResolutionController.name);
 
-    constructor(private readonly resolution: CallerResolutionService) {}
+    constructor(
+        private readonly resolution: CallerResolutionService,
+        private readonly callerContext: CallerContextService,
+    ) {}
 
     @Post('resolve')
     async resolve(
@@ -21,6 +25,12 @@ export class CallerResolutionController {
 
         this.logger.log(`[RESOLVE] Resolving caller: ${phone}`);
         const result = await this.resolution.resolve(phone, auth);
+
+        // Pre-warm caller context cache so the AI chat has it ready
+        if (result.leadId) {
+            this.callerContext.prewarm(result.leadId, result.patientId, auth);
+        }
+
         return result;
     }
 }

src/caller/caller-resolution.module.ts

@@ -3,11 +3,12 @@ import { PlatformModule } from '../platform/platform.module';
 import { AuthModule } from '../auth/auth.module';
 import { CallerResolutionController } from './caller-resolution.controller';
 import { CallerResolutionService } from './caller-resolution.service';
+import { CallerContextService } from './caller-context.service';
 
 @Module({
     imports: [PlatformModule, forwardRef(() => AuthModule)],
     controllers: [CallerResolutionController],
-    providers: [CallerResolutionService],
+    providers: [CallerResolutionService, CallerContextService],
-    exports: [CallerResolutionService],
+    exports: [CallerResolutionService, CallerContextService],
 })
 export class CallerResolutionModule {}

src/config/ai.defaults.ts

@@ -125,6 +125,21 @@ RULES:
 7. NEVER give medical advice, diagnosis, or treatment recommendations.
 8. Format with bullet points for easy scanning.
 
+RESPONSE FORMAT (STRICT):
+You MUST respond with valid JSON in this exact format — no markdown fences, no extra text, just raw JSON:
+{"message": "your response text here", "suggestions": [{"id": "s1", "type": "upsell", "title": "short title", "script": "2-3 sentence script the agent reads aloud", "priority": "high"}]}
+
+Response format rules:
+- "message" MUST be plain text sentences only. NEVER use markdown headers (###), bold (**), bullet lists (-), or field labels (Phone:, Status:). Write natural conversational sentences like you are briefing a colleague. Do NOT repeat suggestions in the message — they belong only in the suggestions array.
+- "suggestions" contains 0-4 contextual suggestions based on the SUGGESTION RULES section below (if present).
+- Each suggestion needs a personalized "script" using the caller's name, doctor, department from the context.
+- type must be one of: upsell, crosssell, retention, operational
+- priority must be one of: high, medium, low
+- On the first response (patient summary), always include suggestions from the rules.
+- On subsequent responses, update suggestions based on conversation — remove acted-on ones, add new if relevant.
+- If no suggestion rules are provided, return an empty suggestions array.
+- Do NOT repeat raw data fields in the message. The summary card already shows name, phone, appointments. Keep the message to insight and context the card doesn't show.
+
 KNOWLEDGE BASE (this is real data from our system):
 {{knowledgeBase}}`;
 

src/rules-engine/suggestion-rules.ts

@@ -0,0 +1,152 @@
+export type SuggestionType = 'upsell' | 'crosssell' | 'retention' | 'operational';
+export type SuggestionPriority = 'high' | 'medium' | 'low';
+
+export type SuggestionTrigger = {
+    type: SuggestionType;
+    title: string;
+    reason: string;
+    priority: SuggestionPriority;
+};
+
+type CallerFacts = {
+    isNew: boolean;
+    interestedService: string | null;
+    leadStatus: string | null;
+    contactAttempts: number;
+    appointments: Array<{ status: string; department: string; doctorName: string; scheduledAt: string }>;
+    calls: Array<{ direction: string; disposition: string | null; startedAt: string }>;
+    utmCampaign: string | null;
+    leadSource: string | null;
+};
+
+const DEPARTMENT_PACKAGES: Record<string, { package: string; description: string }> = {
+    CARDIOLOGY: { package: 'Cardiac Wellness Package', description: 'ECG, stress test, lipid panel' },
+    ORTHOPEDICS: { package: 'Joint Care Package', description: 'X-ray, physiotherapy assessment, bone density' },
+    GENERAL_MEDICINE: { package: 'Full Body Checkup', description: 'Complete health screening with blood work' },
+    NEUROLOGY: { package: 'Neuro Wellness Package', description: 'EEG, nerve conduction, cognitive assessment' },
+    GYNECOLOGY: { package: 'Women\'s Health Package', description: 'Pap smear, mammogram, hormone panel' },
+};
+
+const CROSS_SELL_MAP: Record<string, { department: string; reason: string }> = {
+    ORTHOPEDICS: { department: 'Physiotherapy', reason: 'complement orthopedic treatment' },
+    CARDIOLOGY: { department: 'Dietician', reason: 'dietary guidance for heart health' },
+    GENERAL_MEDICINE: { department: 'Ophthalmology', reason: 'routine eye screening' },
+};
+
+export const evaluateSuggestionRules = (facts: CallerFacts): SuggestionTrigger[] => {
+    const triggers: SuggestionTrigger[] = [];
+
+    // Rule 1: Package upsell by department
+    for (const appt of facts.appointments) {
+        const dept = (appt.department ?? '').toUpperCase().replace(/\s+/g, '_');
+        const pkg = DEPARTMENT_PACKAGES[dept];
+        if (pkg && appt.status === 'SCHEDULED') {
+            triggers.push({
+                type: 'upsell',
+                title: pkg.package,
+                reason: `Patient has ${appt.department} appointment with ${appt.doctorName}, offer ${pkg.description}`,
+                priority: 'high',
+            });
+            break;
+        }
+    }
+
+    // Rule 2: Reschedule missed/cancelled appointments
+    const needsReschedule = facts.appointments.find(a =>
+        a.status === 'CANCELLED' || a.status === 'RESCHEDULED' || a.status === 'NO_SHOW'
+    );
+    if (needsReschedule) {
+        triggers.push({
+            type: 'retention',
+            title: 'Reschedule appointment',
+            reason: `Last ${needsReschedule.department} appointment was ${needsReschedule.status.toLowerCase()}, offer to rebook with ${needsReschedule.doctorName}`,
+            priority: 'medium',
+        });
+    }
+
+    // Rule 3: Cross-sell related department
+    for (const appt of facts.appointments) {
+        const dept = (appt.department ?? '').toUpperCase().replace(/\s+/g, '_');
+        const cross = CROSS_SELL_MAP[dept];
+        if (cross && appt.status === 'SCHEDULED') {
+            triggers.push({
+                type: 'crosssell',
+                title: `${cross.department} consultation`,
+                reason: `${cross.reason} — patient already seeing ${appt.department}`,
+                priority: 'low',
+            });
+            break;
+        }
+    }
+
+    // Rule 4: First-visit patient — health checkup
+    if (facts.isNew || facts.contactAttempts === 0) {
+        triggers.push({
+            type: 'upsell',
+            title: 'Welcome Health Checkup',
+            reason: 'First-time patient, offer introductory health screening package',
+            priority: 'medium',
+        });
+    }
+
+    // Rule 5: Returning patient with no recent appointment
+    if (!facts.isNew && facts.appointments.length === 0 && facts.contactAttempts > 2) {
+        triggers.push({
+            type: 'retention',
+            title: 'Re-engagement',
+            reason: `Returning patient with ${facts.contactAttempts} prior contacts but no active appointments`,
+            priority: 'high',
+        });
+    }
+
+    return triggers.slice(0, 4);
+};
+
+// For display in Settings > Automations (read-only cards)
+export const SUGGESTION_RULE_DEFINITIONS = [
+    {
+        name: 'Package Upsell by Department',
+        category: 'upsell' as const,
+        description: 'Suggest department wellness package when patient has a scheduled appointment.',
+        trigger: 'On call connect',
+        condition: 'Scheduled appointment exists',
+        action: 'Suggest department package',
+        enabled: true,
+    },
+    {
+        name: 'Reschedule Missed Appointment',
+        category: 'retention' as const,
+        description: 'Offer to rebook when patient has a cancelled or rescheduled appointment.',
+        trigger: 'On call connect',
+        condition: 'Cancelled/Rescheduled/No-show appointment exists',
+        action: 'Suggest rebooking',
+        enabled: true,
+    },
+    {
+        name: 'Cross-sell Related Department',
+        category: 'crosssell' as const,
+        description: 'Suggest complementary department service based on current appointment.',
+        trigger: 'On call connect',
+        condition: 'Scheduled appointment in mapped department',
+        action: 'Suggest related service',
+        enabled: true,
+    },
+    {
+        name: 'First Visit Health Checkup',
+        category: 'upsell' as const,
+        description: 'Suggest introductory health screening for first-time patients.',
+        trigger: 'On call connect',
+        condition: 'New patient or zero contact attempts',
+        action: 'Suggest health checkup package',
+        enabled: true,
+    },
+    {
+        name: 'Returning Patient Re-engagement',
+        category: 'retention' as const,
+        description: 'Prompt re-engagement for returning patients with no active appointments.',
+        trigger: 'On call connect',
+        condition: 'Returning patient, no appointments, 3+ contacts',
+        action: 'Suggest booking',
+        enabled: true,
+    },
+];