fred-toolkit 0.1.0

FRED Economic Data Tools for LLM/Agent Integration - Access 800,000+ Federal Reserve time series

fred-toolkit

FRED Economic Data Tools for LLM/Agent Integration

A Python package providing LLM-compatible tools for accessing 800,000+ Federal Reserve Economic Data (FRED) time series. Perfect for building AI agents, chatbots, and automated analysis systems that need access to economic data.

Note: This package is converted from the FRED MCP Server but designed as a lightweight Python library without server deployment overhead.

Features

✅ 3 Powerful Tools for comprehensive FRED data access
✅ OpenAI-Compatible function calling format
✅ Works with any LLM (OpenAI, Anthropic, local models)
✅ No server required - pure Python library
✅ 800,000+ time series from Federal Reserve
✅ Pythonic API for direct usage

Installation

pip install fred-toolkit

Or with uv:

uv pip install fred-toolkit

Quick Start

1. Get your FRED API Key

Get a free API key from: https://fred.stlouisfed.org/docs/api/api_key.html

2. Basic Usage with LLM

from fred_toolkit import FredTools
import openai
import json

# Initialize
fred = FredTools(api_key="your-fred-api-key")
client = openai.OpenAI()

# Get tool definitions
tools = fred.get_tool_definitions()

# Send to LLM
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What's the current US unemployment rate?"}],
    tools=tools
)

# Execute the tool LLM chose
tool_call = response.choices[0].message.tool_calls[0]
result = fred.execute_tool(
    tool_call.function.name,
    json.loads(tool_call.function.arguments)
)

print(result)

3. Direct Python Usage

from fred_toolkit import FredTools

fred = FredTools(api_key="your-fred-api-key")

# Search for series
results = fred.search("unemployment")
print(results)

# Get specific series data
data = fred.get_series("UNRATE", observation_start="2020-01-01")
print(data)

# Browse categories
categories = fred.browse(browse_type="categories")
print(categories)

Available Tools

fred_search

Search for FRED economic data series by keywords, tags, or filters.

Example:

result = fred.execute_tool("fred_search", {
    "search_text": "inflation",
    "limit": 10
})

fred_get_series

Retrieve data for any FRED series with transformations and date ranges.

Example:

result = fred.execute_tool("fred_get_series", {
    "series_id": "GDP",
    "observation_start": "2020-01-01"
})

fred_browse

Browse FRED's catalog through categories, releases, or sources.

Example:

result = fred.execute_tool("fred_browse", {
    "browse_type": "categories"
})

Common Use Cases

Building an Economic Analysis Agent

def ask_fred(user_query: str) -> str:
    """Complete agent loop with automatic tool selection"""
    fred = FredTools(api_key="...")
    client = openai.OpenAI()
    
    messages = [{"role": "user", "content": user_query}]
    
    response = client.chat.completions.create(
        model="gpt-4",
        messages=messages,
        tools=fred.get_tool_definitions()
    )
    
    if response.choices[0].message.tool_calls:
        tool_call = response.choices[0].message.tool_calls[0]
        result = fred.execute_tool(
            tool_call.function.name,
            json.loads(tool_call.function.arguments)
        )
        
        messages.append(response.choices[0].message)
        messages.append({
            "role": "tool",
            "content": json.dumps(result),
            "tool_call_id": tool_call.id
        })
        
        final = client.chat.completions.create(model="gpt-4", messages=messages)
        return final.choices[0].message.content
    
    return response.choices[0].message.content

# Use it
answer = ask_fred("What's the GDP growth trend over the last 5 years?")
print(answer)

Popular Series IDs

• GDP - Gross Domestic Product
• UNRATE - Unemployment Rate
• CPIAUCSL - Consumer Price Index (Inflation)
• FEDFUNDS - Federal Funds Rate
• DGS10 - 10-Year Treasury Constant Maturity Rate
• SP500 - S&P 500 Index

Environment Variables

Instead of passing api_key parameter, you can set:

export FRED_API_KEY="your-api-key-here"

Then use:

fred = FredTools()  # Will use FRED_API_KEY from environment

Requirements

• Python 3.8+
• httpx (installed automatically)

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

For commercial licensing options, please contact the maintainer.

Disclaimer

This open-source project is not affiliated with, sponsored by, or endorsed by the Federal Reserve or the Federal Reserve Bank of St. Louis. "FRED" is a registered trademark of the Federal Reserve Bank of St. Louis, used here for descriptive purposes only.

Credits

Converted from the excellent FRED MCP Server by Stefano Amorelli.

Links

• FRED Website: https://fred.stlouisfed.org/
• FRED API Docs: https://fred.stlouisfed.org/docs/api/
• Get API Key: https://fred.stlouisfed.org/docs/api/api_key.html