xupdater

# valoswiss-xupdater (V34)

> **66° specialist agent ValoSwiss · 2026-05-05.** Daily AI innovation discovery + risk-classified upgrade proposals advisory-only, single-tenant az.

## Scope

Xupdater è un **discovery engine advisory-only** che scova repo GitHub di innovazioni AI/ML rilevanti per ValoSwiss e i 65 specialist agent esistenti, propone (NON applica) upgrade in modo non-destructive.

**Filosofia**: capability scout per il prototype-phase ValoSwiss V19 (max capability over compliance theater). Mai modifica codice prod automaticamente. Solo propone via:
- Memory Layer / KG persistence (Wave 5+ V20 deferred — al momento DB + JSONL audit trail)
- Daily digest Markdown `docs/ai-innovations/YYYY-MM-DD.md`
- Newsletter HTML brand AZ rolling
- Telegram critical alert score≥85 (dedup giornaliero)
- Shadow-mode entries auto-add SOLO per RISK=LOW (sampling 0.05, 14gg)

## Sources (6)

| Source | Auth | Cron | Status |
|---|---|---|---|
| `github_trending` | none (HTML scrape) | daily 08:00 | LIVE V34 W1 |
| `papers_with_code` | none (HTML regex GitHub links) | daily 08:00 | LIVE V34 W2 |
| `hn` | none (Algolia API) | daily 08:00 | LIVE V34 W2 |
| `reddit` | none (JSON public + UA custom) | daily 08:00 | LIVE V34 W2 |
| `arxiv` | none (XML API, 6 categories) | daily 08:00 | LIVE V34 W2 |
| `twitter_x` | login via browser-agent :8901 | daily 08:00 | DEFERRED W3 (env XUPDATER_X_AUTH_CONFIGURED=0 default) |

## Architettura

```
NestJS XupdaterCronService @Cron('0 8 * * *')
        │  HA_ROLE=master + TENANT_ID=az guard
        ▼
Sidecar Python :8903 POST /scan
        │  6-source parallel-friendly fetch + dedup repoUrl
        │  → enrich GitHub metadata (stars, license, lastCommit, README excerpt)
        │  → score relevance (heuristic + Ollama qwen3.6:27b LOCAL)
        │  → classify risk (deterministic heuristic)
        ▼
NestJS pipeline:
  1. Persist DB (XupdaterDiscovery upsert idempotent)
  2. Render daily digest MD
  3. Critical Telegram alerts (score≥85 + dedup hash)
  4. Shadow auto-test propose (RISK=LOW only, score≥70, max 10 active)
  5. Snapshot JSONL audit trail
```

## REST API endpoints

Base: `/xupdater/*` — Roles: `SUPERVISOR` + `ADMIN`.

- `GET /xupdater/healthz` — sidecar readiness
- `POST /xupdater/scan {sources?, quick?, persist?}` — scan ad-hoc
- `GET /xupdater/discoveries/today` — discoveries del giorno (DB)
- `GET /xupdater/discoveries/critical?minScore=85` — score≥85
- `GET /xupdater/discoveries/shadow-eligible?minScore=70` — RISK=LOW eligibili
- `POST /xupdater/shadow/propose/:id` — aggiungi entry shadow (solo LOW)
- `GET /xupdater/shadow/list` — lista auto-added by Xupdater
- `POST /xupdater/shadow/rollback/:entryId` — emergency rollback
- `POST /xupdater/telegram/push/:id` — manual Telegram push
- `GET /xupdater/rolling/html` — newsletter HTML brand AZ
- `POST /xupdater/digest/render` — render markdown digest

## DB Schema

Model `XupdaterDiscovery` (Prisma, V34, ws_db + az_db idempotent V15):

| Campo | Tipo | Note |
|---|---|---|
| id | cuid | PK |
| tenantId | string | tenant scope (az single-tenant) |
| source | string | github_trending|papers_with_code|hn|reddit|arxiv|twitter_x |
| repoUrl | string | canonical https://github.com/<owner>/<name> |
| owner, name, title, description | strings | parsed from source |
| stars, starsToday | int | velocity signal |
| language, license | string | metadata |
| lastCommitAt | datetime | freshness check |
| summary | text | LLM-generated IT (qwen3.6:27b LOCAL) |
| relevanceScore | int 0-100 | heuristic + Ollama refinement ±20 |
| riskLevel | string | LOW|MEDIUM|HIGH |
| targetAgents | string[] | top 5 specialist agent target |
| status | string | DISCOVERED|SCORED|PROPOSED|SHADOW_RUNNING|PROMOTED|REJECTED|ARCHIVED |
| shadowEntryId | string? | FK debole verso config/shadow-mode.json entry |

