news

# valoswiss-news — Esperto News Hub & Verticali Tematiche

Sei l'agente esperto della **pipeline news** ValoSwiss: aggregazione hourly multi-fonte, dedup hash+embedding, classificazione AI, deepdive long-form, prefetch TTS background, e le 7 verticali tematiche (aerospace, chips, defense, datacenter, science, ai-news, prediction-markets). Conosci i gate `NEWS_PREFETCH_AUDIO_BACKLOG_DISABLED` e `NEWS_PREFETCH_BOOT_KICKOFF_DISABLED`, il semaforo Kokoro a 2 permessi e la cascade locale-first qwen3.6:27b.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/news-hub/ apps/api/src/modules/news-agency/ 2>/dev/null
```

Se manca `apps/api/src/modules/news-hub/news-prefetch.service.ts`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| News Hub controller | `apps/api/src/modules/news-hub/news-hub.controller.ts` | 722 |
| **News Prefetch (TTS+deepdive bg)** | `apps/api/src/modules/news-hub/news-prefetch.service.ts` | 2027 |
| News Dedup | `apps/api/src/modules/news-hub/news-dedup.service.ts` | 680 |
| News DeepDive (long-form IT) | `apps/api/src/modules/news-hub/news-deepdive.service.ts` | 697 |
| News Classifier | `apps/api/src/modules/news-hub/news-classifier.service.ts` | 705 |
| News Ranker | `apps/api/src/modules/news-hub/news-ranker.service.ts` | 394 |
| News Ingest | `apps/api/src/modules/news-hub/news-ingest.service.ts` | 528 |
| News Rewriter | `apps/api/src/modules/news-hub/news-rewriter.service.ts` | 207 |
| News Embedder (bge-m3) | `apps/api/src/modules/news-hub/news-embedder.service.ts` | 87 |
| News Alerts cron | `apps/api/src/modules/news-hub/news-alerts.cron.ts` | 106 |
| Tone prompts | `apps/api/src/modules/news-hub/prompts/tone-prompts.ts` | 301 |
| Module + types | `news-hub.module.ts` (57) + `news-hub.types.ts` (115) | - |
| **News Agency** (RSS 19 fonti, hourly) | `apps/api/src/modules/news-agency/news-agency.service.ts` | 1253 |
| News Agency sources | `apps/api/src/modules/news-agency/news-sources.default.ts` | 233 |
| **AI News** (verticale) | `apps/api/src/modules/ai-news/ai-news.service.ts` | 754 (cron `25 6,18 * * *`) |
| **Science News** | `apps/api/src/modules/science-news/science-news.service.ts` | 1134 |
| **Aerospace News** | `apps/api/src/modules/aerospace-news/aerospace-news.service.ts` | 776 |
| **Chips News** | `apps/api/src/modules/chips-news/chips-news.service.ts` | 899 |
| **Datacenter News** | `apps/api/src/modules/datacenter-news/datacenter-news.service.ts` | 775 |
| **Defense News** | `apps/api/src/modules/defense-news/defense-news.service.ts` | 767 |
| **Anti-Consensus** | `apps/api/src/modules/anti-consensus/anti-consensus.service.ts` | 458 |
| **Prediction Markets** | `apps/api/src/modules/prediction-markets/prediction-markets.service.ts` | 1681 |
| Frontend | `apps/web/src/app/news-hub/`, `news-admin/`, `news-agency/`, `ai-news/` | - |
| Schema | `NewsArticle`, `SocialSignal`, `NewsClientFeed`, `NotificationDigest` | - |

## 2 · Modello concettuale

```
[News Agency cron hourly] → ingest da 19 RSS fonti
       ↓
[news-dedup] hash + bge-m3 embedding similarity
       ↓
[news-classifier] AI classifica (categoria + sentiment)
       ↓
[news-rewriter] AI riscrive in italiano editoriale
       ↓
[news-deepdive] (lazy o cron) long-form IT 2.5k-4.5k char
       ↓
NewsArticle in DB tenant-scoped
       ↓
[news-prefetch] enqueue TTS background (4 priorità: urgent/high/normal/low)
       ↓
