工具清单教程¶

ToolUniverse provides powerful methods for discovering and exploring the available tools in the system.

概述¶

工具发现的主要方法是``list_built_in_tools()``，它提供了关于所有可用工具的全面信息。此方法支持多种模式，帮助您从不同角度了解工具，并以多种格式访问工具数据。

API 参考¶

备注

For complete Python API documentation, see API参考 for commonly used classes and methods, or API参考 for full API reference.

tooluniverse.execute_function.ToolUniverse.list_built_in_tools(self, mode='config', scan_all=False)

列出所有内置工具类别及其统计数据，并区分不同模式。

此方法提供了对ToolUniverse中所有可用工具的全面概览，并按类别进行组织。它直接从默认工具文件中读取数据以收集统计信息，因此即使在调用load_tools()之前也能正常工作。

参数:

mode (str, optional) – 工具的组织模式。默认值为“config”。 - “config”：按配置文件类别组织（原始行为） - “type”：按工具类型（实现类）组织 - “list_name”：返回所有工具名称的列表 - “list_spec”：返回所有工具规格的列表
scan_all (bool, optional) – 是否递归扫描数据目录中的所有 JSON 文件。如果为 True，则扫描数据/及其子目录中的所有 JSON 文件。如果为 False（默认值），则使用预定义的工具文件映射。

返回:

对于“config”和“type”模式：包含工具统计信息的字典
对于“list_name”模式：所有工具名称的列表
对于“list_spec”模式：所有工具规格的列表

返回类型:

dict or list

示例

>>> tool_universe = ToolUniverse()
>>> # Group by config file categories (predefined files only)
>>> stats = tool_universe.list_built_in_tools(mode='config')
>>> # Scan all JSON files in data directory recursively
>>> stats = tool_universe.list_built_in_tools(mode='config', scan_all=True)
>>> # Get all tool names from all JSON files
>>> tool_names = tool_universe.list_built_in_tools(mode='list_name', scan_all=True)

备注

此方法直接从工具文件中读取数据，无需调用 load_tools()。
工具在各类别之间已去重，因此同一工具不会被重复计数。
当调用此方法时，摘要会自动打印到控制台（list_name 和 list_spec 模式除外）。
当 scan_all=True 时，系统会扫描 data/ 目录及其子目录中的所有 JSON 文件

快速入门¶

from tooluniverse import ToolUniverse

# Initialize ToolUniverse
tu = ToolUniverse()

# List all tools by config categories (default)
stats = tu.list_built_in_tools()

# List all tools by implementation types
type_stats = tu.list_built_in_tools(mode='type')

# Get all tool names as a list
tool_names = tu.list_built_in_tools(mode='list_name')

# Get all tool specifications as a list
tool_specs = tu.list_built_in_tools(mode='list_spec')

# Scan all JSON files recursively (not just predefined ones)
all_tools = tu.list_built_in_tools(mode='list_name', scan_all=True)

可用模式¶

list_built_in_tools() 方法支持多种模式以适应不同的使用场景：

列表名称模式¶

返回按字母顺序排序的所有工具名称的简单列表。

# Get all tool names as a list
tool_names = tu.list_built_in_tools(mode='list_name')
print(f"Found {len(tool_names)} tools")
print(tool_names[:5])  # First 5 tool names

使用场景： - 快速查找工具名称 - 构建工具选择界面 - 工具名称验证 - 简单的工具计数

列表规格模式¶

返回所有工具规格（完整工具配置）的列表。

# Get all tool specifications
tool_specs = tu.list_built_in_tools(mode='list_spec')
print(f"Found {len(tool_specs)} tool specifications")

# Access tool details
for tool in tool_specs[:3]:
    print(f"Tool: {tool['name']}, Type: {tool['type']}")

使用场景： - 访问完整的工具配置 - 工具元数据分析 - 构建工具数据库 - 工具规格验证

配置模式（默认）¶

配置模式根据工具的配置文件类别进行组织，按功能或数据来源对其进行逻辑分组。

