# savvy-mcp

Python SDK for [Savvy](https://savvy-mcp.com) - financial data and visualization.

Get economic indicators, stock prices, and create beautiful charts with just a few lines of code.

## Installation

```bash
pip install savvy-mcp
```

## Quick Start

```python
import savvy

# Set your API key (or use SAVVY_API_KEY environment variable)
savvy.configure(api_key="sk_...")

# Fetch economic data (returns pandas DataFrame)
df = savvy.economic_data.fetch("UNRATE", start="2020-01-01")
print(df.head())
#         date  value
# 0 2020-01-01    3.6
# 1 2020-02-01    3.5
# 2 2020-03-01    4.4

# Fetch stock data
df = savvy.stock_data.fetch("AAPL", period="1y")

# Create a visualization
chart = savvy.visualize(df, "Stock price over time")
print(chart.url)  # https://savvy-mcp.com/c/abc123
```

## Features

### Economic Data

Access data from 20+ sources including FRED, World Bank, IMF, ECB, and more:

```python
# US unemployment rate
df = savvy.economic_data.fetch("UNRATE")

# GDP growth with date range
df = savvy.economic_data.fetch("GDP", start="2010-01-01", end="2023-12-31")

# Search for data series
results = savvy.economic_data.search("inflation")
for r in results:
    print(f"{r['provider']}: {r['series_id']} - {r['name']}")

# Compare across countries
df = savvy.economic_data.compare("unemployment", ["US", "Germany", "Japan"])
```

### Stock Data

Get stock prices from Yahoo Finance:

```python
# Historical data
df = savvy.stock_data.fetch("AAPL", period="1y")
df = savvy.stock_data.fetch("MSFT", period="5y", interval="1wk")

# Current quote
quote = savvy.stock_data.quote("AAPL")
print(f"AAPL: ${quote['price']:.2f} ({quote['change_percent']:+.2f}%)")
```

### Cryptocurrency Data

```python
# Bitcoin price history
df = savvy.crypto_data.fetch("BTC-USD", period="1y")

# Ethereum quote
quote = savvy.crypto_data.quote("ETH")
```

### Visualization

Create charts with natural language:

```python
# Simple visualization
chart = savvy.visualize(df, "Line chart of stock price over time")

# With options
chart = savvy.visualize(
    df,
    "Show closing prices with a trendline",
    title="AAPL Stock Price",
    theme="executive",
)

# Access chart URLs
print(chart.url)     # Interactive HTML
print(chart.png)     # PNG image
print(chart.svg)     # SVG image
print(chart.python)  # Python code
```

## Configuration

```python
import savvy

# Option 1: Use configure()
savvy.configure(api_key="sk_...")

# Option 2: Environment variable (recommended for production)
# export SAVVY_API_KEY=sk_...

# Option 3: Custom API URL (for development)
savvy.configure(api_key="sk_...", api_url="https://custom.api.com")

# Read current config
print(savvy.api_key)  # Returns configured key
```

## Error Handling

```python
from savvy import SavvyError, AuthenticationError, DataNotFoundError

try:
    df = savvy.economic_data.fetch("INVALID_SERIES")
except DataNotFoundError as e:
    print(f"Series not found: {e.series_id}")
except AuthenticationError:
    print("Invalid API key")
except SavvyError as e:
    print(f"API error: {e}")
```

## Data Sources

| Provider | Data Types | Example |
|----------|-----------|---------|
| FRED | US economic indicators | `UNRATE`, `GDP`, `CPIAUCSL` |
| World Bank | Global development | `NY.GDP.MKTP.CD` |
| IMF | Forecasts | `gdp_growth` |
| ECB | Eurozone rates | `EONIA`, `EURUSD` |
| Yahoo Finance | Stocks, ETFs, crypto | `AAPL`, `SPY`, `BTC-USD` |
| Zillow | Housing data | `ZHVI:San Francisco` |
| And 15+ more... | | |

## Requirements

- Python 3.9+
- pandas
- httpx

## Links

- [Documentation](https://savvy-mcp.com/docs/sdk)
- [API Reference](https://savvy-mcp.com/docs/api)
- [Get an API Key](https://savvy-mcp.com)

## License

MIT
