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