fabricatio-tool

Tool execution layer for Fabricatio — wraps Python callables as discoverable tools, lets LLMs generate orchestration code, and executes it with safety validation.

Installation

pip install fabricatio[tool]
# or
uv pip install fabricatio[tool]

For all Fabricatio packages:

pip install fabricatio[full]

Overview

fabricatio-tool enables Fabricatio agents to use arbitrary Python functions as tools. Tools are grouped into toolboxes, discovered by an LLM-driven selection process, composed into execution code (also LLM-generated), and run inside a ToolExecutor with import/call safety checks. Results are collected in a ResultCollector for downstream use.

The package also includes built-in filesystem tools and MCP (Model Context Protocol) client and server integration.

Core concepts

Key classes and functions

fabricatio_tool.models.tool

• Tool(source, name, description) — wraps a callable with metadata. invoke(*args, **kwargs) calls through. .signature and .briefing are auto-generated.
• ToolBox(name, description) — collects tools. add_tool(func) appends a tool; collect_tool() works as a decorator. get(name) looks up a tool by name. .briefing produces an LLM-friendly description.

fabricatio_tool.models.collector

• ResultCollector — submit(key, val), revoke(key), take(key) for typed retrieval, error() for retrieving execution errors.
• ApplicationError — captures exception type, message, traceback, and the generated source for retry.

fabricatio_tool.models.executor

• ToolExecutor(candidates, data) — execute(source) runs tool-usage code asynchronously. inject_tools(cxt), inject_data(cxt), inject_collector(cxt) prepare the execution context. from_recipe(recipe, toolboxes) constructs an executor by selecting tools by name.

fabricatio_tool.capabilities

• Handle — draft_tool_usage_code(request, tools, data) generates Python code via LLM. handle(request, data) and handle_fine_grind(request, data) run the full pipeline; on execution failure they re-draft with the partial results, error, and failed source appended to the prompt (max_feedback_rounds, default off).
• HandleTask — extends Handle with handle_task(task, data) for Fabricatio Task objects.

fabricatio_tool.fs

Filesystem utilities callable as tools:

fabricatio_tool.mcp

• get_global_mcp_manager(conf) — singleton MCP manager (Rust-backed).
• mcp_tool_to_function(client_id, tool_name) — converts an MCP tool to an async callable.
• mcp_to_toolbox(client_id) — converts all tools from an MCP client into a ToolBox.

fabricatio_tool.mcp_server

Exposes native Python functions as an MCP server (Rust-backed; stdio and streamable HTTP transports):

• get_global_mcp_server() — singleton MCPServer named "fabricatio", versioned with the installed fabricatio-tool.
• add_tool(func, *, name=None, description=None) — registers a sync or async callable; its JSON input schema is derived from the signature.
• serve(host="127.0.0.1", port=9847) — starts the HTTP transport and returns the server URL.
• serve_stdio() — serves over stdin/stdout for clients that spawn the process.
• ToolBox.to_mcp_server() — exposes an entire toolbox's tools over MCP.

CLI (no console script — use python -m):

python -m fabricatio_tool.mcp_server --stdio mcp_fixture           # stdio transport
python -m fabricatio_tool.mcp_server --http 127.0.0.1 9847 pkg.module[:attr]

Targets are import paths: a bare module defaults to its toolbox attribute, a ToolBox is exported via to_mcp_server(), and any callable is registered directly. Logs go to stderr (stdout belongs to the stdio protocol).

fabricatio_tool.toolboxes

• fs_toolbox — pre-built ToolBox containing all filesystem tools listed above.

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide at ../../docs/source/configuration.rst). Set them under the [ext.tool] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.tool] in pyproject.toml, or via FABRICATIO_EXT__TOOL__<FIELD_UPPER> environment variables.

# fabricatio.toml
[ext.tool]
draft_tool_usage_code_template = "built-in/draft_tool_usage_code"
logging_on_ops = true
error_key = "__error__"
max_feedback_rounds = 0
feedback_max_chars = 6000

CheckConfigModel fields:

• targets: Set[str] — set of strings to check; default set()
• mode: Literal["whitelist", "blacklist"] — check mode; default "whitelist"

ServiceConfig fields:

• type: Literal["stdio", "sse", "stream", "worker"] — transport protocol; default "stdio"
• command: Optional[str] — execution command for stdio-type services
• url: Optional[str] — endpoint URL for SSE/stream/worker-type services
• args: List[str] — command-line arguments for stdio services
• env: Dict[str, JsonValue] — environment variables for the service process

Access at runtime: from fabricatio_tool.config import tool_config.

Usage example

from fabricatio_tool.models.tool import Tool, ToolBox
from fabricatio_tool.models.executor import ToolExecutor

# Define a tool
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

# Build a toolbox
box = ToolBox(name="math", description="Math operations")
box.add_tool(add, logging=True)

# Execute LLM-generated tool-usage code
executor = ToolExecutor(candidates=box.tools, data={})
source = """
async def execute(collector):
    result = await add(3, 4)
    collector.submit('sum', result)
"""
await executor.execute(source)
print(executor.collector.take('sum'))  # 7

With filesystem toolbox

from fabricatio_tool.toolboxes import fs_toolbox

# Use the built-in filesystem tools
executor = ToolExecutor(candidates=fs_toolbox.tools, data={})
source = """
async def execute(collector):
    import pathlib
    await dump_text(pathlib.Path('example.txt'), 'Hello, Fabricatio!')
    content = await safe_text_read(pathlib.Path('example.txt'))
    collector.submit('content', content)
"""
await executor.execute(source)
print(executor.collector.take('content'))  # Hello, Fabricatio!

Using capability mixins

from fabricatio_tool.capabilities.handle import Handle

class MyAgent(Handle):
    ...

agent = MyAgent()
result = await agent.handle(
    "Find all Python files and count their total lines",
    data={"dir": "src/"},
    model="default",
)
if result and not result.error():
    print(result.take("output"))

Safety

ToolExecutor validates generated code against configurable whitelists or blacklists for modules, imports, and function calls. By default, only safe builtins (str, int, float, bool, dict, set, list, pathlib.Path, print, len) and math are permitted.

Dependencies

• fabricatio-core — core interfaces and utilities
• pydantic>=2.11.7

License

MIT — see LICENSE