BioFS-CLI v3.18.0 Manual of Operations

Complete Role-Based Operator Reference & Visual State Flow Protocols

Authors: Daniel Uribe (CEO GenoBank.io) & GenoBank.io Engineering Team • Version: v3.18.0 • Target RPC: Sequentia L1 Chain 15132025

← Technical Whitepaper Live Verbs Audit Dashboard →
👥 Defined System Roles & Wallet Contexts
👤 Patient (Data Owner)

Wallet: 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a

Owns biological samples and BioNFTs. Sets BioPIL license terms, manages consent via ConsentManager, executes GDPR Art. 17 right to erasure, receives 95% x402 revenue micropayments, and owns QLoRA Digital Twins.

🔬 Researcher 1 (Precigenetics Accredited Lab)

Wallet: 0x3175d040471FcFCa44E82cdcFB060fD214c9bEa5

Holds an accredited LabNFT credential. Uploads raw FASTQ/BAM sequencing reads, executes high-coverage WES/WGS GPU pipelines, builds OpenCRAVAT SQLite databases, and refreshes lab coverage stores.

🏛️ Researcher 2 (Secondary Academic / Pharma)

Wallet: 0x0947ca077c8a3ce19e84cd4e518f0986dc9f4089

Requests time-bounded research access licenses via BioPIL, pays x402 USDC micropayments, streams ROSA sub-chunk byte ranges over QUIC, and computes Cosic-RRM biophysical spectroscopy.

🤖 AI Agent / BioOS Worker Node

Wallet: 0x2A2ec4669e883d06f9c8996114Fc56398Ec8A583

Autonomous AI worker registered on Sequentia BioAgentNFT contract. Executes NVIDIA Parabricks GPU variant calling, trains per-patient QLoRA Digital Twin adapters, and applies ACMG evidence stacks.

📋 Quick Jump Table of Contents (11 Domains)

1. Local Configuration & Session Management

biofs config Environment Configuration Manager
Utility & Operational Purpose: Manages local developer and operator configuration parameters stored in ~/.biofsrc, including active RPC endpoints, default reference genomes (hg38 / T2T-CHM13), timeout thresholds, and local vault mount paths.
graph LR USER["Operator / Developer"] -->|biofs config set rpcUrl| CFG["Local Config (~/.biofsrc)"] CFG -->|Read Config| CLI["biofs-cli v3.18.0"] CLI -->|Connect Target Network| RPC["Sequentia RPC (https://seqrpc.genobank.app)"]
# Role Execution Examples:
[PATIENT] biofs config set rpcUrl https://seqrpc.genobank.app
[PATIENT] biofs config get rpcUrl
[RESEARCHER-1] biofs config list
biofs login Session Identity Authentication
Utility & Operational Purpose: Authenticates active user session using EIP-712 wallet signatures, Magic links, WebAuthn Passkeys, Tangem NFC hardware cards, or academic ORCID bindings. Establishes session keystore tokens for subsequent BioNFT queries.
graph TD USER["User / Operator"] -->|Provide Signature / Passkey| AUTH["BioFS Auth Client"] AUTH -->|Verify EIP-712 Signature| SEC["Sequentia KeyStore"] SEC -->|Issue Session Token| TOKEN["Active Session (~/.biofs/session.json)"]
# Role Execution Examples:
[PATIENT] biofs login --wallet 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a
[RESEARCHER-1] biofs login --orcid 0000-0002-1825-0097 --wallet 0x3175d040471FcFCa44E82cdcFB060fD214c9bEa5
biofs logout Session Key Purge
Utility & Operational Purpose: Safely terminates active user session, purges cached private keys and EIP-712 authorization bearer tokens from local memory and ~/.biofs/session.json.
graph LR USER["User"] -->|Execute biofs logout| CLI["biofs-cli"] CLI -->|Purge Keys & Bearer Token| MEM["Local Keystore Purge"] MEM -->|Session Terminated| OUT["Logged Out State"]
# Role Execution Examples:
[PATIENT] biofs logout
biofs whoami Active Session Identity Inspection
Utility & Operational Purpose: Inspects active session credentials, displaying the bound EVM wallet address, ORCID academic identity, assigned protocol roles (Patient, LabNFT Holder, Researcher), active Sequentia Chain ID (15132025), and session token expiration.
graph LR CLI["biofs whoami"] -->|Inspect Session| KEY["~/.biofs/session.json"] KEY -->|Read Chain State| CHAIN["Sequentia L1"] CHAIN -->|Display Credentials| OUT["Display Address, Roles, Chain ID"]
# Role Execution Examples:
[RESEARCHER-1] biofs whoami
biofs researcher Academic & Industrial Accreditation Profile
Utility & Operational Purpose: Registers and verifies academic/industrial researcher profiles on Sequentia, linking institutional credentials (ORCID, LinkedIn, Google Scholar) to a Web3 wallet address for requesting BioPIL research licenses.
graph TD R2["Researcher 2"] -->|biofs researcher register| ORCID["ORCID Verification"] ORCID -->|Submit Verification| REG["BioAgentRegistry / LabNFT Registry"] REG -->|Store Accreditation| CHAIN["Sequentia L1 On-Chain Identity"]
# Role Execution Examples:
[RESEARCHER-2] biofs researcher register --orcid 0000-0001-9283-4812 --institution 'Stanford Genomics'
[RESEARCHER-2] biofs researcher status --wallet 0x3175d040471FcFCa44E82cdcFB060fD214c9bEa5

2. BioNFT Tokenization & Asset Management

