tools.tools.toolkits.fred_toolkit¶

Federal Reserve Economic Data (FRED) Toolkit Module.

This toolkit provides tools for accessing economic data from the Federal Reserve Bank of St. Louis FRED API. It allows retrieval of economic time series data, categories, and related metadata.

FRED is a comprehensive database containing hundreds of thousands of economic time series from dozens of national, international, public, and private sources.

Required Environment Variables:

FRED_API_KEY: Your FRED API key from https://fred.stlouisfed.org/docs/api/api_key.html

Examples

>>> from haive.tools.toolkits.fred_toolkit import get_series
>>> # Get information about GDP series
>>> gdp_info = get_series("GDP")
>>> print(f"Series title: {gdp_info['seriess'][0]['title']}")
Series title: Gross Domestic Product

>>> from haive.tools.toolkits.fred_toolkit import get_series_observations
>>> # Get GDP values for 2020-2022
>>> gdp_data = get_series_observations("GDP", "2020-01-01", "2022-12-31")
>>> for obs in gdp_data['observations'][:3]:
...     print(f"Date: {obs['date']}, Value: ${obs['value']} billion")
Date: 2020-01-01, Value: $21477.597 billion

Attributes¶

`BASE_URL`
`FRED_API_KEY`
`fred_toolkit`
`fred_tools`

Classes¶

`CategoryInput`	Input schema for FRED category queries.
`FREDToolkit`	Toolkit for accessing Federal Reserve Economic Data (FRED).
`SeriesInput`	Input schema for FRED series queries.
`SeriesObservationsInput`	Input schema for FRED series observations queries.

Functions¶

`fred_get`(→ dict[str, Any])	Helper function to call the FRED API with proper authentication and formatting.
`get_category`(→ dict[str, Any])	Get information about a FRED category by its ID.
`get_category_children`(→ dict[str, Any])	Get the child categories of a specified FRED category.
`get_category_series`(→ dict[str, Any])	Get all series belonging to a specified FRED category.
`get_series`(→ dict[str, Any])	Get metadata about a specific FRED data series.
`get_series_observations`(→ dict[str, Any])	Get the actual data values (observations) for a FRED time series.

Module Contents¶

class tools.tools.toolkits.fred_toolkit.CategoryInput(/, **data: Any)¶

Bases: pydantic.BaseModel

Input schema for FRED category queries.

category_id: int = None¶

class tools.tools.toolkits.fred_toolkit.FREDToolkit(/, **data: Any)¶

Bases: langchain_core.tools.BaseToolkit

Toolkit for accessing Federal Reserve Economic Data (FRED).

This toolkit provides a collection of tools for interacting with the FRED API to retrieve economic data series, categories, and related information.

The Federal Reserve Economic Data (FRED) database contains hundreds of thousands of economic time series from dozens of national, international, public, and private sources.

get_tools() → list[langchain_core.tools.StructuredTool]¶

Get all tools in the FRED toolkit.

Returns:: A list of tools for interacting with the FRED API.
Return type:: List[StructuredTool]

class tools.tools.toolkits.fred_toolkit.SeriesInput(/, **data: Any)¶

Bases: pydantic.BaseModel

Input schema for FRED series queries.

series_id: str = None¶

class tools.tools.toolkits.fred_toolkit.SeriesObservationsInput(/, **data: Any)¶

Bases: pydantic.BaseModel

Input schema for FRED series observations queries.

end_date: str | None = None¶

series_id: str = None¶

start_date: str | None = None¶

tools.tools.toolkits.fred_toolkit.fred_get(endpoint: str, params: dict[str, Any]) → dict[str, Any]¶

Helper function to call the FRED API with proper authentication and formatting.

This function adds the API key and sets the response format to JSON before making the request to the specified FRED API endpoint.

Parameters:

endpoint (str) – The FRED API endpoint to call (e.g., “series”, “category”).
params (Dict[str, Any]) – Parameters to include in the API request.

Returns:

The JSON response from the FRED API.

Return type:

Dict[str, Any]

Raises:

requests.RequestException – If the API request fails.
ValueError – If FRED_API_KEY is not set in the environment.

tools.tools.toolkits.fred_toolkit.get_category(category_id: int) → dict[str, Any]¶

Get information about a FRED category by its ID.

Categories in FRED organize data series into groups like ‘Money, Banking, & Finance’, ‘Population, Employment, & Labor Markets’, etc.

Parameters:: category_id (int) – The FRED category ID to fetch (e.g., 0 for root category).
Returns:: Category information including name and notes.
Return type:: Dict[str, Any]
Raises:: requests.RequestException – If the API request fails.

tools.tools.toolkits.fred_toolkit.get_category_children(category_id: int) → dict[str, Any]¶

Get the child categories of a specified FRED category.

This function retrieves subcategories for a given parent category, allowing exploration of the FRED category hierarchy.

Parameters:: category_id (int) – The parent category ID to get children for.
Returns:: List of child categories with their IDs and names.
Return type:: Dict[str, Any]
Raises:: requests.RequestException – If the API request fails.

tools.tools.toolkits.fred_toolkit.get_category_series(category_id: int) → dict[str, Any]¶

Get all series belonging to a specified FRED category.

This function retrieves the economic data series that are classified under the specified category.

Parameters:: category_id (int) – The category ID to get series for.
Returns:: List of series in the category with metadata.
Return type:: Dict[str, Any]
Raises:: requests.RequestException – If the API request fails.

tools.tools.toolkits.fred_toolkit.get_series(series_id: str) → dict[str, Any]¶

Get metadata about a specific FRED data series.

This function retrieves detailed information about an economic data series, including its title, units, frequency, seasonal adjustment, and more.

Parameters:: series_id (str) – The FRED series ID (e.g., ‘GDP’, ‘UNRATE’, ‘CPIAUCSL’).
Returns:: Detailed metadata about the requested series.
Return type:: Dict[str, Any]
Raises:: requests.RequestException – If the API request fails.

tools.tools.toolkits.fred_toolkit.get_series_observations(series_id: str, start_date: str | None = None, end_date: str | None = None) → dict[str, Any]¶

Get the actual data values (observations) for a FRED time series.

This function retrieves the time series data points for a specified economic indicator, with optional date range filtering.

Parameters:

series_id (str) – The FRED series ID to fetch observations for.
start_date (Optional[str], optional) – Start date in YYYY-MM-DD format. Defaults to None.
end_date (Optional[str], optional) – End date in YYYY-MM-DD format. Defaults to None.

Returns:

Series observations with dates and values.

Return type:

Dict[str, Any]

Raises:

requests.RequestException – If the API request fails.

tools.tools.toolkits.fred_toolkit.BASE_URL = 'https://api.stlouisfed.org/fred'¶

tools.tools.toolkits.fred_toolkit.FRED_API_KEY¶

tools.tools.toolkits.fred_toolkit.fred_toolkit¶

tools.tools.toolkits.fred_toolkit.fred_tools¶