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_... ではなく UniProt_get_entry_by_accession を使用してください
4. 必須パラメーターを確認してください：tu.all_tool_dict["ToolName"]['parameter'].get('required', [])
5. 決定論的な呼び出し（ML 予測、データベースクエリ）はキャッシュし、リアルタイムデータはキャッシュしないでください

エラー処理

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	文献検索
ML モデル	ADMET-AI, AlphaFold	予測、モデリング
経路	KEGG, Reactome	経路解析

リソース

• ドキュメント: https://zitniklab.hms.harvard.edu/ToolUniverse/
• GitHub: https://github.com/mims-harvard/ToolUniverse
• 詳細なガイドについては、REFERENCE.md をご覧ください。