@genobank/biofs 2.5.0 → 2.5.1

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 (100) hide show
  1. package/CHANGELOG.md +2 -0
  2. package/LICENSE +37 -0
  3. package/README.md +2 -1
  4. package/bin/biofs.js +2 -1
  5. package/contracts/ClaraJobNFT.sol +2 -0
  6. package/dist/commands/link-clara.d.ts.map +1 -1
  7. package/dist/commands/link-clara.js +9 -3
  8. package/dist/commands/link-clara.js.map +1 -1
  9. package/dist/commands/tokenize-biosample.d.ts.map +1 -1
  10. package/dist/commands/tokenize-biosample.js +9 -3
  11. package/dist/commands/tokenize-biosample.js.map +1 -1
  12. package/dist/index.js +1 -1
  13. package/docs/AI_AGENT_MCP_MANUAL.md +2 -0
  14. package/docs/USER_MANUAL.md +2 -0
  15. package/docs/technical-details.html +555 -0
  16. package/lib/bionfs-client.js +2 -0
  17. package/lib/consent-manager.js +2 -0
  18. package/lib/consent-prompt.js +2 -0
  19. package/package.json +3 -3
  20. package/presentation/biofs-x402-kite-presentation.html +2 -0
  21. package/scripts/build_annotator_dictionary.py +1 -0
  22. package/scripts/deploy-clara-nft.js +2 -0
  23. package/test-complete-flow.sh +1 -1
  24. package/test.vcf +1 -0
  25. package/test_23andme.txt +1 -0
  26. package/ADMIN_REGISTER_LAB.md +0 -252
  27. package/ANNOTATOR_RECOMMENDATIONS_API.md +0 -490
  28. package/BIOFS_QUICK_START.md +0 -200
  29. package/BIOFS_TOKENIZE_COMPLETE.md +0 -541
  30. package/BIOFS_V1.2.7_PUBLISHED.md +0 -317
  31. package/BIOFS_V1.2.9_FIXES.md +0 -306
  32. package/BIOFS_V1.3.0_DIRECT_GRANT.md +0 -381
  33. package/BIOFS_V1.3.1_GRANTED_FILES.md +0 -328
  34. package/BIONFS_DEPLOYMENT_GUIDE.md +0 -408
  35. package/BIONFS_MOUNT_INTEGRATION_PLAN.md +0 -415
  36. package/BIONFS_PROTOCOL_SPECIFICATION.md +0 -688
  37. package/BIONFS_SEQUENTIAS_INTEGRATION.md +0 -457
  38. package/BIONFT_NFS_PROTOCOL_ARCHITECTURE.md +0 -583
  39. package/BIOOS_CLI_IMPLEMENTATION_COMPLETE.md +0 -422
  40. package/BIOOS_JOB_MANAGEMENT.md +0 -681
  41. package/BUGFIX_V2.1.3.md +0 -72
  42. package/CHANGELOG_V2.1.0.md +0 -386
  43. package/CHANGELOG_V2.2.0.md +0 -284
  44. package/ENHANCEMENT_DOCUMENTATION.md +0 -218
  45. package/GDPR_BIONFS_CONSENT_ARCHITECTURE.md +0 -798
  46. package/GDPR_BIONFS_IMPLEMENTATION_STATUS.md +0 -462
  47. package/INSTALL_V1.2.7_ON_MAC.md +0 -306
  48. package/LABNFT_BIOFS_INTEGRATION.md +0 -396
  49. package/OPENCRAVAT_ANNOTATORS_REFERENCE.md +0 -340
  50. package/OPENCRAVAT_ANNOTATOR_INTELLIGENCE_COMPLETE.md +0 -479
  51. package/QUICK_START_V2.1.0.md +0 -116
  52. package/RELEASE_SUMMARY_V1.2.7.md +0 -479
  53. package/RELEASE_SUMMARY_V1.3.0.md +0 -324
  54. package/SEQUENTIAS_PROTOCOL_ARCHITECTURE.md +0 -880
  55. package/SEQUENTIA_MIGRATION_GUIDE.md +0 -337
  56. package/SESSION_SUMMARY_DIRECT_GRANT.md +0 -321
  57. package/ULTRATHINK_BIONFS_COMPLETE.md +0 -458
  58. package/WEB3FUSE_LICENSE_TOKEN_ANALYSIS.md +0 -494
  59. package/WHERE_PERMISSIONS_LIVE.md +0 -165
  60. package/artifacts/@openzeppelin/contracts/access/Ownable.sol/Ownable.dbg.json +0 -4
  61. package/artifacts/@openzeppelin/contracts/access/Ownable.sol/Ownable.json +0 -63
  62. package/artifacts/@openzeppelin/contracts/interfaces/IERC4906.sol/IERC4906.dbg.json +0 -4
  63. package/artifacts/@openzeppelin/contracts/interfaces/IERC4906.sol/IERC4906.json +0 -328
  64. package/artifacts/@openzeppelin/contracts/token/ERC721/ERC721.sol/ERC721.dbg.json +0 -4
  65. package/artifacts/@openzeppelin/contracts/token/ERC721/ERC721.sol/ERC721.json +0 -357
  66. package/artifacts/@openzeppelin/contracts/token/ERC721/IERC721.sol/IERC721.dbg.json +0 -4
  67. package/artifacts/@openzeppelin/contracts/token/ERC721/IERC721.sol/IERC721.json +0 -296
  68. package/artifacts/@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol/IERC721Receiver.dbg.json +0 -4
  69. package/artifacts/@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol/IERC721Receiver.json +0 -45
  70. package/artifacts/@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol/ERC721URIStorage.dbg.json +0 -4
  71. package/artifacts/@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol/ERC721URIStorage.json +0 -373
  72. package/artifacts/@openzeppelin/contracts/token/ERC721/extensions/IERC721Metadata.sol/IERC721Metadata.dbg.json +0 -4
  73. package/artifacts/@openzeppelin/contracts/token/ERC721/extensions/IERC721Metadata.sol/IERC721Metadata.json +0 -341
  74. package/artifacts/@openzeppelin/contracts/utils/Address.sol/Address.dbg.json +0 -4
  75. package/artifacts/@openzeppelin/contracts/utils/Address.sol/Address.json +0 -10
  76. package/artifacts/@openzeppelin/contracts/utils/Context.sol/Context.dbg.json +0 -4
  77. package/artifacts/@openzeppelin/contracts/utils/Context.sol/Context.json +0 -10
  78. package/artifacts/@openzeppelin/contracts/utils/Strings.sol/Strings.dbg.json +0 -4
  79. package/artifacts/@openzeppelin/contracts/utils/Strings.sol/Strings.json +0 -10
  80. package/artifacts/@openzeppelin/contracts/utils/introspection/ERC165.sol/ERC165.dbg.json +0 -4
  81. package/artifacts/@openzeppelin/contracts/utils/introspection/ERC165.sol/ERC165.json +0 -30
  82. package/artifacts/@openzeppelin/contracts/utils/introspection/IERC165.sol/IERC165.dbg.json +0 -4
  83. package/artifacts/@openzeppelin/contracts/utils/introspection/IERC165.sol/IERC165.json +0 -30
  84. package/artifacts/@openzeppelin/contracts/utils/math/Math.sol/Math.dbg.json +0 -4
  85. package/artifacts/@openzeppelin/contracts/utils/math/Math.sol/Math.json +0 -10
  86. package/artifacts/@openzeppelin/contracts/utils/math/SignedMath.sol/SignedMath.dbg.json +0 -4
  87. package/artifacts/@openzeppelin/contracts/utils/math/SignedMath.sol/SignedMath.json +0 -10
  88. package/artifacts/build-info/1adfbc50ae3e1821260f858a9c689a37.json +0 -1
  89. package/artifacts/contracts/ClaraJobNFT.sol/ClaraJobNFT.dbg.json +0 -4
  90. package/artifacts/contracts/ClaraJobNFT.sol/ClaraJobNFT.json +0 -667
  91. package/cache/solidity-files-cache.json +0 -628
  92. package/check_clara2.js +0 -70
  93. package/check_clara3.js +0 -65
  94. package/config.json +0 -21
  95. package/hardhat.config.js +0 -25
  96. package/jest.config.js +0 -27
  97. package/mint_and_link_all.js +0 -128
  98. package/opencravat_annotators_dictionary.json +0 -2356
  99. package/package.json.working.v1.9.2.20251105_023952 +0 -48
  100. package/test_v2_mint.js +0 -101
@@ -1,681 +0,0 @@
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