@genobank/biofs 1.2.6 β 1.2.8
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.
- package/ANNOTATOR_RECOMMENDATIONS_API.md +490 -0
- package/BIOFS_V1.2.7_PUBLISHED.md +317 -0
- package/BIOOS_CLI_IMPLEMENTATION_COMPLETE.md +422 -0
- package/BIOOS_JOB_MANAGEMENT.md +681 -0
- package/INSTALL_V1.2.7_ON_MAC.md +306 -0
- package/OPENCRAVAT_ANNOTATORS_REFERENCE.md +340 -0
- package/OPENCRAVAT_ANNOTATOR_INTELLIGENCE_COMPLETE.md +479 -0
- package/README.md +27 -0
- package/RELEASE_SUMMARY_V1.2.7.md +479 -0
- package/dist/commands/job/create.d.ts +7 -0
- package/dist/commands/job/create.d.ts.map +1 -0
- package/dist/commands/job/create.js +108 -0
- package/dist/commands/job/create.js.map +1 -0
- package/dist/commands/job/list.d.ts +7 -0
- package/dist/commands/job/list.d.ts.map +1 -0
- package/dist/commands/job/list.js +135 -0
- package/dist/commands/job/list.js.map +1 -0
- package/dist/commands/job/pipelines.d.ts +5 -0
- package/dist/commands/job/pipelines.d.ts.map +1 -0
- package/dist/commands/job/pipelines.js +77 -0
- package/dist/commands/job/pipelines.js.map +1 -0
- package/dist/commands/job/results.d.ts +6 -0
- package/dist/commands/job/results.d.ts.map +1 -0
- package/dist/commands/job/results.js +101 -0
- package/dist/commands/job/results.js.map +1 -0
- package/dist/commands/job/status.d.ts +6 -0
- package/dist/commands/job/status.d.ts.map +1 -0
- package/dist/commands/job/status.js +139 -0
- package/dist/commands/job/status.js.map +1 -0
- package/dist/index.js +94 -2
- package/dist/index.js.map +1 -1
- package/dist/lib/api/client.d.ts +9 -0
- package/dist/lib/api/client.d.ts.map +1 -1
- package/dist/lib/api/client.js +58 -0
- package/dist/lib/api/client.js.map +1 -1
- package/opencravat_annotators_dictionary.json +2356 -0
- package/package.json +1 -1
- package/scripts/build_annotator_dictionary.py +352 -0
|
@@ -0,0 +1,681 @@
|
|
|
1
|
+
# BioOS Job Management - CLI Guide
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
BioOS (Bio Operating System) is GenoBank's research pipeline orchestration platform that allows you to run complex bioinformatics workflows using natural language prompts. The BioFS CLI provides comprehensive job management commands to create, monitor, and retrieve results from research jobs.
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- π€ **Natural Language Jobs**: Create jobs using plain English prompts
|
|
10
|
+
- π **Pipeline Templates**: Pre-configured workflows for common analyses
|
|
11
|
+
- π **Real-time Monitoring**: Watch job progress with live status updates
|
|
12
|
+
- π₯ **Presigned Downloads**: Secure S3 download URLs for results
|
|
13
|
+
- βοΈ **Story Protocol Lineage**: Track IP asset lineage across pipeline steps
|
|
14
|
+
- π **Flexible File Input**: Support for BioCID, IP IDs, and filenames
|
|
15
|
+
|
|
16
|
+
## Available Commands
|
|
17
|
+
|
|
18
|
+
### 1. `biofs job pipelines` - List Pipeline Templates
|
|
19
|
+
|
|
20
|
+
List all available pipeline templates with detailed step-by-step breakdown.
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# Default formatted output
|
|
24
|
+
biofs job pipelines
|
|
25
|
+
|
|
26
|
+
# JSON output
|
|
27
|
+
biofs job pipelines --json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**Example Output:**
|
|
31
|
+
```
|
|
32
|
+
π§ Available Pipeline Templates:
|
|
33
|
+
|
|
34
|
+
ββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββ¬βββββββββ
|
|
35
|
+
β Template ID β Name β Description β Steps β
|
|
36
|
+
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββΌβββββββββ€
|
|
37
|
+
β fastq_to_report β FASTQ to Clinical Report β Process FASTQ β VCF β Annotation β Clinical Repβ¦ β 2 β
|
|
38
|
+
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββΌβββββββββ€
|
|
39
|
+
β vcf_annotation β VCF Annotation β Annotate VCF with rare coding variants β 1 β
|
|
40
|
+
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββΌβββββββββ€
|
|
41
|
+
β vcf_alphagenome β VCF with AlphaMissense Scorβ¦ β Annotate VCF and score with AlphaMissense β 2 β
|
|
42
|
+
ββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββ΄βββββββββ
|
|
43
|
+
|
|
44
|
+
Pipeline Details:
|
|
45
|
+
|
|
46
|
+
fastq_to_report - FASTQ to Clinical Report
|
|
47
|
+
Process FASTQ β VCF β Annotation β Clinical Report
|
|
48
|
+
Steps:
|
|
49
|
+
1. clara (variant_calling) β
|
|
50
|
+
2. vcf_annotator (annotate)
|
|
51
|
+
|
|
52
|
+
Usage Examples:
|
|
53
|
+
|
|
54
|
+
# FASTQ to Clinical Report
|
|
55
|
+
biofs job create "Process FASTQ β VCF β Annotation β Clinical Report" <file> --pipeline fastq_to_report
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Options:**
|
|
59
|
+
- `--json` - Output as JSON for programmatic use
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
### 2. `biofs job create` - Create Research Job
|
|
64
|
+
|
|
65
|
+
Create a research job from a natural language prompt and input file.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
# Using pipeline template
|
|
69
|
+
biofs job create "Annotate VCF with rare coding variants" sample.vcf --pipeline vcf_annotation
|
|
70
|
+
|
|
71
|
+
# Custom natural language prompt
|
|
72
|
+
biofs job create "Find pathogenic variants in cancer genes" sample.vcf
|
|
73
|
+
|
|
74
|
+
# Using BioCID
|
|
75
|
+
biofs job create "Analyze trio for autism genes" biocid://story/bioip/abc123/trio.vcf
|
|
76
|
+
|
|
77
|
+
# Using IP Asset ID
|
|
78
|
+
biofs job create "Score variants with AlphaMissense" 0x89224559242246F93479Fc44B0d8a1AFF5950faB
|
|
79
|
+
|
|
80
|
+
# JSON output
|
|
81
|
+
biofs job create "Annotate VCF" sample.vcf --json
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**File Input Formats:**
|
|
85
|
+
|
|
86
|
+
1. **Filename**: `sample.vcf` - Searches your uploaded files
|
|
87
|
+
2. **BioCID**: `biocid://story/bioip/{registration_id}/file.vcf` - Direct BioIP reference
|
|
88
|
+
3. **IP Asset ID**: `0x...` - Story Protocol IP asset
|
|
89
|
+
|
|
90
|
+
**Options:**
|
|
91
|
+
- `--pipeline <template>` - Use predefined pipeline template
|
|
92
|
+
- `--json` - Output job details as JSON
|
|
93
|
+
|
|
94
|
+
**Example Output:**
|
|
95
|
+
```
|
|
96
|
+
β Job created successfully!
|
|
97
|
+
|
|
98
|
+
Job Details:
|
|
99
|
+
Job ID: 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12
|
|
100
|
+
Status: pending
|
|
101
|
+
Prompt: Annotate VCF with rare coding variants
|
|
102
|
+
File: sample.vcf (VCF)
|
|
103
|
+
|
|
104
|
+
Track progress:
|
|
105
|
+
biofs job status 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12
|
|
106
|
+
|
|
107
|
+
Watch live updates:
|
|
108
|
+
biofs job status 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12 --watch
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
### 3. `biofs job status` - Check Job Status
|
|
114
|
+
|
|
115
|
+
Monitor job execution status with optional real-time watching.
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
# Single status check
|
|
119
|
+
biofs job status <job_id>
|
|
120
|
+
|
|
121
|
+
# Watch mode (refresh every 5 seconds)
|
|
122
|
+
biofs job status <job_id> --watch
|
|
123
|
+
|
|
124
|
+
# JSON output
|
|
125
|
+
biofs job status <job_id> --json
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Example Output:**
|
|
129
|
+
```
|
|
130
|
+
π Job Status: 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12
|
|
131
|
+
|
|
132
|
+
Status: βΆοΈ RUNNING
|
|
133
|
+
Progress: Step 2/3
|
|
134
|
+
|
|
135
|
+
Pipeline: [ββββββββββββββββββββββββββββββ] 67%
|
|
136
|
+
|
|
137
|
+
Story Protocol Lineage:
|
|
138
|
+
ββ 0xC91940118822D247B46d1eBA6B7Ed2A16F3aDC36 (VCF)
|
|
139
|
+
ββ 0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12269 (Annotation)
|
|
140
|
+
|
|
141
|
+
Output Files:
|
|
142
|
+
ββββββββ¬βββββββββββββββββββββ¬ββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββ
|
|
143
|
+
β Step β Service β File Type β IP Asset β
|
|
144
|
+
ββββββββΌβββββββββββββββββββββΌββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββ€
|
|
145
|
+
β 1 β vcf_annotator β sqlite β 0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12... β
|
|
146
|
+
ββββββββ΄βββββββββββββββββββββ΄ββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββ
|
|
147
|
+
|
|
148
|
+
Created: 2025-10-07 12:34:56
|
|
149
|
+
Updated: 2025-10-07 12:45:23
|
|
150
|
+
|
|
151
|
+
β³ Job is still running...
|
|
152
|
+
Watch mode: biofs job status 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12 --watch
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
**Options:**
|
|
156
|
+
- `--watch` - Refresh status every 5 seconds until completion
|
|
157
|
+
- `--json` - Output as JSON
|
|
158
|
+
|
|
159
|
+
**Status Types:**
|
|
160
|
+
- `β³ pending` - Job queued, waiting to start
|
|
161
|
+
- `βΆοΈ running` - Job actively executing
|
|
162
|
+
- `β
completed` - Job finished successfully
|
|
163
|
+
- `β failed` - Job encountered an error
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
### 4. `biofs job results` - Download Job Results
|
|
168
|
+
|
|
169
|
+
Get job results with presigned S3 download URLs and file verification hashes.
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
# Get all results
|
|
173
|
+
biofs job results <job_id>
|
|
174
|
+
|
|
175
|
+
# Get specific step only
|
|
176
|
+
biofs job results <job_id> --step 2
|
|
177
|
+
|
|
178
|
+
# JSON output
|
|
179
|
+
biofs job results <job_id> --json
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
**Example Output:**
|
|
183
|
+
```
|
|
184
|
+
π₯ Job Results: 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12
|
|
185
|
+
|
|
186
|
+
Story Protocol Lineage:
|
|
187
|
+
ββ 0xC91940118822D247B46d1eBA6B7Ed2A16F3aDC36
|
|
188
|
+
ββ 0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12269
|
|
189
|
+
ββ 0x495B1E8C54b572d78B16982BFb97908823C9358A
|
|
190
|
+
|
|
191
|
+
Output Files (2):
|
|
192
|
+
|
|
193
|
+
ββββββββ¬ββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββ¬βββββββββββ
|
|
194
|
+
β Step β File Type β IP Asset ID β Download β
|
|
195
|
+
ββββββββΌββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββΌβββββββββββ€
|
|
196
|
+
β 1 β sqlite β 0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12269 β [1] β
|
|
197
|
+
ββββββββΌββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββΌβββββββββββ€
|
|
198
|
+
β 2 β csv β 0x495B1E8C54b572d78B16982BFb97908823C9358A β [2] β
|
|
199
|
+
ββββββββ΄ββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββ΄βββββββββββ
|
|
200
|
+
|
|
201
|
+
Download Instructions:
|
|
202
|
+
|
|
203
|
+
[1] Step 1 - sqlite:
|
|
204
|
+
curl -o output_step1.sqlite "https://s3.amazonaws.com/presigned-url-1..."
|
|
205
|
+
|
|
206
|
+
[2] Step 2 - csv:
|
|
207
|
+
curl -o output_step2.csv "https://s3.amazonaws.com/presigned-url-2..."
|
|
208
|
+
|
|
209
|
+
File Verification (SHA256):
|
|
210
|
+
|
|
211
|
+
Step 1: a5b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890
|
|
212
|
+
Step 2: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd
|
|
213
|
+
|
|
214
|
+
π‘ Tip: URLs expire in 1 hour. Use them promptly or re-run this command.
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
**Options:**
|
|
218
|
+
- `--step <number>` - Download specific step only
|
|
219
|
+
- `--json` - Output as JSON
|
|
220
|
+
|
|
221
|
+
**Response Fields:**
|
|
222
|
+
- **IP Lineage**: Story Protocol IP asset chain
|
|
223
|
+
- **Output Files**: Generated files from each pipeline step
|
|
224
|
+
- **Download URLs**: Presigned S3 URLs (1-hour expiry)
|
|
225
|
+
- **File Hashes**: SHA256 checksums for verification
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
### 5. `biofs job list` - List All Jobs
|
|
230
|
+
|
|
231
|
+
List all your research jobs with filtering and status summary.
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
# List all jobs
|
|
235
|
+
biofs job list
|
|
236
|
+
|
|
237
|
+
# Filter by status
|
|
238
|
+
biofs job list --status completed
|
|
239
|
+
biofs job list --status running
|
|
240
|
+
|
|
241
|
+
# Limit results
|
|
242
|
+
biofs job list --limit 10
|
|
243
|
+
|
|
244
|
+
# JSON output
|
|
245
|
+
biofs job list --json
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
**Example Output:**
|
|
249
|
+
```
|
|
250
|
+
π¬ Your Research Jobs (5):
|
|
251
|
+
|
|
252
|
+
ββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββ¬βββββββββββββ¬βββββββββββ¬βββββββββββββββββββ
|
|
253
|
+
β Job ID β Prompt β Status β Progress β Created β
|
|
254
|
+
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββΌβββββββββββββΌβββββββββββΌβββββββββββββββββββ€
|
|
255
|
+
β 66f9e300-8b0e-4... β Annotate VCF with rare coding variants β β
completedβ 3/3 β 2025-10-07 β
|
|
256
|
+
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββΌβββββββββββββΌβββββββββββΌβββββββββββββββββββ€
|
|
257
|
+
β 77g8f411-9c1f-5... β Process FASTQ to clinical report β βΆοΈ running β 1/2 β 2025-10-07 β
|
|
258
|
+
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββΌβββββββββββββΌβββββββββββΌβββββββββββββββββββ€
|
|
259
|
+
β 88h9g522-0d2g-6... β Find autism genes in trio β β³ pending β N/A β 2025-10-06 β
|
|
260
|
+
ββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββ΄βββββββββββββ΄βββββββββββ΄βββββββββββββββββββ
|
|
261
|
+
|
|
262
|
+
Summary:
|
|
263
|
+
β³ Pending: 1
|
|
264
|
+
βΆοΈ Running: 1
|
|
265
|
+
β
Completed: 3
|
|
266
|
+
|
|
267
|
+
Active Jobs:
|
|
268
|
+
β’ 77g8f411-9c... - biofs job status 77g8f411-9c1f-5d3e-a7b4-6c8d9e1f2a3b
|
|
269
|
+
|
|
270
|
+
Download Results:
|
|
271
|
+
β’ 66f9e300-8b... - biofs job results 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
**Options:**
|
|
275
|
+
- `--status <status>` - Filter by: `pending`, `running`, `completed`, `failed`
|
|
276
|
+
- `--limit <number>` - Limit number of results
|
|
277
|
+
- `--json` - Output as JSON
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## Common Workflows
|
|
282
|
+
|
|
283
|
+
### Workflow 1: VCF Annotation Pipeline
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
# 1. Check available pipelines
|
|
287
|
+
biofs job pipelines
|
|
288
|
+
|
|
289
|
+
# 2. Create annotation job
|
|
290
|
+
biofs job create "Annotate VCF with rare coding variants" sample.vcf \
|
|
291
|
+
--pipeline vcf_annotation
|
|
292
|
+
|
|
293
|
+
# Output: Job ID: 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12
|
|
294
|
+
|
|
295
|
+
# 3. Watch progress
|
|
296
|
+
biofs job status 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12 --watch
|
|
297
|
+
|
|
298
|
+
# 4. Download results when complete
|
|
299
|
+
biofs job results 66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### Workflow 2: FASTQ to Clinical Report
|
|
303
|
+
|
|
304
|
+
```bash
|
|
305
|
+
# 1. Create full pipeline job
|
|
306
|
+
biofs job create "Process FASTQ to VCF to clinical report" reads_R1.fastq.gz \
|
|
307
|
+
--pipeline fastq_to_report
|
|
308
|
+
|
|
309
|
+
# 2. Monitor with JSON output for automation
|
|
310
|
+
biofs job status <job_id> --json | jq '.status'
|
|
311
|
+
|
|
312
|
+
# 3. Download specific step results
|
|
313
|
+
biofs job results <job_id> --step 2
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Workflow 3: AlphaMissense Variant Scoring
|
|
317
|
+
|
|
318
|
+
```bash
|
|
319
|
+
# 1. Create scoring job
|
|
320
|
+
biofs job create "Score variants with AlphaMissense" annotated.vcf \
|
|
321
|
+
--pipeline vcf_alphagenome
|
|
322
|
+
|
|
323
|
+
# 2. Check all jobs
|
|
324
|
+
biofs job list --status running
|
|
325
|
+
|
|
326
|
+
# 3. Download final scored results
|
|
327
|
+
biofs job results <job_id>
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
### Workflow 4: Custom Natural Language Job
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
# No template needed - BioOS interprets the prompt
|
|
334
|
+
biofs job create "Find pathogenic variants in BRCA1 and BRCA2 genes" sample.vcf
|
|
335
|
+
|
|
336
|
+
# Watch execution
|
|
337
|
+
biofs job status <job_id> --watch
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## Pipeline Templates
|
|
343
|
+
|
|
344
|
+
### Available Templates
|
|
345
|
+
|
|
346
|
+
#### 1. `fastq_to_report` - FASTQ to Clinical Report
|
|
347
|
+
**Description**: Complete pipeline from raw sequencing to clinical report
|
|
348
|
+
**Steps**:
|
|
349
|
+
1. **Clara**: Variant calling (FASTQ β VCF)
|
|
350
|
+
2. **VCF Annotator**: Annotation and clinical interpretation
|
|
351
|
+
|
|
352
|
+
**Use Case**: Whole genome/exome sequencing analysis
|
|
353
|
+
|
|
354
|
+
```bash
|
|
355
|
+
biofs job create "Process FASTQ to clinical report" sample_R1.fastq.gz \
|
|
356
|
+
--pipeline fastq_to_report
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
#### 2. `vcf_annotation` - VCF Annotation
|
|
360
|
+
**Description**: Annotate VCF with rare coding variants
|
|
361
|
+
**Steps**:
|
|
362
|
+
1. **VCF Annotator**: OpenCRAVAT annotation with rare coding package
|
|
363
|
+
|
|
364
|
+
**Use Case**: Annotating pre-called VCF files
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
biofs job create "Annotate VCF with rare coding variants" sample.vcf \
|
|
368
|
+
--pipeline vcf_annotation
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
#### 3. `vcf_alphagenome` - VCF with AlphaMissense Scoring
|
|
372
|
+
**Description**: Annotate VCF and score with AlphaMissense AI
|
|
373
|
+
**Steps**:
|
|
374
|
+
1. **VCF Annotator**: OpenCRAVAT annotation
|
|
375
|
+
2. **AlphaGenome**: AlphaMissense pathogenicity scoring
|
|
376
|
+
|
|
377
|
+
**Use Case**: AI-powered variant pathogenicity prediction
|
|
378
|
+
|
|
379
|
+
```bash
|
|
380
|
+
biofs job create "Annotate and score variants with AlphaMissense" sample.vcf \
|
|
381
|
+
--pipeline vcf_alphagenome
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
## Story Protocol Integration
|
|
387
|
+
|
|
388
|
+
### IP Asset Lineage
|
|
389
|
+
|
|
390
|
+
BioOS automatically creates Story Protocol IP assets for each pipeline step, establishing a parent-child relationship:
|
|
391
|
+
|
|
392
|
+
```
|
|
393
|
+
VCF File (Parent IP)
|
|
394
|
+
ββ Annotated SQLite (Child IP)
|
|
395
|
+
ββ Clinical Report CSV (Grandchild IP)
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
Each IP asset:
|
|
399
|
+
- Inherits PIL license terms from parent
|
|
400
|
+
- Generates royalties for parent owners
|
|
401
|
+
- Is tokenized as NFT on Story Protocol
|
|
402
|
+
- Has immutable metadata on IPFS
|
|
403
|
+
|
|
404
|
+
### Viewing IP Lineage
|
|
405
|
+
|
|
406
|
+
```bash
|
|
407
|
+
# View full lineage in job status
|
|
408
|
+
biofs job status <job_id>
|
|
409
|
+
|
|
410
|
+
# View lineage in results
|
|
411
|
+
biofs job results <job_id>
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
**Example Lineage Output:**
|
|
415
|
+
```
|
|
416
|
+
Story Protocol Lineage:
|
|
417
|
+
ββ 0xC91940118822D247B46d1eBA6B7Ed2A16F3aDC36 (VCF)
|
|
418
|
+
ββ 0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12269 (SQLite)
|
|
419
|
+
ββ 0x495B1E8C54b572d78B16982BFb97908823C9358A (CSV)
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
---
|
|
423
|
+
|
|
424
|
+
## File Input Reference
|
|
425
|
+
|
|
426
|
+
### 1. Filename
|
|
427
|
+
```bash
|
|
428
|
+
biofs job create "Annotate VCF" sample.vcf
|
|
429
|
+
```
|
|
430
|
+
Searches your uploaded files for matching filename.
|
|
431
|
+
|
|
432
|
+
### 2. BioCID (Bio Content Identifier)
|
|
433
|
+
```bash
|
|
434
|
+
biofs job create "Annotate VCF" biocid://story/bioip/abc123/sample.vcf
|
|
435
|
+
```
|
|
436
|
+
Direct reference to BioIP-registered file.
|
|
437
|
+
|
|
438
|
+
**Format**: `biocid://story/bioip/{registration_id}/{filename}`
|
|
439
|
+
|
|
440
|
+
### 3. IP Asset ID
|
|
441
|
+
```bash
|
|
442
|
+
biofs job create "Score variants" 0x89224559242246F93479Fc44B0d8a1AFF5950faB
|
|
443
|
+
```
|
|
444
|
+
Reference file by Story Protocol IP asset ID.
|
|
445
|
+
|
|
446
|
+
---
|
|
447
|
+
|
|
448
|
+
## JSON Output Format
|
|
449
|
+
|
|
450
|
+
All commands support `--json` flag for programmatic use:
|
|
451
|
+
|
|
452
|
+
### Job Create Response
|
|
453
|
+
```json
|
|
454
|
+
{
|
|
455
|
+
"job_id": "66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12",
|
|
456
|
+
"status": "pending",
|
|
457
|
+
"message": "Job created successfully",
|
|
458
|
+
"prompt": "Annotate VCF with rare coding variants",
|
|
459
|
+
"input_files": [{
|
|
460
|
+
"name": "sample.vcf",
|
|
461
|
+
"type": "vcf",
|
|
462
|
+
"path": "s3://bucket/path/sample.vcf"
|
|
463
|
+
}]
|
|
464
|
+
}
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
### Job Status Response
|
|
468
|
+
```json
|
|
469
|
+
{
|
|
470
|
+
"job_id": "66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12",
|
|
471
|
+
"status": "running",
|
|
472
|
+
"current_step": 1,
|
|
473
|
+
"total_steps": 3,
|
|
474
|
+
"ip_lineage": [
|
|
475
|
+
"0xC91940118822D247B46d1eBA6B7Ed2A16F3aDC36",
|
|
476
|
+
"0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12269"
|
|
477
|
+
],
|
|
478
|
+
"output_files": [{
|
|
479
|
+
"step": 1,
|
|
480
|
+
"service": "vcf_annotator",
|
|
481
|
+
"file_type": "sqlite",
|
|
482
|
+
"ip_id": "0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12269"
|
|
483
|
+
}],
|
|
484
|
+
"created_at": "2025-10-07T12:34:56Z",
|
|
485
|
+
"updated_at": "2025-10-07T12:45:23Z"
|
|
486
|
+
}
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
### Job Results Response
|
|
490
|
+
```json
|
|
491
|
+
{
|
|
492
|
+
"job_id": "66f9e300-8b0e-4ce8-9b6c-5a7b9d4c8e12",
|
|
493
|
+
"status": "completed",
|
|
494
|
+
"ip_lineage": [
|
|
495
|
+
"0xC91940118822D247B46d1eBA6B7Ed2A16F3aDC36",
|
|
496
|
+
"0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12269",
|
|
497
|
+
"0x495B1E8C54b572d78B16982BFb97908823C9358A"
|
|
498
|
+
],
|
|
499
|
+
"results": [{
|
|
500
|
+
"step": 1,
|
|
501
|
+
"file_type": "sqlite",
|
|
502
|
+
"ip_id": "0xB8d03f2E1C02e4cC5b5fe1613c575c01BDD12269",
|
|
503
|
+
"download_url": "https://s3.amazonaws.com/...",
|
|
504
|
+
"file_hash": "a5b3c4d5e6f7890abcdef1234567890..."
|
|
505
|
+
}]
|
|
506
|
+
}
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
---
|
|
510
|
+
|
|
511
|
+
## Troubleshooting
|
|
512
|
+
|
|
513
|
+
### Job Creation Fails
|
|
514
|
+
|
|
515
|
+
**Error**: `File not found`
|
|
516
|
+
```bash
|
|
517
|
+
# Solution: List your files first
|
|
518
|
+
biofs files
|
|
519
|
+
|
|
520
|
+
# Then use exact filename
|
|
521
|
+
biofs job create "Annotate VCF" exact-filename.vcf
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
**Error**: `Invalid pipeline template`
|
|
525
|
+
```bash
|
|
526
|
+
# Solution: List available pipelines
|
|
527
|
+
biofs job pipelines
|
|
528
|
+
|
|
529
|
+
# Use correct template ID
|
|
530
|
+
biofs job create "..." file.vcf --pipeline vcf_annotation
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
### Job Status Not Updating
|
|
534
|
+
|
|
535
|
+
```bash
|
|
536
|
+
# Solution: Check with JSON output for raw data
|
|
537
|
+
biofs job status <job_id> --json
|
|
538
|
+
|
|
539
|
+
# Or watch mode for live updates
|
|
540
|
+
biofs job status <job_id> --watch
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
### Download URLs Expired
|
|
544
|
+
|
|
545
|
+
**Error**: `403 Forbidden` when downloading
|
|
546
|
+
```bash
|
|
547
|
+
# Solution: Re-generate presigned URLs (1-hour expiry)
|
|
548
|
+
biofs job results <job_id>
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
### Job Stuck in Pending
|
|
552
|
+
|
|
553
|
+
```bash
|
|
554
|
+
# Check all jobs to see system status
|
|
555
|
+
biofs job list
|
|
556
|
+
|
|
557
|
+
# Contact support if stuck >10 minutes
|
|
558
|
+
# Include job ID: support@genobank.io
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
---
|
|
562
|
+
|
|
563
|
+
## Advanced Usage
|
|
564
|
+
|
|
565
|
+
### Automation with Shell Scripts
|
|
566
|
+
|
|
567
|
+
```bash
|
|
568
|
+
#!/bin/bash
|
|
569
|
+
# automated_pipeline.sh
|
|
570
|
+
|
|
571
|
+
# Create job and extract job ID
|
|
572
|
+
JOB_ID=$(biofs job create "Annotate VCF" sample.vcf --json | jq -r '.job_id')
|
|
573
|
+
|
|
574
|
+
echo "Created job: $JOB_ID"
|
|
575
|
+
|
|
576
|
+
# Poll until complete
|
|
577
|
+
while true; do
|
|
578
|
+
STATUS=$(biofs job status $JOB_ID --json | jq -r '.status')
|
|
579
|
+
echo "Status: $STATUS"
|
|
580
|
+
|
|
581
|
+
if [ "$STATUS" = "completed" ]; then
|
|
582
|
+
break
|
|
583
|
+
elif [ "$STATUS" = "failed" ]; then
|
|
584
|
+
echo "Job failed!"
|
|
585
|
+
exit 1
|
|
586
|
+
fi
|
|
587
|
+
|
|
588
|
+
sleep 30
|
|
589
|
+
done
|
|
590
|
+
|
|
591
|
+
# Download results
|
|
592
|
+
biofs job results $JOB_ID --json | jq -r '.results[].download_url' | while read URL; do
|
|
593
|
+
curl -O "$URL"
|
|
594
|
+
done
|
|
595
|
+
|
|
596
|
+
echo "Pipeline complete!"
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
### Parallel Job Processing
|
|
600
|
+
|
|
601
|
+
```bash
|
|
602
|
+
# Submit multiple jobs
|
|
603
|
+
for vcf in *.vcf; do
|
|
604
|
+
biofs job create "Annotate VCF" "$vcf" --pipeline vcf_annotation --json
|
|
605
|
+
done
|
|
606
|
+
|
|
607
|
+
# Monitor all jobs
|
|
608
|
+
biofs job list --status running --json | jq -r '.jobs[].job_id' | while read JOB; do
|
|
609
|
+
biofs job status $JOB
|
|
610
|
+
done
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
### Integration with CI/CD
|
|
614
|
+
|
|
615
|
+
```yaml
|
|
616
|
+
# .github/workflows/genomic-analysis.yml
|
|
617
|
+
name: Genomic Analysis
|
|
618
|
+
on: [push]
|
|
619
|
+
|
|
620
|
+
jobs:
|
|
621
|
+
analyze:
|
|
622
|
+
runs-on: ubuntu-latest
|
|
623
|
+
steps:
|
|
624
|
+
- uses: actions/checkout@v2
|
|
625
|
+
|
|
626
|
+
- name: Install BioFS
|
|
627
|
+
run: npm install -g @genobank/biofs
|
|
628
|
+
|
|
629
|
+
- name: Authenticate
|
|
630
|
+
run: |
|
|
631
|
+
echo "$GENOBANK_CREDENTIALS" > ~/.genobank/credentials.json
|
|
632
|
+
|
|
633
|
+
- name: Run Analysis
|
|
634
|
+
run: |
|
|
635
|
+
JOB_ID=$(biofs job create "Annotate VCF" sample.vcf --json | jq -r '.job_id')
|
|
636
|
+
|
|
637
|
+
# Wait for completion
|
|
638
|
+
while [ "$(biofs job status $JOB_ID --json | jq -r '.status')" != "completed" ]; do
|
|
639
|
+
sleep 60
|
|
640
|
+
done
|
|
641
|
+
|
|
642
|
+
# Download results
|
|
643
|
+
biofs job results $JOB_ID
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
---
|
|
647
|
+
|
|
648
|
+
## API Integration
|
|
649
|
+
|
|
650
|
+
The BioOS CLI communicates with these API endpoints:
|
|
651
|
+
|
|
652
|
+
- `POST /api_bioos/create_job` - Create new job
|
|
653
|
+
- `GET /api_bioos/job_status?job_id=<id>` - Get status
|
|
654
|
+
- `GET /api_bioos/job_results?job_id=<id>` - Get results
|
|
655
|
+
- `GET /api_bioos/pipeline_list` - List templates
|
|
656
|
+
- `GET /api_bioos/user_jobs` - List user jobs
|
|
657
|
+
|
|
658
|
+
All endpoints require `user_signature` authentication.
|
|
659
|
+
|
|
660
|
+
---
|
|
661
|
+
|
|
662
|
+
## Support
|
|
663
|
+
|
|
664
|
+
- **Interactive API Guide**: https://genobank.app/static/Genobank_API_Educational_Guide.html
|
|
665
|
+
- **GitHub Issues**: https://github.com/genobank/genobank-cli/issues
|
|
666
|
+
- **Email**: support@genobank.io
|
|
667
|
+
- **Documentation**: https://docs.genobank.io
|
|
668
|
+
|
|
669
|
+
---
|
|
670
|
+
|
|
671
|
+
## Version History
|
|
672
|
+
|
|
673
|
+
### v1.2.6 - BioOS Job Management
|
|
674
|
+
- Added `biofs job create` command
|
|
675
|
+
- Added `biofs job status` with watch mode
|
|
676
|
+
- Added `biofs job results` with presigned URLs
|
|
677
|
+
- Added `biofs job list` with filtering
|
|
678
|
+
- Added `biofs job pipelines` template listing
|
|
679
|
+
- Story Protocol lineage tracking
|
|
680
|
+
- Support for BioCID, IP IDs, and filenames
|
|
681
|
+
- JSON output for all commands
|