Add "vertical" tools (#20)

* Add `tools` module.

- Include `openmeteo` and `openstreetmap`.

* Expose "vertical" tools to openai agent.

* fix(test_unit_openai): Drop outdated tool assert

docs/api.md

@@ -10,10 +10,13 @@
 
 ::: surf_spot_finder.agents.smolagents
 
+::: surf_spot_finder.tools.openmeteo
+::: surf_spot_finder.tools.openstreetmap
+
+::: surf_spot_finder.tracing
+
 ::: surf_spot_finder.prompts.openai.SINGLE_AGENT_SYSTEM_PROMPT
 
 ::: surf_spot_finder.prompts.openai.MULTI_AGENT_SYSTEM_PROMPT
 
 ::: surf_spot_finder.prompts.shared.INPUT_PROMPT
-
-::: surf_spot_finder.tracing

src/surf_spot_finder/agents/openai.py

@@ -21,6 +21,18 @@ from surf_spot_finder.prompts.openai import (
     SINGLE_AGENT_SYSTEM_PROMPT,
     MULTI_AGENT_SYSTEM_PROMPT,
 )
+from surf_spot_finder.tools.openmeteo import get_wave_forecast, get_wind_forecast
+from surf_spot_finder.tools.openstreetmap import (
+    driving_hours_to_meters,
+    get_area_lat_lon,
+    get_surfing_places,
+)
+
+driving_hours_to_meters = function_tool(driving_hours_to_meters)
+get_area_lat_lon = function_tool(get_area_lat_lon)
+get_surfing_places = function_tool(get_surfing_places)
+get_wave_forecast = function_tool(get_wave_forecast)
+get_wind_forecast = function_tool(get_wind_forecast)
 
 
 @function_tool
@@ -125,7 +137,15 @@ def run_openai_agent(
             model=model_id,
             instructions=instructions,
             name=name,
-            tools=[search_web, visit_webpage],
+            tools=[
+                search_web,
+                visit_webpage,
+                get_area_lat_lon,
+                get_surfing_places,
+                get_wave_forecast,
+                get_wind_forecast,
+                driving_hours_to_meters,
+            ],
         )
     result = Runner.run_sync(agent, prompt)
     logger.info(result.final_output)

src/surf_spot_finder/prompts/openai.py

@@ -3,6 +3,8 @@ You will be asked to perform a task.
 
 Before solving the task, plan a sequence of actions using the available tools.
 Then, execute the sequence of actions using the tools.
+
+Prefer to use task-specific tools before relying on generic tools like web search.
 """.strip()
 
 MULTI_AGENT_SYSTEM_PROMPT = """

src/surf_spot_finder/tools/openmeteo.py

@@ -0,0 +1,113 @@
+import json
+from datetime import datetime, timedelta
+import requests
+
+
+def _extract_hourly_data(data: dict) -> list[dict]:
+    hourly_data = data["hourly"]
+    result = [
+        {k: v for k, v in zip(hourly_data.keys(), values)}
+        for values in zip(*hourly_data.values())
+    ]
+    return result
+
+
+def _filter_by_date(
+    date: datetime, hourly_data: list[dict], timedelta: timedelta = timedelta(hours=1)
+):
+    start_date = date - timedelta
+    end_date = date + timedelta
+    return [
+        item
+        for item in hourly_data
+        if start_date <= datetime.fromisoformat(item["time"]) <= end_date
+    ]
+
+
+def get_wave_forecast(lat: float, lon: float, date: str | None = None) -> list[dict]:
+    """Get wave forecast for given location.
+
+    Forecast will include:
+
+    - wave_direction (degrees)
+    - wave_height (meters)
+    - wave_period (seconds)
+    - sea_level_height_msl (meters)
+
+    Args:
+        lat (float): Latitude of the location.
+        lon (float): Longitude of the location.
+        date (str | None): Date to filter by in any valid ISO 8601 format.
+            If not provided, all data (default to 6 days forecast) will be returned.
+
+    Returns:
+        list[dict]: Hourly data for wave forecast.
+            Example output:
+
+            ```json
+            [
+                {'time': '2025-03-19T09:00', 'winddirection_10m': 140, 'windspeed_10m': 24.5}, {'time': '2025-03-19T10:00', 'winddirection_10m': 140, 'windspeed_10m': 27.1},
+                {'time': '2025-03-19T10:00', 'winddirection_10m': 140, 'windspeed_10m': 27.1}, {'time': '2025-03-19T11:00', 'winddirection_10m': 141, 'windspeed_10m': 29.2}
+            ]
+            ```
+    """
+    url = "https://marine-api.open-meteo.com/v1/marine"
+    params = {
+        "latitude": lat,
+        "longitude": lon,
+        "hourly": [
+            "wave_direction",
+            "wave_height",
+            "wave_period",
+            "sea_level_height_msl",
+        ],
+    }
+    response = requests.get(url, params=params)
+    response.raise_for_status()
+    data = json.loads(response.content.decode())
+    hourly_data = _extract_hourly_data(data)
+    if date is not None:
+        date = datetime.fromisoformat(date)
+        hourly_data = _filter_by_date(date, hourly_data)
+    return hourly_data
+
+
+def get_wind_forecast(lat: float, lon: float, date: str | None = None) -> list[dict]:
+    """Get wind forecast for given location.
+
+    Forecast will include:
+
+    - wind_direction (degrees)
+    - wind_speed (meters per second)
+
+    Args:
+        lat (float): Latitude of the location.
+        lon (float): Longitude of the location.
+        date (str | None): Date to filter by in any valid ISO 8601 format.
+            If not provided, all data (default to 6 days forecast) will be returned.
+
+    Returns:
+        list[dict]: Hourly data for wind forecast.
+            Example output:
+
+            ```json
+            [
+                {"time": "2025-03-18T22:00", "wave_direction": 264, "wave_height": 2.24, "wave_period": 10.45, "sea_level_height_msl": -1.27},
+                {"time": "2025-03-18T23:00", "wave_direction": 264, "wave_height": 2.24, "wave_period": 10.35, "sea_level_height_msl": -1.35},
+            ]
+            ```
+    """
+    url = "https://api.open-meteo.com/v1/forecast"
+    params = {
+        "latitude": lat,
+        "longitude": lon,
+        "hourly": ["winddirection_10m", "windspeed_10m"],
+    }
+    response = requests.get(url, params=params)
+    response.raise_for_status()
+    data = json.loads(response.content.decode())
+    hourly_data = _extract_hourly_data(data)
+    if date is not None:
+        date = datetime.fromisoformat(date)
+        hourly_data = _filter_by_date(date, hourly_data)
+    return hourly_data

src/surf_spot_finder/tools/openstreetmap.py

@@ -0,0 +1,92 @@
+import requests
+import json
+
+
+def get_area_lat_lon(area_name: str) -> tuple[float, float]:
+    """Get the latitude and longitude of an area from Nominatim.
+
+    Uses the [Nominatim API](https://nominatim.org/release-docs/develop/api/Search/).
+
+    Args:
+        area_name (str): The name of the area.
+
+    Returns:
+        dict: The area found.
+    """
+    response = requests.get(
+        f"https://nominatim.openstreetmap.org/search?q={area_name}&format=json",
+        headers={"User-Agent": "Mozilla/5.0"},
+    )
+    response.raise_for_status()
+    area = json.loads(response.content.decode())
+    return area[0]["lat"], area[0]["lon"]
+
+
+def driving_hours_to_meters(driving_hours: int) -> int:
+    """Convert driving hours to meters assuming a 70 km/h average speed.
+
+
+    Args:
+        driving_hours (int): The driving hours.
+
+    Returns:
+        int: The distance in meters.
+    """
+    return driving_hours * 70 * 1000
+
+
+def get_lat_lon_center(bounds: dict) -> tuple[float, float]:
+    """Get the latitude and longitude of the center of a bounding box.
+
+    Args:
+        bounds (dict): The bounding box.
+
+            ```json
+            {
+                "minlat": float,
+                "minlon": float,
+                "maxlat": float,
+                "maxlon": float,
+            }
+            ```
+
+    Returns:
+        tuple: The latitude and longitude of the center.
+    """
+    return (
+        (bounds["minlat"] + bounds["maxlat"]) / 2,
+        (bounds["minlon"] + bounds["maxlon"]) / 2,
+    )
+
+
+def get_surfing_places(
+    lat: float, lon: float, radius: int
+) -> list[tuple[str, tuple[float, float]]]:
+    """Get surfing places around a given latitude and longitude.
+
+    Uses the [Overpass API](https://wiki.openstreetmap.org/wiki/Overpass_API).
+
+    Args:
+        lat (float): The latitude.
+        lon (float): The longitude.
+        radius (int): The radius in meters.
+
+    Returns:
+        dict: The surfing places found.
+    """
+    overpass_url = "https://overpass-api.de/api/interpreter"
+    query = "[out:json];("
+    query += f'nwr["natural"="beach"](around:{radius},{lat},{lon});'
+    query += f'nwr["natural"="reef"](around:{radius},{lat},{lon});'
+    query += ");out body geom;"
+    params = {"data": query}
+    response = requests.get(
+        overpass_url, params=params, headers={"User-Agent": "Mozilla/5.0"}
+    )
+    response.raise_for_status()
+    elements = response.json()["elements"]
+    return [
+        (element.get("tags", {}).get("name", ""), get_lat_lon_center(element["bounds"]))
+        for element in elements
+        if "surfing" in element.get("tags", {}).get("sport", "")
+    ]

tests/unit/agents/test_unit_openai.py

@@ -28,7 +28,7 @@ def test_run_openai_agent_default():
             model="gpt-4o",
             instructions=SINGLE_AGENT_SYSTEM_PROMPT,
             name="surf-spot-finder",
-            tools=[search_web, visit_webpage],
+            tools=ANY,
         )
 
 

