Glossario
Definizioni dei termini tecnici e acronimi utilizzati nel progetto Emblema.
📚 Termini Generali
A
Agent (Agente) : Configurazione AI che definisce comportamento, modello e parametri per interagire con l'utente. Include system prompt, modello LLM, e impostazioni come temperatura.
Air-gap : Ambiente isolato senza connessione internet. Emblema supporta deployment air-gap con export/import di Docker images.
Artifact : Output generato dall'AI durante una chat (codice, documenti, diagrammi) che può essere salvato e riutilizzato.
B
Background Task : Elaborazione asincrona gestita da Celery per operazioni intensive come chunking, embedding generation, transcription.
BGE-M3 : Modello di embedding multilingue utilizzato per la generazione di vettori semantici (1024 dimensioni).
C
Chunk : Porzione di documento divisa per ottimizzare la ricerca semantica. Dimensione tipica: 512 token con 75 token di overlap.
Chunking : Processo di divisione documenti in parti più piccole per elaborazione e ricerca. Strategie: recursive, semantic, diarization.
Celery : Task queue distribuita per Python utilizzata per processamento asincrono in background-task service.
D
Diarization : Identificazione automatica di chi parla in un audio/video. Utilizzato da WhisperX per separare speaker in trascrizioni.
Docker Compose : Orchestratore container utilizzato per gestire l'infrastruttura multi-servizio di Emblema.
E
Embedding : Rappresentazione vettoriale di testo generata da modelli AI per ricerca semantica. Emblema usa BGE-M3 (1024 dimensioni).
F
FastAPI : Framework Python moderno per building API REST con validazione automatica e documentazione OpenAPI.
Feature Flag : Meccanismo per abilitare/disabilitare funzionalità tramite variabili ambiente (es. FEATURE_MCP_SUPPORT).
G
GraphQL : Query language per API utilizzato da Hasura per esporre il database PostgreSQL.
H
Hasura : GraphQL engine che genera automaticamente API GraphQL dal database PostgreSQL con sistema di permessi.
Hot Reload : Ricaricamento automatico del codice durante lo sviluppo senza restart del servizio.
K
Keycloak : Identity provider open source per autenticazione SSO e gestione utenti con supporto OIDC/SAML.
Knowledge Base : Collezione di documenti correlati per un dominio specifico, utilizzata per RAG e ricerca contestuale.
L
LiteLLM : Gateway unificato per accedere a diversi provider LLM (OpenAI, Anthropic, modelli locali) con API standard.
LLM (Large Language Model) : Modello di linguaggio di grandi dimensioni per generazione testo, utilizzato per chat e elaborazione linguaggio.
M
MCP (Model Context Protocol) : Protocollo di Anthropic per estendere capacità LLM con tool esterni e accesso a dati.
Milvus : Database vettoriale open source per storage e ricerca di embeddings ad alta performance.
MinIO : Object storage S3-compatible utilizzato per storage file e artifacts.
MinerU : Tool avanzato per estrazione testo da PDF con supporto layout complessi e VLM (Vision Language Models).
Monorepo : Repository singolo che contiene multiple applicazioni e librerie. Emblema usa pnpm workspaces.
N
Next.js : Framework React per applicazioni web con SSR/SSG. Emblema usa v14 con App Router.
NextAuth : Libreria autenticazione per Next.js integrata con Keycloak per SSO.
Novu : Piattaforma notifiche multi-canale per email, SMS, push notifications.
O
OIDC (OpenID Connect) : Protocollo di autenticazione sopra OAuth 2.0 utilizzato per SSO con Keycloak.
P
pnpm : Package manager veloce ed efficiente per JavaScript con supporto workspace nativo.
Preset (Chunking) : Configurazione predefinita per chunking ottimizzata per tipo documento (default, meeting, technical, qa).
R
RAG (Retrieval-Augmented Generation) : Tecnica AI che combina ricerca semantica con generazione per risposte basate su documenti.
RBAC (Role-Based Access Control) : Sistema autorizzazioni basato su ruoli implementato a 3 livelli in Emblema.
Redis : In-memory database utilizzato come message broker per Celery e cache.
S
Semantic Search : Ricerca basata su significato usando embeddings vettoriali invece di keyword matching.
Shadcn/ui : Libreria componenti React basata su Radix UI con styling Tailwind CSS.
SSE (Server-Sent Events) : Protocollo per streaming dati dal server al client, usato per progress updates.
SSO (Single Sign-On) : Autenticazione unica per accedere a multiple applicazioni, implementata con Keycloak.
SSR (Server-Side Rendering) : Rendering HTML lato server per performance e SEO, supportato da Next.js.
SWR : Libreria React per data fetching con caching, revalidation e optimistic updates.
T
Task Queue : Sistema per gestione job asincroni. Emblema usa Celery con Redis come broker.
Token : Unità base di testo per modelli LLM. Usato per calcolare dimensioni chunk e costi API.
Traefik : Reverse proxy e load balancer con auto-discovery per routing dinamico servizi.
Turbo : Build system per monorepo con caching intelligente e parallelizzazione.
U
uv : Package manager Python moderno e veloce, alternativa a pip/poetry.
V
Vector Database : Database specializzato per storage e ricerca similarità vettori. Emblema usa Milvus.
W
WhisperX : Versione enhanced di OpenAI Whisper con speaker diarization per trascrizione audio.
Workspace : Struttura pnpm per gestire multiple packages in monorepo con dipendenze condivise.
Z
Zod : Libreria TypeScript per schema validation e type inference utilizzata per form validation.
🔤 Acronimi
| Acronimo | Significato | Descrizione |
|---|---|---|
| AI | Artificial Intelligence | Intelligenza Artificiale |
| API | Application Programming Interface | Interfaccia per comunicazione tra software |
| CICD | Continuous Integration/Continuous Deployment | Pipeline automazione build e deploy |
| CORS | Cross-Origin Resource Sharing | Meccanismo sicurezza browser per richieste cross-domain |
| CRUD | Create, Read, Update, Delete | Operazioni base database |
| CSV | Comma-Separated Values | Formato file dati tabellari |
| DX | Developer Experience | Esperienza sviluppatore |
| ENV | Environment | Variabili ambiente per configurazione |
| GPU | Graphics Processing Unit | Processore grafico usato per AI/ML |
| HMR | Hot Module Replacement | Aggiornamento moduli senza reload pagina |
| HTTP | HyperText Transfer Protocol | Protocollo comunicazione web |
| HTTPS | HTTP Secure | HTTP con encryption TLS/SSL |
| JSON | JavaScript Object Notation | Formato dati leggibile |
| JWT | JSON Web Token | Token autenticazione stateless |
| KB | Knowledge Base | Base di conoscenza documenti |
| ML | Machine Learning | Apprendimento automatico |
| ORM | Object-Relational Mapping | Mapping oggetti-database |
| Portable Document Format | Formato documento Adobe | |
| REST | Representational State Transfer | Architettura API web |
| RBAC | Role-Based Access Control | Controllo accessi basato ruoli |
| SBOM | Software Bill of Materials | Lista componenti software |
| SDK | Software Development Kit | Kit sviluppo software |
| SQL | Structured Query Language | Linguaggio query database |
| SSL | Secure Sockets Layer | Protocollo sicurezza (ora TLS) |
| TLS | Transport Layer Security | Protocollo sicurezza moderne |
| TTS | Text-To-Speech | Sintesi vocale da testo |
| STT | Speech-To-Text | Trascrizione vocale in testo |
| UI | User Interface | Interfaccia utente |
| URL | Uniform Resource Locator | Indirizzo risorsa web |
| UUID | Universally Unique Identifier | Identificatore univoco |
| VLM | Vision Language Model | Modello AI per testo+immagini |
| VM | Virtual Machine | Macchina virtuale |
| WSL | Windows Subsystem for Linux | Linux su Windows |
| YAML | Yet Another Markup Language | Formato configurazione human-readable |
🏢 Termini Dominio Emblema
Agente : Configurazione personalizzata di un modello AI con prompt, parametri e tool specifici.
Chunk : Unità minima di contenuto indicizzato per ricerca, con metadata e embedding associato.
Documento : File caricato e processato nel sistema, può essere PDF, TXT, MD, MP3, MP4.
Elaborazione : Task di processamento documento che include ottimizzazione, chunking ed embedding.
Knowledge Base : Contenitore logico per documenti correlati con permessi e configurazioni condivise.
Manifest : File JSON che traccia processing history e artifacts di un documento in MinIO.
Preset Chunking : Configurazione predefinita ottimizzata per tipo contenuto (meeting, technical, qa, etc).
Template : Configurazione riutilizzabile per agenti o elaborazioni con parametri predefiniti.
Task : Job asincrono processato da Celery con progress tracking e risultati.
💡 Tip: Questo glossario è in continua evoluzione. Suggerisci nuovi termini aprendo una issue!