justlabs-mcp-server 1.0.0 → 1.1.0

package/src/analysis/analyzePanelResults.ts

@@ -0,0 +1,205 @@
+/**
+ * Analyze panel results - educational context only, no diagnostic language
+ */
+
+import {
+  getReferenceRange,
+  getApplicableRange,
+  classifyValue,
+  checkCriticalValue,
+  formatReferenceRange,
+  BiomarkerRange,
+} from "../ranges/questRanges.js";
+import { getPanel, PanelDefinition } from "../ranges/panels.js";
+
+export interface ResultInput {
+  biomarker_key: string;
+  value: number;
+  unit: string;
+}
+
+export interface AnalysisInput {
+  panel_id: string;
+  results: ResultInput[];
+  sex_at_birth?: "male" | "female";
+  age?: number;
+  fasting?: boolean;
+  on_thyroid_meds?: boolean;
+}
+
+export interface Finding {
+  biomarker_key: string;
+  display_name: string;
+  value: number;
+  unit: string;
+  status: "low" | "high" | "normal" | "unknown";
+  reference_range: string;
+  educational_context: string;
+  note?: string;
+}
+
+export interface AnalysisOutput {
+  panel_id: string;
+  panel_name: string;
+  summary: {
+    overall_status: "all_normal" | "some_outside_range" | "needs_attention" | "critical";
+    headline: string;
+  };
+  key_findings: Finding[];
+  reassuring_findings: string[];
+  missing_required_markers: string[];
+  red_flags_detected: boolean;
+  red_flag_message: string | null;
+  disclaimer_acknowledged: boolean;
+}
+
+/**
+ * Analyze panel results with educational context
+ * Returns structured findings without diagnostic language
+ */
+export function analyzePanelResults(input: AnalysisInput): AnalysisOutput {
+  const panel = getPanel(input.panel_id);
+
+  if (!panel) {
+    return {
+      panel_id: input.panel_id,
+      panel_name: "Unknown Panel",
+      summary: {
+        overall_status: "needs_attention",
+        headline: "Unable to analyze: panel not found",
+      },
+      key_findings: [],
+      reassuring_findings: [],
+      missing_required_markers: [],
+      red_flags_detected: false,
+      red_flag_message: null,
+      disclaimer_acknowledged: false,
+    };
+  }
+
+  // Check for critical values first
+  const criticalFindings: { key: string; message: string }[] = [];
+  for (const result of input.results) {
+    const critical = checkCriticalValue(result.biomarker_key, result.value);
+    if (critical.isCritical && critical.message) {
+      criticalFindings.push({
+        key: result.biomarker_key,
+        message: critical.message,
+      });
+    }
+  }
+
+  if (criticalFindings.length > 0) {
+    return {
+      panel_id: input.panel_id,
+      panel_name: panel.name,
+      summary: {
+        overall_status: "critical",
+        headline: "Important: Please contact a healthcare provider promptly",
+      },
+      key_findings: [],
+      reassuring_findings: [],
+      missing_required_markers: [],
+      red_flags_detected: true,
+      red_flag_message: `One or more values require prompt medical attention. ${criticalFindings.map((f) => f.message).join(" ")} Please contact your healthcare provider or seek medical care.`,
+      disclaimer_acknowledged: false,
+    };
+  }
+
+  // Check for missing required markers
+  const providedKeys = input.results.map((r) => r.biomarker_key.toLowerCase());
+  const missingMarkers = panel.requiredMarkers.filter(
+    (m) => !providedKeys.includes(m.toLowerCase())
+  );
+
+  // Analyze each result
+  const keyFindings: Finding[] = [];
+  const reassuringFindings: string[] = [];
+
+  for (const result of input.results) {
+    const biomarkerRange = getReferenceRange(result.biomarker_key);
+
+    if (!biomarkerRange) {
+      keyFindings.push({
+        biomarker_key: result.biomarker_key,
+        display_name: result.biomarker_key,
+        value: result.value,
+        unit: result.unit,
+        status: "unknown",
+        reference_range: "Not available",
+        educational_context: "Reference range not available for this marker.",
+      });
+      continue;
+    }
+
+    const applicableRange = getApplicableRange(biomarkerRange, input.sex_at_birth);
+    const status = classifyValue(result.value, applicableRange);
+    const referenceRangeStr = formatReferenceRange(applicableRange);
+
+    // Build educational context based on status
+    let educationalContext = biomarkerRange.educationalContext;
+    let note: string | undefined;
+
+    if (status === "low" && biomarkerRange.lowContext) {
+      educationalContext = biomarkerRange.lowContext;
+    } else if (status === "high" && biomarkerRange.highContext) {
+      educationalContext = biomarkerRange.highContext;
+    }
+
+    // Add medication notes if relevant
+    if (input.on_thyroid_meds && ["tsh", "free-t4", "free-t3"].includes(result.biomarker_key.toLowerCase())) {
+      note = "Note: Thyroid medication can affect these values. Results are best interpreted by your prescribing clinician.";
+    }
+
+    // Add fasting note if relevant
+    if (!input.fasting && ["glucose", "insulin", "triglycerides"].includes(result.biomarker_key.toLowerCase())) {
+      note = "Note: This marker is ideally measured after fasting. Non-fasting values may be higher.";
+    }
+
+    const finding: Finding = {
+      biomarker_key: result.biomarker_key,
+      display_name: biomarkerRange.displayName,
+      value: result.value,
+      unit: result.unit,
+      status,
+      reference_range: referenceRangeStr,
+      educational_context: educationalContext,
+      note,
+    };
+
+    if (status === "normal") {
+      reassuringFindings.push(`${biomarkerRange.displayName} is within the expected range.`);
+    } else {
+      keyFindings.push(finding);
+    }
+  }
+
+  // Determine overall status
+  let overallStatus: "all_normal" | "some_outside_range" | "needs_attention" = "all_normal";
+  let headline = "Your results are within expected ranges.";
+
+  if (keyFindings.length > 0) {
+    overallStatus = "some_outside_range";
+    const outsideRangeCount = keyFindings.filter((f) => f.status !== "unknown").length;
+    headline = `${outsideRangeCount} marker${outsideRangeCount !== 1 ? "s" : ""} outside the typical range. See details below.`;
+  }
+
+  if (missingMarkers.length > 0) {
+    headline += ` Note: ${missingMarkers.length} expected marker${missingMarkers.length !== 1 ? "s" : ""} not provided.`;
+  }
+
+  return {
+    panel_id: input.panel_id,
+    panel_name: panel.name,
+    summary: {
+      overall_status: overallStatus,
+      headline,
+    },
+    key_findings: keyFindings,
+    reassuring_findings: reassuringFindings,
+    missing_required_markers: missingMarkers,
+    red_flags_detected: false,
+    red_flag_message: null,
+    disclaimer_acknowledged: false,
+  };
+}

