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