# Pattern sanitari per agenti AI (beta)

> Cosa è cambiato nel record di un paziente e cosa si ripete, calcolato da regole statistiche fisse: trend, deviazioni dal livello abituale della persona e ricorrenza dei sintomi, ciascuno con il suo periodo, evidenza e limitazioni; non diagnosi.

Source: https://developers.anpheros.com/it/guides/health-patterns

**Anpheros calcola cosa è cambiato nel record di un paziente e cosa si ripete, tramite regole statistiche fisse, e fornisce ciascun risultato alla tua applicazione o agente AI con il suo periodo, le risorse sottostanti, la versione del metodo e le sue limitazioni.** Un modello non deve più indovinare un trend da una manciata di numeri: ottiene il trend, l'incertezza attorno ad esso e i dati da citare.

Beta. Nella sandbox funziona con qualsiasi credenziale sandbox (chiavi `sk_test_…` e connessioni OAuth sandbox). Sui record di produzione viene eseguito solo sotto il consenso OAuth di un paziente che include il permesso separato `anpheros/patterns`; le chiavi API di produzione restituiscono 403.

## Cosa trova

| Tipo | Domanda a cui risponde | Metodo |
|---|---|---|
| `trend` | Una misurazione sta aumentando o diminuendo nella finestra temporale? | Pendenza di Theil–Sen con Mann–Kendall su un valore al giorno (mediane settimanali per dati di monitoraggio densi), corretta quando i giorni vicini sono simili |
| `trend` (`change_between_results`) | Come è cambiato un test di laboratorio con due o cinque risultati? | Primo e ultimo risultato, con l'ultimo confrontato con l'intervallo di riferimento del referto; descritto, non testato |
| `trend` (`event_rate_change`) | Un sintomo viene registrato più o meno spesso? | Giorni con sintomi rispetto ai giorni in cui la persona ha registrato qualcosa, ultimi 30 giorni contro i 90 precedenti, test esatto |
| `baseline_deviation` | L'ultima settimana è insolita per questa persona? | Ultimi 7 giorni contro i giorni 8–60, Mann–Whitney o differenza di medie corretta per autocorrelazione |
| `recurrence` | Gli episodi di sintomi si ripresentano a intervalli regolari? | Intervalli tra l'inizio degli episodi, Monte Carlo con seed rispetto agli episodi posizionati casualmente |
| `association` (`around_medication_start`, sandbox) | Un sintomo viene registrato più o meno spesso dall'inizio di un farmaco? | Giorni con sintomi rispetto ai giorni attivi nei 30 giorni dall'inizio contro un massimo di 90 giorni precedenti, test esatto |
| `association` (`after_short_sleep`, sandbox) | Un sintomo viene registrato più spesso nei giorni con meno di 6 ore di sonno? | Giorni con sonno misurato e una registrazione della persona, notti brevi rispetto a notti più lunghe, test esatto di Fisher |
| `convergence` (`recent_changes_together`, sandbox) | Diverse cose sono cambiate nello stesso periodo recente? | Nessun nuovo test: raggruppa almeno due cambiamenti recenti (una settimana insolita, un sintomo più o meno frequente) che sono ciascuno statisticamente supportati; dice solo che sono accaduti insieme |

Tutti i test di una singola esecuzione vengono corretti insieme (Benjamini–Hochberg). Un risultato è `statistically_supported` solo quando il valore q corretto è inferiore a 0.05 **e** la variazione è almeno la soglia per quella misurazione.

## Cosa non è

- **Non è una diagnosi.** I riscontri descrivono il record; non nominano mai una condizione né raccomandano una modifica del trattamento. Ogni riscontro riporta `safety.not_a_diagnosis = true` e `safety.causal_claim = false`.
- **Non è una causa.** Una variazione dopo una nuova medicazione, o due elementi registrati insieme, non sono prova che uno abbia causato l'altro. Le associazioni indicano solo che due eventi si sono verificati circa nello stesso momento; ognuna riporta `confounding_possible` e `not_causal`, e solo le iniziazioni di farmaci e il sonno vengono testati rispetto ai sintomi, non ogni coppia. Attualmente solo con credenziali sandbox.
- **Non è un modello AI e non è ancora stato revisionato clinicamente.** Ogni numero proviene da regole statistiche fisse e versionate; nessun modello AI analizza i dati. Le soglie per una variazione significativa sono state impostate con l'assistenza di AI e non sono ancora state revisionate da un clinico; ogni riscontro lo indica in `review.thresholds_reviewed_by_clinician`. Il motore è validato su pazienti sintetici con pattern noti e piantati: trova ciò che è stato piantato e rimane silenzioso quando non c'è nulla. Questa non è una validazione clinica.

## Prova

Ogni progetto sandbox ha 30 pazienti sintetici, e sei di loro hanno uno schema preimpostato. Trova uno con `GET /fhir/R4/Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|<key>`.

| Paziente | Cosa è stato preimpostato | Cosa riporta il motore |
|---|---|---|
| p01 Andrei Popescu | Pressione sanguigna domiciliare giornaliera, in calo di circa 8/5 mmHg in sei mesi | `trend.decreasing` per la sistolica (8480-6) e la diastolica (8462-4) |
| p06 Giulia Rossi | Mal di testa ogni 7 giorni, più o meno uno | `recurrence.intervals` per mal di testa (R51) |
| p17 Ciarán Murphy | Stanchezza in circa la metà degli ultimi 30 giorni, rispetto a 1 giorno ogni 12 prima | `frequency.increased` per stanchezza (R53) |
| p19 Felix Gruber | Frequenza cardiaca a riposo da un orologio, circa 9 bpm sopra il suo livello abituale nell'ultima settimana | `baseline.higher` per frequenza cardiaca a riposo (40443-4) |
| p20 Ivana Horvat | Frequenza cardiaca a riposo da un orologio, in assestamento di circa 16 bpm in sei mesi | `trend.decreasing` per frequenza cardiaca a riposo (40443-4) |
| p30 Jan Kowalczyk | Dati densi dall'orologio e domiciliari senza nulla di preimpostato | nessun riscontro supportato: il motore rimane silenzioso |

