protein_sequence_similarity_search

Name: protein_sequence_similarity_search
Author: ai4protein

244stars35forks

How to install protein_sequence_similarity_search?

ai4protein/venusfactory2/protein_sequence_similarity_search

$npx -y skills add ai4protein/VenusFactory2 --skill protein_sequence_similarity_search

Installs into the current project.

Summary

Find homologous protein sequences from a query sequence using MMseqs2 (fast, ColabFold web API) or BLAST (comprehensive, EBI). Use when the user provides a protein sequence or FASTA file and wants homologs, function inference by sequence similarity, or input for an MSA. Do NOT us

Files · 1

View on GitHub

SKILL.md

1	# Protein Sequence Similarity Search
2
3	## Overview
4
5	Two complementary search engines, each wrapped as a submit-poll-download-parse pipeline:
6
7	- MMseqs2 (ColabFold) — fast, default. Searches UniRef (+ optional MGnify environmental). Best for quickly building an MSA-grade hit set.
8	- EBI BLAST (NCBI BLAST hosted at EBI) — slower but more exhaustive search across multiple UniProt/UniRef/PDB databases. Use when you need BLAST-specific scoring (e.g., comparing against a published BLAST result) or when MMseqs2 returns few hits.
9
10	Both tools save the full hit list to a JSON file on disk and return only a top-10 markdown preview in the response, keeping the agent's context window small.
11
12	## Project Tools (VenusFactory2)
13
14	\| Tool \| Args \| Returns \| Description \|
15	\|------\|------\|---------\|--------------\|
16	\| download_mmseqs2_homologs_by_sequence \| `sequence_or_fasta_path` (required, raw sequence or FASTA file path), `out_dir` (required), `include_mgnify` (default `False`), `poll_interval` (default `10.0` s), `timeout_secs` (default `900` s) \| JSON: `{status, file_info {file_path -> mmseqs2_<ticket>.json, file_size, format: "json"}, content_preview (top-10 markdown table), biological_metadata {engine, ticket_id, query_length, hit_count, include_mgnify}}` \| Fast UniRef homologue search via ColabFold MMseqs2 API. \|
17	\| download_blast_homologs_by_sequence \| `sequence_or_fasta_path` (required), `out_dir` (required), `database` (default `"uniprotkb_swissprot"`; comma-separated list ok), `email` (optional, falls back to env `USER_EMAIL`), `poll_interval` (default `30.0` s), `timeout_secs` (default `900` s) \| JSON: `{status, file_info {file_path -> blast_<jobid>.json}, content_preview, biological_metadata {engine, job_id, query_length, databases, hit_count, email}}` \| Authoritative BLAST search against UniProt/UniRef/PDB at EBI. \|
18
19	## When to Use This Skill
20
21	- The user gives a sequence and asks "find similar proteins" / "what's this protein's family" / "find homologs"
22	- You need to build an MSA from a single seed sequence: run MMseqs2 → write hits → `download_clustalo_msa_by_fasta`
23	- You need orthologs in a specific clade: BLAST with `database=uniprotkb_human` (or `_bacteria`, `_viruses`, etc.)
24	- You need PDB hits to seed structure-based analysis: BLAST with `database=pdb`
25
26	## Which Engine to Pick
27
28	\| Situation \| Engine \|
29	\|---\|---\|
30	\| Default / unspecified \| MMseqs2 (faster, ~1-3 min) \|
31	\| User explicitly says "BLAST" \| BLAST \|
32	\| MMseqs2 returned <5 hits \| BLAST fallback \|
33	\| Need PDB-only hits \| BLAST with `database=pdb` \|
34	\| Need MGnify environmental hits \| MMseqs2 with `include_mgnify=True` \|
35	\| Want comprehensive UniProtKB+TrEMBL coverage \| BLAST with `database=uniprotkb` \|
36
37	## Supported BLAST Databases
38
39	`uniprotkb` `uniprotkb_swissprot` `uniprotkb_swissprotsv` `uniprotkb_reference_proteomes` `uniprotkb_trembl` `uniprotkb_refprotswissprot` `uniprotkb_archaea` `uniprotkb_arthropoda` `uniprotkb_bacteria` `uniprotkb_complete_microbial_proteomes` `uniprotkb_eukaryota` `uniprotkb_fungi` `uniprotkb_human` `uniprotkb_mammals` `uniprotkb_nematoda` `uniprotkb_rodents` `uniprotkb_vertebrates` `uniprotkb_viridiplantae` `uniprotkb_viruses` `uniprotkb_enzyme` `uniprotkb_covid19` `uniref100` `uniref90` `uniref50` `pdb`
40
41	## Output JSON Schema (file_info.file_path)
42
43	```json
44	{
45	"hits": [
46	{"target_id": "...", "q_cov": 78.3, "e_value": 1.2e-50, "identity": 0.45, "aln_len": 240, ...},
47	...
48	],
49	"metadata": {"engine": "MMseqs2 (ColabFold)", "ticket_id": "...", "query_length": 256, "hit_count": 178, ...}
50	}
51	```
52
53	## Rate Limiting
54
55	- ColabFold MMseqs2: 2 req/s, ~1-3 min wall clock per job. Polls every 10 s.
56	- EBI BLAST: 2 req/s submit; polls every 30 s. Jobs take 2-10 min.
57	- Both timeout at 15 min by default — increase `timeout_secs` for very large queries.
58
59	## Common Mistakes
60
61	- Passing a FASTA file with multiple records but expecting all to be searched: only the first record is used. Loop in the agent if you need multiple queries.
62	- Skipping `out_dir`: required. Tools error with `ValidationError: empty out_dir`.
63	- Setting `database` to an unsupported value: returns `ValidationError` with the full allowed list — pick from that list.
64	- Treating MMseqs2 hits as the final answer when count is 0: this is a soft failure; fall back to BLAST.
65
66	## References
67
68	- [ColabFold MMseqs2 API](https://github.com/sokrypton/ColabFold)
69	- [EBI BLAST web service](https://www.ebi.ac

People who liked this also viewed

6 picks

Type

protein_sequence_similarity_search

244stars35forks

View on GitHub

How to install protein_sequence_similarity_search?

ai4protein/venusfactory2/protein_sequence_similarity_search

$npx -y skills add ai4protein/VenusFactory2 --skill protein_sequence_similarity_search

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Protein Sequence Similarity Search
2
3	## Overview
4
5	Two complementary search engines, each wrapped as a submit-poll-download-parse pipeline:
6
7	- MMseqs2 (ColabFold) — fast, default. Searches UniRef (+ optional MGnify environmental). Best for quickly building an MSA-grade hit set.
8	- EBI BLAST (NCBI BLAST hosted at EBI) — slower but more exhaustive search across multiple UniProt/UniRef/PDB databases. Use when you need BLAST-specific scoring (e.g., comparing against a published BLAST result) or when MMseqs2 returns few hits.
9
10	Both tools save the full hit list to a JSON file on disk and return only a top-10 markdown preview in the response, keeping the agent's context window small.
11
12	## Project Tools (VenusFactory2)
13
14	\| Tool \| Args \| Returns \| Description \|
15	\|------\|------\|---------\|--------------\|
16	\| download_mmseqs2_homologs_by_sequence \| `sequence_or_fasta_path` (required, raw sequence or FASTA file path), `out_dir` (required), `include_mgnify` (default `False`), `poll_interval` (default `10.0` s), `timeout_secs` (default `900` s) \| JSON: `{status, file_info {file_path -> mmseqs2_<ticket>.json, file_size, format: "json"}, content_preview (top-10 markdown table), biological_metadata {engine, ticket_id, query_length, hit_count, include_mgnify}}` \| Fast UniRef homologue search via ColabFold MMseqs2 API. \|
17	\| download_blast_homologs_by_sequence \| `sequence_or_fasta_path` (required), `out_dir` (required), `database` (default `"uniprotkb_swissprot"`; comma-separated list ok), `email` (optional, falls back to env `USER_EMAIL`), `poll_interval` (default `30.0` s), `timeout_secs` (default `900` s) \| JSON: `{status, file_info {file_path -> blast_<jobid>.json}, content_preview, biological_metadata {engine, job_id, query_length, databases, hit_count, email}}` \| Authoritative BLAST search against UniProt/UniRef/PDB at EBI. \|
18
19	## When to Use This Skill
20
21	- The user gives a sequence and asks "find similar proteins" / "what's this protein's family" / "find homologs"
22	- You need to build an MSA from a single seed sequence: run MMseqs2 → write hits → `download_clustalo_msa_by_fasta`
23	- You need orthologs in a specific clade: BLAST with `database=uniprotkb_human` (or `_bacteria`, `_viruses`, etc.)
24	- You need PDB hits to seed structure-based analysis: BLAST with `database=pdb`
25
26	## Which Engine to Pick
27
28	\| Situation \| Engine \|
29	\|---\|---\|
30	\| Default / unspecified \| MMseqs2 (faster, ~1-3 min) \|
31	\| User explicitly says "BLAST" \| BLAST \|
32	\| MMseqs2 returned <5 hits \| BLAST fallback \|
33	\| Need PDB-only hits \| BLAST with `database=pdb` \|
34	\| Need MGnify environmental hits \| MMseqs2 with `include_mgnify=True` \|
35	\| Want comprehensive UniProtKB+TrEMBL coverage \| BLAST with `database=uniprotkb` \|
36
37	## Supported BLAST Databases
38
39	`uniprotkb` `uniprotkb_swissprot` `uniprotkb_swissprotsv` `uniprotkb_reference_proteomes` `uniprotkb_trembl` `uniprotkb_refprotswissprot` `uniprotkb_archaea` `uniprotkb_arthropoda` `uniprotkb_bacteria` `uniprotkb_complete_microbial_proteomes` `uniprotkb_eukaryota` `uniprotkb_fungi` `uniprotkb_human` `uniprotkb_mammals` `uniprotkb_nematoda` `uniprotkb_rodents` `uniprotkb_vertebrates` `uniprotkb_viridiplantae` `uniprotkb_viruses` `uniprotkb_enzyme` `uniprotkb_covid19` `uniref100` `uniref90` `uniref50` `pdb`
40
41	## Output JSON Schema (file_info.file_path)
42
43	```json
44	{
45	"hits": [
46	{"target_id": "...", "q_cov": 78.3, "e_value": 1.2e-50, "identity": 0.45, "aln_len": 240, ...},
47	...
48	],
49	"metadata": {"engine": "MMseqs2 (ColabFold)", "ticket_id": "...", "query_length": 256, "hit_count": 178, ...}
50	}
51	```
52
53	## Rate Limiting
54
55	- ColabFold MMseqs2: 2 req/s, ~1-3 min wall clock per job. Polls every 10 s.
56	- EBI BLAST: 2 req/s submit; polls every 30 s. Jobs take 2-10 min.
57	- Both timeout at 15 min by default — increase `timeout_secs` for very large queries.
58
59	## Common Mistakes
60
61	- Passing a FASTA file with multiple records but expecting all to be searched: only the first record is used. Loop in the agent if you need multiple queries.
62	- Skipping `out_dir`: required. Tools error with `ValidationError: empty out_dir`.
63	- Setting `database` to an unsupported value: returns `ValidationError` with the full allowed list — pick from that list.
64	- Treating MMseqs2 hits as the final answer when count is 0: this is a soft failure; fall back to BLAST.
65
66	## References
67
68	- [ColabFold MMseqs2 API](https://github.com/sokrypton/ColabFold)
69	- [EBI BLAST web service](https://www.ebi.ac

People who liked this also viewed

6 picks

Type