package/src/analysis/generatePatientSummary.ts

@@ -0,0 +1,131 @@
+/**
+ * Generate patient-friendly summary with required disclaimer
+ */
+
+import { AnalysisOutput } from "./analyzePanelResults.js";
+import { NextStepsOutput } from "./suggestNextSteps.js";
+
+export interface PatientSummaryCTA {
+  label: string;
+  url: string;
+}
+
+export interface PatientSummary {
+  headline: string;
+  bullets: string[];
+  cta: PatientSummaryCTA | null;
+  disclaimer: string;
+  requires_acknowledgment: boolean;
+}
+
+export interface PatientSummaryOutput {
+  patient_summary: PatientSummary;
+  safety_warning: string | null;
+}
+
+const DISCLAIMER = `This summary is for educational purposes only and is not medical advice. Reference ranges may vary by lab and individual factors. Always discuss your results with a qualified healthcare provider before making any health decisions.`;
+
+const SAFETY_DISCLAIMER = `IMPORTANT: One or more of your results requires prompt medical attention. Please contact your healthcare provider or seek medical care before reviewing this summary further.`;
+
+/**
+ * Generate a patient-friendly summary
+ * Requires disclaimer acknowledgment before showing analysis
+ */
+export function generatePatientSummary(
+  panelId: string,
+  analysis: AnalysisOutput,
+  nextSteps: NextStepsOutput
+): PatientSummaryOutput {
+  // Safety check first
+  if (analysis.red_flags_detected || nextSteps.safety.red_flags_detected) {
+    return {
+      patient_summary: {
+        headline: "Please contact a healthcare provider",
+        bullets: [
+          "One or more values in your results need prompt medical review.",
+          "Do not delay seeking care based on this summary.",
+          "Your healthcare provider can evaluate these findings properly.",
+        ],
+        cta: null,
+        disclaimer: DISCLAIMER,
+        requires_acknowledgment: true,
+      },
+      safety_warning: nextSteps.safety.message || SAFETY_DISCLAIMER,
+    };
+  }
+
+  // Build summary based on analysis and next steps
+  const bullets: string[] = [];
+
+  // Add headline context
+  if (analysis.summary.overall_status === "all_normal") {
+    bullets.push("All markers reviewed are within expected ranges.");
+  } else if (analysis.key_findings.length > 0) {
+    bullets.push(`${analysis.key_findings.length} marker${analysis.key_findings.length !== 1 ? "s" : ""} outside the typical range.`);
+  }
+
+  // Add key findings (max 2)
+  const significantFindings = analysis.key_findings
+    .filter((f) => f.status === "low" || f.status === "high")
+    .slice(0, 2);
+
+  for (const finding of significantFindings) {
+    const direction = finding.status === "low" ? "below" : "above";
+    bullets.push(
+      `${finding.display_name}: ${finding.value} ${finding.unit} (${direction} typical range of ${finding.reference_range})`
+    );
+  }
+
+  // Add reassuring note if some things are normal
+  if (analysis.reassuring_findings.length > 0 && analysis.key_findings.length > 0) {
+    bullets.push(`${analysis.reassuring_findings.length} other marker${analysis.reassuring_findings.length !== 1 ? "s" : ""} within expected ranges.`);
+  }
+
+  // Add next step guidance
+  if (nextSteps.next_step.type === "additional_testing") {
+    bullets.push(`For more detail, consider: ${nextSteps.next_step.recommended_panel_name}`);
+  } else if (nextSteps.next_step.type === "clinician_discussion") {
+    bullets.push("Consider discussing these results with your healthcare provider.");
+  }
+
+  // Ensure we have 3-5 bullets
+  if (bullets.length < 3) {
+    bullets.push("These results provide a snapshot of selected health markers.");
+  }
+  if (bullets.length < 3) {
+    bullets.push("A healthcare provider can help put these in context with your overall health.");
+  }
+
+  // Cap at 5 bullets
+  const finalBullets = bullets.slice(0, 5);
+
+  // Build CTA only for additional testing
+  let cta: PatientSummaryCTA | null = null;
+  if (nextSteps.next_step.type === "additional_testing") {
+    cta = {
+      label: `Learn more: ${nextSteps.next_step.recommended_panel_name} ($${nextSteps.next_step.price})`,
+      url: nextSteps.next_step.order_url,
+    };
+  }
+
+  // Build headline
+  let headline: string;
+  if (analysis.summary.overall_status === "all_normal") {
+    headline = "Your results are within expected ranges";
+  } else if (analysis.key_findings.length === 1) {
+    headline = "One marker to note in your results";
+  } else {
+    headline = "A few markers to review in your results";
+  }
+
+  return {
+    patient_summary: {
+      headline,
+      bullets: finalBullets,
+      cta,
+      disclaimer: DISCLAIMER,
+      requires_acknowledgment: true,
+    },
+    safety_warning: null,
+  };
+}