I progetti creati prima del 16 ottobre 2026 ottengono questi schemi dopo aver resettato i loro pazienti sintetici dalla dashboard; un reset sostituisce qualsiasi modifica apportata ad essi.

```bash
curl -s https://platform.anpheros.com/v1/patients/$PATIENT/patterns?window_days=180 \
  -H "Authorization: Bearer $ANPHEROS_KEY"
```

Con l'SDK TypeScript (`@anpheros/sdk` 0.2.0 o versioni successive):

```ts
const run = await anpheros.patterns.run(patientId, { window_days: 180, min_strength: 'moderate' });
for (const f of run.findings) console.log(f.summary_text, f.strength, f.limitations.map(l => l.code));
```

Con il server MCP, chiedi al tuo agente *"Cosa è cambiato nel registro di questo paziente negli ultimi sei mesi?"*: chiama `get_health_patterns`, e può proseguire con `get_pattern_evidence`, `get_series` e `compare_periods`. `POST /v1/context` aggiunge una sezione `patterns` per domande su cambiamenti e relazioni, o quando richiedi il bisogno `patterns`.

## Endpoint

| Endpoint | Cosa restituisce |
|---|---|
| `GET /v1/patients/{id}/patterns` | un run: risultati, cosa non è stato possibile calcolare e perché, quale consenso è stato escluso; filtri `window_days` (30–730), `end`, `types`, `min_strength` |
| `GET /v1/patients/{id}/patterns/{finding_id}` | un singolo risultato, ricalcolato per la stessa finestra |
| `GET /v1/patients/{id}/patterns/{finding_id}/evidence` | ogni risorsa di supporto, paginata |
| `GET /v1/patients/{id}/series?code=…` | una singola misurazione come un valore al giorno, con copertura, lacune e modifiche della sorgente |
| `POST /v1/patients/{id}/patterns/compare` | una singola misurazione in due periodi a tua scelta |

## Lettura di un riscontro

- `summary_text`: una frase semplice, sicura da mostrare o citare.
- `strength`: `strong`, `moderate`, `weak` o `not_tested`. Riscontri deboli e non testati sono descrizioni, non prove.
- `window`, `comparison_window`: i periodi analizzati.
- `evidence` (fino a 20, distribuiti nel periodo) e `evidence_total`: le risorse dietro il riscontro, con versione, data, valore e tipo di autore.
- `limitations`: codificato, con testo. Mostrali con il riscontro.
- `review`: se un clinico ha esaminato le soglie (`false` per ora) e da dove provengono.
- `method`, `engine_version`, `input_fingerprint`: gli stessi dati, configurazione e versioni danno lo stesso risultato e lo stesso id.

## Regole da conoscere

- **Consenso prima di tutto.** Nell'ambito di una concessione OAuth, il motore legge solo ciò che la concessione consente; ciò che non è stato possibile leggere è elencato in `omitted`, senza contenuto.
- **ID.** I pazienti appaiono con l'ID pairwise del tuo progetto; gli ID di ricerca sono derivati per progetto. Quando il record cambia, una ricerca ottiene un nuovo ID e il vecchio risponde 404.
- **Ora.** Quando l'ora di una lettura presenta un offset esplicito (`2026-10-16T00:30:00+03:00`), si basa sul giorno della persona; gli orari in UTC (`Z`) o senza offset rimangono nel giorno UTC. Ogni ricerca indica quale in `time_basis` (`record_offsets`, `partly_local` o `local_time_unknown`). I giorni locali sono utilizzati sui record sandbox e di produzione; i pattern orari non sono ancora stati calcolati.
- **Omessi.** I valori scritti dall'IA, i risultati contrassegnati come entered-in-error e le date note solo al mese non vengono utilizzati e vengono conteggiati.
- **Limiti.** 30 esecuzioni di pattern al minuto per credenziale, oltre alle solite 600 richieste al minuto.

## Domande frequenti

### Utilizza un modello linguistico?
No. Ogni numero proviene da metodi statistici fissi e versionati. Qualsiasi modello, ospitato o locale, può leggere i risultati.

### Perché una chiara modifica nei miei dati viene contrassegnata come debole?
Perché l'evidenza non sopravvive alla correzione per tutti i test eseguiti, la serie è breve o rumorosa, o la modifica è al di sotto della soglia per quella misurazione. Il risultato descrive comunque ciò che il record mostra.

### Funziona sui record di produzione?
Sì, dal 16 ottobre 2026, ma solo sotto il consenso OAuth di un paziente che include il permesso separato `anpheros/patterns`, che la schermata di consenso mostra su una riga separata. Richiedi lo scope accanto ai tuoi scope `patient/…`; una concessione senza di esso, e qualsiasi chiave API di produzione, restituisce 403.

## Correlati

- [Server MCP FHIR per agenti AI](https://developers.anpheros.com/it/guides/mcp)
- [Applicazioni LLM e dati sanitari](https://developers.anpheros.com/it/guides/llm-healthcare-data)
- [Agenti AI e dati medici](https://developers.anpheros.com/it/guides/ai-agents-medical-data)
- [API sanitarie con consenso del paziente](https://developers.anpheros.com/it/guides/healthcare-api-patient-consent)