@genobank/biofs 1.2.6 → 1.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/ANNOTATOR_RECOMMENDATIONS_API.md +490 -0
  2. package/BIOOS_CLI_IMPLEMENTATION_COMPLETE.md +422 -0
  3. package/BIOOS_JOB_MANAGEMENT.md +681 -0
  4. package/INSTALL_V1.2.6_ON_MAC.md +282 -0
  5. package/OPENCRAVAT_ANNOTATORS_REFERENCE.md +340 -0
  6. package/OPENCRAVAT_ANNOTATOR_INTELLIGENCE_COMPLETE.md +479 -0
  7. package/README.md +27 -0
  8. package/dist/commands/job/create.d.ts +7 -0
  9. package/dist/commands/job/create.d.ts.map +1 -0
  10. package/dist/commands/job/create.js +108 -0
  11. package/dist/commands/job/create.js.map +1 -0
  12. package/dist/commands/job/list.d.ts +7 -0
  13. package/dist/commands/job/list.d.ts.map +1 -0
  14. package/dist/commands/job/list.js +135 -0
  15. package/dist/commands/job/list.js.map +1 -0
  16. package/dist/commands/job/pipelines.d.ts +5 -0
  17. package/dist/commands/job/pipelines.d.ts.map +1 -0
  18. package/dist/commands/job/pipelines.js +77 -0
  19. package/dist/commands/job/pipelines.js.map +1 -0
  20. package/dist/commands/job/results.d.ts +6 -0
  21. package/dist/commands/job/results.d.ts.map +1 -0
  22. package/dist/commands/job/results.js +101 -0
  23. package/dist/commands/job/results.js.map +1 -0
  24. package/dist/commands/job/status.d.ts +6 -0
  25. package/dist/commands/job/status.d.ts.map +1 -0
  26. package/dist/commands/job/status.js +139 -0
  27. package/dist/commands/job/status.js.map +1 -0
  28. package/dist/index.js +93 -1
  29. package/dist/index.js.map +1 -1
  30. package/dist/lib/api/client.d.ts +9 -0
  31. package/dist/lib/api/client.d.ts.map +1 -1
  32. package/dist/lib/api/client.js +58 -0
  33. package/dist/lib/api/client.js.map +1 -1
  34. package/opencravat_annotators_dictionary.json +2356 -0
  35. package/package.json +1 -1
  36. package/scripts/build_annotator_dictionary.py +352 -0
