macro economic

# valoswiss-macro-economic (31°)

**Macro-categoria**: 📈 QUANT/MARKETS
**Scope**: Macro economic indicators ingestion + multi-source aggregation + regime detection + scenario analysis
**Born**: 2026-05-03 (V20 — 3-Point Registration completa)
**Owner downstream**: ADVISOR · SUPERVISOR/ADMIN (macro dashboard + regime alerts) · trading-agents (macro analyst input)
**Last aligned**: 2026-05-03 V20

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento, verifica in quest'ordine:

1. **Branch + working tree**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Sidecar Python health**
   ```bash
   curl -s http://127.0.0.1:8902/healthz | jq .
   ```
   Deve ritornare `{"status":"ok","version":"1.0.0","sources":["fred","weo","oecd","worldbank","eurostat","alphavantage"]}`. Se 502/connection refused → sidecar PM2 down: `pm2 list | grep macro-economic-py`.
3. **NestJS proxy health**
   ```bash
   curl -s http://127.0.0.1:4010/api/macro-economic/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ sidecar:{status:'ok'}, lastIngestionAt:'...', seriesCount:N }`.
4. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le 3 model `MacroSeries` / `MacroObservation` / `MacroScenario` + 2 enum `MacroSourceEnum` / `MacroRegimeEnum` siano applicate.
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"macroEconomic": true` subito dopo `tradingAgents`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'macroEconomic'` in `defaultModules` per `ADVISOR` + `RELATIONSHIP_MANAGER` + `SUPERVISOR` + `ADMIN`.
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `macroEconomic` con `sidebarSection: 'MERCATI'`, `requiredRole: 'ADVISOR'`, `personaHint: 'macro'`, icon `📈`.
8. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL (vedi §3), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic`.

Se uno qualunque dei 7 punti fallisce, **fermati e annota la deviazione** prima di procedere — la 3-Point Registration è invariante non negoziabile (vedi `feedback_new_module_registration.md`).

---

## §1 · Aree di competenza

### 1.1 Fonti dati macro (repos di riferimento)

| Source | Repo / API | Aggiornamento | Indicatori chiave |
|--------|------------|---------------|-------------------|
| **FRED** (St. Louis Fed) | `mortada/fredapi` (PyPI `fredapi`) | Daily / Weekly | GDP, CPI, PCE, unemployment rate, fed funds rate, M2, yield curve (2Y/5Y/10Y/30Y), credit spreads (OAS HY/IG), VIX |
| **IMF WEO** | `epogrebnyak/weo-reader` + `datasets/imf-weo` | Quarterly (Apr/Oct release) | World GDP, inflation projections, current account, fiscal balance, output gap per 190 countries |
| **OECD.Stat** | OECD API `data.oecd.org/api/data` | Monthly / Quarterly | CLI (Composite Leading Indicators), PMI components, industrial production, retail sales, OECD-wide unemployment |
| **World Bank API** | `letsgoexploring/economic-data` + WB API v2 | Annual | Long-run GDP series, poverty, inequality (Gini), debt/GDP, FDI, trade openness |
| **Alpha Vantage Economic** | Alpha Vantage `/query?function=REAL_GDP` etc | Monthly / Quarterly | US GDP real, treasury yield, CPI, inflation, retail sales, durable goods, nonfarm payrolls |
| **Eurostat** | Eurostat REST API `ec.europa.eu/eurostat/api` | Monthly | EA HICP, EA unemployment, EA GDP flash, EA trade balance, ZEW economic sentiment |
| **OECD CLI** | oecd.stat composite leading indicators | Monthly | CLI 6-month amplitude-adjusted per 38 OECD members |
| **Alpha Vantage FX** | `CURRENCY_EXCHANGE_RATE` | Real-time (intraday) | EUR/USD, USD/CHF, GBP/USD, USD/JPY, EUR/CHF major FX for regime context |

### 1.2 Indicatori macro aggregati

**Ciclo Reale**
- GDP growth YoY, QoQ SAAR (US, EA, CH, UK, CN, JP, World)
- Industrial production index
- Retail sales volume
- PMI composite (Markit/S&P Global — US/EA/CH/UK/CN)
- OECD CLI 6-month rate of change

**Inflazione**
- CPI YoY, MoM (US, EA, CH, UK)
- Core CPI ex-food-energy
- PCE core (Fed's preferred gauge)
- PPI (producer prices upstream signal)
- Breakeven inflation 2Y/5Y/10Y (TIPS spread)

**Lavoro**
- Unemployment rate U3, U6 (US)
- NFP monthly change + revision
- JOLTS job openings, quits rate
- EA unemployment rate (Eurostat)

**Monetario e tassi**
- Fed Funds Rate (effective, target range midpoint)
- ECB Deposit Facility Rate
- SNB policy rate
- 2Y/5Y/10Y/30Y US Treasury yield
- Yield curve slope (10Y-2Y spread — inversion flag)
- Real yield (10Y TIPS)

**Credit / Rischio**
- OAS HY (ICE BofA US High Yield spread)
- OAS IG (ICE BofA US Investment Grade spread)
- VIX (30d implied vol S&P500)
- MOVE index (bond vol)
- TED spread (LIBOR-OIS proxy)

**Commodity**
- WTI crude oil (USD/bbl)
- Brent crude (USD/bbl)
- Henry Hub natural gas (USD/MMBtu)
- Gold (USD/troy oz)
- Copper (USD/lb — industrial barometer)
- CRB commodity index

**FX**
- EUR/USD, USD/CHF, GBP/USD, USD/JPY, EUR/CHF
- DXY Dollar Index (trade-weighted)
- CHF safe-haven indicator (EUR/CHF vs 1.05 floor)

### 1.3 Rolling refresh schedule

| Frequenza | Indicatori | Cron |
|-----------|------------|------|
| Daily 06:00 | FRED high-freq (fed funds, treasuries, VIX, OAS, FX, commodity) | `0 6 * * *` |
| Daily 07:00 | Alpha Vantage economic (US GDP, CPI, retail sales) | `0 7 * * *` |
| Weekly Mon 05:00 | FRED weekly series (M2, initial claims, continuing claims) | `0 5 * * 1` |
| Monthly 5th 04:00 | OECD API (CLI, PMI, industrial production, unemployment) | `0 4 5 * *` |
| Monthly 5th 04:30 | Eurostat (EA HICP, EA unemployment, EA GDP flash) | `30 4 5 * *` |
| Quarterly Apr/Oct | IMF WEO (world GDP, inflation projections, output gap) | manual trigger post-WEO release |
| Annual | World Bank (long-run series, Gini, debt/GDP) | `0 2 1 1 *` |

### 1.4 Regime detection

**HMM (Hidden Markov Model)**
- 3 stati latenti: `EXPANSION` / `CONTRACTION` / `STAGFLATION`
- Features input: yield curve slope, CLI, PMI composite, credit spread OAS HY, unemployment change
- Library: `hmmlearn 0.3.x` (Python sidecar)
- Viterbi decoding → `currentRegime` + `regimeProbabilities[3]`
- Rolling window 36 mesi per fit; re-fit mensile

**Clustering (k-means)**
- K=4 cluster su spazio multidimensionale macro features normalizzate
- Label semantici mapping: `RISK-ON` / `RISK-OFF` / `REFLATION` / `DEFLATION`
- Used for: portfolio regime-driven allocation overlay (coordina valoswiss-portfolio)

### 1.5 Scenario analysis

**Recession probability model**
- Logistic regression su: yield curve inversion duration, CLI decline, credit spread widening, unemployment trend
- Output: `recessionProbability12M` [0,1] — soglie: <0.25 low, 0.25-0.5 elevated, >0.5 high
- NBER-inspired cycle turning point detection

**Fed model hawkish/dovish**
- Inputs: core PCE vs 2% target, unemployment gap vs NAIRU, real fed funds rate, dot plot median
- Output: `fedStance` HAWKISH | NEUTRAL | DOVISH + `nextMoveProbability` {hike: P, hold: P, cut: P}
- Calibrated su Fed Funds futures implied curve (FRED SOFR futures data)

---

## §2 · Pattern di codice

### 2.1 NestJS Service — macro ingestion controller

```typescript
// apps/api/src/modules/macro-economic/macro-economic.controller.ts
@Controller('macro-economic')
@UseGuards(JwtAuthGuard, RolesGuard)
export class MacroEconomicController {
  constructor(private readonly macroService: MacroEconomicService) {}

