Python Guide

Complete guide for using ToolUniverse with Python

Installation

Choose your preferred installation method:

Standard installation with pip:

pip install tooluniverse

Fast, modern package manager:

uv pip install tooluniverse

For contributors and custom modifications:

git clone https://github.com/mims-harvard/ToolUniverse.git
cd ToolUniverse
uv sync  # or: pip install -e .[dev]

Tip

Pro Tip

Use uv for faster installations and better dependency management. Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh

Verify Installation

Check that ToolUniverse is installed correctly:

import tooluniverse
print(f"ToolUniverse version: {tooluniverse.__version__}")
print("✅ Installation successful!")

Quick Start

Get your first scientific query running in 5 minutes:

Step 1: Initialize ToolUniverse

Create a ToolUniverse instance:

from tooluniverse import ToolUniverse

# Initialize ToolUniverse
tu = ToolUniverse()
Step 2: Load Tools

Load the scientific tools ecosystem:

# Load all 1000+ tools
tu.load_tools()

print(f"✅ Loaded {len(tu.all_tools)} scientific tools!")
💡 Advanced: Load Specific Tools

For faster loading, specify tool categories:

# Load only specific tool categories
tu.load_tools(tool_type=['uniprot', 'ChEMBL', 'opentarget'])
Step 3: Execute Your First Tool

Query scientific databases:

# Get protein function from UniProt
result = tu.run({
    "name": "UniProt_get_function_by_accession",
    "arguments": {"accession": "P05067"}
})

print(result)

Important

Success!

You now have access to 1000+ scientific tools for drug discovery, protein analysis, literature search, and more!

Tool Execution

All tools follow a consistent structure:

# Standardized query format
query = {
    "name": "tool_name",           # Tool identifier
    "arguments": {                 # Tool parameters
        "parameter1": "value1",
        "parameter2": "value2"
    }
}

result = tu.run(query)

Two execution methods:

Explicit and clear:

# Method 1: Dictionary API
result = tu.run({
    "name": "OpenTargets_get_associated_targets_by_disease_efoId",
    "arguments": {"efoId": "EFO_0000537"}
})

Convenient shorthand:

# Method 2: Direct Import
from tooluniverse.tools import OpenTargets_get_associated_targets_by_disease_efoId

# Call directly
result = OpenTargets_get_associated_targets_by_disease_efoId(
    efoId="EFO_0000537"
)

Tool Finders

ToolUniverse has three ways to find tools. Don’t browse 1000+ tools manually—use Tool Finder!

Keyword Search
class-card:

hover-lift

shadow:

md

Fast text matching

Best for: Exact terms you know

tools = tu.run({
    "name": "Tool_Finder_Keyword",
    "arguments": {
        "description": "protein structure",
        "limit": 5
    }
})
🤖 LLM Search

Natural language (LLM API required)

Best for: Descriptive queries

tools = tu.run({
    "name": "Tool_Finder_LLM",
    "arguments": {
        "description": "find tools for analyzing gene expression",
        "limit": 5
    }
})
🧠 Semantic Search

Embedding-based (GPU required)

Best for: Conceptual matches

tools = tu.run({
    "name": "Tool_Finder",
    "arguments": {
        "description": "drug safety analysis",
        "limit": 5
    }
})
📋 Browse by Category

Organized view

Best for: Exploring tool types

# List by configuration file
stats = tu.list_built_in_tools(mode='config')

# List by tool type
stats = tu.list_built_in_tools(mode='type')

See also

For detailed guide on finding tools, see Tool Finder Tutorial

Common Examples

Protein & Gene Information

# Get protein function
result = tu.run({
    "name": "UniProt_get_function_by_accession",
    "arguments": {"accession": "P05067"}
})

Drug Safety Analysis

# Check adverse events
result = tu.run({
    "name": "FAERS_count_reactions_by_drug_event",
    "arguments": {"medicinalproduct": "aspirin"}
})

Disease-Target Relationships

# Find therapeutic targets
result = tu.run({
    "name": "OpenTargets_get_associated_targets_by_disease_efoId",
    "arguments": {"efoId": "EFO_0000685"}  # Rheumatoid arthritis
})

Literature Search

# Search scientific papers
result = tu.run({
    "name": "PubTator_search_publications",
    "arguments": {
        "query": "CRISPR cancer therapy",
        "limit": 10
    }
})

