复制安装命令
用 Codex 或 Claude 安装复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它先审查 Skill 页面再帮你安装。
复制前请先查看来源、License 和安全提示。
🔔 Claude Scientific Skills is now Scientific Agent Skills.
用 Codex 或 Claude 安装复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它先审查 Skill 页面再帮你安装。
复制前请先查看来源、License 和安全提示。
来源文件:README.md
🔔 Claude Scientific Skills is now Scientific Agent Skills. Same skills, broader compatibility — now works with any AI agent that supports the open Agent Skills standard, not just Claude.
New: K-Dense BYOK — A free, open-source AI co-scientist that runs on your desktop, powered by Scientific Agent Skills. Bring your own API keys, pick from 40+ models, and get a full research workspace with web search, file handling, 100+ scientific databases, and access to all 158 skills in this repo. Your data stays on your computer, and you can optionally scale to cloud compute via Modal for heavy workloads. Get started here.
Stay up to date: Follow K-Dense on X, LinkedIn, and YouTube for new skills, release announcements, walkthroughs, research workflow demos, and examples you can use with your own AI agent.
A comprehensive collection of 158 ready-to-use scientific and research skills (covering cancer genomics, individual-level 1000 Genomes queries, hosted regulatory-sequence prediction, live pathogen-variant surveillance, analytical method validation, PK/PD modelling and dose selection, full-text biomedical and regulatory literature retrieval, drug-target binding, molecular dynamics, RNA velocity, geospatial science, time series forecasting, scientific ML resource discovery via Hugging Science, 78+ scientific databases, and more) for any AI agent that supports the open Agent Skills standard, created by K-Dense. Works with Cursor, Claude Code, Codex, Google Antigravity, and more. Transform your AI agent into a research assistant capable of executing complex multi-step scientific workflows across biology, chemistry, medicine, and beyond.
⭐ Help make AI for science easier to discover: If Scientific Agent Skills saves you time, teaches your agent a workflow, or helps your lab move faster, please star this repository. A star is a public signal that these open, reusable research skills are worth maintaining: it helps scientists, engineers, and open-source contributors find the project, shows which agent-skill standards are gaining real adoption, and gives us a clear reason to keep expanding the collection for the community.
These skills enable your AI agent to seamlessly work with specialized scientific libraries, databases, and tools across multiple scientific domains. While the agent can use any Python package or API on its own, these explicitly defined skills provide curated documentation and examples that make it significantly stronger and more reliable for the workflows below:
Transform your AI coding agent into an 'AI Scientist' on your desktop!
🎬 New to Scientific Agent Skills? Watch our Getting Started with Scientific Agent Skills video for a quick walkthrough.
This repository provides 158 scientific and research skills organized into the following categories:
Each skill includes:
SKILL.md)scripts/ — CI blocks a pull request that adds bundled tooling without onescripts/ has a suite under tests/, plus a repo-wide structural contract (frontmatter, link resolution, script parsing, --help behavior) that runs on every pull requestInstall Scientific Agent Skills with a single command:
npx skills add K-Dense-AI/scientific-agent-skills
This is a common standards-based installer for supported Agent Skills hosts, including current versions of Claude Code, Claude Cowork, Codex, Gemini CLI, Google Antigravity, and Cursor. Confirm installation paths and optional metadata behavior in your host's current documentation.
gh skill)If you use the GitHub CLI (v2.90.0+), you can install skills with gh skill:
# Browse and install interactively
gh skill install K-Dense-AI/scientific-agent-skills
# Install a specific skill directly
gh skill install K-Dense-AI/scientific-agent-skills scanpy
# Target a specific agent host
gh skill install K-Dense-AI/scientific-agent-skills --agent cursor
gh skill install K-Dense-AI/scientific-agent-skills --agent claude-code
gh skill install K-Dense-AI/scientific-agent-skills --agent codex
gh skill install K-Dense-AI/scientific-agent-skills --agent gemini
gh skill automatically installs to the correct directory for your agent host and records provenance metadata for supply chain integrity.
Pin to a specific release tag or commit SHA for reproducible installs:
# Pin to a release tag
gh skill install K-Dense-AI/scientific-agent-skills --pin v2.62.0
# Pin to a commit SHA
gh skill install K-Dense-AI/scientific-agent-skills --pin abc123def
# Check for updates interactively
gh skill update
# Update all installed skills
gh skill update --all
Agent hosts differ in install paths, discovery settings, and support for optional frontmatter fields. npx skills add (Option 1) commonly installs into the ~/.agents/skills/ convention, with project-scoped installs under .agents/skills/; confirm both paths against your host's current documentation. To install manually on a host configured to scan one of those locations:
git clone https://github.com/K-Dense-AI/scientific-agent-skills.git ~/.agents/skills/scientific-agent-skills # user-level
git clone https://github.com/K-Dense-AI/scientific-agent-skills.git .agents/skills/scientific-agent-skills # project-level
For Hermes versions that support skill taps, add the repository as a tap:
hermes skills tap add K-Dense-AI/scientific-agent-skills
Every SKILL.md has YAML frontmatter, but legacy and community skills vary in metadata formatting (block or flow style) and optional extension fields. Repository updates must keep metadata.version as a quoted numeric string and pass canonical skills-ref validate ./skills/<skill-name> checks. Hosts may interpret optional metadata and credential prompts differently, so verify behavior on the target host. Because 158 skills add up to a lot of standing context, consider installing a topical subset rather than the whole collection.
NemoClaw note: NemoClaw runs agents inside NVIDIA OpenShell with default-deny outbound networking. Skills are discovered and loaded normally, but any skill that needs the network — package installs via
uv, or API calls (Exa, Parallel, Benchling, NCBI, Materials Project, …) — only works once the operator pre-approves the relevant domains in the OpenShell TUI.
That's it! A compatible host can discover the skills from its configured paths and use them when relevant. You can also invoke any skill manually by mentioning the skill name in your prompt.
Skills can execute code and influence your coding agent's behavior. Review what you install.
Agent Skills are powerful — they can instruct your AI agent to run arbitrary code, install packages, make network requests, and modify files on your system. A malicious or poorly written skill has the potential to steer your coding agent into harmful behavior.
We take security seriously. All contributions go through a review process, and we run LLM-based security scans (via Cisco AI Defense Skill Scanner) on every skill in this repository. However, as a small team with a growing number of community contributions, we cannot guarantee that every skill has been exhaustively reviewed for all possible risks.
It is ultimately your responsibility to review the skills you install and decide which ones to trust.
We recommend the following:
SKILL.md before installing. Each skill's documentation describes what it does, what packages it uses, and what external services it connects to. If something looks suspicious, don't install it.K-Dense-AI) have been through our internal review process. Community-contributed skills have been reviewed to the best of our ability, but with limited resources.uv pip install cisco-ai-skill-scanner
skill-scanner scan /path/to/skill --use-behavioral
Skills are scanned weekly — incrementally, so unchanged skills carry their previous findings forward, with a full rescan of everything at least every 30 days and whenever the scanner or model changes — and the results are published to docs/security-report.md. See SECURITY.md for our security policy, what is in scope, how to report a vulnerability privately, and how to contest a scan finding. We try to address security gaps as they arise.
Scientific Agent Skills is powered by 50+ incredible open source projects maintained by dedicated developers and research communities worldwide. Projects like Biopython, Scanpy, RDKit, scikit-learn, PyTorch Lightning, and many others form the foundation of these skills.
If you find value in this repository, please consider supporting the projects that make it possible:
👉 View the full list of projects to support
The docx, pdf, pptx, and xlsx document skills are created and maintained by Anthropic and vendored here from anthropics/skills. They are used under Anthropic's terms — see each skill's LICENSE.txt — and we track upstream so you get their latest improvements. All credit for those four skills goes to Anthropic.
SKILL.md files for specific requirements)The skills use uv as the package manager for installing Python dependencies. Install it using the instructions for your operating system:
macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Alternative (via pip):
pip install uv
After installation, verify it works by running:
uv --version
For more installation options and details, visit the official uv documentation.
Once you've installed the skills, you can ask your AI agent to execute complex multi-step scientific workflows. Here are some example prompts:
Goal: Prioritize EGFR inhibitor candidates for preclinical lung-cancer research
Prompt:
Use available skills you have access to whenever possible. Query ChEMBL for EGFR inhibitors (IC50 < 50nM), analyze structure-activity relationships
with RDKit, generate improved analogs with datamol, perform virtual screening with DiffDock
against AlphaFold EGFR structure, search PubMed for resistance mechanisms, check COSMIC for
mutations, and create visualizations and a comprehensive report.
Skills Used: database-lookup, rdkit, datamol, diffdock, paper-lookup, scientific-visualization
Goal: Comprehensive analysis of 10X Genomics data with public data integration
Prompt:
Use available skills you have access to whenever possible. Load 10X dataset with Scanpy, perform QC and doublet removal, integrate with Cellxgene
Census data, identify cell types using NCBI Gene markers, run differential expression with
PyDESeq2, infer gene regulatory networks with Arboreto, enrich pathways via Reactome/KEGG,
and identify therapeutic targets with Open Targets.
Skills Used: scanpy, cellxgene-census, database-lookup, pydeseq2, arboreto
Goal: Integrate RNA-seq, proteomics, and metabolomics to predict patient outcomes
Prompt:
Use available skills you have access to whenever possible. Analyze RNA-seq with PyDESeq2, process mass spec with pyOpenMS, integrate metabolites from
HMDB/Metabolomics Workbench, map proteins to pathways (UniProt/KEGG), find interactions via
STRING, correlate omics layers with statsmodels, build predictive model with scikit-learn,
and search ClinicalTrials.gov for relevant trials.
Skills Used: pydeseq2, pyopenms, database-lookup, statsmodels, scikit-learn
Goal: Discover allosteric modulators for protein-protein interactions
Prompt:
Use available skills you have access to whenever possible. Retrieve AlphaFold structures, identify interaction interface with BioPython, search ZINC
for allosteric candidates (MW 300-500, logP 2-4), filter with RDKit, dock with DiffDock,
rank with DeepChem, check PubChem suppliers, search USPTO patents, and optimize leads with
MedChem/molfeat.
Skills Used: database-lookup, biopython, rdkit, diffdock, deepchem, medchem, molfeat
Goal: Annotate a synthetic or properly de-identified VCF for hereditary-cancer research and qualified review
Prompt:
Use available skills you have access to whenever possible. Work only with authorized synthetic
or de-identified data. Parse the VCF with pysam, annotate variants with Ensembl VEP, retrieve
ClinVar/COSMIC/NCBI Gene/UniProt evidence, and verify literature sources. Build an evidence-
traceable research summary with scientific-writing. If clinical-reports is used, create only a
visibly marked draft structure from a verified source-fact manifest for qualified review; do not
diagnose, assess individual risk, recommend treatment, or determine trial eligibility.
Skills Used: pysam, database-lookup, paper-lookup, scientific-writing, clinical-reports
Goal: Analyze gene regulatory networks from RNA-seq data
Prompt:
Use available skills you have access to whenever possible. Query NCBI Gene for annotations, retrieve sequences from UniProt, identify interactions via
STRING, map to Reactome/KEGG pathways, analyze topology with Torch Geometric, reconstruct
GRNs with Arboreto, assess druggability with Open Targets, model with PyMC, visualize
networks, and search GEO for similar patterns.
Skills Used: database-lookup, torch-geometric, arboreto, pymc, networkx, scientific-visualization
📖 Want more examples? Check out docs/examples.md for comprehensive workflow examples and detailed use cases across all scientific domains.
This repository contains 158 scientific and research skills organized across multiple domains. Each skill provides comprehensive documentation, code examples, and best practices for working with scientific libraries, databases, and tools.
Note: The Python package and integration skills listed below are explicitly defined skills — curated with documentation, examples, and best practices for stronger, more reliable performance. They are not a ceiling: the agent can install and use any Python package or call any API, even without a dedicated skill. The skills listed simply make common workflows faster and more dependable.
A unified database-lookup skill provides deterministic REST API access to 78 public databases across all domains, with retrieval contracts, pagination/count reconciliation, and endpoint provenance. Dedicated skills cover specialized data platforms. Multi-database packages like BioServices (~40 bioinformatics services), BioPython (39 NCBI sub-databases via Entrez), and gget (20+ genomics databases) add further coverage.
datasets, transformers, and gradio_client)--standard profile<1220>/<1225>/<1226>, the CLSI EP series, and ISO/IEC 17025 cited by designation and scope only; stdlib-only statistics, no network access📖 For complete details on all skills, see docs/skills.md
💡 Looking for practical examples? Check out docs/examples.md for comprehensive workflow examples across all scientific domains.
Deep dives, benchmarks, and guides from the K-Dense blog that are directly relevant to using the skills in this repository.
SKILL.md and scripts/, scan before installing, and pin versions instead of tracking a branch.AGENTS.md profiles supplying the "how to think" layer alongside the "what to do" procedures in these skills.SKILL.md / AGENTS.md expert profiles by distilling how a given practitioner reasons.We welcome contributions to expand and improve this scientific skills repository!
For detailed instructions on adding or updating a skill, see CONTRIBUTING.md. The guide covers repository structure, required SKILL.md frontmatter, Agent Skills specification requirements, versioning, validation, security scanning, and pull request expectations.
✨ Add New Skills
📚 Improve Existing Skills
🐛 Report Issues
git checkout -b feature/amazing-skill)SKILL.md files with required frontmatter and metadata.versiontests/<skill-name>/ if your skill ships scripts/git commit -m 'Add amazing skill')git push origin feature/amazing-skill)✅ Adhere to the Agent Skills Specification — Every skill must follow the official spec (valid SKILL.md frontmatter, naming conventions, directory structure)
✅ Include a quoted metadata.version value in every SKILL.md
✅ Increment metadata.version when updating an existing skill
✅ Maintain consistency with existing skill documentation format
✅ Ensure all code examples are tested and functional
✅ Follow scientific best practices in examples and workflows
✅ Update relevant documentation when adding new capabilities
✅ Provide clear comments and docstrings in code
✅ Include references to official documentation
Every skill that ships scripts/ must have a test suite under tests/<skill-name>/ and an entry in tests/skill-requirements.toml. This is enforced — tests/_meta fails a pull request that adds bundled tooling without one, and it also runs a repo-wide structural contract over all skills (frontmatter conformance, SKILL.md length, local links resolving, scripts parsing, no shipped bytecode, no hardcoded local paths, --help behavior).
# Structural contract and coverage guard — seconds, no scientific packages needed
uv run python -m pytest tests/_meta -q
# One skill's suite
uv run --with pytest python -m pytest tests/<skill-name> -q
# Every suite, each in its own throwaway environment
uv run python tests/run_all.py --isolated
The Skill Tests workflow runs the contract plus the standard-library-only suites on every pull request; the full --isolated sweep builds ~100 environments and is run locally or on a schedule.
All skills in this repository are security-scanned using Cisco AI Defense Skill Scanner, an open-source tool that detects prompt injection, data exfiltration, and malicious code patterns in Agent Skills.
If you are contributing a new skill, we recommend running the scanner locally before submitting a pull request:
uv pip install cisco-ai-skill-scanner
skill-scanner scan /path/to/your/skill --use-behavioral
Note: A clean scan result reduces noise in review, but does not guarantee a skill is free of all risk. Contributed skills are also reviewed manually before merging.
Contributors are recognized in our community and may be featured in:
Your contributions help make scientific computing more accessible and enable researchers to leverage AI tools more effectively!
This project builds on 50+ amazing open source projects. If you find value in these skills, please consider supporting the projects we depend on.
Problem: Skills not loading
SKILL.md fileProblem: Missing Python dependencies
SKILL.md file for required packagesuv pip install package-nameProblem: API rate limits
Problem: Authentication errors
SKILL.md for authentication setupProblem: Outdated examples
Problem: gh skill install or docs link to scientific-skills/ fails (v2.43.0+)
skills/ (not scientific-skills/) to match the Agent Skills layout expected by GitHub CLIscientific-skills/<name> to skills/<name>gh skill install K-Dense-AI/scientific-agent-skills after pulling the latest releaseQ: Is this free to use?
A: Yes! This repository is MIT licensed. However, each individual skill has its own license specified in the license metadata field within its SKILL.md file—be sure to review and comply with those terms.
Q: Why are all skills grouped together instead of separate packages?
A: We believe good science in the age of AI is inherently interdisciplinary. Bundling all skills together makes it trivial for you (and your agent) to bridge across fields—e.g., combining genomics, cheminformatics, clinical data, and machine learning in one workflow—without worrying about which individual skills to install or wire together.
Q: Can I use this for commercial projects?
A: The repository itself is MIT licensed, which allows commercial use. However, individual skills may have different licenses—check the license field in each skill's SKILL.md file to ensure compliance with your intended use.
Q: Do all skills have the same license?
A: No. Each skill has its own license specified in the license metadata field within its SKILL.md file. These licenses may differ from the repository's MIT License. Users are responsible for reviewing and adhering to the license terms of each individual skill they use.
Q: How often is this updated?
A: We regularly update skills to reflect the latest versions of packages and APIs. Major updates are announced in release notes.
Q: Can I use this with other AI models?
A: The core SKILL.md format follows the open Agent Skills standard. Installation paths, discovery, and optional metadata support vary by host and version, so confirm your target host's current documentation.
Q: Do I need all the Python packages installed?
A: No! Only install the packages you need. Each skill specifies its requirements in its SKILL.md file.
Q: What if a skill doesn't work?
A: First check the Troubleshooting section. If the issue persists, file an issue on GitHub with detailed reproduction steps.
Q: Do the skills work offline?
A: Database skills require internet access to query APIs. Package skills work offline once Python dependencies are installed.
Q: Can I contribute my own skills?
A: Absolutely! We welcome contributions. See the Contributing section for guidelines and best practices.
Q: How do I report bugs or suggest features?
A: Open an issue on GitHub with a clear description. For bugs, include reproduction steps and expected vs actual behavior.
Need help? Here's how to get support:
SKILL.md and references/ foldersIf you use Scientific Agent Skills in your research or project, please cite the overall collection and, when relevant, the individual skill or skills that materially supported your work.
The collection citation helps others find the repository, understand the broader skill ecosystem used in your workflow, and credit the maintenance effort behind Scientific Agent Skills. Individual skill citations give more precise credit for the specific package, database, or workflow guidance your agent used.
Recommended practice:
@software{scientific_agent_skills_2026,
author = {{K-Dense Inc.}},
title = {Scientific Agent Skills: A Comprehensive Collection of Scientific Tools for AI Agents},
year = {2026},
url = {https://github.com/K-Dense-AI/scientific-agent-skills},
note = {158 skills covering databases, packages, integrations, and analysis tools}
}
K-Dense Inc. (2026). Scientific Agent Skills: A comprehensive collection of scientific tools for AI agents [Computer software]. https://github.com/K-Dense-AI/scientific-agent-skills
K-Dense Inc. Scientific Agent Skills: A Comprehensive Collection of Scientific Tools for AI Agents. 2026, github.com/K-Dense-AI/scientific-agent-skills.
Scientific Agent Skills by K-Dense Inc. (2026)
Available at: https://github.com/K-Dense-AI/scientific-agent-skills
When citing a specific skill, include the skill name, version from metadata.version in that skill's SKILL.md, and the direct skill URL. For example:
@software{scientific_agent_skills_astropy_2026,
author = {{K-Dense Inc.}},
title = {Astropy Skill for Scientific Agent Skills},
year = {2026},
url = {https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/astropy},
note = {Version 1.0, part of Scientific Agent Skills}
}
Plain text format:
Astropy skill for Scientific Agent Skills, version 1.0.
K-Dense Inc. (2026).
https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/astropy
We appreciate acknowledgment in publications, presentations, or projects that benefit from these skills.
This project is licensed under the MIT License.
Copyright © 2026 K-Dense Inc. (k-dense.ai)
See LICENSE.md for full terms.
⚠️ Important: Each skill has its own license specified in the
licensemetadata field within itsSKILL.mdfile. These licenses may differ from the repository's MIT License and may include additional terms or restrictions. Users are responsible for reviewing and adhering to the license terms of each individual skill they use.
name: tamarind
description: Access a collection of open-source molecular design and structural biology tools on the Tamarind Bio platform, via its REST API or MCP server — no local GPUs required. Tamarind bundles popular open-source models for structure prediction (AlphaFold, Boltz, Chai, ESMFold), protein, binder, and de novo design (RFdiffusion, ProteinMPNN, BoltzGen), antibody and nanobody design and developability, protein-ligand docking (DiffDock, Autodock Vina), binding-affinity prediction, MSA generation, and molecular dynamics. Use when the user mentions Tamarind or tamarind.bio, wants to run any of these open-source tools in the cloud, references app.tamarind.bio/api or the x-api-key header, or needs to submit batches of sequences for structural or biophysical characterization.
license: MIT
compatibility: Requires Python 3.10+, a Tamarind Bio account, and an API key from app.tamarind.bio. Uses the `requests` library against the public REST API (no dedicated Python SDK exists). Network access required. Optional MCP server at mcp.tamarind.bio/mcp for agent hosts.
metadata:
version: "1.1"
skill-author: Tamarind Bio
trigger-keywords: protein structure prediction, AlphaFold, Boltz, Chai, ESMFold, protein design, binder design, de novo design, antibody design, nanobody, protein-ligand docking, DiffDock, Autodock Vina, binding affinity, MSA generation, inverse folding, ProteinMPNN, RFdiffusion, BoltzGen, cloud GPU biology, structure prediction API, x-api-key, developability, adme, enzyme, peptide, protein language models, molecular design
openclaw:
primaryEnv: TAMARIND_API_KEY
envVars:
- name: TAMARIND_API_KEY
required: true
description: Tamarind Bio API key sent as the x-api-key header.Tamarind Bio is a cloud platform that runs computational biology tools — structure prediction, protein and antibody design, docking, binding-affinity, MSA generation, and molecular dynamics — on managed GPUs. Users submit sequences or structures and get back predicted structures, designs, and biophysical scores, without provisioning their own hardware. It exposes hundreds of tools (AlphaFold, Boltz-2, Chai-1, RFdiffusion, ProteinMPNN, BoltzGen, ESMFold2, DiffDock, Autodock Vina, and many more) through one uniform job API.
Official docs: app.tamarind.bio/api-docs · platform UI at app.tamarind.bio
Tamarind publishes live, machine-readable sources. Prefer fetching them at runtime over trusting any hardcoded list — tool names, schemas, and endpoints change frequently:
https://app.tamarind.bio/llms.txt — LLM index: links to the spec, API docs, and MCP guide.https://app.tamarind.bio/openapi.yaml — OpenAPI 3.0 spec for the 8 core job endpoints (submit-job/-batch, jobs, result, upload, files, delete-job/-file; auth ApiKeyAuth). Fetch it for those exact shapes. Discovery/management endpoints (/tools, /usage-statistics, pipelines, …) aren't in it — use the MCP/REST discovery tools for those.https://docs.tamarind.bio/llms.txt — documentation index; every page has a .md form (e.g. docs.tamarind.bio/tamarind/batch.md, /tamarind/api.md, /tamarind/pipelines.md).GET /tools (REST) or MCP getAvailableTools + getJobSchema(jobType) are the source of truth for what tools exist and their parameters.This skill teaches the surface + the non-obvious behaviors those sources don't spell out (see the reference files). When in doubt about a shape, fetch openapi.yaml.
Use Tamarind when the user wants to:
This skill is the right fit when the work should run on Tamarind's managed cloud rather than on a local install. For purely local cheminformatics or one-off sequence I/O, use a local library (RDKit, BioPython) instead.
x-api-key header.TAMARIND_API_KEY environment variable or a .env file (use python-dotenv). Never commit keys to source control.Pricing: Every user gets 10 free jobs. For larger usage, contact info@tamarind.bio to purchase a subscription.
export TAMARIND_API_KEY="your_api_key"
# List available tools
curl https://app.tamarind.bio/api/tools \
-H "x-api-key: $TAMARIND_API_KEY"
Base URL: https://app.tamarind.bio/api/
There is no official Python SDK — the PyPI package named tamarind is an unrelated Neo4j tool. Do not uv pip install tamarind. Write plain requests calls against the REST API (the endpoint shapes are in openapi.yaml), or use the MCP server for agent hosts.
Tamarind hosts an MCP server at https://mcp.tamarind.bio/mcp (API-key auth via the X-API-Key header). When your agent host supports MCP, prefer it — the tools mirror the REST API with agent-friendly schemas:
listModalities() / listTags() — the live filter vocabulary (molecule type / function) with labels + tool counts; call these to learn valid modality/function values instead of hardcodinggetAvailableTools(modality?, function?, search?, custom?) — discover tools (category/tag are deprecated aliases still honored)getJobSchema(jobType) — exact parameter schema for a tool, plus an exampleJob starting payload (validate it before submitting)validateJob(jobName, type, settings) — dry-run validation before submittingsubmitJob(jobName, type, settings) / submitBatch(batchName, type, settings[], jobNames[])getJobs(jobName?, batch?, limit?, includeSequences?) — list/inspect jobs and statuses (the bulky per-job input blob is omitted by default; pass includeSequences=true to keep it)getJobLogs(jobName) — fetch output logs for debugginglistJobFiles(jobName) — list output files (returns s3Path for chaining)getResult(jobName, fileName?) — download resultsuploadFile(filename) — presigned upload URL; or uploadFileContent(filename, content, encoding?) to send file content through MCP when the host can't reach S3 (sandboxed agents)Scope note: MCP query tools (getJobs, getResult, listJobFiles, …) are scoped to the authenticated account.
Use plain HTTP with requests — the endpoint shapes are in openapi.yaml. The core loop is below; references/workflows.md has full recipes.
Always follow discover → schema → validate → submit → poll → results. Do not hardcode tool names or settings — the catalog changes frequently.
import os, time, requests
BASE = "https://app.tamarind.bio/api"
HEADERS = {"x-api-key": os.environ["TAMARIND_API_KEY"]}
# 1. Discover tools. REST /tools returns the full list; filter client-side.
tools = requests.get(f"{BASE}/tools", headers=HEADERS).json()
alphafold = next(t for t in tools if t["name"] == "alphafold")
# 2. Get the exact schema for the chosen tool.
# REST: each /tools entry already includes its inline `settings` schema
# (parameter list) — find the entry whose name == your job type.
# MCP: getJobSchema(jobType) returns the same per-tool detail.
# 3. Submit a job. `settings` is tool-specific — match the schema exactly.
payload = {
"jobName": "my-alphafold-run", # ^[a-zA-Z0-9_-]+$, <=100 chars, unique
"type": "alphafold",
"settings": {
"sequence": "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
"numRecycles": 3,
},
}
resp = requests.post(f"{BASE}/submit-job", headers=HEADERS, json=payload)
resp.raise_for_status() # 200 ok; 400 bad request; 403 budget exceeded; 401 unauthorized
# 4. Poll for completion.
# NOTE the response shape: GET /jobs?jobName=<name> returns the job ROW
# directly (no "jobs" wrapper); the list query (no jobName) returns
# {"jobs": [...]}. Don't index ["jobs"][0] on the by-name response.
while True:
job = requests.get(f"{BASE}/jobs", headers=HEADERS,
params={"jobName": "my-alphafold-run"}).json()
if job["JobStatus"] in ("Complete", "Stopped", "Deleted"):
break
time.sleep(30)
# 5. Retrieve results. POST /result returns a presigned URL *string*;
# GET that URL to download the actual results zip (two-step).
url = requests.post(f"{BASE}/result", headers=HEADERS,
json={"jobName": "my-alphafold-run"}).text.strip('"')
open("my-alphafold-run.zip", "wb").write(requests.get(url).content)
For the agentic version of this loop using MCP tools, and for richer examples, see references/workflows.md.
The catalog has hundreds of tools. Always enumerate at runtime — never rely on a hardcoded list.
REST GET /tools returns the full list (it does not filter server-side); each item is {name, displayName, github, paper, description, settings} where settings is that tool's inline parameter schema. Filter client-side:
tools = requests.get(f"{BASE}/tools", headers=HEADERS).json() # a list
boltz = [t for t in tools if "boltz" in t["name"].lower()]
Note: both surfaces return one row per tool name — REST /tools and MCP getAvailableTools are both deduplicated (the MCP keeps the newest tool version), so a name match returns a single row.
MCP getAvailableTools(search=..., modality=..., function=...) filters server-side and adds categories/tags per tool (category/tag are deprecated aliases of modality/function, still honored). Don't hardcode the vocabulary — it drifts. Get the live values from listModalities() / listTags() (each returns value, label, description, and toolCount), or read the availableCategories / availableTags facet arrays returned on every getAvailableTools response. Modalities are molecule types (protein, antibody, peptide, small-molecule, nucleic-acid, …); functions are what a tool does (structure-prediction, binder-design, protein-ligand-docking, …).
A representative set of widely-used tools (verify with /tools): alphafold, boltz (Boltz-2), chai (Chai-1), esmfold / esmfold2, rfdiffusion, proteinmpnn, ligandmpnn, boltzgen, bindcraft, diffdock. See references/tool_catalog.md for the full category/tag map and how to read tool metadata.
The catalog has many tools per task; don't hardcode a favorite — filter by function (and modality), then read each candidate's description and match it to the user's actual goal (input you have, output you need, constraints like speed or "no MSA"). The description and tags fields are the public "what it's for" signal; let them, plus validateJob, drive the pick. Quick orientation by task:
function=structure-prediction): the AlphaFold3-class reproductions — boltz/chai/openfold/protenix/intfold — are the accurate default for everything, including protein-only systems; they also handle nucleic-acid + small-molecule complexes, so reach for them whenever a ligand/RNA/DNA is part of the system (and boltz adds binding-affinity). alphafold (AF2) remains a solid choice for monomers + multimers (join chains with :). esmfold is single-sequence (no MSA) and fast — reach for it when you want speed and have no MSA; esmfold2 is newer and conditions on an MSA by default (its model setting offers a faster single-sequence mode). Specialized folders exist for antibodies (abodybuilder, immunebuilder), cyclic peptides (highfold), and conformational ensembles (afcluster, alphaflow) — filter and read descriptions.function=binder-design): bindcraft (de novo miniprotein binders) and boltzgen (binders for protein and small-molecule targets, incl. nanobodies/antibodies/peptides) are the go-to de novo binder tools; rfdiffusion also does binder design and is the pick for motif scaffolding / diversifying an existing backbone. Antibody-specific generators live under function=antibody-design.function=inverse-folding): proteinmpnn (general), ligandmpnn (ligand-aware), plus thermostable/soluble/antibody MPNN variants. Inverse folding takes a structure and emits sequences — fold them back to verify (see chaining).function=protein-ligand-docking): prefer boltz/chai — they co-fold the ligand into the complex and predict the bound structure rather than docking into a fixed receptor; reach for autodock-vina when you need fast, large-scale screening against a known pocket.function=binding-affinity) or generate an MSA (search msa) — filter and read.When the user names a specific tool, evaluate that one and sanity-check the alternatives in its tag group — a faster or more appropriate sibling often exists. When unsure, getJobSchema/validateJob to confirm a candidate actually accepts the input you have before committing.
Each tool has its own settings schema. Fetch it before submitting:
/tools entry: each settings param is a trimmed dict. Only name and required are always present; type, default, description, options appear only when relevant (≈60% have type) — so use param.get("type"), not param["type"]. The advanced gating keys (exclude, conditionals) are NOT in the REST response at all.getJobSchema(jobType): the full schema, including exclude, conditionals, and bounds. Use MCP when you need to reason about those gating keys. (restrictOrgs is stripped on both surfaces — an org-gated param you can't use is simply omitted; see references/api_reference.md.)Always validateJob (MCP) before submitting — it's the reliable guard. It runs the same validation as /submit-job without submitting, and surfaces the first missing/invalid field. Don't try to hand-derive which fields to strip from the schema keys (over REST you can't see them anyway) — let validateJob tell you. (The response may include a source field, e.g. "static-fallback" — an internal note on which schema source validated; valid: true/false is the signal you act on.)
validateJob echoes a normalized view of your settings with defaults filled in. Submit the same clean settings you validated; treat normalized as informational (it can carry defaults you didn't set, and for some tools platform-managed fields), so build your submit from your own settings rather than the normalized blob.
Sequences: amino-acid string; separate chains of a multimer with a colon (:), e.g. "MVLS...:EVQL...". Note that some tools (e.g. boltz, chai) require more than sequence — boltz also requires inputFormat (and accepts yamlFile/molecules). Always getJobSchema/validateJob to learn a tool's required fields; don't assume sequence alone suffices.
Platform-internal fields — never set these yourself; the platform owns them: submit_method, monomer_msa, msa. See references/api_reference.md for the full field-handling rules.
Surface consequential choices before submitting, don't default silently. When the request fully specifies what to run, proceed. But when it's open-ended, or when a setting materially changes the results, runtime, or cost (model/variant, number of samples or seeds, MSA on/off, GPU tier, batch size), present the meaningful options plus the default you'd otherwise apply and let the user pick before you submit — rather than choosing silently and reporting it after the job is queued. getJobSchema and validateJob's normalized show exactly which knobs you're filling in on the user's behalf, so you can flag the few worth a quick confirm. This matters most for batches, where one shared-settings choice multiplies across every job.
Tools with file parameters accept input three ways:
PUT /upload/{filename}, or MCP uploadFile → presigned URL → curl -X PUT -T file "<url>". If your host can't reach S3 (a sandboxed agent with no outbound network), use MCP uploadFileContent(filename, content, encoding?) to send the file's content through the MCP channel instead — text by default, encoding="base64" for binary. The object lands at the S3 key {email}/{filename}, but you reference it in settings by the bare filename only (e.g. "targetFile": "GLP1R_ECD.pdb") — the platform scopes it to your account automatically. Do NOT prefix the email: passing {email}/{filename} double-prefixes the lookup and submit-job 400s with "The following files have not been uploaded: <email>/<file>". Confirm the exact name the store registered with MCP getFiles(search=...) / REST GET /files (a flat list of bare names).JobName/path/to/file.ext (this is how you chain jobs — see below).Foot-gun: for a file-typed parameter, a plain string value is treated as inline file content, not as a path to an existing object. To point at an already-uploaded file, use the bare filename (not the {email}/... S3 key) or, for a prior job's output, the JobName/... path form — not a bare string you expect to resolve to new content.
validateJob notes. The response may carry a source field (e.g. "static-fallback") — it labels how the tool's schema was resolved (built-in tools always report static-fallback), not whether the validator was reachable, so act on valid, not source. For file params: reference an uploaded file by its bare filename (above) — a bare name resolves to your account-scoped object, whereas an email-prefixed string can be read as inline content and fail the file-type check ("... must contain ATOM records"). And passing inline file content makes validateJob upload it synchronously before validating, which can be slow; prefer referencing an uploaded file by name (above). If a dry-run is slow, skip it and let submit-job validate.
A finished job's output becomes the next job's input — no download/re-upload. Match the input type the next tool actually wants: a sequence-design tool (ProteinMPNN) emits sequences, so you fold them by passing each as a sequence; a tool that takes a file parameter takes a path.
The cleanest design→fold chain is the MCP submitBatch(fromJob=...), which reads a completed design job's generated sequences and folds each as one job:
# ProteinMPNN designs sequences -> fold every one with AlphaFold, one call:
submitBatch(batchName="verify-designs", type="alphafold", fromJob="my-proteinmpnn-job")
For a file input (e.g. a tool that takes a .pdb/.cif), reference a prior job's output by the path form JobName/path/to/file.ext in that file parameter. Two cautions, both confirmed by validation: (1) match the parameter's required file type — e.g. AlphaFold's templateFiles accepts only .cif and is a list, and is gated behind templateMode: "custom"; (2) templateFiles is for structural templates, not for "fold this designed sequence" — to fold a sequence, pass sequence. Always getJobSchema/validateJob to confirm a file param's type/conditions before chaining into it.
To discover a job's exact output paths, use MCP listJobFiles(job1) — it returns each file's s3Path, usable directly in the next submitJob. (The REST GET /files lists your account's uploaded files as a flat name list; it does not enumerate a job's outputs.) Tamarind also supports saved pipelines: build one in the UI, then drive it with /run-pipeline ({pipelineName, initialInputs, inputs}) or define stages[] inline via /submit-pipeline (each stage names a task + toolSettings, using "pdbFile": "pipe" to thread one stage's output into the next). See references/workflows.md.
Submit many jobs of the same tool in one call. The Python form uses parallel settings[] and jobNames[] arrays (same length, up to 100):
requests.post(f"{BASE}/submit-batch", headers=HEADERS, json={
"batchName": "egfr-binder-screen",
"type": "alphafold",
"jobNames": ["seq1", "seq2", "seq3"],
"settings": [{"sequence": "..."}, {"sequence": "..."}, {"sequence": "..."}],
# optional: "maxRuntimeSeconds": 3600, "weightedHoursBudget": 100,
# (some accounts also accept an optional "gpuType" — confirm with support)
})
Poll the batch parent on batchStatus, not subjob JobStatus. A batch creates a parent job (Type: "batch") plus subjobs. Subjobs flip to Complete as soon as they finish computing, but the batch then spends a few minutes aggregating results into the final downloadable output. Fetch the parent by name and watch batchStatus:
import time
while True:
# ?jobName= returns the parent ROW directly (no "jobs" wrapper)
parent = requests.get(f"{BASE}/jobs", headers=HEADERS,
params={"jobName": "egfr-binder-screen"}).json()
bs = parent.get("batchStatus")
if bs == "Complete":
break
if bs in ("Stopped", "AggregationFailed"):
raise RuntimeError(parent.get("AggregationError", bs))
time.sleep(15) # Running / Aggregating -> keep waiting
# When Complete, the parent carries a presigned `resultUrl` and a `statuses`
# subjob tally ({Complete, Running, In Queue, Stopped}).
open("batch.zip", "wb").write(requests.get(parent["resultUrl"]).content)
Add includeSubjobs=true to GET /jobs?batch=<name> to list per-subjob rows.
Single jobs report JobStatus; batch parents report batchStatus (poll that for batches — see above).
| Status | Meaning |
|---|---|
In Queue | Accepted, waiting for capacity |
Running | Executing on a worker |
Complete | Finished successfully — results available |
Stopped | Stopped (failure, timeout, manual stop, or budget) |
Deleted | Job was deleted out-of-band |
Aggregating | (batch parent only) subjobs done; building the final output |
AggregationFailed | (batch parent only) aggregation step failed |
Completed jobs carry a Score (tool-specific metrics, e.g. pLDDT/pTM/ipTM for folding) and WeightedHours. Treat Complete/Stopped/Deleted (and AggregationFailed for batches) as terminal; poll on a 15-30s interval. Break your poll loop on any terminal status, not just Complete/Stopped — a job that goes Deleted mid-poll would otherwise loop forever. For a Stopped job, fetch getJobLogs(jobName) to see why. WeightedHours is the usage unit billed per job; cap a batch with weightedHoursBudget, and a 403 on submit means a budget was hit (see references/api_reference.md and the /usage-statistics endpoint).
| Code | Meaning | Action |
|---|---|---|
| 400 | Bad request / invalid settings | Re-check against the schema; run validateJob first |
| 401 | Unauthorized | Check x-api-key |
| 403 | Budget exceeded (org/team) | Lower scope or raise the budget |
| 429 | Rate limited | Back off and retry |
| 500 | Server error | Retry; if persistent, contact support |
The openapi.yaml spec is the source of truth for endpoint shapes; these files add the behaviors and gotchas the spec doesn't spell out:
references/examples.md — validated settings payloads per common tool (alphafold/boltz/diffdock/autodock-vina/proteinmpnn/batch), a copy-paste self-check, the "what fails and the exact error" list, and output-shape notes. Start here for a working payload.references/api_reference.md — endpoint quick-reference + the non-obvious shapes: /jobs by-name returns a bare row (not {jobs:[...]}), /result is a two-step download, batch parents poll on batchStatus, /files is a flat name list, the settings field-handling rules.references/tool_catalog.md — category/tag map, how to read tool + parameter metadata, common tool families.references/workflows.md — end-to-end recipes: fold a sequence, validate-before-submit, upload + reference a file, design→fold chaining, batch screen with aggregation polling, usage stats, pagination, and the non-blocking submit-now/check-later pattern for long jobs.
评论 (0)
暂无评论,成为第一个评论者吧!