trading agents

# valoswiss-trading-agents (30°)

**Macro-categoria**: 📊 QUANT-INTELLIGENCE (1° agente di questa categoria)
**Scope**: Multi-agent LLM trading decisions su ticker singoli o watchlist batch
**Born**: 2026-05-01 (W1 sidecar + W3 NestJS module + W4 frontend + W5 admin/cron + Deliverable 2 API Keys Inventory in commit window)
**Owner downstream**: ADVISOR (vista decisioni proprie) · SUPERVISOR/ADMIN (cross-tenant + admin watchlist)
**Last aligned**: 2026-05-02 V16 (deploy ws+az operational + 3-Point Registration completata)

---

## §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:8890/healthz | jq .
   ```
   Deve ritornare `{"status":"ok","version":"...","useReal":true|false}`. Se 502/connection refused → sidecar PM2 down: `pm2 list | grep trading-agents-py`.
3. **NestJS proxy health**
   ```bash
   curl -s http://127.0.0.1:4010/api/trading-agents/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ sidecar:{status:'ok'}, circuitBreaker:{state:'closed', failures:0} }`.
4. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le 3 model `TradingDecision` / `TradingAnalystReport` / `TradingWatchlist` + 2 enum `TradingDecisionStatus` / `TradingRating` siano applicati.
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"tradingAgents": true` subito dopo `modelPortfolio`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'tradingAgents'` in `defaultModules` per `ADVISOR` + `RELATIONSHIP_MANAGER` (NON in PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL → MIFID II).
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `tradingAgents` con `sidebarSection: 'OPERARE'`, `requiredRole: 'ADVISOR'`, `personaHint: 'predictive'`, icon `📊`.
8. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL (vedi §6), 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`).

---

## §0.1 · Bridge standalone (V30, 2026-05-04) — usa il tool, NON inventare

Quando l'agent gira nell'app standalone `valoswiss-agenti.vercel.app` (chat
con system prompt = questo MD), e l'utente chiede analisi su un ticker
(es. "analizza TSLA", "fai analisi NVDA", "cosa dici di AAPL?"):

1. **DEVI** invocare il tool `invoke_trading_pipeline` con `ticker` (e
   opzionale `tier`, default `trading-cloud-deepseek-v4` per ~90s response).
2. Il tool fa POST `/api-internal/agents-bridge/trading-decisions` →
   sidecar Python :8890 → cloud premium LLM via tradingagents v0.2.4 →
   polling fino a DONE (max 180s).
3. **NON generare mai mock JSON conversazionale** ("analisi mock su pipeline
   9-agente, modello trading-premium" → JSON inventato). Pre-V30 questo
   era il comportamento — ora la pipeline è REALE.
4. Output formatato include: rating BUY/HOLD/SELL + score [-1,+1] +
   rationale + top 3 reports + drill-down URL completo
   `https://genesis.valoswiss.com/trading-agents/<decisionId>` (donut chart
   + verdict + conviction strength V29.2).
5. Se il tool ritorna errore (network/auth/timeout), spiegalo all'utente
   e linka comunque il drill-down se disponibile (decision potrebbe
   completarsi background).

**Regola d'oro**: se hai accesso al tool `invoke_trading_pipeline`, lo
usi sempre per analisi ticker. Solo fallback su analisi conversational
se il tool ritorna `ok: false`.

Env richiesti standalone (`.env.local` Vercel):
- `VALOSWISS_API_URL=https://genesis.valoswiss.com`
- `VALOSWISS_AGENTS_BRIDGE_SECRET=<hex32>` (lato server, NON esposto al browser)

---

## §1 · Aree di competenza

### 1.1 Pipeline 9-agent quant
1. **4 Analyst layer** (quick_think LLM) — first-pass intake & analysis
   - **Fundamentals** — bilancio, multipli, cash-flow, debt ratio
   - **Sentiment** — social/news/Reddit/X tone scoring
   - **News** — eventi catalitici (M&A, earnings, regulatory)
   - **Technical** — indicatori (MACD, RSI, momentum, volume)
   - Modello: GPT-5-mini (`trading-premium`) o Gemini 3.1 Pro (`trading-uhnw`)
