openevidence-sdk-patterns

OpenEvidence SDK Patterns

Table of Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Best practices and design patterns for building production clinical decision support with OpenEvidence. Covers client singleton, typed queries, query builder, response transformer, and caching strategies.

Prerequisites

• Completed openevidence-install-auth setup
• Understanding of async/await patterns
• Familiarity with clinical workflows

Instructions

Step 1: Client Singleton with DI

Create OpenEvidenceClientFactory with configure(), getClient(), and setClient() (for testing). Ensures single client instance across the application.

Step 2: Define Typed Clinical Queries

Create TypeScript types for ClinicalSpecialty (10 specialties), QueryUrgency (stat/urgent/routine/research), ClinicalContext (specialty, urgency, patient demographics, conditions, medications), and QueryOptions.

Step 3: Implement Query Builder

Build fluent ClinicalQueryBuilder with .question(), .specialty(), .urgency(), .withPatient(), .withConditions(), .withMedications(), .maxCitations(), .includeGuidelines(), and .build() with validation.

Step 4: Create Response Transformer

Transform raw API responses into FormattedClinicalAnswer with summary, detailed answer, key points, evidence with strength ratings (high for NEJM/JAMA/Lancet, moderate for recent, low otherwise), and confidence level.

Step 5: Implement Caching Layer

Build ClinicalQueryCache with SHA-256 key generation, configurable TTL (1 hour default for clinical data), and invalidation support.

Output

• Client singleton factory with dependency injection
• Typed clinical query interfaces
• Fluent query builder with validation
• Response transformer with evidence strength ratings
• In-memory caching with TTL management

Error Handling

Pattern	Use Case	Benefit
Singleton	Single client instance	Memory efficiency, connection reuse
Builder	Complex queries	Type safety, validation, readability
Transformer	Response normalization	Consistent UI layer, evidence grading
Cache	Repeated queries	Reduced API calls, lower latency

Examples

Query Builder Usage

const query = new ClinicalQueryBuilder()
  .question('Recommended statin dosing for secondary prevention?')
  .specialty('cardiology')
  .urgency('routine')
  .withPatient(65, 'male')
  .withConditions(['prior MI', 'hyperlipidemia'])
  .includeGuidelines()
  .build();

See detailed implementation for advanced patterns.

Resources

• OpenEvidence API Reference
• TypeScript Design Patterns