@peopl-health/nexus 5.10.0-dev.1037 → 5.10.0-dev.1040

package/lib/clinical/config/subAgentsConfig.js

@@ -10,6 +10,7 @@ const CACHE_TTL = 5 * 60 * 1000;
 const CACHE_KEY = 'subAgentsConfig';
 const EXTRACTOR_DEFAULTS = { presetId: '' };
 const COMPOSER_DEFAULTS = { presetId: '' };
+const PATTERN_CONSULT_DEFAULTS = { presetId: '' };
 
 const cache = new MapCache({ maxSize: 1, ttl: CACHE_TTL });
 
@@ -29,7 +30,11 @@ async function load() {
   if (byKey.COMPOSER && !isPlainObject(parsedComposer)) throw new Error('subAgents config COMPOSER is not a JSON object');
   const composer = { ...COMPOSER_DEFAULTS, ...(parsedComposer || {}) };
 
-  const config = { EXTRACTOR: extractor, COMPOSER: composer };
+  const parsedPatternConsult = safeParse(byKey.PATTERN_CONSULT, null);
+  if (byKey.PATTERN_CONSULT && !isPlainObject(parsedPatternConsult)) throw new Error('subAgents config PATTERN_CONSULT is not a JSON object');
+  const patternConsult = { ...PATTERN_CONSULT_DEFAULTS, ...(parsedPatternConsult || {}) };
+
+  const config = { EXTRACTOR: extractor, COMPOSER: composer, PATTERN_CONSULT: patternConsult };
   cache.set(CACHE_KEY, config);
   return config;
 }