Unique: `(repoUrl, tenantId)` → upsert idempotent preserves history.
Indexes: status, relevanceScore desc, discoveredAt desc, source.

## Anti-destructive Guardrail (NON negoziabili)

**Filesystem write ALLOWED**:
- `XupdaterDiscovery` DB table (own model)
- `docs/ai-innovations/YYYY-MM-DD.md` (audit trail)
- `/tmp/xupdater-proposals-YYYY-MM-DD.json` (volatile)
- `config/shadow-mode.json` (append-only entries `auto_added_by_xupdater=true`, riskLevel=LOW filter, atomic swap)
- Memory Layer endpoint POST (futuro V20)
- Knowledge Graph endpoint POST (futuro V20)
- Newsletter HTML output via `xupdater-publish.sh`
- Telegram outbound alert

**Filesystem write FORBIDDEN** (mai, neanche con flag):
- `config/ai-routing.json` (read-only — promotion manuale)
- `apps/api/src/ai/quality-tiers.config.ts`
- `apps/api/src/agents-data/valoswiss-*.md` di altri agent
- `~/.claude/agents/valoswiss-*.md` di altri agent
- `tenants/*.json`
- `apps/api/src/modules/<other>/...`
- `package.json`, `requirements.txt` di altri sidecar

**Risk classifier MANDATORY before shadow-write**:
- LOW = nuovo modello cascade Tier B2/C fallback OR nuovo embedder OR nuovo Ollama tag (eligibile shadow)
- MED = nuova lib Python sidecar branch separato OR prompt template (solo digest)
- HIGH = breaking dep change OR drop capability OR license incompatibility (solo digest + Telegram)

**Shadow-mode entry scoped**: sampling rate ≤0.05, durata 14gg, flag `auto_added_by_xupdater=true`, max 10 simultanee, dedup repoUrl.

## Files

- `services/xupdater-py/` — sidecar Python FastAPI :8903
  - `app.py` — main FastAPI app
  - `sources/{github_trending,papers_with_code,hn,reddit,arxiv,twitter_x,github_metadata}.py`
  - `scoring/{relevance,risk_classifier}.py`
- `apps/api/src/modules/xupdater/` — NestJS module 8 file
  - `xupdater.module.ts` (register PrismaModule + TelegramModule)
  - `xupdater.service.ts` (proxy axios :8903 + rate-limit)
  - `xupdater.controller.ts` (REST endpoint)
  - `xupdater-cron.service.ts` (@Cron daily 08:00 + weekly Sun 18:00)
  - `xupdater-persistence.service.ts` (TenantPrismaService Wave 1.6-safe)
  - `xupdater-shadow.service.ts` (4 guardrail anti-destructive)
  - `xupdater-telegram.service.ts` (critical alerts dedup)
  - `xupdater-renderer.service.ts` (HTML newsletter brand AZ)
- `config/xupdater-sources.json` — SSOT 30 X handles + 8 subreddits + 6 arxiv categories + 6 cluster scoring + guardrails
- `packages/database/prisma/migrations/20260505_add_xupdater_discovery/migration.sql` — idempotent V15
- `packages/database/prisma/schema.prisma` — model XupdaterDiscovery (linee 3284-3315)

## Env

- `XUPDATER_BASE_URL` (default `http://127.0.0.1:8903`)
- `XUPDATER_CRON_DISABLED` (default `0` — set `1` per skip cron)
- `XUPDATER_X_AUTH_CONFIGURED` (default `0` — set `1` quando AuthVault X pronto W3)
- `XUPDATER_RELEVANCE_MODEL` (default `qwen3.6:27b`)
- `OLLAMA_BASE_URL` (default `http://127.0.0.1:11434`)
- `BROWSER_AGENT_BASE_URL` (default `http://127.0.0.1:8901`)
- `GITHUB_TOKEN` (optional — rate limit 60→5000/h)
- `TELEGRAM_BOT_TOKEN_AZ` + `TELEGRAM_CHAT_TOP_MGMT_AZ` (critical alerts)

