Metadata-Version: 2.4
Name: fred-toolkit
Version: 0.1.0
Summary: FRED Economic Data Tools for LLM/Agent Integration - Access 800,000+ Federal Reserve time series
Project-URL: Homepage, https://github.com/pkarcreative/fred-toolkit
Project-URL: Documentation, https://github.com/pkarcreative/fred-toolkit#readme
Project-URL: Repository, https://github.com/pkarcreative/fred-toolkit
Project-URL: Issues, https://github.com/pkarcreative/fred-toolkit/issues
Author-email: Dr Priyabrata Karmakar <pkarcreative@gmail.com>
License: AGPL-3.0
License-File: LICENSE
Keywords: ai-agents,economic-data,federal-reserve,financial-data,fred,function-calling,llm-tools,openai-functions,time-series
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# fred-toolkit

[![PyPI version](https://badge.fury.io/py/fred-toolkit.svg)](https://badge.fury.io/py/fred-toolkit)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

**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](https://github.com/stefanoamorelli/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

```bash
pip install fred-toolkit
```

Or with `uv`:
```bash
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

```python
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

```python
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:**
```python
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:**
```python
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:**
```python
result = fred.execute_tool("fred_browse", {
    "browse_type": "categories"
})
```

## Common Use Cases

### Building an Economic Analysis Agent

```python
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:

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

Then use:
```python
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](https://github.com/stefanoamorelli/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