  @Get('health')
  @Roles('ADVISOR', 'SUPERVISOR', 'ADMIN')
  async health() {
    return this.macroService.getSidecarHealth();
  }

  @Get('series')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'SUPERVISOR', 'ADMIN')
  async listSeries(
    @Query('source') source?: string,
    @Query('frequency') frequency?: string,
    @Query('category') category?: string,
  ) {
    return this.macroService.listSeries({ source, frequency, category });
  }

  @Get('series/:seriesId/observations')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'SUPERVISOR', 'ADMIN')
  async getObservations(
    @Param('seriesId') seriesId: string,
    @Query('from') from?: string,
    @Query('to') to?: string,
    @Query('limit') limit = '120',
  ) {
    return this.macroService.getObservations(seriesId, { from, to, limit: parseInt(limit) });
  }

  @Get('regime')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'SUPERVISOR', 'ADMIN')
  async getCurrentRegime(@Query('tenantSlug') tenantSlug: string) {
    return this.macroService.getCurrentRegime(tenantSlug);
  }

  @Get('scenarios')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'SUPERVISOR', 'ADMIN')
  async getScenarios(@Query('tenantSlug') tenantSlug: string) {
    return this.macroService.getActiveScenarios(tenantSlug);
  }

  @Post('ingest')
  @Roles('SUPERVISOR', 'ADMIN')
  async triggerIngestion(
    @Body() dto: TriggerIngestionDto,
  ) {
    return this.macroService.triggerIngestion(dto.source, dto.seriesIds);
  }
}
```

### 2.2 NestJS Service — facade con sidecar proxy

```typescript
// apps/api/src/modules/macro-economic/macro-economic.service.ts
@Injectable()
export class MacroEconomicService {
  private readonly logger = new Logger(MacroEconomicService.name);

