Implementation:Run llama Llama index ToolNodeMapping

Overview

The ToolNodeMapping module provides object-to-node mappings for LlamaIndex tool objects. It defines mappings for both general BaseTool instances and specialized QueryEngineTool instances, enabling tools to be indexed, retrieved, and selected via vector similarity search. This module is located at llama-index-core/llama_index/core/objects/tool_node_mapping.py (154 lines).

Purpose

This module enables dynamic tool selection in agentic workflows. By converting tool metadata (name, description, schema) into text nodes that can be embedded and retrieved, the system can select the most relevant tools for a given query from a potentially large tool collection without requiring the LLM to evaluate every tool in its context window.

Key Components

Helper Function: convert_tool_to_node

def convert_tool_to_node(tool: BaseTool) -> TextNode

A standalone utility function that converts any BaseTool into a TextNode. This function is shared by multiple mapping classes.

Node construction details:

Component	Value
Node ID	str(hash(tool_identity)) where tool_identity = "{name}{description}{fn_schema}".
Text content	Multi-line string containing tool name, description, and optionally the JSON schema of the function signature.
Metadata	{"name": tool.metadata.name}.
Excluded metadata keys	"name" is excluded from both embedding and LLM metadata.

The text content format is:

Tool name: {name}
Tool description: {description}
Tool schema: {fn_schema_json}

The schema line is only included when tool.metadata.fn_schema is not None.

Class: BaseToolNodeMapping (Abstract)

An abstract base class extending BaseObjectNodeMapping[BaseTool] for tool-specific mappings.

Method	Description
validate_object	Checks that the object is an instance of BaseTool. Raises ValueError otherwise.
obj_node_mapping	Raises NotImplementedError.
persist	Raises NotImplementedError.
from_persist_dir	Raises NotImplementedError with a message that tool mappings do not support persistence.

Class: SimpleToolNodeMapping

A concrete implementation of BaseToolNodeMapping that stores tools in memory keyed by their name.

Constructor

def __init__(self, objs: Optional[Sequence[BaseTool]] = None) -> None

Initializes an internal dictionary self._tools mapping tool names to tool instances.

Method Implementations

Method	Description
from_objects	Class method that instantiates the mapping from a sequence of BaseTool objects.
_add_object	Adds a tool to the internal dictionary keyed by tool.metadata.name.
to_node	Delegates to the convert_tool_to_node() helper function.
_from_node	Looks up the tool by node.metadata["name"] in the internal dictionary. Raises ValueError if metadata is None.

Class: BaseQueryToolNodeMapping (Abstract)

An abstract base class extending BaseObjectNodeMapping[QueryEngineTool] for query-engine-tool-specific mappings.

Method	Description
from_persist_dir	Raises NotImplementedError.
obj_node_mapping	Raises NotImplementedError.
persist	Raises NotImplementedError.

Class: SimpleQueryToolNodeMapping

A concrete implementation of BaseQueryToolNodeMapping that stores QueryEngineTool instances in memory.

Constructor

def __init__(self, objs: Optional[Sequence[QueryEngineTool]] = None) -> None

Initializes an internal dictionary self._tools mapping tool names to QueryEngineTool instances.

Method Implementations

Method	Description
validate_object	Checks that the object is an instance of QueryEngineTool. Raises ValueError otherwise.
from_objects	Class method that instantiates the mapping from a sequence of QueryEngineTool objects.
_add_object	Adds a tool keyed by name. Raises ValueError if the tool name is None.
to_node	Delegates to the convert_tool_to_node() helper function.
_from_node	Looks up the tool by node.metadata["name"]. Raises ValueError if metadata is None.

Class Hierarchy

BaseObjectNodeMapping[BaseTool]
  +-- BaseToolNodeMapping
        +-- SimpleToolNodeMapping

BaseObjectNodeMapping[QueryEngineTool]
  +-- BaseQueryToolNodeMapping
        +-- SimpleQueryToolNodeMapping

Dependencies

Module	Items Imported
llama_index.core.objects.base_node_mapping	DEFAULT_PERSIST_DIR, DEFAULT_PERSIST_FNAME, BaseObjectNodeMapping
llama_index.core.schema	BaseNode, TextNode
llama_index.core.tools.query_engine	QueryEngineTool
llama_index.core.tools.types	BaseTool

Design Notes

• Name-based identity: Tools are stored and looked up by their metadata.name, which is assumed to be unique within a single mapping instance.
• No persistence: Tool mappings are inherently ephemeral because tool objects (especially QueryEngineTool wrapping live query engines) are not serializable.
• Shared conversion logic: The convert_tool_to_node() function is shared between SimpleToolNodeMapping and SimpleQueryToolNodeMapping, ensuring consistent node representation regardless of the tool type.
• Two parallel hierarchies: The module maintains separate class hierarchies for BaseTool and QueryEngineTool to provide type-safe validation, even though the conversion logic is identical.