openevidence-core-workflow-a

OpenEvidence Core Workflow A: Clinical Query

Overview

Primary workflow for real-time clinical queries at the point of care. Returns evidence-based answers in 5-10 seconds with peer-reviewed citations.

Prerequisites

• Completed openevidence-install-auth setup
• Understanding of clinical decision support patterns
• Valid API credentials configured

Use Cases

• Drug interaction checks during prescribing
• Treatment protocol lookups
• Differential diagnosis support
• Dosing verification
• Clinical guideline queries

Instructions

Step 1: Structure the Clinical Query

// src/workflows/clinical-query.ts
import { OpenEvidenceClient } from '@openevidence/sdk';

interface ClinicalQueryRequest {
  question: string;
  specialty: string;
  urgency: 'stat' | 'urgent' | 'routine';
  patientContext?: {
    age?: number;
    sex?: 'male' | 'female';
    conditions?: string[];
    medications?: string[];
  };
}

interface ClinicalQueryResponse {
  answer: string;
  citations: Citation[];
  confidence: number;
  responseTimeMs: number;
  queryId: string;
}

interface Citation {
  source: string;
  title: string;
  year: number;
  doi?: string;
  guideline?: boolean;
}

Step 2: Implement Query Service

// src/services/point-of-care-query.ts
import { OpenEvidenceClient } from '@openevidence/sdk';

const client = new OpenEvidenceClient({
  apiKey: process.env.OPENEVIDENCE_API_KEY,
  orgId: process.env.OPENEVIDENCE_ORG_ID,
  timeout: 15000, // 15 second timeout for point-of-care
});

export async function queryAtPointOfCare(
  request: ClinicalQueryRequest
): Promise<ClinicalQueryResponse> {
  const startTime = Date.now();

  const response = await client.query({
    question: request.question,
    context: {
      specialty: request.specialty,
      urgency: request.urgency,
      ...(request.patientContext && {
        patientAge: request.patientContext.age,
        patientSex: request.patientContext.sex,
        relevantConditions: request.patientContext.conditions,
        currentMedications: request.patientContext.medications,
      }),
    },
    options: {
      maxCitations: 5,
      includeGuidelines: true,
      prioritizeRecent: true, // Prefer evidence from last 3 years
    },
  });

  return {
    answer: response.answer,
    citations: response.citations.map(c => ({
      source: c.source,
      title: c.title,
      year: c.year,
      doi: c.doi,
      guideline: c.type === 'guideline',
    })),
    confidence: response.confidence,
    responseTimeMs: Date.now() - startTime,
    queryId: response.id,
  };
}

Step 3: Drug Interaction Check Example

// src/workflows/drug-interaction.ts
export async function checkDrugInteraction(
  drug1: string,
  drug2: string,
  patientContext?: { age?: number; conditions?: string[] }
): Promise<{
  hasInteraction: boolean;
  severity: 'major' | 'moderate' | 'minor' | 'none';
  details: string;
  citations: Citation[];
}> {
  const response = await queryAtPointOfCare({
    question: `What are the drug interactions between ${drug1} and ${drug2}?`,
    specialty: 'pharmacology',
    urgency: 'urgent',
    patientContext,
  });

  // Parse severity from response
  const severity = determineSeverity(response.answer);

  return {
    hasInteraction: severity !== 'none',
    severity,
    details: response.answer,
    citations: response.citations,
  };
}

function determineSeverity(answer: string): 'major' | 'moderate' | 'minor' | 'none' {
  const lower = answer.toLowerCase();
  if (lower.includes('contraindicated') || lower.includes('major interaction')) return 'major';
  if (lower.includes('moderate interaction') || lower.includes('caution')) return 'moderate';
  if (lower.includes('minor interaction')) return 'minor';
  if (lower.includes('no significant interaction') || lower.includes('no known interaction')) return 'none';
  return 'moderate'; // Default to moderate if unclear
}

Step 4: EHR Integration Pattern

// src/integrations/ehr-hook.ts
import { queryAtPointOfCare } from '../services/point-of-care-query';

// HL7 FHIR CDS Hooks integration
interface CDSRequest {
  hook: string;
  hookInstance: string;
  context: {
    patientId: string;
    encounterId?: string;
    medications?: any[];
  };
}

interface CDSResponse {
  cards: CDSCard[];
}

interface CDSCard {
  summary: string;
  detail: string;
  indicator: 'info' | 'warning' | 'critical';
  source: { label: string; url?: string };
  suggestions?: any[];
}

export async function handleCDSHook(request: CDSRequest): Promise<CDSResponse> {
  // Extract clinical context from FHIR resources
  const medications = request.context.medications?.map(m => m.medicationCodeableConcept?.text) || [];

  // Query OpenEvidence for relevant clinical information
  const evidence = await queryAtPointOfCare({
    question: buildClinicalQuestion(request.hook, medications),
    specialty: 'family-medicine',
    urgency: 'routine',
    patientContext: {
      medications,
    },
  });

  return {
    cards: [{
      summary: 'Clinical Evidence Available',
      detail: evidence.answer,
      indicator: evidence.confidence > 0.9 ? 'info' : 'warning',
      source: {
        label: 'OpenEvidence',
        url: 'https://openevidence.com',
      },
    }],
  };
}

function buildClinicalQuestion(hook: string, medications: string[]): string {
  switch (hook) {
    case 'medication-prescribe':
      return `Are there any drug interactions or contraindications for ${medications.join(', ')}?`;
    case 'order-sign':
      return `What are the clinical considerations for prescribing ${medications.join(', ')}?`;
    default:
      return `Provide clinical guidance for patient on ${medications.join(', ')}`;
  }
}

Output

• Real-time clinical query response (5-10 seconds)
• Evidence-based answer with peer-reviewed citations
• Confidence score for clinical decision support
• Query audit trail for compliance

Error Handling

Performance Considerations

• Target response time: < 10 seconds for point-of-care
• Cache frequent queries (drug info, guidelines)
• Pre-warm connections during low-traffic periods
• Use streaming responses for faster perceived performance

Examples

Complete Point-of-Care Integration

// Example: Emergency department workflow
async function edClinicalSupport(chiefComplaint: string, vitals: any) {
  const queries = await Promise.all([
    queryAtPointOfCare({
      question: `What is the differential diagnosis for ${chiefComplaint}?`,
      specialty: 'emergency-medicine',
      urgency: 'stat',
    }),
    queryAtPointOfCare({
      question: `What workup is recommended for ${chiefComplaint}?`,
      specialty: 'emergency-medicine',
      urgency: 'stat',
    }),
  ]);

  return {
    differential: queries[0],
    workup: queries[1],
  };
}

Resources

• OpenEvidence
• HL7 CDS Hooks
• SMART on FHIR

Next Steps

For comprehensive research queries, see openevidence-core-workflow-b (DeepConsult).