v2.4: Optimize clinical report — hybrid template + AI insights

- Replace full-prose LLM prompt with short JSON schema prompt (~85% token reduction)
- buildMockReport() generates deterministic template, Nova Pro adds clinical insights
- mergeAiInsights() enriches template with severity, DSM-5 mappings, recommendations
- maxTokens 2048 → 512, fallback preserved if Bedrock fails
- Update all docs: Cohere Command R+ → Nova Pro references

Author: Partha-dev01

app/api/report/clinical/route.ts

@@ -1,9 +1,11 @@
 /**
  * POST /api/report/clinical
  *
- * Generates a full DSM-5 aligned clinical report using Amazon Nova Pro
- * via Amazon Bedrock. Falls back to a detailed mock report when AWS
- * credentials are not configured.
+ * Generates a DSM-5 aligned clinical report using a hybrid approach:
+ * 1. Deterministic template (buildMockReport) generates the full report
+ * 2. Amazon Nova Pro provides structured clinical insights via short JSON prompt
+ * 3. Insights are merged into the template for clinical depth
+ * Falls back to the template-only report when Bedrock is unavailable.
  *
  * Request body:
  *   { sessionId: string, biomarkers: BiomarkerAggregate, childAge?: number }
@@ -44,6 +46,15 @@ interface ClinicalResponse {
   };
 }
 
+interface AiInsights {
+  severityLevel: string;
+  criterionA_interpretation: string;
+  criterionB_interpretation: string;
+  clinicalImpression: string;
+  priorityRecommendations: string[];
+  differentialConsiderations: string;
+}
+
 const BEDROCK_REGION = process.env.BEDROCK_REGION || "us-east-1";
 
 function getBedrockClient(): BedrockRuntimeClient {
@@ -119,34 +130,81 @@ IMPORTANT DISCLAIMER: This report is generated by a computer-assisted screening
   return { report, sections: { criterionA, criterionB, motor, recommendations } };
 }
 
-function parseSections(text: string): ClinicalResponse["sections"] {
-  const sectionPatterns = {
-    criterionA: /(?:CRITERION\s*A|Social\s*Communication)[^\n]*\n([\s\S]*?)(?=(?:CRITERION\s*B|Restricted|MOTOR|={3,})|$)/i,
-    criterionB: /(?:CRITERION\s*B|Restricted\s*&?\s*Repetitive)[^\n]*\n([\s\S]*?)(?=(?:MOTOR|RECOMMENDATION|={3,})|$)/i,
-    motor: /(?:MOTOR)[^\n]*\n([\s\S]*?)(?=(?:RECOMMENDATION|={3,})|$)/i,
-    recommendations: /(?:RECOMMENDATION)[^\n]*\n([\s\S]*?)$/i,
-  };
-
-  const sections: ClinicalResponse["sections"] = {
-    criterionA: "",
-    criterionB: "",
-    motor: "",
-    recommendations: "",
-  };
+function buildInsightsPrompt(
+  biomarkers: BiomarkerAggregate,
+  childAge?: number,
+): string {
+  const age = childAge
+    ? `${Math.floor(childAge / 12)}y${childAge % 12}m`
+    : "unknown";
+  return `Autism screening biomarkers for child (age: ${age}): ${JSON.stringify(biomarkers)}
+
+Return ONLY valid JSON (no markdown, no explanation):
+{"severityLevel":"mild|moderate|significant","criterionA_interpretation":"1-2 sentences mapping gaze/vocalization/face scores to DSM-5 A.1/A.2/A.3","criterionB_interpretation":"1-2 sentences mapping motor/behavior patterns to DSM-5 B.1/B.2/B.4","clinicalImpression":"2-3 sentence overall clinical impression","priorityRecommendations":["2-3 specific recommendations for this child"],"differentialConsiderations":"1 sentence on differential diagnosis considerations"}`;
+}
 
-  for (const [key, pattern] of Object.entries(sectionPatterns)) {
-    const match = text.match(pattern);
-    if (match) {
-      sections[key as keyof typeof sections] = match[1].trim();
-    }
+function parseInsights(text: string): AiInsights | null {
+  try {
+    // Try to extract JSON from the response (handle possible markdown wrapping)
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) return null;
+    const parsed = JSON.parse(jsonMatch[0]);
+    if (!parsed.severityLevel || !parsed.clinicalImpression) return null;
+    return parsed as AiInsights;
+  } catch {
+    return null;
   }
+}
 
-  // If parsing failed, put everything in criterionA
-  if (!sections.criterionA && !sections.criterionB) {
-    sections.criterionA = text;
-  }
+function mergeAiInsights(
+  base: ClinicalResponse,
+  insights: AiInsights,
+): ClinicalResponse {
+  const { criterionA, criterionB, motor, recommendations } = base.sections;
+
+  // Enrich Criterion A with AI interpretation
+  const enrichedA = criterionA.replace(
+    /Social Communication Flag:/,
+    `\nClinical Interpretation:\n${insights.criterionA_interpretation}\n\nSocial Communication Flag:`,
+  );
+
+  // Enrich Criterion B with AI interpretation
+  const enrichedB = criterionB.replace(
+    /Restricted Behavior Flag:/,
+    `\nClinical Interpretation:\n${insights.criterionB_interpretation}\n\nRestricted Behavior Flag:`,
+  );
+
+  // Enrich Recommendations with clinical impression and specific recommendations
+  const severityLine = `Clinical Severity Assessment: ${insights.severityLevel.toUpperCase()}\n\n`;
+  const impressionBlock = `Clinical Impression:\n${insights.clinicalImpression}\n\n`;
+  const aiRecs = insights.priorityRecommendations
+    .map((r, i) => `${i + 1}. ${r}`)
+    .join("\n");
+  const differential = `\nDifferential Considerations:\n${insights.differentialConsiderations}`;
+
+  const enrichedRecs = recommendations.replace(
+    /Based on this screening:/,
+    `${severityLine}${impressionBlock}Based on this screening:`,
+  ).replace(
+    /IMPORTANT DISCLAIMER:/,
+    `${aiRecs ? `\nPriority Recommendations:\n${aiRecs}\n\n` : ""}${differential}\n\nIMPORTANT DISCLAIMER:`,
+  );
+
+  const sections = {
+    criterionA: enrichedA,
+    criterionB: enrichedB,
+    motor,
+    recommendations: enrichedRecs,
+  };
 
-  return sections;
+  const report = [
+    sections.criterionA,
+    sections.criterionB,
+    sections.motor,
+    sections.recommendations,
+  ].join("\n\n---\n\n");
+
+  return { report, sections };
 }
 
 export async function POST(req: NextRequest) {
@@ -170,43 +228,15 @@ export async function POST(req: NextRequest) {
 
   const { biomarkers, childAge } = body;
 
-  const ageContext = childAge
-    ? `The child is ${Math.floor(childAge / 12)} years and ${childAge % 12} months old.`
-    : "The child's age was not specified.";
-
-  const prompt = `You are a clinical report generator for an autism screening platform. Generate a comprehensive DSM-5 aligned clinical screening report based on the following biomarker data.
-
-${ageContext}
-
-Biomarker Data:
-${JSON.stringify(biomarkers, null, 2)}
-
-Structure the report with these EXACT section headers:
-
-CRITERION A -- SOCIAL COMMUNICATION & INTERACTION
-Analyze social gaze patterns (avgGazeScore), vocalization quality (avgVocalizationScore), facial affect (dominantFaceBehavior if available), and their mapping to DSM-5 Criterion A sub-criteria (A.1 social-emotional reciprocity, A.2 nonverbal communication, A.3 relationships).
-
-CRITERION B -- RESTRICTED & REPETITIVE BEHAVIOURS
-Analyze motor patterns (avgMotorScore), response latency, body behavior classification (dominantBodyBehavior, behaviorClassDistribution if available), and mapping to DSM-5 Criterion B sub-criteria (B.1 stereotyped movements, B.2 insistence on sameness, B.3 restricted interests, B.4 sensory reactivity).
-
-MOTOR DEVELOPMENT ASSESSMENT
-Provide a focused motor development analysis based on the motor score and any detected body behavior patterns. Note co-occurring motor differences common in ASD.
-
-RECOMMENDATIONS
-Provide actionable next steps based on the screening results: referral recommendations, suggested interventions, monitoring frequency. Include a disclaimer that this is a screening tool, not a diagnostic instrument.
-
-Guidelines:
-- Use clinical but accessible language
-- Reference specific DSM-5 criteria codes where appropriate
-- Include specific scores and thresholds in your analysis
-- Be factual and evidence-based, avoid speculation
-- End with a clear disclaimer about the screening nature of this tool`;
+  // Always generate the deterministic template first
+  const baseReport = buildMockReport(biomarkers, childAge);
 
   try {
     const client = getBedrockClient();
+    const prompt = buildInsightsPrompt(biomarkers, childAge);
     const invokeBody = JSON.stringify({
       messages: [{ role: "user", content: [{ text: prompt }] }],
-      inferenceConfig: { maxTokens: 2048, temperature: 0.5 },
+      inferenceConfig: { maxTokens: 512, temperature: 0.5 },
     });
 
     const command = new InvokeModelCommand({
@@ -219,24 +249,18 @@ Guidelines:
     const response = await client.send(command);
     const responseBody = JSON.parse(new TextDecoder().decode(response.body));
 
-    // Nova Pro returns: { output: { message: { content: [{ text: "..." }] } } }
-    const reportText: string =
+    const text: string =
       responseBody?.output?.message?.content?.[0]?.text ?? "";
 
-    if (!reportText) {
-      console.warn("[Report/Clinical] Empty response from Bedrock, using mock");
-      return NextResponse.json(buildMockReport(biomarkers, childAge));
+    const insights = parseInsights(text);
+    if (!insights) {
+      console.warn("[Report/Clinical] Could not parse AI insights, using template only");
+      return NextResponse.json(baseReport);
     }
 
-    const sections = parseSections(reportText);
-
-    return NextResponse.json({
-      report: reportText,
-      sections,
-    });
+    return NextResponse.json(mergeAiInsights(baseReport, insights));
   } catch (err) {
     console.error("[Report/Clinical] Bedrock invocation failed:", err);
-    // Graceful degradation: return mock report on error
-    return NextResponse.json(buildMockReport(biomarkers, childAge));
+    return NextResponse.json(baseReport);
   }
 }

docs/Amazon_usage.md

@@ -7,7 +7,7 @@
 | Amazon Bedrock (Nova Lite) | `amazon.nova-lite-v1:0` | app/api/chat/conversation/route.ts | Used (fallback when quota=0) |
 | Amazon Bedrock (Nova Lite) | `amazon.nova-lite-v1:0` | app/api/chat/generate-words/route.ts | Used (fallback when quota=0) |
 | Amazon Bedrock (Nova Lite) | `amazon.nova-lite-v1:0` | app/api/report/summary/route.ts | Used (fallback when quota=0) |
-| Amazon Bedrock (Command R+) | `cohere.command-r-plus-v1:0` | app/api/report/clinical/route.ts | Used (fallback when quota=0) |
+| Amazon Bedrock (Nova Pro) | `amazon.nova-pro-v1:0` | app/api/report/clinical/route.ts | Active (hybrid template + AI insights) |
 | Amazon Polly | Neural TTS (Joanna) | app/api/tts/route.ts | Active, working |
 | ONNX Runtime (on-device) | 4 models in `public/models/` | app/lib/inference/ (13 files), workers/inference.worker.ts | Active, working |
 
@@ -36,6 +36,6 @@
 1. **AI voice conversation with child** (Step 7 screening + kid chat) — app/api/chat/conversation/route.ts — Nova Lite generates adaptive multi-turn questions across social/cognitive/language/motor domains
 2. **Dynamic word/sentence generation** (speech stages) — app/api/chat/generate-words/route.ts — Nova Lite generates age-appropriate vocabulary
 3. **Parent-friendly summary** (end of screening) — app/api/report/summary/route.ts — Nova Lite translates biomarker scores to plain language
-4. **DSM-5 clinical report** (end of screening) — app/api/report/clinical/route.ts — Command R+ generates full Criterion A/B/Motor/Recommendations report
+4. **DSM-5 clinical report** (end of screening) — app/api/report/clinical/route.ts — Nova Pro returns structured JSON insights merged with deterministic template (hybrid approach, ~85% fewer tokens)
 
 All 4 Bedrock routes have comprehensive mock fallbacks, so the app is fully functional even with your current quota=0 situation. The on-device ONNX inference (the core screening AI) needs zero cloud — it runs entirely in the browser.

docs/DOCS.md

@@ -30,7 +30,7 @@
 AutiSense is a Next.js 16 web application that provides AI-powered autism screening for children. It combines:
 
 - **Edge AI** — Real-time ONNX inference (YOLO pose detection + TCN behavior classification + FER+ emotion analysis) running entirely in the browser via Web Workers
-- **Generative AI** — Amazon Bedrock (Nova Lite + Cohere Command R+) for generating DSM-5 aligned clinical reports from biomarker data
+- **Generative AI** — Amazon Bedrock (Nova Lite + Nova Pro) for generating DSM-5 aligned clinical reports from biomarker data
 - **Offline-first data** — IndexedDB (Dexie.js) for local storage with DynamoDB sync when online
 - **Adaptive therapy** — 7 post-diagnosis games with dynamic difficulty adjustment
 
@@ -59,7 +59,7 @@ Browser (Client)
 Server (Amplify SSR / Lambda)
 ├── POST /api/chat/conversation → Amazon Bedrock Nova Lite (voice agent)
 ├── POST /api/report/summary    → Amazon Bedrock Nova Lite
-├── POST /api/report/clinical   → Amazon Bedrock Cohere Command R+
+├── POST /api/report/clinical   → Amazon Bedrock Nova Pro (hybrid template + AI insights)
 ├── POST /api/report/pdf        → pdf-lib PDF generation
 ├── POST /api/tts               → Amazon Polly
 ├── GET/POST /api/auth/*        → Google OAuth + DynamoDB sessions
@@ -132,7 +132,7 @@ AutiSense_2/
 │   │   ├── nearby/route.ts             — Overpass API proxy for nearby institutes
 │   │   ├── report/
 │   │   │   ├── summary/route.ts        — Bedrock Nova Lite session summary
-│   │   │   ├── clinical/route.ts       — Bedrock Command R+ clinical report
+│   │   │   ├── clinical/route.ts       — Bedrock Nova Pro clinical report
 │   │   │   ├── pdf/route.ts            — PDF generation via pdf-lib
 │   │   │   └── weekly/route.ts         — Weekly progress report generation
 │   │   ├── sync/route.ts               — Upload session + biomarkers to DynamoDB
@@ -312,7 +312,7 @@ AutiSense_2/
 | S3 bucket + ONNX models | Deployed | 4 models, ~47MB total |
 | IAM policies (3) | Created | Bedrock, Polly, DynamoDB+S3 |
 | IAM user + Amplify role | Created | For local dev + production |
-| Bedrock model access | Auto-enabled | Nova Lite + Command R+ |
+| Bedrock model access | Auto-enabled | Nova Lite + Nova Pro |
 | Budget alarm ($10/mo) | Active | Email alerts at 80% and 100% |
 | Amplify hosting | Live | Auto-deploy from GitHub main |
 
@@ -374,7 +374,7 @@ All inference runs client-side in a Web Worker via ONNX Runtime Web (WebGPU or W
 | Service | Usage | API Endpoint |
 |---------|-------|-------------|
 | **Bedrock** (Nova Lite) | Parent-friendly session summaries | `POST /api/report/summary` |
-| **Bedrock** (Command R+) | DSM-5 aligned clinical reports | `POST /api/report/clinical` |
+| **Bedrock** (Nova Pro) | DSM-5 aligned clinical reports | `POST /api/report/clinical` |
 | **Polly** | Neural TTS voice prompts (Joanna) | `POST /api/tts` |
 | **DynamoDB** | User accounts, auth sessions, biomarkers, child profiles, feed posts | Via AWS SDK v3 |
 | **S3** | ONNX model file hosting (presigned URLs) | Via `@aws-sdk/s3-request-presigner` |
@@ -463,7 +463,7 @@ Difficulty engine (`app/lib/games/difficultyEngine.ts`) auto-adjusts based on re
 | POST | `/api/auth/logout` | Public | Delete session |
 | POST | `/api/chat/conversation` | Public | Dynamic voice agent conversation via Bedrock Nova Lite |
 | POST | `/api/report/summary` | Public | Generate summary via Bedrock Nova Lite |
-| POST | `/api/report/clinical` | Public | Generate clinical report via Bedrock Command R+ |
+| POST | `/api/report/clinical` | Public | Generate clinical report via Bedrock Nova Pro |
 | POST | `/api/report/pdf` | Public | Generate downloadable PDF |
 | POST | `/api/tts` | Public | Text-to-speech via Amazon Polly |
 | POST | `/api/chat/generate-words` | Public | Generate age-appropriate words/sentences via Bedrock |
@@ -547,7 +547,7 @@ npx playwright test    # Run all 30 tests
 
 ### Phase 3 — Bedrock Reports (Complete)
 - [x] Summary API (Nova Lite) with mock fallback
-- [x] Clinical API (Command R+) with DSM-5 section extraction
+- [x] Clinical API (Nova Pro) with DSM-5 section extraction
 - [x] PDF generation with pdf-lib
 - [x] Amazon Polly TTS API
 - [x] Report page with dual report types + PDF download
@@ -629,7 +629,7 @@ npx playwright test    # Run all 30 tests
 **Added:**
 - Complete 12-step autism screening intake flow
 - Real-time ONNX behavioral video analysis (YOLO + TCN + FER+)
-- Amazon Bedrock AI report generation (Nova Lite summaries + Command R+ clinical reports)
+- Amazon Bedrock AI report generation (Nova Lite summaries + Nova Pro clinical reports)
 - PDF report download with scores and clinical text
 - Amazon Polly text-to-speech for child-facing prompts
 - Google OAuth 2.0 authentication with DynamoDB sessions
@@ -1005,6 +1005,24 @@ A complete kids-facing dashboard with bottom tab navigation, daily games, AI cha
 **Files modified:** 11 files across components, games, pages, DB layer, and types.
 **Testing:** TypeScript clean. ESLint clean. Build clean.
 
+### v2.4.0 — 2026-03-06 (Bedrock Optimization — Hybrid Clinical Reports)
+
+**Clinical Report Optimization:**
+- Replaced full-prose LLM prompt with hybrid template + AI insights approach
+- Deterministic template (`buildMockReport`) generates the complete report with scores, thresholds, flags, and disclaimers
+- Nova Pro now returns only a small structured JSON with clinical interpretations (severity level, DSM-5 criterion mappings, clinical impression, priority recommendations, differential considerations)
+- `mergeAiInsights()` enriches the template sections with AI clinical depth
+- ~85% token reduction per clinical report (~400 tokens vs ~2700 previously)
+- `maxTokens` reduced from 2048 to 512
+- Fallback preserved: if Bedrock fails or JSON unparseable, returns template-only report
+
+**Bedrock Model Updates:**
+- Replaced Cohere Command R+ with Amazon Nova Pro for clinical reports (v2.3.0)
+- Fixed `maxNewTokens` → `maxTokens` in generate-words route (v2.3.0)
+- Updated all documentation references from Cohere to Nova Pro
+
+**Files modified:** `app/api/report/clinical/route.ts`, `docs/DOCS.md`, `docs/SETUP_GUIDE.md`, `docs/Amazon_usage.md`
+
 ### v2.2.0 — 2026-03-06 (Game Staging, Nav Fix, Dark Mode, Feed Toggle)
 
 **Navigation & Layout (Phase 1):**

docs/SETUP_GUIDE.md

@@ -22,7 +22,7 @@
 |---------|----------|--------|
 | DynamoDB | 7 tables (`autisense-*`) | ap-south-1 |
 | S3 | `autisense-models-762099405044` (4 ONNX models) | ap-south-1 |
-| Bedrock | Nova Lite + Command R+ | us-east-1 |
+| Bedrock | Nova Lite + Nova Pro | us-east-1 |
 | Polly | Joanna (Neural voice) | ap-south-1 |
 | Amplify | WEB_COMPUTE (Next.js SSR) | ap-south-1 |
 | IAM | `autisense-app` user + `AutiSenseAmplifyRole` | Global |