tooluniverse.base_tool module

class tooluniverse.base_tool.BaseTool

Bases: object

STATIC_CACHE_VERSION = '1'

__init__(tool_config)

_cached_version_hash: str | None

classmethod get_default_config_file()

Get the path to the default configuration file for this tool type.

This method uses a robust path resolution strategy that works across different installation scenarios:

1. Installed packages: Uses importlib.resources for proper package resource access

2. Development mode: Falls back to file-based path resolution

3. Legacy Python: Handles importlib.resources and importlib_resources

Override this method in subclasses to specify a custom defaults file.

Returns

Path or resource object pointing to the defaults file

classmethod load_defaults_from_file()

Load defaults from the configuration file

_apply_defaults(tool_config)

Apply default configuration to the tool config

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

Execute the tool.

The default BaseTool implementation accepts an optional arguments mapping to align with most concrete tool implementations which expect a dictionary of inputs.

Parameters:

• arguments (dict, optional) – Tool-specific arguments

• stream_callback (callable, optional) – Callback for streaming responses

• use_cache (bool, optional) – Whether result caching is enabled

• validate (bool, optional) – Whether parameter validation was performed

Note

These additional parameters (stream_callback, use_cache, validate) are passed from run_one_function() to provide context about the execution. Tools can use these for optimization or special handling.

For backward compatibility, tools that don’t accept these parameters will still work - they will only receive the arguments parameter.

check_function_call(function_call_json)

get_required_parameters()

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

validate_parameters(arguments)

Validate parameters against tool schema.

This method provides standard parameter validation using jsonschema. Subclasses can override this method to implement custom validation logic.

Parameters:

arguments (Dict[str, Any]) – Dictionary of arguments to validate

Returns

ToolError if validation fails, None if validation passes

_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)

Classify a raw exception into a structured ToolError.

This method provides standard error classification. Subclasses can override this method to implement custom error handling logic.

Parameters:

exception (Exception) – The raw exception to classify

Returns

Structured ToolError instance

get_cache_key(arguments)

Generate a cache key for this tool call.

This method provides standard cache key generation. Subclasses can override this method to implement custom caching logic.

Parameters:

arguments (Dict[str, Any]) – Dictionary of arguments for the tool call

Returns

String cache key

supports_streaming()

Check if this tool supports streaming responses.

Returns

True if tool supports streaming, False otherwise

supports_caching()

Check if this tool’s results can be cached.

Returns

True if tool results can be cached, False otherwise

get_batch_concurrency_limit()

Return maximum concurrent executions allowed during batch runs (0 = unlimited).

get_cache_namespace()

Return cache namespace identifier for this tool.

get_cache_version()

Return a stable cache version fingerprint for this tool.

get_cache_ttl(result=None)

Return TTL (seconds) for cached results; None means no expiration.

get_tool_info()

Get comprehensive information about this tool.

Returns

Dictionary containing tool metadata