Weather Tool Calling Agent

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,78 @@
+---
+title: Weather Tool Calling Agent
+emoji: ⛅
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.49.1
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Weather Tool Calling Agent
+
+Bu Space, bir dil modelinin kullanıcı sorusuna göre araç seçmesini, açık bir API'den
+veri almasını ve araç sonuçlarından nihai yanıt üretmesini gösterir.
+
+## Akış
+
+1. Model şehir başına `get_weather` çağırır.
+2. Fonksiyon, Open-Meteo Geocoding ve Forecast API'lerinden güncel veriyi alır.
+3. Kullanıcı Fahrenheit isterse model her sıcaklık için `convert_temperature` çağırır.
+4. Arayüz model turlarını, argümanları ve araç çıktılarını açıkça gösterir.
+5. Model, araç sonuçlarına dayanarak Türkçe nihai yanıtı üretir.
+
+## Tool JSON şemaları
+
+Uygulamadaki `TOOLS` sabiti iki function definition içerir:
+
+- `get_weather(city: string)`
+- `convert_temperature(value: number, from_unit: "C"|"F", to_unit: "C"|"F")`
+
+Her ikisi de strict JSON Schema kullanır.
+
+## Teknolojiler
+
+- Gradio
+- OpenAI Responses API
+- OpenRouter Chat Completions API
+- Open-Meteo (ücretsiz, API anahtarı gerektirmez)
+- `httpx`
+
+## Hugging Face Spaces kurulumu
+
+1. Yeni bir **Gradio Space** açın.
+2. Bu klasördeki `app.py`, `requirements.txt` ve `README.md` dosyalarını Space'e yükleyin.
+3. Space → **Settings → Variables and secrets → New secret** bölümünde:
+   - Ad: `OPENAI_API_KEY`
+   - Değer: OpenAI API anahtarınız
+4. OpenRouter'ı Space anahtarıyla sunmak isterseniz `OPENROUTER_API_KEY` Secret'ını ekleyin.
+5. İsteğe bağlı variable: `OPENAI_MODEL=gpt-5.6-sol`
+6. Space yeniden başladıktan sonra örnek sorguyla test edin.
+
+API anahtarları Secret olarak tanımlanmazsa kullanıcı arayüzde kendi OpenAI veya
+OpenRouter anahtarını geçici olarak girebilir. Anahtar loglanmaz veya diske yazılmaz.
+
+OpenRouter model listesi canlı katalogdan alınır ve yalnızca `tools` desteğini ilan
+eden modeller gösterilir.
+
+## Yerelde çalıştırma
+
+```bash
+pip install -r requirements.txt
+export OPENAI_API_KEY="..."
+python app.py
+```
+
+## Örnek
+
+> Ankara mı daha sıcak Londra mı, ve bu değerler Fahrenheit olarak kaç eder?
+
+İz panelinde önce iki `get_weather`, ardından gerekli `convert_temperature` çağrıları
+görünür; son panelde karşılaştırmalı yanıt yer alır.
+
+## Veri ve güvenilirlik notu
+
+Hava durumu Open-Meteo'dan çalışma anında alınır. Şehir bulunamazsa veya dış servis
+erişilemezse uygulama veri uydurmak yerine hata bilgisini modele geri verir.

app.py

