Upload 16 files

app/ui.py

@@ -0,0 +1,161 @@
+import streamlit as st
+from neo4j import GraphDatabase
+import pandas as pd
+from pyvis.network import Network
+import streamlit.components.v1 as components
+import os
+import csv
+from datetime import datetime
+from dotenv import load_dotenv
+
+# --- CONFIGURAZIONE ---
+
+# Carica variabili d'ambiente
+load_dotenv()
+
+st.set_page_config(page_title="Activa Semantic Discovery", layout="wide")
+# Usa le variabili d'ambiente (con fallback per sicurezza locale)
+URI = os.getenv("NEO4J_URI", "neo4j+s://748d6c94.databases.neo4j.io")
+USER = os.getenv("NEO4J_USER", "neo4j")
+PASSWORD = os.getenv("NEO4J_PASSWORD", "t1bT1DiXwDOGMYfX89qR20loSN8FXurB3Dfg8bPQcTI")
+AUTH = (USER, PASSWORD)
+
+# --- CONNESSIONE NEO4J ---
+@st.cache_resource
+def get_driver():
+    return GraphDatabase.driver(URI, auth=AUTH)
+
+def run_query(query, params=None):
+    driver = get_driver()
+    with driver.session() as session:
+        result = session.run(query, params)
+        return [r.data() for r in result]
+
+# --- LOGICA CORE: FEEDBACK LOOP (Nuova Funzionalità) ---
+def reject_relationship(rel_id, subj, pred, obj, reason="Human Rejection"):
+    """
+    1. Cancella dal DB (Azione Reale).
+    2. Salva in CSV per Active Learning (Data Lineage del rifiuto).
+    """
+    # 1. Cancellazione Reale
+    query = "MATCH ()-[r]->() WHERE elementId(r) = $id DELETE r"
+    try:
+        run_query(query, {"id": rel_id})
+    except Exception as e:
+        st.error(f"Errore durante la cancellazione: {e}")
+        return False
+    
+    # 2. Logging per Fine-Tuning
+    log_file = "rejected_triples.csv"
+    file_exists = os.path.isfile(log_file)
+    
+    try:
+        with open(log_file, mode='a', newline='', encoding='utf-8') as f:
+            writer = csv.writer(f)
+            if not file_exists:
+                writer.writerow(["timestamp", "subject", "predicate", "object", "reason"])
+            writer.writerow([datetime.now(), subj, pred, obj, reason])
+        return True
+    except Exception as e:
+        st.warning(f"Relazione cancellata dal DB, ma errore nel log CSV: {e}")
+        return True
+
+# --- UI: HEADER ---
+st.title("🧠 Automated Semantic Discovery | Lab")
+st.markdown("""
+**Piattaforma Human-in-the-Loop** per la validazione delle ontologie generate.
+Vedi Sezione 5.2.4 della Relazione Tecnica.
+""")
+
+# --- UI: KPI METRICS (Mantenuti dalla versione vecchia perché più completi) ---
+col1, col2, col3 = st.columns(3)
+try:
+    node_count = run_query("MATCH (n) RETURN count(n) as count")[0]['count']
+    rel_count = run_query("MATCH ()-[r]->() RETURN count(r) as count")[0]['count']
+    concept_count = run_query("MATCH (n:Resource) RETURN count(n) as count")[0]['count']
+    
+    col1.metric("Nodi Totali", node_count)
+    col2.metric("Relazioni Attive", rel_count)
+    col3.metric("Concetti Semantici", concept_count)
+except Exception as e:
+    st.error(f"Errore connessione Neo4j: {e}")
+    st.stop()
+
+# --- UI: TAB DI NAVIGAZIONE ---
+tab1, tab2 = st.tabs(["🔍 Validazione (Active Learning)", "🕸️ Visualizzazione Grafo"])
+
+# --- TAB 1: CURATION TABLE (Aggiornato con Lineage e Delete Reale) ---
+with tab1:
+    st.subheader("Curation & Feedback Loop")
+    st.info("Qui l'esperto valida le ipotesi dell'IA. Le cancellazioni addestrano il modello futuro.")
+    
+    # Query aggiornata: Recupera anche 'r.source' (Lineage)
+    triples_data = run_query("""
+        MATCH (s)-[r]->(o) 
+        RETURN elementId(r) as id, s.label as Soggetto, type(r) as Predicato, o.label as Oggetto, r.confidence as Confidenza, r.source as Fonte
+        ORDER BY r.confidence ASC LIMIT 50
+    """)
+    
+    if triples_data:
+        df = pd.DataFrame(triples_data)
+        
+        # Selezione Riga
+        selection = st.dataframe(
+            df.drop(columns=["id"]),
+            width='stretch',
+            hide_index=True,
+            selection_mode="single-row",
+            on_select="rerun"
+        )
+        
+        # Azione di Reject
+        if selection.selection.rows:
+            idx = selection.selection.rows[0]
+            row = df.iloc[idx]
+            
+            st.error(f"Stai per rifiutare: **{row['Soggetto']}** --[{row['Predicato']}]--> **{row['Oggetto']}**")
+            
+            if st.button("🗑️ CONFERMA RIFIUTO (Training Feedback)", type="primary"):
+                success = reject_relationship(row['id'], row['Soggetto'], row['Predicato'], row['Oggetto'])
+                if success:
+                    st.success("Relazione eliminata e loggata per il ri-addestramento!")
+                    st.rerun()
+    else:
+        st.info("Nessuna relazione da validare o DB vuoto.")
+
+# --- TAB 2: GRAPH VISUALIZATION (Mantenuto dalla versione vecchia per la Fisica) ---
+with tab2:
+    st.subheader("Esplorazione Topologica")
+    
+    # Manteniamo la checkbox della fisica (utile per grafi grandi)
+    physics = st.checkbox("Abilita Fisica (Gravità)", value=True)
+    
+    net = Network(height="600px", width="100%", bgcolor="#222222", font_color="white", notebook=False)
+    
+    # Carichiamo i dati (Max 100 relazioni)
+    graph_data = run_query("MATCH (s)-[r]->(o) RETURN s.label as src, type(r) as rel, o.label as dst LIMIT 100")
+    
+    if graph_data:
+        for item in graph_data:
+            # Colori personalizzati come nel vecchio file
+            net.add_node(item['src'], label=item['src'], color="#4facfe") 
+            net.add_node(item['dst'], label=item['dst'], color="#00f2fe")
+            net.add_edge(item['src'], item['dst'], title=item['rel'], label=item['rel'])
+        
+        # Applichiamo la fisica se selezionata
+        net.toggle_physics(physics)
+        
+        try:
+            path = "tmp_graph.html"
+            net.save_graph(path)
+            with open(path, 'r', encoding='utf-8') as f:
+                html_string = f.read()
+            components.html(html_string, height=600, scrolling=True)
+        except Exception as e:
+            st.error(f"Errore generazione grafo: {e}")
+    else:
+        st.write("Grafo vuoto.")
+
+# Footer
+st.markdown("---")
+st.caption("Activa Digital | Next Gen Tech | Prototipo v0.2 (Feedback Loop Enabled)")