biofs tokenize BioNFT Asset Creation & Registration
Utility & Operational Purpose: Tokenizes raw or compressed genomic files (VCF, BAM, CRAM, DICOM) into a sovereign BioNFT on Sequentia. Computes content-addressed sha256 payload digests, generates 1024-bit Bloom filter DNA fingerprints, registers initial ownership, and establishes BioPIL licensing terms.
graph TD PAT["Patient / Lab"] -->|Select Payload File| RAW["sample_brca1.vcf.gz"] RAW -->|Compute sha256 & Bloom Fingerprint| CID["BioCID Generation"] CID -->|Mint BioNFT & Register Routes| CONTRACT["BioCIDRegistry (0x6Fb5...004b)"] CONTRACT -->|Return Token ID & BioCID| PAT
# Role Execution Examples:
[PATIENT] biofs tokenize sample_brca1.vcf.gz --license NON_COMMERCIAL_SOCIAL_REMIXING --royalty-bps 500
[RESEARCHER-1] biofs tokenize patient_wgs.bam --biosample SERIAL-928124 --license CLINICAL_USE
biofs tokenize-biosample Physical Specimen Serial Binding
Utility & Operational Purpose: Tokenizes raw physical biosample metadata and binds physical collection kit barcode serial numbers (e.g., saliva collection tubes, blood vials) to an on-chain BioNFT before sequencing data is generated.
graph LR LAB["Clinical Lab"] -->|Physical Barcode Serial| KIT["Serial: KIT-882914-US"] KIT -->|Register On-Chain Specimen| VAULT["BioAssetVault (0x2fd9...5850)"] VAULT -->|Mint Custodial BioNFT| BIOWALLET["Patient Biowallet"]
# Role Execution Examples:
[RESEARCHER-1] biofs tokenize-biosample KIT-882914-US --patient-wallet 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a
biofs tokenize-fastqs Paired-End Read Tokenization
Utility & Operational Purpose: Tokenizes paired-end Illumina/Element sequencing reads (R1.fastq.gz and R2.fastq.gz), calculating combined cryptographic Merkle tree roots for raw read pairs before alignment.
graph TD R1["read_R1.fastq.gz"] & R2["read_R2.fastq.gz"] -->|Compute Merkle Root| MERKLE["Merkle Root Digest"] MERKLE -->|Register Paired Read BioNFT| REG["BioCIDRegistry"] REG -->|Output BioCID| LAB["Lab Manifest"]
# Role Execution Examples:
[RESEARCHER-1] biofs tokenize-fastqs patient_R1.fastq.gz patient_R2.fastq.gz --biosample SERIAL-928124
biofs ls BioNFT Inventory & Grant Explorer
Utility & Operational Purpose: Lists all tokenized BioNFT assets owned by or granted to the target wallet address, including BioCIDs, file formats, creation timestamps, active storage routes, and BioPIL license terms.
graph LR USER["User / Wallet"] -->|biofs ls --wallet 0x5f5a...| CLI["biofs-cli"] CLI -->|Query On-Chain Inventory| CHAIN["BioCIDRegistry & BioPIL"] CHAIN -->|Return Active BioNFTs| OUT["Display Table of BioNFTs"]
# Role Execution Examples:
[PATIENT] biofs ls --wallet 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a
[RESEARCHER-2] biofs ls --granted-only --json
biofs get License-Validated Biofile Download
Utility & Operational Purpose: Resolves BioRoutes storage URIs, validates active BioPIL license tokens and patient consent state, decrypts payload, and downloads the biofile onto local storage.
graph TD R2["Researcher 2"] -->|biofs get biocid_123| NODE["biofs-node (QUIC)"] NODE -->|Check License & Consent| CHAIN["BioPIL & ConsentManager"] CHAIN -->|Consent Valid| STORAGE["GCS / S3 Storage"] STORAGE -->|Stream Encrypted Bytes| R2
# Role Execution Examples:
[RESEARCHER-2] biofs get biocid_brca1_wes_001 --output ./downloads/brca1.vcf.gz
biofs cat UNIX Stdout Stream Piping
Utility & Operational Purpose: Streams decrypted BioNFT payload directly to standard output (stdout) for UNIX pipe chaining into downstream bioinformatics commands (e.g., bcftools, samtools, grep).
graph LR CLI["biofs cat biocid_123"] -->|Stream Decrypted Payload| STDOUT["stdout Pipe"] STDOUT -->|Pipe Input| BCFTOOLS["bcftools view -v snps"]
# Role Execution Examples:
[RESEARCHER-2] biofs cat biocid_brca1_wes_001 | bcftools view -r chr17:43044295-43125483
biofs rm GDPR Article 17 Right to be Forgotten
Utility & Operational Purpose: Executes GDPR Article 17 Right to Erasure. Sets patient consent flag to consentRevoked = true on-chain, invalidates BioPIL license tokens, burns access credentials, and instructs remote biofs-node storage gateways to purge cached BGZF index files.
graph TD PAT["Patient"] -->|biofs rm biocid_123| CONSENT["ConsentManager (0x2ff3...19cd)"] CONSENT -->|Set consentRevoked = true| CHAIN["Sequentia L1 State"] CHAIN -->|Revoke License Verification| PIL["BioPIL Engine"] PIL -->|Purge Storage Caches| NODE["biofs-node Gateways"]
# Role Execution Examples:
[PATIENT] biofs rm biocid_brca1_wes_001 --confirm-erasure
biofs inspect BioNFT Metadata & Provenance Audit
Utility & Operational Purpose: Displays comprehensive metadata, Bloom filter DNA fingerprints, sha256 payload digests, active BioRoutes storage URIs, and full lineage provenance for a specified BioCID.
graph LR CLI["biofs inspect biocid_123"] -->|Fetch On-Chain Record| REG["BioCIDRegistry"] REG -->|Return Metadata & Fingerprint| OUT["Display Lineage, Hashes, Routes"]
# Role Execution Examples:
[PATIENT] biofs inspect biocid_brca1_wes_001
biofs bionft Direct Smart Contract Token Interaction
Utility & Operational Purpose: Direct interaction with Sequentia BioNFT smart contracts to query token ownership state, view active PIL terms, or execute patient-signed on-chain token revocations.
graph LR USER["User"] -->|biofs bionft status --token 42| CONTRACT["BioNFT Contract (0x1e74...B00A)"] CONTRACT -->|Return Token Owner & PIL URI| USER
# Role Execution Examples:
[PATIENT] biofs bionft status --token-id 1042
[PATIENT] biofs bionft revoke --token-id 1042
biofs context EIP-712 BioContext Manifest Publisher
Utility & Operational Purpose: Builds, verifies, publishes, and revokes EIP-712 signed .bionft BioContext clinical manifests linking clinical phenotyping notes, VCF variants, and DICOM studies into unified case files.
graph TD CLINICIAN["Clinical Lab"] -->|Create BioContext| MANIFEST["case_manifest.json"] MANIFEST -->|Sign EIP-712| SIG["EIP-712 Signature"] SIG -->|Publish BioContext| CHAIN["Sequentia BioContext Registry"]
# Role Execution Examples:
[RESEARCHER-1] biofs context create --case-id CASE-9912 --patient 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a
[RESEARCHER-1] biofs context publish --manifest ./case_manifest.bionft