package/src/analysis/suggestNextSteps.ts

@@ -0,0 +1,183 @@
+/**
+ * Suggest next steps based on panel analysis
+ * Returns at most ONE follow-up panel, framed as "more detail" not diagnosis
+ */
+
+import { AnalysisOutput } from "./analyzePanelResults.js";
+import { getPanel, getFollowUpRules } from "../ranges/panels.js";
+
+export interface NextStepAdditionalTesting {
+  type: "additional_testing";
+  recommended_panel_id: string;
+  recommended_panel_name: string;
+  reason: string;
+  confidence: "suggested" | "may_be_helpful";
+  order_url: string;
+  price: number;
+}
+
+export interface NextStepNoTesting {
+  type: "no_additional_testing";
+  reason: string;
+}
+
+export interface NextStepClinicianDiscussion {
+  type: "clinician_discussion";
+  reason: string;
+}
+
+export type NextStep = NextStepAdditionalTesting | NextStepNoTesting | NextStepClinicianDiscussion;
+
+export interface NextStepsOutput {
+  next_step: NextStep;
+  not_recommended: string[];
+  safety: {
+    red_flags_detected: boolean;
+    message: string | null;
+  };
+  clinician_guidance: string;
+}
+
+/**
+ * Suggest next steps based on analysis
+ * Conservative approach: one follow-up max, educational framing
+ */
+export function suggestNextSteps(
+  panelId: string,
+  analysis: AnalysisOutput
+): NextStepsOutput {
+  // If red flags detected, always recommend clinician
+  if (analysis.red_flags_detected) {
+    return {
+      next_step: {
+        type: "clinician_discussion",
+        reason: "Based on your results, we recommend speaking with a healthcare provider before any additional testing.",
+      },
+      not_recommended: ["Additional testing through JustLabs at this time"],
+      safety: {
+        red_flags_detected: true,
+        message: analysis.red_flag_message,
+      },
+      clinician_guidance: "Please contact your healthcare provider or seek medical attention promptly.",
+    };
+  }
+
+  const rules = getFollowUpRules(panelId);
+
+  // Default response if no rules defined
+  if (!rules) {
+    return {
+      next_step: {
+        type: "clinician_discussion",
+        reason: "Consider discussing these results with a healthcare provider who can provide personalized guidance.",
+      },
+      not_recommended: [],
+      safety: {
+        red_flags_detected: false,
+        message: null,
+      },
+      clinician_guidance: "A healthcare provider can help interpret these results in the context of your overall health.",
+    };
+  }
+
+  // Get markers that are outside range
+  const abnormalMarkerKeys = analysis.key_findings
+    .filter((f) => f.status === "low" || f.status === "high")
+    .map((f) => f.biomarker_key.toLowerCase());
+
+  // Check each condition in order (first match wins)
+  for (const condition of rules.conditions) {
+    if (!condition.abnormalMarkers) continue;
+
+    const matchesCondition = condition.abnormalMarkers.some((marker) =>
+      abnormalMarkerKeys.includes(marker.toLowerCase())
+    );
+
+    if (matchesCondition) {
+      // If followUpPanelId is empty, suggest clinician discussion
+      if (!condition.followUpPanelId) {
+        return {
+          next_step: {
+            type: "clinician_discussion",
+            reason: condition.reason,
+          },
+          not_recommended: ["Repeating the same panel within 4-6 weeks"],
+          safety: {
+            red_flags_detected: false,
+            message: null,
+          },
+          clinician_guidance: "A healthcare provider can help determine the best next steps based on your complete health picture.",
+        };
+      }
+
+      const followUpPanel = getPanel(condition.followUpPanelId);
+      if (followUpPanel) {
+        return {
+          next_step: {
+            type: "additional_testing",
+            recommended_panel_id: followUpPanel.id,
+            recommended_panel_name: followUpPanel.name,
+            reason: condition.reason,
+            confidence: "may_be_helpful",
+            order_url: followUpPanel.url,
+            price: followUpPanel.price,
+          },
+          not_recommended: [
+            "Repeating the same panel within 4-6 weeks",
+            "Multiple additional panels at once",
+          ],
+          safety: {
+            red_flags_detected: false,
+            message: null,
+          },
+          clinician_guidance: "While additional testing may provide more detail, a healthcare provider can help you decide if it's right for you.",
+        };
+      }
+    }
+  }
+
+  // No conditions matched, use default
+  if (rules.defaultFollowUp) {
+    if (rules.defaultFollowUp.type === "no_additional_testing") {
+      return {
+        next_step: {
+          type: "no_additional_testing",
+          reason: rules.defaultFollowUp.reason,
+        },
+        not_recommended: ["Unnecessary repeat testing"],
+        safety: {
+          red_flags_detected: false,
+          message: null,
+        },
+        clinician_guidance: "Your results look reassuring. Consider sharing them with your healthcare provider at your next visit.",
+      };
+    } else {
+      return {
+        next_step: {
+          type: "clinician_discussion",
+          reason: rules.defaultFollowUp.reason,
+        },
+        not_recommended: [],
+        safety: {
+          red_flags_detected: false,
+          message: null,
+        },
+        clinician_guidance: "A healthcare provider can help interpret these results and suggest appropriate next steps.",
+      };
+    }
+  }
+
+  // Fallback
+  return {
+    next_step: {
+      type: "clinician_discussion",
+      reason: "Consider discussing these results with a healthcare provider.",
+    },
+    not_recommended: [],
+    safety: {
+      red_flags_detected: false,
+      message: null,
+    },
+    clinician_guidance: "A healthcare provider can provide personalized guidance based on your complete health picture.",
+  };
+}