  constructor(
    @Optional() private readonly prisma: TenantPrismaService,
    private readonly sidecar: MacroSidecarClient,
  ) {}

  async getSidecarHealth() {
    return this.sidecar.get('/healthz');
  }

  async listSeries(filters: { source?: string; frequency?: string; category?: string }) {
    // Getter esplicito Wave 1.6 — NON usare legacy cast as-any
    const where: Prisma.MacroSeriesWhereInput = {};
    if (filters.source) where.source = filters.source as MacroSourceEnum;
    if (filters.frequency) where.frequency = filters.frequency;
    if (filters.category) where.category = filters.category;
    return this.prisma.macroSeries.findMany({ where, orderBy: { seriesId: 'asc' } });
  }

  async getObservations(seriesId: string, opts: { from?: string; to?: string; limit: number }) {
    const where: Prisma.MacroObservationWhereInput = { seriesId };
    if (opts.from) where.observationDate = { gte: new Date(opts.from) };
    if (opts.to) where.observationDate = { ...(where.observationDate as object), lte: new Date(opts.to) };
    return this.prisma.macroObservation.findMany({
      where,
      orderBy: { observationDate: 'desc' },
      take: opts.limit,
    });
  }

  async getCurrentRegime(tenantSlug: string) {
    // Chiama sidecar :8902 per regime HMM
    const regime = await this.sidecar.post('/regime/current', { tenantSlug });
    return regime;
  }

  async getActiveScenarios(tenantSlug: string) {
    return this.prisma.macroScenario.findMany({
      where: { tenantSlug, isActive: true },
      orderBy: { updatedAt: 'desc' },
    });
  }

  async triggerIngestion(source: string, seriesIds?: string[]) {
    this.logger.log(`Manual ingestion trigger: source=${source}`);
    return this.sidecar.post('/ingest', { source, seriesIds });
  }
}
```

### 2.3 TenantPrismaService getter espliciti (Wave 1.6)

```typescript
// NON usare "legacy cast as-any" su prisma — getter espliciti obbligatori
get macroSeries() { return this.client.macroSeries; }
get macroObservation() { return this.client.macroObservation; }
get macroScenario() { return this.client.macroScenario; }
```

### 2.4 Prisma schema (idempotent V15)

```prisma
// apps/api/prisma/schema.prisma — append dopo trading-agents models

enum MacroSourceEnum {
  FRED
  IMF_WEO
  OECD
  WORLD_BANK
  EUROSTAT
  ALPHA_VANTAGE
}

enum MacroRegimeEnum {
  EXPANSION
  CONTRACTION
  STAGFLATION
  UNDEFINED
}

model MacroSeries {
  id          String          @id @default(cuid())
  seriesId    String          @unique          // es. "FRED:DGS10", "OECD:CLI:USA"
  source      MacroSourceEnum
  name        String                           // "US 10Y Treasury Yield"
  category    String                           // "yield_curve" | "inflation" | "labor" | etc.
  frequency   String                    

…[truncato — apri il file MD per testo completo]