@peopl-health/nexus 5.9.2 → 5.10.0-dev.1021

package/lib/clinical/services/patternConsultService.js

@@ -1,115 +0,0 @@
-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

@@ -1,70 +0,0 @@
-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/lib/clinical/tools/submitPalliativeAssessmentTool.js

@@ -1,75 +0,0 @@
-const { assessmentUid, buildAssessment } = require('../helpers/palliativeAssessmentHelper');
-const { storePalliativeAssessment, readPalliativeByTurn } = require('../../fhir');
-const { fhirId } = require('../../fhir/helpers/fhirHelper');
-
-const definition = {
-  name: 'submitPalliativeAssessment',
-  description: '**Does:** Terminal Phase-1 commit of the `accompaniment` skill — persists a structured palliative assessment with ranked `findings[]` covering symptoms, QoL impact, improvement capacity, need characterization, and urgent-under-24h escalation.\n\n**Required inputs:** `assessment` (one object) with `findings[]` — each `{rank, element_type (cluster|individual), name_short, time_window, symptom_terms[], clinical_description, why_relevant, qol_impact (Low|Medium|High), qol_criteria, improvement_capacity (Low|Medium|High), improvement_criteria, are_meds_needed, needs_characterization, characterization_criteria, probe_questions[], audit_notes, cluster_note, escalation}` — plus `evaluation_summary`, `ranking_rationale`, `escalation_reason`. An `escalation` (`{max_action_time_hours 1-24, escalation_routes[], escalation_reason}`) is present only for a finding urgent under 24h.\n\n**When NOT to call:**\n- Twice in the same turn — fail-hard dedup, returns `assessment_already_committed_for_turn`.\n- To CORRECT a committed assessment — use `updatePalliativeAssessment` (full-replacement) instead.\n\n**Returns:** `accepted`, `assessment_id`, `turn_id`, `committed_at`, `element_count`.\n\n**Side effects:** persists the assessment as a FHIR `ClinicalImpression` (+ a `Task` per urgent finding) + `Provenance`.',
-  strict: false,
-  parameters: {
-    type: 'object',
-    properties: {
-      assessment: {
-        type: 'object',
-        description: 'The full palliative assessment. `findings[]` (ranked, contiguous): each finding carries its clinical shape and an optional `escalation` for urgent-under-24h items. Plus `evaluation_summary`, `ranking_rationale`, `escalation_reason`.',
-      },
-    },
-    required: ['assessment'],
-  },
-};
-
-function fail(error, data = {}) {
-  return JSON.stringify({ success: false, error, data });
-}
-
-async function handler(args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    if (!runtime?.turnId || !runtime?.patientCode) {
-      return fail('submitPalliativeAssessment requires an active turn context (turnId, patientCode).');
-    }
-    const raw = args?.assessment;
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-      return fail('assessment is required (non-empty object)');
-    }
-
-    const patientId = runtime.patientCode;
-    const turnId = runtime.turnId;
-
-    const existing = await readPalliativeByTurn({ patientId, turnId });
-    if (existing) {
-      return fail('assessment_already_committed_for_turn', { existing_assessment_id: fhirId(existing.assessmentId), turn_id: turnId });
-    }
-
-    const assessment = buildAssessment({
-      raw,
-      assessmentId: assessmentUid(),
-      patientId,
-      turnId,
-      committedAt: new Date().toISOString(),
-    });
-    await storePalliativeAssessment({ patientId, assessment });
-
-    const assessmentId = fhirId(assessment.assessmentId);
-    runtime.setPalliativeAssessment({ assessmentId, turnId });
-    runtime.trace.setSignals({ palliativeAssessmentId: assessmentId });
-
-    return JSON.stringify({
-      success: true,
-      data: {
-        accepted: true,
-        assessment_id: assessmentId,
-        turn_id: turnId,
-        committed_at: assessment.committedAt,
-        element_count: assessment.findings.length,
-      },
-    });
-  } catch (err) {
-    return JSON.stringify({ success: false, error: err?.message || 'submitPalliativeAssessment failed', data: {} });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-};

package/lib/clinical/tools/submitRecommendationPlanTool.js

