scimapper 1.0.1__py3-none-any.whl

core/doc_builder.py

@@ -0,0 +1,316 @@
+"""
+AutoSMS Framework - Módulo Generador de Documentos Académicos (DocBuilder)
+========================================================================
+Construye automáticamente un borrador formal en Microsoft Word (.docx)
+con tipografía académica estandarizada (Times New Roman 10pt, justificado),
+tablas unificadas (#666666 / #F0F4F8), diagrama PRISMA tabulado, mapeo
+taxonómico y la estructura de Discusión Cualitativa con los papers seleccionados.
+"""
+
+import os
+import json
+import docx
+from docx.shared import Inches, Pt, RGBColor
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.oxml import OxmlElement, parse_xml
+from docx.oxml.ns import nsdecls, qn
+
+def set_cell_background(cell, color_hex: str):
+    """Asigna color de fondo a una celda de tabla."""
+    tcPr = cell._tc.get_or_add_tcPr()
+    for child in list(tcPr):
+        if child.tag.endswith('shd'):
+            tcPr.remove(child)
+    shading_elm = parse_xml(f'<w:shd {nsdecls("w")} w:fill="{color_hex}"/>')
+    tcPr.append(shading_elm)
+
+def set_cell_margins(cell, top=80, bottom=80, left=120, right=120):
+    """Establece márgenes internos (padding) de la celda en dxa."""
+    tcPr = cell._tc.get_or_add_tcPr()
+    for child in list(tcPr):
+        if child.tag.endswith('tcMar'):
+            tcPr.remove(child)
+    tcMar = OxmlElement('w:tcMar')
+    for m, val in [('top', top), ('bottom', bottom), ('left', left), ('right', right)]:
+        node = OxmlElement(f'w:{m}')
+        node.set(qn('w:w'), str(val))
+        node.set(qn('w:type'), 'dxa')
+        tcMar.append(node)
+    tcPr.append(tcMar)
+
+def style_academic_table(table, col_widths=None):
+    """Aplica formato visual académico uniforme a cualquier tabla."""
+    table.alignment = WD_TABLE_ALIGNMENT.CENTER
+    table.autofit = False
+
+    for row_idx, row in enumerate(table.rows):
+        is_header = (row_idx == 0)
+        bg_color = "666666" if is_header else ("F0F4F8" if row_idx % 2 == 1 else "FFFFFF")
+
+        for col_idx, cell in enumerate(row.cells):
+            set_cell_background(cell, bg_color)
+            set_cell_margins(cell, top=70, bottom=70, left=110, right=110)
+
+            if col_widths and col_idx < len(col_widths):
+                cell.width = col_widths[col_idx]
+
+            for p in cell.paragraphs:
+                p.paragraph_format.line_spacing = 1.05
+                p.paragraph_format.space_before = Pt(2)
+                p.paragraph_format.space_after = Pt(2)
+                for run in p.runs:
+                    run.font.name = "Times New Roman"
+                    run.font.size = Pt(9)
+                    if is_header:
+                        run.font.bold = True
+                        run.font.color.rgb = RGBColor(255, 255, 255)
+                    else:
+                        run.font.color.rgb = RGBColor(30, 30, 30)
+
+class AutoDocBuilder:
+    def __init__(self, config: dict):
+        self.config = config
+        self.meta = config.get("project_metadata", {})
+        self.rqs = config.get("research_questions", {})
+        self.output_dir = self.meta.get("output_dir", "./output")
+        self.title = self.meta.get("title", "Mapeo Sistemático de la Literatura")
+        self.authors = ", ".join(self.meta.get("authors", ["Investigador Principal"]))
+        self.years = self.meta.get("temporal_window", [2018, 2026])
+
+    def add_p(self, doc, text="", bold_prefix="", italic=False, space_after=4, align=WD_ALIGN_PARAGRAPH.JUSTIFY):
+        p = doc.add_paragraph()
+        p.alignment = align
+        p.paragraph_format.line_spacing = 1.15
+        p.paragraph_format.space_after = Pt(space_after)
+        p.paragraph_format.space_before = Pt(0)
+
+        if bold_prefix:
+            r_pre = p.add_run(bold_prefix)
+            r_pre.font.name = "Times New Roman"
+            r_pre.font.size = Pt(10)
+            r_pre.font.bold = True
+
+        if text:
+            r = p.add_run(text)
+            r.font.name = "Times New Roman"
+            r.font.size = Pt(10)
+            r.font.italic = italic
+        return p
+
+    def add_heading_1(self, doc, title_text):
+        p = doc.add_paragraph()
+        p.paragraph_format.space_before = Pt(14)
+        p.paragraph_format.space_after = Pt(6)
+        p.paragraph_format.keep_with_next = True
+        r = p.add_run(title_text)
+        r.font.name = "Times New Roman"
+        r.font.size = Pt(12)
+        r.font.bold = True
+        r.font.color.rgb = RGBColor(0, 51, 102)
+        return p
+
+    def add_heading_2(self, doc, title_text):
+        p = doc.add_paragraph()
+        p.paragraph_format.space_before = Pt(10)
+        p.paragraph_format.space_after = Pt(4)
+        p.paragraph_format.keep_with_next = True
+        r = p.add_run(title_text)
+        r.font.name = "Times New Roman"
+        r.font.size = Pt(10.5)
+        r.font.bold = True
+        r.font.italic = True
+        r.font.color.rgb = RGBColor(50, 50, 50)
+        return p
+
+    def generate_draft(self) -> str:
+        print("\n📄 GENERANDO BORRADOR FORMAL EN MICROSOFT WORD (.docx)...")
+        doc = docx.Document()
+
+        # Configuración de márgenes estándar (2.5 cm)
+        sections = doc.sections
+        for s in sections:
+            s.top_margin = Inches(1.0)
+            s.bottom_margin = Inches(1.0)
+            s.left_margin = Inches(1.0)
+            s.right_margin = Inches(1.0)
+
+        # 1. Título y Metadatos
+        p_title = doc.add_paragraph()
+        p_title.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        p_title.paragraph_format.space_after = Pt(8)
+        r_title = p_title.add_run(self.title)
+        r_title.font.name = "Times New Roman"
+        r_title.font.size = Pt(16)
+        r_title.font.bold = True
+
+        p_sub = doc.add_paragraph()
+        p_sub.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        p_sub.paragraph_format.space_after = Pt(18)
+        r_sub = p_sub.add_run(f"{self.authors}\nVentana de Estudio: {self.years[0]} – {self.years[1]}")
+        r_sub.font.name = "Times New Roman"
+        r_sub.font.size = Pt(10.5)
+        r_sub.font.italic = True
+
+        # Resumen / Abstract
+        self.add_p(doc, 
+            f"El presente estudio reporta un Mapeo Sistemático de la Literatura (SMS) conducido bajo las directrices PRISMA 2020. "
+            f"Se aplicó un pipeline computacional no supervisado basado en modelos de lenguaje denso (Sentence-Transformers) y "
+            f"extracción léxica diferencial (c-TF-IDF), acoplado con supervisión experta continua (Human-in-the-Loop) para categorizar "
+            f"el estado del arte, identificar vacíos de investigación y sintetizar evidencias empíricas.",
+            bold_prefix="Resumen— ")
+
+        # 2. SECCIÓN I: INTRODUCCIÓN
+        self.add_heading_1(doc, "I. INTRODUCCIÓN")
+        self.add_p(doc, 
+            "La creciente proliferación de literatura científica en esta disciplina exige metodologías sistemáticas y reproducibles "
+            "capaces de caracterizar el panorama bibliográfico sin sesgos de selección manual. "
+            "Para guiar esta investigación, se formularon las siguientes Preguntas de Investigación (RQs):")
+
+        for rq_id, rq_desc in self.rqs.items():
+            self.add_p(doc, rq_desc, bold_prefix=f"• {rq_id}: ")
+
+        # 3. SECCIÓN II: METODOLOGÍA Y FLUJO PRISMA 2020
+        self.add_heading_1(doc, "II. METODOLOGÍA Y PROTOCOLO PRISMA")
+        self.add_p(doc, 
+            "El proceso de selección bibliográfica siguió el estándar internacional PRISMA 2020 (Preferred Reporting Items for Systematic "
+            "Reviews and Meta-Analyses), combinando recolección automatizada de metadatos, deduplicación algorítmica y filtrado temático experto.")
+
+        # Cargar datos de tópicos y candidatos
+        topics_json_path = os.path.join(self.output_dir, "discovered_topics.json")
+        candidates_json_path = os.path.join(self.output_dir, "candidatos_discusion.json")
+
+        topics_info = {}
+        if os.path.exists(topics_json_path):
+            with open(topics_json_path, "r", encoding="utf-8") as f:
+                topics_info = json.load(f)
+
+        candidates = []
+        if os.path.exists(candidates_json_path):
+            with open(candidates_json_path, "r", encoding="utf-8") as f:
+                candidates = json.load(f)
+
+        total_mapped = sum(t.get("count", 0) for t in topics_info.values() if not t.get("exclude_prisma", False))
+        total_excluded = sum(t.get("count", 0) for t in topics_info.values() if t.get("exclude_prisma", False))
+        total_raw = total_mapped + total_excluded
+
+        # Tabla PRISMA
+        t_prisma = doc.add_table(rows=5, cols=4)
+        t_prisma.rows[0].cells[0].paragraphs[0].text = "Fase PRISMA"
+        t_prisma.rows[0].cells[1].paragraphs[0].text = "Descripción del Proceso"
+        t_prisma.rows[0].cells[2].paragraphs[0].text = "Registros"
+        t_prisma.rows[0].cells[3].paragraphs[0].text = "Criterio Aplicado"
+
+        datos_prisma = [
+            ("1. Identificación", "Búsqueda automatizada en fuentes académicas abiertas (OpenAlex)", f"N = {total_raw}", "Consultas booleanas estructuradas"),
+            ("2. Deduplicación", "Fusión de registros redundantes mediante DOI y hashes alfanuméricos", f"Filtrado", "Normalización estricta de títulos y DOIs"),
+            ("3. Screening Temático", "Agrupamiento vectorial y evaluación humana de relevancia", f"Excluidos: {total_excluded}", "Criterios de inclusión/exclusión del protocolo"),
+            ("4. Inclusión Final", "Corpus consolidado analizado en el mapeo conceptual y discusión", f"N = {total_mapped}", "Aptos para síntesis cuantitativa y cualitativa")
+        ]
+
+        for i, row in enumerate(datos_prisma):
+            for c_idx in range(4):
+                t_prisma.rows[i+1].cells[c_idx].paragraphs[0].text = row[c_idx]
+
+        style_academic_table(t_prisma, [Inches(1.3), Inches(2.5), Inches(1.1), Inches(1.6)])
+
+        # 4. SECCIÓN III: RESULTADOS Y TAXONOMÍA DEL MAPEO
+        self.add_heading_1(doc, "III. RESULTADOS: TAXONOMÍA Y DINÁMICA TEMPORAL")
+        self.add_p(doc, 
+            "El agrupamiento vectorial no supervisado acoplado a c-TF-IDF y el análisis de trayectorias temporales "
+            "permitieron caracterizar la estructura temática del corpus y su tasa de crecimiento anual compuesta (CAGR).")
+
+        # Tabla de Taxonomías con Dinámica Temporal
+        t_tax = doc.add_table(rows=1 + len(topics_info), cols=6)
+        t_tax.rows[0].cells[0].paragraphs[0].text = "ID"
+        t_tax.rows[0].cells[1].paragraphs[0].text = "Taxonomía / Tópico Descubierto"
+        t_tax.rows[0].cells[2].paragraphs[0].text = "Artículos"
+        t_tax.rows[0].cells[3].paragraphs[0].text = "%"
+        t_tax.rows[0].cells[4].paragraphs[0].text = "Dinámica y CAGR"
+        t_tax.rows[0].cells[5].paragraphs[0].text = "Descriptores Léxicos (c-TF-IDF)"
+
+        for r_idx, (tid, info) in enumerate(sorted(topics_info.items(), key=lambda x: int(x[0]))):
+            status = " [Excluido]" if info.get("exclude_prisma", False) else ""
+            t_dyn = info.get("temporal_dynamics", {})
+            badge = t_dyn.get("badge", "⚖️ Maduro")
+            cagr = t_dyn.get("cagr_percent", 0.0)
+
+            t_tax.rows[r_idx+1].cells[0].paragraphs[0].text = str(tid)
+            t_tax.rows[r_idx+1].cells[1].paragraphs[0].text = f"{info.get('assigned_name')}{status}"
+            t_tax.rows[r_idx+1].cells[2].paragraphs[0].text = str(info.get("count", 0))
+            t_tax.rows[r_idx+1].cells[3].paragraphs[0].text = f"{info.get('percentage', 0)}%"
+            t_tax.rows[r_idx+1].cells[4].paragraphs[0].text = f"{badge} ({cagr:+.1f}%)"
+            t_tax.rows[r_idx+1].cells[5].paragraphs[0].text = ", ".join(info.get("keywords", [])[:5])
+
+        style_academic_table(t_tax, [Inches(0.4), Inches(2.0), Inches(0.7), Inches(0.5), Inches(1.4), Inches(1.5)])
+
+        self.add_p(doc, 
+            "Como se observa en la tabla precedente, los tópicos catalogados como 'Emergentes' (🚀) exhiben una marcada aceleración "
+            "en su volumen de publicaciones en los últimos 3 años (CAGR > 12%), reflejando las líneas de frontera investigativa. "
+            "Por su parte, los tópicos 'Maduros' (⚖️) representan los fundamentos metodológicos consolidados de la disciplina.",
+            italic=True)
+
+        # 5. SECCIÓN IV: DISCUSIÓN CUALITATIVA
+        self.add_heading_1(doc, "IV. DISCUSIÓN Y SÍNTESIS CUALITATIVA")
+        self.add_p(doc, 
+            "Para complementar la visión macroscópica del mapeo, se realizó un análisis cualitativo a texto completo "
+            "sobre una muestra intencional estratificada de artículos representativos (medoides y publicaciones de alto impacto). "
+            "Esta síntesis responde a las metodologías empíricas y vacíos planteados en las RQs.")
+
+        selected_papers = [c for c in candidates if c.get("selected_for_deep_review", False)]
+        if not selected_papers and candidates:
+            # Si el usuario no marcó ninguno aún, tomar el top 1 de cada tópico
+            selected_papers = [c for c in candidates if c.get("rank_in_topic", 1) == 1]
+
+        # Tabla de Artículos Seleccionados
+        self.add_heading_2(doc, "Matriz de Artículos Analizados a Texto Completo")
+        t_sel = doc.add_table(rows=1 + len(selected_papers), cols=5)
+        t_sel.rows[0].cells[0].paragraphs[0].text = "Ref"
+        t_sel.rows[0].cells[1].paragraphs[0].text = "Artículo / Autores"
+        t_sel.rows[0].cells[2].paragraphs[0].text = "Año | Citas"
+        t_sel.rows[0].cells[3].paragraphs[0].text = "Tópico"
+        t_sel.rows[0].cells[4].paragraphs[0].text = "Técnica / Aporte Principal"
+
+        for p_idx, p_data in enumerate(selected_papers):
+            t_sel.rows[p_idx+1].cells[0].paragraphs[0].text = f"P{p_idx+1}"
+            t_sel.rows[p_idx+1].cells[1].paragraphs[0].text = f"{p_data.get('title')}\n({p_data.get('authors')[:40]}...)"
+            t_sel.rows[p_idx+1].cells[2].paragraphs[0].text = f"{p_data.get('publication_year')} | {p_data.get('cited_by_count')} citas"
+            t_sel.rows[p_idx+1].cells[3].paragraphs[0].text = str(p_data.get("topic_name"))[:25]
+            t_sel.rows[p_idx+1].cells[4].paragraphs[0].text = "[Completar técnica y aporte específico]"
+
+        style_academic_table(t_sel, [Inches(0.5), Inches(2.6), Inches(1.0), Inches(1.1), Inches(1.3)])
+
+        # Subsecciones por artículo para redactar hallazgos
+        for p_idx, p_data in enumerate(selected_papers):
+            self.add_heading_2(doc, f"Análisis de P{p_idx+1}: {p_data.get('title')}")
+            self.add_p(doc, f"Autores: {p_data.get('authors')} ({p_data.get('publication_year')}). Publicado en: {p_data.get('venue')}. DOI: {p_data.get('doi')}")
+            self.add_p(doc, p_data.get('abstract', ''), bold_prefix="Síntesis del Abstract: ", italic=True)
+            self.add_p(doc, 
+                f"[Espacio para el investigador]: Describir aquí los hallazgos empíricos clave de este estudio en relación con {list(self.rqs.keys())[0] if self.rqs else 'las RQs'}. "
+                f"Evaluar el rigor de su validación experimental y las limitaciones identificadas por los autores.",
+                bold_prefix="Hallazgos Empíricos y Limitaciones: ")
+
+        # 6. SECCIÓN V: AMENAZAS A LA VALIDEZ
+        self.add_heading_1(doc, "V. AMENAZAS A LA VALIDEZ")
+        self.add_p(doc, "Sesgo de cobertura en fuentes bibliográficas y sensibilidad de las consultas de búsqueda.", bold_prefix="• Validez de Construcción: ")
+        self.add_p(doc, "Posibles sesgos en la interpretación humana durante el nombramiento de clusters y selección de papers para la discusión profunda.", bold_prefix="• Validez Interna: ")
+        self.add_p(doc, "Generalizabilidad de los patrones taxonómicos a entornos industriales no documentados formalmente en la literatura indexada.", bold_prefix="• Validez Externa: ")
+
+        # 7. SECCIÓN VI: CONCLUSIONES
+        self.add_heading_1(doc, "VI. CONCLUSIONES Y TRABAJO FUTURO")
+        self.add_p(doc, 
+            "El mapeo sistemático ha permitido sintetizar de manera estructurada y auditable el estado del arte en el dominio. "
+            "La integración de modelos de lenguaje densos con supervisión humana experta ofreció un balance óptimo entre "
+            "exhaustividad de cobertura y precisión interpretativa, identificando oportunidades prometedoras para futuras investigaciones.")
+
+        # Guardar archivo con manejo de fallback
+        out_docx = os.path.join(self.output_dir, f"{self.meta.get('short_name', 'Mapeo_Sistematico')}_BORRADOR.docx")
+        try:
+            doc.save(out_docx)
+            print(f"✔ Documento Word formal guardado exitosamente en: {out_docx}")
+            return out_docx
+        except PermissionError:
+            fallback = os.path.join(self.output_dir, f"{self.meta.get('short_name', 'Mapeo_Sistematico')}_BORRADOR_NUEVO.docx")
+            doc.save(fallback)
+            print(f"⚠️ El archivo original estaba abierto en Word. Guardado en fallback: {fallback}")
+            return fallback

