Add Google Colab / Kaggle getting started section with complete install steps

README.md

@@ -156,9 +156,14 @@ The fusion weights are **crisis-adaptive**: when the crisis dictionary fires str
 
 ## Quick Start
 
-### Standalone FinBERT (this model only)
+There are two ways to use this model — pick the one that fits your needs:
+
+### Option A: Standalone FinBERT (classification only)
+
+If you just need positive/negative/neutral labels, use the model directly — no repo cloning required:
 
 ```python
+# pip install transformers torch
 from transformers import pipeline
 
 classifier = pipeline("text-classification", model="peyterho/macro-sentiment-finbert", top_k=None)
@@ -167,7 +172,15 @@ print(result)
 # [[{'label': 'positive', 'score': 0.72}, {'label': 'neutral', 'score': 0.21}, {'label': 'negative', 'score': 0.07}]]
 ```
 
-### Full Pipeline (recommended)
+### Option B: Full Pipeline (multi-signal analysis)
+
+For the complete system — topic routing, policy stance, crisis signals, climate scoring, and dictionaries — you need to clone this repo since the pipeline code lives inside it:
+
+```bash
+git clone https://huggingface.co/peyterho/macro-sentiment-finbert
+cd macro-sentiment-finbert
+pip install -r requirements.txt
+```
 
 ```python
 from macro_sentiment import MacroSentimentPipeline
@@ -194,7 +207,132 @@ result = pipe("Die EZB signalisiert Geduld bei künftigen Zinssenkungen.")
 print(result.summary())
 ```
 
-### Structured Output
+## Use in Google Colab / Kaggle
+
+Copy-paste these cells into a notebook. Both work on Colab (free tier) and Kaggle.
+
+### Cell 1 — Standalone FinBERT only
+
+```python
+!pip install -q transformers torch
+
+from transformers import pipeline
+
+classifier = pipeline("text-classification", model="peyterho/macro-sentiment-finbert", top_k=None)
+
+# Try it
+texts = [
+    "Tesla shares surged 15% after crushing earnings expectations.",
+    "The Federal Reserve raised rates by 75bps citing persistent inflation.",
+    "Markets crashed amid recession fears and massive layoffs.",
+    "The company reported quarterly results in line with analyst estimates.",
+]
+
+for text in texts:
+    result = classifier(text)[0]
+    top = max(result, key=lambda x: x["score"])
+    print(f'{top["label"]:>8s} ({top["score"]:.2f})  {text}')
+```
+
+### Cell 1 — Full Pipeline (with policy stance, crisis signals, climate scoring)
+
+```python
+# Install dependencies and clone the repo
+!pip install -q transformers torch pysentiment2 scikit-learn numpy pandas datasets accelerate huggingface_hub
+!git clone https://huggingface.co/peyterho/macro-sentiment-finbert /content/macro-sentiment-finbert
+
+import sys
+sys.path.insert(0, "/content/macro-sentiment-finbert")
+```
+
+### Cell 2 — Score any text
+
+```python
+from macro_sentiment import MacroSentimentPipeline
+
+pipe = MacroSentimentPipeline(device="cpu")
+
+texts = [
+    "Markets rallied on strong earnings, with the S&P 500 hitting record highs.",
+    "The ECB raised rates by 25 basis points, citing persistent inflation pressures.",
+    "The company committed to net-zero emissions by 2040 through renewable energy investments.",
+    "Credit markets froze as contagion fears spread across European banks.",
+    "Die EZB signalisiert Geduld bei künftigen Zinssenkungen.",
+]
+
+for text in texts:
+    result = pipe(text)
+    print(result.summary())
+    print(f"  → {text}\n")
+```
+
+### Cell 3 — Explore the full structured output
+
+```python
+result = pipe("Fed signals two more rate cuts before year-end, a dovish surprise that lifted equities.")
+
+print(f"Macro sentiment:    {result.macro_sentiment:+.3f}")
+print(f"Financial sentiment:{result.financial_sentiment:+.3f}")
+print(f"Policy stance:      {result.policy_stance:+.3f}  (negative=dovish, positive=hawkish)")
+print(f"Crisis signal:      {result.crisis_signal:.3f}")
+print(f"Climate sentiment:  {result.climate_sentiment:+.3f}")
+print(f"Uncertainty:        {result.uncertainty:.3f}")
+print(f"Confidence:         {result.confidence:.3f}")
+print(f"Domain:             {result.detected_domain}")
+print(f"Head used:          {result.head_used}")
+print(f"LM polarity:        {result.lm_polarity:+.3f}")
+print(f"Henry polarity:     {result.henry_polarity:+.3f}")
+print(f"Climate exposure:   {result.climate_exposure:.3f}")
+```
+
+### Cell 4 — Batch scoring with pandas
+
+```python
+import pandas as pd
+
+headlines = [
+    "Strong jobs report pushes markets to record highs",
+    "Tech earnings mixed as AI spending soars",
+    "Fed signals patience on rate cuts, markets dip",
+    "Retail sales disappoint, recession fears resurface",
+    "Green bond issuance hit $500B as investors pivot to sustainable fixed income",
+    "Bank of Japan holds rates steady in surprise decision",
+]
+
+results = pipe.score_batch(headlines, mode="routed")
+
+df = pd.DataFrame([{
+    "text": t,
+    "sentiment": r.macro_sentiment,
+    "policy": r.policy_stance,
+    "crisis": r.crisis_signal,
+    "climate": r.climate_sentiment,
+    "domain": r.detected_domain,
+    "head": r.head_used,
+} for t, r in zip(headlines, results)])
+
+print(df.to_string(index=False))
+```
+
+### Cell 5 — Dictionary-only mode (no GPU needed, instant)
+
+```python
+# No transformer models loaded — uses only the four dictionaries
+result = pipe.score("The central bank cut rates amid fears of a deepening recession.", mode="dict_only")
+print(result.summary())
+print(f"LM polarity:   {result.lm_polarity:+.3f}")
+print(f"Henry polarity: {result.henry_polarity:+.3f}")
+print(f"Policy stance:  {result.policy_stance:+.3f}")
+print(f"Crisis signal:  {result.crisis_signal:.3f}")
+```
+
+> **💡 Notes:**
+> - The full pipeline lazy-loads transformer models on first use. First call takes 30–60 seconds to download (~800MB across 4 models). Subsequent calls are fast.
+> - `mode="routed"` (default) loads only 1 model per call. `mode="all"` loads all 4 models (~2GB RAM).
+> - For Colab free tier, `mode="routed"` works fine. For `mode="all"`, use a GPU runtime to avoid OOM.
+> - On Kaggle, enable "Internet" in notebook settings (Settings → Internet → On) so models can download.
+
+## Structured Output
 
 Every call returns a `MacroSentimentResult` with these fields:
 
@@ -213,21 +351,7 @@ Every call returns a `MacroSentimentResult` with these fields:
 | `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
+## Scoring Modes
 
 ```python
 # "routed" (default) — topic router selects best head