3. Access Control & Permission Management

biofs access Granular Permission Manager
Utility & Operational Purpose: Manages delegate wallet permissions, grants research access to target addresses, checks permission validity, or executes full patient consent revocation.
graph TD PAT["Patient"] -->|biofs access grant| DELEGATE["Researcher 2 (0x0947...)"] DELEGATE -->|Check Permission| CONSENT["ConsentManager (0x2ff3...19cd)"] CONSENT -->|Grant Granted| ACCESS["Active Access Session"]
# Role Execution Examples:
[PATIENT] biofs access grant biocid_brca1_wes_001 --delegate 0x0947ca077c8a3ce19e84cd4e518f0986dc9f4089 --duration 30d
[PATIENT] biofs access list --wallet 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a
biofs share BioPIL Research Sharing Engine
Utility & Operational Purpose: Shares BioNFT assets with accredited research institutions or pharma labs, minting a time-bounded BioPIL license token with custom royalty parameters.
graph LR PAT["Patient"] -->|biofs share biocid_123| LAB["Precigenetics Lab (0x3175...)"] LAB -->|Mint BioPIL License Token| PIL["BioPIL Smart Contract (0x6474...)"] PIL -->|Issue License ID| LAB
# Role Execution Examples:
[PATIENT] biofs share biocid_brca1_wes_001 --lab 0x3175d040471FcFCa44E82cdcFB060fD214c9bEa5 --license RESEARCH_USE
biofs shares Permission Graph Explorer
Utility & Operational Purpose: Displays the complete BioNFT permission graph across all assets (all files shared by you and all files shared with you).
graph LR USER["User"] -->|biofs shares| CLI["biofs-cli"] CLI -->|Traverse Permission Graph| GRAPH["Sequentia Sharing Graph"] GRAPH -->|Display Incoming & Outgoing Grants| OUT["Interactive Table"]
# Role Execution Examples:
[PATIENT] biofs shares --json
biofs labnfts Accredited Lab Directory
Utility & Operational Purpose: Queries verified research institutions, clinical laboratories, and biobanks holding active LabNFT credentials on Sequentia.
graph LR CLI["biofs labnfts"] -->|Query Accredited Labs| REG["LabNFT Registry"] REG -->|Return Accredited Labs| OUT["Precigenetics, Stanford, Broad, UCSF"]
# Role Execution Examples:
[RESEARCHER-2] biofs labnfts
biofs lab High-Coverage FASTQ Stream Refresher
Utility & Operational Purpose: Triggers high-coverage FASTQ replacement streaming from lab primary origin S3 buckets directly into Google Cloud Storage mirrors.
graph TD LAB["Lab Node"] -->|biofs lab refresh-coverage| ORIGIN["Lab S3 Origin"] ORIGIN -->|Stream High-Coverage FASTQs| MIRROR["GCS Primary Mirror"] MIRROR -->|Update BioRoutes Route| ROUTER["BioRoutes Contract"]
# Role Execution Examples:
[RESEARCHER-1] biofs lab refresh-coverage --lab-id LAB-PRECIGENETICS
biofs ticket Single-Use Privacy Ticket Manager
Utility & Operational Purpose: Generates, lists, or burns single-use zero-knowledge privacy tickets (BioNFTCredentials-bound access tokens) for isolated clinical queries.
graph LR PAT["Patient"] -->|Issue Privacy Ticket| TICKET["Single-Use Ticket"] TICKET -->|Redeem Ticket| R2["Researcher 2"] R2 -->|Burn Ticket| CHAIN["On-Chain Ticket Burn"]
# Role Execution Examples:
[PATIENT] biofs ticket create --biocid biocid_123 --recipient 0x0947ca077c8a3ce19e84cd4e518f0986dc9f4089
[RESEARCHER-2] biofs ticket list
biofs cred Scoped Write Upload Credential Issuer
Utility & Operational Purpose: Issues scoped, write-only upload credentials enabling accredited sequencing laboratories to upload raw FASTQ/BAM payloads directly into patient vaults.
graph TD PAT["Patient"] -->|Issue Write Credential| CRED["Scoped Upload Credential"] CRED -->|Upload FASTQ/BAM| LAB["Sequencing Lab"] LAB -->|Write Directly to Vault| VAULT["Patient Vault (GCS / S3)"]
# Role Execution Examples:
[PATIENT] biofs cred issue --lab 0x3175d040471FcFCa44E82cdcFB060fD214c9bEa5 --expires 7d
[RESEARCHER-1] biofs cred list

