tools.tools.toolkits.weather¶

Weather Information Toolkit Module.

This toolkit provides tools for retrieving current weather information using the OpenWeatherMap API. It supports structured data parsing and temperature unit conversion between Celsius and Fahrenheit.

Features: - City and country-based weather lookups - Structured data output with detailed weather metrics - Customizable temperature units (Celsius/Fahrenheit) - Automatic parsing of OpenWeatherMap API responses

Required Environment Variables:

OPENWEATHERMAP_API_KEY: Your OpenWeatherMap API key (will prompt if not found)

Examples

>>> from haive.tools.toolkits.weather import get_weather_by_city_country
>>> # Get structured weather data for Tokyo, Japan
>>> weather = get_weather_by_city_country("Tokyo", "jp", parse=True, temperature_unit="celsius")
>>> print(f"Current temperature in {weather['location']}: {weather['temp_current_c']}°C")
Current temperature in Tokyo, JP: 15.2°C

>>> # Get raw weather data for New York, US in Fahrenheit
>>> weather = get_weather_by_city_country("New York", "us", parse=True, temperature_unit="fahrenheit")
>>> print(f"Feels like: {weather['temp_feels_like_c']}°F")
Feels like: 46.58°F

Attributes¶

weather_tool

Classes¶

`CityCountryWeatherInput`	Input schema for weather query by city and country.
`WeatherData`	Structured weather data model.

Functions¶

get_weather_by_city_country(city, country[, parse, ...])

Fetch current weather information for a specific city and country.

Module Contents¶

class tools.tools.toolkits.weather.CityCountryWeatherInput(/, **data: Any)¶

Bases: pydantic.BaseModel

Input schema for weather query by city and country.

This model defines the parameters needed to request weather information from the OpenWeatherMap API, including location and formatting options.

city¶

The name of the city to get weather for.

Type:: str

country¶

The 2-letter ISO country code in lowercase.

Type:: str

parse¶

Whether to return structured data or raw API response.

Type:: bool

temperature_unit¶

Unit for temperature values (celsius or fahrenheit).

Type:: str

city: str = None¶

country: str = None¶

parse: bool = None¶

temperature_unit: Literal['celsius', 'fahrenheit'] = None¶

class tools.tools.toolkits.weather.WeatherData(/, **data: Any)¶

Bases: pydantic.BaseModel

Structured weather data model.

This model represents parsed weather information from the OpenWeatherMap API, with fields for various weather metrics including temperature, wind, humidity, and precipitation.

location¶

Location name in “City, Country” format.

Type:: Optional[str]

status¶

Weather condition description (e.g., “Clear sky”).

Type:: Optional[str]

wind_speed_mps¶

Wind speed in meters per second.

Type:: Optional[float]

wind_direction_deg¶

Wind direction in degrees.

Type:: Optional[int]

humidity_percent¶

Relative humidity percentage.

Type:: Optional[int]

temp_current_c¶

Current temperature in Celsius.

Type:: Optional[float]

temp_high_c¶

Maximum temperature in Celsius.

Type:: Optional[float]

temp_low_c¶

Minimum temperature in Celsius.

Type:: Optional[float]

temp_feels_like_c¶

“Feels like” temperature in Celsius.

Type:: Optional[float]

rain_mm_last_hour¶

Rainfall in millimeters over the last hour.

Type:: Optional[float]

cloud_cover_percent¶

Cloud coverage percentage.

Type:: Optional[int]

convert_to_fahrenheit() → WeatherData¶

Convert all temperature values from Celsius to Fahrenheit.

Returns:: A new WeatherData instance with temperatures in Fahrenheit.
Return type:: WeatherData

classmethod from_openweather_response(response: str) → WeatherData¶

Parse the text response from OpenWeatherMap API into structured data.

This method uses regular expressions to extract weather information from the text-based API response and creates a structured WeatherData object.

Parameters:: response (str) – Raw text response from the OpenWeatherMap API.
Returns:: Structured weather data extracted from the response.
Return type:: WeatherData

cloud_cover_percent: int | None = None¶

humidity_percent: int | None = None¶

location: str | None = None¶

rain_mm_last_hour: float | None = None¶

status: str | None = None¶

temp_current_c: float | None = None¶

temp_feels_like_c: float | None = None¶

temp_high_c: float | None = None¶

temp_low_c: float | None = None¶

wind_direction_deg: int | None = None¶

wind_speed_mps: float | None = None¶

tools.tools.toolkits.weather.get_weather_by_city_country(city: str, country: str, parse: bool = True, temperature_unit: Literal['celsius', 'fahrenheit'] = 'celsius')¶

Fetch current weather information for a specific city and country.

This function retrieves weather data from the OpenWeatherMap API for the specified location. It can return either raw API response or structured data with various weather metrics.

Parameters:

city (str) – The name of the city (e.g., “London”, “Tokyo”).
country (str) – The 2-letter ISO country code in lowercase (e.g., “gb”, “jp”).
parse (bool, optional) – Whether to parse the response into structured data. Defaults to True.
temperature_unit (str, optional) – Unit for temperature values, either “celsius” or “fahrenheit”. Defaults to “celsius”.

Returns:

Structured weather data as a dictionary if parse=True,: otherwise the raw API response as a string.

Return type:

Union[dict, str]

Raises:

ValueError – If the API key is not provided and the user cancels the prompt.
Exception – If the weather API request fails.

tools.tools.toolkits.weather.weather_tool¶