enh(tools): Add `wrappers` module. (#23)

Allows to import and reuse same tools for different frameworks.

Add `smolagents_single_agent_vertical` and `langchain_single_agent_vertical`

examples/langchain_single_agent_vertical.yaml

@@ -0,0 +1,14 @@
+location: Pontevedra
+date: 2025-03-22 12:00
+max_driving_hours: 2
+model_id: o3-mini
+agent_type: langchain
+tools:
+ - "surf_spot_finder.tools.driving_hours_to_meters"
+ - "surf_spot_finder.tools.get_area_lat_lon"
+ - "surf_spot_finder.tools.get_surfing_spots"
+ - "surf_spot_finder.tools.get_wave_forecast"
+ - "surf_spot_finder.tools.get_wind_forecast"
+ - "surf_spot_finder.tools.search_web"
+ - "surf_spot_finder.tools.visit_webpage"
+# input_prompt_template:

examples/smolagents_single_agent_vertical.yaml

@@ -0,0 +1,17 @@
+location: Pontevedra
+date: 2025-03-22 12:00
+max_driving_hours: 2
+model_id: openai/o3-mini
+api_key_var: OPENAI_API_KEY
+agent_type: smolagents
+tools:
+ - "surf_spot_finder.tools.driving_hours_to_meters"
+ - "surf_spot_finder.tools.get_area_lat_lon"
+ - "surf_spot_finder.tools.get_surfing_spots"
+ - "surf_spot_finder.tools.get_wave_forecast"
+ - "surf_spot_finder.tools.get_wind_forecast"
+ - "surf_spot_finder.tools.search_web"
+ - "surf_spot_finder.tools.visit_webpage"
+ - "smolagents.PythonInterpreterTool"
+ - "smolagents.FinalAnswerTool"
+# input_prompt_template:

src/surf_spot_finder/agents/openai.py

@@ -1,4 +1,3 @@
-import importlib
 import os
 from typing import Optional
 
@@ -8,6 +7,8 @@ from surf_spot_finder.prompts.openai import (
     SINGLE_AGENT_SYSTEM_PROMPT,
     MULTI_AGENT_SYSTEM_PROMPT,
 )
+from surf_spot_finder.tools.wrappers import import_and_wrap_tools, wrap_tool_openai
+
 
 try:
     from agents import (
@@ -70,12 +71,7 @@ def run_openai_agent(
             "surf_spot_finder.tools.visit_webpage",
         ]
 
-    imported_tools = []
-    for tool in tools:
-        module, func = tool.rsplit(".", 1)
-        module = importlib.import_module(module)
-        tool = getattr(module, func)
-        imported_tools.append(function_tool(tool))
+    imported_tools = import_and_wrap_tools(tools, wrap_tool_openai)
 
     if api_key_var and api_base:
         external_client = AsyncOpenAI(

src/surf_spot_finder/agents/smolagents.py

@@ -1,16 +1,16 @@
-import importlib
 import os
 from typing import Optional
 
 from loguru import logger
 
 from surf_spot_finder.prompts.smolagents import SYSTEM_PROMPT
+from surf_spot_finder.tools.wrappers import import_and_wrap_tools, wrap_tool_smolagents
+
 
 try:
     from smolagents import (
         CodeAgent,
         LiteLLMModel,
-        ToolCollection,
     )
 
     smolagents_available = True
@@ -55,16 +55,12 @@ def run_smolagent(
             "smolagents.PythonInterpreterTool",
         ]
 
-    imported_tools = []
     mcp_tool = None
     for tool in tools:
         if "mcp" in tool:
             mcp_tool = tool
-        else:
-            module, func = tool.rsplit(".", 1)
-            module = importlib.import_module(module)
-            tool = getattr(module, func)
-            imported_tools.append(tool())
+            tools.remove(tool)
+    imported_tools = import_and_wrap_tools(tools, wrap_tool_smolagents)
 
     model = LiteLLMModel(
         model_id=model_id,
@@ -74,6 +70,7 @@ def run_smolagent(
 
     if mcp_tool:
         from mcp import StdioServerParameters
+        from smolagents import ToolCollection
 
         # We could easily use any of the MCPs at https://github.com/modelcontextprotocol/servers
         # or at https://glama.ai/mcp/servers

src/surf_spot_finder/tools/openmeteo.py

@@ -35,13 +35,13 @@ def get_wave_forecast(lat: float, lon: float, date: str | None = None) -> list[d
     - 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.
+        lat: Latitude of the location.
+        lon: Longitude of the location.
+        date: 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.
+        Hourly data for wave forecast.
             Example output:
 
             ```json
@@ -81,19 +81,19 @@ def get_wind_forecast(lat: float, lon: float, date: str | None = None) -> list[d
     - 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.
+        lat: Latitude of the location.
+        lon: Longitude of the location.
+        date: 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.
+        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},
+                {"time": "2025-03-18T22:00", "wind_direction": 196, "wind_speed": 9.6},
+                {"time": "2025-03-18T23:00", "wind_direction": 183, "wind_speed": 7.9},
             ]
             ```
     """

src/surf_spot_finder/tools/openstreetmap.py

@@ -8,10 +8,10 @@ def get_area_lat_lon(area_name: str) -> tuple[float, float]:
     Uses the [Nominatim API](https://nominatim.org/release-docs/develop/api/Search/).
 
     Args:
-        area_name (str): The name of the area.
+        area_name: The name of the area.
 
     Returns:
-        dict: The area found.
+        The area found.
     """
     response = requests.get(
         f"https://nominatim.openstreetmap.org/search?q={area_name}&format=json",
@@ -27,10 +27,10 @@ def driving_hours_to_meters(driving_hours: int) -> int:
 
 
     Args:
-        driving_hours (int): The driving hours.
+        driving_hours: The driving hours.
 
     Returns:
-        int: The distance in meters.
+        The distance in meters.
     """
     return driving_hours * 70 * 1000
 
@@ -39,7 +39,7 @@ 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.
+        bounds: The bounding box.
 
             ```json
             {
@@ -51,7 +51,7 @@ def get_lat_lon_center(bounds: dict) -> tuple[float, float]:
             ```
 
     Returns:
-        tuple: The latitude and longitude of the center.
+        The latitude and longitude of the center.
     """
     return (
         (bounds["minlat"] + bounds["maxlat"]) / 2,
@@ -67,12 +67,12 @@ def get_surfing_spots(
     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.
+        lat: The latitude.
+        lon: The longitude.
+        radius: The radius in meters.
 
     Returns:
-        dict: The surfing places found.
+        The surfing places found.
     """
     overpass_url = "https://overpass-api.de/api/interpreter"
     query = "[out:json];("

src/surf_spot_finder/tools/wrappers.py

@@ -0,0 +1,41 @@
+import inspect
+import importlib
+from collections.abc import Callable
+
+
+def import_and_wrap_tools(tools: list[str], wrapper: Callable) -> list[Callable]:
+    imported_tools = []
+    for tool in tools:
+        module, func = tool.rsplit(".", 1)
+        module = importlib.import_module(module)
+        imported_tool = getattr(module, func)
+        if inspect.isclass(imported_tool):
+            imported_tool = imported_tool()
+        imported_tools.append(wrapper(imported_tool))
+    return imported_tools
+
+
+def wrap_tool_openai(tool):
+    from agents import function_tool, FunctionTool
+
+    if not isinstance(tool, FunctionTool):
+        return function_tool(tool)
+    return tool
+
+
+def wrap_tool_langchain(tool):
+    from langchain_core.tools import BaseTool
+    from langchain_core.tools import tool as langchain_tool
+
+    if not isinstance(tool, BaseTool):
+        return langchain_tool(tool)
+    return tool
+
+
+def wrap_tool_smolagents(tool):
+    from smolagents import Tool, tool as smolagents_tool
+
+    if not isinstance(tool, Tool):
+        return smolagents_tool(tool)
+
+    return tool