evolutia 0.1.1

Sistema automatizado para generar preguntas de examen desafiantes basadas en materiales didácticos existentes

EvolutIA: Generador de preguntas de examen

Sistema automatizado para generar preguntas de examen desafiantes basadas en materiales didácticos existentes (lecturas, prácticas, tareas). El sistema aumenta la complejidad matemática de los ejercicios mientras mantiene el formato y estructura familiar.

Características Principales

• Multi-Modo:
  • Variación: Incrementa la complejidad de ejercicios existentes.
  • Creación: Genera ejercicios nuevos desde cero basados en temas y tags.
• RAG (Retrieval-Augmented Generation): Usa tus propios apuntes y ejercicios previos como contexto para generar contenido más alineado al curso.
• Multi-Proveedor: Soporte nativo para OpenAI (GPT-4), Anthropic (Claude 3), Google (Gemini 1.5) y Modelos Locales (via Ollama/LM Studio).
• Análisis de Complejidad: Valida automáticamente que las nuevas preguntas sean matemáticamente más exigentes.
• Formato MyST: Salida compatible con Curvenote y Jupyter Book.

---

Instalación

Requisitos Previos

• Python 3.8 o superior
• API Key de tu proveedor preferido (OpenAI, Anthropic, Google) o un servidor local (Ollama).

Opción 1: Instalación desde PyPI (Recomendada)

Para uso general, instala directamente el paquete:

# Crear entorno virtual (Recomendado)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Instalar
pip install evolutia

Opción 2: Instalación desde Fuente (Desarrollo)

Si deseas modificar el código o contribuir:

git clone https://github.com/glacy/evolutIA.git
cd evolutia
pip install -e .

Configuración Inicial

Crea un archivo .env en la raíz de tu proyecto con tus credenciales:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

---

Guía de Uso Rápido

El comando principal es evolutia. Aquí tienes los casos de uso más comunes:

1. Generar Variaciones (Modo Clásico)

Toma ejercicios existentes de un tema y crea versiones más complejas.

# Generar 3 variaciones del tema 'analisis_vectorial'
evolutia --tema analisis_vectorial --num_ejercicios 3 --output examenes/parcial1

O variar ejercicios específicos por su etiqueta (Label):

evolutia --tema analisis_vectorial --label ex1-s1 ex2-s1 --output examenes/recuperacion

2. Crear Nuevos Ejercicios (Modo Creación)

Genera ejercicios desde cero sin necesitar un "ejercicio semilla".

# Crear 3 ejercicios nuevos sobre 'numeros_complejos'
evolutia --mode creation --tema numeros_complejos --num_ejercicios 3 --output examenes/quiz1

3. Usar RAG (Contexto del Curso)

Enriquece la generación indexando tus lecturas y prácticas.

# La primera vez, usa --reindex para leer tus materiales
evolutia --tema matrices --num_ejercicios 3 --use_rag --reindex --output examenes/final

# Consultas posteriores (usa el índice ya creado)
evolutia --tema matrices --num_ejercicios 3 --use_rag --output examenes/final

4. Consultar tu Base de Conocimiento

Pregúntale al sistema qué sabe sobre un concepto (útil para verificar RAG):

evolutia --query "Teorema de Stokes"

---

Configuración Avanzada

EvolutIA es altamente configurable a través del archivo evolutia_config.yaml o argumentos CLI.

Archivo de Configuración

Puedes colocar un evolutia_config.yaml en la raíz de tu carpeta de curso. Si no existe, puedes generarlo o ver el estado actual con:

# Analiza tu estructura de carpetas y genera/actualiza la config
evolutia --analyze
# O explícitamente usando el script auxiliar
python evolutia/config_manager.py

Argumentos CLI Disponibles

Argumento	Descripción	Default
--tema	Identificador del tema (carpeta)	Requerido
--output	Carpeta de salida	Requerido
--num_ejercicios	Cantidad a generar	1
--complejidad	Nivel objetivo (media, alta, muy_alta)	alta
--api	Proveedor (openai, anthropic, gemini, local)	openai
--type	Tipo de pregunta (problem, multiple_choice)	problem
--no_generar_soluciones	Omite la creación de archivos de solución	False

Uso con Modelos Locales (Offline)

Para usar modelos como Llama 3 o Mistral sin costo de API:

1. Ejecuta tu servidor (ej. ollama serve).
2. Configura evolutia_config.yaml (opcional, si usas defaults de Ollama no es necesario):

   local:
     base_url: "http://localhost:11434/v1"
     model: "llama3"
   

3. Ejecuta con el flag local:

   evolutia --tema basicos --api local --output prueba_local
   

---

Gestión de Materiales (Cómo "ve" los ejercicios EvolutIA)

Para que el sistema encuentre tus ejercicios y lecturas, utiliza una estrategia de descubrimiento basada en carpetas y metadatos.

1. Escaneo de Carpetas: Busca archivos .md dentro de la carpeta del tema (ej: ./analisis_vectorial/).
2. Tags y Metadatos: Para archivos fuera de esa carpeta (ej. en tareas/), el sistema lee el frontmatter YAML. Incluye el tag del tema para hacerlo visible:

---
title: Tarea 1
tags: 
  - analisis_vectorial  # <--- Este tag permite que evolutia encuentre el archivo
  - stokes
---

Trazabilidad

Los ejercicios generados heredan los tags de sus "padres". El archivo final del examen (examenX.md) resume todos los temas cubiertos.

---

Estructura del Proyecto

Se recomienda la siguiente estructura para tus cursos:

MiCurso/
├── evolutia_config.yaml      # Configuración específica del curso
├── analisis_vectorial/       # Materiales del tema 1
│   ├── lectura.md
│   └── practica.md
├── matrices/                 # Materiales del tema 2
├── examenes/                 # Salida generada por EvolutIA
└── .env                      # API Keys (no subir a git)

Nota para usuarios antiguos: Anteriormente se recomendaba usar Git Submodules. Ese método ha sido archivado. Si lo necesitas, consulta docs/legacy/GUIDE_SUBMODULES.md.

Contribuciones y Desarrollo

El código fuente está organizado modularmente en evolutia/:

• evolutia_engine.py: Orquestador principal.
• variation_generator.py: Lógica de prompts y llamadas a LLMs.
• rag/: Subsistema de indexación y recuperación.

Para reportar bugs o mejoras, por favor visita el repositorio en GitHub.

Licencia

Apache 2.0