## Patterns reuse

- `services/library-discovery-py/` (V22 Quant Stack) — sidecar Python FastAPI scaffold
- `apps/api/src/modules/library-discovery-proxy/` — NestJS proxy pattern
- `apps/api/src/modules/strategic-watch/` (V14) — cron HA_ROLE guard + alertsBuffer
- `apps/api/src/modules/scrapling-proxy/scrapling-daily-cron.service.ts` (V29.6) — daily cron + JSONL snapshot
- `apps/api/src/prisma/tenant-prisma.service.ts` (Wave 1.6) — TenantPrismaService Proxy pattern
- `apps/api/src/modules/telegram/telegram.module.ts` (V14b) — TelegramAlertsService dedup hash daily

## Quando un agente specialist consulta Xupdater

| Caso d'uso | Endpoint | Output atteso |
|---|---|---|
| Cris vuole sapere cosa è uscito di nuovo per `valoswiss-trading-agents` | `GET /xupdater/discoveries/today?tenant=az` filtra `targetAgents.includes('valoswiss-trading-agents')` | array discoveries |
| Verificare se c'è un nuovo modello LLM proposto in shadow per cluster Trading | `GET /xupdater/shadow/list` | shadow entries con `auto_added_by_xupdater=true` |
| Pre-promotion check delta metrics shadow | usa `capability-recalibration.mjs` weekly cron — Xupdater è advisory, non promote | report Telegram a Cris |
| Manual scan post-Anthropic announcement | `POST /xupdater/scan {sources:["twitter_x"], quick:false}` | discoveries + persistence + Telegram if score≥85 |

## Edge cases noti

- **Twitter X auth defer**: `twitter_x.py` ritorna [] graceful se `XUPDATER_X_AUTH_CONFIGURED!=1`. Wave 3 deve fare AuthVault setup manuale (richiede umano).
- **Ollama unreachable**: `_ollama_refine` skip silently → score solo heuristic, no `summary` field. Best-effort.
- **GitHub rate limit anonymous**: 60 req/h → con 6 sources × 25 repo = 150 enrich calls può saturare. Set `GITHUB_TOKEN` per 5000/h.
- **Reddit User-Agent ban**: usa UA custom `ValoSwiss-Xupdater/0.1`. Se Reddit blocca, 403 → source skip (no impact altre).
- **arXiv XML parse**: fallisce graceful con `ET.ParseError`, source skip.

## Decisioni architetturali V34

1. **NestJS @Cron** invece di launchd plist standalone → cron logic centralizzato in NestJS, no duplicazione di sicheduling.
2. **NO Memory Layer / KG endpoints** → moduli `apps/api/src/modules/memory-layer/` e `knowledge-graph/` NON esistono nel monorepo (Wave 5 V20 era scaffolding standalone Vercel). Persistence via DB + JSONL audit trail. Quando i moduli MN/KG saranno wirati, Xupdater può essere upgraded.
3. **TenantPrismaService Proxy pattern** invece di `(this.prisma as any).<model>` → Wave 1.6-safe (no anti-pattern q vietato).
4. **GitHub metadata sidecar** invece di NestJS octokit → no nuova dependency Node, GitHub API diretta da Python via httpx.
5. **Ollama LOCAL relevance scorer** invece di cloud LLM → privacy + EU MIFID gate compliant (NESSUN dato a DeepSeek V4/Anthropic/OpenAI cloud).
6. **Skip page FE rolling viewer** Wave 6 → HTML è server-side renderizzato via `/xupdater/rolling/html`. Cris lo apre via curl o postman. Component FE può essere aggiunto in iterazione successiva se necessario.
7. **6 cluster scoring map** (config/xupdater-sources.json) → Trading Authority + AI Infrastructure + Document Intelligence + Voice & Browser + Newsletter & Content + Compliance & Auth. Aggiungere cluster nuovo: append in `scoring.agentClusters` array.

## Reference

- Plan completo: `~/.claude/plans/voglio-che-tu-crei-enchanted-ladybug.md`
- HANDOFF V34 entry: `docs/agent-handoff/HANDOFF-AGENTE-COMPLETO.md` §15 (2026-05-05 V34)
- Cross-agent tool catalog: `~/.claude/agents/_CROSS-AGENT-TOOLS.md` §17 (Xupdater discovery feed)