@@ -1,242 +0,0 @@
-const { ZodError } = require('zod');
-
-const { storeRecommendationPlan, recommendationPlanExists } = require('../../fhir');
-const { RecommendationPlan, recommendationId } = require('../../shared/dtos/RecommendationPlan');
-const { logger } = require('../../utils/logger');
-
-const definition = {
-  name: 'submitRecommendationPlan',
-  description: '**Does:** Commits the symptom plan for THIS turn: ranked elements, each carrying its assessment fields AND its recommendation inline (rank/name/targets cannot diverge — one nested unit). Call ONCE per turn, AFTER submitSafetyGate on a triage turn (a chat turn may plan without a gate). Server-validated: contiguous ranks 1..N; denied symptoms excluded; main_recommendation 2-4 sentences; when_to_escalate ≤90 chars (auto-trimmed at a `;` boundary; required when the element escalates); every element delivers a patient-facing action (main_recommendation, otc_offer, or followup=team_referral); otc_offer only on chat turns and only complete (dose, frequency, duration, warnings) with non-null contraindications. Meds-need is carried solely by `recommendation.is_pharmacological_med_needed`; any element-level `are_meds_needed` is ignored. Repairs are disclosed in `auto_repairs`.\n\n**Required inputs:** `takeaways` (`safety_confirmation_needed`, `vital_risk_possible_now`, `summary_patient_facing`, `summary_internal`) and `elements[]` (each: `rank`, `type`, `name_short`, `targeted_ctcae_terms`, `why_relevant`, `escalation`, `recommendation`).\n\n**Returns:** `accepted`, `run_id`, `element_count`, `recommendation_ids` (rank order — reference these, never invent ids), `palliative_escalation`, `auto_repairs`.\n\n**Side effects:** persists the plan as a run-scoped FHIR ClinicalImpression + CarePlan + one Task per recommendation.',
-  strict: false,
-  parameters: {
-    type: 'object',
-    properties: {
-      takeaways: {
-        type: 'object',
-        description: '`{safety_confirmation_needed, safety_confirmation_question, vital_risk_possible_now, summary_patient_facing, summary_internal}`. `safety_confirmation_question` is exactly one closed yes/no question when needed; null otherwise.',
-      },
-      elements: {
-        type: 'array',
-        description: 'Ranked plan elements (contiguous ranks 1..N). Each: `{rank, type(cluster|individual), name_short, time_window, symptoms[{ctcae_term, grade, verification_status}], targeted_ctcae_terms[], why_relevant, qol_impact, improvement_capacity, escalation{urgent_under_24h, max_action_time_hours, routes[], clinical_criteria}, recommendation{symptoms_patient_facing[], is_pharmacological_med_needed, patient{main_recommendation, when_to_escalate, contraindications, expected_effectiveness}, otc_offer?, followup?, followup_urgency?}, grounded_in[]}`.',
-        items: { type: 'object' },
-      },
-    },
-    required: ['takeaways', 'elements'],
-  },
-};
-
-const str = (value) => (typeof value === 'string' ? value : '');
-const arr = (value) => (Array.isArray(value) ? value : []);
-const strList = (value) => arr(value).map(str).filter(Boolean);
-const num = (value) => (Number.isInteger(value) ? value : null);
-const nullableStr = (value) => str(value).trim() || null;
-const inEnum = (value, values) => (values.includes(str(value).trim()) ? str(value).trim() : null);
-
-const SENTENCE_END = /[.!?](?=\s|$)/g;
-const SENTENCE_PROTECT = /\b(?:\d+\.\d+|p\.\s?ej\.|Dr\.|Dra\.|etc\.)/gi;
-
-function sentenceCount(text) {
-  const protectedText = text.trim().replace(SENTENCE_PROTECT, (match) => match.replace(/\./g, '·'));
-  return (protectedText.match(SENTENCE_END) || []).length;
-}
-
-function trimEscalationText(text) {
-  if (text.length <= 90) return text;
-  let out = '';
-  for (const part of text.split(';').map((piece) => piece.trim()).filter(Boolean)) {
-    const candidate = out ? `${out}; ${part}` : part;
-    if (candidate.length > 90) break;
-    out = candidate;
-  }
-  return out || `${text.slice(0, 89).trimEnd()}…`;
-}
-
-function buildSymptom(raw) {
-  return {
-    ctcaeTerm: str(raw?.ctcae_term).trim(),
-    grade: num(raw?.grade),
-    verificationStatus: str(raw?.verification_status).trim() || 'suspected',
-  };
-}
-
-function buildOtcOffer(raw) {
-  if (!raw || typeof raw !== 'object') return null;
-  return {
-    label: str(raw?.label).trim(),
-    dose: nullableStr(raw?.dose),
-    frequency: nullableStr(raw?.frequency),
-    duration: nullableStr(raw?.duration),
-    warnings: nullableStr(raw?.warnings),
-  };
-}
-
-function buildElement(raw, repairs) {
-  const rawRec = raw?.recommendation || {};
-  const rawPatient = rawRec?.patient || {};
-  const patient = {
-    mainRecommendation: str(rawPatient?.main_recommendation).trim(),
-    whenToEscalate: nullableStr(rawPatient?.when_to_escalate),
-    contraindications: nullableStr(rawPatient?.contraindications),
-    expectedEffectiveness: inEnum(rawPatient?.expected_effectiveness, ['low', 'medium', 'high']),
-  };
-  if (patient.whenToEscalate && patient.whenToEscalate.length > 90) {
-    const trimmed = trimEscalationText(patient.whenToEscalate);
-    repairs.push(`when_to_escalate (rank ${raw?.rank ?? '?'}) recortado de ${patient.whenToEscalate.length} a ≤90 caracteres en límite de criterio`);
-    patient.whenToEscalate = trimmed;
-  }
-  const recommendation = {
-    symptomsPatientFacing: strList(rawRec?.symptoms_patient_facing),
-    isPharmacologicalMedNeeded: rawRec?.is_pharmacological_med_needed === true,
-    patient,
-    otcOffer: buildOtcOffer(rawRec?.otc_offer),
-    followup: inEnum(rawRec?.followup, ['checkin_48h', 'team_referral', 'none']),
-    followupUrgency: nullableStr(rawRec?.followup_urgency),
-  };
-  const rawEsc = raw?.escalation || {};
-  return {
-    rank: num(raw?.rank) || 0,
-    type: str(raw?.type).trim(),
-    nameShort: str(raw?.name_short).trim(),
-    timeWindow: nullableStr(raw?.time_window),
-    symptoms: arr(raw?.symptoms).map(buildSymptom),
-    targetedCtcaeTerms: strList(raw?.targeted_ctcae_terms),
-    whyRelevant: str(raw?.why_relevant).trim(),
-    qolImpact: inEnum(raw?.qol_impact, ['low', 'moderate', 'high']),
-    improvementCapacity: inEnum(raw?.improvement_capacity, ['low', 'moderate', 'high']),
-    escalation: {
-      urgentUnder24h: rawEsc?.urgent_under_24h === true,
-      maxActionTimeHours: num(rawEsc?.max_action_time_hours),
-      routes: strList(rawEsc?.routes),
-      clinicalCriteria: nullableStr(rawEsc?.clinical_criteria),
-    },
-    recommendation,
-    groundedIn: strList(raw?.grounded_in),
-  };
-}
-
-function validate(elements) {
-  const issues = [];
-  const ranks = elements.map((element) => element.rank).sort((a, b) => a - b);
-  const contiguous = ranks.every((rank, index) => rank === index + 1);
-  if (!contiguous) {
-    issues.push({ path: 'elements[].rank', problem: `ranks deben ser contiguos 1..${ranks.length}; recibidos ${ranks.join(', ')}` });
-  }
-  elements.forEach((element, index) => {
-    const path = `elements[${index}]`;
-    const { recommendation } = element;
-    const { patient } = recommendation;
-    for (const symptom of element.symptoms) {
-      if (symptom.verificationStatus === 'denied') {
-        issues.push({ path: `${path}.symptoms`, problem: `síntoma negado (${symptom.ctcaeTerm}) no se incluye` });
-      }
-    }
-    const count = patient.mainRecommendation ? sentenceCount(patient.mainRecommendation) : 0;
-    if (patient.mainRecommendation && !(count >= 2 && count <= 4)) {
-      issues.push({ path: `${path}.recommendation.patient.main_recommendation`, problem: `2-4 oraciones; detectadas: ${count}` });
-    }
-    if (element.escalation.urgentUnder24h && !patient.whenToEscalate) {
-      issues.push({ path: `${path}.recommendation.patient.when_to_escalate`, problem: 'elemento con escalamiento <24h ⇒ when_to_escalate no puede ser null' });
-    }
-    if (!patient.mainRecommendation && recommendation.otcOffer === null && recommendation.followup !== 'team_referral') {
-      issues.push({ path: `${path}.recommendation`, problem: 'sin main_recommendation, sin otc_offer y sin followup=team_referral — el paciente no recibe nada' });
-    }
-    if (recommendation.otcOffer !== null) {
-      for (const field of ['dose', 'frequency', 'duration', 'warnings']) {
-        if (!recommendation.otcOffer[field]) {
-          issues.push({ path: `${path}.recommendation.otc_offer.${field}`, problem: 'los 4 elementos del contrato OTC son obligatorios' });
-        }
-      }
-      if (!patient.contraindications) {
-        issues.push({ path: `${path}.recommendation.patient.contraindications`, problem: 'contraindications no puede ser null con una oferta OTC' });
-      }
-    }
-  });
-  return issues;
-}
-
-async function handler(args = {}, context = {}) {
-  try {
-    const runtime = context?.toolRuntimeContext || null;
-    if (!runtime?.turnId || !runtime?.patientCode) {
-      return JSON.stringify({ success: false, error: 'submitRecommendationPlan requires an active turn context (turnId, patientCode).', data: {} });
-    }
-    const takeaways = args?.takeaways;
-    if (!takeaways || typeof takeaways !== 'object') {
-      return JSON.stringify({ success: false, error: 'takeaways is required.', data: {} });
-    }
-    const rawElements = arr(args?.elements);
-    if (!rawElements.length) {
-      return JSON.stringify({ success: false, error: 'elements is required and must be non-empty.', data: {} });
-    }
-
-    // Nexus is chat-lane-only; the triage safety-gate precondition is Python-deferred.
-    const runId = `recrun-chat-${runtime.turnId}`;
-
-    if (await recommendationPlanExists({ runId })) {
-      return JSON.stringify({ success: false, error: 'plan_already_committed_for_turn', data: { run_id: runId } });
-    }
-
-    const repairs = [];
-    const elements = rawElements.map((raw) => buildElement(raw, repairs));
-    const issues = validate(elements);
-    if (issues.length) {
-      return JSON.stringify({ success: false, error: 'plan_invalid', data: { issues } });
-    }
-
-    const plan = new RecommendationPlan({
-      runId,
-      patientId: runtime.patientCode,
-      turnId: runtime.turnId,
-      takeaways: {
-        safetyConfirmationNeeded: takeaways.safety_confirmation_needed === true,
-        safetyConfirmationQuestion: nullableStr(takeaways.safety_confirmation_question),
-        vitalRiskPossibleNow: takeaways.vital_risk_possible_now === true,
-        summaryPatientFacing: str(takeaways.summary_patient_facing).trim(),
-        summaryInternal: str(takeaways.summary_internal).trim(),
-      },
-      elements,
-      createdAt: new Date().toISOString(),
-    });
-
-    await storeRecommendationPlan({ patientId: runtime.patientCode, plan });
-
-    const ranked = [...plan.elements].sort((a, b) => a.rank - b.rank);
-    const recommendationIds = ranked.map((element) => recommendationId(runId, element.rank));
-    const palliativeEscalation = plan.elements.some((element) => element.escalation.urgentUnder24h);
-
-    const trace = runtime.trace || null;
-    if (trace) {
-      trace.setSignals({
-        recommendationPlan: {
-          runId,
-          elementCount: plan.elements.length,
-          palliativeEscalation,
-        },
-      });
-    } else {
-      logger.warn('[submitRecommendationPlan] no trace on runtime context; plan signal not recorded', { turnId: runtime.turnId });
-    }
-
-    return JSON.stringify({
-      success: true,
-      data: {
-        accepted: true,
-        run_id: runId,
-        element_count: plan.elements.length,
-        recommendation_ids: recommendationIds,
-        palliative_escalation: palliativeEscalation,
-        auto_repairs: repairs,
-      },
-    });
-  } catch (err) {
-    if (err instanceof ZodError) {
-      return JSON.stringify({ success: false, error: 'plan_schema_invalid', data: { issues: err.issues.map((issue) => ({ path: issue.path.join('.'), problem: issue.message })) } });
-    }
-    return JSON.stringify({ success: false, error: err?.message || 'submitRecommendationPlan failed', data: {} });
-  }
-}
-
-module.exports = {
-  definition,
-  handler,
-};