@@ -0,0 +1,354 @@
+import json
+import os
+from typing import Any
+
+import gradio as gr
+import httpx
+from openai import OpenAI
+
+from llm_providers import (
+    OPENAI_DEFAULT,
+    OPENROUTER_DEFAULT,
+    provider_models,
+    run_openrouter_tool_loop,
+)
+
+MODEL = os.getenv("OPENAI_MODEL", OPENAI_DEFAULT)
+TIMEOUT = 15.0
+MAX_TURNS = 6
+
+WEATHER_CODES = {
+    0: "açık",
+    1: "çoğunlukla açık",
+    2: "parçalı bulutlu",
+    3: "kapalı",
+    45: "sisli",
+    48: "kırağılı sis",
+    51: "hafif çisenti",
+    53: "çisenti",
+    55: "yoğun çisenti",
+    61: "hafif yağmurlu",
+    63: "yağmurlu",
+    65: "şiddetli yağmurlu",
+    71: "hafif kar yağışlı",
+    73: "kar yağışlı",
+    75: "yoğun kar yağışlı",
+    80: "hafif sağanak",
+    81: "sağanak",
+    82: "şiddetli sağanak",
+    95: "gök gürültülü fırtına",
+}
+
+TOOLS = [
+    {
+        "type": "function",
+        "name": "get_weather",
+        "description": (
+            "Bir şehir adını koordinata çevirir ve Open-Meteo'dan o konumdaki "
+            "güncel sıcaklık, hissedilen sıcaklık, hava durumu ve rüzgârı getirir. "
+            "Başarılı sonuç city, country, temp_c, apparent_temp_c, sky ve wind_kmh alanlarını içerir."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "city": {
+                    "type": "string",
+                    "description": "Hava durumu istenen şehir; ör. Ankara veya London",
+                }
+            },
+            "required": ["city"],
+            "additionalProperties": False,
+        },
+        "strict": True,
+    },
+    {
+        "type": "function",
+        "name": "convert_temperature",
+        "description": (
+            "Sıcaklığı Celsius veya Fahrenheit birimine dönüştürür. "
+            "Sonuç value, unit, source_value ve source_unit alanlarını içerir."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "value": {"type": "number", "description": "Dönüştürülecek sıcaklık"},
+                "from_unit": {
+                    "type": "string",
+                    "enum": ["C", "F"],
+                    "description": "Kaynak birim",
+                },
+                "to_unit": {
+                    "type": "string",
+                    "enum": ["C", "F"],
+                    "description": "Hedef birim",
+                },
+            },
+            "required": ["value", "from_unit", "to_unit"],
+            "additionalProperties": False,
+        },
+        "strict": True,
+    },
+]
+
+SYSTEM_PROMPT = """Sen Türkçe yanıt veren bir hava durumu asistanısın.
+Güncel hava durumu sorularında mutlaka get_weather aracını kullan.
+Kullanıcı sıcaklığı farklı bir birimde isterse hesaplamayı kendin yapma; her değer için
+convert_temperature aracını kullan. Birden fazla şehir için bağımsız çağrıları aynı turda
+yapabilirsin. Araç sonucu hata içerirse bunu açıkça belirt ve veri uydurma.
+Son yanıtı kısa, karşılaştırmalı ve kullanılan birimleri açık yazarak ver."""
+
+
+def get_weather(city: str) -> dict[str, Any]:
+    with httpx.Client(timeout=TIMEOUT, follow_redirects=True) as client:
+        geo_response = client.get(
+            "https://geocoding-api.open-meteo.com/v1/search",
+            params={"name": city, "count": 1, "language": "tr", "format": "json"},
+        )
+        geo_response.raise_for_status()
+        matches = geo_response.json().get("results") or []
+        if not matches:
+            return {"error": f"'{city}' için konum bulunamadı."}
+
+        place = matches[0]
+        weather_response = client.get(
+            "https://api.open-meteo.com/v1/forecast",
+            params={
+                "latitude": place["latitude"],
+                "longitude": place["longitude"],
+                "current": "temperature_2m,apparent_temperature,weather_code,wind_speed_10m",
+                "timezone": "auto",
+            },
+        )
+        weather_response.raise_for_status()
+        current = weather_response.json()["current"]
+
+    code = int(current["weather_code"])
+    return {
+        "city": place["name"],
+        "country": place.get("country", ""),
+        "temp_c": current["temperature_2m"],
+        "apparent_temp_c": current["apparent_temperature"],
+        "sky": WEATHER_CODES.get(code, f"hava kodu {code}"),
+        "wind_kmh": current["wind_speed_10m"],
+        "observed_at": current["time"],
+        "source": "Open-Meteo",
+    }
+
+
+def convert_temperature(value: float, from_unit: str, to_unit: str) -> dict[str, Any]:
+    if from_unit == to_unit:
+        converted = value
+    elif from_unit == "C" and to_unit == "F":
+        converted = value * 9 / 5 + 32
+    else:
+        converted = (value - 32) * 5 / 9
+    return {
+        "value": round(converted, 1),
+        "unit": to_unit,
+        "source_value": value,
+        "source_unit": from_unit,
+    }
+
+
+FUNCTIONS = {
+    "get_weather": get_weather,
+    "convert_temperature": convert_temperature,
+}
+
+
+def _as_dict(item: Any) -> dict[str, Any]:
+    if hasattr(item, "model_dump"):
+        return item.model_dump(exclude_none=True)
+    return dict(item)
+
+
+def _trace_markdown(events: list[dict[str, Any]]) -> str:
+    if not events:
+        return "_Henüz araç çağrısı yok._"
+    blocks = []
+    for event in events:
+        blocks.append(
+            f"### Turn {event['turn']} · `{event['tool']}`\n"
+            f"**→ Argümanlar**\n```json\n"
+            f"{json.dumps(event['arguments'], ensure_ascii=False, indent=2)}\n```\n"
+            f"**← Araç çıktısı**\n```json\n"
+            f"{json.dumps(event['result'], ensure_ascii=False, indent=2)}\n```"
+        )
+    return "\n\n".join(blocks)
+
+
+def _provider_controls(provider: str):
+    models = provider_models(provider)
+    default = OPENROUTER_DEFAULT if provider == "OpenRouter" else MODEL
+    values = {value for _, value in models}
+    if default not in values:
+        default = models[0][1]
+    return (
+        gr.update(choices=models, value=default),
+        gr.update(visible=provider == "OpenAI"),
+        gr.update(visible=provider == "OpenRouter"),
+    )
+
+
+def ask(question: str, provider: str, model: str, openai_key: str, openrouter_key: str):
+    question = (question or "").strip()
+    if provider == "OpenRouter":
+        key = (openrouter_key or "").strip() or os.getenv("OPENROUTER_API_KEY", "")
+    else:
+        key = (openai_key or "").strip() or os.getenv("OPENAI_API_KEY", "")
+    if not question:
+        return "Lütfen bir soru yazın.", "_Henüz araç çağrısı yok._"
+    if not key:
+        return (
+            (
+                f"{provider} API anahtarı gerekli. Space sahibi ilgili Secret'ı "
+                "tanımlayabilir veya anahtarı yalnızca bu istek için alana girebilirsiniz."
+            ),
+            "_İstek modele gönderilmedi._",
+        )
+
+    if provider == "OpenRouter":
+        try:
+            text, provider_trace = run_openrouter_tool_loop(
+                api_key=key,
+                model=model,
+                system_prompt=SYSTEM_PROMPT,
+                user_prompt=question,
+                tools=TOOLS,
+                execute_tool=lambda name, arguments: FUNCTIONS[name](**arguments),
+                max_turns=MAX_TURNS,
+            )
+            trace = [
+                {
+                    "turn": item["turn"],
+                    "tool": item["name"],
+                    "arguments": item["detail"]["arguments"],
+                    "result": item["detail"]["result"],
+                }
+                for item in provider_trace
+            ]
+            return text, _trace_markdown(trace)
+        except Exception as exc:  # noqa: BLE001 - UI boundary must return a readable error
+            return f"İstek tamamlanamadı: `{type(exc).__name__}: {exc}`", "_Araç döngüsü tamamlanamadı._"
+
+    client = OpenAI(api_key=key)
+    conversation: list[Any] = [{"role": "user", "content": question}]
+    trace: list[dict[str, Any]] = []
+
+    try:
+        for turn in range(1, MAX_TURNS + 1):
+            response = client.responses.create(
+                model=model,
+                instructions=SYSTEM_PROMPT,
+                input=conversation,
+                tools=TOOLS,
+                reasoning={"effort": "low"},
+            )
+            output_items = [_as_dict(item) for item in response.output]
+            conversation.extend(output_items)
+            calls = [item for item in output_items if item.get("type") == "function_call"]
+            if not calls:
+                return response.output_text, _trace_markdown(trace)
+
+            for call in calls:
+                arguments: dict[str, Any] = {}
+                try:
+                    arguments = json.loads(call.get("arguments") or "{}")
+                    function = FUNCTIONS[call["name"]]
+                    result = function(**arguments)
+                except Exception as exc:  # noqa: BLE001 - tool errors are returned to the model
+                    result = {"error": f"{type(exc).__name__}: {exc}"}
+                trace.append(
+                    {
+                        "turn": turn,
+                        "tool": call["name"],
+                        "arguments": arguments,
+                        "result": result,
+                    }
+                )
+                conversation.append(
+                    {
+                        "type": "function_call_output",
+                        "call_id": call["call_id"],
+                        "output": json.dumps(result, ensure_ascii=False),
+                    }
+                )
+        return "Agent güvenlik tur sınırına ulaştı.", _trace_markdown(trace)
+    except Exception as exc:  # noqa: BLE001 - UI boundary must return a readable error
+        return f"İstek tamamlanamadı: `{type(exc).__name__}: {exc}`", _trace_markdown(trace)
+
+
+CSS = """
+.gradio-container {max-width: 1120px !important; margin: auto !important}
+.hero {background: linear-gradient(135deg,#0b1220,#173b5e); padding:28px;
+border-radius:20px; color:#fff; margin-bottom:18px}
+.hero h1 {margin:0 0 8px 0; font-size:2rem}
+.hero p {opacity:.86; margin:0}
+.panel {border:1px solid rgba(120,140,170,.22); border-radius:16px; padding:4px}
+"""
+
+with gr.Blocks(css=CSS, title="Hava Durumu Tool Calling Agent") as demo:
+    gr.HTML(
+        """<div class="hero"><h1>⛅ Hava Durumu Tool Calling Agent</h1>
+        <p>Open‑Meteo verisi · OpenAI Responses API · Görünür araç izleri</p></div>"""
+    )
+    with gr.Row():
+        with gr.Column(scale=5, elem_classes="panel"):
+            provider_input = gr.Dropdown(
+                label="LLM sağlayıcısı",
+                choices=["OpenAI", "OpenRouter"],
+                value="OpenAI",
+            )
+            model_input = gr.Dropdown(
+                label="Tool-calling destekli model",
+                choices=provider_models("OpenAI"),
+                value=MODEL,
+                allow_custom_value=False,
+            )
+            question_input = gr.Textbox(
+                label="Sorunuz",
+                value="Ankara mı daha sıcak Londra mı, ve bu değerler Fahrenheit olarak kaç eder?",
+                lines=3,
+            )
+            openai_key_input = gr.Textbox(
+                label="OpenAI API anahtarı (Space Secret yoksa)",
+                type="password",
+                placeholder="sk-… — saklanmaz",
+            )
+            openrouter_key_input = gr.Textbox(
+                label="OpenRouter API anahtarı (Space Secret yoksa)",
+                type="password",
+                placeholder="sk-or-… — saklanmaz",
+                visible=False,
+            )
+            submit = gr.Button("Agentı çalıştır", variant="primary")
+            gr.Examples(
+                examples=[
+                    ["İstanbul ve Berlin'in güncel sıcaklıklarını karşılaştır."],
+                    ["İzmir'de hava nasıl? Fahrenheit olarak da söyle."],
+                    ["Tokyo, Paris ve Ankara arasında en sıcak şehir hangisi?"],
+                ],
+                inputs=question_input,
+            )
+        with gr.Column(scale=7, elem_classes="panel"):
+            answer = gr.Markdown("Yanıt burada görünecek.")
+    with gr.Accordion("🔎 Araç çağrıları ve adımlar", open=True):
+        trace_view = gr.Markdown("_Henüz araç çağrısı yok._")
+
+    provider_input.change(
+        _provider_controls,
+        [provider_input],
+        [model_input, openai_key_input, openrouter_key_input],
+    )
+    ask_inputs = [
+        question_input,
+        provider_input,
+        model_input,
+        openai_key_input,
+        openrouter_key_input,
+    ]
+    submit.click(ask, ask_inputs, [answer, trace_view])
+    question_input.submit(ask, ask_inputs, [answer, trace_view])
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=8).launch()

