virusprimerpro-agent-api

name	virusprimerpro-agent-api
description	Use when an agent needs to call the VirusPrimerPro Agent API instead of the GUI, or prepare viral genome inputs for it: request/use API keys, download viral genomes from NCBI, install/run MAFFT, check and repair abnormal sequences, prepare phylogenetic trees/annotations, upload aligned FASTA/tree/GenBank files, poll runs, and fetch artifacts.

VirusPrimerPro Agent API

Use this skill when a task requires calling VirusPrimerPro through /api/v1/agent/* rather than the browser GUI. The API is asynchronous: submit files and parameters, start the run, then poll status until succeeded or failed.

Setup

Prefer environment variables so secrets do not appear in prompts, logs, or commits:

export VPP_AGENT_BASE_URL="http://127.0.0.1:3006"
export VPP_AGENT_API_KEY="vpp_live_<prefix>_<secret>"

For admin-only key issuance:

export VPP_AGENT_ADMIN_TOKEN="<admin token>"

Preferred Helper

Use the bundled standard-library Python helper for reliable uploads and polling:

python agentskill/scripts/vpp_agent_api.py \
  --base-url "$VPP_AGENT_BASE_URL" \
  --api-key-env VPP_AGENT_API_KEY \
  submit \
  --msa aligned.fasta \
  --profile standard \
  --config-json '{"mode":"primer_site","target_coverage":0.95,"amplicon_min":100,"amplicon_max":400}' \
  --wait \
  --poll-interval 30 \
  --output-dir results

Import the helper when building a larger agent workflow:

from pathlib import Path
from agentskill.scripts.vpp_agent_api import VirusPrimerProClient

client = VirusPrimerProClient.from_env()
run = client.submit_primer_site_run(
    msa_path=Path("aligned.fasta"),
    config={"mode": "primer_site", "target_coverage": 0.95},
    profile="standard",
    wait=True,
    poll_interval=30,
)
print(run["status"])

Workflow

1. Ensure the agent has an approved API key. If not, call apply-key and wait for an administrator to approve and issue a key.
2. Create a run with top-level mode, profile, config, and file metadata.
3. Upload each file in chunks. The chunk upload path must include /parts/{part_no}.
4. Call /start. It returns quickly with queued; do not wait on the HTTP request.
5. Poll GET /api/v1/agent/runs/{run_id} every 30 seconds, or longer for heavy runs.
6. On succeeded, fetch /result and artifacts. On failed, report process_exit_code, warning_flags, and any available artifacts.

Status handling:

• created or uploading: finish missing uploads, then call start.
• queued: worker has not started; wait and poll again.
• running: computation is active; wait and poll again.
• succeeded: fetch result and artifacts.
• failed: surface the error metadata and available artifacts.
• aborted: the upload run was cancelled before queueing.

PhyloGuide Preparation

For phylo_guide, prepare the tree and annotation before calling submit. Do not invent genotype groups from the sequence names. Use literature or curated references for the target species, then make those groups explicit in a groups.json file.

python agentskill/scripts/vpp_agent_api.py prepare-phylo \
  --msa aligned.fasta \
  --groups-file groups.json \
  --species "Target species name" \
  --reference-id NC_000000 \
  --target-group GenotypeA \
  --citation "Author Year DOI/PMID or URL" \
  --out-dir phylo_ready

Then submit:

python agentskill/scripts/vpp_agent_api.py \
  --base-url "$VPP_AGENT_BASE_URL" \
  --api-key-env VPP_AGENT_API_KEY \
  submit \
  --mode phylo_guide \
  --msa phylo_ready/aligned.normalized.fasta \
  --tree phylo_ready/tree.newick \
  --annotation-file phylo_ready/annotation.json \
  --config-json '{"mode":"phylo_guide"}' \
  --wait

Read references/phylo_prepare.md before preparing a PhyloGuide job.

NCBI + MAFFT Preparation

Use agentskill/scripts/ncbi_mafft.py when the agent must download viral genomes from NCBI, install or run MAFFT, check alignment quality, or repair abnormal sequences.

python agentskill/scripts/ncbi_mafft.py install-mafft

python agentskill/scripts/ncbi_mafft.py download-ncbi \
  --query '"Target virus"[Organism] AND "complete genome"[Title]' \
  --max-records 50 \
  --output ncbi_raw.fasta \
  --manifest ncbi_manifest.json

python agentskill/scripts/ncbi_mafft.py pipeline \
  --input ncbi_raw.fasta \
  --out-dir mafft_ready \
  --thread 4 \
  --adjust-direction \
  --drop-reason empty_after_removing_gaps \
  --drop-reason high_n_fraction

Use mafft_ready/aligned.repaired.fasta as the MSA for prepare-phylo or submit. Read references/ncbi_mafft.md before running the pipeline.

Safety Rules

• Never print, commit, or write the full API key unless the user explicitly asks to capture a newly issued key.
• Prefer Authorization: Bearer ...; X-API-Key is also accepted.
• Use top-level profile; the API treats it as authoritative and overwrites conflicting config.primer_site_profile.
• high_coverage and diagnostic require both key approval and server-side enablement.
• Use short polling requests. Do not keep one HTTP connection open waiting for long computations.

References

Read references/api_contract.md when you need endpoint details, artifact IDs, or common error handling. Read references/ncbi_mafft.md when you need to download NCBI viral genomes, install/run MAFFT, or QC/repair alignments. Read references/phylo_prepare.md when you need to prepare phylo_guide inputs.

Specialized Production Skills

Load the narrower skill under agentskill/skills/ when the task is specifically about one production step:

• literature-taxonomy-curation: cited genotype/subtype/clade definitions.
• reference-dataset-curation: accession filtering, deduplication, and manifests.
• specificity-screening: host/background/near-neighbor off-target checks.
• primer-wetlab-qc: Tm/GC/degeneracy/dimer/amplicon QC.
• tngs-panel-design: tiled amplicon panel selection and gap reporting.
• panel-interaction-balancing: multiplex pool assignment.
• wetlab-export: order sheets, pooling plans, and plate maps.
• validation-report: release-gate report assembly.
• run-orchestration: batch submit, poll, and summarize long API runs.
• advanced-phylogeny: external phylogeny planning and tree/MSA validation.