data/gold_standard/examples.json

@@ -0,0 +1,63 @@
+[
+  {
+    "text": "Il Menhir di Canne, situato lungo la strada provinciale, è un monolite calcareo che fungeva da segnacolo funerario o confine territoriale in epoca pre-romana.",
+    "triples": [
+      {"subject": "Menhir di Canne", "predicate": "rdf:type", "object": "xchh:HeritageObject", "confidence": 1.0},
+      {"subject": "Menhir di Canne", "predicate": "crm:P45_consists_of", "object": "Calcare", "confidence": 1.0},
+      {"subject": "Menhir di Canne", "predicate": "crm:P2_has_type", "object": "Segnacolo funerario", "confidence": 0.9},
+      {"subject": "Menhir di Canne", "predicate": "crm:P53_has_former_or_current_location", "object": "Strada Provinciale", "confidence": 1.0}
+    ]
+  },
+  {
+    "text": "La Battaglia di Canne del 216 a.C. vide la vittoria dell'esercito cartaginese guidato da Annibale contro le legioni romane.",
+    "triples": [
+      {"subject": "Battaglia di Canne", "predicate": "rdf:type", "object": "xchh:HistoricalEvent", "confidence": 1.0},
+      {"subject": "Battaglia di Canne", "predicate": "crm:P4_has_time-span", "object": "216 a.C.", "confidence": 1.0},
+      {"subject": "Battaglia di Canne", "predicate": "crm:P11_had_participant", "object": "Esercito Cartaginese", "confidence": 1.0},
+      {"subject": "Annibale", "predicate": "crm:P14_carried_out_by", "object": "Esercito Cartaginese", "confidence": 0.95}
+    ]
+  },
+  {
+    "text": "L'Antiquarium custodisce un prezioso corredo funerario proveniente dalla necropoli dauna, inclusi vasi a figure rosse.",
+    "triples": [
+      {"subject": "Antiquarium", "predicate": "rdf:type", "object": "xchh:Place", "confidence": 1.0},
+      {"subject": "Corredo funerario", "predicate": "crm:P55_has_current_location", "object": "Antiquarium", "confidence": 1.0},
+      {"subject": "Corredo funerario", "predicate": "crm:P108i_was_produced_by", "object": "Cultura Dauna", "confidence": 0.9},
+      {"subject": "Vasi a figure rosse", "predicate": "crm:P46_is_composed_of", "object": "Corredo funerario", "confidence": 1.0}
+    ]
+  },
+  {
+    "text": "Il visitatore, avvicinandosi al totem multimediale, attiva l'esperienza di Realtà Aumentata che mostra la ricostruzione della cittadella medievale.",
+    "triples": [
+      {"subject": "Visitatore", "predicate": "rdf:type", "object": "xcha:Agent", "confidence": 1.0},
+      {"subject": "Esperienza AR", "predicate": "rdf:type", "object": "xche:ExperienceSession", "confidence": 1.0},
+      {"subject": "Visitatore", "predicate": "xch:activates", "object": "Esperienza AR", "confidence": 1.0},
+      {"subject": "Esperienza AR", "predicate": "xch:visualizes", "object": "Cittadella Medievale", "confidence": 1.0}
+    ]
+  },
+  {
+    "text": "I resti della Domus Apula testimoniano l'organizzazione abitativa romana. Le mura sono realizzate in opera reticolata.",
+    "triples": [
+      {"subject": "Domus Apula", "predicate": "rdf:type", "object": "xchh:Site", "confidence": 1.0},
+      {"subject": "Domus Apula", "predicate": "crm:P2_has_type", "object": "Abitazione Romana", "confidence": 0.9},
+      {"subject": "Mura", "predicate": "crm:P46_forms_part_of", "object": "Domus Apula", "confidence": 1.0},
+      {"subject": "Mura", "predicate": "crm:P32_used_general_technique", "object": "Opera Reticolata", "confidence": 1.0}
+    ]
+  },
+  {
+    "text": "L'Agente Cognitivo ha inferito con una confidenza del 90% che il frammento ceramico appartiene al periodo tardo-antico.",
+    "triples": [
+      {"subject": "Agente Cognitivo", "predicate": "rdf:type", "object": "xcha:ArtificialAgent", "confidence": 1.0},
+      {"subject": "Frammento ceramico", "predicate": "xch:hasInferredPeriod", "object": "Periodo Tardo-Antico", "confidence": 0.9},
+      {"subject": "Inferenza", "predicate": "prov:wasGeneratedBy", "object": "Agente Cognitivo", "confidence": 1.0}
+    ]
+  },
+  {
+    "text": "Il progetto Canusium xCH mira a creare un'eterotopia digitale per la valorizzazione del patrimonio culturale della provincia BAT.",
+    "triples": [
+      {"subject": "Canusium xCH", "predicate": "rdf:type", "object": "xch:Project", "confidence": 1.0},
+      {"subject": "Canusium xCH", "predicate": "xch:targetsDomain", "object": "Patrimonio Culturale", "confidence": 1.0},
+      {"subject": "Provincia BAT", "predicate": "crm:P89_falls_within", "object": "Puglia", "confidence": 1.0}
+    ]
+  }
+]

