# 需要：pip install openai
# 前置：ollama pull qwen2.5:3b && ollama serve
# Note: Stage 3+ 用 qwen2.5:3b（tool-use 穩定）、不是 gemma4:e4b
import sys, json
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# Step 1: 定義 tool schema — OpenAI-compatible 格式包一層 {"type":"function", "function":{...}}
weather_tool = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查詢城市目前天氣（晴/雨/陰），回傳一個短字串。",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名稱（如「台北」）"},
            },
            "required": ["city"],
        },
    },
}

# Step 2: 問問題、讓 LLM 自己決定要不要呼叫 tool
resp = client.chat.completions.create(
    model="qwen2.5:3b",
    max_tokens=512,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "台北現在有下雨嗎？"}],
)

# === 自我驗證 ===
msg = resp.choices[0].message
print("finish_reason:", resp.choices[0].finish_reason)
print("tool_calls:", msg.tool_calls)

assert msg.tool_calls, "預期 LLM 會選擇呼叫 tool（而非直接回答）"
tc = msg.tool_calls[0]
assert tc.function.name == "get_weather", f"預期呼叫 get_weather、實際 {tc.function.name}"
args = json.loads(tc.function.arguments)
assert args.get("city"), "預期 city 參數有值"
print(f"✅ 練習 1 通過 — qwen2.5:3b 正確選了 get_weather、帶 city='{args['city']}' 參數")

預期輸出（樣本）：

finish_reason: tool_calls
tool_calls: [ChatCompletionMessageToolCall(id='call_xxx', function=Function(name='get_weather', arguments='{"city": "台北"}'), type='function')]
✅ 練習 1 通過 — qwen2.5:3b 正確選了 get_weather、帶 city='台北' 參數

沒裝 Ollama 也能驗邏輯：用 unittest.mock.MagicMock 取代 client、塞固定 response、assert 一樣 work。完整 mock 範例見 examples/stage-3/03-react-from-scratch/test.py（pattern 跨 backend 通用）。

# 需要：pip install anthropic
# 環境變數：export ANTHROPIC_API_KEY=sk-ant-...
import anthropic

client = anthropic.Anthropic()

# Anthropic native tool schema — 不用包 wrapper
weather_tool = {
    "name": "get_weather",
    "description": "查詢城市目前天氣（晴/雨/陰），回傳一個短字串。",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "城市名稱（如「台北」）"},
        },
        "required": ["city"],
    },
}

resp = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=512,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "台北現在有下雨嗎？"}],
)

# === 自我驗證 ===
assert resp.stop_reason == "tool_use", f"非預期 stop_reason: {resp.stop_reason}"
tool_calls = [b for b in resp.content if b.type == "tool_use"]
assert tool_calls[0].name == "get_weather"
assert tool_calls[0].input.get("city")
print(f"✅ 練習 1 通過（Anthropic）— Claude 選了 get_weather、city='{tool_calls[0].input['city']}'")

3 個關鍵 SDK 差異：

• Schema wrap：Anthropic 直接 tools=[{name, description, input_schema}]；OpenAI/Ollama 要包 [{"type":"function", "function":{...}}]
• Response 路徑：Anthropic 從 resp.content[i].type=="tool_use" 抓；OpenAI/Ollama 從 resp.choices[0].message.tool_calls[i]
• Args 格式：Anthropic .input 是 dict（自動 parse）；OpenAI/Ollama .function.arguments 是 JSON string，要 json.loads(...)

成本：1 次 ≈ $0.001。Claude 的 tool-use 比 qwen2.5:3b 更穩——複雜場景（5+ tools、模糊問題）gap 會明顯。

NEW vs 練習 1：tools 從 1 個變 3 個。LLM 看 description 邊界決定挑哪個——description 寫得越像「給人讀的 docstring」、越容易挑錯。

from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

