#!/usr/bin/env python3 # -*- coding: utf-8 -*- import os import traceback from flask import Flask, request, jsonify from flask_cors import CORS # Try to import spaCy lazily and handle missing models gracefully try: import spacy except Exception: spacy = None # ------------------------------ # Config # ------------------------------ MAX_SENTENCE_LENGTH = 2000 # characters, to avoid huge inputs SUBORD_DEPS = {"acl:relcl", "advcl", "ccomp", "csubj", "xcomp", "acl", "parataxis"} # ------------------------------ # Utility dictionaries (Italian) # ------------------------------ SPIEGAZIONI_POS_IT = { "ADJ": "Aggettivo", "ADP": "Preposizione", "ADV": "Avverbio", "AUX": "Ausiliare", "CONJ": "Congiunzione", "CCONJ": "Congiunzione Coordinante", "SCONJ": "Congiunzione Subordinante", "DET": "Determinante", "INTJ": "Interiezione", "NOUN": "Sostantivo", "NUM": "Numerale", "PART": "Particella", "PRON": "Pronome", "PROPN": "Nome Proprio", "PUNCT": "Punteggiatura", "SPACE": "Spazio", "SYM": "Simbolo", "VERB": "Verbo", "X": "Altro", } SPIEGAZIONI_ENT_IT = { "PER": "Persona", "LOC": "Luogo", "ORG": "Organizzazione", "MISC": "Miscellanea", # spaCy uses many possible entity labels depending on model/lang — fallback to label itself later } KEY_MAP = { "Gender": "Genere", "Number": "Numero", "Mood": "Modo", "Tense": "Tempo", "Person": "Persona", "VerbForm": "Forma del Verbo", "PronType": "Tipo di Pronome", "Clitic": "Clitico", "Definite": "Definitezza", "Degree": "Grado", "Case": "Caso", "Poss": "Possessivo", "Reflex": "Riflessivo", "Aspect": "Aspetto", "Voice": "Voce", } VALUE_MAP = { "Masc": "Maschile", "Fem": "Femminile", "Sing": "Singolare", "Plur": "Plurale", "Cnd": "Condizionale", "Sub": "Congiuntivo", "Ind": "Indicativo", "Imp": "Imperfetto", "Inf": "Infinito", "Part": "Participio", "Ger": "Gerundio", "Fin": "Finita", "Pres": "Presente", "Past": "Passato", "Fut": "Futuro", "Pqp": "Trapassato", "1": "1ª", "2": "2ª", "3": "3ª", "Prs": "Personale", "Rel": "Relativo", "Int": "Interrogativo", "Dem": "Dimostrativo", "Art": "Articolativo", "Yes": "Sì", "No": "No", "Def": "Determinato", "Indef": "Indefinito", "Abs": "Assoluto", "Cmp": "Comparativo", "Sup": "Superlativo", "Nom": "Nominativo", "Acc": "Accusativo", "Gen": "Genitivo", "Dat": "Dativo", "Perf": "Perfetto", "Prog": "Progressivo", "Act": "Attiva", "Pass": "Passiva", } PAIR_VALUE_MAP = { ("Mood", "Imp"): "Imperativo", ("Tense", "Imp"): "Imperfetto", ("Mood", "Ind"): "Indicativo", ("Definite", "Ind"): "Indeterminato", } # ------------------------------ # Map dependency labels to Italian labels and explanations # ------------------------------ MAPPA_DEP = { "nsubj": {"label": "Soggetto", "description": "Indica chi o cosa compie l'azione o si trova in un certo stato."}, "nsubj:pass": {"label": "Soggetto (Passivo)", "description": "Soggetto di una frase in forma passiva."}, "ROOT": {"label": "Predicato Verbale", "description": "Esprime l'azione, l'esistenza o lo stato del soggetto."}, "obj": {"label": "Complemento Oggetto", "description": "Indica l'oggetto diretto dell'azione. Risponde alla domanda: chi? / che cosa?"}, "iobj": {"label": "Complemento di Termine", "description": "Indica a chi o a cosa è destinata l'azione. Risponde alla domanda: a chi? / a che cosa?"}, "obl": {"label": "Complemento Indiretto", "description": "Fornisce informazioni aggiuntive (luogo, tempo, modo, causa, ecc.)."}, "obl:agent": {"label": "Complemento d'Agente", "description": "Indica chi compie l'azione in una frase passiva. Risponde alla domanda: da chi?"}, "nmod": {"label": "Complemento di Specificazione", "description": "Specifica o definisce un altro nome. Risponde alla domanda: di chi? / di che cosa?"}, "amod": {"label": "Attributo", "description": "Aggettivo che qualifica o descrive un nome a cui si riferisce."}, "advmod": {"label": "Complemento Avverbiale", "description": "Modifica o precisa il significato di un verbo, aggettivo o altro avverbio."}, "appos": {"label": "Apposizione", "description": "Sostantivo che si affianca a un altro per meglio identificarlo."}, "acl:relcl": {"label": "Proposizione Subordinata Relativa", "description": "Frase introdotta da un pronome relativo che espande un nome."}, "advcl": {"label": "Proposizione Subordinata Avverbiale", "description": "Frase che funziona come un complemento avverbiale per la principale."}, "ccomp": {"label": "Proposizione Subordinata Oggettiva", "description": "Frase che funge da complemento oggetto del verbo della principale."}, "csubj": {"label": "Proposizione Subordinata Soggettiva", "description": "Frase che funge da soggetto del verbo della principale."}, "xcomp": {"label": "Complemento Predicativo", "description": "Completa il significato del verbo riferendosi al soggetto o all'oggetto."}, "conj": {"label": "Elemento Coordinato", "description": "Elemento collegato a un altro con la stessa funzione logica."}, "cc": {"label": "Congiunzione Coordinante", "description": "Congiunzione (es. e, ma, o) che collega elementi con la stessa funzione."}, "cop": {"label": "Copula", "description": "Verbo 'essere' che collega il soggetto a un nome o aggettivo (parte nominale)."}, } # ------------------------------ # Model load helper (non-blocking) # ------------------------------ def load_it_model(): """ Try to load an Italian spaCy model in order of quality. Returns (nlp, model_name, error_message) where nlp may be None. """ if spacy is None: return None, None, "La libreria spaCy non è installata. Esegui: pip install spacy" candidates = ["it_core_news_lg", "it_core_news_md", "it_core_news_sm"] last_err = None for name in candidates: try: nlp = spacy.load(name) return nlp, name, None except Exception as e: last_err = e suggestion = ( "Impossibile caricare un modello italiano spaCy. " "Installa almeno uno tra: it_core_news_lg / it_core_news_md / it_core_news_sm.\n" "Esempio: python -m spacy download it_core_news_lg\n" f"Dettagli ultimo errore: {last_err}" ) return None, None, suggestion nlp, IT_MODEL, MODEL_LOAD_ERROR = load_it_model() # ------------------------------ # Small helper converters # ------------------------------ def spiega_in_italiano(tag, tipo='pos'): if tipo == 'pos': return SPIEGAZIONI_POS_IT.get(tag, tag) if tipo == 'ent': return SPIEGAZIONI_ENT_IT.get(tag, tag) return tag def traduci_morfologia(morph_str: str) -> str: if not morph_str or morph_str == "___": return "Non disponibile" parti = morph_str.split('|') parti_tradotte = [] for parte in parti: if '=' not in parte: continue chiave, valore = parte.split('=', 1) chiave_trad = KEY_MAP.get(chiave, chiave) valore_trad = PAIR_VALUE_MAP.get((chiave, valore), VALUE_MAP.get(valore, valore)) parti_tradotte.append(f"{chiave_trad}: {valore_trad}") return ", ".join(parti_tradotte) or "Non disponibile" def ottieni_tipo_complemento_con_dettagli(token): """ Given a token that is an 'obl' or similar, inspect 'case' (preposition) children to return a more precise complement label (e.g. stato in luogo, di termine, ecc.) """ # find child with dep_ == 'case' (a preposition) case_token = next((c for c in token.children if c.dep_ == 'case'), None) if not case_token: # fallback return MAPPA_DEP.get("obl", {"label": "Complemento", "description": "Complemento non specificato."}) prepo = case_token.text.lower() # mapping by start of preposition mappa = { "di": ("Complemento di Specificazione", "Risponde alla domanda: di chi? / di che cosa?"), "a": ("Complemento di Termine", "Risponde alla domanda: a chi? / a che cosa?"), "da": ("Complemento di Moto da Luogo / Origine", "Risponde alla domanda: da dove?"), "in": ("Complemento di Stato in Luogo", "Risponde alla domanda: dove?"), "con": ("Complemento di Compagnia o Mezzo", "Risponde alla domanda: con chi? / con che cosa?"), "su": ("Complemento di Argomento o Luogo", "Risponde alla domanda: su chi? / su che cosa? / dove?"), "per": ("Complemento di Fine o Causa", "Risponde alla domanda: per quale fine? / per quale causa?"), "tra": ("Complemento Partitivo / Luogo", "Risponde alla domanda: tra chi? / tra cosa?"), "fra": ("Complemento Partitivo / Luogo", "Risponde alla domanda: fra chi? / fra cosa?"), "sopra": ("Complemento di Luogo", "Risponde alla domanda: dove?"), "sotto": ("Complemento di Luogo", "Risponde alla domanda: dove?"), } for base, (label, desc) in mappa.items(): if prepo.startswith(base): # special-case: 'da' + passive aux => agente if base == "da" and any(c.dep_.endswith('agent') or c.dep_ == 'aux:pass' for c in token.head.children): return {"label": "Complemento d'Agente", "description": "Indica da chi è compiuta l'azione in una frase passiva."} return {"label": label, "description": desc} return MAPPA_DEP.get("obl", {"label": "Complemento", "description": "Complemento non specificato."}) def get_full_phrase_for_token(token): """ Build a compact phrase for a head token by collecting determiners, amod, case, compounds, and simple modifiers. Returns (text, set(indices)). """ # recursive collection but with small scope to avoid over-collecting collected = set() def collect(t): if t.i in collected: return collected.add(t.i) # Collect children that usually belong inside the noun phrase / token phrase for child in t.children: if child.dep_ in ('det', 'amod', 'case', 'compound', 'nummod', 'appos', 'fixed', 'flat', 'advmod'): collect(child) collect(token) # also include simple coordinated tokens (conj) for child in token.children: if child.dep_ == 'conj': collect(child) # include the coordinating conjunction token if present (cc) cc = next((c for c in child.children if c.dep_ == 'cc'), None) if cc: collected.add(cc.i) # sort by token index tokens = sorted(collected) text = " ".join(token.doc[i].text for i in tokens) return text, set(tokens) def costruisci_sintagmi_con_dettagli(tokens_proposizione): """ Build structured analysis for each "major" token in a clause. """ risultato = [] # tokens_proposizione assumed to be a list of spaCy tokens (no punctuation/space) DEPS_DA_SALTARE = {'det', 'amod', 'case', 'aux', 'aux:pass', 'cop', 'mark', 'cc', 'compound', 'appos', 'punct'} indici_elaborati = set() for token in tokens_proposizione: if token.i in indici_elaborati: continue # skip tokens that are primarily modifiers (we will include them as part of head tokens) if token.dep_ in DEPS_DA_SALTARE and token.head.i != token.i: continue testo_sintagma, indici_usati = get_full_phrase_for_token(token) dep = token.dep_ if dep in ('obl', 'obl:agent', 'nmod'): info_etichetta = ottieni_tipo_complemento_con_dettagli(token) else: info_etichetta = MAPPA_DEP.get(dep, {"label": dep.capitalize(), "description": "Relazione non mappata."}) token_details = { "lemma": getattr(token, "lemma_", token.text), "pos": f"{getattr(token, 'pos_', token.pos_)}: {spiega_in_italiano(getattr(token, 'pos_', token.pos_), 'pos')}", "tag": getattr(token, "tag_", ""), "morph": traduci_morfologia(str(getattr(token, "morph", ""))) } risultato.append({ "text": testo_sintagma, "label_info": info_etichetta, "token_details": token_details, "token_index": token.i }) indici_elaborati.update(indici_usati) # include leftover important tokens like copula or coordinating conjunctions if not already included for token in tokens_proposizione: if token.i not in indici_elaborati and token.dep_ in ('cop', 'cc'): risultato.append({ "text": token.text, "label_info": MAPPA_DEP.get(token.dep_, {"label": token.dep_, "description": ""}), "token_details": { "lemma": getattr(token, "lemma_", token.text), "pos": f"{getattr(token, 'pos_', token.pos_)}: {spiega_in_italiano(getattr(token, 'pos_', token.pos_), 'pos')}", "tag": getattr(token, "tag_", ""), "morph": traduci_morfologia(str(getattr(token, "morph", ""))) }, "token_index": token.i }) indici_elaborati.add(token.i) risultato.sort(key=lambda x: x['token_index']) return risultato def analizza_proposizione_con_dettagli(tokens): tokens_validi = [t for t in tokens if not t.is_punct and not t.is_space] return costruisci_sintagmi_con_dettagli(tokens_validi) # ------------------------------ # Flask app # ------------------------------ app = Flask(__name__) CORS(app) @app.route("/") def home(): status = "ok" if nlp else "model_missing" return jsonify({ "messaggio": "API analisi logica in esecuzione", "modello_spacy": IT_MODEL or "Nessuno", "model_status": status, "model_error": MODEL_LOAD_ERROR }) @app.route('/api/analyze', methods=['POST']) def analizza_frase(): # Basic checks if not nlp: return jsonify({"errore": "Modello spaCy non caricato.", "dettagli": MODEL_LOAD_ERROR}), 503 try: dati = request.get_json(silent=True) or {} frase = (dati.get('sentence') or "").strip() if not frase: return jsonify({"errore": "Frase non fornita o vuota."}), 400 if len(frase) > MAX_SENTENCE_LENGTH: return jsonify({"errore": "Frase troppo lunga.", "max_length": MAX_SENTENCE_LENGTH}), 400 doc = nlp(frase) proposizioni_subordinate = [] indici_subordinate = set() # detect subordinate clauses via tokens that have dependency in SUBORD_DEPS for token in doc: if token.dep_ in SUBORD_DEPS and token.i not in indici_subordinate: subtree = list(token.subtree) indici_subtree = {t.i for t in subtree} indici_subordinate.update(indici_subtree) info_tipo = MAPPA_DEP.get(token.dep_, {"label": "Proposizione Subordinata", "description": "Frase che dipende da un'altra."}) proposizioni_subordinate.append({ "type_info": info_tipo, "text": " ".join(t.text for t in subtree if not t.is_punct).strip(), "analysis": analizza_proposizione_con_dettagli(subtree) }) # main clause tokens are tokens not part of subordinate clause subtrees token_principale = [t for t in doc if t.i not in indici_subordinate and not t.is_punct and not t.is_space] # named entities (unique) entita_nominate = [] visti = set() for ent in doc.ents: if ent.text not in visti: visti.add(ent.text) entita_nominate.append({ "text": ent.text, "label": ent.label_, "explanation": spiega_in_italiano(ent.label_, 'ent') }) analisi_finale = { "full_sentence": frase, "model": IT_MODEL, "main_clause": { "text": " ".join(t.text for t in token_principale).strip(), "analysis": analizza_proposizione_con_dettagli(token_principale) }, "subordinate_clauses": proposizioni_subordinate, "named_entities": entita_nominate } return jsonify(analisi_finale) except Exception as e: # print to server log for debugging but return safe message traceback.print_exc() return jsonify({"errore": "Si è verificato un errore interno.", "dettagli": str(e)}), 500 if __name__ == '__main__': port = int(os.environ.get("PORT", 8080)) # Note: debug=False for production; set to True only during development app.run(host="0.0.0.0", port=port, debug=False, threaded=True)