tests/unit/tools/test_unit_openmeteo.py

@@ -0,0 +1,102 @@
+import json
+from datetime import datetime, timedelta
+from unittest.mock import patch, MagicMock
+
+from surf_spot_finder.tools import openmeteo
+
+
+def test_extract_hourly_data():
+    data = {
+        "hourly": {
+            "time": ["2023-01-01T00:00", "2023-01-01T01:00"],
+            "wave_height": [1.5, 1.6],
+            "wave_period": [10, 11],
+        }
+    }
+    expected = [
+        {"time": "2023-01-01T00:00", "wave_height": 1.5, "wave_period": 10},
+        {"time": "2023-01-01T01:00", "wave_height": 1.6, "wave_period": 11},
+    ]
+    assert openmeteo._extract_hourly_data(data) == expected
+
+
+def test_filter_by_date():
+    hourly_data = [
+        {"time": "2023-01-01T00:00", "wave_height": 1.5},
+        {"time": "2023-01-01T01:00", "wave_height": 1.6},
+        {"time": "2023-01-01T02:00", "wave_height": 1.7},
+        {"time": "2023-01-01T03:00", "wave_height": 1.8},
+    ]
+    date = datetime.fromisoformat("2023-01-01T01:00")
+    expected = [
+        {"time": "2023-01-01T00:00", "wave_height": 1.5},
+        {"time": "2023-01-01T01:00", "wave_height": 1.6},
+        {"time": "2023-01-01T02:00", "wave_height": 1.7},
+    ]
+    assert openmeteo._filter_by_date(date, hourly_data) == expected
+
+    expected = [
+        {"time": "2023-01-01T01:00", "wave_height": 1.6},
+    ]
+    assert openmeteo._filter_by_date(date, hourly_data, timedelta(hours=0)) == expected
+
+
+def test_get_wave_forecast():
+    with patch("requests.get") as mock_get:
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.content.decode.return_value = json.dumps(
+            {
+                "hourly": {
+                    "time": ["2023-02-02T00:00", "2023-02-02T01:00"],
+                    "wave_direction": [270, 280],
+                    "wave_height": [1.5, 1.6],
+                    "wave_period": [10, 11],
+                    "sea_level_height_msl": [0.5, 0.6],
+                }
+            }
+        )
+        mock_get.return_value = mock_response
+        result = openmeteo.get_wave_forecast(lat=40.0, lon=-3.0)
+
+        assert len(result) == 2
+        assert result[1]["time"] == "2023-02-02T01:00"
+        assert result[1]["wave_direction"] == 280
+        assert result[1]["wave_height"] == 1.6
+        assert result[1]["wave_period"] == 11
+        assert result[1]["sea_level_height_msl"] == 0.6
+
+        result_filtered = openmeteo.get_wave_forecast(
+            lat=40.0, lon=-3.0, date="2023-02-02T02:00"
+        )
+        assert len(result_filtered) == 1
+        assert result_filtered[0]["time"] == "2023-02-02T01:00"
+
+
+def test_get_wind_forecast():
+    with patch("requests.get") as mock_get:
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.content.decode.return_value = json.dumps(
+            {
+                "hourly": {
+                    "time": ["2023-02-02T00:00", "2023-02-02T01:00"],
+                    "winddirection_10m": [270, 280],
+                    "windspeed_10m": [10, 11],
+                }
+            }
+        )
+        mock_get.return_value = mock_response
+
+        result = openmeteo.get_wind_forecast(lat=40.0, lon=-3.0)
+        assert len(result) == 2
+        assert result[1]["time"] == "2023-02-02T01:00"
+        assert result[1]["winddirection_10m"] == 280
+        assert result[1]["windspeed_10m"] == 11
+
+        result_filtered = openmeteo.get_wind_forecast(
+            lat=40.0, lon=-3.0, date="2023-02-02T02:00"
+        )
+        assert len(result_filtered) == 1
+        assert result_filtered[0]["time"] == "2023-02-02T01:00"
+        assert result[0]["windspeed_10m"] == 10

