Update README.md

README.md

@@ -1,19 +1,197 @@
----
-title: AutomatedSemanticDiscovery
-emoji: 🚀
-colorFrom: red
-colorTo: red
-sdk: docker
-app_port: 8501
-tags:
-- streamlit
-pinned: false
-short_description: 'prototipo di sistema per la scoperta semantica automatica '
----
-
-# Welcome to Streamlit!
-
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
-
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+# Automated Semantic Discovery – Prototype
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Neo4j](https://img.shields.io/badge/graphdb-Neo4j-green)
+![Status](https://img.shields.io/badge/status-research%20prototype-orange)
+
+Questo repository contiene un **prototipo di sistema per la scoperta semantica automatica (Automated Semantic Discovery)**, finalizzato alla generazione di **ontologie leggere** e **vocabolari semantici** a partire da **corpora documentali non strutturati**.
+
+Il progetto nasce come **proof-of-concept di ricerca** e implementa una **pipeline neuro-simbolica** che integra:
+
+- la potenza rappresentazionale dei **modelli vettoriali** (*Neuro*);
+- regole di **estrazione ed inferenza NLP** (*Symbolic*).
+
+## Obiettivi del prototipo
+
+Il prototipo ha i seguenti obiettivi principali:
+
+- dimostrare la fattibilità di una **pipeline automatizzata di Semantic Knowledge Discovery**;
+- ridurre il **knowledge acquisition bottleneck** nella costruzione di grafi di conoscenza;
+- validare un **approccio modulare e scalabile** alla scoperta semantica;
+- fornire una **base sperimentale per architetture GraphRAG**.
+
+> Il sistema **non è un prodotto industriale**, ma un **laboratorio sperimentale orientato alla ricerca applicata**.
+
+## Workflow Architetturale
+
+<p align="center">
+  <img src="docs/workflow.png" alt="Workflow Architetturale della Pipeline Neuro-Simbolica" width="90%">
+</p>
+
+## Moduli della Pipeline
+
+La pipeline è organizzata in **moduli indipendenti e sequenziali**.
+
+### 1. Ingestion & Pre-processing
+
+- Caricamento dei documenti testuali.
+- Normalizzazione e pulizia del testo.
+
+### 2. Semantic Chunking (Componente *Neuro*)
+
+- Segmentazione del testo basata su **similarità semantica vettoriale**, non solo sintattica.
+- Utilizzo di **modelli di embedding** per garantire la coerenza tematica dei frammenti.
+
+### 3. Information Extraction (Componente *Simbolica*)
+
+- Estrazione di **entità (NER)** e **relazioni** tramite analisi delle dipendenze sintattiche.
+- Produzione di **strutture intermedie** sotto forma di **triple concettuali (Soggetto–Predicato–Oggetto)**.
+
+### 4. Knowledge Graph Construction
+
+- Mapping delle triple estratte nel **modello a grafo**.
+- Persistenza su **database a grafo (Neo4j)**.
+
+## Struttura del repository
+
+```text
+prototipo/
+│
+├── data/
+│   ├── raw/                # Documenti di input grezzi
+│   ├── processed/          # Output intermedi (chunk, debug JSON)
+│   └── gold_standard/      # Esempi e dati di riferimento
+│
+├── src/
+│   ├── ingestion/
+│   │   └── semantic_splitter.py
+│   ├── extraction/
+│   │   └── extractor.py
+│   └── graph/
+│       └── graph_builder.py
+│
+├── neo4j/                  # Script o Docker Compose per il DB
+├── .env.example            # Template per le variabili d'ambiente
+├── requirements.txt
+└── README.md
+```
+
+## Tech Stack & Requisiti
+
+- **Linguaggio**: Python 3.10+
+- **Database**: Neo4j (Community / Enterprise)
+
+### Core Libraries
+
+- **Neuro / Vectors**  
+  `sentence-transformers`, `scikit-learn`
+
+- **NLP / Symbolic**  
+  `spacy`, `nltk`
+
+- **Data & Graph**  
+  `pandas`, `neo4j-driver`
+
+> Le dipendenze complete sono elencate in `requirements.txt`.
+
+## Configurazione
+
+Creare un file `.env` nella root del progetto:
+
+```env
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=la_tua_password_locale
+```
+
+**Nota**: assicurarsi che il file `.env` sia incluso nel `.gitignore`.
+
+## Installazione
+
+```bash
+git clone https://github.com/<username>/<repository>.git
+cd prototipo
+
+python -m venv venv
+source venv/bin/activate      # Linux / macOS
+# venv\\Scripts\activate   # Windows
+
+pip install -r requirements.txt
+```
+
+## Utilizzo del prototipo
+
+### 1. Inserimento dei documenti
+
+Copiare i documenti in `data/raw/`.
+
+### 2. Segmentazione semantica
+
+```bash
+python src/ingestion/semantic_splitter.py
+```
+
+### 3. Estrazione di entità e relazioni
+
+```bash
+python src/extraction/extractor.py
+```
+
+### 4. Costruzione del Knowledge Graph
+
+```bash
+python src/graph/graph_builder.py
+```
+
+## Output
+
+Il sistema produce:
+
+- file JSON intermedi per il tracciamento e il debug della pipeline;
+- dati strutturati utilizzabili per validazione manuale o semi-automatica;
+- un Knowledge Graph persistente su Neo4j, interrogabile tramite Cypher.
+
+## Risultati e Validazione Visiva
+
+Questa sezione mostra alcuni output significativi del prototipo, 
+utilizzati per la validazione qualitativa della pipeline di scoperta semantica.
+
+### Validazione delle estrazioni
+
+<p align="center">
+  <img src="docs/validation.png" alt="Validazione delle entità estratte" width="90%">
+</p>
+
+Lo screenshot mostra esempi di entità e relazioni estratte a partire dai chunk semantici,
+utilizzati per verificare la correttezza e la coerenza delle triple generate.
+
+### Visualizzazione del Knowledge Graph
+
+<p align="center">
+  <img src="docs/graph.png" alt="Grafo risultante su Neo4j" width="90%">
+</p>
+
+Il grafo risultante è persistito su Neo4j ed esplorabile tramite Neo4j Browser,
+consentendo l’analisi interattiva delle entità e delle relazioni scoperte.
+
+## Limiti noti
+
+- **Scalabilità**: prototipo non ottimizzato per ingestione massiva.
+- **Reasoning**: regole simboliche basate su euristiche, dominio-dipendenti.
+- **LLM**: uso intenzionalmente limitato per privilegiare determinismo e spiegabilità.
+
+## Possibili estensioni future
+
+- Integrazione LLM / GraphRAG
+- Supporto RDF / OWL / SHACL
+- Dockerizzazione
+
+## Riferimenti
+
+**Automated Semantic Discovery – Generazione Neuro-Simbolica di Ontologie Leggere e Vocabolari Semantici**  
+Gaetano Parente, Dicembre 2025
+
+## Autore
+
+**Gaetano Parente**  
+Activa Digital – NextGenTech