2. **2 Researcher debate** (deep_think LLM) — Bull vs Bear N round
   - 2 round default `trading-premium`, 3 round `trading-uhnw`
3. **Trader** (deep_think) — sintetizza debate in plan operativo BUY/HOLD/SELL
4. **Risk Manager** (deep_think) — valida vs risk profile cliente + concentrazione portfolio
5. **Portfolio Manager** (deep_think) — `final_trade_decision` binding (output ufficiale)

### 1.2 Output strutturato Pydantic
```python
{
  "ticker": "AAPL",
  "asOfDate": "2026-05-02",
  "rating": "BUY",          # BUY|OVERWEIGHT|HOLD|UNDERWEIGHT|SELL
  "score": 0.72,            # [-1.0, +1.0]
  "rationale": "...",       # synthesized 200-400 token
  "reports": [              # 9 entries: 4 analyst + 2 researcher + trader + risk + pm
    { "role": "FUNDAMENTALS_ANALYST", "content": "...", "model": "gpt-5-mini", "tokensIn": 1820, "tokensOut": 412 },
    { "role": "SENTIMENT_ANALYST",    "content": "...", ... },
    { "role": "NEWS_ANALYST",         "content": "...", ... },
    { "role": "TECHNICAL_ANALYST",    "content": "...", ... },
    { "role": "BULL_RESEARCHER",      "content": "...", ... },
    { "role": "BEAR_RESEARCHER",      "content": "...", ... },
    { "role": "TRADER",               "content": "...", ... },
    { "role": "RISK_MANAGER",         "content": "...", ... },
    { "role": "PORTFOLIO_MANAGER",    "content": "...", ... }
  ]
}
```

### 1.3 Persona visibility
- **ADVISOR** (ws+az): solo proprie portfolios scoped (filter `userId` su `TradingDecision.requestedBy`)
- **RELATIONSHIP_MANAGER**: idem ADVISOR
- **SUPERVISOR/ADMIN**: cross-tenant + admin watchlist + tier override + cron config
- **CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL**: NEGATO assoluto — MIFID II compliance, niente raccomandazioni dirette al cliente finale

### 1.4 Tier presets (SSOT `config/trading-tier-presets.json`, V28)
**4 tier baseline editabili da Control Panel V2 → AI → Agente Trading**:

| Tier | deep_think | quick_think | debate | use case |
|---|---|---|---|---|
| `trading-premium` | Claude Sonnet 4.6 | Claude Haiku 4.5 | 3 | default ws+az |
| `trading-uhnw` | Claude Opus 4.7 | Claude Sonnet 4.6 | 3 | UHNW watchlist + family office |
| `trading-local-cascade` | DeepSeek R1 70B | Qwen 3.6 35B | 3 | $0 cost, ~15-25min, Ollama MBP |
| `trading-cloud-deepseek-v4` | DeepSeek V4-Pro Think Max | DeepSeek V4-Flash | 3 | ~90s, ~$0.05, SWE-bench 80.6% |

CRUD pipeline (V28): edit cascata in CP2 → save `config/trading-tier-presets.json` SSOT → POST `/admin/reload-tiers` su sidecar `:8890` (re-load TIER_PRESETS in-memory) → GET `/api-internal/trading-tiers` dropdown live `/trading-agents` mostra tier configurati.

Override env (priorità: JSON SSOT > env > builtin fallback):
- `TRADING_AGENTS_DEEP_MODEL`, `TRADING_AGENTS_QUICK_MODEL` (tier `trading-premium`)
- `TRADING_AGENTS_UHNW_DEEP_MODEL`, `TRADING_AGENTS_UHNW_QUICK_MODEL` (tier `trading-uhnw`)

### 1.5 i18n strategy (V28.1 + V28.8 rollback) — EN-only content, IT-only labels
**Decisione 2026-05-04 V28.8** (rollback V28.5/V28.7): TUTTO il contenuto LLM generato dalla pipeline tradingagents resta in inglese — Bull/Bear/Trader/Risk/PM/Verdetto Operativo. Auto-translation IT (anche con qwen3:27b o DeepSeek V4) ha qualità inaccettabile per private banking professional context. Max quality preserved → contenuto EN.