4. Storage Routing & FUSE Directory Vault

biofs vault Local Directory Vault Scaffolder
Utility & Operational Purpose: Scaffolds and manages local ~/genobank/vault directory structure holding patient-owned BioNFT assets.
graph LR CLI["biofs vault setup"] -->|Scaffold Tree| DIR["~/genobank/vault/"] DIR -->|Subdirectories| SUB["/vcf, /bam, /fastq, /dicom"] SUB -->|Mount GCS Fuse| MOUNT["gcsfuse Mount Points"]
# Role Execution Examples:
[PATIENT] biofs vault setup
[PATIENT] biofs vault status
biofs mount POSIX FUSE Filesystem Mount
Utility & Operational Purpose: Mounts remote BioNFT storage via POSIX FUSE / gcsfuse onto local filesystem directory for direct file access by standard UNIX tools.
graph TD R2["Researcher 2"] -->|biofs mount ./vault| FUSE["gcsfuse Kernel Module"] FUSE -->|Authenticate EIP-712| NODE["biofs-node"] NODE -->|Expose POSIX Filesystem| FS["Local Directory ./vault"]
# Role Execution Examples:
[RESEARCHER-2] biofs mount ~/genobank/vault/brca1
biofs mount-remote Remote Cluster Gateway Mount
Utility & Operational Purpose: Mounts remote BioNFT storage gateways onto high-performance compute clusters (HPC) over SSH/gRPC tunnels.
graph LR HPC["HPC Cluster Node"] -->|biofs mount-remote| GATEWAY["biofs-node Remote Gateway"] GATEWAY -->|Stream QUIC Payload| HPC
# Role Execution Examples:
[RESEARCHER-2] biofs mount-remote --gateway https://seqrpc.genobank.app:4433 --target /mnt/hpc/biofs
biofs umount FUSE Unmount & Key Purge
Utility & Operational Purpose: Unmounts active FUSE storage directory, closes active QUIC byte streams, and purges transient decryption keys from kernel memory.
graph LR USER["User"] -->|biofs umount ./vault| FUSE["Unmount gcsfuse"] FUSE -->|Close QUIC Streams| NODE["biofs-node"] NODE -->|Purge Decryption Keys| MEM["Memory Purge"]
# Role Execution Examples:
[RESEARCHER-2] biofs umount ~/genobank/vault/brca1
biofs resolve On-Chain Storage Route Resolver
Utility & Operational Purpose: Queries Sequentia BioRoutes on-chain to resolve a BioCID or Bloom filter fingerprint to active storage URIs across PRIMARY, SECONDARY, ARCHIVE, and MIRROR tiers.
graph TD CLI["biofs resolve biocid_123"] -->|Query BioRoutes Contract| ROUTER["BioRoutes (0xF758...4BAD)"] ROUTER -->|Check Storage Tiers| TIERS["Primary: GCS | Secondary: S3 | Archive: IPFS"] TIERS -->|Return Active Storage URIs| CLI
# Role Execution Examples:
[PATIENT] biofs resolve biocid_brca1_wes_001
biofs route Storage Route Health Linter & Self-Healer
Utility & Operational Purpose: Lints and automatically repairs broken gcsfuse storage mounts and stale storage URIs across compute nodes.
graph LR CLI["biofs route check"] -->|Probe Storage Mounts| MOUNT["/mnt/gcsfuse-bioroutes/"] MOUNT -->|Mount Stale / Broken| HEAL["Execute Self-Healing Auto-Mount"] HEAL -->|Route Restored| OK["Route Healthy"]
# Role Execution Examples:
[RESEARCHER-1] biofs route check
[RESEARCHER-1] biofs route heal
biofs upload-fastq Resumable GCS Fast Upload
Utility & Operational Purpose: Uploads large FASTQ/BAM payloads via scoped write credentials using Google Cloud Storage resumable upload protocol.
graph TD LAB["Sequencing Lab"] -->|biofs upload-fastq| RESUMABLE["GCS Resumable Chunk Upload"] RESUMABLE -->|Upload Chunks| BUCKET["gcs-bucket: genobank-biovault"] BUCKET -->|Register New BioCID| REG["BioCIDRegistry"]
# Role Execution Examples:
[RESEARCHER-1] biofs upload-fastq --file raw_wgs_r1.fastq.gz --cred CRED-9912

5. BioOS Compute & Asynchronous GPU Pipelines

