Manual de Usuario Oficial — ThesisForge
Guía integral para la formulación, fundamentación bibliográfica, redacción modular y compilación de proyectos de tesis y artículos científicos con ThesisForge.
1. Introducción y Filosofía de Diseño
ThesisForge es una plataforma de software diseñada para asistir a tesistas, investigadores y directores de tesis a lo largo de todo el ciclo de vida del trabajo de grado. A diferencia de generadores de texto genéricos, ThesisForge implementa:
- Garantía Metodológica: Validación taxonómica basada en taxonomía de Bloom y matrices de consistencia científica.
- Trazabilidad Probatoria (RAG Real): Cada afirmación fáctica puede contrastarse contra literatura indexada en tiempo real (Semantic Scholar, ArXiv, CrossRef y PDFs propios).
- Memoria Contextual Jerárquica: Los capítulos se redactan conservando la memoria viva de la metodología aprobada y los resúmenes de las secciones precedentes.
- Privacidad Estricta (BYOK + AppSec): Claves API cifradas localmente con Fernet (AES-128-CBC + HMAC-SHA256) y derivación de clave PBKDF2-SHA256, con defensas perimetrales contra SSRF y Formula Injection (CWE-1236).
- Formateo Editorial APA 7ª Edición: Generación automatizada de archivos Microsoft Word (
.docx) respetando tipografía, sangría francesa, márgenes y estilos de tablas.
2. Requisitos del Sistema e Instalación
Requisitos Previos
- Python: Versión 3.10 o superior (recomendado Python 3.12).
- Gestor de Paquetes:
uv(recomendado) opip. - Motor LLM: Servidor local Ollama, clave Google Gemini, OpenAI o cuenta en OpenRouter.
Instalación Rápida
# Clonar el repositorio
git clone https://github.com/oscarbol09/thesisforge.git
cd thesisforge
# Crear entorno virtual e instalar dependencias
uv venv
uv pip install -e ".[dev]"
3. Flujo de Trabajo en Cinco Fases
┌─────────────────────────────────────────────────────────────┐
│ FASE 1: Orientación & Formulación Metodológica │
│ (Tema -> Problema -> Objetivos -> Matriz de Consistencia) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FASE 2: Contexto Bibliográfico & Evidencia RAG │
│ (Búsqueda Real -> Ingestión PDF -> Citation Guard) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FASE 3: Redacción Modular & Compilación APA 7 │
│ (Capítulos 1-5 -> Memoria Jerárquica -> DOCX Compilado) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FASE 4: Tribunal Multi-Agente & Defensa Oral Socrática │
│ (Auditoría 4 Jurados -> Veredicto -> Rondas de Réplica WS) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FASE 5: Interfaz Visual SPA & Lanzador de Escritorio │
│ (PyWebView -> Tailwind + Alpine.js -> Experiencia Monomando) │
└─────────────────────────────────────────────────────────────┘
4. Fase 1: Delimitación Metodológica con el Asesor
Creación de un Proyecto
El proyecto almacena la configuración de nivel académico (Pregrado, Maestría, Doctorado), enfoque metodológico (Cuantitativo, Cualitativo, Mixto) y estado de avance.
A través de la API REST o interfaz web:
* POST /api/projects: Define el título tentativo, área de estudio y nivel.
* POST /api/advisor/{project_id}/step: Permite completar secuencialmente cada uno de los 7 pasos metodológicos guiados:
1. problem_statement: Planteamiento del problema (mínimo 100 caracteres con diagnóstico empírico).
2. research_question: Pregunta general (inicia con pronombre interrogativo y signo de cierre).
3. hypothesis: Hipótesis explicativa (obligatoria en cuantitativo/mixto, omitible en cualitativo).
4. general_objective: Objetivo general encabezado por verbo en infinitivo evaluable.
5. specific_objectives: Lista de objetivos específicos derivados.
6. justification: Relevancia teórica, metodológica y práctica.
7. methodology: Tipo y diseño de investigación, población, muestra e instrumentos.
5. Fase 2: Búsqueda y Verificación Bibliográfica (RAG)
Búsqueda en Bases de Datos Reales
ThesisForge consulta directamente los índices abiertos de Semantic Scholar, ArXiv y CrossRef:
# Búsqueda desde la terminal
thesisforge search-papers "machine learning in healthcare" --limit 5 --format apa
Ingestión de Documentos PDF Propios
Los artículos en formato PDF se procesan extrayendo metadatos, limpiando encabezados repetitivos y dividiendo el texto en fragmentos que preservan abreviaturas académicas:
# Endpoint para subir e indexar artículos al vector store local
POST /api/literature/projects/{project_id}/documents/index-pdf
Validación de Afirmaciones (Citation Guard)
Para verificar si un enunciado teórico está respaldado por los documentos indexados:
POST /api/literature/projects/{project_id}/verify-claim
{
"claim": "Los modelos de lenguaje basados en transformers mejoran la precisión en diagnósticos preliminares."
}
Asistencia en Revisiones Sistemáticas (Flujo PRISMA 2020)
ThesisForge integra soporte metodológico para el estándar internacional PRISMA 2020 (Page et al., 2021) como herramienta de asistencia y registro auditable. El sistema permite estructurar y documentar las etapas de identificación, desduplicación, cribado y elegibilidad documental; la decisión crítica y cualitativa final sobre la inclusión o exclusión de cada artículo es siempre responsabilidad del investigador.
6. Fase 3: Redacción Modular por Capítulos
Estructura Canónica de 5 Capítulos
ThesisForge inicializa automáticamente la estructura estándar requerida por universidades de habla hispana:
- Capítulo I: Planteamiento del Problema
sec_1_1: Descripción de la realidad problemática (8 Movimientos del Problema)sec_1_2: Formulación del problema (Pregunta rectora con 5 componentes anatómicos y subpreguntas)sec_1_3: Objetivos de la investigación (Regla de Oro $OG \equiv PG$ y objetivos específicos por fases)sec_1_4: Justificación e importancia (4 dimensiones con Formulación Negativa)sec_1_5: Delimitación y limitaciones (Fórmula de limitaciones en 4 pasos)- Capítulo II: Marco Teórico y Conceptual
sec_2_1: Antecedentes internacionales y nacionales (últimos 5 años)sec_2_2: Bases teórico-científicas y fundamentación conceptualsec_2_3: Definición de términos básicossec_2_4: Hipótesis y operacionalización de variables (enfoques cuantitativo/mixto)- Capítulo III: Marco Metodológico
sec_3_1: Enfoque, tipo, nivel y diseño de investigaciónsec_3_2: Población, muestra ($G*\text{Power}$) y unidad de análisissec_3_3: Técnicas e instrumentos de recolección de datos (validez psicométrica y confiabilidad $\omega$)sec_3_4: Procedimientos de procesamiento y análisis de datossec_3_5: Consideraciones éticas y rigor científico- Capítulo IV: Presentación y Análisis de Resultados, Contrastación y Discusión
sec_4_1: Presentación y análisis de resultados (Secuencia en 3 niveles cuantitativos / 4 movimientos cualitativos con reporte APA 7 en 4 componentes)sec_4_2: Contrastación formal de hipótesis / Triangulación de datos en 3 movimientos / Joint Display mixtosec_4_3: Discusión de resultados en 4 movimientos (Convergencia, Divergencia obligatoria, Extensión e Implicaciones)- Capítulo V: Conclusiones y Recomendaciones
sec_5_1: Conclusiones vinculadas isomórficamente a los objetivos ($N = N$) y Conclusión General en 3 movimientossec_5_2: Recomendaciones operacionales en 4 componentes por destinatario explícitosec_5_3: Aportes a la comunidad científica, transferencia social y declaración de originalidad disciplinar
Comandos CLI de Redacción
# Inicializar la estructura capitular de un proyecto
thesisforge draft-init --project-id "proj_abc123"
# Listar las secciones y su estado de avance
thesisforge draft-list --project-id "proj_abc123"
Streaming en Tiempo Real vía WebSockets
Para observar la generación progresiva de un capítulo o sección:
const ws = new WebSocket("ws://localhost:8000/api/drafting/ws/proj_abc123/sec_1_1");
ws.onopen = () => {
ws.send(JSON.stringify({
action: "generate",
user_instructions: "Profundizar en antecedentes de los últimos 3 años."
}));
};
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
if (msg.event === "token") {
process.stdout.write(msg.data);
} else if (msg.event === "complete") {
console.log("\nBorrador generado con éxito:", msg.section.word_count, "palabras");
}
};
7. Compilación y Exportación APA 7ª Edición
ThesisForge compila directamente el estado del proyecto en un archivo .docx con las especificaciones editoriales oficiales de la American Psychological Association (APA 7th Edition):
- Márgenes: 2.54 cm (1.0 pulgada) en los cuatro costados.
- Tipografía: Times New Roman 12 pt (o Calibri 11 pt).
- Interlineado: Doble espacio (2.0) sin espaciado adicional entre párrafos.
- Sangría: Primera línea de cada párrafo con 1.27 cm (0.5 pulgadas).
- Portada para Estudiante / Profesional: Título en negrita centrado, autor, afiliación institucional, asesor y fecha.
- Tabla de Contenidos (TOC): Inclusión automática de índice formal con código de campo Word
TOC \o "1-3" \h \z \uy lista jerárquica de secciones. - Paginación: Número de página en esquina superior derecha de cada encabezado.
- Tablas: Estilo APA 7 con bordes horizontales únicamente y sanitización estricta contra inyección de fórmulas (CWE-1236).
- Referencias Desduplicadas: Sangría francesa de 1.27 cm, ordenación alfabética automática y desduplicación por DOI normalizado y firma autor-título-año.
Compilación desde la Terminal
thesisforge export-docx \
--project-id "proj_abc123" \
--output "./tesis_final.docx" \
--author "Lic. Valeria Mendoza" \
--institution "Universidad Nacional de Ingeniería" \
--advisor "Dra. Carmen Soto"
Compilación desde la API REST
curl -X POST "http://localhost:8000/api/export/projects/proj_abc123/docx" \
-H "Content-Type: application/json" \
-d '{
"author_name": "Valeria Mendoza",
"institution_name": "Universidad Nacional",
"advisor_name": "Dra. Carmen Soto",
"year": 2026
}' \
--output tesis_compilada.docx
8. Fase 4: Panel Multi-Agente de Jurado Formativo y Simulador Socrático de Defensa
[!NOTE] Naturaleza Formativa y Asistencial del Jurado El panel multi-agente y el simulador socrático son herramientas heurísticas de entrenamiento y diagnóstico pedagógico. No sustituyen al tribunal examinador institucional, a la asesoría metodológica universitaria ni a los comités de titulación oficiales.
Composición del Panel Evaluador Formativo
ThesisForge somete la tesis a una evaluación multidisciplinaria formativa conformada por cuatro perfiles académicos rigurosos:
- Dr. Arístides Valenzuela (Metodólogo Principal): Evalúa la alineación epistemológica entre el problema, los objetivos, la hipótesis y el diseño metodológico.
- Dra. Beatriz Salamanca (Especialista Temática): Revisa la densidad teórica, la relevancia empírica del marco conceptual y la pertinencia de los antecedentes.
- Dr. Camilo Restrepo (Auditor Estadístico): Audita el cálculo muestral, la validez interna/externa, la coherencia de los contrastes de hipótesis y los análisis estadísticos.
- Dr. Demetrio Sotomayor (Abogado del Diablo): Identifica sesgos de confirmación, variables confusoras no controladas, causalidades espurias y debilidades argumentativas.
Auditoría Científica Híbrida
El motor de evaluación combina:
* Reglas Deterministas: Verificación formal de matrices de consistencia, correspondencia entre enfoque cuantitativo e hipótesis explícitas, y umbral mínimo de citas APA 7.
* Deliberación Cualitativa: Dictámenes analíticos con ponderaciones de 0 a 100 y clasificación de observaciones (CRITICAL, MAJOR, MINOR, SUGGESTION).
* Dictámenes Formativos de Referencia: APROBADO_CON_DISTINCION, APROBADO, MODIFICACIONES_MENORES, MODIFICACIONES_MAYORES, NO_APROBADO (indicadores formativos basados en rúbricas universitarias con regla de veto ante inconsistencias críticas; tienen propósito pedagógico preparatorio y carecen de validez legal/institucional).
Simulador Socrático de Defensa Oral
Permite al tesista ensayar la sustentación de su trabajo y robustecer sus réplicas argumentativas:
* Generación de Preguntas Calibradas: Basadas en las debilidades reales detectadas durante la auditoría formativa del proyecto.
* Evaluación de Réplicas por Turnos: Calificación de respuestas (0–100) con retroalimentación detallada y rúbricas formativas.
* Sesiones en Tiempo Real vía WebSocket: Conexión bidireccional continua en /api/defense/ws/{session_id}.
Comandos de Consola (CLI)
# Ejecutar auditoría completa del jurado formativo y guardar reporte
thesisforge jury-audit --project-id "proj_abc123" --save
# Iniciar simulación interactiva de sustentación en la terminal
thesisforge defense-start --project-id "proj_abc123" --turns 4
9. Fase 5: Interfaz de Usuario SPA y Entorno de Escritorio Nativo
Lanzamiento de la Aplicación de Escritorio
ThesisForge integra una interfaz gráfica completa servida por FastAPI y renderizada en una ventana nativa de escritorio mediante PyWebView:
# Iniciar la interfaz gráfica de escritorio interactiva
thesisforge gui
# Iniciar en un puerto específico con soporte de DevTools
thesisforge gui --port 8080 --debug
Navegación y Vistas de la SPA
- Portafolio / Dashboard: Gestión visual de proyectos, métricas de avance y creación guiada.
- Asesor Metodológico: Formulario interactivo con retroalimentación socrática en vivo y validación taxonómica.
- Literatura & RAG: Búsqueda federada (Semantic Scholar, ArXiv, CrossRef), indexación de PDFs con PyMuPDF y verificación de afirmaciones (claim grounding).
- Estudio de Redacción Modular: Esquema canónico de 5 capítulos, streaming en tiempo real vía WebSockets y aprobación de secciones con síntesis en memoria jerárquica.
- Compilación Word APA 7: Configuración de metadatos institucionales y descarga directa de archivos
.docxformateados. - Tribunal y Sustentación: Deliberación formativa multi-agente y simulador interactivo de defensa oral.
- Configuración BYOK: Modal seguro para registrar claves de API locales cifradas (OpenRouter, Google Gemini, OpenAI, Groq, NVIDIA NIM, Ollama).
10. Seguridad y Privacidad
- Cero Fuga de Datos: Las claves de API se almacenan localmente en la base de datos SQLite asíncrona (
aiosqlitedirecto sin ORM, en modo WAL) cifradas con una clave maestra local AES-256 (LocalKeyVault). - Protección SSRF: Cualquier descarga de artículos remotos pasa por filtros que bloquean direcciones IP privadas, de enlace local (
169.254.169.254), bucles locales y esquemas inseguros (file://,gopher://). - Defensa CWE-1236: Los datos contenidos en tablas se escapan ante fórmulas maliciosas de Excel/Word (
=,+,-,@,\t,\r).