data/processed/chunks_debug.txt

@@ -0,0 +1,6 @@
+--- CHUNK 0 ---
+Il Menhir di Canne della Battaglia rappresenta uno dei punti di ancoraggio simbolici e spaziali più densi del Parco Archeologico. Isolato ma al centro di un paesaggio carico di memoria, il monolite diventa un nodo di connessione tra materia e contesto. L'obiettivo del progetto Canusium xCH non è la mera restituzione digitale dell'oggetto, ma la costruzione di una soglia esperienziale.
+
+--- CHUNK 1 ---
+L'esperienza comincia nell'approccio fisico al luogo. Avvicinandosi al Menhir, l'utente viene riconosciuto dal sistema tramite geo-anchoring e riceve sul proprio dispositivo un invito discreto ad attivare la modalità immersiva. La sovrapposizione digitale appare come una finestra trasparente che mantiene visibile il paesaggio, mentre introduce il modello 3D calibrato.
+

data/raw/menhir_test.txt

@@ -0,0 +1,5 @@
+Il Menhir di Canne della Battaglia rappresenta uno dei punti di ancoraggio simbolici e spaziali più densi del Parco Archeologico.
+Isolato ma al centro di un paesaggio carico di memoria, il monolite diventa un nodo di connessione tra materia e contesto.
+L'obiettivo del progetto Canusium xCH non è la mera restituzione digitale dell'oggetto, ma la costruzione di una soglia esperienziale.
+L'esperienza comincia nell'approccio fisico al luogo. Avvicinandosi al Menhir, l'utente viene riconosciuto dal sistema tramite geo-anchoring e riceve sul proprio dispositivo un invito discreto ad attivare la modalità immersiva.
+La sovrapposizione digitale appare come una finestra trasparente che mantiene visibile il paesaggio, mentre introduce il modello 3D calibrato.

data/raw/venezia_arte.doc

@@ -0,0 +1,13 @@
+Il Palazzo Ducale, capolavoro dell'arte gotica, sorge in Piazza San Marco a Venezia.
+Antica sede del Doge e delle magistrature veneziane, è il simbolo della potenza della Serenissima.
+Fondato nel IX secolo, l'edificio ha subito numerose ristrutturazioni a causa di incendi devastanti.
+La struttura attuale è il risultato dei lavori iniziati nel 1340.
+
+All'interno del palazzo si possono ammirare opere di inestimabile valore.
+La Sala del Maggior Consiglio ospita "Il Paradiso", una tela monumentale dipinta da Jacopo Tintoretto e dalla sua bottega tra il 1588 e il 1592.
+Questa sala era il cuore politico della Città Lagunare, dove si riunivano i nobili per prendere decisioni di stato.
+Un altro protagonista della decorazione interna è Paolo Veronese, che ha realizzato lo splendido soffitto della Sala del Collegio.
+
+Collegato al Palazzo Ducale tramite il celebre Ponte dei Sospiri, si trova il palazzo delle Prigioni Nuove.
+Il ponte, costruito nel 1600 in stile barocco, attraversa il Rio di Palazzo ed era attraversato dai condannati.
+Venezia continua ad attrarre milioni di visitatori che rimangono incantati dalla sua storia millenaria e dalla sua architettura unica al mondo.

src/extraction/extractor.py

