Dodici agenti. Una rete. Un sistema che non dorme mai.
Da un'interfaccia Next.js a un orchestratore FastAPI,
fino a una costellazione di agenti specializzati in esecuzione locale —
e in cima a tutto, MediLog: la cartella clinica elettronica a portata di clic.
Giugno 2026Versione 1.0
La visione
Un'infrastruttura AI che vive in casa tua
solveiAgents è una piattaforma multi-agente AI
progettata per girare interamente su hardware privato o VPS — senza inviare
dati sensibili a servizi cloud di terze parti. Un'interfaccia web moderna
conversa con un orchestratore centrale, che a sua volta coordina una squadra
di agenti specializzati: ognuno con un dominio preciso, ognuno alimentato
da modelli linguistici open-weight eseguiti localmente via Ollama.
L'architettura segue un principio semplice: un agente specializzato
batte sempre un generalista. Un modello addestrato a ragionare su
referti medici non è lo stesso che analizza mercati finanziari. Un agente
che conosce il tuo wiki personale produce risultati diversi da uno che
naviga Wikipedia a caso. La specializzazione non è un limite — è una scelta
di qualità.
Il principio fondante
Immagina un ospedale universitario. Non c'è un medico solo che sa tutto:
c'è il cardiologo, il radiologo, il neurochirurgo, il medico di base.
E c'è il primario che coordina. solveiAgents è esattamente così —
ma per il tuo flusso di lavoro digitale. Ogni agente eccelle nel suo dominio,
e l'orchestratore sa sempre a chi chiedere.
Architettura della piattaforma
Next.js
Interfaccia utente
→
Orchestratore FastAPI
LLM coordinatore · Clerk Auth
→
Finanziario
Wiki
Medico
Immagini
Video
Notizie
Blog
Docling
Il team specializzato
Dodici menti, un solo obiettivo
La piattaforma include oggi dodici agenti operativi,
ciascuno esposto su una porta dedicata e attivato su richiesta dall'orchestratore.
Il principio on-demand evita sprechi di risorse: gli agenti dormono finché non
servono, si svegliano in pochi secondi e si riaddormentano dopo l'inattività.
Ogni agente e ogni servizio infrastrutturale comune vive nel suo "container docker".
:8016 Whisper — trascrizione audio con faster-whisper large-v3-turbo
🏠 Privacy by design
Tutti i modelli LLM girano in locale via Ollama.
I dati — specialmente quelli sanitari — non lasciano mai il server.
Nessun dato viene inviato a OpenAI, Anthropic, Google o altri provider cloud.
Per le funzionalità che richiedono connessione (letteratura scientifica,
notizie finanziarie), i dati trasmessi sono esclusivamente query testuali anonimizzate.
"La vera intelligenza distribuita non è avere un modello più grande — è avere il modello giusto per ogni compito."
Fondamenta solide
Lo stack che regge tutto
Ogni componente della piattaforma è scelto per ragioni precise:
affidabilità, interoperabilità con gli standard aperti,
e capacità di girare senza dipendenze cloud obbligatorie.
Frontend
Interfaccia e accesso
Next.js 14 con App Router e React Server Components
Clerk per autenticazione multi-app (agents + medilog)
Tailwind CSS con shadcn/ui e design token
WebSocket per streaming risposte in tempo reale
nginx con terminazione SSL/TLS e routing per vhost
Backend
Orchestrazione e agenti
FastAPI + SQLAlchemy async per tutti i servizi
PostgreSQL con schemi separati (phr, ref, fhir)
Alembic per migrazione database controllata
MinIO per storage oggetti (documenti, immagini)
Grafana + Prometheus + Loki per osservabilità completa
✦
Modulo principale · Cartella Clinica Elettronica
MediLog — il PHR che pensa con te
Non una semplice anagrafica paziente. Una piattaforma clinica completa con
AI integrata: dalla raccolta dei dati alla videoconsulenza, dall'analisi
dei referti all'archiviazione DICOM, tutto in un unico sistema open-source
che gira in locale e rispetta la privacy dei dati sanitari.
29+Migrazioni DB
160kFarmaci AIFA
16kCodici ICD-9-CM
140+Test automatici
Nucleo clinico
Cartella Clinica Completa
Il cuore di MediLog è lo schema phr in PostgreSQL:
pazienti, allergie, eventi clinici con codice ICD-9-CM italiano,
terapie farmacologiche con farmaci AIFA, osservazioni quotidiane,
documenti allegati e studi DICOM — tutto collegato e interrogabile.
👤
Pazienti e Anamnesi
Gestione paziente con dati anagrafici, familiarità, allergie (farmaci/alimenti/ambiente), terapie con dosaggio, frequenza e farmaco AIFA.
📅
Timeline Clinica
Timeline cronologica degli eventi con codice ICD-9-CM, descrizione, date e pin di documenti/DICOM associati. Visualizzazione calendario interattiva.
📄
Archivio Documenti
Upload documenti (PDF, immagini, audio, Markdown) con storage MinIO. OCR automatico via Docling, riepilogo AI, ricerca full-text su tutte le entità.
🔍
Ricerca Globale
GET /search?q= unificata su pazienti, eventi, documenti, farmaci, strutture, ICD-9-CM. Navigazione dalla topbar con Enter.
📋 Banche dati integrate
MediLog include loader pronti per: AIFA farmaci (~160k voci, fascia A/C/SOP/H/OTC),
strutture sanitarie AIFA (~3.3k, cp1252), ICD-9-CM Ministero della Salute
(~16.2k codici, parser formato non-standard), LOINC per analisi di laboratorio.
Tutti aggiornabili via endpoint amministrativo POST /phr/admin/ref/update.
Imaging diagnostico
DICOM nativo con viewer OHIF
Gli studi di diagnostica per immagini (RX, TC, RM, ecografie) vengono
caricati direttamente nel sistema tramite upload cartella — anche con file
senza estensione. Orthanc gestisce lo storage DICOM con
deduplicazione per StudyInstanceUID: ricaricare uno studio già presente
aggiorna il conteggio serie senza creare duplicati.
Il viewer OHIF è servito direttamente da nginx —
accessibile sia da agents.solvei.it che da medilog.solvei.it —
con autenticazione Clerk tramite l'auth-validator interno.
L'URL di visualizzazione viene costruito lato frontend dal
window.origin + StudyInstanceUID,
usando percorsi dicom-web relativi.
Integrazione clinica
Ogni studio DICOM può essere pinnato sulla timeline clinica:
un'icona CalendarPlus su ogni riga degli studi apre una dialog che permette
di collegare lo studio a un evento esistente o di crearne uno nuovo.
In timeline, il badge DICOM è cliccabile e apre direttamente il viewer OHIF.
Assistenza clinica AI
Chat paziente con analisi multimodale
La chat clinica integrata non è un chatbot generico: accede alla cartella
del paziente, legge i documenti allegati, analizza le immagini DICOM tramite
modelli vision (qwen3-vl), e consulta la letteratura scientifica internazionale
— PubMed, Europe PMC, Semantic Scholar — allegando le fonti citate con link
diretti al fulltext open access.
Il flusso tecnico: agent-phr prepara gli allegati da MinIO/Orthanc in
una cartella condivisa /data/uploads
e fa proxy verso agent-medical via SSE streaming.
Il token Clerk viene rinnovato per ogni richiesta tramite
registerTokenGetter
— evitando il problema del token cached a 60s che causava 401 silenziosi.
🧠
Analisi DICOM visiva
Il medico può chiedere "dimmi cosa vedi in questa ecografia" — la chat analizza le immagini DICOM con qwen3-vl via Ollama. Sequenze multi-frame supportate.
📚
Letteratura scientifica
cite_sources flag: ogni risposta su diagnosi o terapie viene arricchita con link a pubblicazioni PubMed/PMC open access pertinenti.
🔬
Query laboratorio NLP
"Mostrami le ultime 5 glicemie" — /labs/parse-query interpreta la richiesta in linguaggio naturale e recupera i valori LOINC corrispondenti.
📎
Allegati contestuali
I documenti MinIO e gli studi Orthanc vengono preparati e stagingati automaticamente prima di ogni chiamata al modello vision.
Analisi di laboratorio
Estrazione strutturata dei referti
Carica un referto ematico in PDF o immagine — MediLog lo elabora con OCR Docling,
poi lo invia ad agent-medical per l'estrazione strutturata dei valori:
nome analita, valore numerico, unità di misura, intervallo di riferimento,
codice LOINC. Il risultato viene presentato in una review interattiva
prima del salvataggio — il clinico può correggere valori errati o aggiungere note.
I valori salvati alimentano la vista Esami con grafici recharts
per ogni analita nel tempo. Oltre 60 analiti supportati nel mapping LOINC:
glicemia, emocromo completo, funzionalità renale ed epatica, lipidi,
ormoni tiroidei, marcatori cardiaci, coagulazione, vitamina D, HbA1c, D-dimero.
🏷️ Standard LOINC e UCUM
Ogni osservazione è codificata secondo LOINC (Logical Observation Identifiers
Names and Codes) e UCUM (Unified Code for Units of Measure).
I valori sono anche esportabili come risorse FHIR R4 Observation
verso HAPI FHIR. L'intervallo di riferimento viene derivato automaticamente
da formati italiani ("da X a Y", "< 200", "superiore a 60").
Telemedicina
Videovisita con mediasoup SFU
MediLog include un sistema completo di videochiamata SFU
(Selective Forwarding Unit) basato su mediasoup 3.20 — la stessa tecnologia
usata da Zoom e Teams, ma in esecuzione locale senza dipendenze cloud.
Sala d'attesa
Il paziente crea una stanza (phr.call_rooms) e condivide il link.
Il medico accede con token guest UNIQUE — senza necessità di account Clerk.
In chiamata
Video + audio bidirezionale, condivisione schermo
(replaceTrack su unico producer video — compatibile con tutti i browser),
late-join con producer esistenti, stale-peer eviction automatica.
Registrazione
Registrazione server-side via PlainTransport + ffmpeg.
Scelta solo-audio o audio+video. Al termine, il file viene trascritto automaticamente
da agent-whisper (faster-whisper large-v3-turbo)
e salvato come documento con trascrizione editabile.
Infrastruttura
agent-call Node.js 22 (:2000) + coturn TURN server (:3478,
network_mode:host). MEDIASOUP_ANNOUNCED_IP = IP LAN (critico: non 127.0.0.1 —
Docker Desktop non forwarda UDP al loopback).
Interoperabilità clinica
FHIR R4 e Patient Summary IPS
Tutti i dati clinici di MediLog sono disponibili in formato FHIR R4
tramite HAPI FHIR (:8080). Il Patient Summary conforme allo standard
IPS (International Patient Summary) viene generato come Bundle
FHIR e include: Patient, AllergyIntolerance, MedicationStatement, Condition
(ICD-9-CM → codifica ICD-10 per FHIR), Observation (valori laboratorio LOINC),
DocumentReference per i documenti allegati.
L'endpoint GET /phr/fhir/bundle
genera il bundle on-demand. I dati FHIR sono anche coperti dal backup giornaliero
pg_dump — poiché HAPI usa lo stesso PostgreSQL
(currentSchema=fhir).
Affidabilità in produzione
Always-on, reboot-proof, backup
MediLog è progettato per sopravvivere ai riavvii del server senza intervento manuale.
Tre problemi storici — tutti risolti con soluzioni radicali:
Problema
Cosa andava storto dopo un reboot
agent-phr e agent-medical con restart:"no" restavano Exited(255)
Orchestratore lanciava alembic prima che Postgres fosse pronto (crash-loop)
Cache JWKS usava monotonic() dal boot → per la prima ora di uptime non fetchava mai le pubkey Clerk → 401 su tutto
Soluzione
Come è stato risolto
restart:unless-stopped su phr, medical, whisper, agent-call
wait-for-db (pg_isready) in entrypoint.sh prima di alembic
shared/clerk_jwks.py unico per tre servizi — _cache_fresh() richiede fetched_at non-None E keys non vuote
Il backup giornaliero (3:00 UTC) copre tutto:
database relazionale PostgreSQL via pg_dump (schemi phr/ref/fhir),
blob MinIO (documenti e immagini) e studi Orthanc —
tutti mountati read-only nel container orchestratore e archiviati
nella cartella host ./data/backups.
In sviluppo: VM GPU OCI A10.1 Frankfurt per inferenza vision accelerata
(qwen3-vl:4b ora parzialmente su CPU → ~5 min/studio; target <30s su A10).
Architettura decisa: always-on CPU (Ollama modelli piccoli) +
GPU on-demand con billing pausa su stop, in VCN privata OCI senza
dati PHI che escono dalla regione.
▶ Demo
solveiAgents in azione — video dimostrativo
La piattaforma solveiAgents al lavoro: orchestratore, agenti specializzati e MediLog PHR in una demo completa.