llm_providers.py

@@ -0,0 +1,142 @@
+import json
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+from openai import OpenAI
+
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+OPENROUTER_DEFAULT = "openai/gpt-5.6-sol"
+OPENAI_DEFAULT = "gpt-5.6-sol"
+MODEL_TIMEOUT = 15.0
+
+OPENAI_MODELS = [
+    ("GPT-5.6 Sol · en güçlü", "gpt-5.6-sol"),
+    ("GPT-5.6 Terra · dengeli", "gpt-5.6-terra"),
+    ("GPT-5.6 Luna · ekonomik", "gpt-5.6-luna"),
+]
+
+FALLBACK_OPENROUTER_MODELS = [
+    ("OpenAI: GPT-5.6 Sol", "openai/gpt-5.6-sol"),
+    ("Anthropic: Claude Opus 5", "anthropic/claude-opus-5"),
+    ("Google: Gemini 3.6 Flash", "google/gemini-3.6-flash"),
+]
+
+
+def fetch_openrouter_models(require_structured: bool = False) -> list[tuple[str, str]]:
+    """Return only models whose live OpenRouter metadata declares required capabilities."""
+    try:
+        response = httpx.get(
+            f"{OPENROUTER_BASE_URL}/models",
+            params={"supported_parameters": "tools"},
+            timeout=MODEL_TIMEOUT,
+        )
+        response.raise_for_status()
+        models = []
+        for item in response.json().get("data", []):
+            supported = set(item.get("supported_parameters") or [])
+            if "tools" not in supported:
+                continue
+            if require_structured and "structured_outputs" not in supported:
+                continue
+            model_id = item.get("id")
+            if not model_id or model_id.endswith(":batch"):
+                continue
+            models.append((item.get("name") or model_id, model_id))
+        if models:
+            priority = {
+                OPENROUTER_DEFAULT: 0,
+                "anthropic/claude-opus-5": 1,
+                "google/gemini-3.6-flash": 2,
+            }
+            return sorted(models, key=lambda pair: (priority.get(pair[1], 100), pair[0].lower()))
+    except Exception:  # noqa: BLE001 - startup must survive catalog outages
+        pass
+    return FALLBACK_OPENROUTER_MODELS
+
+
+def provider_models(provider: str, require_structured: bool = False) -> list[tuple[str, str]]:
+    if provider == "OpenRouter":
+        return fetch_openrouter_models(require_structured=require_structured)
+    return OPENAI_MODELS
+
+
+def responses_tools_to_chat(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": tool["name"],
+                "description": tool.get("description", ""),
+                "parameters": tool["parameters"],
+            },
+        }
+        for tool in tools
+        if tool.get("type") == "function"
+    ]
+
+
+def run_openrouter_tool_loop(
+    *,
+    api_key: str,
+    model: str,
+    system_prompt: str,
+    user_prompt: str,
+    tools: list[dict[str, Any]],
+    execute_tool: Callable[[str, dict[str, Any]], Any],
+    max_turns: int,
+    response_schema: dict[str, Any] | None = None,
+) -> tuple[str, list[dict[str, Any]]]:
+    client = OpenAI(base_url=OPENROUTER_BASE_URL, api_key=api_key)
+    chat_tools = responses_tools_to_chat(tools)
+    messages: list[dict[str, Any]] = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt},
+    ]
+    trace: list[dict[str, Any]] = []
+
+    for turn in range(1, max_turns + 1):
+        request: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "tools": chat_tools,
+        }
+        if response_schema:
+            request["response_format"] = {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": "agent_result",
+                    "strict": True,
+                    "schema": response_schema,
+                },
+            }
+        completion = client.chat.completions.create(**request)
+        message = completion.choices[0].message
+        calls = message.tool_calls or []
+        if not calls:
+            return message.content or "", trace
+
+        messages.append(message.model_dump(exclude_none=True))
+        for call in calls:
+            arguments: dict[str, Any] = {}
+            try:
+                arguments = json.loads(call.function.arguments or "{}")
+                result = execute_tool(call.function.name, arguments)
+            except Exception as exc:  # noqa: BLE001 - tool failures must return to the model
+                result = {"error": f"{type(exc).__name__}: {exc}"}
+            trace.append(
+                {
+                    "turn": turn,
+                    "type": "function_call",
+                    "name": call.function.name,
+                    "detail": {"arguments": arguments, "result": result},
+                }
+            )
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": call.id,
+                    "content": json.dumps(result, ensure_ascii=False),
+                }
+            )
+    raise RuntimeError("Agent güvenlik tur sınırına ulaştı.")

requirements.txt

@@ -0,0 +1,3 @@
+gradio==5.49.1
+httpx>=0.27,<1
+openai>=1.93,<3