Proto is not affiliated with NCBI. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.

### BLAST Search (`blast-search`) Aligns a query sequence against a reference database and returns the resulting hits. The remote execution mode submits the query to the NCBI BLAST web service through the QBLAST API. The local execution mode invokes the appropriate BLAST+ program (`blastn`, `blastp`, `blastx`, `tblastn`, or `tblastx`) against a user-supplied database. The query field accepts either a raw nucleotide or protein sequence string or a path to a FASTA file, and the input form is detected automatically. #### API Reference

Source A raw nucleotide/protein sequence (e.g. `"ATGCGTAAA"`) or a path to a FASTA file. Automatically set to `"sequence"` or `"fasta_path"` during validation. Read-only; do not set manually. Available options: `sequence`, `fasta_path`

Source `"online"` routes to NCBI QBLAST; `"local"` runs BLAST+ CLI against a local database. Available options: `online`, `local` BLAST algorithm (blastn, blastp, blastx, tblastn, tblastx). Available options: `blastn`, `blastp`, `blastx`, `tblastn`, `tblastx` NCBI database to search (online only). Available options: `nt`, `nr`, `refseq_rna`, `refseq_protein`, `swissprot`, `pdb`, `pataa`, `patnt` Restrict online search with an Entrez query. Number of hits to return (online only). Use MegaBLAST (online, blastn only). Path to a local BLAST database (local only, required). CPU threads for local search. E-value threshold (both modes). Word size for initial matches (both modes). Cost to open a gap (both modes). Cost to extend a gap (both modes). Scoring matrix for protein searches (both modes). Nucleotide match reward (blastn only, both modes). Nucleotide mismatch penalty (blastn only, both modes). Min word score for lookup table (protein only, both modes). Composition-based stats mode (protein only, both modes). Max aligned sequences to keep (local only). Min percent identity filter (both modes). Min query coverage per HSP (local only). Soft masking for initial matches (local only). Treat lowercase in FASTA as masked (both modes). Low-complexity filter for nucleotide queries (local only). Low-complexity filter for protein queries (local only). Task preset (local only). Ungapped alignment only (both modes). Query strand (local only; for blastn/blastx/tblastx). Genetic code for translating query (blastx/tblastx, both modes). Genetic code for translating DB (tblastn/tblastx, both modes). Verbatim BLAST+ CLI tokens for niche flags not exposed above (e.g. `["-max_hsps", "1"]`). Local mode only; online mode goes through `NCBIWWW.qblast` which doesn't accept arbitrary CLI tokens. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source BLAST alignment hits with standard tabular Query sequence ID. Subject sequence ID. Percentage of identical matches. Alignment length. Number of mismatches. Number of gap openings. Start of alignment in query. End of alignment in query. Start of alignment in subject. End of alignment in subject. Expect value. Bit score.

#### Applications This tool is the standard first step in any analysis that begins with an unknown sequence and asks what it resembles. Representative applications include functional annotation of a newly assembled gene through homology to characterised proteins, taxonomic identification of an environmental DNA fragment, off-target screening of a PCR primer or CRISPR guide against a reference genome, and tracing the evolutionary distribution of a gene across species. #### Usage Tips * **The `program` field must match the query and database types.** Mismatched combinations return no hits and waste a search. Use `blastn` for nucleotide-against-nucleotide, `blastp` for protein-against-protein, `blastx` for a nucleotide query against a protein database, `tblastn` for a protein query against a nucleotide database, and `tblastx` for translated nucleotide against translated nucleotide. * **Remote execution targets the NCBI BLAST web service and is limited by NCBI rate limits.** The `database` field selects from the hosted reference databases (`nt`, `nr`, `refseq_rna`, `refseq_protein`, `swissprot`, `pdb`, `pataa`, `patnt`). High-throughput or batch workloads should use local execution to avoid being throttled or blocked by NCBI. * **Local execution requires a `local_db` value pointing at a prebuilt database.** Build one with `blast-create-db` or download a prebuilt NCBI database. The path is the database stem with no file extension. The configuration validator hard-errors when `local_db` is missing in local mode. * **`evalue` is the primary parameter controlling sensitivity.** The BLAST+ default of `10.0` is permissive and returns spurious hits. Set it to `1e-5` or stricter to filter out alignments that would occur by chance, or use a higher value when searching for short or divergent matches. * **`extra_args` accepts verbatim BLAST+ CLI tokens and applies only in local execution.** Pass any CLI flag not exposed as a typed field through this list (for example `["-max_hsps", "1"]`). The remote QBLAST API does not accept arbitrary CLI tokens, so `extra_args` is ignored when `search_mode="online"` and the configuration validator emits a warning in that case.

### Create BLAST Database (`blast-create-db`) Builds a local BLAST database from a FASTA file using the BLAST+ `makeblastdb` program. The output is a set of indexed files referenced by a common stem path. The stem path is returned as `db_path` and can be passed directly as `local_db` to `blast-search`. #### API Reference

Source Path to a FASTA file containing the sequences to be indexed into a BLAST database. The file must exist and contain valid FASTA-formatted sequences. For nucleotide databases, sequences should be DNA or RNA. For protein databases, sequences should be amino acids.

Source `"nucl"` for DNA/RNA, `"prot"` for protein. Must match the input FASTA. Available options: `nucl`, `prot` File-path prefix for generated DB files; `None` falls back to the input FASTA stem. Descriptive DB title shown in BLAST reports; `makeblastdb` falls back to the input file name when `None`. Parse FASTA seq IDs so `blastdbcmd` can address sequences by ID; required for v5 taxonomy lookups. Create a hash index of seq IDs (faster ID lookups). DB format version. `5` (taxonomy- aware) is the upstream default since BLAST+ 2.10. Available options: `4`, `5` Max size per DB volume with a unit suffix (e.g. `"1GB"`); upstream caps at `"4GB"`. NCBI taxonomy ID assigned to every sequence; set to tag a single-organism DB. Extra `makeblastdb` CLI tokens passed verbatim (e.g. `["-mask_data", "/path/to/mask"]`). Escape hatch for flags not exposed as typed fields above. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source The base path to the generated BLAST database files (without file extensions). This path can be used directly as the value for the `local_db` parameter in `BlastSearchConfig`. For example, if `db_path` is `"/data/mydb"`, `makeblastdb` will have created multiple files like `"/data/mydb.nhr"`, `"/data/mydb.nin"`, `"/data/mydb.nsq"` (for nucleotide databases) or similar extensions for protein databases.

#### Applications This tool is the prerequisite for any local BLAST workflow that searches against a custom reference set, such as an in-house genome assembly, a curated subset of a public database, or a panel of designed sequences. Building a local database once and reusing it across many queries avoids repeated network traffic to NCBI and gives full control over the reference content. #### Usage Tips * **`dbtype` must match the input FASTA type.** Use `"nucl"` for nucleotide sequences and `"prot"` for amino-acid sequences. The configuration validator hard-errors on any other value, and a mismatch against the FASTA content will be caught by `makeblastdb` at runtime. * **`out_prefix` defaults to the input FASTA stem in the same directory.** Set it explicitly when the database should live in a different location or under a different name. * **`parse_seqids=True` is required for FASTA identifiers to be addressable.** Enable it when downstream calls need to retrieve sequences by identifier through `blastdbcmd` or when building a taxonomy-aware database. Pair it with `hash_index=True` for faster identifier lookups. * **`extra_args` accepts verbatim `makeblastdb` CLI tokens.** Use it for niche flags not exposed as typed fields, such as `["-mask_data", "/path/to/mask"]` for premasking input or `["-gi_mask", "..."]` for taxonomy-related options.