@@ -0,0 +1,191 @@
+import json
+import os
+import numpy as np
+from typing import List, Optional
+from pydantic import BaseModel, Field, ValidationError
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
+from langchain_ollama import ChatOllama
+from langchain_huggingface import HuggingFaceEmbeddings
+from sklearn.metrics.pairwise import cosine_similarity
+
+# --- 1. DEFINIZIONE DELLO SCHEMA ---
+class GraphTriple(BaseModel):
+    subject: str = Field(..., description="Entità sorgente (Canonical).")
+    predicate: str = Field(..., description="Relazione (snake_case).")
+    object: str = Field(..., description="Entità target.")
+    confidence: float = Field(..., description="Confidenza (0.0 - 1.0).")
+    source: Optional[str] = Field(None, description="ID del documento o chunk.")
+
+class KnowledgeGraphExtraction(BaseModel):
+    reasoning: Optional[str] = Field(None, description="Breve ragionamento logico.")
+    triples: List[GraphTriple]
+
+# --- 2. ESTRATTORE DINAMICO (Dynamic Few-Shot) ---
+class NeuroSymbolicExtractor:
+    def __init__(self, model_name="llama3", temperature=0, gold_standard_path=None):
+        print(f"🦙 Inizializzazione Local LLM: {model_name}...")
+        
+        # 1. LLM per l'inferenza
+        self.llm = ChatOllama(
+            model=model_name,
+            temperature=temperature,
+            format="json",
+            base_url="http://localhost:11434"
+        )
+
+        # 2. Modello Embedding per la selezione dinamica
+        print("🧠 Caricamento modello embedding per Dynamic Selection...")
+        # Nota: Usiamo lo stesso modello dello splitter per coerenza
+        self.embedding_model = HuggingFaceEmbeddings(model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")
+
+        # 3. Caricamento e Indicizzazione Gold Standard
+        self.examples = []
+        self.example_embeddings = None
+        
+        if gold_standard_path and os.path.exists(gold_standard_path):
+            print(f"🌟 Indicizzazione vettoriale Gold Standard da: {gold_standard_path}")
+            self._index_examples(gold_standard_path)
+        else:
+            print("⚠️ Nessun Gold Standard trovato. Modalità Zero-Shot.")
+
+        # Template Specializzato per Canusium xCH (CIDOC-CRM + Ontology Layers)
+        self.system_template_base = """Sei l'Agente Cognitivo (AC) del sistema Canusium xCH.
+        Il tuo compito è trasformare il testo non strutturato in un Digital Twin Graph (RDF).
+
+        SCHEMA JSON RICHIESTO:
+        {{
+            "reasoning": "Spiega brevemente perché hai scelto queste classi/relazioni...",
+            "triples": [
+                {{"subject": "Entità", "predicate": "prefix:Relazione", "object": "Entità", "confidence": 0.95}}
+            ]
+        }}
+
+        ONTOLOGIA DI RIFERIMENTO (Usa questi prefissi):
+        - xchh: (Heritage) -> Per oggetti fisici, siti, reperti (es. xchh:HeritageObject, xchh:Site).
+        - crm: (CIDOC-CRM) -> Per relazioni standard (es. crm:P55_has_current_location, crm:P4_has_time-span).
+        - xche: (Experience) -> Per sessioni AR/VR, visitatori, interazioni (es. xche:ExperienceSession).
+        - xcha: (Agents) -> Per agenti umani o artificiali.
+        - skos: -> Per concetti generici o gerarchie.
+
+        ESEMPI CONTESTUALI (Dynamic Few-Shot):
+        {selected_examples}
+
+        REGOLE DI CONFIDENZA (Trust Layer):
+        - 1.0 (Fatto Curato): Informazione esplicita e certa nel testo.
+        - 0.8 - 0.9 (Inferenza): Deduzione logica forte ma non esplicita.
+        - < 0.7 (Ipotesi): Associazione probabile ma incerta (da marcare per revisione umana).
+        
+        Canonicalizza i nomi (es. "Il Parco" -> "Parco Archeologico di Canne").
+        """
+
+    def _index_examples(self, path: str):
+        """Carica il JSON e calcola i vettori per ogni esempio."""
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                self.examples = json.load(f)
+            
+            # Estraiamo solo il testo di input per calcolare l'embedding
+            texts = [ex['text'] for ex in self.examples]
+            self.example_embeddings = self.embedding_model.embed_documents(texts)
+            print(f"✅ Indicizzati {len(self.examples)} esempi di Gold Standard.")
+        except Exception as e:
+            print(f"❌ Errore indicizzazione Gold Standard: {e}")
+            self.examples = []
+
+    def _get_relevant_examples(self, query_text: str, k=2) -> str:
+        """
+        Trova i k esempi più simili semanticamente al chunk attuale.
+        """
+        if not self.examples or self.example_embeddings is None:
+            return "Nessun esempio disponibile."
+
+        # 1. Embed del chunk attuale
+        query_embedding = self.embedding_model.embed_query(query_text)
+        
+        # 2. Calcolo similarità coseno
+        similarities = cosine_similarity([query_embedding], self.example_embeddings)[0]
+        
+        # 3. Selezione dei top-k
+        top_k_indices = np.argsort(similarities)[-k:][::-1]
+        
+        formatted_text = ""
+        for i, idx in enumerate(top_k_indices):
+            ex = self.examples[idx]
+            sim_score = similarities[idx]
+            formatted_text += f"\n--- ESEMPIO RILEVANTE #{i+1} (Sim: {sim_score:.2f}) ---\n"
+            formatted_text += f"INPUT: {ex['text']}\n"
+            formatted_text += f"OUTPUT: {json.dumps({'triples': ex['triples']}, ensure_ascii=False)}\n"
+            
+        return formatted_text
+
+    def extract(self, text_chunk: str, source_id: str = "unknown", max_retries=3) -> KnowledgeGraphExtraction:
+        print(f"🧠 Processing {source_id} con Llama 3 (Dynamic Mode)...")
+        
+        # --- FASE DINAMICA: Selezione Esempi ---
+        relevant_examples_str = self._get_relevant_examples(text_chunk, k=2)
+        
+        # Costruzione Prompt Finale (usando .format per iniettare gli esempi scelti)
+        final_sys_text = self.system_template_base.format(selected_examples=relevant_examples_str)
+        
+        # Creazione del SystemMessage 'raw' per evitare problemi di parsing delle graffe
+        sys_msg = SystemMessage(content=final_sys_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})
+                data = json.loads(response.content)
+                
+                # Normalizzazione output
+                if isinstance(data, list):
+                    validated_data = KnowledgeGraphExtraction(triples=data, reasoning="Direct list output")
+                else:
+                    validated_data = KnowledgeGraphExtraction(**data)
+                
+                for t in validated_data.triples:
+                    t.source = source_id
+                    
+                return validated_data
+
+            except (json.JSONDecodeError, ValidationError) as e:
+                print(f"⚠️ Errore Validazione (Tentativo {attempt+1}/{max_retries}): {e}")
+                
+                # SELF-CORRECTION LOOP (Mantenuto dalla tua versione robusta)
+                correction_prompt = ChatPromptTemplate.from_messages([
+                    sys_msg,
+                    HumanMessage(content=text_chunk),
+                    AIMessage(content=response.content), # La risposta sbagliata
+                    HumanMessage(content=f"Errore nel JSON precedente: {e}. Correggi e restituisci SOLO JSON valido.")
+                ])
+                
+                chain = correction_prompt | self.llm
+                
+            except Exception as e:
+                print(f"❌ Errore critico: {e}")
+                break
+
+        return KnowledgeGraphExtraction(triples=[])
+
+# --- TEST ---
+if __name__ == "__main__":
+    # Testiamo se seleziona l'esempio giusto
+    chunk_arte = "Il dipinto mostra una tecnica a olio sopraffina."
+    chunk_storia = "Il senato elesse il nuovo capo di stato nel 1200."
+    
+    # Nota: Assicurati che il percorso del file JSON sia corretto
+    extractor = NeuroSymbolicExtractor(gold_standard_path="data/gold_standard/examples.json")
+    
+    print("\n--- TEST SELEZIONE DINAMICA (ARTE) ---")
+    # Dovrebbe pescare l'esempio della Primavera o Restauro
+    print(extractor._get_relevant_examples(chunk_arte, k=1))
+    
+    print("\n--- TEST SELEZIONE DINAMICA (STORIA/POLITICA) ---")
+    # Dovrebbe pescare l'esempio del Doge o Colosseo
+    print(extractor._get_relevant_examples(chunk_storia, k=1))

