feat: implement batch NLP analysis endpoint with automated entity resolution and data integration logic.

app.py

@@ -143,6 +143,11 @@ class ProcessSheetPayloadRaw(BaseModel):
     institucion: Optional[str] = None
     tipo_fuente: Optional[str] = None
 
+from typing import Union
+
+class BatchPayload(BaseModel):
+    records: List[ProcessSheetPayloadRaw]
+
 @app.get("/")
 def read_root():
     return {
@@ -761,5 +766,153 @@ def get_dashboard_kpis(db: Session = Depends(get_db)):
             }
         }
     except Exception as e:
-        logger.error(f"Fallo KPI: {e}")
-        raise HTTPException(status_code=500, detail=str(e))
+        raise HTTPException(status_code=500, detail=str(e))
+
+def anonymize_name(name: str) -> str:
+    if not name or name.strip() == "":
+        return "Desconocido"
+    parts = name.strip().split()
+    anonymized_parts = []
+    for p in parts:
+        if len(p) > 1:
+            anonymized_parts.append(p[0] + "***")
+        else:
+            anonymized_parts.append(p + "***")
+    return " ".join(anonymized_parts)
+
+@app.post("/api/v1/nlp/batch-analyze")
+def batch_analyze_nlp(
+    payload: Union[BatchPayload, List[ProcessSheetPayload]], 
+    db: Session = Depends(get_db)
+):
+    if isinstance(payload, list):
+        records = payload
+    else:
+        records = payload.records
+
+    results = []
+    estudiantes_existentes = db.query(DimEstudiante).all()
+
+    for record in records:
+        # Extraer NLP
+        entidades = ner_engine.extract_entities(record.texto_celda)
+        confianza_ia = sum([e["score"] for e in entidades]) / len(entidades) if entidades else 1.0
+        nombre_resuelto = record.texto_celda[:200].strip()
+
+        # Consultar log_auditoria_nlp primero
+        log_memoria = db.query(LogAuditoriaNlp).filter(
+            LogAuditoriaNlp.texto_original == nombre_resuelto
+        ).order_by(LogAuditoriaNlp.created_at.desc()).first()
+
+        estudiante = None
+        requiere_revision = False
+        
+        if log_memoria and log_memoria.correccion_humana != "PENDIENTE":
+            nombre_resuelto = log_memoria.correccion_humana
+            confianza_ia = 1.0
+            best_match, _ = find_best_match(nombre_resuelto, estudiantes_existentes)
+            if best_match:
+                estudiante = best_match
+            else:
+                estudiante = DimEstudiante(nombre_completo=nombre_resuelto, codigo_estudiante=record.codigo_estudiante)
+                db.add(estudiante)
+                db.flush()
+                estudiantes_existentes.append(estudiante)
+        else:
+            best_match, score = find_best_match(nombre_resuelto, estudiantes_existentes)
+            if best_match and score >= 0.8:
+                estudiante = best_match
+                if score < confianza_ia:
+                    confianza_ia = score
+            else:
+                if confianza_ia >= 0.60:
+                    estudiante = DimEstudiante(nombre_completo=nombre_resuelto, codigo_estudiante=record.codigo_estudiante)
+                    db.add(estudiante)
+                    db.flush()
+                    estudiantes_existentes.append(estudiante)
+
+        # Calculo de alertas
+        alertas = []
+        if record.nota_detectada <= 70.0:
+            alertas.append("RIESGO_ACADEMICO_CRITICO")
+        if record.asistencia < 70.0 or record.incumplimiento_tareas > 30.0:
+            alertas.append("RIESGO_DESERCION_ALTA")
+
+        if confianza_ia < 0.60:
+            log = LogAuditoriaNlp(
+                texto_original=nombre_resuelto,
+                prediccion_beto=nombre_resuelto,
+                confianza_ia=confianza_ia,
+                correccion_humana="PENDIENTE",
+                usuario_auditor=getattr(record, 'id_usuario', 1)
+            )
+            db.add(log)
+            db.flush()
+            requiere_revision = True
+        else:
+            # Insert into Constellation Schema
+            id_tiempo_val = getattr(record, 'id_tiempo', 1)
+            id_docente_val = getattr(record, 'id_docente', 1)
+            id_modulo_val = getattr(record, 'id_modulo', 1)
+            id_documento_val = getattr(record, 'id_documento', 1)
+            id_usuario_val = getattr(record, 'id_usuario', 1)
+
+            # Ensure dimensions exist
+            if not db.query(DimDocente).filter(DimDocente.id_docente == id_docente_val).first():
+                db.add(DimDocente(id_docente=id_docente_val, nombre_completo="Docente Generico", area_especialidad="Generico"))
+            if not db.query(DimModulo).filter(DimModulo.id_modulo == id_modulo_val).first():
+                db.add(DimModulo(id_modulo=id_modulo_val, nombre_modulo=getattr(record, 'modulo', "Modulo Generico") or "Modulo Generico", nombre_institucion=getattr(record, 'institucion', "GiraGroup") or "GiraGroup", programa=getattr(record, 'programa', "General") or "General"))
+            if not db.query(DimTiempo).filter(DimTiempo.id_tiempo == id_tiempo_val).first():
+                db.add(DimTiempo(id_tiempo=id_tiempo_val, gestion=2026, semestre=1, mes="Mayo"))
+            if not db.query(DimOrigenDocumental).filter(DimOrigenDocumental.id_documento == id_documento_val).first():
+                db.add(DimOrigenDocumental(id_documento=id_documento_val, tipo_documento="SHEET", nombre_archivo="carga_automatica"))
+            if not db.query(Users).filter(Users.id == id_usuario_val).first():
+                db.add(Users(id=id_usuario_val, username=f"sistema_{id_usuario_val}", hashed_password="$placeholder$", role="admin"))
+            db.flush()
+
+            if record.tipo_fuente == "FINANCE":
+                fact = FactSituacionFinanciera(
+                    id_estudiante=estudiante.id_estudiante,
+                    id_tiempo=id_tiempo_val,
+                    monto_deuda=getattr(record, 'monto_deuda', 0),
+                    cuotas_impagas=getattr(record, 'cuotas_impagas', 0),
+                    estado_cartera="AL_DIA",
+                    tipo_alerta="NINGUNA"
+                )
+                db.add(fact)
+            else:
+                fact = FactRendimientoAcademico(
+                    id_estudiante=estudiante.id_estudiante,
+                    id_docente=id_docente_val,
+                    id_modulo=id_modulo_val,
+                    id_tiempo=id_tiempo_val,
+                    id_documento=id_documento_val,
+                    id_usuario_carga=id_usuario_val,
+                    nota_final=record.nota_detectada,
+                    asistencia_pct=record.asistencia,
+                    incumplimiento_actividades_pct=record.incumplimiento_tareas,
+                    nivel_confianza_ia=confianza_ia,
+                    requiere_revision=False
+                )
+                db.add(fact)
+
+        results.append({
+            "anonymized_name": anonymize_name(nombre_resuelto),
+            "nombre_resuelto": nombre_resuelto,
+            "confianza_ia": round(float(confianza_ia), 4),
+            "alertas": alertas,
+            "requiere_revision": requiere_revision,
+            "status": "pending_human_review" if requiere_revision else "inserted"
+        })
+
+    try:
+        db.commit()
+    except Exception as e:
+        db.rollback()
+        raise HTTPException(status_code=500, detail=str(e))
+
+    return {
+        "status": "success",
+        "processed_count": len(records),
+        "results": results
+    }