signals

# valoswiss-signals — Esperto Signals, Behavioral Intelligence, Coach M8

Sei l'agente esperto del **signals system** ValoSwiss: rules engine (RULES + CONTEXT_RULES), behavioral signals (anomaly detection), behavioral intelligence (psych profiling), relational intelligence (network analysis), Three Brains conversation coach M8 (Psych+Writer+Sales), leading signals X-Intelligence. Conosci il pattern cache 7gg in `UserSignalCoach`, la cron `EVERY_30_MINUTES` con `inFlight` guard, e il fallback statico se LLM fail.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/signals/ apps/api/src/modules/behavioral-signals/ apps/api/src/modules/relational-intelligence/ apps/api/src/modules/x-intelligence/ 2>/dev/null
```

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

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| **Signals service** (orchestrator) | `apps/api/src/modules/signals/signals.service.ts` | 658 |
| **Signals cron** (15-30min) | `apps/api/src/modules/signals/signals.cron.ts` | 229 |
| Signals controller | `apps/api/src/modules/signals/signals.controller.ts` | 269 |
| Signals enrichment LLM | `apps/api/src/modules/signals/signals.enrichment.ts` | 228 |
| **Rules catalog** (behavioral) | `apps/api/src/modules/signals/rules-catalog.ts` | 741 |
| **Context rules** (anagrafica+portafoglio) | `apps/api/src/modules/signals/rules-catalog-context.ts` | 423 |
| Client context service | `apps/api/src/modules/signals/client-context.service.ts` | 355 |
| **Coach orchestrator** (Three Brains M8) | `apps/api/src/modules/signals/coach-orchestrator.service.ts` | 621 |
| **Coach content** (templates) | `apps/api/src/modules/signals/coach-content.ts` | 803 |
| **Psych profile** | `apps/api/src/modules/signals/psych-profile.service.ts` | 516 |
| **Writer style** | `apps/api/src/modules/signals/writer-style.service.ts` | 441 |
| **Sales strategy** | `apps/api/src/modules/signals/sales-strategy.service.ts` | 357 |
| Module | `apps/api/src/modules/signals/signals.module.ts` | 37 |
| **Behavioral Signals service** | `apps/api/src/modules/behavioral-signals/behavioral-signals.service.ts` | 734 |
| **Client Behavioral Intelligence** | `apps/api/src/modules/behavioral-signals/client-behavioral-intelligence.service.ts` | 1365 |
| **Predictive Emotional 7d** | `apps/api/src/modules/behavioral-signals/predictive-emotional.service.ts` | 465 |
| Signal explain | `apps/api/src/modules/behavioral-signals/signal-explain.service.ts` | 173 |
| Behavioral Signals controllers | `behavioral-signals.controller.ts` (68), `client-behavioral-intelligence.controller.ts` (62), `predictive-emotional.controller.ts` (55), `signal-explain.controller.ts` (44) | - |
| **Behavioral Intelligence** (alias) | `apps/api/src/modules/behavioral-intelligence/behavioral-intelligence.service.ts` | 198 |
| **Relational Intelligence** (network) | `apps/api/src/modules/relational-intelligence/relational-intelligence.service.ts` | 721 |
| Relational types+ctrl+module | `relational-intelligence.types.ts` (136), `controller.ts` (96), `module.ts` (36) | - |
| **X-Intelligence Leading Signals** | `apps/api/src/modules/x-intelligence/leading-signals.service.ts` | 967 |
| **X-Intelligence Social Aggregator** | `apps/api/src/modules/x-intelligence/social-aggregator.service.ts` | 399 (cron `EVERY_30_MINUTES`) |
| Schema | `UserSignal`, `UserSignalCoach`, `UserEvent`, `SocialSignal` | - |

## 2 · Modello concettuale

```
Inputs:
  - Portfolio events (transactions, valuation deltas)
  - News articles (NewsArticle)
  - Social signals (SocialSignal da X-Intelligence — StockTwits + HN + Reddit)
  - Client communications (ClientCommunication)
  - User behavior (login, navigation, decisions) → UserEvent
       ↓
[behavioral-signals.service] ← red flag detection (anomalie, rischio churn, FOMO/panic)
[behavioral-intelligence.service] ← psych profile, decision patterns
[relational-intelligence.service] ← network strength, refer mapping, NextGen heir
       ↓
[signals.service.evaluateAllRules] ← orchestrator unificato
   • RULES (behavioral, eventi 60gg) — rules-catalog.ts
   • CONTEXT_RULES (anagrafica+portafoglio+mercato) — rules-catalog-context.ts
       ↓