biofs pipeline End-to-End Agentic GPU Pipeline Runner
Utility & Operational Purpose: Executes end-to-end WES/WGS pipeline: FASTQ input -> NVIDIA Parabricks GPU alignment -> DeepVariant calling -> OpenCRAVAT annotation -> Vault registration -> QLoRA Digital Twin training.
graph TD FASTQ["FASTQ Read Pairs"] -->|Parabricks GPU| BAM["Aligned BAM"] BAM -->|DeepVariant| VCF["Variant Call Format (VCF)"] VCF -->|OpenCRAVAT| DB["SQLite Variant DB"] DB -->|Twin Adapter| TWIN["Patient QLoRA Twin"]
# Role Execution Examples:
[RESEARCHER-1] biofs pipeline run-wes --fastqs patient_R1.fastq.gz,patient_R2.fastq.gz --patient 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a
[RESEARCHER-1] biofs pipeline run-somatic --tumor tumor.bam --normal normal.bam
biofs job Asynchronous GPU Job Dispatcher
Utility & Operational Purpose: Dispatches, monitors, recalls, and reconciles asynchronous GPU variant calling and annotation jobs on BioOS worker nodes.
graph LR CLI["biofs job create"] -->|Dispatch Job Payload| WORKER["BioOS GPU Worker (Nebius / Parabricks)"] WORKER -->|Execute Parabricks| JOB["Job ID: JOB-8829"] JOB -->|Poll Status / Fetch Results| CLI
# Role Execution Examples:
[RESEARCHER-1] biofs job list
[RESEARCHER-1] biofs job submit-clara --ref hg38 --sample SAMPLE-101
biofs agent-health GPU Worker Node Readiness Probe
Utility & Operational Purpose: Checks readiness, available GPU VRAM, queue depth, and model weight initialization across background compute worker agents.
graph LR CLI["biofs agent-health"] -->|Probe GPU Worker| NODE["BioOS Compute Agent (0x2A2e...)"] NODE -->|Return VRAM & Queue Status| OUT["Display VRAM, GPU Temp, Queue Depth"]
# Role Execution Examples:
[AI-AGENT] biofs agent-health
biofs cohort-pipeline Cohort-Scale Batch Pipeline
Utility & Operational Purpose: Batch pipeline execution across a cohort of biosample serials with resume-awareness and automatic biowallet minting.
graph TD COHORT["Cohort Manifest (50 Samples)"] -->|Batch Dispatch| WORKER["Parabricks GPU Cluster"] WORKER -->|Parallel Variant Calling| VCFS["Multi-Sample VCFs"] VCFS -->|Automatic Minting| VAULT["BioAssetVault Biowallets"]
# Role Execution Examples:
[RESEARCHER-1] biofs cohort-pipeline --manifest cohort_50_samples.csv
biofs annotate OpenCRAVAT Clinical Variant Annotator
Utility & Operational Purpose: Annotates VCF variant files using OpenCRAVAT (curated clinical panels or all 146 annotators including ClinVar, gnomAD, COSMIC, PharmGKB).
graph LR VCF["raw.vcf"] -->|biofs annotate| CRAVAT["OpenCRAVAT Engine"] CRAVAT -->|146 Clinical Annotators| DB["annotated.sqlite"] DB -->|Generate Clinical Summary| OUT["ACMG Classification Input"]
# Role Execution Examples:
[RESEARCHER-2] biofs annotate patient.vcf --annotators clinvar,gnomad,cosmic,pharmgkb
biofs imaging PACS DICOM Imaging Acquisition
Utility & Operational Purpose: Acquires hospital DICOM medical imaging studies (e.g. UCSF eUnity PACS) into the patient vault via biofs-node.
graph TD HOSPITAL["Hospital PACS (eUnity)"] -->|Pull DICOM Series| NODE["biofs-node"] NODE -->|Encrypt & Tokenize DICOM| VAULT["Patient BioVault"] VAULT -->|Register DICOM BioCID| CHAIN["BioCIDRegistry"]
# Role Execution Examples:
[RESEARCHER-1] biofs imaging pull --study-uid 1.2.840.113619.2.55.3.28311021 --patient 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a

6. Patient Digital Twins & AI Intelligence

biofs twin Patient Digital Twin LLM Trainer
Utility & Operational Purpose: Trains a patient-owned Digital Twin LLM via per-patient QLoRA adapter across a 3-base LLM bake-off (Llama-3, MedGemma, Mistral) from grounded twin.json.
graph TD GROUNDED["twin.json Grounded Knowledge"] -->|QLoRA Fine-Tuning| GPU["Nebius GPU Cluster"] GPU -->|Train Per-Patient Adapter| ADAPTER["Patient QLoRA Adapter"] ADAPTER -->|Deploy Vault Model| TWIN["Patient Digital Twin AI"]
# Role Execution Examples:
[PATIENT] biofs twin train --patient 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a --base-model medgemma
[PATIENT] biofs twin status
biofs cancermap Grounded Cancer Map Generator
Utility & Operational Purpose: Regenerates agent-grade cancer map twin.json and grounded variant explorer for somatic precision oncology cases.
graph LR SOMATIC["Somatic VCF & CRAVAT DB"] -->|biofs cancermap regen| MAP["Grounded twin.json"] MAP -->|Parse Somatic Driver Mutations| EXPLORER["Grounded Cancer Explorer"]
# Role Execution Examples:
[RESEARCHER-1] biofs cancermap regen --case-id CANCER-CASE-01
biofs fluency Contig Coverage Conversational Indexer
Utility & Operational Purpose: Precomputes per-contig coverage and per-gene rollups to make genomic stores conversational for LLM agents.
graph TD VCF["Genomic VCF Store"] -->|biofs fluency build| INDEX["Fluency Index"] INDEX -->|Enable Conversational Queries| LLM["LLM AI Agent"] LLM -->|Ask: 'Summarize BRCA1 variants'| OUT["Instant Conversational Summary"]
# Role Execution Examples:
[RESEARCHER-2] biofs fluency build --biocid biocid_123
[RESEARCHER-2] biofs fluency state
biofs ancestry 24-Population Ancestry Projection
Utility & Operational Purpose: Computes SOMOS 24-population ancestry projections using supervised-ADMIXTURE or homomorphic CKKS blind encryption.
graph TD VCF["Patient VCF"] -->|Supervised ADMIXTURE| SOMOS["SOMOS 24-Population Engine"] SOMOS -->|CKKS Homomorphic Blind Encryption| PROJ["Ancestry Projections"] PROJ -->|Store Projections| VAULT["Patient Vault"]
# Role Execution Examples:
[PATIENT] biofs ancestry --vcf sample.vcf.gz
[PATIENT] biofs ancestry status
biofs somos SOMOS Population Genomics Integration
Utility & Operational Purpose: Direct SOMOS DAO population genomics integration for Hispanic, Latino, and underrepresented population ancestry calls.
graph LR VCF["Patient VCF"] -->|biofs somos| ENGINE["SOMOS Population Classifier"] ENGINE -->|Return Population Percentages| OUT["24 Sub-Population Percentages"]
# Role Execution Examples:
[PATIENT] biofs somos SERIAL-928124
biofs dissect Phenotype-Specific SNP Extractor
Utility & Operational Purpose: Extracts phenotype-specific SNP subsets using AI-powered discovery queries across multi-sample VCF stores.
graph LR VCF["Multi-Sample VCF"] -->|Query: 'Type 2 Diabetes SNPs'| AI["AI Phenotype Extractor"] AI -->|Filter VCF Records| SUBSET["Target SNP Subset VCF"]
# Role Execution Examples:
[RESEARCHER-2] biofs dissect 'Type 2 Diabetes risk loci' patient.vcf.gz
biofs match Zero-Knowledge SNP Matcher
Utility & Operational Purpose: Matches target SNPs against an owner corpus via Bloom filters without revealing non-matching genotypes.
graph TD QUERY["Target Risk SNPs"] -->|Query Bloom Filter| BLOOM["1024-bit DNA Bloom Filter"] BLOOM -->|Check Membership| MATCH["Zero-Knowledge Match Result"] MATCH -->|Reveal Only Matching SNPs| R2["Researcher 2"]
# Role Execution Examples:
[RESEARCHER-2] biofs match --target-snps rs1801133,rs429358 --biocid biocid_123

