Science Skill and command-line interface (CLI) for interacting with the STRING Database API v12.0. This skill enables AI agents and human researchers to query protein-protein interaction (PPI) networks, retrieve functional enrichment annotations (Gene Ontology, KEGG, Reactome), analyze cross-species homology, generate network visualizations, and perform genome-wide ranked gene set enrichment analysis (Values/Ranks GSEA).
The STRING (Search Tool for the Retrieval of Interacting Genes/Proteins) database is a comprehensive repository of known and predicted protein-protein interactions covering physical interactions and functional associations across thousands of organisms.
This repository provides:
skills/string_database/SKILL.md: Complete skill specification for AI agent harnesses using progressive disclosure.skills/string_database/scripts/string_cli.py: A robust Python CLI built with inline PEP 723 script metadata, strict 1 QPS rate-limiting viapolite-http, structured logging, output redirection to protect context windows, and diagnostic error reporting.skills/string_database/scripts/dashboard_builder.py: A standalone HTML dashboard builder that renders the CLI's output files plus live UniProt / AlphaFold / RCSB lookups.skills/string_database/references/: Domain reference manuals covering identifier mapping, network topologies, statistical enrichment models, values/ranks GSEA, and Bayesian score calibrations.sample_data/: Fully synthetic, PHI-free sample datasets for testing mapping, pathway enrichment, and continuous expression ranking.tests/: Offline unit tests plus live integration tests that run against the real APIs.
Every number, node, edge, pathway, domain and 3D coordinate this skill reports comes from one of:
- a live STRING API v12.0 response,
- a live UniProt / AlphaFold / RCSB PDB lookup, or
- a file the user supplied.
There are no built-in gene tables, no recorded API responses, and no synthesized structures. When a value cannot be resolved (for example, a protein with no AlphaFold model) the dashboard shows an explicit empty state instead of a placeholder. This is enforced by tests/test_no_fabricated_data.py, which fails the build if fabricated data or mocking is reintroduced.
string-database-visualize-skill/
├── .gitignore
├── .licenses/
│ └── string_database_LICENSE.txt
├── LICENSE
├── Makefile # make test / test-live / lint / regenerate-results
├── README.md
├── assets/
│ └── workflow_overview.png
├── conftest.py # puts the skill scripts + test harness on sys.path
├── pyproject.toml # dependency, pytest and ruff configuration
├── requirements.txt # pip/venv equivalent of the PEP 723 metadata
├── results/ # regenerate with `make regenerate-results`
│ ├── dashboard.html
│ ├── enrichment.tsv
│ ├── mapped_genes.tsv
│ ├── network_edges.tsv
│ └── ppi_enrichment.tsv
├── sample_data/
│ ├── synthetic_cancer_genes.txt
│ ├── synthetic_mapping_queries.txt
│ └── synthetic_ranked_expression.tsv
├── skills/
│ └── string_database/
│ ├── SKILL.md
│ ├── references/
│ │ ├── enrichment.md
│ │ ├── interactions.md
│ │ ├── mapping.md
│ │ ├── scores_and_metrics.md
│ │ └── valuesranks.md
│ └── scripts/
│ ├── dashboard_builder.py
│ └── string_cli.py
└── tests/
├── __init__.py
├── harness.py # real-CLI runner + live-service gating
├── test_cli_parsing.py
├── test_dashboard.py
├── test_enrichment_filtering.py
├── test_live_smoke.py
├── test_no_fabricated_data.py
├── test_species_lookup.py
└── test_valuesranks_validation.py
The CLI requires Python 3.10+. The recommended runner is uv, which resolves the dependencies declared in the script's PEP 723 header automatically.
uv --version # verify installationIf uv is not installed:
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Run any command with uv run skills/string_database/scripts/string_cli.py <subcommand>; dependencies are cached in an isolated environment.
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt # or: pip install -e ".[dev]"
python skills/string_database/scripts/string_cli.py species --query mouse| Host | Used by | Purpose |
|---|---|---|
string-db.org |
all query subcommands | PPI networks, enrichment, homology, images, GSEA |
rest.uniprot.org |
dashboard |
accession, sequence length and domain features |
alphafold.ebi.ac.uk |
dashboard |
predicted 3D backbone coordinates |
files.rcsb.org |
dashboard |
experimental PDB coordinates (fallback) |
Use dashboard --no-fetch-structures to build a dashboard with zero outbound calls beyond the STRING data you already downloaded.
| Variable | Purpose | Default |
|---|---|---|
STRING_API_KEY |
API key for the Values/Ranks workflow (alternative to --api_key, keeps keys out of shell history and process listings) |
unset |
STRING_CLI_LOG_LEVEL |
Default log verbosity (DEBUG/INFO/WARNING/ERROR) |
INFO |
RUN_LIVE_TESTS |
Set to 0 to skip all live tests |
1 |
RUN_LIVE_VALUESRANKS |
Set to 0 to skip the slow async GSEA job test when STRING's queue is backed up |
1 |
KEEP_TEST_OUTPUT |
Set to 1 to keep live test output files for debugging |
unset |
No credentials are ever hardcoded in the repository.
- stdout carries only consumable result lines (summaries,
Saved ... to: <path>), so output can be parsed or piped. - stderr carries structured log records:
2026-01-01 12:00:00,000 ERROR string_cli: .... Control verbosity with--log-level(placed before the subcommand) orSTRING_CLI_LOG_LEVEL. - Exit codes:
0success,1runtime/API/filesystem failure,2usage error (missing inputs or credentials).
uv run skills/string_database/scripts/string_cli.py --log-level DEBUG map -i TP53 -s 9606 -o results/tp53.tsv- Project Code and Skill: This project, its CLI tool (
string_cli.py), test suite, and skill definitions are licensed under the Apache License, Version 2.0. - STRING Database Access and Data: Non-commercial and academic use of the STRING database is freely permitted under the Creative Commons Attribution 4.0 (CC-BY 4.0) license.
- Commercial entities must obtain a commercial license from the STRING consortium.
- Access terms: https://string-db.org/cgi/access
- The CLI automatically verifies and logs license compliance in
.licenses/string_database_LICENSE.txt.
This guide is for researchers, bioinformaticians, and non-programmers interacting with an AI assistant equipped with this skill. You do not need to write code or execute terminal commands manually.
When you ask biological questions involving gene lists, protein interactions, or pathway enrichment, the AI assistant automatically uses this skill to:
- Verify the organism and resolve your gene names to canonical identifiers.
- Query the STRING database for interaction networks, confidence scores, and enriched pathways.
- Save structured data files and generate an interactive visual dashboard for your browser or preview pane.
A plain text file containing gene symbols or protein IDs (one per line).
Example (my_genes.txt):
TP53
MDM2
CDKN1A
RB1
E2F1
ATM
CHEK2
BRCA1
PTEN
PIK3CA
A two-column tab-separated table containing gene symbols in column 1 and numerical rank metrics (such as log2 fold-change, signed p-values, or t-statistics) in column 2.
Example (ranked_expression.tsv):
TP53 9.45
CDKN1A 8.12
MDM2 7.80
ATM 6.23
MYC -3.50
BCL2 -4.70
"Find the top 10 highest-confidence interaction partners for human TP53 using STRING. Summarize what cellular roles each partner plays."
"I have a list of 15 upregulated genes in my experiment:
TP53, MDM2, CDKN1A, RB1, E2F1, ATM, CHEK2, BRCA1, PTEN, PIK3CA, AKT1, MTOR, EGFR, KRAS, BRAF. Run KEGG and Reactome pathway enrichment on these genes in human (Taxon ID 9606), and report any pathways with FDR < 0.01."
"Analyze the interaction network for the attached file
my_genes.txtin human. Generate an interactive dashboard with the network graph and pathway table so I can explore the results."
"Map the human proteins TP53 and MDM2 to their mouse orthologs (Taxon ID 10090), and check if their interaction score is conserved."
"Run a Values/Ranks gene set enrichment analysis on my ranked differential expression file
ranked_expression.tsvfor human. Identify the biological processes most enriched at the positive and negative ends of the ranking."
Run any command using uv run skills/string_database/scripts/string_cli.py <subcommand> [options].
Supplying identifiers. --identifiers / -i accepts space- or comma-separated
names, and @path/to/file reads them from a file. A file supplies one identifier per
line; blank lines and # comments are skipped, only the first tab-delimited field of
each line is used, and a leading STRING TSV header row is dropped. A STRING result
table can therefore be chained straight into the next command:
uv run skills/string_database/scripts/string_cli.py map -i @sample_data/synthetic_cancer_genes.txt -s 9606 --limit_to_best -o results/mapped_genes.tsv
uv run skills/string_database/scripts/string_cli.py network -i @results/mapped_genes.tsv -s 9606 -o results/network_edges.tsvResolve common names or scientific names to NCBI Taxonomy IDs, or view the built-in top 20 model organisms table.
# Search for an organism
uv run skills/string_database/scripts/string_cli.py species --query "mouse"
# View table of common model organisms
uv run skills/string_database/scripts/string_cli.py speciesMap gene symbols, UniProt accessions, or Ensembl IDs to canonical STRING identifiers (stringId).
uv run skills/string_database/scripts/string_cli.py map \
--identifiers TP53 MDM2 CDKN1A \
--species 9606 \
--limit_to_best \
--output results/mapped_genes.tsvExtract interaction edges between query proteins with confidence score filtering.
uv run skills/string_database/scripts/string_cli.py network \
--identifiers TP53 MDM2 CDKN1A RB1 \
--species 9606 \
--required_score 700 \
--summary \
--output results/network_edges.tsvRetrieve top interaction partners for seed proteins.
uv run skills/string_database/scripts/string_cli.py partners \
--identifiers 9606.ENSP00000269305 \
--species 9606 \
--limit 15 \
--required_score 700 \
--output results/tp53_partners.tsvCalculate whether the query proteins have significantly more interactions than expected by chance.
uv run skills/string_database/scripts/string_cli.py ppi-enrichment \
--identifiers TP53 MDM2 CDKN1A RB1 ATM \
--species 9606 \
--output results/ppi_enrichment.tsvPerform over-representation analysis against Gene Ontology, KEGG, Reactome, and protein domain databases. Results are filtered by category/FDR, sorted by ascending FDR, and truncated by --limit.
uv run skills/string_database/scripts/string_cli.py enrichment \
--identifiers @sample_data/synthetic_cancer_genes.txt \
--species 9606 \
--category KEGG \
--fdr 0.05 \
--summary \
--output results/enrichment.tsvSearch for functional annotations, disease associations, or Gene Ontology terms matching a text keyword.
uv run skills/string_database/scripts/string_cli.py functional-terms \
--term_text "DNA repair" \
--species 9606 \
--limit 20 \
--output results/dna_repair_terms.tsvRetrieve functional descriptions and domain summaries for a set of proteins.
uv run skills/string_database/scripts/string_cli.py functional-annotation \
--identifiers TP53 MDM2 \
--species 9606 \
--output results/annotations.tsvMap orthologous proteins between species.
uv run skills/string_database/scripts/string_cli.py homology-best \
--identifiers TP53 MDM2 \
--species 9606 \
--species_b 10090 \
--output results/human_mouse_orthologs.tsvGenerate high-resolution PNG or vector SVG network diagrams.
uv run skills/string_database/scripts/string_cli.py image \
--identifiers TP53 MDM2 CDKN1A RB1 \
--species 9606 \
--format svg \
--network_flavor confidence \
--output results/network.svgPerform cutoff-free gene set enrichment on a continuously ranked dataset (e.g. differential expression log2FC or signed p-value). Polling retries transient network failures against the --timeout budget.
# 1. Fetch anonymous API key
uv run skills/string_database/scripts/string_cli.py valuesranks-key \
--output results/key.json
# 2. Submit ranked dataset (key may also come from $STRING_API_KEY)
export STRING_API_KEY="<API_KEY>"
uv run skills/string_database/scripts/string_cli.py valuesranks-submit \
--input_file sample_data/synthetic_ranked_expression.tsv \
--species 9606 \
--output results/job.json
# 3. Poll and download final results
uv run skills/string_database/scripts/string_cli.py valuesranks-status \
--job_id "<JOB_ID>" \
--wait \
--timeout 300 \
--output results/ranked_enrichment.tsvImportant
The valuesranks-key response carries a note saying the key activates "within
30 minutes"; in practice it is often usable immediately. If a submit returns
{"status": "error"} the CLI logs STRING's message and exits 1 - wait and retry
rather than minting another key. Reuse a stored key via STRING_API_KEY.
The three subcommands wrap json/get_api_key, json/valuesranks_enrichment_submit
and json/valuesranks_enrichment_status. There is no separate results endpoint: on
status == "success" the CLI follows the absolute download_url returned in the
status record. Add --rank_direction {-1,0,1} to restrict testing to one tail of the
ranking. See valuesranks.md for
the full output schema.
Generate a self-contained, responsive HTML dashboard for agent harnesses with HTML / iframe preview panes. Requires at least one input file; missing files are a hard error (exit code 1) rather than a silently empty dashboard.
Features included in the dashboard:
- Light and dark theme toggle with icon-only button (Sun / Moon SVG icons).
- Real-time physics simulation with drag-and-drop nodes, zooming, panning, anti-overlap constraints, and live minimum confidence score slider.
- Metric summary cards (mapped proteins count, observed/expected edges, average node degree, PPI p-value) read directly from the PPI enrichment file.
- Functional enrichment explorer with search filtering, category dropdown (KEGG, Reactome, GO Process, etc.), FDR significance bars, and CSV export.
- Protein details inspector modal with a 3D viewer that renders real AlphaFold or RCSB PDB coordinates, states which database each structure came from, and shows an explicit "no structure available" state when nothing can be retrieved.
- Domain architecture track built from UniProt feature annotations for the queried proteins (any organism, not a fixed gene list).
uv run skills/string_database/scripts/string_cli.py dashboard \
--title "Synthetic Cancer Gene Network & Pathway Analysis" \
--map_file results/mapped_genes.tsv \
--network_file results/network_edges.tsv \
--ppi_file results/ppi_enrichment.tsv \
--enrichment_file results/enrichment.tsv \
--output results/dashboard.html
# Deterministic, fully offline build (no UniProt/AlphaFold/RCSB calls)
uv run skills/string_database/scripts/string_cli.py dashboard \
--map_file results/mapped_genes.tsv \
--no-fetch-structures \
--structure-timeout 5 \
--output results/dashboard_offline.htmlThis skill conforms to standard Agent Skill specifications and can be used across various AI agent harnesses:
- Place the repository in the workspace or add
skills/string_databaseto your agent's skill search paths. - The agent discovers
skills/string_database/SKILL.mdautomatically. - When answering questions about protein interactions or gene enrichment, the agent invokes
string_cli.pyto fetch data, inspects results safely, and presents structured answers.
- Ensure the agent environment has Python 3.10+ and
uv(or a virtualenv withrequirements.txt) to execute CLI commands and generate interactive HTML artifacts.
All datasets in sample_data/ are 100% synthetic, containing public gene symbols and simulated numerical values. They are inputs for demos and tests - they are never substituted for API responses. They contain no protected health information (PHI):
sample_data/synthetic_cancer_genes.txt: 15 canonical cancer-associated gene symbols for testing mapping and over-representation analysis.sample_data/synthetic_ranked_expression.tsv: 30 ranked gene entries with simulated signed scores for testing the Values/Ranks workflow.sample_data/synthetic_mapping_queries.txt: Mixed symbols, UniProt accessions, and Ensembl protein IDs for testing batch normalization.
The files in results/ are build artifacts, not fixtures. Rebuild them from live STRING queries at any time:
make regenerate-resultsCI runs this target so the committed dashboard is provably produced by the current code.
The suite contains no mocking libraries, no recorded API responses and no fixture payloads. Tests either exercise pure functions with inputs they generate, or run the real CLI against live services. Live tests skip automatically when the network is unavailable or RUN_LIVE_TESTS=0.
# Offline: parsers, validators, argument handling, dashboard payload construction
make test
# equivalent to:
RUN_LIVE_TESTS=0 uv run --with pytest --with polite-http pytest tests/ -v
# Full suite including live STRING / UniProt / AlphaFold integration tests
make test-live
# Static analysis (unused imports, bare excepts, bugbear rules)
make lint
# Just the asynchronous Values/Ranks GSEA job (also part of `make test-live`)
make test-valuesrankstests/harness.py: Shared real-CLI runner plus live-service reachability gating.tests/test_cli_parsing.py: Parser and identifier-resolver behaviour, plus offline failure paths (missing files, missing API key, stdout/stderr separation, exit codes).tests/test_species_lookup.py: Search behaviour of thespeciessubcommand and live validation that the built-in taxon IDs are accepted by STRING.tests/test_enrichment_filtering.py: The skill's real filtering/sorting functions, verified both deterministically and against live STRING payloads.tests/test_valuesranks_validation.py: The real ranked-TSV validator (malformed rows, comments, empty identifiers, scientific notation) and CLI exit codes.tests/test_dashboard.py: PDB parsing, payload-to-source-file equivalence, live UniProt annotation for arbitrary proteins, full live dashboard build, and regressions against fabricated identifiers or synthetic structures.tests/test_live_smoke.py: Live integration coverage for every subcommand, asserting schemas and that--required_score,--limitand--fdrare actually honoured. Includes the full asynchronous Values/Ranks GSEA round trip (key -> submit -> poll -> download), which checks that every protein STRING reports back was present in the submitted ranking.tests/test_no_fabricated_data.py: Meta-tests banning mocking, hardcoded gene tables, procedural structures andprint-style diagnostics.
This software and skill suite are distributed under the terms of the Apache License, Version 2.0. See the LICENSE file for the full text.