riviste le varie sezioni e i commenti

api.py

@@ -4,6 +4,7 @@ import uvicorn
 import os
 import time
 import hashlib
+from contextlib import asynccontextmanager
 
 from src.ingestion.semantic_splitter import ActivaSemanticSplitter
 from src.extraction.extractor import NeuroSymbolicExtractor
@@ -11,27 +12,45 @@ from src.validation.validator import SemanticValidator
 from src.graph.graph_loader import KnowledgeGraphPersister
 from src.graph.entity_resolver import EntityResolver
 
+# --- GESTORE DEGLI STATI GLOBALI ---
+# Usiamo un dizionario globale per tenere in RAM i pesi dei modelli. 
+ml_models = {}
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Nel mondo FastAPI il lifespan è il modo più pulito per fare il setup. 
+    # Mi permette di caricare i modelli di embedding e l'LLM all'avvio del worker, una sola volta.
+    print("⏳ Inizializzazione modelli (SentenceTransformers e Llama3) nel Lifespan...")
+    
+    ml_models["splitter"] = ActivaSemanticSplitter(model_name="all-MiniLM-L6-v2")
+    
+    schema_path = os.path.join("data", "schemas", "ARCO_schema.json")
+    ml_models["extractor"] = NeuroSymbolicExtractor(model_name="llama3", schema_path=schema_path)
+    
+    ml_models["persister"] = KnowledgeGraphPersister()
+    ml_models["resolver"] = EntityResolver(neo4j_driver=ml_models["persister"].driver, similarity_threshold=0.85)
+    ml_models["validator"] = SemanticValidator()
+    
+    print("✅ Modelli caricati e pronti a ricevere richieste!")
+    
+    yield # Qui l'API inizia ad ascoltare le chiamate in ingresso
+    
+    # Chiusura pulita delle connessioni. Evita query appese su Neo4j quando killiamo il container.
+    print("🛑 Spegnimento in corso... chiusura connessioni e pulizia memoria.")
+    if "persister" in ml_models and ml_models["persister"]:
+        ml_models["persister"].close() 
+    ml_models.clear()
+
 app = FastAPI(
     title="Automated Semantic Discovery API", 
     description="Endpoint per l'ingestion testuale e l'estrazione neuro-simbolica",
-    version="1.0"
+    version="1.0",
+    lifespan=lifespan
 )
 
-# Struttura del JSON in ingresso
 class DiscoveryRequest(BaseModel):
     documentText: str
 
-# Carico i pesi dei modelli all'avvio del server (Warm-up)
-print("⏳ Inizializzazione modelli (SentenceTransformers e Llama3)...")
-splitter = ActivaSemanticSplitter(model_name="all-MiniLM-L6-v2")
-schema_path = os.path.join("data", "schemas", "ARCO_schema.json")
-extractor = NeuroSymbolicExtractor(model_name="llama3", schema_path=schema_path)
-persister = KnowledgeGraphPersister()
-resolver = EntityResolver(neo4j_driver=persister.driver, similarity_threshold=0.85)
-validator = SemanticValidator()
-print("✅ Modelli caricati e pronti a ricevere richieste!")
-
-# Endpoint principale
 @app.post("/api/discover")
 def run_discovery(payload: DiscoveryRequest):
     start_time = time.time()
@@ -40,10 +59,19 @@ def run_discovery(payload: DiscoveryRequest):
     if not raw_text or not raw_text.strip():
         raise HTTPException(status_code=400, detail="Il testo fornito è vuoto.")
 
+    # Recupero le istanze
+    splitter = ml_models["splitter"]
+    extractor = ml_models["extractor"]
+    validator = ml_models["validator"]
+    resolver = ml_models["resolver"]
+    persister = ml_models["persister"]
+
     # --- FASE 1: INGESTION ---
+    # Taglio il testo in modo semantico per non sforare la context window dell'LLM
     chunks, _, _ = splitter.create_chunks(raw_text, percentile_threshold=90)
     
     # --- FASE 2: EXTRACTION ---
+    # Invocazione del motore neuro-simbolico per ogni blocco di testo
     all_triples = []
     all_entities = []
     for i, chunk in enumerate(chunks):
@@ -60,10 +88,11 @@ def run_discovery(payload: DiscoveryRequest):
         return {
             "status": "success", 
             "message": "Nessuna entità trovata.", 
-            "graph_data": [] # Restituisco un array vuoto invece di fallire
+            "graph_data": []
         }
 
     # --- FASE 2.1: SYMBOLIC RESOLUTION ---
+    # Deduplica in RAM e linking verso Wikidata e Neo4j (Entity Resolution)
     entities_to_save = []
     try:
         all_entities, all_triples, entities_to_save = resolver.resolve_entities(all_entities, all_triples)
@@ -71,10 +100,11 @@ def run_discovery(payload: DiscoveryRequest):
         print(f"⚠️ Errore nel resolver (skip): {e}")
 
     # --- FASE 2.2: VALIDATION ---
+    # Prima di salvare nel DB, verifico con SHACL 
+    # se l'LLM ha generato allucinazioni o violato i vincoli dell'ontologia.
     is_valid, report, _ = validator.validate_batch(entities_to_save, all_triples)
     if not is_valid:
         print("\n❌ [SHACL VALIDATION FAILED] Rilevate entità o relazioni non conformi all'ontologia:")
-        # Il report di pyshacl contiene già l'elenco esatto dei nodi e delle regole violate
         print(report)
         print("-" * 60)
     else:
@@ -83,10 +113,10 @@ def run_discovery(payload: DiscoveryRequest):
     # --- FASE 3: PERSISTENCE (Neo4j) ---
     try:
         persister.save_entities_and_triples(entities_to_save, all_triples)
-        persister.close()
     except Exception as e:
         print(f"⚠️ Errore salvataggio Neo4j: {e}")
 
+    # Preparazione payload di risposta
     graph_data = []
     for t in all_triples:
         subj = getattr(t, 'subject', t[0] if isinstance(t, tuple) else str(t))
@@ -102,7 +132,7 @@ def run_discovery(payload: DiscoveryRequest):
         pred_str = str(pred)
         obj_str = str(obj)
 
