@claude-flow/plugin-healthcare-clinical 3.0.0-alpha.1

package/README.md

@@ -0,0 +1,280 @@
+# @claude-flow/plugin-healthcare-clinical
+
+[![npm version](https://img.shields.io/npm/v/@claude-flow/plugin-healthcare-clinical.svg)](https://www.npmjs.com/package/@claude-flow/plugin-healthcare-clinical)
+[![npm downloads](https://img.shields.io/npm/dm/@claude-flow/plugin-healthcare-clinical.svg)](https://www.npmjs.com/package/@claude-flow/plugin-healthcare-clinical)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A HIPAA-compliant clinical decision support plugin that combines ultra-fast vector search for medical literature retrieval with graph neural networks for patient pathway analysis. The plugin enables semantic search across medical records, drug interaction detection, and evidence-based treatment recommendations while maintaining strict data privacy through on-device WASM processing.
+
+## Features
+
+- **Patient Similarity Search**: Find similar patient cases based on clinical features (diagnoses, labs, vitals, medications)
+- **Drug Interaction Detection**: Analyze drug-drug and drug-condition interactions using graph neural networks
+- **Clinical Pathway Recommendations**: Suggest evidence-based clinical pathways based on diagnosis and patient history
+- **Medical Literature Search**: Semantic search across medical literature (PubMed, Cochrane, UpToDate)
+- **Ontology Navigation**: Navigate ICD-10, SNOMED-CT, LOINC, and RxNorm hierarchies using hyperbolic embeddings
+
+## Installation
+
+### npm
+
+```bash
+npm install @claude-flow/plugin-healthcare-clinical
+```
+
+### CLI
+
+```bash
+npx claude-flow plugins install --name @claude-flow/plugin-healthcare-clinical
+```
+
+## Quick Start
+
+```typescript
+import { HealthcareClinicalPlugin } from '@claude-flow/plugin-healthcare-clinical';
+
+// Initialize the plugin
+const healthcare = new HealthcareClinicalPlugin({
+  ontologyPath: './data/ontologies',
+  indexPath: './data/patient-index',
+  hipaaCompliance: true
+});
+
+// Find similar patients
+const similarPatients = await healthcare.patientSimilarity({
+  patientFeatures: {
+    diagnoses: ['E11.9', 'I10'],  // ICD-10 codes
+    labResults: { HbA1c: 7.5, eGFR: 65 },
+    medications: ['metformin', 'lisinopril']
+  },
+  topK: 5
+});
+
+// Check drug interactions
+const interactions = await healthcare.drugInteractions({
+  medications: ['warfarin', 'aspirin', 'ibuprofen'],
+  severity: 'major'
+});
+
+// Search medical literature
+const literature = await healthcare.literatureSearch({
+  query: 'diabetes management in elderly patients',
+  sources: ['pubmed', 'cochrane'],
+  evidenceLevel: 'systematic-review'
+});
+```
+
+## MCP Tools
+
+### 1. `healthcare/patient-similarity`
+
+Find similar patient cases for treatment guidance.
+
+```typescript
+// Example usage via MCP
+const result = await mcp.invoke('healthcare/patient-similarity', {
+  patientFeatures: {
+    diagnoses: ['J45.20', 'J30.9'],
+    labResults: { FEV1: 72, eosinophils: 450 },
+    vitals: { peakFlow: 380 },
+    medications: ['budesonide', 'albuterol']
+  },
+  topK: 5,
+  cohortFilter: 'adult-asthma'
+});
+```
+
+### 2. `healthcare/drug-interactions`
+
+Detect potential drug-drug and drug-condition interactions.
+
+```typescript
+const result = await mcp.invoke('healthcare/drug-interactions', {
+  medications: ['clopidogrel', 'omeprazole', 'atorvastatin'],
+  conditions: ['CKD-stage-3'],
+  severity: 'all'
+});
+```
+
+### 3. `healthcare/clinical-pathways`
+
+Recommend evidence-based clinical pathways.
+
+```typescript
+const result = await mcp.invoke('healthcare/clinical-pathways', {
+  primaryDiagnosis: 'I21.0',  // STEMI
+  patientHistory: {
+    age: 68,
+    comorbidities: ['E11.9', 'I10']
+  },
+  constraints: {
+    excludeMedications: ['aspirin'],  // Allergy
+    outpatientOnly: false
+  }
+});
+```
+
+### 4. `healthcare/literature-search`
+
+Semantic search across medical literature.
+
+```typescript
+const result = await mcp.invoke('healthcare/literature-search', {
+  query: 'SGLT2 inhibitors cardiovascular outcomes',
+  sources: ['pubmed', 'cochrane'],
+  dateRange: { from: '2020-01-01', to: '2024-12-31' },
+  evidenceLevel: 'rct'
+});
+```
+
+### 5. `healthcare/ontology-navigate`
+
+Navigate medical ontology hierarchies.
+
+```typescript
+const result = await mcp.invoke('healthcare/ontology-navigate', {
+  code: 'E11',
+  ontology: 'icd10',
+  direction: 'descendants',
+  depth: 2
+});
+```
+
+## Configuration Options
+
+```typescript
+interface HealthcarePluginConfig {
+  // Data paths
+  ontologyPath: string;           // Path to ontology files
+  indexPath: string;              // Path to HNSW index storage
+
+  // HIPAA compliance
+  hipaaCompliance: boolean;       // Enable HIPAA-compliant mode (default: true)
+  auditLogPath: string;           // Path for audit logs
+  encryptionKey?: string;         // AES-256 encryption key
+
+  // Performance
+  maxMemoryMB: number;            // WASM memory limit (default: 512)
+  cacheSize: number;              // Embedding cache size (default: 10000)
+
+  // Ontologies
+  enabledOntologies: string[];    // ['icd10', 'snomed', 'loinc', 'rxnorm']
+
+  // Access control
+  roleBasedAccess: boolean;       // Enable RBAC (default: true)
+}
+```
+
+## Security Considerations
+
+### HIPAA Compliance
+
+This plugin is designed with HIPAA compliance as a core requirement:
+
+| Requirement | Implementation |
+|-------------|----------------|
+| **PHI Protection** | All patient data processed exclusively in WASM sandbox |
+| **Encryption at Rest** | AES-256 encryption for all stored embeddings and indexes |
+| **Encryption in Transit** | TLS 1.3 minimum for any network operations |
+| **Access Logging** | Immutable audit logs with tamper detection (HMAC) |
+| **Minimum Necessary** | Role-based data filtering at query time |
+
+### On-Device Processing
+
+- All PHI is processed locally via WASM - no cloud transmission
+- WASM sandbox prevents network access and file system access
+- Memory limited to 512MB to prevent exhaustion attacks
+- 30-second CPU timeout per operation
+
+### Role-Based Access Control
+
+```typescript
+const roles = {
+  PHYSICIAN: ['patient-similarity', 'drug-interactions', 'clinical-pathways', 'literature-search', 'ontology-navigate'],
+  NURSE: ['drug-interactions', 'ontology-navigate'],
+  PHARMACIST: ['drug-interactions', 'literature-search'],
+  RESEARCHER: ['literature-search', 'ontology-navigate'],  // No patient data
+  CODER: ['ontology-navigate']  // Billing codes only
+};
+```
+
+### Audit Logging
+
+All tool invocations are logged with:
+- Timestamp (ISO 8601 with timezone)
+- User ID and role
+- Tool name and action type
+- Hashed patient identifiers (not actual PHI)
+- Query hash for reproducibility
+
+Audit logs are retained for 6 years per HIPAA requirements.
+
+### Input Validation
+
+All inputs are validated using Zod schemas:
+- ICD-10 codes must match format `/^[A-Z]\d{2}(\.\d{1,2})?$/`
+- RxNorm CUIs validated for format
+- Maximum 100 diagnoses, 50 medications per query
+- String lengths capped to prevent injection attacks
+- Patient identifiers must be UUIDs or match institutional format
+
+### Rate Limiting
+
+```typescript
+const rateLimits = {
+  'healthcare/patient-similarity': { requestsPerMinute: 30, maxConcurrent: 3 },
+  'healthcare/drug-interactions': { requestsPerMinute: 60, maxConcurrent: 5 },
+  'healthcare/clinical-pathways': { requestsPerMinute: 20, maxConcurrent: 2 },
+  'healthcare/literature-search': { requestsPerMinute: 30, maxConcurrent: 3 },
+  'healthcare/ontology-navigate': { requestsPerMinute: 120, maxConcurrent: 10 }
+};
+```
+
+## Performance
+
+| Metric | Target |
+|--------|--------|
+| Patient similarity search | <50ms for 100K records |
+| Drug interaction check | <10ms for 20 medications |
+| Literature search | <100ms for 1M abstracts |
+| Ontology traversal | <5ms per hop |
+
+## Dependencies
+
+- `micro-hnsw-wasm`: Fast similarity search (150x faster than traditional)
+- `ruvector-gnn-wasm`: Graph neural networks for pathway analysis
+- `ruvector-hyperbolic-hnsw-wasm`: Hierarchical medical ontology embeddings
+- `ruvector-sparse-inference-wasm`: Efficient inference on sparse clinical features
+- `@medplum/fhirtypes`: FHIR R4 type definitions
+
+## Related Plugins
+
+| Plugin | Description | Use Case |
+|--------|-------------|----------|
+| [@claude-flow/plugin-legal-contracts](../legal-contracts) | Contract analysis and compliance | Healthcare vendor agreements, BAAs |
+| [@claude-flow/plugin-financial-risk](../financial-risk) | Risk analysis and compliance | Healthcare billing fraud detection |
+| [@claude-flow/plugin-code-intelligence](../code-intelligence) | Code analysis | EHR integration development |
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Claude Flow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bridges/gnn-bridge.d.ts

@@ -0,0 +1,70 @@
+/**
+ * GNN Bridge - Healthcare Clinical Plugin
+ *
+ * Provides Graph Neural Network capabilities for clinical pathway
+ * analysis and drug interaction detection. Integrates with
+ * ruvector-gnn-wasm for efficient graph-based reasoning.
+ *
+ * Use Cases:
+ * - Clinical pathway recommendations
+ * - Drug interaction network analysis
+ * - Comorbidity pattern detection
+ * - Treatment outcome prediction
+ */
+import type { GNNBridge, GNNConfig, GNNNode, GNNEdge, GNNPathResult, GNNInteractionResult, DrugInteraction, ClinicalPathway, Logger } from '../types.js';
+/**
+ * Healthcare GNN Bridge implementation
+ */
+export declare class HealthcareGNNBridge implements GNNBridge {
+    private wasmModule;
+    private graphPtr;
+    private config;
+    private logger;
+    private nodes;
+    private edges;
+    private nodeIdToIndex;
+    private drugInteractionGraph;
+    private clinicalPathwayGraph;
+    initialized: boolean;
+    constructor(config?: Partial<GNNConfig>, logger?: Logger);
+    /**
+     * Initialize the GNN bridge
+     */
+    initialize(config?: GNNConfig): Promise<void>;
+    /**
+     * Load a graph into the GNN
+     */
+    loadGraph(nodes: GNNNode[], edges: GNNEdge[]): Promise<void>;
+    /**
+     * Predict optimal pathway between nodes
+     */
+    predictPathway(startNode: string, endNode: string, constraints?: Record<string, unknown>): Promise<GNNPathResult>;
+    /**
+     * Analyze interactions between nodes
+     */
+    analyzeInteractions(nodeIds: string[]): Promise<GNNInteractionResult>;
+    /**
+     * Get clinical pathway for a diagnosis
+     */
+    getClinicalPathway(diagnosis: string): ClinicalPathway | undefined;
+    /**
+     * Check drug interactions
+     */
+    checkDrugInteractions(medications: string[], severityFilter?: string): DrugInteraction[];
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+    private resolveWasmPath;
+    private loadWasmModule;
+    private getNodeIdByIndex;
+    private bfsPath;
+    private calculatePathRisk;
+    private severityToStrength;
+}
+/**
+ * Create a new GNN bridge instance
+ */
+export declare function createGNNBridge(config?: Partial<GNNConfig>, logger?: Logger): HealthcareGNNBridge;
+export default HealthcareGNNBridge;
+//# sourceMappingURL=gnn-bridge.d.ts.map

package/dist/bridges/gnn-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gnn-bridge.d.ts","sourceRoot":"","sources":["../../src/bridges/gnn-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,OAAO,EACP,OAAO,EACP,aAAa,EACb,oBAAoB,EACpB,eAAe,EAEf,eAAe,EACf,MAAM,EACP,MAAM,aAAa,CAAC;AA2SrB;;GAEG;AACH,qBAAa,mBAAoB,YAAW,SAAS;IACnD,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,oBAAoB,CAAuB;IACnD,OAAO,CAAC,oBAAoB,CAAuB;IAE5C,WAAW,UAAS;gBAEf,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM;IAYxD;;OAEG;IACG,UAAU,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnD;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4ClE;;OAEG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAAC,aAAa,CAAC;IA0CzB;;OAEG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA4B3E;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAIlE;;OAEG;IACH,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,cAAc,GAAE,MAAc,GAAG,eAAe,EAAE;IAI/F;;OAEG;IACH,OAAO,IAAI,IAAI;YAYD,eAAe;YAUf,cAAc;IAM5B,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,OAAO;IAiCf,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,kBAAkB;CAS3B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAEjG;AAED,eAAe,mBAAmB,CAAC"}