Tool Specifications

Inspect tool details before execution:

# Get single tool specification
spec = tu.tool_specification("UniProt_get_function_by_accession", format="openai")

print(f"Name: {spec['name']}")
print(f"Description: {spec['description']}")
print("Parameters:")
for param_name, param_info in spec['parameters']['properties'].items():
    print(f"  - {param_name}: {param_info['type']} - {param_info['description']}")

# Get multiple specifications
specs = tu.get_tool_specification_by_names([
    "FAERS_count_reactions_by_drug_event",
    "OpenTargets_get_associated_targets_by_disease_efoId"
])

See also

For AI-Tool Interaction Protocol details, see AI-Tool Interaction Protocol

Building Workflows

Chain tools for complex research tasks:

Multi-Step Pipeline

from tooluniverse import ToolUniverse

tu = ToolUniverse()
tu.load_tools()

# Step 1: Find tools for drug discovery
tools = tu.run({
    "name": "Tool_Finder_Keyword",
    "arguments": {"description": "drug target", "limit": 3}
})

# Step 2: Get disease targets
targets = tu.run({
    "name": "OpenTargets_get_associated_targets_by_disease_efoId",
    "arguments": {"efoId": "EFO_0000685"}
})

# Step 3: For each target, get protein info
rows = targets['data']['disease']['associatedTargets']['rows']
for row in rows[:3]:  # First 3 targets
    target = row['target']
    protein_info = tu.run({
        "name": "UniProt_get_entry_by_accession",
        "arguments": {"accession": target.get("id")}
    })
    print(f"Target: {target.get('approvedSymbol')}")
    print(f"Protein: {protein_info}")

Batch Execution

Execute multiple tools in parallel:

# Prepare multiple queries
queries = [
    {"name": "UniProt_get_function_by_accession", "arguments": {"accession": "P05067"}},
    {"name": "UniProt_get_function_by_accession", "arguments": {"accession": "P04637"}},
    {"name": "UniProt_get_function_by_accession", "arguments": {"accession": "P01112"}},
]

# Execute in batch
results = [tu.run(query) for query in queries]

See also

Configuration

API Keys

Some tools require API keys for enhanced performance:

Setting Up API Keys

Environment Variables (Recommended)

# Essential for specific features
export NVIDIA_API_KEY=your_nvidia_key_here        # Structure prediction
export HF_TOKEN=your_huggingface_token_here       # Model hosting

# Recommended for better performance
export NCBI_API_KEY=your_ncbi_key_here            # 3x faster queries
export SEMANTIC_SCHOLAR_API_KEY=your_key_here     # 100x faster literature
export FDA_API_KEY=your_fda_key_here              # 6x faster safety data

Using .env File

# Copy template
cp docs/.env.template .env

# Edit with your keys
nano .env

See detailed guide: API Keys and Authentication

Tool Loading Options

# Load all tools (default)
tu.load_tools()

# Load specific categories
tu.load_tools(tool_type=['uniprot', 'ChEMBL', 'opentarget'])

# Load only specific tools by name
tu.load_tools(include_tools=['UniProt_get_function_by_accession', 'PubMed_search_articles'])

Logging

Configure logging for debugging:

import logging

# Enable detailed logging
logging.basicConfig(level=logging.INFO)

# ToolUniverse operations will now log details
tu = ToolUniverse()
tu.load_tools()

See also

For comprehensive logging configuration, see Logging Tutorial

Advanced Features

Tool Composition
link:

tool_composition

link-type:

doc

class-card:

hover-lift

shadow:

md

Chain multiple tools into scientific workflows

Hooks System
link:

hooks/index

link-type:

doc

class-card:

hover-lift

shadow:

md

Intelligent output processing and summarization

Cache System
link:

cache_system

link-type:

doc

class-card:

hover-lift

shadow:

md

Optimize performance with smart caching

HTTP API
link:

http_api

link-type:

doc

class-card:

hover-lift

shadow:

md

Deploy ToolUniverse as a remote service

ChatGPT API
link:

chatgpt_api

link-type:

doc

class-card:

hover-lift

shadow:

md

Use ToolUniverse tools as OpenAI function calls

Complete Case Study: Drug discovery workflow with Gemini 2.5 Pro

API Reference: Detailed Python API documentation

Need Help?