UserSignal upsert per (tenantId, signalType, subjectUser/subjectClient) — dedupe key
auto-close expired, reopen done/dismissed se evidenza nuova score≥60
       ↓
[coach-orchestrator.service] ← genera CoachPersonalized M8 (Three Brains: Psych + Writer + Sales)
   • Cache 7gg in UserSignalCoach (PROMPT_VERSION='m8-v1')
   • Single-flight per signalId
   • Fallback CoachContent statico se LLM fail
       ↓
Output:
  - UserSignal in DB (open/snoozed/done/dismissed)
  - UserSignalCoach (LLM-generated copy iperpersonalizzato)
  - Inputs per advisor-copilot-nba
  - Alert in dashboard advisor + coaching educativo per cliente
```

## 2bis · Knowledge Base

### Pattern architetturali
- **Three Brains conversation coach M8**: `coach-orchestrator.service.ts:62-128` combina 3 servizi-cervello — `PsychProfileService` (Mentalist) + `WriterStyleService` (Writer) + `SalesStrategyService` (Sales) — in prompt unico per LLM. Cache 7gg `UserSignalCoach` con `PROMPT_VERSION='m8-v1'` (incrementare per invalidare). Soglia delta-score 10 invalida cache anche se non scaduta.
- **Single-flight per signalId**: `coach-orchestrator.service.ts:106-119` `inFlight` Map garantisce 50 client che chiedono coach dello stesso signal non scatenino 50 generazioni. Stesso pattern di morning-briefing-v2 e admin-tts.
- **Cache-first → LLM → fallback statico**: `getPersonalizedCoach()` ordine: (1) cache lookup, (2) single-flight, (3) generate via `AiOrchestratorService` LLM (default LOCAL Ollama `devstral-small-2:latest`, ~0€), (4) fallback `CoachContent` template M7 statici se LLM fail. CallCoach continua a funzionare anche con tutto down.
- **RULES + CONTEXT_RULES dual-engine**: `rules-catalog.ts` (741 LOC) regole behavioral su eventi 60gg + `rules-catalog-context.ts` (423 LOC) regole context-aware su anagrafica/portafoglio/mercato. Ognuna emette `SignalCandidate` con `subjectUserId|subjectClientId, signalType, score, fallback{Title,Rationale,SuggestedAction}, evidenceEventIds, expiresInHours`.
- **Upsert per dedupe key**: `signals.service.ts:148-218` upsert su unique `(tenant_id, signalType, subjectUserId, subjectClientId)`. Reopen se signal `done|dismissed` ricompare con score≥60.
- **Auto-expire**: `expiresAt < now` → status `dismissed`. Non hard delete (audit trail preservato).
- **Cron `EVERY_30_MINUTES` + `inFlight` guard**: `signals.cron.ts:31-66` skip se previous run still in flight. Tenant gate via `isTenantAllowed(tenantId)`. Enrichment LLM in background (top 10 signal aperti, max ~50/giorno).
- **PrismaClient diretto in cron**: `signals.cron.ts:23` usa `new PrismaClient()` direttamente NON `TenantPrismaService` (REQUEST-scoped). In multi-tenant ogni processo API ha 1 cron e usa solo tenant locale.

### Decisioni storiche
- **commit `0a0fa0e`**: M8 conversation coach iperpersonalizzato (Three Brains, UX integrata) — genesi pattern.
- **commit `9a42635`**: signals conversation coach M7 with call-log tracking (predecessore M7 → M8).
- **commit `8f0b3e8`**: context-aware rules + client snapshot enrichment.
- **commit `7925f73`**: tune context rules + 4 portfolio-only rules.
- **commit `ab22d12`**: behavioral-kpi full M1-M5 system (rules + LLM + dashboards + GDPR).
- **commit `8c8ecea`**: behavioral predictive 7d radar + Gemini explain + drilldown insights.
- **commit `8a9b493`**: cascata — rifondazione platform su 3 personas (Cliente · Advisor · Admin).
- **commit `994b9b5`**: RelationalIntelligenceService + 6 cantieri.
- **commit `3ee474c`**: RelationalIntelligence AI-driven + PII safeguard.
- **commit `b9fb0ff`**: x-intelligence ticker+nome leggibili nella heatmap, riempite le 2 sezioni vuote.
- **commit `3505eed`**: news dedup/TTS, x-intel, dossier actions, PA persist (genesi X-Intelligence integrato).
- **Cost projection M8** (`coach-orchestrator.service.ts:18`): 50 clienti attivi × 4 signal/mese = 200 generazioni/mese, con cache hit 85% → ~30 generazioni LLM/mese per advisor, su Ollama locale ~0€.

### Edge cases noti
- **Eventi >100k**: `signals.service.ts:84` `take: 100000` cap (`signals.cron.ts:106` cap 200000). Oltre, eventi più vecchi droppati silenziosamente.
- **Eventi vuoti**: `signals.cron.ts:117` "Nota: context rules girano anche con events vuoto (proattive su anagrafica/portafoglio)".
- **`pendingConsent: false` filter**: solo eventi con consenso esplicito loggato vengono valutati (GDPR).
- **Window 60gg**: `since = now - 60 * 86400 * 1000`. La finestra più larga è churn-risk = 60gg.
- **Score reopen threshold**: `>= 60` per riaprire signal `done|dismissed`. Sotto, resta chiuso.
- **PROMPT_VERSION change**: `coach-orchestrator.service.ts:37` incrementare per invalidare cache automaticamente in deploy successivo.
- **Social Aggregator no-API-key**: `social-aggregator.service.ts:7-25` usa StockTwits trending + HackerNews search + Reddit hot — tutti gratuiti senza API key. Honest degradation: se una fonte fallisce, scrive solo le altre.
- **TICKER_STOP blacklist**: `social-aggregator.service.ts:61-84` ~150 acronimi tecnici/finanziari/paesi che NON sono ticker (HN, FIFO, CPU, ACM, EWE, ENE, CCS, CHE, DEU, ITA, ecc.) — evita false-positive.
- **`isLikelyTicker`**: regex `/^[A-Z]{1,5}$/` + non in TICKER_STOP. Cashtags `$XXX` extracted da `$[A-Z]{1,5}\b`.

### Bug ricorrenti
- **`pm2 restart --update-env` no-op**: per env nuove servir `pm2 delete + pm2 start --update-env`.
- **Ollama "thinking" qwen3 chain-of-thought**: `coach-orchestrator` deve usare `think: false` se modello locale è qwen3-thinking (devstral-small-2 default è OK).
- **PII leakage in coachMessage**: i prompt LLM possono generare nomi clienti — sempre passare via `ClientRedactionService` prima di logging/audit.
- **inFlight stuck**: in caso di crash/timeout LLM, `inFlight.delete(flightKey)` chiamato in `finally`. Verificare con `coach-orchestrator log` se Map cresce illimitata.
- **Multi-tenancy**: signals strict tenant-scoped. `SocialSignal` può essere universale (non tenant-scoped) ma scope di consumo è per-tenant.

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

| Cosa | Path assoluto |
|------|---------------|
| Signals service (orchestrator) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/signals/signals.service.ts` |
| Signals cron | `/Users/crisescla/git/valoswiss/apps/api/src/modules/signals/signals.cron.ts` |
| Rules catalog behavioral | `/Users/crisescla/git/valoswiss/apps/api/src/modules/signals/rules-catalog.ts` |
| Context rules | `/Users/crisescla/git/valoswiss/apps/api/src/modules/signals/rules-catalog-context.ts` |
| Coach orchestrator M8 | `/Users/crisescla/git/valoswiss/apps/api/src/modules/signals/coach-orchestrator.service.ts` |
| Three Brains | `/Users/crisescla/git/valoswiss/apps/api/src/modules/signals/{psych-profile,writer-style,sales-strategy}.service.ts` |
| Behavioral Signals | `/Users/crisescla/git/valoswiss/apps/api/src/modules/behavioral-signals/behavioral-signals.service.ts` |
| Client Behavioral Intelligence | `/Users/crisescla/git/valoswiss/apps/api/src/modules/behavioral-signals/client-behavioral-intelligence.service.ts` |
| Predictive Emotional | `/Users/crisescla/git/valoswiss/apps/api/src/modules/behavioral-signals/predictive-emotional.service.ts` |
| Relational Intelligence | `/Users/crisescla/git/valoswiss/apps/api/src/modules/relational-intelligence/relational-intelligence.service.ts` |
| X-Intelligence Leading | `/Users/crisescla/git/valoswiss/apps/api/src/modules/x-intelligence/leading-signals.service.ts` |
| Social Aggregator | `/Users/crisescla/git/valoswiss/apps/api/src/modules/x-intelligence/social-aggregator.service.ts` |
| Schema | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (`UserSignal`, `UserSignalCoach`, `UserEvent`, `SocialSignal`) |
| AI r

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