Improve model card with comprehensive documentation

README.md

@@ -2,65 +2,404 @@
 library_name: transformers
 base_model: ProsusAI/finbert
 tags:
-- generated_from_trainer
+- sentiment-analysis
+- finance
+- macroeconomics
+- climate
+- esg
+- policy
+- ensemble
+- dictionary
+- finbert
+- text-classification
+language:
+- en
+- ar
+- fr
+- de
+- hi
+- it
+- pt
+- es
+license: apache-2.0
+datasets:
+- nickmuchi/financial-classification
+- zeroshot/twitter-financial-news-sentiment
+- FinanceInc/auditor_sentiment
+- pauri32/fiqa-2018
+- climatebert/climate_sentiment
 metrics:
 - accuracy
+- f1
+pipeline_tag: text-classification
 model-index:
 - name: macro-sentiment-finbert
-  results: []
+  results:
+  - task:
+      type: text-classification
+      name: Sentiment Analysis
+    dataset:
+      name: Combined Financial Sentiment (5 datasets)
+      type: custom
+    metrics:
+    - type: accuracy
+      value: 0.8973
+      name: Accuracy
+    - type: f1
+      value: 0.8813
+      name: F1 (macro)
+    - type: f1
+      value: 0.8984
+      name: F1 (weighted)
+  - task:
+      type: text-classification
+      name: Sentiment Analysis (OOD)
+    dataset:
+      name: Jean-Baptiste/financial_news_sentiment_mixte_with_phrasebank_75
+      type: Jean-Baptiste/financial_news_sentiment_mixte_with_phrasebank_75
+    metrics:
+    - type: accuracy
+      value: 0.9236
+      name: Accuracy
+    - type: f1
+      value: 0.9134
+      name: F1 (macro)
+  - task:
+      type: text-classification
+      name: Sentiment Analysis (OOD)
+    dataset:
+      name: ic-fspml/stock_news_sentiment
+      type: ic-fspml/stock_news_sentiment
+    metrics:
+    - type: accuracy
+      value: 0.6781
+      name: Accuracy
+    - type: f1
+      value: 0.6765
+      name: F1 (macro)
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
+# Macro Sentiment FinBERT
 
-# macro-sentiment-finbert
+**A multi-signal macroeconomic sentiment pipeline** that combines fine-tuned transformer ensembles with financial dictionaries and topic routing to produce structured sentiment analysis for financial news, central bank communications, climate/ESG reports, and social media.
 
