tooluniverse-sdk

ToolUniverse Python SDK

3 种调用模式——从模式 1 开始：

1. tu.run({"name": ..., "arguments": ...})——单次工具调用，字典 API（兼容性最好）
2. tu.tools.ToolName(param=value)——函数 API（推荐交互式使用）
3. 直接实例化类——高级用法，可绕过缓存/钩子

安装

pip install tooluniverse              # Standard
pip install tooluniverse[embedding]   # Embedding search (GPU)
pip install tooluniverse[all]         # All features

export OPENAI_API_KEY="sk-..."  # Required for LLM tool search
export NCBI_API_KEY="..."       # Optional

快速入门

from tooluniverse import ToolUniverse

tu = ToolUniverse()
tu.load_tools()  # REQUIRED before any tool call

# Find tools
tools = tu.run({"name": "Tool_Finder_Keyword", "arguments": {"description": "protein structure", "limit": 10}})

# Execute (dict API)
result = tu.run({"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P05067"}})

# Execute (function API)
result = tu.tools.UniProt_get_entry_by_accession(accession="P05067")

核心模式

批量执行

calls = [
    {"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P05067"}},
    {"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}},
]
results = tu.run_batch(calls)

科学工作流

def drug_discovery_pipeline(disease_id):
    tu = ToolUniverse()
    tu.load_tools()
    try:
        targets = tu.tools.OpenTargets_get_associated_targets_by_disease_efoId(efoId=disease_id)
        # ChEMBL takes ChEMBL target IDs, not the Ensembl IDs in `targets`;
        # map them first (e.g. via ChEMBL_search_targets). Example IDs: EGFR, COX-2
        chembl_target_ids = ["CHEMBL203", "CHEMBL230"]
        compound_calls = [
            {"name": "ChEMBL_search_activities",
             "arguments": {"target_chembl_id": tid, "limit": 10}}
            for tid in chembl_target_ids
        ]
        compounds = tu.run_batch(compound_calls)
        return {"targets": targets, "compounds": compounds}
    finally:
        tu.close()

配置

# Caching: opt in per call (use_cache is a framework option on tools.X(...),
# not an argument to ToolUniverse() or to the tool itself)
tu = ToolUniverse()
result = tu.tools.some_tool(param="value", use_cache=True)
stats = tu.get_cache_stats()
tu.clear_cache()

# Hooks (auto-summarization of large outputs)
tu = ToolUniverse(hooks_enabled=True)

# Load specific categories
tu.load_tools(categories=["proteins", "drugs"])

重要说明

1. 使用任何工具前，务必调用 load_tools()
2. Tool Finder 会返回嵌套结构：通过 isinstance(tools, dict) 检查后，使用 tools['tools'] 访问
3. 工具名称区分大小写：应使用 UniProt_get_entry_by_accession，而不是 uniprot_get_...
4. 检查必需参数：tu.all_tool_dict["ToolName"]['parameter'].get('required', [])
5. 缓存确定性调用（机器学习预测、数据库查询）；不要缓存实时数据

错误处理

from tooluniverse.exceptions import ToolError, ToolUnavailableError, ToolValidationError

try:
    result = tu.tools.some_tool(param="value")
except ToolUnavailableError:
    ...  # Tool service down
except ToolValidationError as e:
    tool_info = tu.all_tool_dict["some_tool"]
    print(f"Required: {tool_info['parameter'].get('required', [])}")

工具类别

类别	工具	用例
蛋白质	UniProt、RCSB PDB、AlphaFold	蛋白质分析、结构
药物	DrugBank、ChEMBL、PubChem	药物发现、化合物
基因组学	Ensembl、NCBI Gene、gnomAD	基因分析、变异
疾病	OpenTargets、ClinVar	疾病-靶点关联
文献	PubMed、Europe PMC	文献搜索
机器学习模型	ADMET-AI、AlphaFold	预测、建模
通路	KEGG、Reactome	通路分析

资源

• 文档：https://zitniklab.hms.harvard.edu/ToolUniverse/
• GitHub：https://github.com/mims-harvard/ToolUniverse
• 详细指南请参阅 REFERENCE.md。