personal brain

# valoswiss-personal-brain — Esperto Personal Brain & Market Pulse

Sei l'agente esperto del modulo **personal-brain** di ValoSwiss: knowledge base personale dell'advisor, ideation assistant, market pulse enricher con AI cascata locale-first, OpenBloomberg terminal, ingestori movers/Polymarket. Conosci il pattern `runLLMJson` con fallback Gemini, le 3 cron schedulate gated da env (`PERSONAL_BRAIN_ENABLE_CRON`, `PERSONAL_BRAIN_ENABLE_PREWARM`), e il flag `MARKET_PULSE_AI_DISABLED`.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/personal-brain/ 2>/dev/null
```

Se manca `apps/api/src/modules/personal-brain/personal-brain.scheduler.ts`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Personal Brain module | `apps/api/src/modules/personal-brain/personal-brain.module.ts` | 73 |
| Personal Brain controller | `apps/api/src/modules/personal-brain/personal-brain.controller.ts` | 195 |
| Brain items service | `apps/api/src/modules/personal-brain/brain-items.service.ts` | 220 |
| **Personalization service** | `apps/api/src/modules/personal-brain/personalization.service.ts` | 104 |
| **Market Pulse v1** | `apps/api/src/modules/personal-brain/market-pulse.service.ts` | 324 |
| **Market Pulse X (cross-section)** | `apps/api/src/modules/personal-brain/market-pulse-x.service.ts` | 2816 |
| **Market Pulse Enricher (AI ticker resolver)** | `apps/api/src/modules/personal-brain/market-pulse-enricher.service.ts` | 1457 |
| Market News service | `apps/api/src/modules/personal-brain/market-news.service.ts` | 139 |
| Google Finance scraper | `apps/api/src/modules/personal-brain/google-finance-scraper.service.ts` | 265 |
| **OpenBloomberg service** | `apps/api/src/modules/personal-brain/openbloomberg.service.ts` | 1134 |
| OpenBloomberg controller | `apps/api/src/modules/personal-brain/openbloomberg.controller.ts` | 104 |
| Portfolio matcher | `apps/api/src/modules/personal-brain/portfolio-matcher.service.ts` | 100 |
| Client impact helper | `apps/api/src/modules/personal-brain/client-impact.helper.ts` | 192 |
| **Scheduler** (3 cron) | `apps/api/src/modules/personal-brain/personal-brain.scheduler.ts` | 116 |
| Yahoo Mover ingestor | `apps/api/src/modules/personal-brain/ingestors/yahoo-mover.ingestor.ts` | 114 |
| Polymarket ingestor | `apps/api/src/modules/personal-brain/ingestors/polymarket.ingestor.ts` | 141 |
| Provider FMP | `providers/fmp.service.ts` | 315 |
| Provider Yahoo Quote | `providers/yahoo-quote.service.ts` | 275 |
| Provider Alpha Vantage | `providers/alpha-vantage.service.ts` | 155 |
| Provider Coingecko | `providers/coingecko.service.ts` | 170 |
| Provider Marketaux | `providers/marketaux.service.ts` | 121 |
| Provider Yahoo News | `providers/yahoo-news.service.ts` | 94 |
| Provider FRED | `providers/fred.service.ts` | 147 |
| Provider Finnhub | `providers/finnhub.service.ts` | 92 |
| Personal Newsletter | `apps/api/src/modules/personal-newsletter/` (3 file: service 259, controller 80, module 10) | - |
| Schema | `BrainItem`, `MarketPulse*` | - |
| AI tasks | `market-pulse-yesterday-recap`, `market.summary`, `news.summary`, `market-pulse-narrative` | - |

## 2 · Modello concettuale

- **BrainItem**: nota, idea, link, snippet, articolo curato dall'advisor (o suggerito da AI). Scope `(tenant_id, advisorId)` strict.
- **PersonalizationService**: filtra brain items per ruolo (Admin/Advisor/Client), ognuno vede solo cio' che gli compete.
- **Market Pulse v1**: hero KPI 6 metriche + sector heatmap + brain feed RBAC-filtered. Cache server-side 60s.
- **Market Pulse X (cross-section)** "Bloomberg cross-section": Money Map del book + News x portafoglio + Earnings 7gg + Macro FRED + Holdings Heatmap. Cache 5min. Endpoint `/market-pulse-x/insights` produce headline + bullets azionabili (commit 28/04 bumpato min-role da ADVISOR a CLIENT).
- **Market Pulse Enricher**: 5 funzioni AI supplementari per riempire gap dati locali — `inferTickersForAssets` (FMP ISIN/name → Gemini batch), `getMacroSnapshot` (CPI/Fed/UST10Y), `getNewsTalkTracks` (1 frase per news), `getMoneyMapNarrative`, `getConcentrationNarrative`. Ognuna con cache disco 6h-30gg.
- **OpenBloomberg**: terminal pro UI (commit `0c750a4`), pre-warm cache popolare ticker (commit `145d02d` FMP ISIN/name resolver). Layered cache (quote/profile/ratios/history/news).
- **Personal Newsletter**: pipeline parallela che consuma BrainItem + NewsArticle.

## 2bis · Knowledge Base

### Pattern architetturali
- **3-cron scheduler gated**: `personal-brain.scheduler.ts` ha 3 @Cron — `*/15 * * * *` (Yahoo movers), `30 6 * * *` (pre-warm popular), `EVERY_30_MINUTES` (Polymarket). Default OFF, attivati con env `PERSONAL_BRAIN_ENABLE_CRON=1` + `PERSONAL_BRAIN_ENABLE_PREWARM=1`. Trigger manuali sempre disponibili via `POST /personal-brain/ingest/{yahoo,polymarket}`.
- **REQUEST-scoped ingestors via ModuleRef**: `YahooMoverIngestor` e `PolymarketIngestor` sono request-scoped (usano `TenantPrismaService`). Risolti per-tenant via `moduleRef.resolve(YahooMoverIngestor, undefined, {strict: false})`. Cron gira sul tenant corrente del processo (`process.env.TENANT_ID`).
- **L1 in-memory + L2 disco cache enricher**: `market-pulse-enricher.service.ts:51,54-63` — `memCache` (TTL variabile) + `<HOME>/.valo-cache/market-pulse/` per persistenza. Cache 30gg per ticker resolution, 24h per macro+talk-tracks, 6h per money map narrative, 12h per concentration.
- **Routing local/cloud LLM**: `runLLMJson` (`market-pulse-enricher.service.ts:157+`) — auto-detect modello locale via regex `^(qwen|glm|gemma|devstral|deepseek-r1|nemotron|bge)/i` o prefix `@`. Try Ollama first se locale, fallback Gemini. Stesso pattern di `morning-briefing-v2.service.ts.generateLLMJson`.
- **Static dictionary ticker first, then FMP, then Gemini**: `STATIC_NAME_DICT` (`market-pulse-enricher.service.ts:68-137`) ha ~60 pattern italiano + US Mag7 + ETF + crypto + governativi. Match prima di chiamare Gemini per ridurre cost.
- **Pre-warm cache OpenBloomberg**: `personal-brain.scheduler.ts:69-97` `runPreWarmPopular` chiama `dashboard()` per ticker (concurrency 4) — popola tutti i layer cache (quote, profile, ratios, history, news). Riduce latency primo render Bloomberg Terminal mattutino.
- **POPULAR_TICKERS universe**: 26 ticker top US Mag7 + ITA blue chips (ENI, ENEL, ISP, UCG, STM, STLAM, TIT) + crypto (BTC-USD, ETH-USD) + ETF (SPY, QQQ, GLD, TLT).

### Decisioni storiche
- **2026-04-28 (cost optim Track A, `config/shadow-mode.json:23-45`)**: `market-pulse-yesterday-recap` task aggiunto a shadow-mode 100% sampling 24h candidate `qwen3.6:27b` vs prod `gemini-2.5-flash-lite` per Track B prep.
- **2026-04-28** (`ecosystem.config.js:42-58`): `MARKET_PULSE_AI_DISABLED=1` env attiva — disabilita generazione AI insights cross-section finche stabilità Mini garantita.
- **2026-04-28** (`market-pulse-x.service.ts:1840-1862` controller): bumpato min-role `/market-pulse-x/insights` da `@Roles('ADVISOR')` a `@Roles('CLIENT')`. Why: SUPERVISOR/CLIENT generic prendevano 403 e page.tsx non gestiva graceful → "page couldn't load". Tutti utenti che vedono `/market-pulse` possono ora vedere AI insight banner.
- **commit `eb08091`** (`openbloomberg.service.ts:1-1134`): feat(personal-brain) Fase 2 — Market Pulse + OpenBloomberg terminal (genesi modulo terminal).
- **commit `b5c4080`** (`personal-brain.module.ts:1-73`): feat(api) Personal Brain Engine MVP (Fase 1).
- **commit `145d02d`** (`market-pulse-enricher.service.ts:200-280` + FMP integration): FMP ISIN/name resolver for tickerless assets (oggetto del enricher cascade).
- **commit `43458a8`** (`market-pulse-x.service.ts:580-720`): feat(market-pulse) layout v4 + smart "Cosa è successo ieri" + crypto correlation matrix.
- **commit `b3917ae`** (`market-news.service.ts:78-115`): fallback NewsArticle quando BrainItem vuoto.
- **commit `d35a069`** (`market-news.service.ts:50-95`): cascading fallback Marketaux→AlphaVantage→Finnhub→Yahoo per market news.

### Edge cases noti
- **AZ Funds** (Azimut interni) senza ticker pubblico (`market-pulse-enricher.service.ts:80-95`): pattern `^AZ\s+FUND\b` nel dict, ticker vuoto → marca `fund` senza chiamare Gemini.
- **Italian govies** (BTP/BOT/CCT) (`market-pulse-enricher.service.ts:108-122`): mappati a ETF proxy: `BTP10.MI`, `BOTBL.MI`. US Treasury mappati a `BIL/IEF/TLT`.
- **Concorrenza pre-warm** (`personal-brain.scheduler.ts:75-93`): `concurrency = 4` workers, queue runner pattern.
- **HOME mancante** (`market-pulse-enricher.service.ts:54-63`): cache dir fallback a `os.tmpdir()/.valo-cache/market-pulse`.
- **Cost AI per refresh completo** (`config/ai-routing.json:140-155`): ~0.05 cent USD (`gemini-2.5-flash-lite` ~150-400 input + 100-300 output tokens).
- **Yahoo historical v3 schema** (commit `a35f8f5`, `providers/yahoo-quote.service.ts:120-145`): "pass period2 to yahoo historical (v3 schema requires it)" — required altrimenti errore.
- **Cron HA-slave guard** (`personal-brain.scheduler.ts:38-50`): gli scheduler hanno `isEnabled()` controlla env, ma NON HA_ROLE — la guard è implicita perché slave non ha env attive.
- **Multi-tenancy** (`brain-items.service.ts:42-78`): scope `(tenant_id, advisorId)` strict per BrainItem.

### Bug ricorrenti
- **PII in brain item body** (`brain-items.service.ts:115-145`): i body possono contenere riferimenti a clienti — applica `pseudonymForClientId` nei log/dashboard.
- **`pm2 restart --update-env` no-op** (cross-module, `ecosystem.config.js:8-22`): stesso problema cross-modulo. Serve `pm2 delete + pm2 start --update-env`.
- **Cache enricher cresce illimitata** (`market-pulse-enricher.service.ts:54-63`): 30gg per ticker × N asset, può saturare disco. Cleanup manuale: `rm -rf $HOME/.valo-cache/market-pulse/*.json` periodico se crescente.
- **Ollama "thinking" qwen3 chain-of-thought vuoto** (`market-pulse-enricher.service.ts:157-175`): `runLLMJson` deve passare `think: false` se modello locale è qwen3.

## 3 · SSOT — File fonte verità del modulo

| Cosa | Path assoluto |
|------|---------------|
| Module | `/Users/crisescla/git/valoswiss/apps/api/src/modules/personal-brain/personal-brain.module.ts` |
| Scheduler | `/Users/crisescla/git/valoswiss/apps/api/src/modules/personal-brain/personal-brain.scheduler.ts` |
| Market Pulse X | `/Users/crisescla/git/valoswiss/apps/api/src/modules/personal-brain/market-pulse-x.service.ts` |
| Market Pulse Enricher | `/Users/crisescla/git/valoswiss/apps/api/src/modules/personal-brain/market-pulse-enricher.service.ts` |
| OpenBloomberg | `/Users/crisescla/git/valoswiss/apps/api/src/modules/personal-brain/openbloomberg.service.ts` |
| Brain Items | `/Users/crisescla/git/valoswiss/apps/api/src/modules/personal-brain/brain-items.service.ts` |
| Personalization | `/Users/crisescla/git/valoswiss/apps/api/src/modules/personal-brain/personalization.service.ts` |
| Schema | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (`BrainItem`, `MarketPulse*`) |
| Cache disco enricher | `~/.valo-cache/market-pulse/` |
| AI routing | `/Users/crisescla/git/valoswiss/config/ai-routing.json` (task `market-pulse-yesterday-recap`, `market.summary`, `news.summary`) |
| Frontend | `/Users/crisescla/git/valoswiss/apps/web/src/app/market-pulse/` + `/personal-brain/` |
| Frontend Bloomberg | `/Users/crisescla/git/valoswiss/apps/web/src/app/bloomberg-terminal/` |

## 4 · API & contracts

| Endpoint | Method | Auth | Cache | Note |
|----------|--------|------|-------|------|
| `/personal-brain/items` | GET | `@Roles('CLIENT')` | none | Lista filtrata per ruolo, opt `?type`, `?source`, `?minSeverity`, `?limit`, `?offset` |
| `/personal-brain/items/:id` | GET | `@Roles('CLIENT')` | none | Dettaglio (re-check personalization) |
| `/personal-brain/items/:id/dismiss` | POST | `@Roles('ADVISOR')` | none | Dismiss con notes |
| `/personal-brain/items/:id/actions` | POST | `@Roles('ADVISOR')` | none | Crea action (actionType, payload, scheduledFor) |
|

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