Tool Calling and Structured Output

1. You tell the model what tools exist (name, description, parameters)  ->  "you may call get_weather(city)"
2. User: "Do I need an umbrella in Paris?"
3. Model replies NOT with text but with a tool request:  get_weather({"city": "Paris"})
4. YOUR code runs get_weather("Paris") for real  ->  {"temp": 14, "rain_chance": 80}
5. You send that result back to the model as a 'tool' message
6. Model writes the final answer: "Yes, bring one. 80% chance of rain, around 14 degrees."

The model never touches the outside world. Your code is always in the middle.

{
  "name": "get_weather",
  "description": "Get the current weather for a city. Use when the user asks about weather or what to wear.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city":  {"type": "string", "description": "City name, e.g. Paris"},
      "units": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    },
    "required": ["city"]
  }
}

import json

# ---------- your tools: ordinary Python functions ----------
def get_weather(city, units="celsius"):
    data = {"paris": (14, 80), "cairo": (33, 0), "oslo": (2, 40)}
    if city.lower() not in data:
        return {"error": f"unknown city '{city}'. Try Paris, Cairo or Oslo."}
    temp, rain = data[city.lower()]
    return {"city": city, "temp": temp if units == "celsius" else round(temp * 9 / 5 + 32), "rain_chance": rain}

def add(a, b):
    return {"result": a + b}

TOOLS = {"get_weather": get_weather, "add": add}

# ---------- a stand-in for the model ----------
def fake_model(messages):
    """Decides what to do next. A real LLM does this from its training."""
    last = messages[-1]
    if last["role"] == "user":
        text = last["content"].lower()
        if "umbrella" in text or "weather" in text:
            city = next((c for c in ["Paris", "Cairo", "Oslo", "Rome"] if c.lower() in text), "Paris")
            return {"type": "tool_call", "name": "get_weather", "args": {"city": city}}
        return {"type": "text", "content": "I can help with weather questions."}
    if last["role"] == "tool":
        result = json.loads(last["content"])
        if "error" in result:
            return {"type": "text", "content": f"Sorry: {result['error']}"}
        need = "Yes, bring an umbrella." if result["rain_chance"] > 50 else "No umbrella needed."
        return {"type": "text", "content": f"{need} It is {result['temp']} degrees, and the chance of rain is {result['rain_chance']}%."}

# ---------- the loop: this is the part YOU write ----------
def run(user_message):
    messages = [{"role": "user", "content": user_message}]
    for step in range(5):                                     # hard cap: never loop forever
        reply = fake_model(messages)
        if reply["type"] == "text":
            return reply["content"]
        print(f"  model asks -> {reply['name']}({reply['args']})")
        result = TOOLS[reply["name"]](**reply["args"])        # YOUR code executes it
        print(f"  tool says  -> {result}")
        messages.append({"role": "tool", "content": json.dumps(result)})
    return "gave up after too many steps"

for q in ["Do I need an umbrella in Paris?", "What is the weather in Rome?"]:
    print("USER:", q)
    print("BOT :", run(q), "\n")

// 1) You send the conversation + tool definitions. The model answers with a tool request:
{"role": "assistant", "tool_calls": [
  {"id": "call_1", "name": "get_weather", "arguments": {"city": "Paris"}}
]}

// 2) You run it and append the result, linking it by id:
{"role": "tool", "tool_call_id": "call_1", "content": "{\"temp\": 14, \"rain_chance\": 80}"}

// 3) You call the model again. This time it answers in text.

def validate(args, schema):
    """A tiny JSON-Schema-style validator (real code: use jsonschema or pydantic)."""
    problems = []
    for name in schema.get("required", []):
        if name not in args:
            problems.append(f"missing required field '{name}'")
    for name, value in args.items():
        spec = schema["properties"].get(name)
        if spec is None:
            problems.append(f"unexpected field '{name}'")
            continue
        types = {"string": str, "integer": int, "number": (int, float)}
        if not isinstance(value, types[spec["type"]]):
            problems.append(f"'{name}' should be {spec['type']}")
        if "enum" in spec and value not in spec["enum"]:
            problems.append(f"'{name}' must be one of {spec['enum']}")
        if "maximum" in spec and isinstance(value, (int, float)) and value > spec["maximum"]:
            problems.append(f"'{name}' must be <= {spec['maximum']}")
    return problems

schema = {
    "properties": {"amount": {"type": "number", "maximum": 100}, "currency": {"type": "string", "enum": ["USD", "EUR"]}},
    "required": ["amount", "currency"],
}

for args in [{"amount": 25, "currency": "USD"},
             {"amount": 5000, "currency": "USD"},
             {"amount": "ten", "currency": "GBP"},
             {"currency": "EUR", "note": "hi"}]:
    print(args, "->", validate(args, schema) or "OK")