- **Tutto il contenuto LLM** (Fundamentals/Sentiment/News/Technical/Bull/Bear/Trader/Risk debate/PM verdict): output **EN preservato** dal framework upstream tradingagents v0.2.4 (prompts hardcoded EN).
- **Labels UI italiane** (hardcoded, NON LLM-translated): "Verdetto Operativo", "Decisione Portfolio Manager", "Razionale chiave", "Decisione finale", "Position sizing", "Orizzonte temporale", "Conviction", "Tesi rialzista/ribassista", "Driver chiave bullish/bearish", "Posizione aggressiva/conservativa/neutrale", "Verdetto finale" risk judge — questi OK perché sono hardcoded UI strings.
- **Summary card structured**: extractor regex EN-only (es. `final|decision|recommend|conclusion|verdict`, NO italian keywords).

**NON aggiungere translate_to_italian() o simili nel sidecar Python o frontend**. Vedi memory feedback `feedback_no_translation_max_quality.md`.

---

## §2 · Modello concettuale (architettura completa V11→V16)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  Frontend Next.js (apps/web)                                                │
│   ├─ /trading-agents                  [ADVISOR+]                            │
│   │   page.tsx — lista filtri ticker/tenant + RATING_COLORS badge           │
│   │   RunDecisionDialog — modal trigger nuova analisi                       │
│   ├─ /trading-agents/[id]            [ADVISOR+]                             │
│   │   drill-down hero rating gigante + Bull-vs-Bear side-by-side            │
│   │   accordion 9 analyst report con role badges colorati                   │
│   │   polling 3s SOLO se RUNNING/PENDING (anti-recurrence rrr)              │
│   │   MIFID II disclaimer footer client-side (anti-recurrence sss)          │
│   └─ /control-panel-v2/ai/trading-agents [SUPERVISOR/ADMIN]                 │
│       health card sidecar + tier presets info + watchlist editor            │
│   /control-panel-v2/secrets [SUPERVISOR/ADMIN]                              │
│       ApiKeysCard.tsx (~380 LOC) — banner 3 contatori + filtri criticality  │
│       + tabella sortable + status pill + crit pill + drawer drill-down      │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │ cookie valo_token
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  NestJS API :4010 (apps/api)                                                │
│   ├─ TradingAgentsModule (10 file ~1100 LOC, commit ccf80e6 W3)             │
│   │   ├─ trading-agents.controller — Roles ADVISOR/SUPERVISOR/ADMIN         │
│   │   │   GET/POST /decisions, GET /decisions/:id, GET /decisions/:id/poll  │
│   │   │   GET /health, GET /watchlist, POST/DELETE /watchlist (SUP/ADM)     │
│   │   ├─ trading-agents.service — facade + quota guard                      │
│   │   ├─ services/decision-runner.service — Prisma persist + Wave 1.6       │
│   │   │   getter espliciti tradingDecision/AnalystReport/Watchlist          │
│   │   ├─ services/python-sidecar.client — circuit breaker 3 fail→30s        │
│   │   │   open auto-recover (anti-recurrence (qqq))                         │
│   │   ├─ services/watchlist.service — CRUD multi-tenant scoped              │
│   │   ├─ services/telegram-alerts.service (W6, ~135 LOC)                    │
│   │   │   notifyRatingShift(ticker, tenant, new, score, prev)               │
│   │   │   notifySecretAlert(envVar, severity, days)                         │
│   │   ├─ services/portfolio-integration.service (W10 stub)                  │
│   │   │   syncWatchlistFromPortfolios + getStrategicWatchCrossRef           │
│   │   ├─ trading-agents.cron — @Cron('30 4 * * *') HA-master                │
│   │   ├─ cost-ledger-external.controller — POST /admin/cost-ledger/         │
│   │   │   record-external (loopback-only + X-Internal-Secret)               │
│   │   └─ types/zod schemas                                                  │
│   ├─ ApiKeysInventoryModule (Deliverable 2 V1+V2)                           │
│   │   ├─ api-keys-inventory.service — computeReport + assertCriticalSecrets │
│   │   │   + loadInventory() con o

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