tests/unit/tools/test_unit_openstreetmap.py

@@ -0,0 +1,74 @@
+import json
+from unittest.mock import MagicMock, patch
+
+from surf_spot_finder.tools import openstreetmap
+
+
+def test_get_area_lat_lon():
+    with patch("requests.get") as mock_get:
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.content.decode.return_value = json.dumps(
+            [{"lat": "40.0", "lon": "-3.0"}]
+        )
+        mock_get.return_value = mock_response
+
+        lat, lon = openstreetmap.get_area_lat_lon("Madrid")
+        assert lat == "40.0"
+        assert lon == "-3.0"
+
+
+def test_driving_hours_to_meters():
+    assert openstreetmap.driving_hours_to_meters(1) == 70000
+
+
+def test_get_lat_lon_center():
+    bounds = {"minlat": 40.0, "minlon": -3.0, "maxlat": 41.0, "maxlon": -2.0}
+    lat, lon = openstreetmap.get_lat_lon_center(bounds)
+    assert lat == 40.5
+    assert lon == -2.5
+
+
+def test_get_surfing_places():
+    with patch("requests.get") as mock_get:
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "elements": [
+                {
+                    "tags": {"name": "Surf Spot 1", "sport": "surfing"},
+                    "bounds": {
+                        "minlat": 40.0,
+                        "minlon": -3.0,
+                        "maxlat": 40.1,
+                        "maxlon": -2.9,
+                    },
+                },
+                {
+                    "tags": {"name": "Beach 2", "sport": "swimming"},
+                    "bounds": {
+                        "minlat": 41.0,
+                        "minlon": -4.0,
+                        "maxlat": 41.1,
+                        "maxlon": -3.9,
+                    },
+                },
+                {
+                    "tags": {"name": "Surf Spot 3", "sport": "surfing"},
+                    "bounds": {
+                        "minlat": 42.0,
+                        "minlon": -5.0,
+                        "maxlat": 42.1,
+                        "maxlon": -4.9,
+                    },
+                },
+            ]
+        }
+        mock_get.return_value = mock_response
+
+        results = openstreetmap.get_surfing_places(lat=40.5, lon=-3.5, radius=10000)
+        assert len(results) == 2
+        assert results[0][0] == "Surf Spot 1"
+        assert results[0][1] == (40.05, -2.95)
+        assert results[1][0] == "Surf Spot 3"
+        assert results[1][1] == (42.05, -4.95)