@peopl-health/nexus 6.0.0-dev.649 → 6.0.0-dev.658

package/lib/clinical/helpers/clinicalFactsHelper.js

@@ -0,0 +1,81 @@
+const CATEGORY_TO_KIND = {
+  symptom: 'observation',
+  lab_value: 'observation',
+  emotion: 'observation',
+  medication: 'medication',
+  adherence: 'medication',
+  diagnosis: 'condition',
+  indication: 'condition',
+  treatment: 'procedure',
+  appointment: 'appointment',
+  allergy: 'allergy',
+};
+const LOW_CONFIDENCE = 0.7;
+
+function projectClinicalFacts({ clinicalMentions = [], safetyFlags = [], gradeScales = {} }) {
+  const clinicalFacts = clinicalMentions.map((m) => toClinicalFact(m, gradeScales)).filter(Boolean);
+
+  const symptoms = clinicalMentions.filter((m) => m?.fact?.category === 'symptom').length;
+  const agentHint = !clinicalMentions.length
+    ? 'Sin entidades clínicas extraíbles en este mensaje.'
+    : symptoms ? `${symptoms} síntoma(s) nuevo(s)` : `${clinicalMentions.length} mención(es) clínica(s)`;
+
+  return {
+    success: true,
+    data: {
+      agent_hint: agentHint,
+      safety_flags_received: [...safetyFlags],
+      degraded: false,
+      degraded_reasons: [],
+      clinical_facts: clinicalFacts,
+    },
+  };
+}
+
+function toClinicalFact(mention, gradeScales = {}) {
+  const fact = mention?.fact || {};
+  const prov = mention?.provenance || {};
+  if (!fact.mentionId || !fact.category || !fact.canonicalTerm) return null;
+
+  const kind = CATEGORY_TO_KIND[fact.category] || 'observation';
+  const out = { id: fact.mentionId, code: fact.canonicalTerm, kind };
+  if (fact.reportedAt) out.effective = fact.reportedAt;
+
+  const notes = Array.isArray(prov.verbatimQuotes) ? prov.verbatimQuotes.filter(Boolean) : [];
+  if (notes.length) out.notes = notes;
+
+  const assertion = fact.assertion;
+  if (assertion && typeof assertion === 'object') {
+    const interp = {
+      negated: Boolean(assertion.negated),
+      hedged: Boolean(assertion.hedged),
+      experiencer: assertion.experiencer || 'patient',
+      temporal: assertion.temporal || 'current',
+    };
+    const isDefault = !interp.negated && !interp.hedged
+      && interp.experiencer === 'patient' && interp.temporal === 'current';
+    if (!isDefault) out.interpretation = interp;
+  }
+
+  const confidence = prov.extractorConfidence;
+  if (typeof confidence === 'number' && confidence < LOW_CONFIDENCE) out.confidence = confidence;
+
+  if (kind === 'observation') {
+    if (fact.ctcaeTerm) out.code_ctcae = fact.ctcaeTerm;
+    const observed = Object.fromEntries(
+      Object.entries(fact.observedFields || {}).filter(([, v]) => v !== null && v !== undefined),
+    );
+    if (Object.keys(observed).length) out.value = { observed };
+    const gradeScale = fact.ctcaeTerm ? gradeScales[fact.ctcaeTerm] || null : null;
+    if (gradeScale) out.grade_scale = gradeScale;
+  } else if (kind === 'medication') {
+    out.adherence_status = fact.category === 'adherence' ? 'non_adherent' : 'unknown';
+  } else if (kind === 'condition') {
+    out.clinical_status = fact.category === 'diagnosis' ? 'active' : 'unknown';
+  }
+  return out;
+}
+
+module.exports = {
+  projectClinicalFacts,
+};

package/lib/clinical/index.js

@@ -24,6 +24,7 @@ const llmConfigModule = require('./config/llmConfig');
 const { ToolRuntimeContext } = require('./context/ToolRuntimeContext');
 
 const { getCtcaeCatalog } = require('./stores/CtcaeCatalog');