7. Biophysical Spectroscopy & Cosic-RRM Resonances

biofs fourier-score Cosic-RRM Biophysical Variant Scorer
Utility & Operational Purpose: Computes Cosic Resonant Recognition Model (EIIP + DFT) biophysical scoring for missense variants (Sum|Delta F|, Delta E%). Measures exact physical energy shifts caused by amino acid substitutions.
graph TD VARIANT["Missense Mutation (p.Val600Glu)"] -->|Map EIIP Energy| EIIP["EIIP Sequence Signal"] EIIP -->|Discrete Fourier Transform| DFT["DFT Power Spectrum"] DFT -->|Calculate Energy Shift Delta E%| SCORE["Cosic-RRM Biophysical Score"]
# Role Execution Examples:
[RESEARCHER-2] biofs fourier-score --gene BRCA1 --variant p.Asp1692His
[RESEARCHER-2] biofs fourier-score --vcf patient_missense.vcf
biofs rrm-consensus Characteristic Frequency (f_c) Extractor
Utility & Operational Purpose: Computes Cosic-RRM characteristic frequency f_c via cross-spectrum of a gene's functional protein family across homologous species.
graph LR FAMILY["Homologous Protein Family (M Sequences)"] -->|Cross-Spectrum Product| CROSS["S(k) Product Spectrum"] CROSS -->|Identify Prominent Peak| FC["Characteristic Frequency f_c"]
# Role Execution Examples:
[RESEARCHER-2] biofs rrm-consensus BRCA1
biofs psm-consensus Piezoelectric Signal Dipole Cross-Spectrum
Utility & Operational Purpose: Calculates Piezoelectric Signal Model characteristic frequency f_c via side-chain dipole cross-spectrum.
graph LR DIPOLES["Side-Chain Dipole Oscillations"] -->|PSM Cross-Spectrum| SPEC["Piezoelectric Spectrum"] SPEC -->|Extract Phonon Coupling Frequency| FC["PSM f_c"]
# Role Execution Examples:
[RESEARCHER-2] biofs psm-consensus BRCA1
biofs wavelet-consensus Morlet Continuous Wavelet Transform Map
Utility & Operational Purpose: Generates Morlet continuous wavelet transform consensus map (position by scale) for a gene family.
graph TD PROTEIN["Protein Sequence Signal"] -->|Morlet CWT| WAVELET["Continuous Wavelet Matrix"] WAVELET -->|Scale-Position Resonance Map| MAP["Spatial-Spectral Resonance Map"]
# Role Execution Examples:
[RESEARCHER-2] biofs wavelet-consensus BRCA1
biofs tokenize-spectrum Discrete Spectral Token Emitter
Utility & Operational Purpose: Emits LLM-friendly discrete spectral tokens representing protein biophysical resonance for input into generative AI transformers.
graph LR SPECTRUM["Protein Biophysical Spectrum"] -->|Quantize Peaks| TOKENS["LLM Spectral Tokens"] TOKENS -->|Pass to LLM Context| LLM["Transformer Model"]
# Role Execution Examples:
[RESEARCHER-2] biofs tokenize-spectrum BRCA1
biofs bode Transfer Function Log-Log Bode Plotter
Utility & Operational Purpose: Generates log-log Bode plot of protein-family transfer function |H(j w)| showing system frequency response.
graph LR TRANSFER["Transfer Function H(j w)"] -->|Compute Log Magnitude & Phase| BODE["Log-Log Bode Plot"] BODE -->|Export Image| OUT["bode_plot.png"]
# Role Execution Examples:
[RESEARCHER-2] biofs bode BRCA1
biofs rrm-distribution ClinVar Feature Synthesis Engine
Utility & Operational Purpose: Pulls ClinVar missense variants for a gene and computes Cosic-RRM biophysical features with gnomAD pseudo-benign synthesis.
graph TD CLINVAR["ClinVar Missense Variants"] -->|Compute RRM Features| MATRIX["Feature Matrix"] MATRIX -->|Synthesize gnomAD Benigns| TRAIN_SET["Balanced Training Set"]
# Role Execution Examples:
[RESEARCHER-2] biofs rrm-distribution BRCA1
biofs rrm-train Ensemble XGBoost Classifier Trainer
Utility & Operational Purpose: Trains XGBoost ensemble combining Cosic-RRM biophysical features with AlphaMissense, REVEL, and PrimateAI scores.
graph TD RRM["RRM Features"] & REVEL["REVEL / AlphaMissense"] -->|Combine Vector| XGB["XGBoost Trainer"] XGB -->|Train Ensemble Classifier| MODEL["Pathogenicity Model"]
# Role Execution Examples:
[RESEARCHER-2] biofs rrm-train BRCA1
biofs cohort-fourier-score Cohort Biophysical Spectral Scorer
Utility & Operational Purpose: Cohort-scale Cosic-RRM spectral scoring across multi-exome serials.
graph LR COHORT["Cohort VCFs"] -->|Batch Fourier Scoring| SCORES["Cohort RRM Score Matrix"]
# Role Execution Examples:
[RESEARCHER-1] biofs cohort-fourier-score --cohort-dir ./vcf_cohort/
biofs cohort-train Multi-Gene Benchmark Trainer
Utility & Operational Purpose: Multi-gene benchmark running rrm-consensus + rrm-distribution + rrm-train across a cohort.
graph TD GENES["Gene List (BRCA1, TP53, MSH2)"] -->|Multi-Gene Pipeline| BENCH["Cohort Benchmark Results"]
# Role Execution Examples:
[RESEARCHER-2] biofs cohort-train --genes BRCA1,TP53,MSH2