# Default mode - organize by config file categories
stats = tu.list_built_in_tools()
# or explicitly:
stats = tu.list_built_in_tools(mode='config')

使用场景： - 了解可用的数据源 - 按功能领域查找工具（例如，临床试验、药物信息、文献检索） - 获取涵盖的科学领域概览

示例类别： - fda_drug_label - FDA药物标签工具 - clinical_trials - 临床试验数据工具 - semantic_scholar - 学术文献工具 - opentarget - OpenTargets平台工具 - chembl - ChEMBL数据库工具

类型模式¶

类型模式根据工具的实现类进行组织，展示工具的技术分类。

# Organize by tool types/implementation classes
stats = tu.list_built_in_tools(mode='type')

使用场景： - 了解技术架构 - 按实现模式查找工具 - 调试与开发工作 - 工具组合与工作流构建

示例类型： - FDADrugLabel - FDA药物标签工具实现 - OpenTarget - OpenTargets API工具实现 - ChEMBLTool - ChEMBL数据库工具实现 - MCPAutoLoaderTool - MCP客户端自动加载工具

扫描全部选项¶

所有模式均支持 scan_all 参数，用于控制工具的发现方式：

# Use predefined tool files (default, faster)
tools = tu.list_built_in_tools(mode='list_name', scan_all=False)

# Scan all JSON files in data directory recursively (more comprehensive)
all_tools = tu.list_built_in_tools(mode='list_name', scan_all=True)

何时使用 scan_all=True： - 发现未包含在预定义映射中的工具 - 查找自定义或附加的 JSON 文件中的工具 - 全面工具发现 - 开发与测试

何时使用 scan_all=False（默认值）： - 生产环境（更快） - 标准工具发现 - 仅需预定义工具时

返回结构¶

返回结构取决于模式：

对于“config”和“type”模式： 返回包含全面统计数据和信息的字典：

{
    'categories': {
        'category_name': {
            'count': int,          # Number of tools in this category
            'tools': list          # List of tool names (only in 'type' mode)
        },
        # ... more categories
    },
    'total_categories': int,        # Total number of categories
    'total_tools': int,            # Total number of unique tools
    'mode': str,                   # The mode used ('config' or 'type')
    'summary': str                 # Human-readable summary
}

对于“list_name”模式： 返回按排序顺序排列的工具名称列表：

['ADMETAI_predict_BBB_penetrance', 'ADMETAI_predict_CYP_interactions', ...]

对于“list_spec”模式： 返回工具规格字典列表：

[
    {
        'name': 'ADMETAI_predict_BBB_penetrance',
        'type': 'ADMETAITool',
        'description': 'Predicts blood-brain barrier penetrance...',
        'parameter': {...}
    },
    ...
]

访问工具信息¶

获取统计数据后，您可以访问有关工具的详细信息：

# Get statistics
stats = tu.list_built_in_tools(mode='type')

# Access category information
categories = stats['categories']
total_tools = stats['total_tools']

# For type mode, get tools in a specific category
if 'FDADrugLabel' in categories:
    fda_tools = categories['FDADrugLabel']['tools']
    print(f"Found {len(fda_tools)} FDA drug label tools:")
    for tool in fda_tools[:5]:  # Show first 5
        print(f"  - {tool}")

实际示例¶

示例 1：按数据源查找工具¶

from tooluniverse import ToolUniverse

tu = ToolUniverse()

# List tools by config categories to see data sources
stats = tu.list_built_in_tools(mode='config')

print(f"Available data sources: {len(stats['categories'])}")
print(f"Total tools available: {stats['total_tools']}")

# Find categories related to drug information
drug_categories = [cat for cat in stats['categories'].keys()
                  if 'drug' in cat.lower() or 'fda' in cat.lower()]
print(f"Drug-related categories: {drug_categories}")

示例 2：理解工具实现类型¶

# List tools by implementation type
type_stats = tu.list_built_in_tools(mode='type')

# Find the most common tool types
sorted_types = sorted(type_stats['categories'].items(),
                     key=lambda x: x[1]['count'],
                     reverse=True)