src/graph/entity_resolver.py

@@ -0,0 +1,99 @@
+import numpy as np
+from sklearn.cluster import DBSCAN
+from langchain_huggingface import HuggingFaceEmbeddings
+from collections import Counter
+
+class EntityResolver:
+    def __init__(self, model_name="all-MiniLM-L6-v2", similarity_threshold=0.85):
+        """
+        Inizializza il modello per il calcolo delle similarità.
+        similarity_threshold: quanto devono essere vicini i vettori (0-1).
+                              Convertito in 'eps' per DBSCAN.
+        """
+        print("🧩 Inizializzazione Entity Resolver (DBSCAN)...")
+        self.embedding_model = HuggingFaceEmbeddings(model_name=model_name)
+        # DBSCAN usa la distanza, non la similarità. Distanza = 1 - Similarità.
+        # Se threshold è 0.85 (alta similarità), eps deve essere 0.15 (bassa distanza).
+        self.eps = 1 - similarity_threshold
+
+    def resolve_entities(self, triples):
+        """
+        Prende una lista di triple (GraphTriple) e normalizza i nomi delle entità.
+        """
+        if not triples:
+            return []
+
+        # 1. Estrazione di tutte le entità uniche (Soggetti e Oggetti)
+        all_entities = set()
+        for t in triples:
+            all_entities.add(t.subject)
+            all_entities.add(t.object)
+        
+        unique_entities = list(all_entities)
+        print(f"   Analisi di {len(unique_entities)} entità uniche per deduplica...")
+
+        if len(unique_entities) < 2:
+            return triples
+
+        # 2. Calcolo Embeddings
+        embeddings = self.embedding_model.embed_documents(unique_entities)
+        X = np.array(embeddings)
+
+        # 3. Clustering DBSCAN
+        # metrica='cosine' è fondamentale per vettori semantici
+        clustering = DBSCAN(eps=self.eps, min_samples=1, metric='cosine').fit(X)
+        labels = clustering.labels_
+
+        # 4. Creazione Mappa {Variante -> Canonico}
+        # Raggruppiamo le entità per Cluster ID
+        cluster_map = {}
+        for entity, label in zip(unique_entities, labels):
+            if label not in cluster_map:
+                cluster_map[label] = []
+            cluster_map[label].append(entity)
+
+        # Per ogni cluster, eleggiamo il "Canonico" (es. la stringa più lunga)
+        entity_replacement_map = {}
+        for label, variants in cluster_map.items():
+            if len(variants) > 1:
+                # Euristiche di canonicalizzazione:
+                # 1. Preferisci quella che inizia con maiuscola
+                # 2. Preferisci la più lunga (spesso più descrittiva: "San Marco" vs "Basilica di San Marco")
+                canonical = sorted(variants, key=len, reverse=True)[0]
+                print(f"   ✨ Deduplica: {variants} -> '{canonical}'")
+                for v in variants:
+                    entity_replacement_map[v] = canonical
+            else:
+                entity_replacement_map[variants[0]] = variants[0]
+
+        # 5. Riscrittura Triple
+        resolved_triples = []
+        for t in triples:
+            # Sostituiamo soggetto e oggetto con le versioni canoniche
+            t.subject = entity_replacement_map.get(t.subject, t.subject)
+            t.object = entity_replacement_map.get(t.object, t.object)
+            resolved_triples.append(t)
+
+        return resolved_triples
+
+# --- TEST ---
+if __name__ == "__main__":
+    from pydantic import BaseModel
+    class MockTriple(BaseModel):
+        subject: str
+        predicate: str
+        object: str
+    
+    # Esempio con sinonimi
+    raw_triples = [
+        MockTriple(subject="Venezia", predicate="ha_monumento", object="Basilica di San Marco"),
+        MockTriple(subject="La Serenissima", predicate="situata_in", object="Laguna"), # Venezia = Serenissima
+        MockTriple(subject="S. Marco", predicate="stile", object="Bizantino") # S. Marco = Basilica di San Marco
+    ]
+
+    resolver = EntityResolver(similarity_threshold=0.6) # Soglia bassa per il test
+    clean_triples = resolver.resolve_entities(raw_triples)
+
+    print("\n--- RISULTATO ---")
+    for t in clean_triples:
+        print(f"{t.subject} --[{t.predicate}]--> {t.object}")