+const { registerClinicalTools } = require('./tools/registerClinicalTools');
 
 async function initialize() {
   await getCtcaeCatalog().initialize();
@@ -31,6 +32,7 @@ async function initialize() {
 
 module.exports = {
   initialize,
+  registerClinicalTools,
   createLLMProvider,
   PROVIDER_VARIANTS,
   OpenAIResponsesProvider,

package/lib/clinical/tools/extractClinicalInfoTool.js

@@ -0,0 +1,156 @@
+const { requireOpenAIProvider } = require('../config/llmConfig');
+const { getCtcaeCatalog } = require('../stores/CtcaeCatalog');
+const { getSafetyFlagPatterns } = require('../config/divergenceConfig');
+const { extractClinicalMentions, getConversationalTokens } = require('../services/clinicalExtractionService');
+const { detectSafetyFlags } = require('../helpers/safetyFlagsHelper');
+const { projectClinicalFacts } = require('../helpers/clinicalFactsHelper');
+const { logger } = require('../../utils/logger');
+
+const DETECTED_TAG_ENUM = [
+  'symptom', 'indication', 'treatment', 'adherence', 'medication', 'appointment',
+  'emotion', 'lab_value', 'diagnosis', 'allergy', 'comorbidity', 'performance_status',
+];
+const MAX_CONVERSATIONAL_TOKENS = 5;
+
+const definition = {
+  name: 'extractClinicalInfo',
+  description: "**Does:** Extracts ALL structured clinical facts from the current patient message — symptoms, labs, medications, diagnoses, appointments, treatments — and returns them as a discriminated-union `clinical_facts[]` list keyed by `kind`. Call ONCE per turn with ALL detected tags in a single call — one call covers every category.\n\n**Required inputs:** `raw_message` (the patient's current turn text, VERBATIM), `detected_tags` (list, at least one of: `symptom`, `indication`, `treatment`, `adherence`, `medication`, `appointment`, `emotion`, `lab_value`, `diagnosis`, `allergy`, `comorbidity`, `performance_status`), `intake_source` (`self` | `caregiver` | `team_relay`).\n\n**When to call:** at the start of any turn where the patient message mentions, explicitly or implicitly, any of the 12 supported categories. The result drives every downstream router-side read (landscape / history / risk / patterns).\n\n**When NOT to call:**\n- When the patient SHARED raw numeric results / lab values / files — use `reportResultsReceived` instead (it both logs the share AND emits FHIR Observations directly).\n- More than once per turn — a single call covers every category.\n\n**Returns:** `data.clinical_facts[]` — a discriminated-union list where each record has `kind` (observation | medication | condition | procedure | appointment | allergy) plus common fields `{id, code, effective, notes}` (null/default fields are OMITTED — e.g. `interpretation` appears only when non-default) and kind-specific fields:\n- `kind=observation`: `code_ctcae`, `value`, `grade_scale`,   `episode_id`, `trend`. Read `grade_scale` to anchor the   grade assigned in `recordClinicalImpression`; it is sent   only while the symptom has no open case yet (once open,   `grade_scale_omitted_open_case` carries the case_id — use   `lookupCtcaeEntry` if you need the ladder again).\n- `kind=medication`: `adherence_status` (`started` |   `ongoing` | `non_adherent` | …).\n- `kind=condition`: `clinical_status` (`active` | `resolved`   | …) — patient self-report of an existing diagnosis   (distinct from `openCondition` which commits a new   agent-tracked case).\n- `kind=procedure`: patient-reported procedure done   elsewhere (distinct from `recordIntervention` which is   agent-authored); `venue`/`outcome` may be null in the   current extraction phase.\n- `kind=appointment`: `scheduled_for`, `purpose` (may be   null in the current extraction phase).\nThe system writes the matching FHIR resource (Observation / MedicationStatement / Condition / Procedure / Appointment) + `Provenance` per fact on the audit lane; `allergy`, `comorbidity`, and `performance_status` are captured in a dedicated aggregate, not as a per-fact resource.\n\n**Side effects:** System emits a FHIR resource + `Provenance` per fact on the audit lane, except `allergy`/`comorbidity`/`performance_status` (aggregated).",
+  strict: true,
+  parameters: {
+    type: 'object',
+    properties: {
+      raw_message: {
+        type: 'string',
+        description: 'Mensaje VERBATIM del paciente para este turno (el mismo texto que recibiste; no lo parafrasees). El backend lo estructura.',
+      },
+      detected_tags: {
+        type: 'array',
+        items: { type: 'string', enum: DETECTED_TAG_ENUM },
+        description: [
+          'Lista de variables clínicas que el mensaje MENCIONA (explícita o implícitamente). Incluye TODAS las que apliquen en UNA sola llamada — el backend procesa múltiples categorías juntas. Guía rápida:',
+          '- symptom: síntoma nuevo, cambio, recurrente, o resuelto.',
+          '- indication: indicación del equipo (medicación, dieta, actividad, conducta).',
+          '- treatment: tratamiento oncológico (oral / IV / radio / cirugía) con cambio de estado (planeado/iniciado/pausado/completado).',
+          '- adherence: toma/omisión/ajuste de una indicación o medicación.',
+          '- medication: medicación no-oncológica o adyuvante. Etiqueta aunque solo la vaya a empezar, la tome ahora, o la haya tomado antes (el backend distingue planeada/actual/pasada y solo la actual entra a la lista de medicación vigente).',
+          '- appointment: cita o estudio confirmado/atendido/cancelado.',
+          '- emotion: estado emocional expresado (ansiedad, tristeza, miedo, etc.).',
+          '- lab_value: valor NUMÉRICO de laboratorio que el paciente comparte en el texto (ej: hemoglobina 9.2). Para solo mencionar que recibió resultados sin valores, usa reportResultsReceived.',
+          '- diagnosis: diagnóstico nuevo, confirmado, descartado, en progresión o remisión.',
+          '- allergy: alergia o reacción adversa a una sustancia.',
+          '- comorbidity: condición crónica NO oncológica (diabetes, hipertensión, etc.).',
+          '- performance_status: valor ECOG o Karnofsky reportado.',
+        ].join('\n'),
+      },
+      intake_source: {
+        type: 'string',
+        enum: ['self', 'caregiver', 'team_relay'],
+        description: "Quién reporta la información. 'self' = paciente directamente; 'caregiver' = familiar; 'team_relay' = el paciente transmite algo que le dijo un clínico (su equipo, un médico, especialista). Importa para la autoridad del dato: un juicio clínico (diagnosis, ECOG) transmitido como team_relay se registra como 'según médico'; si el paciente lo afirma por su cuenta queda 'sin confirmar'.",
+      },
+      response_format: {
+        anyOf: [
+          { type: 'string', enum: ['router', 'full'], description: "'router' (default) trims each clinical fact to the router's decision-critical fields — `id`, `interpretation` (negated/hedged/experiencer/temporal), `confidence`, `grade_scale` (the CTCAE grade RUBRIC), `value.observed` (the structured grading EVIDENCE, non-null entries only), `episode_id`, and `trend`. Use 'full' only when you need the complete verbose per-fact record in this turn." },
+          { type: 'null' },
+        ],
+      },
+    },
+    required: ['raw_message', 'detected_tags', 'intake_source', 'response_format'],
+    additionalProperties: false,
+  },
+};
+
+const SUPPORTED_TAGS = new Set(DETECTED_TAG_ENUM);
+
+async function handler(args, context = {}) {
+  const runtime = context?.toolRuntimeContext || null;
+  const trace = runtime?.trace || null;
+
+  const rawMessage = (args?.raw_message || '').trim();
+  const detectedTagsRaw = Array.isArray(args?.detected_tags) ? args.detected_tags : [];
+  const intakeSource = args?.intake_source || 'self';
+  const requestedFormat = typeof args?.response_format === 'string' ? args.response_format.toLowerCase() : 'router';
+  const responseFormat = ['router', 'full'].includes(requestedFormat) ? requestedFormat : 'router';
+
+  if (!rawMessage) {
+    if (trace?.setSignals) trace.setSignals({ clinicalMentions: [], safetyFlags: [] });
+    return JSON.stringify({ success: false, error: 'extractClinicalInfo requires `raw_message`.' });
+  }
+
+  const detectedTags = detectedTagsRaw
+    .filter((t) => typeof t === 'string' && SUPPORTED_TAGS.has(t.toLowerCase()))
+    .map((t) => t.toLowerCase());
+
+  if (!detectedTags.length) {
+    const supported = [...SUPPORTED_TAGS].sort();
+    const safetyFlags = await scanSafetyFlags(rawMessage);
+    if (trace?.setSignals) trace.setSignals({ clinicalMentions: [], safetyFlags });
+
+    let conversationalTokens = [];
+    try {
+      conversationalTokens = await getConversationalTokens();
+    } catch (err) {
+      logger.warn('[extractClinicalInfo] conversational token load failed; treating inbound as non-conversational', { turnId: runtime?.turnId, error: err?.message });
+    }
+    if (!detectedTagsRaw.length && isPurelyConversational(rawMessage, conversationalTokens)) {
+      return JSON.stringify({
+        success: true,
+        data: { degraded: false, conversational_inbound: true, clinical_facts: [] },
+      });
+    }
+    const error = !detectedTagsRaw.length
+      ? `extractClinicalInfo was called with an empty \`detected_tags\` list and the inbound is not purely conversational. Two recovery paths: (a) if the inbound has no clinical content, skip intake and respond with DeliverPatientMessage(intent_type=casual_acknowledge); (b) if you missed clinical content, re-call with at least one of: ${supported.join(', ')}.`
+      : `extractClinicalInfo received detected_tags=${JSON.stringify(detectedTagsRaw)} but none are supported. Use only these exact strings (lowercase): ${supported.join(', ')}. Re-call with the corrected tags.`;
+    return JSON.stringify({ success: false, error, supported_tags: supported, received_tags: detectedTagsRaw });
+  }
+
+  if (!runtime?.turnId || !runtime?.patientCode) {
+    return JSON.stringify({ success: false, error: 'extractClinicalInfo requires an active turn context (turnId, patientCode).' });
+  }
+
+  const { clinicalMentions, safetyFlags } = await extractClinicalMentions({
+    text: rawMessage,
+    detectedTags,
+    intakeSource,
+    responseFormat,
+    turnId: runtime.turnId,
+    code: runtime.patientCode,
+    provider: requireOpenAIProvider(),
+  });
+
+  if (trace?.setSignals) {
+    trace.setSignals({ clinicalMentions, safetyFlags });
+  } else {
+    logger.warn('[extractClinicalInfo] no trace on runtime context; signals not recorded', { turnId: runtime?.turnId });
+  }
+
+  const terms = [...new Set(clinicalMentions.map((m) => m?.fact?.ctcaeTerm).filter(Boolean))];
+  const catalog = getCtcaeCatalog();
+  const gradeScales = {};
+  for (const term of terms) gradeScales[term] = catalog.getGradeScale(term);
+  const envelope = projectClinicalFacts({ clinicalMentions, safetyFlags, gradeScales });
+  return JSON.stringify(envelope);
+}
+
+async function scanSafetyFlags(text) {
+  try {
+    return detectSafetyFlags(text, await getSafetyFlagPatterns());
+  } catch (err) {
+    logger.warn('[extractClinicalInfo] deterministic safety scan failed', { error: err?.message });
+    return [];
+  }
+}
+
+function isPurelyConversational(text, tokens) {
+  if (!text) return true;
+  const cleaned = text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ');
+  const found = cleaned.split(/\s+/).filter(Boolean);
+  if (!found.length) return true;
+  if (found.length > MAX_CONVERSATIONAL_TOKENS) return false;
+  const allowed = tokens instanceof Set ? tokens : new Set(tokens || []);
+  return found.every((tok) => allowed.has(tok));
+}
+
+module.exports = {
+  definition,
+  handler,
+};

package/lib/clinical/tools/registerClinicalTools.js

@@ -0,0 +1,19 @@
+const { registerTool } = require('../../services/toolRegistryService');
+
+const TOOLS = [
+  require('./extractClinicalInfoTool'),
+];
+
+function registerClinicalTools() {
+  for (const tool of TOOLS) {
+    registerTool({
+      name: tool.definition.name,
+      description: tool.definition.description,
+      parameters: tool.definition.parameters,
+      strict: tool.definition.strict,
+      handler: tool.handler,
+    });
+  }
+}
+
+module.exports = { registerClinicalTools };

package/lib/index.js

@@ -16,6 +16,7 @@ const {
   DefaultMemoryManager,
   EnhancedMemoryManager,
   initialize: initializeClinical,
+  registerClinicalTools,
 } = require('./clinical');
 const { initialize: initializeFhir } = require('./fhir');
 const { logger } = require('./utils/logger');
@@ -157,6 +158,12 @@ class Nexus {
       logger.warn('[Nexus] clinical init skipped', { error: e?.message || e });
     }
 
+    try {
+      registerClinicalTools();
+    } catch (e) {
+      logger.warn('Warning: failed to register clinical tools:', e?.message || e);
+    }
+
     this.isInitialized = true;
   }
 

package/package.json

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