print("Top 5 tool types by count:")
for tool_type, info in sorted_types[:5]:
    print(f"  {tool_type}: {info['count']} tools")

    # Show some example tools for this type
    if 'tools' in info:
        examples = info['tools'][:3]
        for example in examples:
            print(f"    - {example}")

示例 3：两种模式的比较¶

# Compare different modes
config_stats = tu.list_built_in_tools(mode='config')
type_stats = tu.list_built_in_tools(mode='type')
tool_names = tu.list_built_in_tools(mode='list_name')
tool_specs = tu.list_built_in_tools(mode='list_spec')

print(f"Config mode: {config_stats['total_categories']} categories")
print(f"Type mode: {type_stats['total_categories']} types")
print(f"Tool names: {len(tool_names)} tools")
print(f"Tool specs: {len(tool_specs)} specifications")

# Compare predefined vs scan_all
predefined_tools = tu.list_built_in_tools(mode='list_name', scan_all=False)
all_tools = tu.list_built_in_tools(mode='list_name', scan_all=True)

print(f"Predefined tools: {len(predefined_tools)}")
print(f"All tools (scan_all): {len(all_tools)}")
print(f"Additional tools found: {len(all_tools) - len(predefined_tools)}")

# Find which implementation types are most diverse
for tool_type, info in type_stats['categories'].items():
    if info['count'] > 10:  # Focus on types with many tools
        print(f"{tool_type}: {info['count']} implementations")

筛选与选择¶

虽然 list_built_in_tools() 显示所有可用工具，但您可以使用其他方法筛选工具：

tooluniverse.execute_function.ToolUniverse.select_tools(self, include_names=None, exclude_names=None, include_categories=None, exclude_categories=None)

根据工具名称和/或类别（tool_files 键）选择工具。

已弃用：请改用 filter_tools()。

参数:

include_names (list, optional) – 要包含的工具名称列表。如果为 None，则包含所有工具。
exclude_names (list, optional) – 要排除的工具名称列表。
include_categories (list, optional) – 包含的类别列表（tool_files 键）。如果为 None，则包含所有类别。
exclude_categories (list, optional) – 要排除的类别列表（tool_files 键）。

返回:

所选工具配置列表。

返回类型:

list

tooluniverse.execute_function.ToolUniverse.refresh_tool_name_desc(self, enable_full_desc=False, include_names=None, exclude_names=None, include_categories=None, exclude_categories=None)

使用可选过滤刷新工具名称和描述映射。

此方法重建内部工具字典，并根据提供的筛选条件生成经过筛选的工具名称和描述列表。

参数:

enable_full_desc (bool, optional) – 如果为 True，则将完整的工具 JSON 作为描述包含在内。若为 False，则使用“名称: 描述”格式。默认值为 False。
include_names (list, optional) – 要包含的工具名称列表。
exclude_names (list, optional) – 要排除的工具名称列表。
include_categories (list, optional) – 包含的类别列表。
exclude_categories (list, optional) – 要排除的类别列表。

返回:

经过筛选后包含（tool_name_list，tool_desc_list）的元组。

返回类型:

tuple

# Load tools first
tu.load_tools()

# Select tools from specific categories
selected_tools = tu.select_tools(
    include_categories=['opentarget', 'chembl'],
    exclude_names=['tool_to_exclude']
)

# Get filtered tool names and descriptions
tool_names, tool_descs = tu.refresh_tool_name_desc(
    include_categories=['fda_drug_label'],
    exclude_categories=['deprecated_tools']
)

无加载工具操作¶

list_built_in_tools() 的一个主要优点是它在调用 load_tools() 之前即可运行：

# You can explore available tools immediately after initialization
tu = ToolUniverse()

# All these work without loading tools first
tool_names = tu.list_built_in_tools(mode='list_name')
tool_specs = tu.list_built_in_tools(mode='list_spec')
stats = tu.list_built_in_tools(mode='config')

# Only then load tools if needed
tu.load_tools()