-This model is a fine-tuned version of [ProsusAI/finbert](https://huggingface.co/ProsusAI/finbert) on the None dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.3450
-- Accuracy: 0.8486
-- F1 Macro: 0.8325
-- F1 Weighted: 0.8515
+This repo hosts the **FinBERT head** (109M params, fine-tuned from [ProsusAI/finbert](https://huggingface.co/ProsusAI/finbert)) — the default routing target and backbone of the full pipeline. The complete system includes three additional transformer heads, four dictionary scorers, and a keyword-based topic router.
 
-## Model description
+## Key Features
 
-More information needed
+- 🏦 **Macro-aware** — outputs financial sentiment, monetary policy stance (dovish ↔ hawkish), crisis signals, and uncertainty
+- 🌱 **Climate/ESG scoring** — dedicated ClimateBERT head + Sautner-style exposure dictionary for climate risk vs. opportunity
+- 🔀 **Topic routing** — automatically selects the best transformer head based on text content (policy → RoBERTa-Large, climate → ClimateBERT, financial news → FinBERT)
+- 🌍 **Multilingual** — non-English text auto-routes to XLM-RoBERTa (8+ languages: EN, AR, FR, DE, HI, IT, PT, ES)
+- 📖 **Dictionary layer** — Loughran-McDonald, Henry earnings tone, climate exposure, and macro policy dictionaries provide interpretable feature signals alongside neural predictions
 
-## Intended uses & limitations
+## Architecture
 
-More information needed
+```
+                          ┌──────────────────────────────────┐
+                          │         Input Text               │
+                          └──────────────┬───────────────────┘
+                                         │
+                    ┌────────────────────┼────────────────────┐
+                    ▼                    ▼                    ▼
+          ┌─────────────────┐  ┌─────────────────┐  ┌───────────────┐
+          │  Topic Router   │  │   Dictionary    │  │   Language    │
+          │  (keywords)     │  │   Scorers (×4)  │  │   Detection   │
+          └────────┬────────┘  └────────┬────────┘  └───────┬───────┘
+                   │                    │                    │
+          ┌────────▼────────────────────┼────────────────────▼────────┐
+          │                    Head Selection                         │
+          │  policy → RoBERTa-Large  │  climate → ClimateBERT        │
+          │  financial → FinBERT ★   │  non-English → XLM-RoBERTa   │
+          └────────┬────────────────────────────────────────┬────────┘
+                   │                                        │
+          ┌────────▼────────┐                     ┌────────▼────────┐
+          │   Transformer   │                     │   Dictionary    │
+          │   Score [-1,+1] │                     │   Composite     │
+          └────────┬────────┘                     └────────┬────────┘
+                   │                                        │
+                   └──────────────┬─────────────────────────┘
+                                  ▼
+                   ┌──────────────────────────────┐
+                   │    Weighted Fusion            │
+                   │  (crisis-adaptive weights)    │
+                   └──────────────┬───────────────┘
+                                  ▼
+                   ┌──────────────────────────────┐
+                   │   MacroSentimentResult       │
+                   │  • macro_sentiment [-1,+1]   │
+                   │  • policy_stance [-1,+1]     │
+                   │  • crisis_signal [0,1]       │
+                   │  • climate_sentiment [-1,+1] │
+                   │  • confidence [0,1]          │
+                   │  • detected_domain           │
+                   └──────────────────────────────┘
+```
 
-## Training and evaluation data
+The fusion weights are **crisis-adaptive**: when the crisis dictionary fires strongly, more weight shifts to the dictionary composite (up to 75% dict / 25% transformer), since crisis language often carries clearer signal through keywords than neural softmax probabilities.
 
-More information needed
+## Ensemble Components
 
-## Training procedure
+| Head | Model | Params | Base | Role |
+|---|---|---|---|---|
+| **FinBERT** ★ | [peyterho/finbert-macro-sentiment](https://huggingface.co/peyterho/finbert-macro-sentiment) | 109M | [ProsusAI/finbert](https://huggingface.co/ProsusAI/finbert) | Default — financial news, tweets |
+| **RoBERTa-Large** | [peyterho/financial-roberta-large-macro-sentiment](https://huggingface.co/peyterho/financial-roberta-large-macro-sentiment) | 355M | [soleimanian/financial-roberta-large-sentiment](https://huggingface.co/soleimanian/financial-roberta-large-sentiment) | Policy/macro text |
+| **ClimateBERT** | [peyterho/climatebert-macro-sentiment](https://huggingface.co/peyterho/climatebert-macro-sentiment) | 82M | [climatebert/distilroberta-base-climate-sentiment](https://huggingface.co/climatebert/distilroberta-base-climate-sentiment) | Climate/ESG text |
+| **XLM-RoBERTa** | [cardiffnlp/twitter-xlm-roberta-base-sentiment-multilingual](https://huggingface.co/cardiffnlp/twitter-xlm-roberta-base-sentiment-multilingual) | 278M | — | Non-English text (8+ languages) |
 
-### Training hyperparameters
+| Dictionary | Based On | Signal |
+|---|---|---|
+| **Loughran-McDonald** | Loughran & McDonald (2011) | Financial polarity, subjectivity |
+| **Henry** | Henry (2008) — earnings tone | Earnings press release tone |
+| **Climate Exposure** | Sautner et al. (2023) style | Climate risk vs. opportunity density |
+| **Macro Policy** | Custom | Hawkish/dovish stance, crisis intensity, uncertainty |
 
-The following hyperparameters were used during training:
-- learning_rate: 2e-05
-- train_batch_size: 16
-- eval_batch_size: 32
-- seed: 42
-- gradient_accumulation_steps: 4
-- total_train_batch_size: 64
-- optimizer: Use OptimizerNames.ADAMW_TORCH_FUSED with betas=(0.9,0.999) and epsilon=1e-08 and optimizer_args=No additional optimizer arguments
-- lr_scheduler_type: cosine
-- lr_scheduler_warmup_steps: 31
-- num_epochs: 2
+## Quick Start
 
-### Training results
+### Standalone FinBERT (this model only)
 
-| Training Loss | Epoch | Step | Validation Loss | Accuracy | F1 Macro | F1 Weighted |
-|:-------------:|:-----:|:----:|:---------------:|:--------:|:--------:|:-----------:|
-| 1.6807        | 1.0   | 314  | 0.3761          | 0.8246   | 0.8058   | 0.8300      |
-| 1.1679        | 2.0   | 628  | 0.3450          | 0.8486   | 0.8325   | 0.8515      |
+```python
+from transformers import pipeline
 
+classifier = pipeline("text-classification", model="peyterho/macro-sentiment-finbert", top_k=None)
+result = classifier("The Federal Reserve signaled a pause in rate hikes amid cooling inflation.")
+print(result)
+# [[{'label': 'positive', 'score': 0.72}, {'label': 'neutral', 'score': 0.21}, {'label': 'negative', 'score': 0.07}]]
+```
 
-### Framework versions
+### Full Pipeline (recommended)
+
+```python
+from macro_sentiment import MacroSentimentPipeline
+
+pipe = MacroSentimentPipeline(device="cpu")
+
+# Financial news — auto-routes to FinBERT
+result = pipe("Markets rallied on strong earnings, with the S&P 500 hitting record highs.")
+print(result.summary())
+# Sentiment: Positive (+0.612) | Policy: Neutral (+0.000) | Crisis: Normal (0.000) | Domain: financial_news
+
+# Central bank communication — auto-routes to RoBERTa-Large
+result = pipe("The ECB raised rates by 25 basis points, citing persistent inflation pressures.")
+print(result.summary())
+# Sentiment: Negative (-0.348) | Policy: Hawkish (+0.714) | Crisis: Normal (0.000) | Domain: policy
+
+# Climate/ESG text — auto-routes to ClimateBERT
+result = pipe("The company committed to net-zero emissions by 2040 through renewable energy investments.")
+print(result.summary())
+# Sentiment: Positive (+0.445) | Policy: Neutral (+0.000) | Crisis: Normal (0.000) | Domain: climate | Climate: Opportunity (exp=0.60)
+
+# Non-English text — auto-routes to XLM-RoBERTa
+result = pipe("Die EZB signalisiert Geduld bei künftigen Zinssenkungen.")
+print(result.summary())
+```
+
+### Structured Output
+
+Every call returns a `MacroSentimentResult` with these fields:
+
+| Field | Range | Description |
+|---|---|---|
+| `macro_sentiment` | [-1, +1] | Overall macroeconomic sentiment (weighted fusion of transformer + dictionary) |
+| `financial_sentiment` | [-1, +1] | Financial-domain sentiment from the selected transformer head |
+| `policy_stance` | [-1, +1] | Monetary policy orientation: -1 = very dovish, +1 = very hawkish |
+| `climate_sentiment` | [-1, +1] | Climate outlook: -1 = risk, +1 = opportunity |
+| `crisis_signal` | [0, 1] | Crisis language intensity (recession, contagion, bank failure, etc.) |
+| `uncertainty` | [0, 1] | Uncertainty/volatility language density |
+| `confidence` | [0, 1] | Pipeline confidence (based on head agreement, topic match, uncertainty) |
+| `detected_domain` | str | Routed domain: `financial_news`, `policy`, `climate`, `social`, `ensemble` |
+| `head_used` | str | Which transformer head was selected |
+| `lm_polarity` | [-1, +1] | Loughran-McDonald polarity score |
+| `henry_polarity` | [-1, +1] | Henry earnings tone score |
+| `climate_exposure` | [0, 1] | Climate keyword density (Sautner-style) |
+
+### Batch Scoring
+
+```python
+texts = [
+    "GDP growth exceeded expectations at 3.2% annualized.",
+    "Credit markets froze as contagion fears spread across European banks.",
+    "Solar installations surged 40% year-over-year globally.",
+]
+results = pipe.score_batch(texts, mode="routed")
+for text, r in zip(texts, results):
+    print(f"{r.summary()}")
+    print(f"  → {text[:80]}...\n")
+```
+
+### Scoring Modes
+
+```python
+# "routed" (default) — topic router selects best head
+result = pipe.score("text", mode="routed")
+
+# "all" — runs ALL heads and averages composite scores
+result = pipe.score("text", mode="all")
+
+# "dict_only" — dictionary signals only, no transformer inference
+result = pipe.score("text", mode="dict_only")
+```
+
+## Training Data
+
+All three transformer heads were fine-tuned on the same combined dataset of **5 public financial/climate sentiment corpora**:
+
+| Dataset | Domain | Samples | Label Mapping |
+|---|---|---|---|
+| [nickmuchi/financial-classification](https://huggingface.co/datasets/nickmuchi/financial-classification) | Financial PhraseBank | ~4,800 train / ~1,200 test | negative / neutral / positive |
+| [zeroshot/twitter-financial-news-sentiment](https://huggingface.co/datasets/zeroshot/twitter-financial-news-sentiment) | Financial tweets | ~9,900 train / ~2,500 val | bearish → neg, bullish → pos, neutral |
+| [FinanceInc/auditor_sentiment](https://huggingface.co/datasets/FinanceInc/auditor_sentiment) | Auditor reports | ~3,600 train / ~900 test | negative / neutral / positive |
+| [pauri32/fiqa-2018](https://huggingface.co/datasets/pauri32/fiqa-2018) | Financial QA + microblog | ~938 train+val / ~235 test | Continuous score thresholded at ±0.15 |
+| [climatebert/climate_sentiment](https://huggingface.co/datasets/climatebert/climate_sentiment) | Climate reports | ~1,000 train / ~500 test | risk → neg, neutral, opportunity → pos |
+
+All datasets were unified to a consistent 3-class schema: `0=negative`, `1=neutral`, `2=positive`.
+
+## Training Details
+
+### FinBERT Head (this model)
+
+| Hyperparameter | Value |
+|---|---|
+| Base model | [ProsusAI/finbert](https://huggingface.co/ProsusAI/finbert) |
+| Learning rate | 2e-5 |
+| Batch size | 16 × 4 gradient accumulation = 64 effective |
+| Epochs | 2 |
+| Scheduler | Cosine with 31 warmup steps |
+| Optimizer | AdamW (fused) |
+| Max length | 512 |
+| Seed | 42 |
+
+### Training Curve
+
+| Epoch | Train Loss | Val Loss | Accuracy | F1 (macro) | F1 (weighted) |
+|:---:|:---:|:---:|:---:|:---:|:---:|
+| 1 | 1.6807 | 0.3761 | 0.8246 | 0.8058 | 0.8300 |
+| 2 | 1.1679 | 0.3450 | 0.8486 | 0.8325 | 0.8515 |
+
+> Note: The higher training loss reflects the FinBERT label ordering (positive=0, negative=1, neutral=2) which differs from the unified schema — a label remapping is applied at training time.
+
+## Evaluation Results
+
+### In-Domain (Combined Test Set — 4,333 samples)
+
+| Model | Accuracy | F1 (macro) | F1 (weighted) |
+|---|:---:|:---:|:---:|
+| **RoBERTa-Large (355M)** | **0.9130** | **0.9023** | **0.9137** |
+| FinBERT (109M) ★ | 0.8973 | 0.8813 | 0.8984 |
+| ClimateBERT (82M) | 0.8885 | 0.8716 | 0.8898 |
+| Dict-only baseline (GBT) | 0.6693 | 0.5781 | 0.6500 |
+| Dict-only baseline (rules) | 0.5684 | 0.5277 | 0.5784 |
+
+### Out-of-Domain: Financial News Phrasebank (785 samples)
+
+Evaluated on [Jean-Baptiste/financial_news_sentiment_mixte_with_phrasebank_75](https://huggingface.co/datasets/Jean-Baptiste/financial_news_sentiment_mixte_with_phrasebank_75) — **not in the training mix**.
+
+| Model | Accuracy | F1 (macro) |
+|---|:---:|:---:|
+| **RoBERTa-Large** | **0.9414** | **0.9357** |
+| ClimateBERT | 0.9248 | 0.9213 |
+| FinBERT ★ | 0.9236 | 0.9134 |
+
+### Out-of-Domain: Stock News Headlines (30,150 samples)
+
+Evaluated on [ic-fspml/stock_news_sentiment](https://huggingface.co/datasets/ic-fspml/stock_news_sentiment) — 5-class mapped to 3-class. **Not in the training mix**.
+
+| Model | Accuracy | F1 (macro) |
+|---|:---:|:---:|
+| **RoBERTa-Large** | **0.7211** | **0.7265** |
+| FinBERT ★ | 0.6781 | 0.6765 |
+| ClimateBERT | 0.6472 | 0.6441 |
+
+Performance drops on stock news headlines are expected — these are short, noisy texts with 5→3 class mapping, representing a significant domain shift from the training data.
+
+## Custom Fine-Tuning
+
+You can fine-tune any head on your own labelled data using the included `finetune.py` script:
+
+```bash
+pip install -r requirements.txt
+
+python -m macro_sentiment.finetune \
+    --data my_labels.csv \
+    --text-column headline \
+    --label-column sentiment \
+    --base-model peyterho/macro-sentiment-finbert \
+    --output my-org/my-custom-model \
+    --push-to-hub \
+    --epochs 4 \
+    --lr 2e-5 \
+    --batch-size 32
+```
+
+Accepts CSV, TSV, JSON, or JSONL. Labels can be strings (`"positive"`, `"negative"`, `"neutral"`, `"bullish"`, `"bearish"`, `"risk"`, `"opportunity"`) or integers (0/1/2). Automatic class-weighted loss handles imbalanced datasets.
+
+## Limitations
+
+- **English-centric** — the fine-tuned heads (FinBERT, RoBERTa, ClimateBERT) are English-only. Non-English text falls back to the pre-trained XLM-RoBERTa multilingual model, which was not fine-tuned on the macro sentiment training mix.
+- **Domain-specific** — trained on financial news, earnings reports, climate disclosures, and financial tweets. Performance on general-purpose sentiment tasks (movie reviews, product reviews) will be lower.
+- **Dictionary lag** — the Loughran-McDonald and Henry dictionaries use static word lists that may not capture emerging financial terminology or evolving language patterns.
+- **No temporal awareness** — the model treats each text independently and does not incorporate time-series context or market state.
+- **Topic router is keyword-based** — the routing heuristic may misclassify ambiguous texts. Use `mode="all"` for important decisions to get ensemble averaging across all heads.
+- **Label noise** — the FiQA dataset uses continuous sentiment scores thresholded at ±0.15 to create discrete labels, introducing boundary noise for scores near the thresholds.
+
+## Citation
+
+If you use this model or pipeline, please cite the base models:
+
+```bibtex
+@article{araci2019finbert,
+  title={FinBERT: Financial Sentiment Analysis with Pre-Trained Language Models},
+  author={Araci, Dogu},
+  journal={arXiv preprint arXiv:1908.10063},
+  year={2019}
+}
+
+@article{loughran2011liability,
+  title={When is a liability not a liability? Textual analysis, dictionaries, and 10-Ks},
+  author={Loughran, Tim and McDonald, Bill},
+  journal={The Journal of Finance},
+  volume={66},
+  number={1},
+  pages={35--65},
+  year={2011}
+}
+
+@article{henry2008earnings,
+  title={Are investors influenced by how earnings press releases are written?},
+  author={Henry, Elaine},
+  journal={Journal of Business Communication},
+  volume={45},
+  number={4},
+  pages={363--407},
+  year={2008}
+}
+```
+
+## Repository Contents
+
+```
+├── model.safetensors          # FinBERT fine-tuned weights (109M params)
+├── config.json                # Model config (3-class: positive/negative/neutral)
+├── tokenizer.json             # BERT tokenizer
+├── eval_results.json          # In-domain benchmarks for all heads
+├── eval_ood_results.json      # Out-of-domain benchmarks
+├── artifacts/
+│   ├── meta_classifier.joblib # GradientBoosting meta-classifier on dictionary features
+│   └─��� smart_router.joblib    # Topic routing model
+├── macro_sentiment/
+│   ├── __init__.py            # Public API exports
+│   ├── pipeline.py            # MacroSentimentPipeline — main entry point
+│   ├── transformers_ensemble.py # Multi-head transformer ensemble + topic router
+│   ├── dictionaries.py        # LM, Henry, Climate, Macro dictionary scorers
+│   ├── data_prep.py           # Dataset loading and combination (5 datasets)
+│   ├── finetune.py            # Custom fine-tuning script
+│   └── train_meta.py          # Meta-classifier training script
+└── requirements.txt
+```
+
+## Framework Versions
 
 - Transformers 5.6.2
-- Pytorch 2.11.0+cu130
+- PyTorch 2.11.0+cu130
 - Datasets 4.8.4
 - Tokenizers 0.22.2