src/graph/graph_loader.py

@@ -0,0 +1,115 @@
+import os
+from neo4j import GraphDatabase
+from dotenv import load_dotenv
+
+# Carica variabili d'ambiente
+load_dotenv()
+
+class KnowledgeGraphPersister:
+    def __init__(self):
+        """
+        Inizializza il driver Neo4j usando le variabili d'ambiente per sicurezza.
+        """
+        uri = os.getenv("NEO4J_URI", "bolt://localhost:7687")
+        user = os.getenv("NEO4J_USER", "neo4j")
+        password = os.getenv("NEO4J_PASSWORD", "activa_semantic_lab")
+        
+        try:
+            self.driver = GraphDatabase.driver(uri, auth=(user, password))
+            self.driver.verify_connectivity()
+            print(f"✅ Connesso a Neo4j ({uri}) successfully.")
+        except Exception as e:
+            print(f"❌ Errore critico connessione Neo4j: {e}")
+            self.driver = None
+
+    def close(self):
+        if self.driver:
+            self.driver.close()
+
+    def sanitize_name(self, name):
+        """
+        Normalizza i nomi per creare URI coerenti (Canonicalization base).
+        """
+        if not name: return "Unknown"
+        # Rimuove caratteri speciali e spazi extra, mantiene coerenza maiuscole/minuscole
+        return name.strip().replace(" ", "_").replace("'", "").replace('"', "")
+
+    def save_triples(self, triples):
+        """
+        Salva le triple in BATCH (ottimizzazione performance).
+        Usa UNWIND per processare liste di dati in un'unica transazione.
+        """
+        if not self.driver:
+            print("⚠️ Driver non connesso. Impossibile salvare.")
+            return
+
+        if not triples:
+            return
+
+        print(f"💾 Salvataggio BATCH di {len(triples)} triple su Neo4j...")
+        
+        # 1. Prepariamo i dati come lista di dizionari (Payload leggero)
+        batch_data = []
+        for t in triples:
+            batch_data.append({
+                "subj_uri": self.sanitize_name(t.subject),
+                "subj_label": t.subject,
+                "pred": t.predicate, # Nota: Il predicato dinamico richiede attenzione in Cypher
+                "obj_uri": self.sanitize_name(t.object),
+                "obj_label": t.object,
+                "conf": t.confidence,
+                "src": t.source
+            })
+
+        # 2. Query Batch Ottimizzata
+        # Nota: In Cypher non si può parametrizzare il TIPO di relazione (es. :RELAZIONE).
+        # Per performance pura con relazioni dinamiche, usiamo APOC o un approccio ibrido.
+        # Qui usiamo un approccio sicuro iterando nel driver ma con transazione unica,
+        # oppure raggruppiamo per tipo di relazione. 
+        
+        # Approccio Migliore per MVP: Transazione singola
+        with self.driver.session() as session:
+            try:
+                session.execute_write(self._batch_write_tx, batch_data)
+                print("✅ Batch completato.")
+            except Exception as e:
+                print(f"⚠️ Errore durante il salvataggio batch: {e}")
+
+    @staticmethod
+    def _batch_write_tx(tx, batch_data):
+        """Funzione transazionale interna."""
+        for item in batch_data:
+            # Usiamo MERGE per evitare duplicati
+            # Usiamo apoc.create.relationship se disponibile per predicati dinamici,
+            # altrimenti usiamo string formatting controllata (safe perché interna).
+            
+            # Sanitizzazione predicato per evitare injection (solo caratteri sicuri)
+            safe_pred = "".join(x for x in item['pred'] if x.isalnum() or x in "_:")
+            if not safe_pred: safe_pred = "RELATED_TO"
+
+            query = (
+                f"MERGE (s:Resource {{uri: $subj_uri}}) "
+                f"ON CREATE SET s.label = $subj_label "
+                f"MERGE (o:Resource {{uri: $obj_uri}}) "
+                f"ON CREATE SET o.label = $obj_label "
+                f"MERGE (s)-[r:`{safe_pred}`]->(o) "
+                f"SET r.confidence = $conf, r.source = $src"
+            )
+            
+            tx.run(query, item)
+
+# --- TEST ISOLATO ---
+if __name__ == "__main__":
+    # Creiamo un mock per testare senza dipendenze esterne
+    from collections import namedtuple
+    MockTriple = namedtuple("MockTriple", ["subject", "predicate", "object", "confidence", "source"])
+
+    triples = [
+        MockTriple("Batch Node 1", "TEST_BATCH", "Batch Node 2", 0.99, "test_doc_1"),
+        MockTriple("Batch Node 2", "IS_RELATED_TO", "Batch Node 3", 0.85, "test_doc_1")
+    ]
+
+    # Assicurati di avere le variabili d'ambiente o fallback attivi
+    persister = KnowledgeGraphPersister()
+    persister.save_triples(triples)
+    persister.close()

src/ingestion/semantic_splitter.py