-        # Genero un ID univoco ma stabile per il nodo di partenza basato sul suo nome.
+        # Genero un ID stabile per facilitare il rendering dei nodi lato client
         node_id = hashlib.md5(subj_str.encode('utf-8')).hexdigest()
 
         graph_data.append({
@@ -124,4 +154,4 @@ def run_discovery(payload: DiscoveryRequest):
     }
 
 if __name__ == "__main__":
-    uvicorn.run(app, host="0.0.0.0", port=5000)
+    uvicorn.run("api:app", host="0.0.0.0", port=5000, reload=True)

data/schemas/arco_schema.json

@@ -1,42 +0,0 @@
-[
-  {
-    "id": "arco:CulturalProperty",
-    "type": "Class",
-    "description": "Qualsiasi bene culturale, materiale o immateriale. Include monumenti, reperti archeologici, statue, dipinti, edifici storici, strade antiche come la Via Appia."
-  },
-  {
-    "id": "cis:CulturalInstituteOrSite",
-    "type": "Class",
-    "description": "Un istituto o luogo della cultura. Include musei, archivi, biblioteche, parchi archeologici, complessi monumentali."
-  },
-  {
-    "id": "l0:Location",
-    "type": "Class",
-    "description": "Un'entità geografica o amministrativa. Include città, comuni, regioni, nazioni, fiumi, o aree topografiche."
-  },
-  {
-    "id": "core:Event",
-    "type": "Class",
-    "description": "Un evento storico, una battaglia, una mostra, una scoperta archeologica o una campagna di scavo."
-  },
-  {
-    "id": "a-loc:hasCurrentLocation",
-    "type": "Property",
-    "description": "Collega un bene culturale al luogo fisico o all'istituto (es. un museo) in cui è attualmente conservato o esposto."
-  },
-  {
-    "id": "core:hasPart",
-    "type": "Property",
-    "description": "Indica che un'entità contiene o è composta da un'altra entità. Utile per indicare che un museo contiene una collezione, o una città contiene un'area."
-  },
-  {
-    "id": "cis:hasSite",
-    "type": "Property",
-    "description": "Collega un istituto culturale (come un museo) alla sua sede fisica o al comune in cui si trova."
-  },
-  {
-    "id": "ti:atTime",
-    "type": "Property",
-    "description": "Collega un evento, una scoperta o un reperto alla sua epoca, data o periodo storico."
-  }
-]

src/extraction/extractor.py

@@ -12,10 +12,10 @@ from langchain_huggingface import HuggingFaceEmbeddings, ChatHuggingFace, Huggin
 from sklearn.metrics.pairwise import cosine_similarity
 from dotenv import load_dotenv
 
+# Carico le variabili d'ambiente. Su HF Spaces non trova il .env ma pesca in automatico dai secrets.
+load_dotenv() 
 
-load_dotenv() # in locale carica il file .env , su HF non trovando il file utilizza i secrets inseriti nella sezione settings.
-
-# --- DEFINIZIONE DELLO SCHEMA ---
+# Modelli Pydantic per blindare l'output dell'LLM. 
 class GraphTriple(BaseModel):
     subject: str = Field(..., description="Entità sorgente.")
     predicate: str = Field(..., description="Relazione (es. arco:hasCurrentLocation).")
@@ -28,13 +28,15 @@ class KnowledgeGraphExtraction(BaseModel):
     entities: List[str] = Field(default_factory=list, description="TUTTE le entità estratte, incluse quelle isolate/orfane.")
     triples: List[GraphTriple]
 
-# --- ESTRATTORE DINAMICO (Schema-RAG) ---
+
 class NeuroSymbolicExtractor:
     def __init__(self, model_name="llama3", temperature=0, schema_path=None):
         
         hf_token = os.getenv("HF_TOKEN")
-        groq_api_key=os.getenv("GROQ_API_KEY")
+        groq_api_key = os.getenv("GROQ_API_KEY")
         
+        # Setup del provider LLM a cascata: do priorità ai servizi cloud ad alte performance,
+        # se mancano le key faccio un fallback sull'istanza locale di Ollama.
         if hf_token:
             print("☁️ Rilevato ambiente Cloud (HF Spaces). Utilizzo HuggingFace Inference API.")
             repo_id = "meta-llama/Meta-Llama-3-8B-Instruct" 
@@ -58,7 +60,7 @@ class NeuroSymbolicExtractor:
                 self.llm = ChatGroq(
                     temperature=0, 
                     model="llama-3.3-70b-versatile",
-                    api_key=os.getenv("GROQ_API_KEY")
+                    api_key=groq_api_key
                 )
             except Exception as e:
                 print(f"❌ Errore Groq API {e}")           
@@ -74,67 +76,71 @@ class NeuroSymbolicExtractor:
             except Exception as e:
                  print(f"⚠️ Errore Ollama: {e}")
 
-        # Modello Embedding per la selezione dinamica
+        # Carico il modello leggero per fare l'embedding delle query e matchare l'ontologia al volo
         print("🧠 Caricamento modello embedding per Dynamic Selection...")
         self.embedding_model = HuggingFaceEmbeddings(model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")
 
-        # Caricamento vocabolario ontologico
         self.ontology_elements = []
         self.ontology_embeddings = None
         
+        # Se ho passato il dizionario json generato da ArCo, lo calcolo e lo tengo in RAM
         if schema_path and os.path.exists(schema_path):
             print(f"🌟 Indicizzazione vettoriale Ontologia da: {schema_path}")
             self._index_ontology(schema_path)
 
-        # Template Specializzato con regole di Graceful Degradation
-        self.system_template_base = """Sei un Agente Cognitivo per l'estrazione dati (Information Extraction).
+        # Prompt di sistema: le regole di Graceful Degradation qui sono critiche
+        # altrimenti il modello inizia a inventare predicati e inquina il grafo.
+        self.system_template_base = """Sei un esperto di Ingegneria della Conoscenza specializzato nell'Ontologia ArCo (Patrimonio Culturale Italiano).
         Il tuo compito è analizzare il testo e generare un JSON contenente entità e relazioni.
         
         REGOLE FONDAMENTALI:
-        1. Estrai TUTTI i concetti rilevanti e inseriscili nell'array "entities" (anche se non sai come collegarli).
-        2. Per creare le "triples", puoi usare ESCLUSIVAMENTE le seguenti Classi (per rdf:type) e Proprietà che sono pertinenti a questo testo:
+        1. Estrai TUTTI i reperti, luoghi, materiali, tecniche, concetti e persone e inseriscili nell'array "entities".
+        2. Crea le "triples" usando ESCLUSIVAMENTE le seguenti Classi (per rdf:type) e Proprietà, recuperate dall'ontologia:
         
-        CLASSI CONSENTITE (usa come oggetto quando predicate = rdf:type):
+        CLASSI ARCO CONSENTITE (da usare come oggetto quando predicate = rdf:type):
         {retrieved_classes}
         
-        PROPRIETÀ CONSENTITE (usa come predicate):
+        PROPRIETÀ ARCO CONSENTITE (da usare come predicate):
         {retrieved_properties}
         
-        REGOLE DI GRACEFUL DEGRADATION E ANTI-ALLUCINAZIONE (CRITICO):
-        - Relazioni (Fallback): Se due entità sono correlate ma nessuna delle proprietà fornite è adatta al contesto esatto, non inventare predicati. Usa il predicato 'skos:related'.
-        - Classificazione (rdf:type): Se non trovi una Classe specifica esatta tra quelle fornite per tipizzare un'entità, NON FORZARE la classificazione in classi errate. Usa i tipi di salvataggio universali: 'core:Agent' per le persone/popoli, 'core:Concept' per concetti astratti/materiali, 'l0:Location' per i luoghi geografici. 
-        - Entità Orfane: Se sei in forte dubbio su come collegare o classificare un'entità testuale, limitati a inserirla nell'array "entities" come orfana senza creare alcuna tripla. Non inquinare il grafo con dati inesatti.
+        REGOLE DI CLASSIFICAZIONE E ANTI-ALLUCINAZIONE (CRITICO):
+        - rdf:type: Sforzati di usare le classi ArCo specifiche fornite sopra (es. 'arco:HistoricOrArtisticProperty', 'cis:ArchaeologicalSite'). 
+        - Divieto di uso improprio di core:Concept: NON classificare materiali (es. marmo), tecniche costruttive (es. opera laterizia) o dettagli architettonici (es. capitello) come 'core:Concept'. Se non c'è una classe perfetta, classificali come 'arco:ArchaeologicalPropertySurveyType' o lasciali nell'array "entities" senza rdf:type.
+        - Usa 'core:Agent' SOLO per persone, famiglie storiche o organizzazioni (es. Antichi Romani, Canova, Imperatore Domiziano).
+        - Relazioni: Se due entità sono connesse ma nessuna delle proprietà fornite descrive il legame in modo accurato, usa il predicato generico 'skos:related'.
         
         Rispondi SOLO ed ESCLUSIVAMENTE con un JSON valido strutturato così:
         {{
             "reasoning": "Breve logica delle estrazioni fatte...",
-            "entities": ["Entità 1", "Entità orfana"],
+            "entities": ["Entità 1", "Entità orfana", "Marmo"],
             "triples": [
-                {{"subject": "Entità 1", "predicate": "rdf:type", "object": "Classe Consentita", "confidence": 0.9}},
-                {{"subject": "Entità 1", "predicate": "Proprietà Consentita", "object": "Entità 2", "confidence": 0.8}}
+                {{"subject": "Entità 1", "predicate": "rdf:type", "object": "arco:HistoricOrArtisticProperty", "confidence": 0.9}},
+                {{"subject": "Entità 1", "predicate": "a-loc:isLocatedIn", "object": "Entità 2", "confidence": 0.8}}
             ]
         }}
         """
 
     def _index_ontology(self, path: str):
+        """Vettorizza le descrizioni delle classi per permettere allo Schema-RAG di pescare solo quelle utili."""
         try:
             with open(path, 'r', encoding='utf-8') as f:
                 self.ontology_elements = json.load(f)
-            # Vettorizziamo le descrizioni semantiche delle classi/proprietà
+            
             texts = [el['description'] for el in self.ontology_elements]
             self.ontology_embeddings = self.embedding_model.embed_documents(texts)
             print(f"✅ Indicizzati {len(self.ontology_elements)} elementi dell'ontologia.")
         except Exception as e:
             print(f"❌ Errore indicizzazione Ontologia: {e}")
 
-    def _retrieve_schema(self, query_text: str, top_k_classes=3, top_k_props=4):
+    def _retrieve_schema(self, query_text: str, top_k_classes=10, top_k_props=8):
+        """Calcola la cosine similarity tra il testo in ingresso e le voci dell'ontologia."""
         if not self.ontology_elements or self.ontology_embeddings is None:
             return "Nessuna classe specifica.", "skos:related"
 
         query_embedding = self.embedding_model.embed_query(query_text)
         similarities = cosine_similarity([query_embedding], self.ontology_embeddings)[0]
         
-        # Ordiniamo gli indici per similarità
+        # Ordino per beccare i match migliori
         sorted_indices = np.argsort(similarities)[::-1]
         
         classes = []
@@ -145,39 +151,43 @@ class NeuroSymbolicExtractor:
             if element["type"] == "Class" and len(classes) < top_k_classes:
                 classes.append(f"- {element['id']}: {element['description']}")
             elif element["type"] == "Property" and len(properties) < top_k_props:
-                properties.append(f"- {element['id']}: {element['description']}")
+                
+                # N.B. Inietto Domain e Range estratti dallo script build_schema 
+                # per dare all'LLM i paletti relazionali esatti.
+                prop_str = f"- {element['id']}: {element['description']}"
+                dom = element.get("domain")
+                rng = element.get("range")
+                
+                if dom or rng:
+                    prop_str += f" [VINCOLO -> Soggetto: {dom or 'Qualsiasi'}, Oggetto: {rng or 'Qualsiasi'}]"
+                    
+                properties.append(prop_str)
                 
         return "\n".join(classes), "\n".join(properties)
 
+
     def extract(self, text_chunk: str, source_id: str = "unknown", max_retries=3) -> KnowledgeGraphExtraction:
         print(f"🧠 Processing {source_id} (Schema-RAG Mode)...")
         
-        # 1. Recupero dinamico dello schema basato sul testo
+        # 1. Recupero dinamico (pesco solo lo schema utile per questo specifico frammento di testo)
         retrieved_classes, retrieved_properties = self._retrieve_schema(text_chunk)
         
-        # 2. Iniezione nel prompt
+        # 2. Inietto i paletti nel system prompt
         final_sys_text = self.system_template_base.format(
             retrieved_classes=retrieved_classes,
             retrieved_properties=retrieved_properties
         )
         
         sys_msg = SystemMessage(content=final_sys_text)
-        
-        prompt = ChatPromptTemplate.from_messages([
-            sys_msg,
-            ("human", "{text}")
-        ])
-        
+        prompt = ChatPromptTemplate.from_messages([sys_msg, ("human", "{text}")])
         chain = prompt | self.llm
         
         for attempt in range(max_retries):
             try:
                 response = chain.invoke({"text": text_chunk})
-                
-                # Parsing della risposta (diversa tra Ollama e HF)
                 content = response.content
                 
-                # Pulizia base se il modello chiacchiera prima del JSON
+                # I LLM a volte ci mettono i backtick markdown anche se chiedi solo JSON puro. Li elimino.
                 if "```json" in content:
                     content = content.split("```json")[1].split("```")[0].strip()
                 elif "```" in content:
@@ -188,11 +198,11 @@ class NeuroSymbolicExtractor:
 
                 data = json.loads(content)
                 
-                # Normalizzazione output
+                # Normalizzo l'output per gestire eventuali fluttuazioni della risposta
                 if isinstance(data, list):
                     validated_data = KnowledgeGraphExtraction(triples=data, reasoning="Direct list output")
                 else:
-                    # Filtra campi extra che il modello potrebbe inventare
+                    # Filtro eventuali chiavi fittizie inventate dal modello per rispettare strettamente Pydantic
                     triples = [GraphTriple(**t) for t in data.get("triples", [])]
                     validated_data = KnowledgeGraphExtraction(
                         reasoning=data.get("reasoning", "N/A"),
@@ -208,7 +218,8 @@ class NeuroSymbolicExtractor:
             except (json.JSONDecodeError, ValidationError) as e:
                 print(f"⚠️ Errore Validazione (Tentativo {attempt+1}/{max_retries}): {e}")
                 
-                # SELF-CORRECTION LOOP
+                # SELF-CORRECTION LOOP: Se l'LLM sbagliaa la struttura del JSON, 
+                # non butto via tutto ma gli rido in pasto l'errore per farglielo correggere.
                 prev_content = locals().get('content', 'No content')
                 
                 correction_prompt = ChatPromptTemplate.from_messages([

src/graph/entity_resolver.py

@@ -6,13 +6,21 @@ from langchain_huggingface import HuggingFaceEmbeddings
 class EntityResolver:
     def __init__(self, neo4j_driver, model_name="all-MiniLM-L6-v2", similarity_threshold=0.85):
         print("🧩 Inizializzazione Entity Resolver Ibrido (Vector Search + Wikidata EL)...")
+        # Uso un modello di embedding ultra-leggero per la risoluzione. Non serve la semantica 
+        # profonda di un LLM qui, mi basta beccare le stringhe molto simili.
         self.embedding_model = HuggingFaceEmbeddings(model_name=model_name)
+        
+        # DBSCAN ragiona in termini di distanza (eps), quindi la deduco dalla soglia di similarità (1 - score)
         self.eps = 1 - similarity_threshold
         self.similarity_threshold = similarity_threshold
         self.driver = neo4j_driver
     
     def _find_canonical_in_db(self, embedding_vector):
-        """Interroga l'indice vettoriale di Neo4j per trovare il nodo più simile."""
+        """
+        Interroga l'indice vettoriale nativo di Neo4j. 
+        Se il nodo esiste già nel grafo globale con un nome leggermente diverso ma 
+        semanticamente quasi identico, ce lo facciamo restituire per evitare sdoppiamenti.
+        """
         if not self.driver: return None
         
         query = """
@@ -30,8 +38,9 @@ class EntityResolver:
 
     def _link_to_wikidata(self, entity_name):
         """
-        Interroga l'API di Wikidata per trovare un match diretto (Entity Linking).
-        Ritorna l'URI di Wikidata (es. wd:Q12345) o None.
+        Chiamata REST a Wikidata (Entity Linking).
+        Ci serve per ancorare i nodi del nostro grafo a concetti universali (es. wd:Q12345).
+        Cruciale per il layer di GraphRAG futuro.
         """
         url = "https://www.wikidata.org/w/api.php"
         params = {
@@ -39,28 +48,28 @@ class EntityResolver:
             "search": entity_name,
             "language": "it",
             "format": "json",
-            "limit": 1 # Prendo solo il best match per la riconciliazione automatica
+            "limit": 1 # Ci serve solo il top-match per fare riconciliazione a tappeto, niente paginazione.
         }
         try:
-            # Timeout breve per non bloccare la pipeline se Wikidata è lento
+            # Metto un timeout super restrittivo (3s). Se Wikidata è congestionato, 
+            # preferisco fallire silenziosamente il linking piuttosto che bloccare tutta l'ingestion della pipeline.
             response = requests.get(url, params=params, timeout=3.0)
             if response.status_code == 200:
                 data = response.json()
-                if not data.get("search"):
-                    print(f"   [DEBUG] Wikidata non ha trovato corrispondenze per: '{entity_name}'")
-                    
                 if data.get("search"):
                     best_match = data["search"][0]
                     return f"wd:{best_match['id']}"
+                else:
+                    print(f"   [DEBUG] Wikidata non ha trovato corrispondenze per: '{entity_name}'")    
         except Exception as e:
-            print(f"   ⚠️ Errore lookup Wikidata per '{entity_name}': {e}")
+            print(f"   ⚠️ Errore lookup Wikidata per '{entity_name}' (ignorato): {e}")
         return None
 
     def resolve_entities(self, extracted_entities, triples):
         if not triples and not extracted_entities:
-            return [], []
+            return [], [], []
 
-        # Raccolgo tutte le entità uniche dal chunk corrente
+        # 1. Raccoglitore: Metto a fattor comune tutte le entità del chunk di testo appena processato
         chunk_entities = set(extracted_entities)
         for t in triples:
             chunk_entities.add(t.subject)
@@ -68,12 +77,14 @@ class EntityResolver:
         unique_chunk_entities = list(chunk_entities)
 
         if not unique_chunk_entities:
-            return [], triples
+            return [], triples, []
 
-        # Calcolo gli embedding per il batch locale
+        # Embedding massivo di tutte le entità isolate in questo chunk
         embeddings = self.embedding_model.embed_documents(unique_chunk_entities)
         
-        # Local Batch Deduplication
+        # 2. DEDUPLICA LOCALE IN RAM (DBSCAN)
+        # Se nel testo l'LLM ha estratto sia "Canova" che "Antonio Canova", 
+        # li collassiamo in un solo cluster prima ancora di toccare il database.
         clustering = DBSCAN(eps=self.eps, min_samples=1, metric='cosine').fit(np.array(embeddings))
         
         local_cluster_map = {}
@@ -83,25 +94,25 @@ class EntityResolver:
             local_cluster_map[label].append({"name": entity, "embedding": emb})
 
         entity_replacement_map = {}
-        entities_to_save = [] # Array di {label, embedding, wikidata_sameAs}
+        entities_to_save = [] # Struttura per il loader Neo4j: {label, embedding, wikidata_sameAs}
 
-        # Global Database Resolution & Wikidata Linking
+        # 3. RISOLUZIONE GLOBALE & ENTITY LINKING
         for label, items in local_cluster_map.items():
+            # Tra le varianti locali, eleggo come canonica provvisoria la stringa più lunga (es. "Tempio di Giove" batte "Tempio")
             local_canonical_item = sorted(items, key=lambda x: len(x["name"]), reverse=True)[0]
             local_canonical_name = local_canonical_item["name"]
             local_canonical_emb = local_canonical_item["embedding"]
 
+            # Guardo se il database conosce già qualcosa di molto simile
             db_canonical_name = self._find_canonical_in_db(local_canonical_emb)
 
             if db_canonical_name:
-                # Caso A: Neo4j conosce già questa entità (ha già il suo embedding e potenziale URI)
+                # Caso A: Entità già nota. Faccio override col nome che Neo4j conosce già per evitare biforcazioni.
                 final_canonical = db_canonical_name
                 print(f"   🔗 Match Globale: '{local_canonical_name}' -> '{db_canonical_name}' (Neo4j)")
             else:
-                # Caso B: È un'entità veramente nuova. Tento l'Entity Linking!
+                # Caso B: Entità inedita. Provo a darle una "carta d'identità" agganciandola a Wikidata.
                 final_canonical = local_canonical_name
-                
-                # Chiamata a Wikidata
                 wikidata_uri = self._link_to_wikidata(final_canonical)
                 
                 entity_dict = {
@@ -117,11 +128,12 @@ class EntityResolver:
                     
                 entities_to_save.append(entity_dict)
 
-            # Mappo le varianti locali al canonico
+            # Costruisco la mappa di traduzione per tutte le varianti sporche di questo cluster
             for item in items:
                 entity_replacement_map[item["name"]] = final_canonical
 
-        # Riscrittura Output
+        # 4. RISCRITTURA FINALE (Output pulito)
+        # Sostituisco i nomi vecchi/sporchi con il canonico definitivo prima di passare il blocco al validatore SHACL
         resolved_triples = []
         for t in triples:
             t.subject = entity_replacement_map.get(t.subject, t.subject)

src/graph/graph_loader.py

@@ -3,13 +3,12 @@ from collections import defaultdict
 from neo4j import GraphDatabase
 from dotenv import load_dotenv
 
-load_dotenv() # in locale carica il file .env , su HF non trovando il file utilizza i secrets inseriti nella sezione settings.
+# Carico le env vars. Su HF Spaces pesca in automatico dai secrets.
+load_dotenv() 
 
 class KnowledgeGraphPersister:
     def __init__(self):
-        """
-        Inizializza il driver Neo4j e crea i vincoli necessari per le performance.
-        """
+        # Setup della connessione a Neo4j. 
         uri = os.getenv("NEO4J_URI")
         user = os.getenv("NEO4J_USER")
         password = os.getenv("NEO4J_PASSWORD")
@@ -19,7 +18,8 @@ class KnowledgeGraphPersister:
             self.driver.verify_connectivity()
             print(f"✅ Connesso a Neo4j ({uri}).")
             
-            # Creazione indici all'avvio (Fondamentale per la velocità dei MERGE)
+            # Chiamo subito la creazione degli indici. Se partiamo a fare ingestion massiva 
+            # senza constraint, il DB collassa al primo blocco di MERGE.
             self._create_constraints()
             
         except Exception as e:
@@ -27,16 +27,18 @@ class KnowledgeGraphPersister:
             self.driver = None
 
     def close(self):
+        # Chiudo pulito il driver (chiamato nel lifecycle shutdown dell'API)
         if self.driver:
             self.driver.close()
 
     def _create_constraints(self):
-        """
-        Crea un vincolo di unicità sulla proprietà URI.
-        Senza questo, MERGE diventa lentissimo (Full Table Scan).
-        """
         if not self.driver: return
+        
+        # Senza questo vincolo UNIQUE, l'istruzione MERGE fa un Full Table Scan ogni volta.
+        # Fondamentale per mantenere le transazioni < 10ms anche con migliaia di nodi.
         query = "CREATE CONSTRAINT resource_uri_unique IF NOT EXISTS FOR (n:Resource) REQUIRE n.uri IS UNIQUE"
+        
+        # Indice vettoriale nativo per le ricerche di similarità (dimensionato a 384 per matchare all-MiniLM)
         query_vector = """
         CREATE VECTOR INDEX entity_embeddings IF NOT EXISTS 
         FOR (n:Resource) ON (n.embedding) 
@@ -59,40 +61,30 @@ class KnowledgeGraphPersister:
                 print(f"⚠️ Warning vector index: {e}")
 
     def sanitize_name(self, name):
-        """
-        Canonicalization base.
-        """
+        # Canonicalizzazione molto base: sostituisco spazi inutili e tolgo gli apici che spaccano le query Cypher.
         if not name: return "Unknown"
-        # Rimuove spazi extra e normalizza.
         return name.strip().replace(" ", "_").replace("'", "").replace('"', "")
 
     def sanitize_predicate(self, pred):
-        """
-        Pulisce il predicato per evitare Cypher Injection.
-        """
+        # Cruciale per evitare Cypher Injection. In Cypher NON si può parametrizzare 
+        # il tipo di relazione in un MERGE (es. non puoi fare -[r:$pred]-). Devo per forza 
+        # iniettarlo nella stringa della query, quindi lo normalizzo in modo drastico.
         if not pred: return "RELATED_TO"
         
-        # Normalizzazione preliminare dei separatori comuni
-        # Sostituisco i due punti dei namespace e trattini con underscore
         pred = pred.replace(":", "_").replace("-", "_").replace(" ", "_")
-        
-        # Rimozione caratteri non sicuri (mantiene solo alfanumerici e underscore)
         clean = "".join(x for x in pred if x.isalnum() or x == "_")
         
-        # Conversione in uppercase (convenzione Neo4j per Relationships)
+        # Convenzione Neo4j: le relationships sono sempre in UPPERCASE
         return clean.upper() if clean else "RELATED_TO"
 
     def save_triples(self, triples):
-        """
-        Salva le triple usando VERO Batching (UNWIND).
-        Raggruppa le triple per predicato per aggirare il limite di parametrizzazione delle relazioni.
-        """
         if not self.driver or not triples:
             return
 
         print(f"💾 Preparazione Batch di {len(triples)} triple...")
 
-        # Raggruppamento per Predicato
+        # Visto che non posso parametrizzare il predicato nella query Cypher,
+        # raggruppo le triple per tipo di relazione e lancio un batch per ognuna.
         batched_by_pred = defaultdict(list)
         
         for t in triples:
@@ -108,7 +100,6 @@ class KnowledgeGraphPersister:
             }
             batched_by_pred[safe_pred].append(item)
 
-        # Esecuzione Transazioni (Una per tipo di relazione)
         with self.driver.session() as session:
             for pred, data_list in batched_by_pred.items():
                 try:
@@ -120,14 +111,13 @@ class KnowledgeGraphPersister:
         print("✅ Salvataggio completato.")
 
     def save_entities_and_triples(self, entities_to_save, triples):
-        """Salva prima i nodi isolati (con i loro vettori), poi le relazioni."""
         if not self.driver: return
 
-        # Salvataggio Nodi (anche senza relazioni, includendo l'embedding)
+        # Ingestion a 2 step: prima butto dentro i nodi isolati con tutti i loro payload
+        # (embedding vettoriali e link a Wikidata), poi in un secondo momento ci aggancio sopra le relazioni.
         if entities_to_save:
             print(f"💾 Salvataggio di {len(entities_to_save)} nodi singoli con vettori...")
             
-            # Aggiungo il campo "uri" calcolandolo dalla label
             node_batch = []
             for item in entities_to_save:
                 item["uri"] = self.sanitize_name(item["label"])
@@ -136,12 +126,13 @@ class KnowledgeGraphPersister:
             with self.driver.session() as session:
                 session.execute_write(self._unwind_write_nodes, node_batch)
 
-        # Salvataggio Triple
         if triples:
             self.save_triples(triples)
 
     @staticmethod
     def _unwind_write_nodes(tx, batch_data):
+        # L'UNWIND è l'unico modo per fare VERO batching massivo in Neo4j senza distruggere la RAM.
+        # Passo un intero array JSON ($batch) e Cypher lo "srotola" inserendo migliaia di nodi al volo.
         query = (
             "UNWIND $batch AS row "
             "MERGE (n:Resource {uri: row.uri}) "
@@ -154,19 +145,32 @@ class KnowledgeGraphPersister:
 
     @staticmethod
     def _unwind_write_tx(tx, predicate, batch_data):
-        """
-        Usa UNWIND per inserire migliaia di righe in un colpo solo.
-        """
-        query = (
-            f"UNWIND $batch AS row "
-            f"MERGE (s:Resource {{uri: row.subj_uri}}) "
-            f"ON CREATE SET s.label = row.subj_label "
-            f"MERGE (o:Resource {{uri: row.obj_uri}}) "
-            f"ON CREATE SET o.label = row.obj_label "
-            f"MERGE (s)-[r:`{predicate}`]->(o) "
-            f"SET r.confidence = row.conf, "
-            f"    r.source = row.src, "
-            f"    r.last_updated = datetime()"
-        )
-        
-        tx.run(query, batch=batch_data)
+        # Qui avviene la vera traduzione dal mondo RDF a quello Labeled Property Graph (LPG).
+        if predicate in ["RDF_TYPE", "TYPE", "A", "CORE_HASTYPE"]:
+            # Se l'LLM ha generato una tripla di classificazione ontologica, NON creo un nodo astratto inutile. 
+            # Uso APOC per convertire l'oggetto della tripla in una vera Label sul nodo di partenza.
+            query = (
+                "UNWIND $batch AS row "
+                "MERGE (s:Resource {uri: row.subj_uri}) "
+                "ON CREATE SET s.label = row.subj_label, s.last_updated = datetime() "
+                "WITH s, row "
+                "CALL apoc.create.addLabels(s, [replace(row.obj_label, ':', '_')]) YIELD node "
+                "RETURN count(node)"
+            )
+            tx.run(query, batch=batch_data)
+            
+        else:
+            # Per tutte le altre relazioni semantiche classiche (es. si_trova_in, ha_autore)
+            # eseguo un merge standard tra le due entità.
+            query = (
+                f"UNWIND $batch AS row "
+                f"MERGE (s:Resource {{uri: row.subj_uri}}) "
+                f"ON CREATE SET s.label = row.subj_label "
+                f"MERGE (o:Resource {{uri: row.obj_uri}}) "
+                f"ON CREATE SET o.label = row.obj_label "
+                f"MERGE (s)-[r:`{predicate}`]->(o) "
+                f"SET r.confidence = row.conf, "
+                f"    r.source = row.src, "
+                f"    r.last_updated = datetime()"
+            )
+            tx.run(query, batch=batch_data)

src/ingestion/semantic_splitter.py

@@ -1,11 +1,13 @@
 import os
 import re
 import numpy as np
+import nltk
 from sklearn.metrics.pairwise import cosine_similarity
 from dotenv import load_dotenv
 from langchain_huggingface import HuggingFaceEmbeddings
 
-load_dotenv() # in locale carica il file .env , su HF non trovando il file utilizza i secrets inseriti nella sezione settings.
+# Carico l'ambiente. Su HF Spaces andrà a pescare dai secrets, in locale dal .env
+load_dotenv()
 
 class ActivaSemanticSplitter:
     def __init__(self, model_name="sentence-transformers/all-MiniLM-L6-v2", batch_size=32):
@@ -13,6 +15,8 @@ class ActivaSemanticSplitter:
         
         print("🔄 Inizializzazione HuggingFace Embedding Engine...")
         
+        # Scelto MiniLM-L6: per questo prototipo ci serve un modello veloce e leggero in RAM 
+        # che non faccia da collo di bottiglia durante l'ingestion massiva di documenti.
         try:
             self.embedding_model = HuggingFaceEmbeddings(model_name=model_name)    
             print("✅ Modello caricato correttamente.")
@@ -20,31 +24,31 @@ class ActivaSemanticSplitter:
             print(f"❌ Errore caricamento modello: {e}")
             raise e
 
+        # Check preventivo sui tokenizer.
+        try:
+            nltk.data.find('tokenizers/punkt')
+            nltk.data.find('tokenizers/punkt_tab')
+        except LookupError:
+            print("⬇️ Download risorse NLTK...")
+            nltk.download('punkt', quiet=True)
+            nltk.download('punkt_tab', quiet=True)
+
     def _split_sentences(self, text):
-        """
-        Divide il testo in frasi gestendo le abbreviazioni custom (es. sec., S.).
-        """
+        # La pulizia base. Fondamentale per i testi estratti da vecchi OCR o documenti sporchi.
         text = text.strip()
         try:
-            import nltk
-            # Controllo che i dati ci siano
-            try:
-                nltk.data.find('tokenizers/punkt')
-                nltk.data.find('tokenizers/punkt_tab')
-            except LookupError:
-                print("⬇️ Download risorse NLTK...")
-                nltk.download('punkt', quiet=True)
-                nltk.download('punkt_tab', quiet=True)
-
-            # Invece di usare sent_tokenize() che è una black box, carico l'oggetto.
+            # Recupero il tokenizer dell'italiano. Evito sent_tokenize() puro perché è una black box
+            # e mi serve poter iniettare eccezioni custom per la punteggiatura.
             try:
                 tokenizer = nltk.data.load('tokenizers/punkt/italian.pickle')
             except:
-                # Fallback se il pickle path non viene risolto automaticamente
+                # Fallback di sicurezza se il path del pickle salta
                 from nltk.tokenize.punkt import PunktSentenceTokenizer
                 tokenizer = PunktSentenceTokenizer()
 
             # --- LISTA ECCEZIONI ABBREVIAZIONI ---
+            # Evito che il chunker mi spezzi la frase a metà quando incontra "pag." o "art."
+            # cosa che distruggerebbe il senso semantico prima ancora di passare all'LLM.
             custom_abbrevs = ['sec', 's', 'prof', 'dott', 'avv', 'pag', 'fig', 'nr', 'art']
             for abbr in custom_abbrevs:
                 tokenizer._params.abbrev_types.add(abbr)
@@ -58,9 +62,13 @@ class ActivaSemanticSplitter:
             print(f"⚠️ Errore NLTK ({e}). Fallback su Regex.")
             sentences = re.split(r'(?<=[.?!])\s+', text)
             
+        # Filtro via il rumore di fondo (stringhe troppo corte o spazi rimasti appesi)
         return [s.strip() for s in sentences if len(s.strip()) > 5]
 
     def combine_sentences(self, sentences, buffer_size=1):
+        # Sliding window per dare contesto: embeddare una frase singola tipo "Di conseguenza."  non ha senso vettoriale. 
+        # Le affianco la frase prima e quella dopo per "spalmare" il significato
+        # ed evitare che una frase breve sballi il calcolo del coseno.
         combined = []
         for i in range(len(sentences)):
             start = max(0, i - buffer_size)
@@ -70,6 +78,7 @@ class ActivaSemanticSplitter:
         return combined
 
     def calculate_cosine_distances(self, sentences):
+        # Embeddo tutto in batch. Se arrivano malloppi enormi da estrarre non voglio saturare la memoria.
         embeddings = []
         total = len(sentences)
         
@@ -78,10 +87,11 @@ class ActivaSemanticSplitter:
             batch_embeddings = self.embedding_model.embed_documents(batch)
             embeddings.extend(batch_embeddings)
 
+        # Calcolo le distanze sequenziali tra la frase N e la frase N+1
         distances = []
         for i in range(len(embeddings) - 1):
             similarity = cosine_similarity([embeddings[i]], [embeddings[i+1]])[0][0]
-            #(0 = identiche, 1 = completamente diverse)
+            # Inverto la similarità in distanza (0 = concetti identici, 1 = cambio totale di argomento)
             distance = 1.0 - similarity 
             distances.append(distance)
             
@@ -96,21 +106,25 @@ class ActivaSemanticSplitter:
         distances, _ = self.calculate_cosine_distances(combined_sentences)
         
         if not distances:
+            # Testo troppo breve per essere splittato, lo tengo intero
             return [text], [], 0
 
+        # Calcolo la soglia di taglio dinamicamente in base alle variazioni semantiche del documento stesso.
         threshold = np.percentile(distances, percentile_threshold)
         
-        # Un breakpoint avviene quando la distanza supera la soglia
+        # Individuo i "punti di rottura" dove l'argomento cambia radicalmente
         indices_above_thresh = [i for i, x in enumerate(distances) if x > threshold]
         
         chunks = []
         start_index = 0
         breakpoints = indices_above_thresh + [len(single_sentences)]
 
+        # Ricostruisco i paragrafi unendo le frasi originali (non quelle col buffer) 
+        # delimitandole dai punti di rottura che abbiamo appena trovato.
         for i in breakpoints:
             end_index = i + 1
             chunk_text = " ".join(single_sentences[start_index:end_index])
-            if len(chunk_text) > 20:
+            if len(chunk_text) > 20: # Salto micro-frammenti spazzatura (es. singole parole o punteggiatura)
                 chunks.append(chunk_text)
             start_index = end_index
             

src/utils/build_schema.py

@@ -3,11 +3,61 @@ import json
 from pathlib import Path
 from rdflib import Graph
 
+# --- MAPPA FORZATA DEI NAMESPACE ARCO E ONTOPIA ---
+# rdflib spesso fa casini con i prefissi di default (generando ID vuoti tipo ':Acquisition').
+# Forziamo la mano con un dizionario hardcoded per avere sempre QName puliti 
+# e standardizzati, fondamentali per non confondere l'LLM durante lo Schema-RAG.
+ARCO_NAMESPACES = {
+    "https://w3id.org/arco/ontology/arco/": "arco",
+    "https://w3id.org/arco/ontology/core/": "core",
+    "https://w3id.org/arco/ontology/location/": "a-loc",
+    "https://w3id.org/arco/ontology/context-description/": "a-cd",
+    "https://w3id.org/arco/ontology/denotative-description/": "a-dd",
+    "https://w3id.org/arco/ontology/cultural-event/": "a-ce",
+    "http://dati.beniculturali.it/cis/": "cis",
+    "https://w3id.org/italia/onto/l0/": "l0",
+    "https://w3id.org/italia/onto/CLV/": "clv",
+    "https://w3id.org/italia/onto/TI/": "ti",
+    "https://w3id.org/italia/onto/RO/": "ro",
+    "https://w3id.org/italia/onto/SM/": "sm",
+    "http://www.w3.org/2002/07/owl#": "owl"
+}
+
+def uri_to_qname(uri: str) -> str:
+    """
+    Prende un URI chilometrico e lo riduce a un QName compatto (es. arco:CulturalProperty).
+    L'LLM impazzirebbe a leggere URL completi nel prompt, sprecando token inutilmente.
+    """
+    if not uri:
+        return None
+    uri_str = str(uri)
+    
+    # Match sulla base dei namespace noti (cerco la radice più lunga)
+    best_match = ""
+    for ns_uri in ARCO_NAMESPACES.keys():
+        if uri_str.startswith(ns_uri) and len(ns_uri) > len(best_match):
+            best_match = ns_uri
+            
+    if best_match:
+        prefix = ARCO_NAMESPACES[best_match]
+        name = uri_str[len(best_match):].lstrip('#')
+        return f"{prefix}:{name}"
+    
+    # Fallback drastico se peschiamo qualcosa fuori dai radar: tengo solo l'ultimo pezzetto
+    if '#' in uri_str:
+        return uri_str.split('#')[-1]
+    return uri_str.split('/')[-1]
+
+
 def build_schema_from_ontology(owl_folder_path: str, output_json_path: str):
     print(f"⏳ Inizializzazione Graph e caricamento file .owl da {owl_folder_path}...")
+    
+    # Creo un mega-grafo in memoria. Caricando tutti i file .owl insieme, 
+    # risolvo automaticamente i cross-reference (es. una proprietà di 'location.owl' 
+    # che punta a una classe di 'core.owl').
     g = Graph()
     
-    # 1. Caricamento di tutti i moduli dell'ontologia
+    # 1. Caricamento Moduli
     owl_files = list(Path(owl_folder_path).glob('**/*.owl'))
     if not owl_files:
         print("❌ Nessun file .owl trovato nella directory specificata.")
@@ -15,25 +65,22 @@ def build_schema_from_ontology(owl_folder_path: str, output_json_path: str):
 
     for file_path in owl_files:
         try:
-            # I file .owl standard sono scritti in RDF/XML
             g.parse(file_path, format="xml")
             print(f"  -> Caricato (XML): {file_path.name}")
         except Exception as e_xml:
-            try:
-                g.parse(file_path, format="turtle")
-                print(f"  -> Caricato (Turtle): {file_path.name}")
-            except Exception as e_ttl:
-                print(f"  ⚠️ Impossibile parsare {file_path.name}. XML err: {e_xml} | TTL err: {e_ttl}")
-
+            print(f"  ⚠️ Impossibile parsare {file_path.name}. XML err: {e_xml}")
 
     print("✅ Ontologia caricata in memoria. Esecuzione query SPARQL...")
 
-    # 2. Query SPARQL per estrarre Classi e ObjectProperties con le loro descrizioni in italiano
+    # 2. Query SPARQL 
+    # Estrazione massiva. Ho rimosso i FILTER(isIRI) su domain e range perché ArCo 
+    # fa largo uso di Blank Nodes per definire le UNION di classi. Se li filtro, 
+    # perdo un sacco di vincoli relazionali utili per l'estrattore LLM.
     sparql_query = """
     PREFIX owl: <http://www.w3.org/2002/07/owl#>
     PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
 
-    SELECT DISTINCT ?entity ?type ?label ?comment
+    SELECT DISTINCT ?entity ?type ?label ?comment ?domain ?range
     WHERE {
       {
         ?entity a owl:Class .
@@ -43,62 +90,77 @@ def build_schema_from_ontology(owl_folder_path: str, output_json_path: str):
         BIND("Property" AS ?type)
       }
       
-      # Recuperiamo le label in italiano (o senza lingua)
       OPTIONAL { 
           ?entity rdfs:label ?label . 
           FILTER(LANGMATCHES(LANG(?label), "it") || LANG(?label) = "") 
       }
       
-      # Recuperiamo i commenti/definizioni in italiano (o senza lingua)
       OPTIONAL { 
           ?entity rdfs:comment ?comment . 
           FILTER(LANGMATCHES(LANG(?comment), "it") || LANG(?comment) = "") 
       }
+
+      OPTIONAL { ?entity rdfs:domain ?domain . }
+      OPTIONAL { ?entity rdfs:range ?range . }
       
-      # Filtriamo per evitare i blank nodes (nodi senza URI)
       FILTER(isIRI(?entity))
     }
     """
 
     results = g.query(sparql_query)
-    
     schema_elements = {}
 
-    # 3. Elaborazione e formattazione dei risultati
+    # 3. Formattazione e Pulizia
     for row in results:
         entity_uri = row.entity
         entity_type = str(row.type)
         label = str(row.label) if row.label else ""
         comment = str(row.comment) if row.comment else ""
         
-        # Trasformiamo l'URI lungo in un prefisso leggibile (es. arco:CulturalProperty)
-        try:
-            prefix, namespace, name = g.compute_qname(entity_uri)
-            qname = f"{prefix}:{name}"
-        except Exception:
-            # Fallback se non riesce a calcolare il prefisso
-            qname = str(entity_uri).split('/')[-1].split('#')[-1]
+        qname = uri_to_qname(entity_uri)
+
+        # Gestione Blank Nodes: se il dominio o range non è un URI netto (inizia con http), 
+        # significa che l'ontologia sta usando una costruzione logica complessa (es. unione di classi).
+        # Metto "Mixed/Union" come fallback per avvisare l'LLM che accetta tipi misti.
+        domain_str = uri_to_qname(row.domain) if (row.domain and str(row.domain).startswith("http")) else ("Mixed/Union" if row.domain else None)
+        range_str = uri_to_qname(row.range) if (row.range and str(row.range).startswith("http")) else ("Mixed/Union" if row.range else None)
 
-        # Costruiamo la descrizione aggregata per l'LLM
         description_parts = []
         if label: description_parts.append(label)
         if comment: description_parts.append(comment)
         
         final_description = " - ".join(description_parts)
 
-        # Se una classe non ha né label né commento, la scartiamo per non confondere l'LLM
+        # Scarto le voci senza documentazione testuale. Se non hanno un commento, 
+        # l'LLM non capirebbe mai come usarle e farebbe solo allucinazioni.
         if not final_description.strip():
             continue
 
-        # Usiamo un dizionario per evitare duplicati (spesso le ontologie definiscono la stessa classe in più file)
+        # Se l'entità non è ancora nel dizionario, la creiamo
         if qname not in schema_elements:
-            schema_elements[qname] = {
+            element_data = {
                 "id": qname,
                 "type": entity_type,
                 "description": final_description.strip()
             }
+            # Strutturo domain e range come chiavi a se stanti per poterle iniettare facilmente nel prompt
+            if entity_type == "Property":
+                element_data["domain"] = domain_str
+                element_data["range"] = range_str
+                
+            schema_elements[qname] = element_data
+            
+        else:
+            # Deduplica intelligente: poiché i file OWL si sovrappongono, potrei leggere la stessa 
+            # proprietà due volte (una volta vuota, una volta con i vincoli). 
+            # Se trovo i vincoli al secondo giro, aggiorno il dizionario per non perdere dati preziosi.
+            if entity_type == "Property":
+                if domain_str and not schema_elements[qname].get("domain"):
+                    schema_elements[qname]["domain"] = domain_str
+                if range_str and not schema_elements[qname].get("range"):
+                    schema_elements[qname]["range"] = range_str
 
-    # 4. Salvataggio in JSON
+    # 4. Salvataggio su disco
     output_list = list(schema_elements.values())
     
     with open(output_json_path, 'w', encoding='utf-8') as f:
@@ -107,15 +169,10 @@ def build_schema_from_ontology(owl_folder_path: str, output_json_path: str):
     print(f"🎉 Finito! Generato dizionario con {len(output_list)} elementi.")
     print(f"💾 Salvato in: {output_json_path}")
 
-
 if __name__ == "__main__":
-    # Esempio di utilizzo:
-    # Assicurati di scaricare i file .ttl di ArCo e metterli in una cartella, ad es. 'data/arco_raw/'
     NOME_ONTOLOGIA = "ARCO"
     INPUT_FOLDER = f"data/ontologie_raw/{NOME_ONTOLOGIA}" 
     OUTPUT_FILE = f"data/schemas/{NOME_ONTOLOGIA}_schema.json"
     
-    # Crea la directory di output se non esiste
     os.makedirs(os.path.dirname(OUTPUT_FILE), exist_ok=True)
-    
     build_schema_from_ontology(INPUT_FOLDER, OUTPUT_FILE)

src/validation/shapes/schema_constraints.ttl

@@ -1,10 +1,12 @@
 @prefix sh: <http://www.w3.org/ns/shacl#> .
 @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
-@prefix ex: <http://activa.ai/ontology/> .
+@prefix ex: <http://activadigital.it/ontology/> .
 @prefix arco: <https://w3id.org/arco/ontology/arco/> .
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 
-# 1. REGOLA BASE: Ogni entità (soggetto o oggetto) deve avere un nome testuale (Label)
+# --- REGOLA 1: Anti-nodi fantasma ---
+# Il DB a grafo non deve riempirsi di nodi vuoti o corrotti. Se l'LLM decide di estrarre 
+# un'entità (soggetto o oggetto che sia), mi deve garantire che abbia una label di testo associata.
 ex:NodeLabelShape
     a sh:NodeShape ;
     sh:targetSubjectsOf skos:prefLabel ;
@@ -12,25 +14,31 @@ ex:NodeLabelShape
         sh:path skos:prefLabel ;
         sh:minCount 1 ;
         sh:nodeKind sh:Literal ;
-        sh:message "Errore Topologico: Ogni entità nel grafo deve possedere un nome leggibile."
+        sh:message "Errore Topologico: Il nodo estratto non ha un nome testuale. Impossibile creare l'entità in Neo4j."
     ] .
 
-# 2. REGOLA RELAZIONALE: Le proprietà non devono puntare a testi (Literal), ma ad altri nodi (IRI)
+# --- REGOLA 2: Protezione Relazioni (No Datatype properties) ---
+# Un classico limite degli LLM in ambito knowledge graph: confondono i nodi con le stringhe. 
+# Spesso tentano di fare (Soggetto) -[relazione]-> "Stringa di testo". 
+# Qui blindo la cosa: le relazioni semantiche devono SEMPRE puntare a un altro nodo fisico (IRI).
 ex:ObjectPropertyShape
     a sh:NodeShape ;
-    sh:targetSubjectsOf skos:prefLabel ; # Si applica a tutti i nodi
+    sh:targetSubjectsOf skos:prefLabel ; 
     sh:property [
         sh:path skos:related ;
         sh:nodeKind sh:IRI ;
-        sh:message "Errore Semantico (skos:related): Le relazioni generiche devono collegare due nodi distinti, non un nodo a un testo."
+        sh:message "Errore Semantico: La relazione punta a un testo libero (Literal) invece che a un nodo (IRI)."
     ] .
 
-# 3. REGOLA ONTOLOGICA: Se un nodo ha un rdf:type, deve essere un IRI (es. arco:CulturalProperty)
+# --- REGOLA 3: Tipizzazione rigorosa ---
+# Se LLM prova a classificare un'entità usando rdf:type, l'oggetto DEVE essere
+# un URI valido pescato dall'ontologia (es. arco:HistoricOrArtisticProperty). 
+# È severamente vietato inventarsi classi testuali tipo rdf:type -> "Monumento Antico".
 ex:TypeShape
     a sh:NodeShape ;
     sh:targetSubjectsOf rdf:type ;
     sh:property [
         sh:path rdf:type ;
         sh:nodeKind sh:IRI ;
-        sh:message "Errore Ontologico: La classe assegnata tramite rdf:type deve essere un URI valido dell'ontologia, non una stringa."
+        sh:message "Errore Ontologico: L'LLM ha usato una stringa per rdf:type invece di un URI ufficiale di ArCo."
     ] .

src/validation/validator.py

@@ -5,15 +5,19 @@ from pyshacl import validate
 
 class SemanticValidator:
     def __init__(self):
+        # Carico le regole SHACL.
+        # Se l'LLM ha un'allucinazione e inventa relazioni assurde, SHACL lo blocca qui.
         self.shapes_file = os.path.join(os.path.dirname(__file__), "shapes/schema_constraints.ttl")
         
-        # Dizionario dei Namespace ufficiali di ArCo e fallback
+        # Mappatura dei namespace di ArCo. 
+        # Il namespace 'ex' ci serve come discarica/fallback per tutte le entità testuali pure 
+        # (es. "Colosseo", "Monumento") che l'LLM non ha saputo ancorare a un'URI ufficiale.
         self.namespaces = {
             "arco": Namespace("https://w3id.org/arco/ontology/arco/"),
             "core": Namespace("https://w3id.org/arco/ontology/core/"),
             "a-loc": Namespace("https://w3id.org/arco/ontology/location/"),
             "cis": Namespace("http://dati.beniculturali.it/cis/"),
-            "ex": Namespace("http://activa.ai/ontology/") # Fallback per le entità
+            "ex": Namespace("http://activadigital.it/ontology/") 
         }
         
         if os.path.exists(self.shapes_file):
@@ -21,69 +25,79 @@ class SemanticValidator:
             self.shacl_graph.parse(self.shapes_file, format="turtle")
             print("🛡️  SHACL Constraints caricati.")
         else:
-            print("⚠️  File SHACL non trovato. Validazione disabilitata.")
+            print("⚠️  File SHACL non trovato. Validazione disabilitata (pericoloso in prod!).")
             self.shacl_graph = None
 
     def _get_uri(self, text_val):
-        """Metodo di supporto per tradurre un testo 'prefisso:nome' in un URIRef reale."""
+        # L'LLM ci restituisce stringhe come "arco:CulturalProperty" o semplice testo "Statua di bronzo".
+        # rdflib ha bisogno di URIRef veri, quindi faccio un po' di parsing per convertirli.
         if ":" in text_val and not text_val.startswith("http"):
             prefix, name = text_val.split(":", 1)
             if prefix in self.namespaces:
                 return self.namespaces[prefix][name]
         
-        # Se è un'entità senza prefisso (es. "Menhir di Canne"), uso il namespace custom
+        # Se è testo libero senza namespace, lo ripulisco per evitare che gli spazi 
+        # rompano l'URI e lo forzo nel nostro namespace custom.
         clean_name = text_val.replace(" ", "_").replace("'", "").replace('"', "")
         return self.namespaces["ex"][clean_name]
 
     def _json_to_rdf(self, entities, triples):
-        """Converte dinamicamente rispettando l'ontologia ArCo."""
+        # Il validatore pyshacl non digerisce i nostri oggetti Pydantic o i JSON nativi.
+        # Devo ricostruire un micro-grafo RDF al volo solo per fargli fare il check formale.
         g = Graph()
-        # Registriamo i prefissi nel grafo per leggibilità
+        
+        # Registro i prefissi nel grafo per facilitare l'eventuale debug testuale
         for prefix, ns in self.namespaces.items():
             g.bind(prefix, ns)
         g.bind("skos", SKOS)
 
-        # 1. Popolamento Entità Isolate (Orfani)
+        # 1. Recupero entità orfane (trovate nel testo ma non agganciate a nessuna tripla)
         if entities:
             for ent in entities:
+                # Gestisco il tipo di dato a seconda di cosa è uscito dal resolver
                 label = ent["label"] if isinstance(ent, dict) else str(ent)
                 ent_uri = self._get_uri(label)
                 g.add((ent_uri, SKOS.prefLabel, Literal(label, lang="it")))
 
-        # 2. Popolamento delle Triple
+        # 2. Ricostruzione delle Triple relazionali
         if triples:
             for t in triples:
                 subj_uri = self._get_uri(t.subject)
                 
-                # Assicuriamoci che ogni nodo abbia un nome leggibile
+                # Le nostre regole SHACL (schema_constraints.ttl) esigono tipicamente che i nodi 
+                # non siano scatole vuote (NodeLabelShape). Ci appiccico sempre la prefLabel in italiano.
                 g.add((subj_uri, SKOS.prefLabel, Literal(t.subject, lang="it")))
 
-                if t.predicate in ["rdf:type", "a", "type"]:
-                    # Se l'LLM sta classificando il nodo (es. oggetto = arco:CulturalProperty)
+                # Separo le classificazioni dalle relazioni standard
+                if t.predicate.lower() in ["rdf:type", "a", "type", "rdf_type"]:
                     obj_uri = self._get_uri(t.object)
                     g.add((subj_uri, RDF.type, obj_uri))
                 else:
-                    # Se è una relazione standard (es. a-loc:hasCurrentLocation)
+                    # Relazione standard (es. a-loc:hasCurrentLocation)
                     pred_uri = self._get_uri(t.predicate)
                     obj_uri = self._get_uri(t.object)
                     
                     g.add((subj_uri, pred_uri, obj_uri))
+                    # Anche il nodo di destinazione deve avere un nome umano
                     g.add((obj_uri, SKOS.prefLabel, Literal(t.object, lang="it")))
             
         return g
 
     def validate_batch(self, entities, triples):
         """
-        Esegue la validazione SHACL sia sulle entità isolate che sulle triple.
-        Ritorna (is_valid, report_text, rdf_graph)
+        Scatena il motore di regole SHACL sia sulle entità isolate che sulle triple.
+        Ritorna l'esito, il report testuale degli errori, e il grafo temporaneo.
         """
         if not self.shacl_graph:
             return True, "No Constraints", None
 
-        # Passiamo entrambe le liste al convertitore
+        # Converto la pappa di Pydantic in un vero grafo RDF
         data_graph = self._json_to_rdf(entities, triples)
         
         print("🔍 Esecuzione Validazione SHACL...")
+        
+        # Abilito inference='rdfs' così se una regola si applica a una super-classe, 
+        # pyshacl lo deduce da solo scendendo l'albero gerarchico.
         conforms, report_graph, report_text = validate(
             data_graph,
             shacl_graph=self.shacl_graph,