8. Clinical Genomics, ACMG & External Integrations

biofs clinical Phenotype-Driven ACMG/AMP Classifier
Utility & Operational Purpose: Executes phenotype-driven multi-exome ACMG/AMP 2015 + ClinGen-SVI 2024 variant classification (returns Pathogenic/Likely Pathogenic evidence stacks). NFT-gated, server-side execution.
graph TD PATIENT["Biosample Serial"] -->|Fetch VCF & HPO Phenotypes| ACMG["ACMG/AMP Evidence Engine"] ACMG -->|Evaluate PVS1, PS1, PM2, PP3| EVID["Evidence Stack"] EVID -->|Output Call| VERDICT["Pathogenic / Likely Pathogenic"]
# Role Execution Examples:
[RESEARCHER-1] biofs clinical SERIAL-928124 --hpo HP:0001250,HP:0001263
[RESEARCHER-1] biofs clinical SERIAL-928124 --json
biofs cohort-acmg Cohort Batch ACMG Classifier
Utility & Operational Purpose: Batch processes cohort biosamples: mints biowallets, extracts ClinVar P/LP, applies ACMG-SVI evidence stacks.
graph LR COHORT["Cohort Biosamples"] -->|Batch ACMG Execution| STACKS["ACMG Evidence Stacks"] STACKS -->|Output Summary Table| OUT["Cohort ACMG Report"]
# Role Execution Examples:
[RESEARCHER-1] biofs cohort-acmg --manifest cohort_manifest.csv
biofs variants OpenCRAVAT Variant Query Tool
Utility & Operational Purpose: Queries annotated variants from OpenCRAVAT SQLite database for a biosample with gene, region, Sequence Ontology, and ClinVar filters.
graph LR DB["OpenCRAVAT SQLite DB"] -->|biofs variants| FILTER["Filter: gene=BRCA1, clinvar=P"] FILTER -->|Return Matching Variants| OUT["JSON / Table Output"]
# Role Execution Examples:
[RESEARCHER-1] biofs variants SERIAL-928124 --gene BRCA1 --clinvar Pathogenic
biofs myvariant MyVariant.info REST API Queries
Utility & Operational Purpose: Queries MyVariant.info v1 API for single variants, gene-wide batches, or raw expressions.
graph LR CLI["biofs myvariant BRCA1"] -->|HTTP GET| MYVARIANT["MyVariant.info REST API"] MYVARIANT -->|Return ClinVar & gnomAD Annotations| OUT["Display Variant Annotations"]
# Role Execution Examples:
[RESEARCHER-2] biofs myvariant chr17:g.43044295G>A
[RESEARCHER-2] biofs myvariant BRCA1
biofs mavedb-ingest MaveDB Multiplex Assay Effect Lookups
Utility & Operational Purpose: Super-SCDS Multiplexed Assay of Variant Effect (MaveDB) data ingestion and functional effect lookups.
graph LR MAVEDB["MaveDB Repository"] -->|Ingest Assay Scores| SCDS["Super-SCDS Local Store"] SCDS -->|Lookup Variant Functional Effect| OUT["Display Assay Effect Score"]
# Role Execution Examples:
[RESEARCHER-1] biofs mavedb-ingest stats
[RESEARCHER-1] biofs mavedb-ingest query --variant p.Asp1692His
biofs mychart Epic MyChart FHIR Health Record Sync
Utility & Operational Purpose: Connects Epic MyChart FHIR health records, listing lab results, medications, and problem lists into the BioRouter registry.
graph TD EPIC["Epic MyChart FHIR Server"] -->|OAuth2 FHIR Connect| MYCHART["biofs mychart"] MYCHART -->|Parse Lab Results & Medications| VAULT["Patient Vault"] VAULT -->|Register Clinical Manifest| ROUTER["BioRouter Registry"]
# Role Execution Examples:
[PATIENT] biofs mychart connect --fhir-endpoint https://fhir.epic.com/interconnect-fhir-oauth/
[PATIENT] biofs mychart stats