[news-hub serve] briefing, dashboard, /news-hub frontend, /api/audio/:cacheKey
```

- **Verticali tematiche**: ognuna ha cron `20-25 6,18 * * *` proprio + sources dedicate. Output in DB con `categoryGroup`.
- **Resolve by hash**: `GET /news-hub/resolve/:hash` ridirige a `canonicalUrl` per briefing clickable.
- **Cache disco news-prefetch**: persistente in `<LOGS_DIR>/tts-cache/` (allineato a AdminTtsService dal 28/04).

## 2bis · Knowledge Base

### Pattern architetturali
- **4-priority TTS prefetch**: `news-prefetch.service.ts` ha priorità `urgent` (utente click PLAY) > `high` (top-12 visibili) > `normal` (cron rete-di-sicurezza) > `low` (TUTTI gli altri). Worker single-thread per Ollama deepdive + pool `MAX_CONCURRENT_TTS=1` (abbassato da 3 il 27/04) per Kokoro.
- **News Agency RSS pipeline**: `news-agency.service.ts` cron 30min, 19 international press agencies, traduzione+rewrite italiano via Ollama locale, file-based cache stale-while-revalidate 30-min TTL.
- **Single-leader cron**: `news-agency` + `podcast-intelligence.cron.ts:27` girano SOLO su `TENANT_ID=ws` (commit `d85452e` "cron condivisi girano solo su ws-api — elimina 3x duplicazione per tenant").
- **Kokoro semaforo 2 permessi**: `admin-tts.service.ts:153` `TTS_KOKORO_MAX_CONCURRENT=2`. Era 3 fino al 27/04 16:30 ma con Kokoro che internamente serializza smart-split, 3 in volo significavano chunk1 ~30s, chunk2 ~60s, chunk3 ~90s e fetch sforava budget Node 60s → CB OPEN → outage 5min.
- **Cache disco TTS unified**: `<LOGS_DIR>/tts-cache/` (commit 28/04) — allineato tra `news-prefetch.service.ts:90-110` e `admin-tts.service.ts:94-116`. MAI `/tmp` (volatile su macOS reboot).
- **Honest degradation**: tutti provider TTS open → `status='failed' + reason + provider snapshot`. Niente fallback fittizio.
- **MAX_AUDIO_ATTEMPTS=3**: dopo 3 retry su un articolo, finisce in `failed-permanent` e NON viene più raccolto da catch-up (reset solo via `/news-hub/admin/audio-reset/:id`).
- **Deep-dive lazy ITA 2.5k-4.5k chars**: commit `1939d98` "articolo italiano lungo lazy-generated" — generato on-demand quando utente apre articolo, cached.

### Decisioni storiche
- **2026-04-28 commit `69ebda2`**: `NEWS_PREFETCH_AUDIO_BACKLOG_DISABLED=1` — disabilita cron `audioShortBacklogTick` (2min) e `audioCatchupTick` (5min). Why: flapping ws-api/az-api (HTTP 000 sotto polling SUPERVISOR + 11 restart/giorno watchdog) tracciato a TTS retry storm: quando Kokoro/Orpheus erano down i cron iteravano centinaia di articoli pending/failed promuovendoli a 'failed-permanent' a raffica, saturando event loop nei primi 30-120s post-boot. Fast-path utente (`kickoffTtsForArticle` urgent click) resta operativo.
- **2026-04-28 commit `412dceb`**: `NEWS_PREFETCH_BOOT_KICKOFF_DISABLED=1` — il rientro online del Mac Mini dopo 3 giorni di disconnessione ha generato uno storm: 105 articoli failed-permanent → pending su `az`, 80 short-fallback TTS in coda, 26+ enqueue ad alta priorità in pochi secondi. Ogni restart az-api ripeteva lo storm, saturando connection pool e bloccando `/auth/login`. Backlog viene recuperato dai cron periodici senza burst iniziale.
- **2026-04-27 commit `08f115e`**: pre-warm aggressivo + boot kickoff + auto-recovery providers. `MAX_CONCURRENT_TTS` abbassato 3→1 dopo incidente AZ del 16:03.
- **2026-04-28**: spostata cache disco TTS da `/tmp/valo-radio-cache` (volatile) a `<LOGS_DIR>/tts-cache` (persistente). Override `NEWS_PREFETCH_CACHE_DIR` o `TTS_CACHE_DIR`.
- **2026-04-21 commit `b1bf542`**: chain TTS solo locale/opensource (orpheus → kokoro), no Gemini. `TTS_ALLOW_CLOUD_FALLBACK=0` default.
- **commit `0ec7153`**: M9 — News Hub iperpersonalizzato + Radio Giornale + PWA + Telegram voice (genesi modulo).

### Edge cases noti
- **Mac Mini OFFLINE per >24h**: backlog accumula 100+ articoli pending. Boot post-recovery genera storm — ora gated da `BOOT_KICKOFF_DISABLED`.
- **Kokoro `tts-empty-or-tiny-buffer`**: aggiunto a `PROVIDER_ERROR_PATTERNS` (commit 27/04) — quando Mini era spento e Kokoro in stallo per concorrenza, news-prefetch promuoveva 10 articoli AZ a failed-permanent. Ora pattern auto-resettato al boot.
- **Provider error patterns** (auto-reset al boot): `all-tts-providers-open`, `fetch failed`, `ECONNREFUSED`, `ETIMEDOUT`, `HTTP 5\d{2}`, `HTTP 429`, `tts-empty-or-tiny-buffer`, `empty response`.
- **`BOOT_KICKOFF_MAX_RESET=30`**: limite hard per il reset al boot per tenant (evita thundering herd da 105 articoli).
- **Resolve hash all-zeros**: `0000…` → 200 di test (smoke). Permette health check senza articoli reali.
- **Wrapper `{ briefing: { sections } }`**: parser supporta entrambi `{ sections }` flat e `{ briefing: { sections } }` (commit `1d5d0b6`).
- **TTS_TRACE_LOG_PATH**: log JSONL post-mortem in `/var/log/valoswiss/tts-trace.jsonl` (default in production NODE_ENV).

### Bug ricorrenti
- **Anti-loop deepdive qwen3.5**: prima della migrazione qwen3.6 (commit `8f86e09`), qwen3.5 ripeteva l'ultimo paragrafo 6x. Workaround: prompt anti-drift + `injectParagraphBreaks`.
- **Gemma4 timeout su Mac mini**: commit `3476c57` "torna a qwen3.5 (gemma4 timeout sul Mac mini)" — gemma4 non riesce a girare a velocità sufficiente su Mini in concorrenza con altri carichi.
- **Date parser italiano**: commit `c8885de` "parser data riconosce formato italiano DD mmm HH:MM".
- **`pm2 restart --update-env` no-op**: stesso problema del briefing — env nuove non caricate. Serve `pm2 delete + pm2 start --update-env` o `safe-deploy.sh`.
- **News empty page**: commit `1658b57` "elimina pagine vuote — non sovrascrivere cache buona con feed vuoto".
- **Prisma `not:null` filter incompatible**: commit `5edec44` "rimuovi filtro Prisma not:null incompatibile con String?".

### RAM/cold-load gotcha Mini (lezione 2026-04-30)

- **Mini M4 Pro 64GB satura** quando `qwen3.6:27b` 17GB + `glm-4.7-flash` 19GB + LocalAI bundle (gemma-4-e4b-it 5GB + qwen3-vl-8b 8GB + qwen3-embedding-0.6b 1GB) sono tutti caldi. Con `news-rewrite-headline` mappato su `@qwen-general` (qwen3.6:27b) e Mini saturo, le chiamate timeout 30s e i titoli restano **inglesi** in DB (rewriteStatus='failed').
- **Sintomo prod (Azimut 30-04 mattina)**: https://genesis.valoswiss.com/news-hub mostrava "Oil jumps to highest price since 2022..." (BBC Business, 12h fa) con bandiera 🇮🇹. Log API: `[NewsRewriterService] rewrite cmolo6pv8003i4hvl5mm4la1k failed: Ollama call failed: This operation was aborted` × N articoli. Test live: `curl http://127.0.0.1:11434/api/generate -d '{"model":"gemma4:e4b",...}'` → HTTP 503 (cold-load timeout 30s).
- **Mitigation 30-04 (PM)**: 
  1. Switch `news-rewrite-headline` + `news-rewrite-summary` da `@qwen-general` → **`@nemotron-nano`** (`nemotron-nano:8b` ~5GB, NVIDIA Llama-3.1-Nemotron-Nano-8B Q4 multilingual nativo, già residente Mini).
  2. Bump `timeoutMs` task config da 30s → 60s (headline) e 45s → 75s (summary) per cold-load tolerance.
  3. Rimuovere `qwen3-vl-8b-instruct` da `localai-mini` (Wave 4 vision = magic-upload non in production attiva, libera 8GB).
  4. (Future) Wave 1.5: `nvidia_llama-3.1-nemotron-nano-4b-v1.1` LocalAI 3GB ancora più snello (download in corso 30-04 sera).
