OpenEvidence Core Workflow B: DeepConsult Research

Overview

Execute comprehensive medical evidence synthesis using OpenEvidence DeepConsult API. Build multi-source literature reviews, generate evidence summaries with confidence levels, and create structured clinical decision support outputs.

Prerequisites

• OpenEvidence API key with DeepConsult access
• Understanding of medical evidence hierarchies
• Familiarity with clinical question formats (PICO)
• Output template for clinical summaries

Instructions

Step 1: Structure Clinical Questions (PICO Format)

interface ClinicalQuestion {
  population: string;     // Patient population
  intervention: string;   // Treatment or exposure
  comparison?: string;    // Alternative treatment
  outcome: string;        // Desired outcome
  studyType?: string;     // RCT, meta-analysis, cohort
}

function formatPICOQuery(q: ClinicalQuestion): string {
  let query = `In ${q.population}, does ${q.intervention}`;
  if (q.comparison) query += ` compared to ${q.comparison}`;
  query += ` improve ${q.outcome}?`;
  return query;
}

// Example
const question: ClinicalQuestion = {
  population: 'adults with type 2 diabetes',
  intervention: 'GLP-1 receptor agonists',
  comparison: 'DPP-4 inhibitors',
  outcome: 'cardiovascular outcomes',
};

Step 2: Execute DeepConsult Query

const OPENEVIDENCE_API = 'https://api.openevidence.com/v1';

async function deepConsult(query: string, options?: {
  maxSources?: number;
  evidenceLevel?: 'all' | 'high-quality' | 'rct-only';
  recencyYears?: number;
}) {
  const response = await fetch(`${OPENEVIDENCE_API}/deepconsult`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.OPENEVIDENCE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query,
      max_sources: options?.maxSources || 20,
      evidence_filter: options?.evidenceLevel || 'all',
      recency_years: options?.recencyYears || 5,
    }),
  });

  if (!response.ok) throw new Error(`DeepConsult error: ${response.status}`);
  return response.json();
}

Step 3: Process and Structure Evidence

interface EvidenceSummary {
  question: string;
  conclusion: string;
  confidenceLevel: 'high' | 'moderate' | 'low' | 'very-low';
  keyFindings: string[];
  sources: Array<{
    title: string;
    authors: string;
    journal: string;
    year: number;
    evidenceType: string;
    url?: string;
  }>;
  limitations: string[];
}

function processDeepConsultResponse(response: any): EvidenceSummary {
  return {
    question: response.query,
    conclusion: response.synthesis?.conclusion || '',
    confidenceLevel: mapConfidence(response.synthesis?.confidence),
    keyFindings: response.synthesis?.key_findings || [],
    sources: (response.citations || []).map((c: any) => ({
      title: c.title,
      authors: c.authors?.join(', ') || 'Unknown',
      journal: c.journal || 'Unknown',
      year: c.year || 0,
      evidenceType: c.study_type || 'Unknown',
      url: c.doi ? `https://doi.org/${c.doi}` : undefined,
    })),
    limitations: response.synthesis?.limitations || [],
  };
}

function mapConfidence(score: number): EvidenceSummary['confidenceLevel'] {
  if (score >= 0.8) return 'high';
  if (score >= 0.6) return 'moderate';
  if (score >= 0.4) return 'low';
  return 'very-low';
}

Step 4: Generate Clinical Summary Report

function generateReport(summary: EvidenceSummary): string {
  const lines = [
    `# Evidence Summary`,
    ``,
    `**Question:** ${summary.question}`,
    ``,
    `## Conclusion (Confidence: ${summary.confidenceLevel})`,
    summary.conclusion,
    ``,
    `## Key Findings`,
    ...summary.keyFindings.map((f, i) => `${i + 1}. ${f}`),
    ``,
    `## Sources (${summary.sources.length})`,
    ...summary.sources.map(s =>
      `- ${s.authors} (${s.year}). *${s.title}*. ${s.journal}. [${s.evidenceType}]`
    ),
    ``,
    `## Limitations`,
    ...summary.limitations.map(l => `- ${l}`),
  ];

  return lines.join('\n');
}

Error Handling

Examples

Quick Evidence Lookup

const query = formatPICOQuery({
  population: 'elderly patients with atrial fibrillation',
  intervention: 'direct oral anticoagulants',
  comparison: 'warfarin',
  outcome: 'stroke prevention',
});

const result = await deepConsult(query, { evidenceLevel: 'high-quality' });
const summary = processDeepConsultResponse(result);
console.log(generateReport(summary));

Resources

• OpenEvidence API
• GRADE Evidence Framework
• PICO Framework Guide

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale