fix: fix m serve tool-calling examples

- switch server example to OpenAIBackend
- align tool-calling example with tested Granite model setup
- narrow advertised tools when `tool_choice` selects a specific function
- enable `tool_calls=True` in the serve path
- replace calculator example with stock-price tool
- examples 1/2 as tool-call-only demos
- example 4 as the full tool execution round-trip
- improve client diagnostics for empty/no-tool responses

Signed-off-by: Mark Sturdevant <mark.sturdevant@ibm.com>
Assisted-by: IBM Bob

Author: markstur

docs/examples/m_serve/client_tool_calling.py

@@ -27,48 +27,55 @@
             "name": "get_weather",
             "description": "Get the current weather in a given location",
             "parameters": {
-                "type": "object",
-                "properties": {
-                    "location": {
-                        "type": "string",
-                        "description": "The city name, e.g. San Francisco",
+                "RootModel": {
+                    "type": "object",
+                    "properties": {
+                        "location": {
+                            "type": "string",
+                            "description": "The city name, e.g. San Francisco",
+                        },
+                        "units": {
+                            "type": "string",
+                            "enum": ["celsius", "fahrenheit"],
+                            "description": "Temperature units",
+                        },
                     },
-                    "units": {
-                        "type": "string",
-                        "enum": ["celsius", "fahrenheit"],
-                        "description": "Temperature units",
-                    },
-                },
-                "required": ["location"],
+                    "required": ["location"],
+                }
             },
         },
     },
     {
         "type": "function",
         "function": {
-            "name": "calculator",
-            "description": "Evaluate a mathematical expression",
+            "name": "get_stock_price",
+            "description": "Get the current stock price for a given ticker symbol",
             "parameters": {
-                "type": "object",
-                "properties": {
-                    "expression": {
-                        "type": "string",
-                        "description": "The mathematical expression to evaluate",
-                    }
-                },
-                "required": ["expression"],
+                "RootModel": {
+                    "type": "object",
+                    "properties": {
+                        "symbol": {
+                            "type": "string",
+                            "description": "The stock ticker symbol, e.g. AAPL, GOOGL",
+                        }
+                    },
+                    "required": ["symbol"],
+                }
             },
         },
     },
 ]
 
 
-def make_request(messages: list[dict], tools: list[dict] | None = None) -> dict:
+def make_request(
+    messages: list[dict], tools: list[dict] | None = None, tool_name: str | None = None
+) -> dict:
     """Make a request to the m serve API.
 
     Args:
         messages: List of message dictionaries
         tools: Optional list of tool definitions
+        tool_name: Optional tool name to request explicitly
 
     Returns:
         Response dictionary from the API
@@ -81,13 +88,53 @@ def make_request(messages: list[dict], tools: list[dict] | None = None) -> dict:
 
     if tools:
         payload["tools"] = tools
-        payload["tool_choice"] = "auto"
+        if tool_name is not None:
+            # m serve forwards tool_choice to compatible backends, but the
+            # downstream provider/model may ignore it or treat it as a weak
+            # preference rather than a guarantee. Use an explicit function
+            # selection in this client so the example demonstrates the API
+            # contract even when the model would otherwise decline to call tools.
+            payload["tool_choice"] = {
+                "type": "function",
+                "function": {"name": tool_name},
+            }
+        else:
+            payload["tool_choice"] = "auto"
 
     response = requests.post(ENDPOINT, json=payload, timeout=30)
-    response.raise_for_status()
+
+    if response.status_code >= 400:
+        try:
+            error_payload = response.json()
+        except ValueError:
+            error_payload = {"error": {"message": response.text}}
+
+        error_message = error_payload.get("error", {}).get("message", response.text)
+        raise requests.HTTPError(
+            f"{response.status_code} Server Error: {error_message}", response=response
+        )
+
     return response.json()
 
 
+def _run_local_tool(tool_name: str, args: dict) -> str:
+    """Simulate local execution of the example tools."""
+    if tool_name == "get_weather":
+        units = args.get("units") or "celsius"
+        unit_suffix = "C" if units == "celsius" else "F"
+        return f"The weather in {args['location']} is sunny and 22°{unit_suffix}"
+    if tool_name == "get_stock_price":
+        mock_prices = {
+            "AAPL": "$175.43",
+            "GOOGL": "$142.87",
+            "MSFT": "$378.91",
+            "TSLA": "$242.15",
+        }
+        symbol = args["symbol"].upper()
+        return f"The current price of {symbol} is {mock_prices.get(symbol, '$100.00')}"
+    return "Tool result"
+
+
 def main():
     """Run example tool calling interactions."""
     print("=" * 60)
@@ -100,7 +147,7 @@ def main():
     messages = [{"role": "user", "content": "What's the weather like in Tokyo?"}]
 
     print(f"User: {messages[0]['content']}")
-    response = make_request(messages, tools=tools)
+    response = make_request(messages, tools=tools, tool_name="get_weather")
 
     choice = response["choices"][0]
     print(f"\nFinish Reason: {choice['finish_reason']}")
@@ -111,16 +158,18 @@ def main():
             func = tool_call["function"]
             args = json.loads(func["arguments"])
             print(f"  - {func['name']}({json.dumps(args)})")
-    else:
+    elif choice.get("message", {}).get("content"):
         print(f"Assistant: {choice['message']['content']}")
+    else:
+        print("Assistant returned no content and no tool calls.")
 
-    # Example 2: Request that should trigger calculator tool
-    print("\n\n2. Math Query")
+    # Example 2: Request that should trigger stock price tool
+    print("\n\n2. Stock Price Query")
     print("-" * 60)
-    messages = [{"role": "user", "content": "What is 15 * 23 + 7?"}]
+    messages = [{"role": "user", "content": "What's the current stock price of AAPL?"}]
 
     print(f"User: {messages[0]['content']}")
-    response = make_request(messages, tools=tools)
+    response = make_request(messages, tools=tools, tool_name="get_stock_price")
 
     choice = response["choices"][0]
     print(f"\nFinish Reason: {choice['finish_reason']}")
@@ -131,8 +180,10 @@ def main():
             func = tool_call["function"]
             args = json.loads(func["arguments"])
             print(f"  - {func['name']}({json.dumps(args)})")
-    else:
+    elif choice.get("message", {}).get("content"):
         print(f"Assistant: {choice['message']['content']}")
+    else:
+        print("Assistant returned no content and no tool calls.")
 
     # Example 3: Request without tools (normal chat)
     print("\n\n3. Normal Chat (No Tools)")
@@ -152,7 +203,7 @@ def main():
     messages = [{"role": "user", "content": "What's the weather in Paris?"}]
 
     print(f"User: {messages[0]['content']}")
-    response = make_request(messages, tools=tools)
+    response = make_request(messages, tools=tools, tool_name="get_weather")
 
     choice = response["choices"][0]
     assistant_message = choice["message"]
@@ -169,17 +220,17 @@ def main():
             }
         )
 
+        tool_results: list[str] = []
+
         # Process each tool call and add tool responses
         for tool_call in assistant_message["tool_calls"]:
             func = tool_call["function"]
             args = json.loads(func["arguments"])
             print(f"  - {func['name']}({json.dumps(args)})")
 
-            # Simulate tool execution
-            if func["name"] == "get_weather":
-                tool_result = f"The weather in {args['location']} is sunny and 22°C"
-            else:
-                tool_result = "Tool result"
+            tool_result = _run_local_tool(func["name"], args)
+            tool_results.append(tool_result)
+            print(f"    Result: {tool_result}")
 
             # Add tool response to conversation
             messages.append(
@@ -190,11 +241,32 @@ def main():
                 }
             )
 
-        # Get final response after tool execution
+        # Get final response after tool execution.
+        # Ask for a concise answer that explicitly uses the tool result so the
+        # example output includes the actual weather/price instead of only a
+        # conversational acknowledgement.
+        messages.append(
+            {
+                "role": "user",
+                "content": (
+                    f"Original question: {messages[0]['content']}\n"
+                    f"Tool result: {'; '.join(tool_results)}\n"
+                    "Answer the original question directly using only that tool "
+                    "result. Do not mention unrelated topics or other tools."
+                ),
+            }
+        )
         print("\nGetting final response after tool execution...")
-        response = make_request(messages, tools=tools)
+        response = make_request(messages, tools=None)
         choice = response["choices"][0]
-        print(f"Assistant: {choice['message']['content']}")
+        if choice.get("message", {}).get("content"):
+            print(f"Assistant: {choice['message']['content']}")
+        else:
+            print("Assistant returned no content after tool execution.")
+    elif assistant_message.get("content"):
+        print(f"Assistant: {assistant_message['content']}")
+    else:
+        print("Assistant returned no content and no tool calls.")
 
     print("\n" + "=" * 60)
     print("Examples completed!")
@@ -208,5 +280,12 @@ def main():
         print("Error: Could not connect to server.")
         print("Make sure the server is running:")
         print("  uv run m serve docs/examples/m_serve/m_serve_example_tool_calling.py")
+    except requests.exceptions.HTTPError as e:
+        print(f"Error: {e}")
+        if e.response is not None:
+            try:
+                print("Server response:", json.dumps(e.response.json(), indent=2))
+            except ValueError:
+                print("Server response:", e.response.text)
     except Exception as e:
         print(f"Error: {e}")