Metadata-Version: 2.4
Name: moneyfeel-mri
Version: 1.0.2
Summary: Python client for the MoneyFeel Macro & Geopolitical Risk Index API
Author-email: moneyfeel <info@moneyfeel.it>
License: CC BY-NC 4.0
Project-URL: Homepage, https://moneyfeel.it
Project-URL: Documentation, https://github.com/moneyfeel-io/mri-api
Project-URL: Repository, https://github.com/moneyfeel-io/mri-api
Project-URL: Get API Key, https://moneyfeel.it/account
Project-URL: Bug Reports, https://github.com/moneyfeel-io/mri-api/issues
Keywords: macro,regime,finance,risk,geopolitical,mri,moneyfeel,quant,portfolio
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
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: License :: Free for non-commercial use
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: pandas
Requires-Dist: pandas>=1.3; extra == "pandas"
Provides-Extra: all
Requires-Dist: pandas>=1.3; extra == "all"

# moneyfeel-mri

**Python client for the moneyfeel Macro & Geopolitical Risk Index.**

[![PyPI version](https://img.shields.io/pypi/v/moneyfeel-mri.svg)](https://pypi.org/project/moneyfeel-mri/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
[![License: CC BY-NC 4.0](https://img.shields.io/badge/License-CC%20BY--NC%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

Free programmatic access to the moneyfeel MRI — an institutional-grade macro regime classifier covering **5 regions** (GLOBAL, US, EU, ASIA, EM) across **3 timeframes** (Daily, Weekly, Monthly), updated daily.

---

## Installation

```bash
pip install moneyfeel-mri

# With pandas support (recommended)
pip install moneyfeel-mri[pandas]
```

## Get a Free API Key

1. Register at [moneyfeel.it](https://moneyfeel.it) — free, no credit card
2. Go to your [account page](https://moneyfeel.it/conto-iscrizione/)
3. Find the **MRI API Access** section → **Generate API Key**

---

## Quick Start

```python
from moneyfeel import MRI

client = MRI("mf_live_YOUR_KEY")

# Current regime — no auth required
current = client.current()
for region in current:
    print(region["region"], region["regime_weekly"], region["score_weekly"])

# Historical data as pandas DataFrame
df = client.history_df("US", "WEEKLY", from_date="2020-01-01")
print(df.tail())

# Latest regime
latest = client.latest("EU", "WEEKLY")
print(f"EU: {latest['regime']} | score={latest['mri_score']}")

# Performance metrics
m = client.metrics("US", "WEEKLY")[0]
print(f"Sharpe: {m['sharpe']} | CAGR: {m['cagr_strategy']}% | MaxDD: {m['max_dd']}%")

# Full CSV download
df_full = client.download("US", "WEEKLY")           # returns DataFrame
client.download("US", "WEEKLY", "us_weekly.csv")    # saves to file
```

---

## All Methods

| Method | Auth | Description |
|--------|------|-------------|
| `current()` | No | Current regime for all 5 regions |
| `status()` | No | API health check |
| `regions()` | No | Available regions and timeframes |
| `history(region, tf, from_date, to_date)` | Yes | Historical regime data |
| `history_df(region, tf, from_date, to_date)` | Yes | Same, as pandas DataFrame |
| `latest(region, tf)` | Yes | Most recent regime record |
| `metrics(region, tf)` | Yes | Strategy performance KPIs |
| `timeseries(region, tf, from_date)` | Yes | Daily return series |
| `timeseries_df(region, tf, from_date)` | Yes | Same, as pandas DataFrame |
| `eoy(region, tf)` | Yes | Year-by-year returns |
| `drawdowns(region, tf)` | Yes | Top 10 drawdown periods |
| `download(region, tf, output_path)` | Yes | Full CSV dataset |

---

## Error Handling

```python
from moneyfeel import MRI, MRIAuthError, MRIRateLimitError
import time

client = MRI("mf_live_YOUR_KEY")

try:
    data = client.history("US", "WEEKLY")
except MRIAuthError:
    print("Invalid or revoked key — get a new one at moneyfeel.it/account")
except MRIRateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
    time.sleep(e.retry_after)
```

---

## Data Coverage

- **Regions:** GLOBAL · US · EU · ASIA · EM
- **Timeframes:** DAILY · WEEKLY · MONTHLY
- **History:** 2007-01-04 to present
- **Updated:** daily at market close

## Rate Limits

| Limit | Value |
|-------|-------|
| Requests/minute | 30 |
| Requests/day | 2,000 |
| History | Full (2007+) |
| Cost | Free |

---

## Links

- 🌐 [moneyfeel.it](https://moneyfeel.it)
- 📊 [Live Dashboard](https://moneyfeel.it/dashboard/macro-regime-index/)
- 📖 [API Documentation](https://github.com/moneyfeel-io/mri-api)
- 🔑 [Get API Key](https://moneyfeel.it/conto-iscrizione/)

## License

CC BY-NC 4.0 — free for research and non-commercial use.