@@ -41,4 +46,5 @@ async function get(key) {
 module.exports = {
   getExtractor: () => get('EXTRACTOR'),
   getComposer: () => get('COMPOSER'),
+  getPatternConsult: () => get('PATTERN_CONSULT'),
 };

package/lib/clinical/models/patternConsultModel.js

@@ -0,0 +1,37 @@
+const mongoose = require('mongoose');
+
+const { clinicalConnection } = require('../config/connection');
+
+const patternConsultSchema = new mongoose.Schema({
+  consultationId: { type: String, required: true },
+  patientCode: { type: String, required: true },
+  turnId: { type: String, default: null },
+  concern: { type: String, default: null },
+  impressions: { type: Array, default: [] },
+  recommendedProbes: { type: [String], default: [] },
+  watchFor: { type: [String], default: [] },
+  escalationAdvice: { type: Object, default: null },
+  degraded: { type: Boolean, default: false },
+  degradedReasons: { type: [String], default: [] },
+}, { timestamps: true });
+
+patternConsultSchema.index({ consultationId: 1 }, { unique: true });
+patternConsultSchema.index({ patientCode: 1, createdAt: -1 });
+
+function patternConsultStore() {
+  const conn = clinicalConnection();
+  const model = conn.models.PatternConsult || conn.model('PatternConsult', patternConsultSchema, 'patternConsult');
+
+  return {
+    get(consultationId) {
+      return model.findOne({ consultationId }).lean();
+    },
+    put(doc) {
+      return model.create(doc);
+    },
+  };
+}
+
+module.exports = {
+  patternConsultStore,
+};

package/lib/clinical/services/patternConsultService.js

@@ -0,0 +1,115 @@
+const crypto = require('node:crypto');
+
+const { getPatternConsult } = require('../config/subAgentsConfig');
+const { patternConsultStore } = require('../models/patternConsultModel');
+const { readOutputText } = require('../helpers/clinicalMentionHelper');
+const { assembleLandscape } = require('../tools/getActiveSymptomLandscapeTool');
+const { safeParse } = require('../../utils/jsonUtils');
+const { logger } = require('../../utils/logger');
+
+const PLAUSIBILITY = new Set(['low', 'moderate', 'high']);
+
+function asStringArray(value) {
+  return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+
+function shapeImpressions(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter((item) => item && typeof item === 'object')
+    .map((item) => ({
+      label: typeof item.label === 'string' ? item.label : '',
+      plausibility: PLAUSIBILITY.has(item.plausibility) ? item.plausibility : 'low',
+      supporting: asStringArray(item.supporting),
+      against: asStringArray(item.against),
+      missing_discriminators: asStringArray(item.missing_discriminators),
+    }));
+}
+
+function shapeEscalation(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  return {
+    indicated_now: raw.indicated_now === true,
+    if_then: typeof raw.if_then === 'string' ? raw.if_then : '',
+  };
+}
+
+function degradedEnvelope(consultationId, degradedReasons) {
+  return { consultationId, impressions: [], recommendedProbes: [], watchFor: [], escalationAdvice: null, degradedReasons, degraded: true };
+}
+
+function buildConsultInput(concern, bundle) {
+  return [
+    `S/B/A/R concern: ${concern}`,
+    `evidence_bundle: ${JSON.stringify(bundle)}`,
+  ].join('\n');
+}
+
+async function persist(store, record) {
+  if (!store) return false;
+  try {
+    await store.put(record);
+    return true;
+  } catch (err) {
+    logger.warn('[patternConsult] persist failed', { turnId: record.turnId, error: err?.message });
+    return false;
+  }
+}
+
+async function requestPatternConsult({ concern, patientId, turnId, provider }) {
+  const consultationId = `pc_${turnId}_${crypto.randomUUID().replace(/-/g, '').slice(0, 8)}`;
+  let store = null;
+
+  try {
+    store = patternConsultStore();
+    const { presetId } = await getPatternConsult();
+    const bundle = await assembleLandscape(patientId);
+
+    if (!bundle.active_cases?.length) {
+      await persist(store, { consultationId, patientCode: patientId, turnId, concern, degraded: true, degradedReasons: ['no_open_cases_to_consult_on'] });
+      return degradedEnvelope(consultationId, ['no_open_cases_to_consult_on']);
+    }
+
+    if (!presetId || !provider?.runStructured) {
+      await persist(store, { consultationId, patientCode: patientId, turnId, concern, degraded: true, degradedReasons: ['consultant_unavailable'] });
+      return degradedEnvelope(consultationId, ['consultant_unavailable']);
+    }
+
+    const result = await provider.runStructured({
+      presetId,
+      input: [{ role: 'user', content: buildConsultInput(concern, bundle) }],
+      metadata: { subAgent: 'pattern-consult', turnId },
+    });
+
+    if (result?.status && result.status !== 'completed') throw new Error(`pattern consult incomplete: status=${result.status}`);
+
+    const outputText = readOutputText(result);
+    const parsed = safeParse(outputText, null);
+    if (outputText && outputText.trim() && parsed === null) {
+      logger.warn('[patternConsult] model output did not parse as JSON; degraded', { turnId });
+      await persist(store, { consultationId, patientCode: patientId, turnId, concern, degraded: true, degradedReasons: ['malformed_model_output'] });
+      return degradedEnvelope(consultationId, ['malformed_model_output']);
+    }
+
+    const impressions = shapeImpressions(parsed?.impressions);
+    const recommendedProbes = asStringArray(parsed?.recommended_probes);
+    const watchFor = asStringArray(parsed?.watch_for);
+    const escalationAdvice = shapeEscalation(parsed?.escalation_advice);
+
+    const persisted = await persist(store, {
+      consultationId, patientCode: patientId, turnId, concern,
+      impressions, recommendedProbes, watchFor, escalationAdvice,
+    });
+    if (!persisted) return degradedEnvelope(consultationId, ['persist_failed']);
+
+    return { consultationId, impressions, recommendedProbes, watchFor, escalationAdvice, degradedReasons: [], degraded: false };
+  } catch (err) {
+    logger.error('[patternConsult] consult failed; degraded', { turnId, error: err?.message });
+    await persist(store, { consultationId, patientCode: patientId, turnId, concern, degraded: true, degradedReasons: ['consultant_unavailable'] });
+    return degradedEnvelope(consultationId, ['consultant_unavailable']);
+  }
+}
+
+module.exports = {
+  requestPatternConsult,
+};

package/lib/clinical/tools/requestPatternConsultTool.js

@@ -0,0 +1,70 @@
+const { requireGatewayProvider } = require('../config/llmConfig');
+const { requestPatternConsult } = require('../services/patternConsultService');
+
+const definition = {
+  name: 'requestPatternConsult',
+  description: '**Does:** Consults a symptom-pattern specialist sub-agent that reviews the patient\'s active symptom landscape and returns RANKED differential impressions, each with supporting AND against evidence plus the discriminators still missing. Read-only and NON-TERMINAL — it informs your reasoning; it does not resolve the turn.\n\n**Required inputs:** `concern` (SBAR-style, 1-2 sentences framing what to reason about).\n\n**When to call:** when several concurrent symptoms, an ambiguous presentation, or a possible cluster warrant an expert second read before you route or probe.\n\n**Returns:** `data.impressions[]` (each: `label`, `plausibility` low|moderate|high, `supporting[]`, `against[]`, `missing_discriminators[]`), `data.recommended_probes[]`, `data.watch_for[]`, `data.escalation_advice` ({ indicated_now, if_then } or null), `data.degraded` (true when the consult could not run — treat as advisory-absent, not as a clear result) with `data.degraded_reasons[]`.',
+  strict: false,
+  parameters: {
+    type: 'object',
+    properties: {
+      concern: {
+        type: 'string',
+        description: 'SBAR-style framing of the clinical question, 1-2 sentences: what the patient presents and what you want the specialist to reason about.',
+      },
+    },
+    required: ['concern'],
+  },
+};
+
+async function handler(args = {}, context = {}) {
+  try {
+    const runtime = context?.toolRuntimeContext || null;
+    const trace = runtime?.trace || null;
+
+    if (!runtime?.turnId || !runtime?.patientCode) {
+      return JSON.stringify({ success: false, error: 'requestPatternConsult requires an active turn context (turnId, patientCode).', data: {} });
+    }
+
+    const concern = (args?.concern || '').trim();
+    if (!concern) {
+      return JSON.stringify({ success: false, error: 'requestPatternConsult requires `concern`.', data: {} });
+    }
+
+    const r = await requestPatternConsult({
+      concern,
+      patientId: runtime.patientCode,
+      turnId: runtime.turnId,
+      provider: requireGatewayProvider(),
+    });
+
+    trace?.setSignals?.({
+      patternConsult: {
+        consultationId: r.consultationId,
+        impressions: r.impressions.length,
+        escalationIndicated: !!r.escalationAdvice?.indicated_now,
+        degraded: r.degraded,
+      },
+    });
+
+    return JSON.stringify({
+      success: true,
+      data: {
+        consultation_id: r.consultationId,
+        impressions: r.impressions,
+        recommended_probes: r.recommendedProbes,
+        watch_for: r.watchFor,
+        escalation_advice: r.escalationAdvice,
+        degraded: r.degraded,
+        degraded_reasons: r.degradedReasons,
+      },
+    });
+  } catch (err) {
+    return JSON.stringify({ success: false, error: err?.message || 'requestPatternConsult failed', data: {} });
+  }
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "5.10.0-dev.1037",
+  "version": "5.10.0-dev.1040",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",