tooluniverse.base_tool module

class tooluniverse.base_tool.BaseTool

基类：object

STATIC_CACHE_VERSION = '1'

__init__(tool_config)

_cached_version_hash: str | None

classmethod get_default_config_file()

获取此工具类型的默认配置文件路径。

该方法采用了一种稳健的路径解析策略，适用于不同的安装场景：

1. 已安装的软件包：使用 importlib.resources 以实现正确的软件包资源访问

2. 开发模式：回退到基于文件的路径解析

3. 遗留版 Python：处理 importlib.resources 和 importlib_resources

在子类中重写此方法以指定自定义默认值文件。

退货

指向默认文件的路径或资源对象

classmethod load_defaults_from_file()

从配置文件加载默认设置

_apply_defaults(tool_config)

Apply default configuration to the tool config

run(arguments=None, stream_callback=None, use_cache=False, validate=True)

执行该工具。

默认的 BaseTool 实现接受一个可选的参数映射，以便与大多数具体工具实现保持一致，这些工具通常期望输入为字典形式。

参数:

• arguments (dict, optional) – 工具专用参数

• stream_callback (callable, optional) – 用于流式响应的回调

• use_cache (bool, optional) – 是否启用了结果缓存

• validate (bool, optional) – 是否已执行参数验证

备注

这些附加参数（stream_callback、use_cache、validate）由 run_one_function() 传递，用于提供有关执行的上下文。工具可以利用这些参数进行优化或特殊处理。

为了向后兼容，不接受这些参数的工具仍然可以正常工作——它们只会接收到 arguments 参数。

check_function_call(function_call_json)

get_schema_const_operation()

Return the operation value from the tool’s parameter schema, or empty string.

Checks const first (single fixed value), then falls back to the first value in enum (single-value enum is equivalent to const).

get_required_parameters()

Retrieve required parameters from the endpoint definition. Returns list: List of required parameters for the given endpoint.

validate_parameters(arguments)

根据工具架构验证参数。

此方法使用 jsonschema 提供标准参数验证。子类可以重写此方法以实现自定义验证逻辑。

参数:

arguments (Dict[str, Any]) – 参数验证字典

退货

验证失败时返回 ToolError，验证通过时返回 None

_ERROR_CLASSIFICATION = [({'401', '403', 'api key', 'auth', 'token', 'unauthorized'}, <class 'tooluniverse.exceptions.ToolAuthError'>, 'Authentication failed'), ({'429', 'limit exceeded', 'quota', 'rate limit'}, <class 'tooluniverse.exceptions.ToolRateLimitError'>, 'Rate limit exceeded'), ({'404', 'connection', 'network', 'not found', 'timeout', 'unavailable'}, <class 'tooluniverse.exceptions.ToolUnavailableError'>, 'Tool unavailable'), ({'invalid', 'parameter', 'schema', 'validation'}, <class 'tooluniverse.exceptions.ToolValidationError'>, 'Validation error'), ({'config', 'configuration', 'setup'}, <class 'tooluniverse.exceptions.ToolConfigError'>, 'Configuration error'), ({'dependency', 'import', 'module', 'package'}, <class 'tooluniverse.exceptions.ToolDependencyError'>, 'Dependency error')]

handle_error(exception)

将原始异常分类为结构化的 ToolError。

此方法提供标准错误分类。子类可以重写此方法以实现自定义错误处理逻辑。

参数:

exception (Exception) – 用于分类的原始异常

退货

结构化 ToolError 实例

get_cache_key(arguments)

为此工具调用生成缓存键。

此方法提供标准的缓存键生成。子类可以重写此方法以实现自定义的缓存逻辑。

参数:

arguments (Dict[str, Any]) – 工具调用参数字典

退货

字符串缓存键

supports_streaming()

检查此工具是否支持流式响应。

退货

如果工具支持流式处理，则为 True，否则为 False

supports_caching()

检查此工具的结果是否可以缓存。

退货

如果工具结果可以被缓存，则为 True，否则为 False

get_batch_concurrency_limit()

返回批处理运行期间允许的最大并发执行数（0 = 不限）。

get_cache_namespace()

返回此工具的缓存命名空间标识符。

get_cache_version()

为此工具返回稳定的缓存版本指纹。

get_cache_ttl(result=None)

返回缓存结果的TTL（秒）；None表示没有过期时间。

get_tool_info()

获取有关此工具的全面信息。

退货

包含工具元数据的字典