# 🏦 Macroeconomic Sentiment Analysis Pipeline

A multi-head NLP system for scoring macroeconomic text — news articles, central bank policy statements, regulatory documents, tweets, and climate/ESG reports.

## Architecture

The pipeline combines **dictionary-based signals** with **transformer models** through intelligent domain routing:

```
Input Text
    │
    ├─► [Topic Router] ──► Policy/Macro ──► Financial-RoBERTa-Large
    │                  ──► Climate/ESG  ──► ClimateBERT
    │                  ──► News/Corp    ──► FinBERT
    │                  ──► Social/Tweet ──► FinBERT
    │
    ├─► [Loughran-McDonald Dictionary] ──► polarity, subjectivity
    ├─► [Henry (2008) Dictionary] ──────► earnings tone
    ├─► [Sautner-style Climate Dict] ───► risk/opportunity density
    ├─► [Macro Policy Dictionary] ──────► hawkish/dovish, crisis, uncertainty
    │
    └─► [Combiner] ──► Final macro sentiment score [-1, +1]
```

## Quick Start

```python
from macro_sentiment import MacroSentimentPipeline

pipe = MacroSentimentPipeline(device="cpu")
result = pipe("The Federal Reserve raised rates by 75bps citing persistent inflation.")
print(result.summary())
# Sentiment: Positive (+0.398) | Policy: Very Hawkish (+0.98) | Crisis: Normal | Domain: policy

print(result.macro_sentiment)      # [-1, +1]
print(result.policy_stance)        # [-1 dovish, +1 hawkish]
print(result.crisis_signal)        # [0, 1]
print(result.climate_exposure)     # [0, 1]
```

### Dictionary-Only Mode (no GPU required)
```python
pipe = MacroSentimentPipeline(load_transformers=False)
result = pipe("Markets crashed amid recession fears.", mode="dict_only")
```

## Output Fields

| Field | Range | Description |
|-------|-------|-------------|
| `macro_sentiment` | [-1, +1] | Composite sentiment score |
| `policy_stance` | [-1, +1] | Dovish (-1) to Hawkish (+1) |
| `financial_sentiment` | [-1, +1] | Financial news sentiment |
| `climate_sentiment` | [-1, +1] | Climate risk (-1) to opportunity (+1) |
| `crisis_signal` | [0, 1] | Crisis intensity |
| `uncertainty` | [0, 1] | Uncertainty level |
| `confidence` | [0, 1] | Model confidence |
| `detected_domain` | str | policy/climate/financial_news/social |

## Dictionaries

| Dictionary | Paper | Captures |
|-----------|-------|----------|
| **Loughran-McDonald** | LM (2011) | Financial negative/positive/uncertainty/litigious |
| **Henry** | Henry (2008) | Earnings press release tone |
| **Climate Exposure** | Sautner et al. (2023) style | Climate risk/opportunity/regulatory density |
| **Macro Policy** | Custom | Hawkish/dovish stance, crisis intensity, uncertainty |

## Transformer Models

| Head | Model | Domain |
|------|-------|--------|
| **FinBERT** | `ProsusAI/finbert` | Financial news |
| **Financial-RoBERTa** | `soleimanian/financial-roberta-large-sentiment` | Policy/formal text |
| **ClimateBERT** | `climatebert/distilroberta-base-climate-sentiment` | Climate/ESG |

## Training Data

~20K samples from 5 datasets: FinancialPhraseBank, Twitter Financial News, Auditor Sentiment, FiQA, ClimateBERT Climate Sentiment.

## Meta-classifier

Dictionary-only meta-classifier (GradientBoosting): **F1 macro = 0.58** on 24 dictionary features. Combined transformer+dictionary meta-classifier improves further.

## Literature

- Loughran & McDonald (2011), Henry (2008), Sautner et al. (2023)
- FinBERT (arxiv:1908.10063), FOMC-RoBERTa (arxiv:2305.07972)
- ClimateBERT (arxiv:2110.12010), FinDPO (arxiv:2507.18417)
- InflaBERT (arxiv:2410.20198)

## License
Apache 2.0