README.md

---
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

![Python](https://img.shields.io/badge/python-3.13-blue)
![FastAPI](https://img.shields.io/badge/framework-FastAPI-009688)
![Streamlit](https://img.shields.io/badge/UI-Streamlit-FF4B4B)
![Neo4j](https://img.shields.io/badge/graphdb-Neo4j-green)
![LLM](https://img.shields.io/badge/LLM-Groq%20%7C%20Llama%203-black)
![Status](https://img.shields.io/badge/status-Phase%201%20Completed-success)

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

```text
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:

```env
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

```bash
# 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:

```bash
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:

```bash
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