@@ -0,0 +1,169 @@
+import os
+import re
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn.metrics.pairwise import cosine_similarity
+from dotenv import load_dotenv
+from langchain_huggingface import HuggingFaceEmbeddings
+
+load_dotenv()
+
+class ActivaSemanticSplitter:
+    def __init__(self, model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2", batch_size=32):
+        self.batch_size = batch_size
+        provider = os.getenv("EMBEDDING_PROVIDER", "huggingface").lower()
+        
+        print(f"🔄 Inizializzazione Embedding Engine (Provider: {provider})...")
+        
+        try:
+            if provider == "openai":
+                from langchain_openai import OpenAIEmbeddings
+                api_key = os.getenv("OPENAI_API_KEY")
+                if not api_key:
+                    raise ValueError("OPENAI_API_KEY mancante nel file .env")
+                self.embedding_model = OpenAIEmbeddings(model="text-embedding-3-small")
+            else:
+                self.embedding_model = HuggingFaceEmbeddings(model_name=model_name)
+                
+            print("✅ Modello caricato correttamente.")
+            
+        except Exception as e:
+            print(f"❌ Errore caricamento modello: {e}")
+            raise e
+
+    def _split_sentences(self, text):
+        """
+        Divide il testo in frasi gestendo le abbreviazioni custom (es. sec., S.).
+        """
+        text = text.strip()
+        try:
+            import nltk
+            # Assicuriamoci 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)
+            
+            # FIX: Carichiamo il tokenizer italiano specifico
+            # Invece di usare sent_tokenize() che è una black box, carichiamo l'oggetto.
+            try:
+                tokenizer = nltk.data.load('tokenizers/punkt/italian.pickle')
+            except:
+                # Fallback se il pickle path non viene risolto automaticamente
+                from nltk.tokenize.punkt import PunktSentenceTokenizer
+                tokenizer = PunktSentenceTokenizer()
+
+            # --- LISTA ECCEZIONI ABBREVIAZIONI ---
+            # Diciamo al tokenizer che queste parole seguite da punto NON chiudono la frase
+            custom_abbrevs = ['sec', 's', 'prof', 'dott', 'avv', 'pag', 'fig', 'nr', 'art']
+            for abbr in custom_abbrevs:
+                tokenizer._params.abbrev_types.add(abbr)
+
+            sentences = tokenizer.tokenize(text)
+            
+        except ImportError:
+            print("⚠️ NLTK non installato. Fallback su Regex semplice.")
+            sentences = re.split(r'(?<=[.?!])\s+', text)
+        except Exception as e:
+            print(f"⚠️ Errore NLTK ({e}). Fallback su Regex.")
+            sentences = re.split(r'(?<=[.?!])\s+', text)
+            
+        return [s.strip() for s in sentences if len(s.strip()) > 5]
+
+    def combine_sentences(self, sentences, buffer_size=1):
+        combined = []
+        for i in range(len(sentences)):
+            start = max(0, i - buffer_size)
+            end = min(len(sentences), i + 1 + buffer_size)
+            combined_context = " ".join(sentences[start:end])
+            combined.append(combined_context)
+        return combined
+
+    def calculate_cosine_distances(self, sentences):
+        embeddings = []
+        total = len(sentences)
+        
+        for i in range(0, total, self.batch_size):
+            batch = sentences[i : i + self.batch_size]
+            batch_embeddings = self.embedding_model.embed_documents(batch)
+            embeddings.extend(batch_embeddings)
+
+        distances = []
+        for i in range(len(embeddings) - 1):
+            similarity = cosine_similarity([embeddings[i]], [embeddings[i+1]])[0][0]
+            distances.append(similarity)
+            
+        return distances, embeddings
+
+    def create_chunks(self, text, percentile_threshold=95):
+        single_sentences = self._split_sentences(text)
+        if not single_sentences:
+            return [], [], 0
+
+        combined_sentences = self.combine_sentences(single_sentences)
+        distances, _ = self.calculate_cosine_distances(combined_sentences)
+        
+        if not distances:
+            return [text], [], 0
+
+        threshold = np.percentile(distances, 100 - percentile_threshold)
+        indices_above_thresh = [i for i, x in enumerate(distances) if x < threshold]
+        
+        chunks = []
+        start_index = 0
+        breakpoints = indices_above_thresh + [len(single_sentences)]
+
+        for i in breakpoints:
+            end_index = i + 1
+            chunk_text = " ".join(single_sentences[start_index:end_index])
+            if len(chunk_text) > 20:
+                chunks.append(chunk_text)
+            start_index = end_index
+            
+        return chunks, distances, threshold
+
+    def plot_similarity(self, distances, threshold, filename="chunking_analysis.png"):
+        try:
+            plt.figure(figsize=(10, 6))
+            plt.plot(distances, label="Cosine Similarity")
+            plt.axhline(y=threshold, color='r', linestyle='--', label=f"Threshold")
+            plt.title("Analisi della Coerenza Vettoriale")
+            plt.xlabel("Frase")
+            plt.ylabel("Similarità")
+            plt.legend()
+            plt.savefig(filename)
+            print(f"📊 Grafico salvato: {filename}")
+            plt.close()
+        except Exception:
+            pass
+
+# --- TEST ---
+if __name__ == "__main__":
+    sample_text = """
+    La Basilica di S. Marco a Venezia è un'opera d'arte unica. 
+    Risale al sec. XI e rappresenta lo stile bizantino. 
+    L'interno è ricco di mosaici.
+    
+    Tuttavia, cambiando argomento, la cucina veneziana offre piatti come le sarde in saor.
+    È un piatto a base di cipolle e aceto.
+    """
+
+    splitter = ActivaSemanticSplitter()
+    # Soglia molto bassa (10) per FORZARE lo split solo sul cambio drastico di argomento
+    chunks, dists, thresh = splitter.create_chunks(sample_text, percentile_threshold=50)
+
+    print(f"\n--- TEST FIX ABBREVIAZIONI ---")
+    print(f"Input: {len(sample_text)} chars")
+    
+    # Debug delle frasi grezze riconosciute
+    sentences = splitter._split_sentences(sample_text)
+    print(f"Frasi riconosciute ({len(sentences)}):")
+    for s in sentences:
+        print(f"  - {s}")
+
+    print(f"\n--- CHUNK GENERATI ---")
+    for i, c in enumerate(chunks):
+        print(f"🔹 Chunk {i+1}: {c}")

src/validation/shapes/schema_constraints.ttl

@@ -0,0 +1,37 @@
+@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 rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# REGOLA GENERALE PER TUTTI I CONCETTI
+ex:ConceptShape
+    a sh:NodeShape ;
+    sh:targetClass skos:Concept ;
+    
+    # 1. Obbligo di Label (Accetta qualsiasi Literal con lingua)
+    sh:property [
+        sh:path skos:prefLabel ;
+        sh:minCount 1 ;
+        sh:nodeKind sh:Literal ;
+        sh:message "Ogni concetto deve avere una label."
+    ] ;
+
+    # 2. Relazione: Related
+    sh:property [
+        sh:path skos:related ;
+        sh:class skos:Concept ;
+        sh:message "La relazione 'related' deve puntare a un nodo di tipo Concept."
+    ] ;
+    
+    # 3. Relazione: Situato In
+    sh:property [
+        sh:path ex:situato_in ;
+        sh:class skos:Concept
+    ] ;
+    
+    # 4. Relazione: Broader
+    sh:property [
+        sh:path skos:broader ;
+        sh:class skos:Concept
+    ] .

src/validation/validator.py

@@ -0,0 +1,91 @@
+import os
+from rdflib import Graph, Literal, RDF, URIRef, Namespace
+from rdflib.namespace import SKOS, XSD
+from pyshacl import validate
+
+class SemanticValidator:
+    def __init__(self):
+        # Definiamo i namespace
+        self.EX = Namespace("http://activa.ai/ontology/")
+        self.shapes_file = os.path.join(os.path.dirname(__file__), "shapes/schema_constraints.ttl")
+        
+        # Carica le shapes se il file esiste, altrimenti usa grafo vuoto
+        if os.path.exists(self.shapes_file):
+            self.shacl_graph = Graph()
+            self.shacl_graph.parse(self.shapes_file, format="turtle")
+            print("🛡️  SHACL Constraints caricati.")
+        else:
+            print("⚠️  File SHACL non trovato. Validazione disabilitata.")
+            self.shacl_graph = None
+
+    def _json_to_rdf(self, triples):
+        """Converte le triple JSON (Pydantic) in un grafo RDFLib in memoria."""
+        g = Graph()
+        g.bind("skos", SKOS)
+        g.bind("ex", self.EX)
+
+        for t in triples:
+            # Creiamo URI sanitizzati
+            subj_uri = URIRef(self.EX[t.subject.replace(" ", "_")])
+            obj_uri = URIRef(self.EX[t.object.replace(" ", "_")])
+            
+            # Aggiungiamo il tipo Concept
+            g.add((subj_uri, RDF.type, SKOS.Concept))
+            g.add((subj_uri, SKOS.prefLabel, Literal(t.subject, lang="it")))
+            
+            g.add((obj_uri, RDF.type, SKOS.Concept))
+            g.add((obj_uri, SKOS.prefLabel, Literal(t.object, lang="it")))
+
+            # Mappiamo il predicato (se è standard o custom)
+            if t.predicate == "skos:related" or t.predicate == "related":
+                pred = SKOS.related
+            elif t.predicate == "skos:broader" or t.predicate == "broader":
+                pred = SKOS.broader
+            else:
+                # Fallback su namespace custom per predicati non standard (es. situato_in)
+                pred = self.EX[t.predicate]
+
+            g.add((subj_uri, pred, obj_uri))
+            
+        return g
+
+    def validate_batch(self, triples):
+        """
+        Esegue la validazione SHACL sulle triple.
+        Ritorna (is_valid, report_text, rdf_graph)
+        """
+        if not self.shacl_graph:
+            return True, "No Constraints", None
+
+        data_graph = self._json_to_rdf(triples)
+        
+        print("🔍 Esecuzione Validazione SHACL...")
+        conforms, report_graph, report_text = validate(
+            data_graph,
+            shacl_graph=self.shacl_graph,
+            inference='rdfs',
+            serialize_report_graph=True
+        )
+        
+        return conforms, report_text, data_graph
+
+# --- TEST DEL MODULO ---
+if __name__ == "__main__":
+    # Simuliamo triple dall'LLM
+    from collections import namedtuple
+    Triple = namedtuple("Triple", ["subject", "predicate", "object", "confidence"])
+    
+    # Caso Test: Una tripla valida e una (potenzialmente) invalida
+    mock_triples = [
+        Triple("Basilica San Marco", "situato_in", "Venezia", 0.9),
+        Triple("Venezia", "skos:related", "Laguna", 0.95)
+    ]
+    
+    validator = SemanticValidator()
+    is_valid, report, _ = validator.validate_batch(mock_triples)
+    
+    if is_valid:
+        print("✅ Dati Conformi allo Schema SHACL.")
+    else:
+        print("❌ Violazione dei vincoli rilevata!")
+        print(report)