ToolUniverse Python SDK
3 calling patterns -- start with pattern 1:
tu.run({"name": ..., "arguments": ...}) -- single tool call, dict API (most portable)tu.tools.ToolName(param=value) -- function API (recommended for interactive use)- Direct class instantiation -- advanced, bypasses caching/hooks
Installation
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
Quick Start
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")
Core Patterns
Batch Execution
calls = [
{"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P05067"}},
{"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}},
]
results = tu.run_batch(calls)
Scientific Workflow
def drug_discovery_pipeline(disease_id):
tu = ToolUniverse(use_cache=True)
tu.load_tools()
try:
targets = tu.tools.OpenTargets_get_associated_targets_by_disease_efoId(efoId=disease_id)
compound_calls = [
{"name": "ChEMBL_search_molecule_by_target",
"arguments": {"target_id": t['id'], "limit": 10}}
for t in targets['data'][:5]
]
compounds = tu.run_batch(compound_calls)
return {"targets": targets, "compounds": compounds}
finally:
tu.close()
Configuration
# Caching
tu = ToolUniverse(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"])
Critical Notes
- Always call
load_tools() before using any tools
- Tool Finder returns nested structure: access via
tools['tools'] after isinstance(tools, dict) check
- Tool names are case-sensitive:
UniProt_get_entry_by_accession not uniprot_get_...
- Check required params:
tu.all_tool_dict["ToolName"]['parameter'].get('required', [])
- Cache deterministic calls (ML predictions, DB queries); don't cache real-time data
Error Handling
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', [])}")
Tool Categories
| Category |
Tools |
Use Cases |
| Proteins |
UniProt, RCSB PDB, AlphaFold |
Protein analysis, structure |
| Drugs |
DrugBank, ChEMBL, PubChem |
Drug discovery, compounds |
| Genomics |
Ensembl, NCBI Gene, gnomAD |
Gene analysis, variants |
| Diseases |
OpenTargets, ClinVar |
Disease-target associations |
| Literature |
PubMed, Europe PMC |
Literature search |
| ML Models |
ADMET-AI, AlphaFold |
Predictions, modeling |
| Pathways |
KEGG, Reactome |
Pathway analysis |
Resources
1---2name: tooluniverse-sdk3description: Build AI scientist systems with the ToolUniverse Python SDK for scientific research. Covers the 3 calling patterns (`tu.run` portable dict API, `tu.tools.X` function API, direct class instantiation), tool loading, batch execution, MCP server integration, and embedding-based tool search. Use for SDK programming, custom tool composition, benchmarking pipelines, and integrating ToolUniverse into research workflows.4---5
6# ToolUniverse Python SDK
7
8**3 calling patterns -- start with pattern 1:**
91. `tu.run({"name": ..., "arguments": ...})` -- single tool call, dict API (most portable)
102. `tu.tools.ToolName(param=value)` -- function API (recommended for interactive use)
113. Direct class instantiation -- advanced, bypasses caching/hooks
12
13## Installation
14
15```bash
16pip install tooluniverse # Standard
17pip install tooluniverse[embedding] # Embedding search (GPU)
18pip install tooluniverse[all] # All features
19```
20
21```bash
22export OPENAI_API_KEY="sk-..." # Required for LLM tool search
23export NCBI_API_KEY="..." # Optional
24```
25
26## Quick Start
27
28```python
29from tooluniverse import ToolUniverse
30
31tu = ToolUniverse()
32tu.load_tools() # REQUIRED before any tool call
33
34# Find tools
35tools = tu.run({"name": "Tool_Finder_Keyword", "arguments": {"description": "protein structure", "limit": 10}})
36
37# Execute (dict API)
38result = tu.run({"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P05067"}})
39
40# Execute (function API)
41result = tu.tools.UniProt_get_entry_by_accession(accession="P05067")
42```
43
44## Core Patterns
45
46### Batch Execution
47
48```python
49calls = [
50 {"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P05067"}},
51 {"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}},
52]
53results = tu.run_batch(calls)
54```
55
56### Scientific Workflow
57
58```python
59def drug_discovery_pipeline(disease_id):
60 tu = ToolUniverse(use_cache=True)
61 tu.load_tools()
62 try:
63 targets = tu.tools.OpenTargets_get_associated_targets_by_disease_efoId(efoId=disease_id)
64 compound_calls = [
65 {"name": "ChEMBL_search_molecule_by_target",
66 "arguments": {"target_id": t['id'], "limit": 10}}
67 for t in targets['data'][:5]
68 ]
69 compounds = tu.run_batch(compound_calls)
70 return {"targets": targets, "compounds": compounds}
71 finally:
72 tu.close()
73```
74
75## Configuration
76
77```python
78# Caching
79tu = ToolUniverse(use_cache=True)
80stats = tu.get_cache_stats()
81tu.clear_cache()
82
83# Hooks (auto-summarization of large outputs)
84tu = ToolUniverse(hooks_enabled=True)
85
86# Load specific categories
87tu.load_tools(categories=["proteins", "drugs"])
88```
89
90## Critical Notes
91
921. **Always call `load_tools()`** before using any tools
932. **Tool Finder returns nested structure**: access via `tools['tools']` after `isinstance(tools, dict)` check
943. **Tool names are case-sensitive**: `UniProt_get_entry_by_accession` not `uniprot_get_...`
954. **Check required params**: `tu.all_tool_dict["ToolName"]['parameter'].get('required', [])`
965. **Cache deterministic calls** (ML predictions, DB queries); don't cache real-time data
97
98## Error Handling
99
100```python
101from tooluniverse.exceptions import ToolError, ToolUnavailableError, ToolValidationError
102
103try:
104 result = tu.tools.some_tool(param="value")
105except ToolUnavailableError:
106 ... # Tool service down
107except ToolValidationError as e:
108 tool_info = tu.all_tool_dict["some_tool"]
109 print(f"Required: {tool_info['parameter'].get('required', [])}")
110```
111
112## Tool Categories
113
114| Category | Tools | Use Cases |
115|----------|-------|-----------|
116| Proteins | UniProt, RCSB PDB, AlphaFold | Protein analysis, structure |
117| Drugs | DrugBank, ChEMBL, PubChem | Drug discovery, compounds |
118| Genomics | Ensembl, NCBI Gene, gnomAD | Gene analysis, variants |
119| Diseases | OpenTargets, ClinVar | Disease-target associations |
120| Literature | PubMed, Europe PMC | Literature search |
121| ML Models | ADMET-AI, AlphaFold | Predictions, modeling |
122| Pathways | KEGG, Reactome | Pathway analysis |
123
124## Resources
125
126- **Docs**: https://zitniklab.hms.harvard.edu/ToolUniverse/
127- **GitHub**: https://github.com/mims-harvard/ToolUniverse
128- See [REFERENCE.md](REFERENCE.md) for detailed guides.
mims-harvard