core/embedder.py

@@ -0,0 +1,70 @@
+"""
+AutoSMS Framework - Módulo de Embeddings (Embedder)
+Gestiona la selección de modelos de lenguaje por dominio,
+vectorización semántica densa y caché de vectores binarios.
+"""
+
+import os
+import json
+import hashlib
+import numpy as np
+import pandas as pd
+import logging
+from sentence_transformers import SentenceTransformer
+
+logger = logging.getLogger("scimapper.embedder")
+
+class AutoEmbedder:
+    def __init__(self, config: dict):
+        self.config = config
+        self.nlp_cfg = config.get("nlp_tuning", {})
+        self.output_dir = config.get("project_metadata", {}).get("output_dir", "./output")
+        os.makedirs(self.output_dir, exist_ok=True)
+
+        # Determinar modelo según preset o selección personalizada
+        preset = self.nlp_cfg.get("domain_preset", "software_engineering")
+        catalog = self.nlp_cfg.get("domain_presets_catalog", {})
+        self.model_name = catalog.get(preset, self.nlp_cfg.get("embedding_model", "sentence-transformers/all-MiniLM-L6-v2"))
+        model_slug = hashlib.sha256(self.model_name.encode()).hexdigest()[:8]
+        self.cache_file = os.path.join(self.output_dir, f"embeddings_cache_{model_slug}.npy")
+        self.meta_file = os.path.join(self.output_dir, f"embeddings_cache_{model_slug}.json")
+
+    def _cache_valid(self, n_texts: int) -> bool:
+        if not (os.path.exists(self.cache_file) and os.path.exists(self.meta_file)):
+            return False
+        try:
+            with open(self.meta_file, "r", encoding="utf-8") as f:
+                meta = json.load(f)
+            if meta.get("model_name") != self.model_name:
+                return False
+            if meta.get("n_texts") != n_texts:
+                return False
+            arr = np.load(self.cache_file)
+            if arr.shape[0] != n_texts:
+                return False
+            return True
+        except Exception:
+            return False
+
+    def encode(self, df: pd.DataFrame) -> np.ndarray:
+        logger.info("GENERACIÓN DE EMBEDDINGS DENSOS...")
+        logger.info("Modelo seleccionado: %s", self.model_name)
+
+        textos = (df["title"] + ". " + df["abstract"]).tolist()
+
+        if self._cache_valid(len(textos)):
+            logger.info("Cargando vectores precalculados desde caché: %s", self.cache_file)
+            return np.load(self.cache_file)
+
+        logger.info("Iniciando inferencia semántica sobre %d documentos...", len(textos))
+        model = SentenceTransformer(self.model_name)
+        embeddings = model.encode(textos, show_progress_bar=True, batch_size=32, normalize_embeddings=True)
+
+        np.save(self.cache_file, embeddings)
+        with open(self.meta_file, "w", encoding="utf-8") as f:
+            json.dump(
+                {"model_name": self.model_name, "n_texts": len(textos), "shape": list(embeddings.shape)},
+                f, indent=2, ensure_ascii=False,
+            )
+        logger.info("Vectores guardados (%d docs, %d dims).", embeddings.shape[0], embeddings.shape[1])
+        return embeddings

