fabricatio_tool.models.tool

A module for defining tools and toolboxes.

This module provides classes for defining tools and toolboxes, which can be used to manage and execute callable functions with additional functionalities such as logging, execution info, and briefing.

Classes

Tool	A class representing a tool with a callable source function.
ToolBox	A class representing a collection of tools.

Module Contents

class fabricatio_tool.models.tool.Tool[**P, R](/, **data: Any)

Bases: fabricatio_core.models.generic.WithBriefing

A class representing a tool with a callable source function.

This class encapsulates a callable function (source) and provides methods to invoke it, log its execution, and generate a brief description (briefing) of the tool.

name: str = None

The name of the tool.

description: str = None

The description of the tool.

source: Callable[P, R]

The source function of the tool.

model_post_init(__context: Any) → None

Initialize the tool with a name and a source function.

This method sets the tool’s name and description based on the source function’s name and docstring.

Parameters:

__context (Any) – Context passed during model initialization.

Raises:

RuntimeError – If the tool does not have a source function.

invoke(*args: P.args, **kwargs: P.kwargs) → R

Invoke the tool’s source function with the provided arguments.

This method logs the invocation of the tool and then calls the source function with the given arguments.

Parameters:

• *args (P.args) – Positional arguments to be passed to the source function.

• **kwargs (P.kwargs) – Keyword arguments to be passed to the source function.

Returns:

The result of the source function.

Return type:

R

property signature: str

Return the signature of the tool’s source function.

property briefing: str

Return a brief description of the tool.

This method generates a brief description of the tool, including its name, signature, and description.

Returns:

A brief description of the tool.

Return type:

str

class fabricatio_tool.models.tool.ToolBox(/, **data: Any)

Bases: fabricatio_core.models.generic.WithBriefing

A class representing a collection of tools.

This class manages a list of tools and provides methods to add tools, retrieve tools by name, and generate a brief description (briefing) of the toolbox.

description: str = ''

The description of the toolbox.

tools: List[Tool] = None

A list of tools in the toolbox.

collect_tool[**P, R](*, confirm: bool = tool_config.confirm_on_ops, logging: bool = tool_config.logging_on_ops) → Callable[[Callable[P, R]], Callable[P, R]]

collect_tool(func: Callable[P, R]) → Callable[P, R]

Add a callable function to the toolbox as a tool.

This method wraps the function with logging execution info and adds it to the toolbox.

Parameters:

• func (Callable[P, R]) – The function to be added as a tool.

• confirm (bool, optional) – Whether to confirm before executing the function. Defaults to True.

• logging (bool, optional) – Whether to log the execution info. Defaults to True.

Returns:

The added function.

Return type:

Callable[P, R]

add_tool[**P, R](func: Callable[P, R], *, confirm: bool = tool_config.confirm_on_ops, logging: bool = tool_config.logging_on_ops) → Self

Add a callable function to the toolbox as a tool.

This method wraps the function with logging execution info and adds it to the toolbox.

Parameters:

• func (Callable) – The function to be added as a tool.

• confirm (bool, optional) – Whether to confirm before executing the function. Defaults to True.

• logging (bool, optional) – Whether to log the execution info. Defaults to True.

Returns:

The current instance of the toolbox.

Return type:

Self

property briefing: str

Return a brief description of the toolbox.

This method generates a brief description of the toolbox, including its name, description, and a list of tools.

Returns:

A brief description of the toolbox.

Return type:

str

get(name: str) → Tool | None

Retrieve a tool by its name from the toolbox.

This method looks up and returns a tool with the specified name from the list of tools in the toolbox.

Parameters:

name (str) – The name of the tool to retrieve.

Returns:

The tool instance with the specified name if found; otherwise, None.

Return type:

Optional[Tool]

__hash__() → int

Return a hash of the toolbox based on its briefing.

Returns:

A hash value based on the toolbox’s briefing.

Return type:

int