9. Custodial Biowallets & Family Vaults

biofs biowallet De-Novo Biowallet Minter
Utility & Operational Purpose: Mints de-novo EIP-55 custodial biowallets (random keypairs, BIP-39 mnemonic, encrypted keystores) bound to biosample serials.
graph LR LAB["Lab / Patient"] -->|biofs biowallet create| KEYGEN["BIP-39 Key Generator"] KEYGEN -->|Derive EIP-55 Wallet| WALLET["Biowallet Address"] WALLET -->|Bind to Biosample Serial| VAULT["BioAssetVault"]
# Role Execution Examples:
[PATIENT] biofs biowallet create --serial SERIAL-928124
[PATIENT] biofs biowallet list
biofs family BIP-32 Family Vault Manager
Utility & Operational Purpose: Manages Family Vaults: single BIP-32 master mnemonic deriving N child biowallets via derivation path m/44'/60'/0'/0/index.
graph TD MASTER["Master Family Seed Phrase"] -->|BIP-32 Derivation m/44'/60'/0'/0/i| DERIVE["Child Biowallets"] DERIVE -->|Child 0: Father| W0["Biowallet 0"] DERIVE -->|Child 1: Mother| W1["Biowallet 1"] DERIVE -->|Child 2: Child A| W2["Biowallet 2"]
# Role Execution Examples:
[PATIENT] biofs family create --name 'Uribe Family Vault'
[PATIENT] biofs family derive --index 2 --label 'Child A'
biofs claim Custodial Biowallet Self-Custody Claim
Utility & Operational Purpose: Allows patients to claim custodial biowallets into self-custodial Web3 wallets or Tangem NFC hardware cards.
graph LR PATIENT["Patient Web3 Wallet"] -->|biofs claim 0x2A2e...| CUSTODIAL["Custodial Biowallet"] CUSTODIAL -->|Transfer Token Ownership| SELF_CUSTODY["Tangem NFC / Self-Custody Wallet"]
# Role Execution Examples:
[PATIENT] biofs claim 0x2A2ec4669e883d06f9c8996114Fc56398Ec8A583 --to 0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a

10. x402 Micropayments & Agent Economy

biofs payment x402 HTTP Micropayment Settlement
Utility & Operational Purpose: Executes x402 HTTP micropayments in USDC on Sequentia / Avalanche for biofile access or agent execution.
graph TD R2["Researcher 2"] -->|HTTP Request BioFile| ROUTER["x402 Router (0xe95f...8014)"] ROUTER -->|Require $1.00 USDC| PAYMENT["x402 Settlement"] PAYMENT -->|95% $0.95 USDC| PATIENT["Patient Biowallet"] PAYMENT -->|5% $0.05 USDC| TREASURY["Sequentia Treasury"]
# Role Execution Examples:
[RESEARCHER-2] biofs payment --biocid biocid_123 --amount 1.00 --currency USDC
biofs agent Autonomous BioAgent NFT Registry
Utility & Operational Purpose: Registers autonomous BioFS processing agents on Kite AI Network and Sequentia BioAgentNFT contract.
graph LR AGENT["AI Agent Worker"] -->|biofs agent register| REG["BioAgentRegistry (0x24e6...6B6B)"] REG -->|Mint BioAgentNFT| CHAIN["Sequentia L1 Agent Registry"]
# Role Execution Examples:
[AI-AGENT] biofs agent register --category VARIANT_ANNOTATOR --name 'OpenCRAVAT Worker 1'
[AI-AGENT] biofs agent list

11. Data Metamorphosis, Lineage & Verification

biofs lineage Biodata Metamorphosis Tree Reporter
Utility & Operational Purpose: Reports the biodata metamorphosis tree: derivation history, parent BioCIDs, owner graph, and cascading erasure dependencies.
graph TD FASTQ["Parent: FASTQ (BioCID-1)"] --> BAM["Derived: BAM (BioCID-2)"] BAM --> VCF["Derived: VCF (BioCID-3)"] VCF --> TWIN["Derived: Twin Adapter (BioCID-4)"]
# Role Execution Examples:
[PATIENT] biofs lineage biocid_vcf_001
biofs verify DNA Bloom Filter Integrity Verifier
Utility & Operational Purpose: Verifies local file integrity against on-chain DNA Bloom filter fingerprint.
graph LR FILE["Local biofile.vcf.gz"] -->|Compute Local Bloom Filter| LOCAL["Local Fingerprint"] LOCAL -->|Compare On-Chain| CHAIN["BioCIDRegistry Fingerprint"] CHAIN -->|Fingerprint Match| OK["Integrity Verified (PASS)"]
# Role Execution Examples:
[PATIENT] biofs verify biocid_123 ./local_file.vcf.gz
biofs view GDPR Right to Access Payload Viewer
Utility & Operational Purpose: Displays decrypted file contents in accordance with GDPR Right to Access.
graph LR PATIENT["Patient"] -->|biofs view biocid_123| NODE["biofs-node"] NODE -->|Decrypt Payload| SCREEN["Display Decrypted Records"]
# Role Execution Examples:
[PATIENT] biofs view biocid_brca1_wes_001