core/selector.py

@@ -0,0 +1,129 @@
+"""
+AutoSMS Framework - Módulo de Selección Estratificada (Selector)
+==============================================================
+Identifica de forma algorítmica los artículos candidatos más representativos
+para la Discusión Cualitativa Profunda mediante:
+1. Umbral inteligente de citas mínimas (prioriza papers con validación bibliométrica).
+2. Centralidad semántica respecto al centroide del cluster (medoide).
+3. Impacto de citas normalizado logarítmicamente.
+4. Cobertura proporcional balanceada por cada una de las taxonomías activas.
+"""
+
+import os
+import json
+import numpy as np
+import pandas as pd
+
+class AutoSelector:
+    def __init__(self, config: dict):
+        self.config = config
+        self.output_dir = config.get("project_metadata", {}).get("output_dir", "./output")
+        self.synth_cfg = config.get("qualitative_synthesis", {})
+        self.top_per_topic = self.synth_cfg.get("candidates_per_topic", 3)
+        self.min_citations = self.synth_cfg.get("min_citations", 1)
+
+    def select_candidates(self, df: pd.DataFrame, embeddings: np.ndarray, topics_info: dict) -> list:
+        print("\n🎯 SELECCIÓN ESTRATIFICADA DE ARTÍCULOS PARA LA DISCUSIÓN...")
+        print(f"   Estrategia: Centralidad Semántica (60%) + Citas (40%) | Umbral preferente: >= {self.min_citations} citas")
+
+        df = df.reset_index(drop=True).copy()
+        if len(df) != len(embeddings):
+            raise ValueError(f"Desalineación df/embeddings: {len(df)} vs {len(embeddings)}")
+
+        candidates_list = []
+
+        # Asegurar tipos y columnas
+        df["topic_id"] = df["topic_id"].astype(int)
+        df["cited_by_count"] = pd.to_numeric(df.get("cited_by_count", 0), errors="coerce").fillna(0).astype(int)
+
+        for tid_str, t_info in topics_info.items():
+            tid = int(tid_str)
+            if t_info.get("exclude_prisma", False):
+                print(f"   [!] Omitiendo Tópico {tid} (marcado como excluido en PRISMA).")
+                continue
+
+            indices = df.index[df["topic_id"] == tid].tolist()
+            if not indices:
+                continue
+
+            sub_embs = embeddings[indices]
+            sub_df = df.loc[indices].copy()
+
+            # 1. Calcular centroide semántico del cluster
+            centroid = np.mean(sub_embs, axis=0)
+            centroid_norm = np.linalg.norm(centroid) + 1e-9
+
+            # 2. Similaridad Coseno con el centroide (Centralidad)
+            sub_norms = np.linalg.norm(sub_embs, axis=1) + 1e-9
+            cos_sim = np.dot(sub_embs, centroid) / (sub_norms * centroid_norm)
+            sim_min, sim_max = cos_sim.min(), cos_sim.max()
+            sim_scaled = (cos_sim - sim_min) / (sim_max - sim_min + 1e-9)
+
+            # 3. Impacto de Citas normalizado logarítmicamente
+            cites = sub_df["cited_by_count"].values
+            cite_log = np.log1p(cites)
+            cite_min, cite_max = cite_log.min(), cite_log.max()
+            cite_scaled = (cite_log - cite_min) / (cite_max - cite_min + 1e-9)
+
+            # 4. Puntuación combinada multiobjetivo
+            composite_score = (0.60 * sim_scaled) + (0.40 * cite_scaled)
+            sub_df["score_representatividad"] = np.round(composite_score, 4)
+            sub_df["centralidad_semantica"] = np.round(cos_sim, 4)
+
+            # 5. Filtro inteligente de citas mínimas:
+            # Si existen papers en este cluster con >= min_citations, se les da prioridad
+            has_cited_papers = (sub_df["cited_by_count"] >= self.min_citations).any()
+            sub_df["meets_citation_threshold"] = sub_df["cited_by_count"] >= self.min_citations
+
+            if has_cited_papers:
+                # Priorizar primero los que superan el umbral de citas, luego por score
+                sorted_candidates = sub_df.sort_values(
+                    by=["meets_citation_threshold", "score_representatividad"],
+                    ascending=[False, False]
+                ).head(self.top_per_topic)
+            else:
+                # Si todos tienen 0 citas (ej. cluster 100% de 2025/2026), ordenar puramente por score
+                sorted_candidates = sub_df.sort_values(by="score_representatividad", ascending=False).head(self.top_per_topic)
+
+            for rank, (_, row) in enumerate(sorted_candidates.iterrows()):
+                is_preselected = (rank == 0)
+                n_cites = int(row["cited_by_count"])
+                
+                if n_cites >= self.min_citations:
+                    notes = f"✔ Validación bibliométrica confirmada ({n_cites} citas)."
+                else:
+                    notes = "⚠️ Sin citas acumuladas (publicación reciente/early access). Validar aporte cualitativo."
+
+                candidates_list.append({
+                    "topic_id": tid,
+                    "topic_name": t_info.get("assigned_name", f"Tópico {tid}"),
+                    "rank_in_topic": rank + 1,
+                    "selected_for_deep_review": is_preselected,
+                    "title": str(row["title"]),
+                    "authors": str(row["authors"]),
+                    "publication_year": int(row["publication_year"]) if str(row["publication_year"]).isdigit() else 2024,
+                    "venue": str(row["venue"]),
+                    "cited_by_count": n_cites,
+                    "doi": str(row["doi"]),
+                    "centrality_score": float(row["centralidad_semantica"]),
+                    "composite_score": float(row["score_representatividad"]),
+                    "meets_citation_threshold": bool(row["meets_citation_threshold"]),
+                    "abstract": str(row["abstract"]),
+                    "human_notes": notes
+                })
+
+        # Guardar en JSON (para edición humana)
+        json_out = os.path.join(self.output_dir, "candidatos_discusion.json")
+        with open(json_out, "w", encoding="utf-8") as f:
+            json.dump(candidates_list, f, indent=2, ensure_ascii=False)
+
+        # Guardar también en CSV (para lectura en Excel)
+        csv_out = os.path.join(self.output_dir, "candidatos_discusion.csv")
+        export_df = pd.DataFrame(candidates_list).drop(columns=["abstract"])
+        export_df.to_csv(csv_out, index=False, encoding="utf-8-sig")
+
+        print(f"✔ Lista de candidatos sugeridos generada ({len(candidates_list)} artículos evaluados):")
+        print(f"   JSON editable: {json_out}")
+        print(f"   CSV resumido:  {csv_out}")
+        print("💡 Abre 'candidatos_discusion.json' y ajusta 'selected_for_deep_review': true/false según tu criterio.")
+        return candidates_list

