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.

[akihikokuroda]

Here is a plan: Make _call_tools Public API

Context

Currently, _call_tools is a private function in mellea's functional API that executes tool calls from model responses. It includes built-in support for:

• Plugin hooks (TOOL_PRE_INVOKE, TOOL_POST_INVOKE)
• Telemetry and observability
• Proper error handling and state management

The problem: Users who need direct tool execution currently must either:

1. Call internal _call_tools directly (breaks encapsulation, silently bypasses hooks/telemetry)
2. Manually implement tool execution (complex, error-prone, duplicates logic)
3. Use higher-level APIs like act() or instruct() which may not fit their workflows

Documentation and examples already teach patterns using the private function, making the "gap" official but undocumented.

Goal: Make _call_tools a stable public API that users can rely on with full transparency about hook and telemetry support.

Proposed Solution

Rename _call_tools → call_tools and enhance documentation to:

• Explain when and why to use this lower-level primitive
• Document all hooks it fires and telemetry it records
• Clarify that callers manage context state (not bundled)
• Show comparison with higher-level act() / instruct() patterns
• Provide clear examples in docs/examples/

Scope constraints:

• Keep return type as list[ToolMessage] (don't bundle context management)
• Ensure hooks and telemetry continue to fire correctly
• Don't change the function's core behavior, only its visibility and documentation
• Related bug transform()/atransform() discard the result of Context.add, so the tool message never reaches the returned context #1475 (tool messages not added to contexts) addressed separately

Implementation Plan

Phase 1: Code Changes

1. Rename the function in mellea/stdlib/functional.py (or location TBD by exploration):

• _call_tools → call_tools
• Update all internal calls to use new name
  • Keep old _call_tools as deprecated private wrapper if needed for backwards compat

2. Update exports:

• Add call_tools to mellea/stdlib/init.py or appropriate all
• Remove any underscore-prefixed entries if they exist
  Enhance docstring to include:
• Clear description of when/why to use this vs. higher-level APIs
• Hook firing points and their purpose
• Telemetry recorded (usage, errors, latency)
  • Note that callers are responsible for context state management
  • Return type clarification: list[ToolMessage]

4. Update all internal references to the public name throughout the codebase

Phase 2: Documentation

1. API reference (docs/docs/api/):

• Regenerate if auto-generated
• Ensure call_tools appears with correct docstring

2. Conceptual guide (new or update existing):

• Title: "Tool Execution Primitives" or "Manual Tool Call Handling"
• Section: When to use call_tools vs. act() / instruct()
• Section: Understanding hooks and telemetry
• Examples showing context management patterns

3. Examples in docs/examples/:

• Add or update example showing call_tools usage
• Show proper context state management
  • Demonstrate hook observation (if observability examples exist)
  • Include comparison with act() usage

Phase 3: Testing & Verification

1. Update existing tests that import _call_tools to use new public name
   Add new tests covering:

• Hook firing for public API
• Telemetry recorded correctly
• Return type is as documented

3. Example validation via pytest:

• Run validate-snippets skill on new documentation

4. Manual verification:

• Ensure uv run pytest -m "not qualitative" passes
• Run ruff format and ruff check
• Run mypy for type checking
• Regenerate CLI docs if applicable

Phase 4: Migration Path

1. Deprecation notice (optional, if _call_tools wrapper kept):

• Add comment: "Use call_tools() instead of _call_tools()"
• Can be removed in next major version

2. No breaking changes for code already using _call_tools:

• Both names work during transition period (if wrapper kept)

Critical Files to Modify

• mellea/stdlib/functional.py — where _call_tools lives, needs rename + docstring enhancement
• mellea/stdlib/init.py — add to public exports
• docs/docs/api/ — regenerate if auto-generated
• docs/examples/ — add/update tool execution examples
• test/ — update imports, add new tests for public API
• Any other internal files importing _call_tools (identified by exploration)

Verification Checklist

• call_tools is exported from mellea.stdlib
• All tests pass: uv run pytest -m "not qualitative"
• Type checking passes: uv run mypy .
• Linting clean: uv run ruff check . / uv run ruff format .
  [ ] Documentation builds: uv run poe clidocs (if CLI ref affected)
• Docstring quality: uv run python tooling/docs-autogen/audit_coverage.py --quality --threshold 100 (if in all)
• New examples validate: uv run validate-snippets on doc snippets
• Hooks fire correctly: verify in tests or manual observation

Notes

• Relationship to transform()/atransform() discard the result of Context.add, so the tool message never reaches the returned context #1475: That issue is a separate bug about context state management. This proposal intentionally keeps the function at the lower level (returning list[ToolMessage] only) to leave context handling to callers.
• Hook/telemetry transparency: Part of making this public is documenting exactly what happens inside — users should not be surprised by observability side effects.
• Backwards compatibility: If old _call_tools wrapper is kept for one version, can be removed cleanly with clear deprecation messaging.

Exploration Results (Completed)

Location & Signature

• File: mellea/stdlib/functional.py (lines 1316–1419)
• Sync wrapper: def _call_tools(result: ModelOutputThunk, backend: Backend) -> list[ToolMessage]:
• Async impl: async def _acall_tools(result: ModelOutputThunk, backend: Backend) -> list[ToolMessage]:
• Sync version delegates to async via _run_async_in_thread()

Hooks Fired

1. TOOL_PRE_INVOKE (before tool execution)

• Payload: ToolPreInvokePayload with tool_invocation_id, model_tool_call, is_control_flow
• Allows plugins to inspect/modify tool call before invocation

2. TOOL_POST_INVOKE (after tool execution)

• Payload: ToolPostInvokePayload with tool_invocation_id, model_tool_call, tool_output, tool_message, execution_time_ms, success, error, is_control_flow
• Allows plugins to inspect or transform tool output

Telemetry

• Execution time via time.monotonic() (recorded as execution_time_ms)
• Success/failure status (boolean flag)
• Error object if execution fails
• Tool invocation UUID for tracing across hooks

Return Type

• Always list[ToolMessage] (may be empty if no tool calls)
• Each message contains: role, content, tool_output, name, args, tool

Current Usage

• Already imported in docs/examples/plugins/tool_hooks.py (7+ usages)
• Used internally by transform(), atransform(), react() functions
• Pattern demonstrates the gap: examples show users importing private API

[ajbozarth]

In general I think this plan looks ok, I had thought we should wrap _call_tools in a new call_tools function, but I hadn't realized that all it did was call _run_async_in_thread(_acall_tools()) so I am good with just renaming to a public call_tools