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

Instructions

Step 1: Initiate DeepConsult Request

// 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

// 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<string> {
  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<DeepConsultResponse> {
  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<DeepConsultReport> {
  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

// 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<void> {
  // 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<void> {
  // 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<void> {
  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

// 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

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

// 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
• Evidence-Based Medicine Guidelines

Next Steps

For error handling patterns, see openevidence-common-errors.