TOOLS = [
    {"type": "function", "function": {"name": "web_search",
        "description": "Search current or external info not in the prompt.",
        "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}},
    {"type": "function", "function": {"name": "calculator",
        "description": "Evaluate basic arithmetic with +, -, *, /, parentheses.",
        "parameters": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}}},
    {"type": "function", "function": {"name": "calendar_lookup",
        "description": "Look up events for a specific date.",
        "parameters": {"type": "object", "properties": {"date": {"type": "string"}}, "required": ["date"]}}},
]

resp = client.chat.completions.create(model="qwen2.5:3b", tools=TOOLS,
    messages=[{"role": "user", "content": "What is (19 * 42) - 8?"}])

tc = resp.choices[0].message.tool_calls[0]
print(f"LLM 挑了: {tc.function.name}, args: {json.loads(tc.function.arguments)}")
# 預期：calculator, {"expression": "(19 * 42) - 8"}

punchline：3 個 tool 的 description 邊界要互斥——calendar 寫「行事曆」太籠統、會跟 web_search 撞；寫「特定日期事件」就清楚。小 model 對 description 質量比 Claude 更敏感。

Path B (Anthropic) 改 3 行：schema 拿掉 {"type": "function", "function": {...}} 外包、tool_calls 變 [b for b in resp.content if b.type == "tool_use"]、tc.input 已經是 dict 不用 json.loads。完整版見 folder。

NEW vs 練習 2：把單次 call 包進迴圈、messages 一直長、看 tool_calls 在不在來決定收尾。

# 假設 TOOLS + TOOL_IMPL（dict: name → callable）已經像練習 2 一樣定義好
messages = [{"role": "user", "content": "台北人口除以紐約人口？"}]

for step in range(5): # max_iter safety net
    r = client.chat.completions.create(model="qwen2.5:3b", tools=TOOLS, messages=messages)
    msg = r.choices[0].message
    # 把 assistant response 接回 messages（重要！下輪 LLM 才看得到自己上輪講什麼）
    messages.append({"role": "assistant", "content": msg.content, "tool_calls": msg.tool_calls})
    if not msg.tool_calls:
        print(f"✅ 收尾：{msg.content}"); break
    for tc in msg.tool_calls:
        args = json.loads(tc.function.arguments)
        obs = TOOL_IMPL[tc.function.name](args) # 本地執行
        # observation 接回 messages（用 role="tool"、配 tool_call_id）
        messages.append({"role": "tool", "tool_call_id": tc.id, "content": obs})

3 個容易踩坑：

1. 忘記把 assistant response 加回 messages——下輪 LLM 看不到自己上輪講什麼、會 loop forever
2. tool message 沒帶 tool_call_id——LLM 無法配對哪個 result 對應哪個 call
3. 沒 max_iter——tool 結果寫不好時、LLM 會無限呼叫，safety net 必須設

Path B (Anthropic) 差幾行：迴圈架構一模一樣、msg.tool_calls 變 [b for b in resp.content if b.type == "tool_use"]、用 stop_reason == "end_turn" 判停、tool result 包成 {"type": "tool_result", "tool_use_id": ..., "content": obs} 放進 user message。完整版見 folder。

NEW vs 練習 3：完全同一個 loop——只是 TOOLS 換成 4 個（lookup_population / divide / to_percentage / round_int）、題目自然走完 4 輪 tool call 才收尾。

# 沒有新 code、純粹是 TOOLS / TOOL_IMPL 換內容
TOOL_IMPL = {
    "lookup_population": lambda i: lookup_population(i["city"]),
    "divide": lambda i: divide(i["a"], i["b"]),
    "to_percentage": lambda i: to_percentage(i["ratio"]),
    "round_int": lambda i: round_int(i["x"]),
}
# loop 完全照 練習 3，只是 max_iter 拉大到 8

punchline：多步推理不是新 pattern、是讓 ReAct loop 跑久一點。真正的挑戰是「LLM 會不會中間漏一步」——qwen2.5:3b 可能漏「轉百分比」、Claude haiku 較穩。這恰好是觀察「model 規模 vs 多步穩定度」的好實驗。試試 MODEL=qwen2.5:7b python starter.py 對照。

NEW vs 練習 4：tool error 回傳結構化 dict、不要 raise。loop 把 dict 接回 LLM、模型自己決定 retry / 改 query / 放棄。

def fetch_weather(city: str) -> dict:
    if network_failed():
        return {"error": "network timeout", "retry_hint": "try again in 1s"}
    return {"city": city, "forecast": "rain", "temperature_c": 24}

# loop 裡：
obs = fetch_weather(args["city"])
messages.append({"role": "tool", "tool_call_id": tc.id,
                 "content": json.dumps(obs, ensure_ascii=False)}) # error dict 也是 string 化接回去
# 下一輪 LLM 看到 retry_hint、可能會 retry、可能會放棄、可能會改 query

為什麼不 raise：raise 直接中斷 loop、LLM 沒機會 recover。Production 的 retry 不在 Python 層、而在 LLM 層——這個 mental flip 是 Stage 3 練習 5 的核心。

Bad vs Good error 回傳：

小 model 觀察：qwen2.5:3b 對 retry_hint follow-up 較弱、可能直接放棄；Claude haiku 較穩。完整版（含連續失敗 graceful end 範例）見 folder。

NEW vs 練習 5：同一個工具（溫度轉換）、兩種 schema 寫法。看 4 個差別。

# ❌ BAD — qwen2.5:3b 幾乎必錯（Claude haiku 還能猜對、但機率明顯下降）
{"name": "convert", "description": "Convert a value.",
 "parameters": {"type": "object", "properties": {
     "value": {"type": "string"}, "unit": {"type": "string"}}}}

# ✅ GOOD — qwen 也能穩定挑對
{"name": "convert_temperature",
 "description": "Use when user asks to convert temperatures between Fahrenheit and Celsius.",
 "parameters": {"type": "object", "properties": {
     "value": {"type": "number", "description": "Temperature value"},
     "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}},
     "required": ["value", "unit"]}}

4 個改進：(1) name 改具體、(2) description 寫「何時用」而非「做什麼」、(3) type 改 number、(4) 加 required + enum。

punchline：寫 schema 的功夫能省下換大 model 的成本——小 model 對 schema 質量比大 model 敏感，相同 bad schema 在 Claude 上可能還能猜對、在 qwen 上幾乎必錯。Production 想用便宜 model？schema 必須寫到 production-grade。

搞不定 schema 怎麼辦：裝 examples/stage-5/tool-calling-tutor/ skill，遇到「LLM 不呼叫我的 tool」、「我這 schema 哪裡寫壞」會自動跳出來幫你 debug。