Metadata-Version: 2.4
Name: finsdk
Version: 0.3.1
Summary: Python SDK for financial data and visualization
Project-URL: Homepage, https://savvy-mcp.com
Project-URL: Documentation, https://savvy-mcp.com/docs/sdk
Project-URL: Repository, https://github.com/nimar2/savvy
Project-URL: Issues, https://github.com/nimar2/savvy/issues
Author-email: Savvy <hello@savvy-mcp.com>
License-Expression: MIT
Keywords: charts,data,economics,finance,mcp,stocks,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Requires-Dist: pandas>=1.5.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# finsdk

Python SDK for financial data and visualization.

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

## Installation

```bash
pip install finsdk
```

## Quick Start

```python
import finsdk

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

# Fetch economic data (returns pandas DataFrame)
df = finsdk.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 = finsdk.stock_data.fetch("AAPL", period="1y")

# Create a visualization
chart = finsdk.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 = finsdk.economic_data.fetch("UNRATE")

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

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

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

### Stock Data

Get stock prices from Yahoo Finance:

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

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

### Cryptocurrency Data

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

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

### Visualization

Create charts with natural language:

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

# With options
chart = finsdk.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 finsdk

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

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

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

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

## Error Handling

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

try:
    df = finsdk.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
