Should "_call_tools" in mellea/stdlib/functional.py be public?

[akihikokuroda]

The "_call_tools" is the only method that executes tools requested by the model call. It is used only in

1. transform() function in functional.py (line 472) - MObject case

• After getting a model response with tool calls, executes them
• Selects the best tool output to return based on type matching

2. react.py reasoning loop (line 123) - React framework

• Executes tool responses returned from the model during ReAct loop
• Adds each tool response to the context
• Checks if the final tool (MELLEA_FINALIZER_TOOL) was called to determine if reasoning is complete

So Mellea executes tools automatically in only these cases.

Programs that use "(a)instruct" or "(a)act" must process the tool_call in model response. The "_call_tools" method is useful for the case but it is an internal function.

Should "_call_tools" in mellea/stdlib/functional.py be changed public?

[psschwei]

Programs that use "(a)instruct" or "(a)act" must process the tool_call in model response.

How are tools currently processed in those scenarios?

[akihikokuroda]

The caller of (a)instruct" or "(a)act takes out tool_calls from model response(ModelOutputThunk) and loop through returned tool calls and call "call_func()" for each of them.

[akihikokuroda]

Here is the _call_tools code

def _call_tools(result: ModelOutputThunk, backend: Backend) -> list[ToolMessage]:
    """Call all the tools requested in a result's tool calls object.                                                                                   
                                                                                                                                                       
    Returns:                                                                                                                                           
        list[ToolMessage]: A list of tool messages that can be empty.                                                                                  
    """
    return _run_async_in_thread(_acall_tools(result, backend))


async def _acall_tools(result: ModelOutputThunk, backend: Backend) -> list[ToolMessage]:
    """Call all the tools requested in a result's tool calls object.                                                                                   
                                                                                                                                                       
    Call tools with tool_pre_invoke / tool_post_invoke hook support.                                                                                   
                                                                                                                                                       
    Returns:                                                                                                                                           
        list[ToolMessage]: A list of tool messages that can be empty.                                                                                  
    """
    outputs: list[ToolMessage] = []
    tool_calls = result.tool_calls
    if not tool_calls:
        return outputs

    for tool in tool_calls:
        name = tool.name
        control_flow = is_internal_tool(name)
        tool_invocation_id = str(uuid.uuid4())

        # --- tool_pre_invoke ---                                                                                                                      
        if has_plugins(HookType.TOOL_PRE_INVOKE):
            pre_payload = ToolPreInvokePayload(
                tool_invocation_id=tool_invocation_id,
                model_tool_call=tool,
                is_control_flow=control_flow,
            )
            _, pre_payload = await invoke_hook(
                HookType.TOOL_PRE_INVOKE, pre_payload, backend=backend
            )
            if pre_payload.model_tool_call is not tool and isinstance(
                pre_payload.model_tool_call, ModelToolCall
            ):
              	tool = pre_payload.model_tool_call

        # --- execute the tool ---                                                                                                                     
        t0 = time.monotonic()
        success = True
        error: Exception | None = None
        try:
            output = tool.call_func()
        except Exception as e:
            output = e
            success = False
            error = e
        latency_ms = int((time.monotonic() - t0) * 1000)

	# Default to the output. Attempt to properly print it. If that doesn't result in a str,                                                        
        # stringify it.                                                                                                                                
	content = str(output)
        if isinstance(backend, FormatterBackend):
            content = backend.formatter.print(output)  # type: ignore                                                                                  
            content = str(content)

        tool_msg = ToolMessage(
            role="tool",
            content=content,
            tool_output=output,
            name=name,
            args=tool.args,
            tool=tool,
        )

        # --- tool_post_invoke ---                                                                                                                     
        if has_plugins(HookType.TOOL_POST_INVOKE):
            post_payload = ToolPostInvokePayload(
                tool_invocation_id=tool_invocation_id,
                model_tool_call=tool,
                tool_output=output,
                tool_message=tool_msg,
                execution_time_ms=latency_ms,
                success=success,
                error=error,
                is_control_flow=control_flow,
            )
            _, post_payload = await invoke_hook(
                HookType.TOOL_POST_INVOKE, post_payload, backend=backend
            )
            # If a plugin modified tool_output, reformat and rebuild the ToolMessage                                                                   
            if post_payload.tool_output is not output:
                output = post_payload.tool_output
                content = str(output)
                if isinstance(backend, FormatterBackend):
                    content = backend.formatter.print(output)  # type: ignore                                                                          
                    content = str(content)
                tool_msg = ToolMessage(
                    role="tool",
                    content=content,
                    tool_output=output,
                    name=name,
                    args=tool.args,
                    tool=tool,
                )

        outputs.append(tool_msg)

    return outputs

[akihikokuroda]

Tool usage telemetry is emitted in _call_tools

[psschwei]

Should "_call_tools" in mellea/stdlib/functional.py be changed public?

I would not promote as is. If we did expose something like this, we should probably implement a new helper, maybe something like call_tools(mot, ctx, backend) -> (list[ToolMessage], Context), that better matches the codebase conventions.

Would be good for others to weigh in too: @generative-computing/mellea-maintainers

[ajbozarth]

I think I agree with this view point, but I'd need to spend some more time in the code thinking deeper to have a better option of such a design

[planetf1]

Yes, expose it. Users calling instruct()/act() with tool_calls=True have a documented path — call .call_func() directly — but it silently bypasses every plugin hook (TOOL_PRE_INVOKE/TOOL_POST_INVOKE) and the execute_tool OTel span that ToolTracingPlugin emits off those hooks. That is true across the nine doc locations teaching that pattern today.

We already ship a tool_hooks.py example that imports _call_tools by the private name — the gap is already live.

On the shape: keep list[ToolMessage], do not add context to the return. The two in-tree callers want genuinely different context behaviour — transform selects one message from potentially many and is meant to add only that one (it currently does not — see #1475); react adds all of them. A single helper that returns an updated context cannot serve both.

External frameworks point the same way, but the stronger argument is in our own tree. For reference: LangGraph's ToolNode returns messages and lets the graph state reducer handle merging; smolagents exposes execute_tool_call as the bare primitive and builds process_tool_calls (which updates memory) on top — the primitive is public, the state-updating wrapper is a separate layer. That is the layering we would be providing here.

On "matches codebase conventions": act/instruct/transform return (value, Context) because they generate context entries. call_tools executes something the caller then decides what to do with — different responsibility, different return shape is right.

Fix: drop the underscores (_call_tools → call_tools, _acall_tools → acall_tools). Add Args: sections to both docstrings and mention hook/telemetry support explicitly — currently only the async variant's docstring references it, and that is the whole reason a user would prefer this over calling .call_func() directly. One follow-on in the same PR: react.py calls the sync variant from async context and should switch to acall_tools.

Side note — filed as #1475: lines 502 and 1271 in functional.py call new_ctx.add(chosen_tool) and discard the return value. Context.add is non-mutating, so the tool message never reaches the returned context despite the log line saying it did. The asymmetry with react.py:125 (context = context.add(tool_res)) is real and worth fixing independently of how this discussion resolves.