openevidence-core-workflow-b

# OpenEvidence Core Workflow B: DeepConsult ## Overview DeepConsult is OpenEvidence's advanced research synthesis feature. It uses reasoning models to autonomously analyze and cross-reference hundreds of peer-reviewed medical studies, producing comprehensive research reports that would otherwise take months of human effort. ## Prerequisites - Completed `openevidence-install-auth` setup - Understanding of clinical research methodologies - Valid API credentials with DeepConsult access ## Key Differences from Clinical Query | Feature | Clinical Query | DeepConsult | |---------|---------------|-------------| | Response time | 5-10 seconds | 2-5 minutes | | Compute cost | 1x | 100x+ | | Studies analyzed | 5-10 | Hundreds | | Use case | Point-of-care | Research synthesis | | Output | Quick answer | Comprehensive report | ## Instructions ### Step 1: Initiate DeepConsult Request ```typescript // src/workflows/deep-consult.ts import { OpenEvidenceClient } from '@openevidence/sdk'; interface DeepConsultRequest { question: string; specialty: string; researchFocus?: 'treatment' | 'diagnosis' | 'prognosis' | 'epidemiology'; timeframe?: { startYear?: number; endYear?: number; }; preferredSources?: string[]; excludeSources?: string[]; } interface DeepConsultResponse { id: string; status: 'pending' | 'processing' | 'completed' | 'failed'; progress?: number; report?: DeepConsultReport; estimatedCompletionTime?: number; } interface DeepConsultReport { executiveSummary: string; detailedFindings: Section[]; methodology: string; studiesAnalyzed: number; citations: ExtendedCitation[]; limitations: string[]; clinicalImplications: string[]; generatedAt: string; } interface Section { title: string; content: string; citations: string[]; } interface ExtendedCitation { source: string; title: string; authors: string[]; year: number; doi?: string; studyType?: string; sampleSize?: number; evidenceLevel?: string; } ``` ### Step 2: Implement Async DeepConsult Service ```typescript // src/services/deep-consult.ts const client = new OpenEvidenceClient({ apiKey: process.env.OPENEVIDENCE_API_KEY, orgId: process.env.OPENEVIDENCE_ORG_ID, timeout: 300000, // 5 minute timeout for DeepConsult }); export async function initiateDeepConsult( request: DeepConsultRequest ): Promise { const response = await client.deepConsult.create({ question: request.question, context: { specialty: request.specialty, researchFocus: request.researchFocus || 'treatment', timeframe: request.timeframe, }, options: { preferredSources: request.preferredSources, excludeSources: request.excludeSources, maxDepth: 'comprehensive', // vs 'moderate' for faster results }, }); return response.consultId; } export async function checkDeepConsultStatus( consultId: string ): Promise { const status = await client.deepConsult.status(consultId); return { id: consultId, status: status.state, progress: status.progress, report: status.state === 'completed' ? status.report : undefined, estimatedCompletionTime: status.estimatedSecondsRemaining, }; } export async function waitForDeepConsult( consultId: string, onProgress?: (progress: number) => void ): Promise { const pollInterval = 5000; // 5 seconds const maxWait = 600000; // 10 minutes max const startTime = Date.now(); while (Date.now() - startTime < maxWait) { const status = await checkDeepConsultStatus(consultId); if (status.progress && onProgress) { onProgress(status.progress); } if (status.status === 'completed' && status.report) { return status.report; } if (status.status === 'failed') { throw new Error(`DeepConsult failed: ${consultId}`); } await new Promise(r => setTimeout(r, pollInterval)); } throw new Error(`DeepConsult timed out after ${maxWait / 1000}s`); } ``` ### Step 3: Webhook-Based Completion Handler ```typescript // src/webhooks/deep-consult-webhook.ts import { Request, Response } from 'express'; import { verifyWebhookSignature } from '../openevidence/security'; interface DeepConsultWebhookPayload { event: 'deepconsult.completed' | 'deepconsult.failed'; consultId: string; report?: DeepConsultReport; error?: string; timestamp: string; } export async function handleDeepConsultWebhook( req: Request, res: Response ): Promise { // Verify webhook signature const signature = req.headers['x-openevidence-signature'] as string; if (!verifyWebhookSignature(req.body, signature)) { res.status(401).json({ error: 'Invalid signature' }); return; } const payload: DeepConsultWebhookPayload = req.body; switch (payload.event) { case 'deepconsult.completed': await processCompletedReport(payload.consultId, payload.report!); break; case 'deepconsult.failed': await handleFailedConsult(payload.consultId, payload.error!); break; } res.status(200).json({ received: true }); } async function processCompletedReport( consultId: string, report: DeepConsultReport ): Promise { // Store report in database await db.deepConsultReports.insert({ consultId, report, completedAt: new Date(), }); // Notify requesting user await notificationService.send({ type: 'deep_consult_ready', consultId, summary: report.executiveSummary.substring(0, 200), }); } async function handleFailedConsult( consultId: string, error: string ): Promise { await db.deepConsultReports.update(consultId, { status: 'failed', error, }); // Alert operations team for investigation await alertService.send({ severity: 'warning', message: `DeepConsult ${consultId} failed: ${error}`, }); } ``` ### Step 4: Format Report for Clinical Use ```typescript // src/services/report-formatter.ts export function formatDeepConsultReport( report: DeepConsultReport ): FormattedReport { return { title: 'OpenEvidence DeepConsult Research Synthesis', generatedAt: report.generatedAt, // Executive summary for quick review summary: { text: report.executiveSummary, studiesReviewed: report.studiesAnalyzed, evidenceStrength: calculateOverallEvidenceStrength(report.citations), }, // Main findings organized by section findings: report.detailedFindings.map(section => ({ heading: section.title, content: section.content, supportingEvidence: section.citations.length, })), // Clinical takeaways clinicalImplications: report.clinicalImplications, // Study methodology and limitations methodology: report.methodology, limitations: report.limitations, // Full citation list references: report.citations.map((c, i) => ({ number: i + 1, formatted: formatCitation(c), doi: c.doi, evidenceLevel: c.evidenceLevel, })), // Disclaimer disclaimer: `This research synthesis was generated by OpenEvidence DeepConsult on ${report.generatedAt}. It analyzed ${report.studiesAnalyzed} studies and should be used to supplement, not replace, clinical judgment.`, }; } function calculateOverallEvidenceStrength(citations: ExtendedCitation[]): string { const highLevel = citations.filter(c => c.evidenceLevel === 'I' || c.evidenceLevel === 'II' ).length; const ratio = highLevel / citations.length; if (ratio > 0.5) return 'Strong'; if (ratio > 0.25) return 'Moderate'; return 'Limited'; } function formatCitation(c: ExtendedCitation): string { const authors = c.authors.length > 3 ? `${c.authors[0]} et al.` : c.authors.join(', '); return `${authors}. ${c.title}. ${c.source}. ${c.year}.`; } ``` ## Output - Comprehensive research report with executive summary - Hundreds of peer-reviewed studies analyzed - Evidence-graded citations with study details - Clinical implications and limitations ## Error Handling | Error | Cause | Solution | |-------|-------|----------| | Timeout | Extremely complex question | Use webhook for completion notification | | Insufficient sources | Very narrow topic | Broaden search criteria or timeframe | | Rate limit | Too many concurrent consults | Queue requests, process sequentially | | Report incomplete | Processing interrupted | Retry with same consultId | ## Cost Considerations - DeepConsult uses 100x+ compute vs standard queries - Use for research, not point-of-care - Implement quotas per user/team - Cache reports for identical questions ## Examples ### Research Use Case ```typescript // Example: Oncologist researching emerging treatment async function researchEmergingTreatment() { const consultId = await initiateDeepConsult({ question: 'What are the latest advances in CAR-T therapy for relapsed B-cell lymphoma?', specialty: 'oncology', researchFocus: 'treatment', timeframe: { startYear: 2022, endYear: 2025 }, preferredSources: ['NEJM', 'JCO', 'Blood', 'Lancet Oncology'], }); console.log(`DeepConsult initiated: ${consultId}`); console.log('Report will be ready in approximately 2-5 minutes...'); const report = await waitForDeepConsult(consultId, (progress) => { console.log(`Progress: ${progress}%`); }); const formatted = formatDeepConsultReport(report); return formatted; } ``` ## Resources - [OpenEvidence DeepConsult](https://www.openevidence.com/announcements/) - [Evidence-Based Medicine Guidelines](https://www.cebm.ox.ac.uk/) ## Next Steps For error handling patterns, see `openevidence-common-errors`.