178 lines
3.9 KiB
Markdown
178 lines
3.9 KiB
Markdown
# Tool Execution in ToolUniverse
|
|
|
|
## Overview
|
|
|
|
Execute individual tools through ToolUniverse's standardized interface using the `run()` method.
|
|
|
|
## Basic Tool Execution
|
|
|
|
### Standard Pattern
|
|
```python
|
|
from tooluniverse import ToolUniverse
|
|
|
|
tu = ToolUniverse()
|
|
tu.load_tools()
|
|
|
|
# Execute a tool
|
|
result = tu.run({
|
|
"name": "tool_name_here",
|
|
"arguments": {
|
|
"param1": "value1",
|
|
"param2": "value2"
|
|
}
|
|
})
|
|
|
|
print(result)
|
|
```
|
|
|
|
## Real-World Examples
|
|
|
|
### Example 1: Disease-Target Associations (OpenTargets)
|
|
```python
|
|
# Find targets associated with hypertension
|
|
result = tu.run({
|
|
"name": "OpenTargets_get_associated_targets_by_disease_efoId",
|
|
"arguments": {
|
|
"efoId": "EFO_0000537" # Hypertension
|
|
}
|
|
})
|
|
|
|
print(f"Found {len(result)} targets associated with hypertension")
|
|
```
|
|
|
|
### Example 2: Protein Structure Prediction
|
|
```python
|
|
# Get AlphaFold structure prediction
|
|
result = tu.run({
|
|
"name": "AlphaFold_get_structure",
|
|
"arguments": {
|
|
"uniprot_id": "P12345"
|
|
}
|
|
})
|
|
```
|
|
|
|
### Example 3: Chemical Property Calculation
|
|
```python
|
|
# Calculate molecular descriptors
|
|
result = tu.run({
|
|
"name": "RDKit_calculate_descriptors",
|
|
"arguments": {
|
|
"smiles": "CCO" # Ethanol
|
|
}
|
|
})
|
|
```
|
|
|
|
### Example 4: Gene Expression Analysis
|
|
```python
|
|
# Analyze differential gene expression
|
|
result = tu.run({
|
|
"name": "GeneExpression_differential_analysis",
|
|
"arguments": {
|
|
"dataset_id": "GSE12345",
|
|
"condition1": "control",
|
|
"condition2": "treatment"
|
|
}
|
|
})
|
|
```
|
|
|
|
## Tool Execution Workflow
|
|
|
|
### 1. Discover the Tool
|
|
```python
|
|
# Find relevant tools
|
|
tools = tu.run({
|
|
"name": "Tool_Finder_Keyword",
|
|
"arguments": {
|
|
"description": "pathway enrichment",
|
|
"limit": 5
|
|
}
|
|
})
|
|
|
|
# Review available tools
|
|
for tool in tools:
|
|
print(f"Name: {tool['name']}")
|
|
print(f"Description: {tool['description']}")
|
|
print(f"Parameters: {tool['parameters']}")
|
|
print("---")
|
|
```
|
|
|
|
### 2. Check Tool Parameters
|
|
```python
|
|
# Get detailed tool information
|
|
tool_info = tu.get_tool_info("KEGG_pathway_enrichment")
|
|
print(tool_info['parameters'])
|
|
```
|
|
|
|
### 3. Execute with Proper Arguments
|
|
```python
|
|
# Execute the tool
|
|
result = tu.run({
|
|
"name": "KEGG_pathway_enrichment",
|
|
"arguments": {
|
|
"gene_list": ["TP53", "BRCA1", "EGFR"],
|
|
"organism": "hsa" # Homo sapiens
|
|
}
|
|
})
|
|
```
|
|
|
|
## Handling Tool Results
|
|
|
|
### Check Result Type
|
|
```python
|
|
result = tu.run({
|
|
"name": "some_tool",
|
|
"arguments": {"param": "value"}
|
|
})
|
|
|
|
# Results can be various types
|
|
if isinstance(result, dict):
|
|
print("Dictionary result")
|
|
elif isinstance(result, list):
|
|
print(f"List with {len(result)} items")
|
|
elif isinstance(result, str):
|
|
print("String result")
|
|
```
|
|
|
|
### Process Results
|
|
```python
|
|
# Example: Processing multiple results
|
|
results = tu.run({
|
|
"name": "PubMed_search",
|
|
"arguments": {
|
|
"query": "cancer immunotherapy",
|
|
"max_results": 10
|
|
}
|
|
})
|
|
|
|
for idx, paper in enumerate(results, 1):
|
|
print(f"{idx}. {paper['title']}")
|
|
print(f" PMID: {paper['pmid']}")
|
|
print(f" Authors: {', '.join(paper['authors'][:3])}")
|
|
print()
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
```python
|
|
try:
|
|
result = tu.run({
|
|
"name": "some_tool",
|
|
"arguments": {"param": "value"}
|
|
})
|
|
except Exception as e:
|
|
print(f"Tool execution failed: {e}")
|
|
# Check if tool exists
|
|
# Verify parameter names and types
|
|
# Review tool documentation
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Verify Tool Parameters**: Always check required parameters before execution
|
|
2. **Start Simple**: Test with simple cases before complex workflows
|
|
3. **Handle Results Appropriately**: Check result type and structure
|
|
4. **Error Recovery**: Implement try-except blocks for production code
|
|
5. **Documentation**: Review tool descriptions for parameter requirements and output formats
|
|
6. **Rate Limiting**: Be aware of API rate limits for remote tools
|
|
7. **Data Validation**: Validate input data format (e.g., SMILES, UniProt IDs, gene symbols)
|