core/utils.py

@@ -0,0 +1,79 @@
+"""Utility helpers for SciMapper: logging, validation and reproducibility."""
+
+import json
+import logging
+import os
+import hashlib
+from datetime import datetime
+
+
+def setup_logging(verbose: bool = False) -> logging.Logger:
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+        datefmt="%H:%M:%S",
+    )
+    return logging.getLogger("scimapper")
+
+
+def validate_config(config: dict) -> list:
+    """Return a list of validation errors (empty if valid)."""
+    errors = []
+    meta = config.get("project_metadata", {})
+    if not isinstance(meta, dict):
+        errors.append("project_metadata debe ser un objeto.")
+        return errors
+
+    if not meta.get("title"):
+        errors.append("project_metadata.title es obligatorio.")
+    if not meta.get("short_name"):
+        errors.append("project_metadata.short_name es obligatorio.")
+
+    years = meta.get("temporal_window", [])
+    if not (isinstance(years, list) and len(years) == 2):
+        errors.append("project_metadata.temporal_window debe ser [año_inicio, año_fin].")
+    else:
+        try:
+            y0, y1 = int(years[0]), int(years[1])
+            if y0 > y1:
+                errors.append("temporal_window: el año inicial no puede ser mayor al final.")
+            if y0 < 1900 or y1 > 2100:
+                errors.append("temporal_window: rango de años fuera de límites razonables.")
+        except (TypeError, ValueError):
+            errors.append("temporal_window debe contener enteros.")
+
+    strategy = config.get("search_strategy", {})
+    queries = strategy.get("queries", [])
+    if not isinstance(queries, list) or not queries:
+        errors.append("search_strategy.queries debe ser una lista no vacía.")
+    if not strategy.get("openalex_email"):
+        errors.append("search_strategy.openalex_email es obligatorio.")
+
+    nlp = config.get("nlp_tuning", {})
+    k = nlp.get("n_clusters", 6)
+    try:
+        if int(k) < 2 or int(k) > 50:
+            errors.append("nlp_tuning.n_clusters debe estar entre 2 y 50.")
+    except (TypeError, ValueError):
+        errors.append("nlp_tuning.n_clusters debe ser entero.")
+
+    return errors
+
+
+def config_hash(config: dict) -> str:
+    blob = json.dumps(config, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    return hashlib.sha256(blob).hexdigest()[:12]
+
+
+def write_manifest(output_dir: str, config: dict, counts: dict) -> str:
+    os.makedirs(output_dir, exist_ok=True)
+    manifest = {
+        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "config_hash": config_hash(config),
+        "counts": counts,
+    }
+    path = os.path.join(output_dir, "run_manifest.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2, ensure_ascii=False)
+    return path