@@ -0,0 +1,490 @@
1
+ # OpenCRAVAT Annotator Recommendations API
2
+
3
+ ## Overview
4
+
5
+ The BioOS API now provides intelligent annotator recommendations based on phenotype or analysis type. Claude API can query these endpoints to recommend the most appropriate OpenCRAVAT annotators for any given research job.
6
+
7
+ ## API Endpoints
8
+
9
+ ### 1. Get Annotator Recommendations
10
+
11
+ **Endpoint**: `GET /api_bioos/annotator_recommendations`
12
+
13
+ Get recommended OpenCRAVAT annotators based on phenotype or analysis type.
14
+
15
+ **Query Parameters**:
16
+ - `phenotype` (optional): Phenotype category
17
+ - `cancer`
18
+ - `cardiovascular`
19
+ - `hereditary_cancer`
20
+ - `rare_disease`
21
+ - `pharmacogenomics`
22
+ - `autism`
23
+ - `developmental_delay`
24
+
25
+ - `analysis_type` (optional): Analysis type
26
+ - `rare_coding`
27
+ - `splicing`
28
+ - `regulatory`
29
+ - `de_novo`
30
+
31
+ **Examples**:
32
+
33
+ ```bash
34
+ # Get recommendations for cancer analysis
35
+ curl "https://genobank.app/api_bioos/annotator_recommendations?phenotype=cancer"
36
+
37
+ # Get recommendations for splicing analysis
38
+ curl "https://genobank.app/api_bioos/annotator_recommendations?analysis_type=splicing"
39
+
40
+ # List all available options
41
+ curl "https://genobank.app/api_bioos/annotator_recommendations"
42
+ ```
43
+
44
+ **Response Example** (phenotype=cancer):
45
+ ```json
46
+ {
47
+ "status": "Success",
48
+ "status_details": {
49
+ "data": {
50
+ "phenotype": "cancer",
51
+ "description": "Cancer-related analysis",
52
+ "recommended_annotators": [
53
+ "clinvar",
54
+ "cosmic",
55
+ "cancer_genome_interpreter",
56
+ "cancer_hotspots",
57
+ "civic",
58
+ "oncokb",
59
+ "chasmplus",
60
+ "gnomad",
61
+ "alphamissense",
62
+ "revel"
63
+ ],
64
+ "annotator_details": [
65
+ {
66
+ "name": "clinvar",
67
+ "title": "ClinVar",
68
+ "description": "ClinVar is an archive of reports of the relationships among human variations and phenotypes...",
69
+ "tags": ["mendelian disease", "variants"],
70
+ "level": "variant",
71
+ "version": "2025.09.01",
72
+ "developer": "NCBI",
73
+ "citation": "...",
74
+ "website": "https://www.ncbi.nlm.nih.gov/clinvar/"
75
+ },
76
+ ...
77
+ ]
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ **Response Example** (no parameters):
84
+ ```json
85
+ {
86
+ "status": "Success",
87
+ "status_details": {
88
+ "data": {
89
+ "available_phenotypes": [
90
+ "cancer",
91
+ "cardiovascular",
92
+ "hereditary_cancer",
93
+ "rare_disease",
94
+ "pharmacogenomics",
95
+ "autism",
96
+ "developmental_delay"
97
+ ],
98
+ "available_analysis_types": [
99
+ "rare_coding",
100
+ "splicing",
101
+ "regulatory",
102
+ "de_novo"
103
+ ],
104
+ "message": "Specify phenotype or analysis_type parameter for recommendations"
105
+ }
106
+ }
107
+ }
108
+ ```
109
+
110
+ ---
111
+
112
+ ### 2. Get Annotator Dictionary
113
+
114
+ **Endpoint**: `GET /api_bioos/annotator_dictionary`
115
+
116
+ Browse the complete OpenCRAVAT annotator dictionary with 146 annotators.
117
+
118
+ **Query Parameters**:
119
+ - `category` (optional): Filter by category
120
+ - `clinical_significance`
121
+ - `cancer`
122
+ - `population_frequency`
123
+ - `variant_effect_prediction`
124
+ - `pharmacogenomics`
125
+ - `mendelian_disease`
126
+ - `splicing`
127
+ - `regulatory`
128
+ - `conservation`
129
+ - `pathways`
130
+ - `protein_function`
131
+ - `other`
132
+
133
+ - `name` (optional): Get specific annotator by name (e.g., `clinvar`, `gnomad`, `alphamissense`)
134
+
135
+ **Examples**:
136
+
137
+ ```bash
138
+ # Get full dictionary
139
+ curl "https://genobank.app/api_bioos/annotator_dictionary"
140
+
141
+ # Get cancer-related annotators
142
+ curl "https://genobank.app/api_bioos/annotator_dictionary?category=cancer"
143
+
144
+ # Get specific annotator details
145
+ curl "https://genobank.app/api_bioos/annotator_dictionary?name=clinvar"
146
+ ```
147
+
148
+ **Response Example** (full dictionary):
149
+ ```json
150
+ {
151
+ "status": "Success",
152
+ "status_details": {
153
+ "data": {
154
+ "version": "1.0.0",
155
+ "total_annotators": 146,
156
+ "last_updated": "2025-10-07",
157
+ "annotators": [
158
+ {
159
+ "name": "clinvar",
160
+ "title": "ClinVar",
161
+ "description": "...",
162
+ "tags": ["mendelian disease", "variants"],
163
+ "level": "variant",
164
+ "version": "2025.09.01",
165
+ "developer": "NCBI",
166
+ "citation": "...",
167
+ "website": "..."
168
+ },
169
+ ...
170
+ ],
171
+ "categories": {
172
+ "clinical_significance": ["clinvar", "clinvar_acmg", "omim"],
173
+ "cancer": ["cosmic", "oncokb", "civic", ...],
174
+ ...
175
+ },
176
+ "recommendations": {
177
+ "phenotypes": {
178
+ "cancer": {
179
+ "description": "Cancer-related analysis",
180
+ "recommended_annotators": [...]
181
+ },
182
+ ...
183
+ },
184
+ "analysis_types": {
185
+ "rare_coding": {
186
+ "description": "Rare coding variant analysis",
187
+ "recommended_annotators": [...]
188
+ },
189
+ ...
190
+ }
191
+ }
192
+ }
193
+ }
194
+ }
195
+ ```
196
+
197
+ **Response Example** (name=alphamissense):
198
+ ```json
199
+ {
200
+ "status": "Success",
201
+ "status_details": {
202
+ "data": {
203
+ "name": "alphamissense",
204
+ "title": "AlphaMissense",
205
+ "description": "Variant pathogenicity scores from AlphaMissense",
206
+ "tags": ["variant effect prediction", "variants", "clinical relevance"],
207
+ "level": "variant",
208
+ "version": "1.1.1",
209
+ "developer": "Google DeepMind",
210
+ "citation": "J. Cheng et al., Science 381, eadg7492 (2023). DOI: 10.1126/science.adg7492",
211
+ "website": ""
212
+ }
213
+ }
214
+ }
215
+ ```
216
+
217
+ ---
218
+
219
+ ## Phenotype-Based Recommendations
220
+
221
+ ### Cancer
222
+ **Description**: Cancer-related analysis
223
+
224
+ **Recommended Annotators**:
225
+ - `clinvar` - Clinical significance
226
+ - `cosmic` - Catalogue of Somatic Mutations in Cancer
227
+ - `cancer_genome_interpreter` - Oncogenic alterations and drug biomarkers
228
+ - `cancer_hotspots` - Statistically significant mutations
229
+ - `civic` - Clinical interpretations of variants in cancer
230
+ - `oncokb` - Precision oncology knowledge base
231
+ - `chasmplus` - Machine learning for cancer driver mutations
232
+ - `gnomad` - Population frequency
233
+ - `alphamissense` - AI pathogenicity prediction
234
+ - `revel` - Ensemble pathogenicity score
235
+
236
+ ### Cardiovascular
237
+ **Description**: Cardiovascular disease analysis
238
+
239
+ **Recommended Annotators**:
240
+ - `clinvar` - Clinical significance
241
+ - `cardioboost` - Pathogenicity for cardiac conditions
242
+ - `cvdkp` - Cardiovascular Disease Knowledge Portal
243
+ - `gnomad` - Population frequency
244
+ - `alphamissense` - AI pathogenicity prediction
245
+ - `sift` - Protein function prediction
246
+ - `polyphen2` - Protein structure-based prediction
247
+
248
+ ### Hereditary Cancer
249
+ **Description**: Hereditary cancer predisposition
250
+
251
+ **Recommended Annotators**:
252
+ - `clinvar` - Clinical significance
253
+ - `brca1_func_assay` - BRCA1 saturation genome editing scores
254
+ - `cgc` - Cancer Gene Census
255
+ - `cosmic` - Somatic mutations in cancer
256
+ - `gnomad` - Population frequency
257
+ - `alphamissense` - AI pathogenicity prediction
258
+ - `revel` - Ensemble pathogenicity score
259
+
260
+ ### Rare Disease
261
+ **Description**: Rare Mendelian disease
262
+
263
+ **Recommended Annotators**:
264
+ - `clinvar` - Clinical significance with ACMG guidelines
265
+ - `clinvar_acmg` - ACMG PS1 and PM5 predictions
266
+ - `omim` - Online Mendelian Inheritance in Man
267
+ - `hpo` - Human Phenotype Ontology
268
+ - `gnomad` - Population frequency
269
+ - `alphamissense` - AI pathogenicity prediction
270
+ - `cadd` - Combined annotation dependent depletion
271
+ - `sift` - Protein function prediction
272
+ - `polyphen2` - Protein structure-based prediction
273
+ - `spliceai` - Deep learning splice prediction
274
+
275
+ ### Pharmacogenomics
276
+ **Description**: Drug response prediction
277
+
278
+ **Recommended Annotators**:
279
+ - `pharmgkb` - PharmGKB clinical annotations
280
+ - `dgi` - Drug-gene interaction database
281
+ - `clinvar` - Clinical significance
282
+ - `gnomad` - Population frequency
283
+
284
+ ### Autism
285
+ **Description**: Autism spectrum disorder
286
+
287
+ **Recommended Annotators**:
288
+ - `clinvar` - Clinical significance
289
+ - `omim` - Disease-gene associations
290
+ - `hpo` - Phenotype ontology
291
+ - `gnomad` - Population frequency
292
+ - `denovo` - De novo mutation annotations
293
+ - `alphamissense` - AI pathogenicity prediction
294
+ - `cadd` - Combined annotation
295
+
296
+ ### Developmental Delay
297
+ **Description**: Developmental delay and intellectual disability
298
+
299
+ **Recommended Annotators**:
300
+ - `clinvar` - Clinical significance
301
+ - `omim` - Disease-gene associations
302
+ - `hpo` - Phenotype ontology
303
+ - `gnomad` - Population frequency
304
+ - `denovo` - De novo mutations
305
+ - `alphamissense` - AI pathogenicity prediction
306
+ - `spliceai` - Splice site predictions
307
+
308
+ ---
309
+
310
+ ## Analysis Type Recommendations
311
+
312
+ ### Rare Coding
313
+ **Description**: Rare coding variant analysis
314
+
315
+ **Recommended Annotators**:
316
+ - `clinvar` - Clinical significance
317
+ - `gnomad` - Population frequency filtering
318
+ - `alphamissense` - AI pathogenicity
319
+ - `revel` - Ensemble score
320
+ - `cadd` - Deleteriousness score
321
+ - `sift` - Function prediction
322
+ - `polyphen2` - Structure-based prediction
323
+ - `vest` - Ensemble predictor
324
+
325
+ ### Splicing
326
+ **Description**: Splicing variant analysis
327
+
328
+ **Recommended Annotators**:
329
+ - `clinvar` - Clinical significance
330
+ - `spliceai` - Deep learning splice prediction
331
+ - `dbscsnv` - Splice consensus regions
332
+ - `gnomad` - Population frequency
333
+
334
+ ### Regulatory
335
+ **Description**: Regulatory variant analysis
336
+
337
+ **Recommended Annotators**:
338
+ - `encode_tfbs` - Transcription factor binding sites
339
+ - `ensembl_regulatory_build` - Regulatory features
340
+ - `regulomedb` - Regulatory elements
341
+ - `vista_enhancer` - Validated enhancers
342
+ - `gnomad` - Population frequency
343
+
344
+ ### De Novo
345
+ **Description**: De novo variant analysis
346
+
347
+ **Recommended Annotators**:
348
+ - `clinvar` - Clinical significance
349
+ - `denovo` - De novo mutation database
350
+ - `gnomad` - Population frequency (should be absent)
351
+ - `alphamissense` - AI pathogenicity
352
+ - `cadd` - Deleteriousness score
353
+
354
+ ---
355
+
356
+ ## Claude API Integration
357
+
358
+ ### Usage in Job Creation
359
+
360
+ When a user creates a BioOS job with `biofs job create`, Claude API should:
361
+
362
+ 1. **Parse the prompt** to identify phenotype or analysis type
363
+ 2. **Query annotator_recommendations** endpoint
364
+ 3. **Generate annotator list** for OpenCRAVAT pipeline
365
+
366
+ **Example Flow**:
367
+
368
+ ```python
369
+ # User prompt
370
+ prompt = "Annotate VCF for hereditary cancer predisposition"
371
+
372
+ # Claude API extracts phenotype
373
+ phenotype = "hereditary_cancer"
374
+
375
+ # Query recommendations
376
+ response = requests.get(
377
+ "https://genobank.app/api_bioos/annotator_recommendations",
378
+ params={"phenotype": phenotype}
379
+ )
380
+
381
+ recommended = response.json()["status_details"]["data"]["recommended_annotators"]
382
+ # ['clinvar', 'brca1_func_assay', 'cgc', 'cosmic', 'gnomad', 'alphamissense', 'revel']
383
+
384
+ # Create job with recommended annotators
385
+ job_data = {
386
+ "prompt": prompt,
387
+ "input_files": [...],
388
+ "pipeline": {
389
+ "steps": [{
390
+ "service": "vcf_annotator",
391
+ "action": "annotate",
392
+ "params": {
393
+ "annotators": recommended
394
+ }
395
+ }]
396
+ }
397
+ }
398
+ ```
399
+
400
+ ### Natural Language Mapping
401
+
402
+ Claude API should map user prompts to phenotypes/analysis types:
403
+
404
+ | User Keywords | Maps To |
405
+ |---------------|---------|
406
+ | "cancer", "tumor", "oncology" | `phenotype=cancer` |
407
+ | "heart", "cardiac", "cardiovascular" | `phenotype=cardiovascular` |
408
+ | "BRCA", "hereditary cancer" | `phenotype=hereditary_cancer` |
409
+ | "rare disease", "Mendelian" | `phenotype=rare_disease` |
410
+ | "drug", "medication", "pharmacogenomics" | `phenotype=pharmacogenomics` |
411
+ | "autism", "ASD" | `phenotype=autism` |
412
+ | "developmental delay", "intellectual disability" | `phenotype=developmental_delay` |
413
+ | "rare coding" | `analysis_type=rare_coding` |
414
+ | "splice", "splicing" | `analysis_type=splicing` |
415
+ | "regulatory", "non-coding" | `analysis_type=regulatory` |
416
+ | "de novo", "trio" | `analysis_type=de_novo` |
417
+
418
+ ---
419
+
420
+ ## Testing
421
+
422
+ ```bash
423
+ # Test annotator recommendations
424
+ curl "https://genobank.app/api_bioos/annotator_recommendations?phenotype=cancer" | jq
425
+
426
+ # Test dictionary browsing
427
+ curl "https://genobank.app/api_bioos/annotator_dictionary?category=cancer" | jq
428
+
429
+ # Test specific annotator
430
+ curl "https://genobank.app/api_bioos/annotator_dictionary?name=alphamissense" | jq
431
+
432
+ # List all options
433
+ curl "https://genobank.app/api_bioos/annotator_recommendations" | jq
434
+ ```
435
+
436
+ ---
437
+
438
+ ## Benefits
439
+
440
+ 1. **Intelligent Recommendations**: Claude API provides context-aware annotator selection
441
+ 2. **Comprehensive Coverage**: 146 OpenCRAVAT annotators categorized and documented
442
+ 3. **Phenotype-Driven**: Recommendations based on clinical context
443
+ 4. **Analysis-Driven**: Recommendations based on variant type
444
+ 5. **Flexible Queries**: Browse by category, name, or get full dictionary
445
+ 6. **Up-to-date**: Annotator versions and citations included
446
+
447
+ ---
448
+
449
+ ## Example Conversations
450
+
451
+ ### User: "Annotate my VCF for autism genes"
452
+
453
+ **Claude API**:
454
+ 1. Extracts phenotype: `autism`
455
+ 2. Queries: `/api_bioos/annotator_recommendations?phenotype=autism`
456
+ 3. Receives recommended annotators: `['clinvar', 'omim', 'hpo', 'gnomad', 'denovo', 'alphamissense', 'cadd']`
457
+ 4. Creates job with recommended annotator pipeline
458
+
459
+ ### User: "Find pathogenic splicing variants"
460
+
461
+ **Claude API**:
462
+ 1. Extracts analysis type: `splicing`
463
+ 2. Queries: `/api_bioos/annotator_recommendations?analysis_type=splicing`
464
+ 3. Receives recommended annotators: `['clinvar', 'spliceai', 'dbscsnv', 'gnomad']`
465
+ 4. Creates job with splicing-focused annotators
466
+
467
+ ### User: "What annotators are available for cancer?"
468
+
469
+ **Claude API**:
470
+ 1. Queries: `/api_bioos/annotator_dictionary?category=cancer`
471
+ 2. Returns 26 cancer-related annotators with full details
472
+ 3. User can browse and select specific ones
473
+
474
+ ---
475
+
476
+ ## Next Steps
477
+
478
+ 1. ✅ Dictionary built with 146 annotators
479
+ 2. ✅ API endpoints created
480
+ 3. ⏳ Restart production API to load endpoints
481
+ 4. ⏳ Test endpoints with curl
482
+ 5. ⏳ Integrate with Claude API for intelligent recommendations
483
+ 6. ⏳ Update CLI documentation
484
+
485
+ ---
486
+
487
+ **Version**: 1.0.0
488
+ **Last Updated**: 2025-10-07
489
+ **Total Annotators**: 146
490
+ **API Base**: `https://genobank.app/api_bioos/`