README.md

metadata

license: apache-2.0
title: Automated Semantic Discovery
sdk: docker
colorFrom: blue
colorTo: red
pinned: false
emoji: 🧠
short_description: Neurosymbolic prototype for automatic semantic discovery

Automated Semantic Discovery – Prototype

Questo repository contiene un prototipo avanzato per la scoperta semantica automatica (Automated Semantic Discovery). Il sistema agisce come un microservizio finalizzato alla generazione di ontologie authoritative e Knowledge Graphs a partire da testo non strutturato.

Nasce come strumento abilitante per scenari aziendali e di BPO, dove l'estrazione massiva di dati deve coniugarsi con il rigore dei vocabolari semantici formali (es. ArCo, OntoPiA, CIDOC-CRM).

Il progetto espone una doppia interfaccia:

1. API REST (FastAPI): Ideale per l'integrazione asincrona e l'orchestrazione da parte di backend esterni ad alte prestazioni (es. Go/Java).
2. Web UI (Streamlit): Un'interfaccia interattiva, perfetta per demo, test curati e visualizzazione topologica del grafo.

Il Paradigma Neuro-Simbolico

Il progetto supera i limiti dei tradizionali sistemi RAG o delle semplici estrazioni LLM implementando una pipeline ibrida:

• Neuro (AI Generativa & Vettoriale): Sfrutta la comprensione del testo dei Large Language Models (tramite Groq/Llama 3) e il clustering semantico basato su embedding spaziali (sentence-transformers).
• Symbolic (Logica Deterministica): Applica regole algoritmiche rigide per la validazione ontologica (SHACL via pyshacl), il Type-Driven Domain Traversal (TDDT) e l'Entity Linking formale.

Workflow Architetturale (Fase 1)

La pipeline elabora i dati in memoria ed è orchestrata in moduli sequenziali indipendenti:

1. Semantic Chunking (semantic_splitter.py)

Segmentazione dinamica del testo basata su cosine similarity vettoriale. L'algoritmo calcola i percentili di distanza per individuare i reali "punti di rottura" argomentativi, garantendo chunk semanticamente coesi.

2. Type-Driven Domain Traversal - TDDT (extractor.py)

Estrazione relazionale a "imbuto" in due passaggi (Pass 1: Macro-Categorizzazione e Specializzazione; Pass 2: Estrazione Relazionale). Il modello linguistico è vincolato tramite Structured Outputs (Pydantic JSON Schema) a utilizzare esclusivamente gli URI presenti nel Domain Index, azzerando le allucinazioni sui tipi.

3. Hybrid Entity Resolution (entity_resolver.py)

• Deduplica locale in RAM tramite clustering spaziale (DBSCAN).
• Normalizzazione del "Label Bloat" tramite algoritmi di Majority Voting sui tipi ontologici.
• Risoluzione globale sui Vector Index nativi di Neo4j.
• Entity Linking asincrono tramite chiamate REST all'API di Wikidata per l'ancoraggio a concetti universali (owl:sameAs).

4. SHACL Blocking & Validation (validator.py & build_schema.py)

Costruzione automatica di vincoli SHACL a partire dal dizionario ontologico. Durante l'estrazione, un reasoner OWL RL convalida la conformità (Domain/Range) delle triple. Le triple invalide vengono deviate su una DLQ (Dead Letter Queue) in MongoDB per non corrompere il grafo principale.

5. Graph Persistence (graph_loader.py)

Salvataggio massivo transazionale (UNWIND Cypher) su database a grafo Neo4j, includendo tracciabilità della fonte (evidence, reasoning) per garantire la massima Explainability.

Struttura del repository

prototipo/
│
├── assets/
│   └── style.css
│
├── ontology/
│   ├── domain_index.json         # Indice gerarchico delle ontologie (JSON)
│   └── shapes/
│       └── auto_constraints.ttl  # Regole SHACL autogenerate
│
├── src/
│   ├── ingestion/
│   │   └── semantic_splitter.py
│   ├── extraction/
│   │   └── extractor.py
│   ├── validation/
│   │   └── validator.py
│   └── graph/
│       ├── graph_loader.py
│       └── entity_resolver.py
│
├── app.py                  # Entrypoint Web UI (Streamlit)
├── api.py                  # Entrypoint API REST (FastAPI)
├── build_schema.py         # Script per la generazione di index e shapes SHACL
├── Dockerfile              # Configurazione container
├── .env.example            
├── requirements.txt        
└── README.md

Tech Stack & Requisiti

• Linguaggio: Python 3.13
• Database: Neo4j (Graph), MongoDB (DLQ)
• Interfacce: FastAPI, Uvicorn, Streamlit
• Core Libraries:
  • Neuro : langchain, langchain-huggingface, langchain-groq, scikit-learn
  • Symbolic : neo4j, rdflib, pyshacl, pydantic

Le dipendenze complete sono elencate in requirements.txt.

Configurazione Locale

Per testare il sistema in locale, creare un file .env a partire dal template:

NEO4J_URI=neo4j+s://<tuo-cluster>.databases.neo4j.io
NEO4J_USER=neo4j
NEO4J_PASSWORD=la_tua_password
MONGO_URI=mongodb://localhost:27017/
GROQ_API_KEY=tua_api_key_groq
ONTOLOGY_PATH=./ontology

Installazione ed Esecuzione

# 1. Clona il repository
git clone [https://github.com/](https://github.com/)<username>/<repository>.git
cd prototipo

# 2. Crea l'ambiente virtuale e attivalo
python -m venv venv
source venv/bin/activate      # Linux / macOS
# venv\Scripts\activate       # Windows

# 3. Installa le dipendenze
pip install -r requirements.txt

# 4. Genera gli indici ontologici (una tantum)
python build_schema.py

Modalità 1: Web UI (Streamlit)

Avvia la dashboard interattiva per visualizzare il grafo e testare l'estrazione:

streamlit run app.py

L'interfaccia sarà disponibile su http://localhost:8501.

Modalità 2: API REST Headless

Avvia il motore in ascolto per l'orchestrazione backend:

python api.py

L'endpoint sarà disponibile su http://0.0.0.0:5000/api/discover.

Output dell'API

Il sistema produce una risposta JSON strutturata contenente:

• Statistiche di esecuzione (tempo, chunk elaborati).
• Esito della validazione SHACL.
• La lista completa delle triple riconciliate e validate.
• Il feedback di avvenuto inserimento massivo su Neo4j.

Limiti noti

• Rate Limiting Wikidata: Le chiamate di Entity Linking dipendono dai tempi di risposta dell'API pubblica di Wikidata; per ingestion intensive è consigliato l'uso di cache locali stratificate.
• Dipendenza da Vocabolari: L'accuratezza dell'estrazione semantica tramite Schema-RAG fluttua in base alla ricchezza descrittiva del dizionario JSON ontologico fornito in ingresso.

Riferimenti

Automated Semantic Discovery – Generazione Neuro-Simbolica di Ontologie Leggere e Vocabolari Semantici
Gaetano Parente, Dicembre 2025

Autore

Gaetano Parente
Activa Digital – NextGenTech