micsapp OpenEvidence SDK Patterns
Table of Contents
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-authsetup - 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.