TutorIA

Tutor virtual inteligente en CLI orientado a apoyo escolar, con agentes especializados para redaccion, correccion, explicacion y resumen.
El sistema integra la API de OpenAI con validaciones locales, personalidad configurable y manejo robusto de errores.

Vision

TutorIA busca sentirse como una conversacion real con un tutor: amable, claro, personalizado y util para avanzar rapido en tareas academicas.

Funcionalidades actuales

• Generacion de texto sobre un tema.
• Correccion de ortografia, gramatica y estilo.
• Explicacion de temas con enfoque pedagogico.
• Resumen y sintesis de textos.
• Personalizacion de sesion (nombre, objetivo, nivel) sin persistencia.
• Manejo de errores API con mensajes claros y reintentos cortos.

Arquitectura del proyecto

.
|-- agents/                 # Agentes por tarea
|-- config/                 # Configuracion global y constantes
|-- core/                   # Cliente OpenAI, alma del tutor y orquestador central
|-- functions/              # Menu e integracion CLI
|-- utils/                  # Validacion, limpieza y utilidades reutilizables
|-- main.py                 # Punto de entrada

Componentes clave

• core/soul.md: guia de personalidad y estilo de TutorIA.
• core/tutor.py: TutorCore y SessionProfile para orquestar contexto y flujo.
• core/openai_client.py: capa de llamada API con timeout, retry y errores controlados.
• functions/agent_selector.py: menu principal y enrutamiento de agentes.
• utils/validators.py: validaciones balanceadas para menu y entradas de usuario.
• utils/text_processing.py: saneamiento y normalizacion de texto.
• utils/helpers.py: helpers de contexto de sesion y formato de mensajes.

Requisitos

• Python 3.10 o superior.
• Cuenta OpenAI con API key activa.

Instalacion

pip install -r requirements.txt

Configuracion

1. Copia .env.example a .env.
2. Configura tus valores:

OPENAI_API_KEY=tu_api_key_aqui
OPENAI_MODEL=gpt-4.1-mini

Ejecucion

python main.py

Flujo de uso

1. El sistema solicita datos opcionales de sesion para personalizar respuestas.
2. Se muestra menu de agentes.
3. Se valida y limpia la entrada antes de llamar a la API.
4. TutorIA responde con el estilo definido en core/soul.md.

Errores comunes y solucion

• [Error] OPENAI_API_KEY no configurada: revisa .env.
• [Error] API key invalida o faltante: valida credenciales en OpenAI.
• [Error] El modelo '...' no existe: corrige OPENAI_MODEL.
• [Error] Cuota o saldo insuficiente (429): revisa billing/usage de la cuenta.
• [Error] No se pudo conectar con OpenAI: verifica red y estado del servicio.

Calidad y pruebas

• Se recomienda ejecutar:

python -m compileall .

• Para pruebas automatizadas futuras:

pytest

Contribucion basica

1. Crea una rama por cambio.
2. Realiza cambios pequenos y atomicos.
3. Ejecuta pruebas/verificaciones locales.
4. Abre pull request con descripcion clara.

Roadmap corto

• Agregar tests unitarios para TutorCore y validadores.
• Mejorar contexto pedagógico por nivel academico.
• Incorporar modo historico opcional con persistencia local.