WikidAI - PoC Implementation
Sistema multi-agente educational che dimostra l’orchestrazione trasparente di AI con Gemini 2.5 Pro.
📋 Caratteristiche PoC Implementate
✅ US-PoC-001: Setup Docker
- Dockerfile multi-stage per il backend
- Container frontend basato su Nginx
- Redis per caching futuro
- Hot-reload abilitato per lo sviluppo
✅ US-PoC-002: Integrazione Gemini
- Gemini 2.5 Pro con modalità Thinking
- Function calling per l’orchestrazione degli agenti
- Gestione della cronologia delle conversazioni
✅ US-PoC-003: Agente Wikidata
- Generazione SPARQL da linguaggio naturale
- Validazione della sintassi con sparqljs
- Sanificazione di sicurezza (query read-only)
- “SPARQL Gauntlet” implementato
✅ US-PoC-004: Agente Wikipedia
- Recupero riassunti dall’API di Wikipedia
- Gestione errori per articoli mancanti
- Output formattato
✅ US-PoC-005: Workflow Multi-Turn
- Conservazione della cronologia delle conversazioni
- Chiamate sequenziali agli agenti
- Gestione della “Thought signature”
✅ US-PoC-006: UI Educativa
- Dashboard a 3 pannelli (Input, Reasoning, Output)
- Visualizzazione in tempo reale del ragionamento dell’AI
- Tracciamento delle chiamate agli agenti
- Visualizzazione metriche (latenza, agenti utilizzati)
📝 Query di Esempio
È possibile provare queste query nella dashboard:
- Query Semplice Wikipedia:
- “Chi era Albert Einstein?”
- Atteso: Riassunto da Wikipedia
- Query Complessa SPARQL:
- “Chi è il sindaco di Roma?”
- Atteso: Generazione ed esecuzione di SPARQL su Wikidata
- Query Multi-Turn:
- “Parlami di Einstein e della sua città natale”
- Atteso: Chiamate multiple ad agenti (Wikipedia → Wikipedia)
🎨 Diagrammi UML — Dettagli Implementativi
Questa sezione fornisce una visione approfondita dell’architettura TypeScript e dei flussi di orchestrazione AI attraverso diagrammi UML dettagliati.
📐 Class Diagram — Backend Structure
Architettura backend TypeScript: GeminiOrchestrator come cervello centrale coordina 4 Agent specializzati (Wikidata, Wikipedia, Nominatim, OpenMeteo). ConversationManager mantiene contesto multi-turn.
classDiagram
direction TB
class ExpressServer {
+start()
+POST /api/query
+GET /api/conversations
}
class ConversationManager {
-conversations Map
-maxConversations number
+createConversation(title)
+addUserMessage(id, content)
+addAssistantMessage(id, content, response)
+getGeminiHistory(id)
+getStats(id)
}
class GeminiOrchestrator {
-genAI GoogleGenerativeAI
-wikidataAgent WikidataAgent
-wikipediaAgent WikipediaAgent
-nominatimAgent NominatimAgent
-openMeteoAgent OpenMeteoAgent
-promptMode PromptModeType
+constructor(promptMode)
+executeQuery(query, history) QueryResponse
-getFunctionDeclarations()
-getSystemInstructions()
}
class ReflexiveMode {
+handleReflexive(query) ReflexiveResponse
-isReflexiveQuery(query)
}
class WikidataAgent {
+execute(sparqlQuery)
+formatResults(results)
}
class SPARQLValidator {
+validate(query)
}
class WikipediaAgent {
+execute(term)
+formatSummary(summary)
}
class NominatimAgent {
+geocode(query)
+formatResults(results)
}
class OpenMeteoAgent {
+getWeather(lat, lon)
+formatWeather(data)
}
class QueryResponse {
+thoughts string[]
+agentCalls AgentCall[]
+answer string
}
note for QueryResponse "TypeScript interface"
ExpressServer ..> ConversationManager : usa
ExpressServer ..> GeminiOrchestrator : usa
ExpressServer ..> ReflexiveMode : usa
GeminiOrchestrator --> WikidataAgent
GeminiOrchestrator --> WikipediaAgent
GeminiOrchestrator --> NominatimAgent
GeminiOrchestrator --> OpenMeteoAgent
WikidataAgent ..> SPARQLValidator : valida
GeminiOrchestrator ..> QueryResponse : restituisce
🔄 Sequence Diagram — Orchestration Flow
Flusso completo: query utente → context loading → loop LLM con thinking mode e tool execution → salvataggio contesto → risposta JSON strutturata con thoughts, agent calls e answer.
Loop di ragionamento Chain of Thought + Function Calling tra Orchestrator e Gemini 2.5 Pro. Multi-turn reasoning fino a risposta finale.
sequenceDiagram
autonumber
actor User
participant API as Express API
participant CM as ConversationManager
participant Orch as GeminiOrchestrator
participant Gemini as Gemini 2.5 Pro
participant Agents as Specialized Agents
User->>API: POST /api/query
API->>CM: addUserMessage(query)
API->>CM: getGeminiHistory()
CM-->>API: history context
API->>Orch: executeQuery(query, history)
loop Reasoning & Tool Use
Orch->>Gemini: sendMessage(query + tools)
alt Thinking Mode
Gemini-->>Orch: Thought: Devo cercare su Wikidata...
end
Gemini-->>Orch: FunctionCallRequest
break No FunctionCalls
Orch-->>API: Final Answer
end
Orch->>Agents: Execute function
Agents-->>Orch: JSON Result
Orch->>Gemini: FunctionResponse
Note right of Gemini: Analizza risultato
decide prossimo step end Orch-->>API: QueryResponse API->>CM: addAssistantMessage(response) API-->>User: JSON response
decide prossimo step end Orch-->>API: QueryResponse API->>CM: addAssistantMessage(response) API-->>User: JSON response
🐳 Component Diagram — Deployment Architecture
Architettura Docker: Frontend Nginx (static + reverse proxy), Backend Node.js (Express + Orchestrator), Redis cache. Connessioni a servizi esterni: Gemini API, Wikidata/Wikipedia, OSM Nominatim, OpenMeteo.
flowchart TD
subgraph Docker["🐳 Docker Host"]
direction TB
subgraph Frontend["Frontend Container - Nginx"]
UI[Static HTML/JS]
Proxy[Reverse Proxy :80]
end
subgraph Backend["Backend Container - Node.js"]
Server[Express Server :3000]
Orchestrator[Gemini Orchestrator]
end
subgraph Data["Data / Cache"]
Redis[(Redis Cache)]
end
end
subgraph External["☁️ External Services"]
GeminiAPI[Google Gemini API]
WikiAPI[Wikidata / Wikipedia]
GeoAPI[Nominatim / OpenMeteo]
end
User((👤 Browser)) --> Proxy
Proxy -->|/api/*| Server
Proxy -->|static| UI
Server --> Orchestrator
Server -.-> Redis
Orchestrator -->|GenAI + Function Calling| GeminiAPI
Orchestrator -->|SPARQL / REST| WikiAPI
Orchestrator -->|REST| GeoAPI
💬 State Diagram — Conversation Management
Gestione stato conversazione: analisi richiesta → biforcazione tra Reflexive Mode (comandi /help, /clear, meta-domande) e Standard Orchestration (domande di conoscenza con loop LLM completo).
stateDiagram-v2
[*] --> Idle
Idle --> Analysis : POST /query
state Analysis {
[*] --> CheckType
CheckType --> IsReflexive : comando o meta-domanda
CheckType --> IsStandard : domanda conoscenza
}
Analysis --> Reflexive : reflexive query
Analysis --> Standard : knowledge query
state Reflexive {
[*] --> CheckCommand
CheckCommand --> ExecClear : /clear
CheckCommand --> ExecHelp : /help
CheckCommand --> ExecMeta : come funzioni?
ExecClear --> Done : Cancella memoria
ExecHelp --> Done : Testo statico
ExecMeta --> Done : Spiega architettura
Done --> [*]
}
state Standard {
[*] --> LoadContext
LoadContext --> LLM_Loop
state LLM_Loop {
[*] --> GenerateThought
GenerateThought --> DecideTool
DecideTool --> ExecuteAgent : Function Call
DecideTool --> Finalize : Risposta pronta
ExecuteAgent --> GenerateThought : Ritorna dati
}
LLM_Loop --> SaveContext
SaveContext --> [*]
}
Reflexive --> Idle : JSON Response
Standard --> Idle : JSON Response
note right of LLM_Loop : Chain of Thought
+ Tool Use Loop
+ Tool Use Loop
🏗️ Architettura
WikidAI adotta una architettura multilivello containerizzata in Docker che mostra in modo trasparente come gli agenti AI cooperano per rispondere a query complesse.
🔍 Panoramica dei Componenti
- Frontend (Vanilla JS + Nginx): fornisce un’interfaccia didattica e visualizza in tempo reale il ragionamento dell’AI.
- Backend (Node.js + Express): gestisce la logica applicativa e coordina l’orchestrazione.
- Gemini Orchestrator: seleziona e coordina dinamicamente gli agenti in base alla query.
- Agenti Specializzati:
- WikidataAgent: genera e valida query SPARQL.
- WikipediaAgent: recupera riassunti multilingue.
- NominatimAgent: fornisce geocodifica da OpenStreetMap.
- OpenMeteoAgent: integra dati meteo in tempo reale.
- Redis Cache: prevista per caching, rate limiting e metriche.
⚙️ Pipeline di Orchestrazione
- Input utente → Gemini analizza intento e seleziona agente appropriato.
- Esecuzione agente → raccolta dati esterni.
- Aggregazione risultati → reasoning finale.
- Output trasparente → dashboard utente.
💡 Decisioni di Design
- Vanilla JS per trasparenza e semplicità didattica.
- Gemini 2.5 Pro per reasoning esplicito e function calling nativo.
- Docker-first per isolamento e riproducibilità.
🔗 Estensioni Future
- Integrazione BullMQ per rate limiting.
- Nuovi agenti (DuckDuckGo, DBpedia, Europeana).
- Dashboard metrica avanzata con performance e logica SPARQL visuale.