- **Ref commits**: `f1c3def` (placeholder), `~/.claude/plans/fai-piano-per-ottimizzare-whimsical-marshmallow.md`.

### Image fallback policy 2026-04-30

- **Direttiva utente**: "immagini pertinenti generic OK, no foto specifica articolo. Anche se le notizie fossero prive di immagine ne aggiungiamo una che contenga qualcosa che richiama l'articolo".
- **Tier-5 LocalAI Z-Image-Turbo on-prem**: `apps/api/src/modules/news-hub/news-image-localai.helper.ts` — quando cascade publisher (RSS/og:image/twitter/json-ld/body-img) fallisce **e** flag `NEWS_IMAGE_GENERATE_FALLBACK=1` **e** modello `Z-Image-Turbo` presente in `/v1/models`, genera 1024x576 PNG → resize sharp 1200x675 WebP q80 → cache disco standard (`getCachePath(contentHash)`, shard primi 2 char).
- **Privacy + cost**: on-prem MPS Apple Silicon, **$0**, MIFID/FINMA compliant. Nessun upload publisher data esterno. Solo title/keyword nei prompt.
- **Prompt**: `"professional news editorial illustration, clean modern photographic style, soft natural lighting, depth of field, vibrant but tasteful colors, {3-4 keyword extracted}, no text, no watermark, no signature, no logo, no human face close-up"`.
- **Provenance enum**: `localai-zimage-turbo` (aggiunto a `ImageProvenance`).
- **Fallback safety**: se Z-Image-Turbo non disponibile (404 modello, LocalAI down) → `imageStatus='failed'` come oggi → fronten

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