Metadata-Version: 2.4
Name: evolutia
Version: 0.1.0
Summary: Sistema automatizado para generar preguntas de examen desafiantes basadas en materiales didácticos existentes
Home-page: https://github.com/glacy/evolutIA
Author: Gerardo Lacy-Mora
Author-email: glacycr@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: openai
Requires-Dist: anthropic
Requires-Dist: google-generativeai
Requires-Dist: tqdm
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

- **Extracción automática**: Lee y procesa materiales didácticos en formato Markdown/MyST
- **Análisis de complejidad**: Identifica tipo, pasos, variables y conceptos de cada ejercicio
- **Generación inteligente**: Usa IA (OpenAI GPT-4 o Claude) para crear variaciones más complejas
- **Validación automática**: Verifica que las variaciones sean más desafiantes que los originales
- **Formato consistente**: Genera archivos en formato MyST/Markdown compatible con Curvenote
- **Multi-proveedor**: Soporte para OpenAI (GPT-4), Anthropic (Claude 3) y Google (Gemini 1.5).
- **RAG (Retrieval-Augmented Generation)**: Utiliza apuntes de clase y ejercicios existentes para dar contexto.
- **Modo Creación**: Genera ejercicios nuevos desde cero basados en temas y tags del curso.
- **Generación Paralela**: Utiliza concurrencia para acelerar drásticamente la generación de múltiples ejercicios.
- **Parseo Robusto**: Sistema avanzado para manejar y limpiar JSON con alta densidad de LaTeX.

```mermaid
flowchart LR
    A[📚 Materiales Didácticos<br>Lecturas, Tareas, Prácticas] --> B(🔍 Extracción y Análisis<br>Identifica ejercicios y conceptos)
    B --> C{⚙️ Motor de Generación}
    subgraph C [ ]
        direction LR
        D[Modo Variación<br>Incrementa complejidad]
        E[Modo Creación<br>Nuevos ejercicios desde cero]
    end
    C --> F(🧠 Inteligencia Artificial<br>LLM + RAG opcional)
    F --> G(✅ Validación<br>Verifica aumento de dificultad)
    G --> H[📝 Generación de Archivos<br>Examen y Soluciones en MyST/Markdown]
    H --> I(🎯 Evaluación Coherente y Desafiante)
    I --> J(🚀 Generación Paralela<br>Concurrencia para acelerar)
```

## Requisitos

- Python 3.8 o superior
- API key de OpenAI o Anthropic (Claude)
- Opcional: Servidor LLM local (Ollama, LM Studio) para generación offline

### Instalación

1.  Clona el repositorio:
    ```bash
    git clone https://github.com/glacy/evolutIA.git
    cd evolutia
    ```

2.  Crea y activa un entorno virtual:
    ```bash
    python -m venv venv
    source venv/bin/activate  # En Windows: venv\Scripts\activate
    ```

3.  Instala el paquete en modo editable (esto instalará también las dependencias):
    ```bash
    pip install -e .
    ```

4.  Configura las variables de entorno:
    ```bash
    cp .env.example .env
    # Edita .env con tus API keys
    ```
   Y edita `.env` con tus claves reales:
   ```
   OPENAI_API_KEY=sk-tu-api-key-aqui
   ANTHROPIC_API_KEY=sk-ant-tu-api-key-aqui
   GOOGLE_API_KEY=tu-api-key-aqui
   ```

   **Obtener API keys**:
   - OpenAI: https://platform.openai.com/api-keys
   - Anthropic: https://console.anthropic.com/
   - Google: https://console.cloud.google.com/ai/generative-ai/credentials

## Uso

### Uso básico

```bash
python evolutia.py \
  --tema analisis_vectorial \
  --num_ejercicios 4 \
  --output examenes/examen3
```

### Variación de ejercicios específicos

```bash
python evolutia.py \
  --tema analisis_vectorial \
  --label ex1-s1 ex2-s1 \
  --output variacion_especifica
```

### Listar ejercicios disponibles

```bash
python evolutia.py --tema analisis_vectorial --list
```

Si no se indica un tema, el sistema buscará en todos los archivos disponibles.

### Opciones disponibles

- `--tema`: Tema del examen (requerido)
  - Ejemplos: `analisis_vectorial`, `matrices`, `edps`, `espacios_vectoriales`, `numeros_complejos`
  
- `--num_ejercicios`: Número de ejercicios a generar (default: 1)

- `--output`: Directorio de salida (requerido)
  - Se creará automáticamente si no existe

- `--complejidad`: Nivel de complejidad objetivo
  - Opciones: `media`, `alta` (default), `muy_alta`

- `--api`: Proveedor de API de IA
  - Opciones: `openai` (default), `anthropic`, `local`, `gemini`

- `--label`: ID(s) específico(s) del ejercicio a variar (ej: `ex1-s1` o múltiples: `ex1-s1 ex2-s1`).
  - Si se usa, ignora `--num_ejercicios` y genera variaciones **solo** para los ejercicios indicados.

- `--config`: Ruta a un archivo de configuración externo (ej: `./mi_curso_config.yaml`). (default: busca `evolutia_config.yaml` en la raíz, o usa el interno).

- `--base_path`: Ruta base del proyecto (default: directorio actual)

- `--examen_num`: Número del examen (se infiere del nombre del directorio si no se especifica)

- `--no_generar_soluciones`: NO genera las soluciones (por defecto siempre se generan)

- `--subject`: Asignatura del examen (default: "IF3602 - II semestre 2025")

- `--keywords`: Palabras clave para el examen (múltiples valores)

- `--use_rag`: Usa RAG para enriquecer generación con contexto del curso (requiere indexación inicial)

- `--reindex`: Fuerza re-indexación de materiales (solo con `--use_rag`)

- `--list`: Lista todos los ejercicios encontrados en los temas seleccionados y muestra sus etiquetas, archivo origen y preview.

- `--query`: Realiza una búsqueda semántica en la base de datos RAG y muestra los fragmentos de texto más relevantes encontrados. Útil para verificar qué "sabe" el sistema sobre un tema.

- `--workers`: Número de hilos simultáneos para la generación paralela (default: 5). Útil para ajustar el rendimiento o evitar límites de rate.

### Ejemplos

**Generar examen de análisis vectorial con 4 ejercicios:**
```bash
python evolutia.py \
  --tema analisis_vectorial \
  --num_ejercicios 4 \
  --output examenes/examen3
```

**Generar examen usando Claude (las soluciones se generan automáticamente):**
```bash
python evolutia.py \
  --tema matrices \
  --num_ejercicios 3 \
  --api anthropic \
  --output examenes/examen4
```

### Uso Básico

Una vez instalado, puedes usar el comando `evolutia` (o ejecutar el wrapper `python evolutia_cli.py`):

1.  **Analizar el repositorio y entender la estructura:**
    ```bash
    evolutia --analyze
    ```
    *(Esto generará `config.yaml` si no existe)*

2.  **Generar examen con variaciones de ejercicios existentes:**
    ```bash
    evolutia --exam-number 1 --num-ejercicios 3 --tema "Derivadas" --complejidad "media"
    ```
**Generar examen SIN soluciones:**
```bash
python evolutia.py \
  --tema matrices \
  --num_ejercicios 3 \
  --no_generar_soluciones \
  --output examenes/examen5
```

**Generar examen con complejidad muy alta:**
```bash
python evolutia.py \
  --tema edps \
  --num_ejercicios 5 \
  --complejidad muy_alta \
  --output examenes/examen5
```

**Generar examen usando RAG (recomendado para mejor calidad):**
```bash
python evolutia.py \
  --tema analisis_vectorial \
  --num_ejercicios 4 \
  --use_rag \
  --output examenes/examen3
```

### Herramienta de Consulta RAG
Puedes "preguntarle" al sistema qué información tiene sobre un concepto específico sin generar nada:

```bash
python evolutia.py --query "Teorema de Stokes"
```

Esto mostrará una lista de ejercicios y lecturas relevantes con su puntuación de similitud.

### Modo Creación (Nuevo)
Genera ejercicios totalmente nuevos desde cero, basándose en un tema y tags opcionales, en lugar de variar ejercicios existentes.

**Generar 3 ejercicios nuevos de variable compleja:**
```bash
python evolutia.py \
  --mode creation \
  --tema numeros_complejos \
  --num_ejercicios 3 \
  --output examenes/parcial1
```

**Generar con tags específicos y usar Gemini:**
```bash
python evolutia.py \
  --mode creation \
  --tema analisis_vectorial \
  --tags stokes divergencia \
  --api gemini \
  --output examenes/quiz3
```

### Tipos de Ejercicio
Ahora puedes elegir entre ejercicios de desarrollo (default) o selección única (quiz).

**Generar pregunta de Selección Única (Conceptual):**
```bash
python evolutia.py \
  --mode creation \
  --tema matrices \
  --type multiple_choice \
  --api anthropic \
  --output examenes/quiz_rapido
```

## Uso de LLM local (offline)

EvolutIA soporta la generación de exámenes usando modelos locales como Llama 3, Mistral, o Qwen, ejecutándose en tu propia máquina a través de herramientas como [Ollama](https://ollama.com/) o [LM Studio](https://lmstudio.ai/).

**Requisitos:**
1. Tener corriendo un servidor local compatible con OpenAI API.
   - **Ollama**: Ejecuta `ollama serve` (por defecto en puerto 11434).
   - **LM Studio**: Inicia el servidor local desde la interfaz.

2. **Ejemplo de ejecución:**
```bash
python evolutia.py \
  --tema matrices \
  --num_ejercicios 3 \
  --api local \
  --output examenes/examen_local
```

3. **Configuración avanzada (opcional):**
Si tu servidor no usa el puerto por defecto o quieres cambiar el modelo, edita `evolutia/config/config.yaml`:
```yaml
local:
  base_url: "http://localhost:11434/v1"  # URL de tu servidor
  model: "llama3"                        # Modelo a utilizar
  api_key: "not-needed"
```

## Sistema RAG (Retrieval-Augmented Generation)

El sistema incluye un módulo RAG opcional que mejora significativamente la calidad de las variaciones generadas.

### ¿Qué es RAG?

RAG (Retrieval-Augmented Generation) es un sistema que:
- **Indexa** todos tus materiales didácticos (ejercicios, soluciones y **lecturas/teoría**)
- **Busca** ejercicios similares y conceptos teóricos relevantes cuando generas variaciones
- **Enriquece** los prompts con información del curso para generar variaciones más coherentes
- **Valida** consistencia comparando con ejercicios y teoría reales del curso

### Ventajas de usar RAG

1. **Mejor contexto**: Las variaciones son más coherentes con el estilo y nivel del curso
2. **Consistencia**: Los ejercicios generados se alinean mejor con materiales existentes
3. **Relevancia**: Selección inteligente de ejercicios base por similitud semántica
4. **Validación mejorada**: Compara con ejercicios reales del curso

### Cómo usar RAG

**Primera vez (indexación inicial):**
```bash
python evolutia.py \
  --tema analisis_vectorial \
  --num_ejercicios 4 \
  --use_rag \
  --reindex \
  --output examenes/examen3
```

La primera vez con `--use_rag` indexará automáticamente todos los materiales. Esto puede tardar unos minutos.

**Uso posterior:**
```bash
python evolutia.py \
  --tema analisis_vectorial \
  --num_ejercicios 4 \
  --use_rag \
  --output examenes/examen4
```

El índice se reutiliza automáticamente. Solo usa `--reindex` si cambias materiales y quieres actualizar el índice.

### Configuración de RAG

Edita `config/config.yaml` para personalizar RAG:
```yaml
rag:
  vector_store:
    # Base de datos vectorial persistente
    persist_directory: "./storage/vector_store"
    collection_name: "mi_curso_coleccion"
  embeddings:
    provider: openai
    model: text-embedding-3-small
  retrieval:
    top_k: 5
    similarity_threshold: 0.7
```

**Opciones de embeddings:**
- `openai`: Más rápido y preciso, pero tiene costo (~$0.02 por 1M tokens)
- `sentence-transformers`: Gratis y local, pero más lento

### Costos de RAG

- **Indexación inicial**: ~$1-5 dependiendo del volumen de materiales
- **Búsquedas**: Mínimas, solo cuando generas variaciones
- **Alternativa gratuita**: Usa `sentence-transformers` en lugar de OpenAI

### Cuándo usar RAG

**Usa RAG si:**
- Tienes muchos materiales (50+ ejercicios)
- Quieres máxima consistencia con el curso
- Tienes presupuesto para embeddings de OpenAI

**No uses RAG si:**
- Tienes pocos materiales (<20 ejercicios)
- Prefieres simplicidad y rapidez
- El costo es una preocupación

## Gestión de metadatos y descubrimiento

### Organización y visibilidad de ejercicios

Para que `evolutia` encuentre ejercicios ubicados en carpetas generales como `examenes/` o `tareas/` cuando filtras por un tema (ej: `--tema analisis_vectorial`), es fundamental que los archivos fuente incluyan los metadatos correctos.

El sistema utiliza la siguiente lógica de "descubrimiento":

1. **Escaneo directo**: Todos los archivos dentro de la carpeta del tema (ej: `analisis_vectorial/`) son incluidos automáticamente.
2. **Escaneo de exámenes y tareas**: Para archivos fuera de la carpeta del tema, el sistema revisa el *frontmatter* y los incluye **SOLO SI** encuentra coincidencias con el tema en:
    - **`tags`**: (Recomendado) Incluye el código del tema (ej: `analisis_vectorial`) en la lista.
    - **`subject`**: El nombre de la asignatura o tema.
    - **`keywords`**: Palabras clave relacionadas.

**Ejemplo de Frontmatter para que un examen sea "visible":**
```yaml
---
title: Examen Parcial 1
tags: 
  - analisis_vectorial    # <--- CRÍTICO: Permite que el extractor lo encuentre
  - stokes
subject: Cálculo Superior
---
```

> **Nota**: Si usas `--label` para seleccionar un ejercicio específico, el filtro de tema se ignora y el sistema buscará el ID en todos los archivos disponibles.

### Propagación de tags (trazabilidad)

`EvolutIA` asegura que los metadatos de los ejercicios originales se conserven en las variaciones generadas. Esto es crucial para mantener un registro de qué conceptos se están evaluando.

**¿Cómo funciona?**
1. **Lectura**: El sistema lee los tags del archivo fuente (`.md`) donde reside el ejercicio original.
2. **Transferencia**: Al generar la variación, estos tags se copian al nuevo archivo generado.
3. **Agregación**: El archivo final del examen (`examenX.md`) recopila automáticamente los tags de *todos* los ejercicios incluidos, generando un resumen temático del examen.

#### Ejemplo práctico

**1. Archivo fuente (ej: `matrices/semana11_practica.md`)**
Este archivo contiene los ejercicios originales ("semilla") y define el contexto temático:

```yaml
---
title: Ejercicios Semana 11
tags: 
  - autovalores        # Concepto clave
  - diagonalizacion    # Concepto clave
  - procedimental      # Tipo de competencia
  - intermedio         # Nivel de dificultad
subject: Matrices y Algebra Lineal
---
```

**2. Archivo generado (ej: `examenes/examen1/ex1_e1.md`)**
La variación generada hereda estos metadatos y agrega los suyos propios:

```yaml
---
generator: evolutia
source: ai_variation
tags: [autovalores, diagonalizacion, procedimental, intermedio] # <--- Tags heredados
original_subject: Matrices y Algebra Lineal
complexity: media
mode: variation          # <--- Nuevo: Modo de generación
target_difficulty: alta  # <--- Nuevo: Dificultad objetivo
based_on: ex1-e1         # <--- Nuevo: ID del ejercicio semilla
rag_references:          # <--- Nuevo: Contexto usado (con --use_rag)
  - ex5-e2
  - semana3_lectura.md
---
```


## Estructura de archivos generados

El script genera la siguiente estructura:

```
examenes/examen3/
├── examen3.md              # Archivo principal del examen
├── ex1_e3.md              # Ejercicio 1
├── ex2_e3.md              # Ejercicio 2
├── ex3_e3.md              # Ejercicio 3
├── ex4_e3.md              # Ejercicio 4
├── solucion_ex1_e3.md     # Solución ejercicio 1
├── solucion_ex2_e3.md     # Solución ejercicio 2
├── solucion_ex3_e3.md     # Solución ejercicio 3
└── solucion_ex4_e3.md     # Solución ejercicio 4
```

## ¿Cómo funciona?

1. **Extracción**: El sistema busca y lee materiales didácticos del tema especificado
   - Busca en directorios del tema (ej: `analisis_vectorial/`)
   - Lee archivos de prácticas (`*practica*.md`)
   - Lee archivos de tareas (`tareas/tarea*/tarea*.md`)

2. **Análisis**: Analiza cada ejercicio encontrado
   - Identifica tipo (demostración, cálculo, aplicación)
   - Cuenta pasos en soluciones
   - Extrae variables y conceptos matemáticos
   - Calcula complejidad matemática

3. **Generación**: Crea variaciones más complejas usando IA
   - Aumenta número de variables
   - Combina múltiples conceptos
   - Agrega pasos intermedios
   - Modifica sistemas de coordenadas

4. **Validación**: Verifica que las variaciones sean más complejas
   - Compara complejidad total
   - Verifica aumento en pasos, variables, conceptos
   - Valida operaciones matemáticas

5. **Generación de archivos**: Crea archivos en formato MyST/Markdown
   - Frontmatter YAML apropiado
   - Estructura de ejercicios con labels
   - Bloques de solución

## Configuración

Puedes personalizar el comportamiento editando `config/config.yaml`:

- **APIs**: Configurar modelos y parámetros
- **Rutas**: Especificar directorios de materiales (dentro de `materials_directories`)
- **Complejidad**: Ajustar umbrales de validación
- **Exámenes**: Configurar valores por defecto y **keywords** por tema
- **RAG**: Definir persistencia (local vs nube) y nombres de colección

### Cambiar Proveedor por Defecto
Puedes definir qué IA usar si no se especifica el argumento `--api`:

```yaml
api:
  default_provider: gemini  # openai, anthropic, gemini, local
  gemini:
    model: gemini-1.5-pro   # Cambiar modelo específico
```

### Nota Importante sobre Configuración
Para evitar errores de validación, asegúrate de que tu `evolutia_config.yaml` incluya la sección `api`. El sistema usa esto para determinar los modelos por defecto.

### Configuración Avanzada / Multi-Curso

Para usar `evolutia` en múltiples cursos o sin modificar el código fuente:

1.  **Archivo de Configuración Externo**: Crea un archivo `evolutia_config.yaml` en la raíz de tu proyecto (junto a la carpeta `evolutia/`). El sistema lo detectará automáticamente.
2.  **Argumento CLI**: Usa `--config ruta/a/mi_config.yaml` para especificar un archivo arbitrario.

**Ejemplo de estructura recomendada para un nuevo curso:**
```
NuevoCurso/
├── evolutia/            # Carpeta copiada o submódulo git
├── evolutia_config.yaml # Configuración específica de este curso
└── temas/               # Carpetas de contenido
```

> **IMPORTANTE**: No edites `evolutia/config/config.yaml` para datos de un curso específico. Ese archivo es una plantilla del motor. Crea un `evolutia_config.yaml` en la raíz de tu proyecto para tus ajustes personales.

> **Guía Detallada**: Para instrucciones paso a paso sobre cómo usar Git Submodules, consulta [GUIDE_SUBMODULES.md](GUIDE_SUBMODULES.md).

## Estrategias de aumento de complejidad

El sistema aplica las siguientes estrategias para aumentar la complejidad:

1. **Más variables independientes**: Introduce parámetros adicionales
2. **Combinación de conceptos**: Integra múltiples teoremas en un ejercicio
3. **Pasos intermedios**: Agrega cálculos adicionales
4. **Casos límite**: Introduce condiciones especiales
5. **Sistemas de coordenadas**: Cambia de cartesianas a cilíndricas/esféricas
6. **Dimensiones adicionales**: Aumenta la dimensionalidad del problema

## Solución de Problemas

### Error: "No se encontraron materiales"
- Verifica que el tema especificado existe como directorio
- Asegúrate de que hay archivos `.md` con ejercicios en ese directorio
- Usa `--base_path` para especificar la ruta correcta

### Error: "API key no configurada"
- Verifica que el archivo `.env` existe y contiene la API key
- Asegúrate de que el archivo está en el directorio `evolutia/`
- Revisa que la variable se llama correctamente (`OPENAI_API_KEY` o `ANTHROPIC_API_KEY`)

### Error: "No se generaron variaciones válidas"
- Intenta aumentar el número de ejercicios candidatos
- Verifica que los ejercicios originales tienen suficiente complejidad
- Considera usar `--complejidad media` para requisitos menos estrictos

### Variaciones no son suficientemente complejas
- Ajusta los umbrales en `config/config.yaml`
- Usa `--complejidad muy_alta`
- Revisa los prompts en `variation_generator.py` y ajústalos según necesites
- Considera usar `--use_rag` para mejor contexto

### Error: "RAG no disponible"
- Instala dependencias: `pip install chromadb sentence-transformers`
- Verifica que `OPENAI_API_KEY` está configurada si usas embeddings de OpenAI
- Si prefieres embeddings locales, cambia `provider: sentence-transformers` en `config.yaml`

## Limitaciones

- Requiere conexión a internet para usar APIs de IA
- Los costos de API dependen del número de ejercicios generados
- La calidad depende de la calidad de los materiales originales
- Las variaciones requieren revisión manual antes de usar

## Mejores prácticas

1. **Revisar siempre**: Las variaciones generadas deben revisarse manualmente
2. **Ajustar según necesidad**: Modifica los ejercicios generados según tu criterio
3. **Probar primero**: Genera un examen de prueba antes de usar en evaluación real
4. **Mantener materiales actualizados**: Asegúrate de que los materiales fuente están completos
5. **Documentar cambios**: Si modificas ejercicios, documenta los cambios realizados

## Configuración automática

El proyecto incluye una herramienta para sincronizar automáticamente el archivo de configuración con la estructura de carpetas y los metadatos de los archivos de lectura.

### config_manager.py

Este script escanea el directorio del proyecto para:
1. Identificar carpetas de temas existentes.
2. Leer los archivos de lectura (`semana*_lectura.md`) y extraer las palabras clave (`keywords`) del frontmatter.
3. Actualizar el archivo de configuración activo (`evolutia_config.yaml` o interno).

**Uso:**

```bash
# Uso básico (detecta configuración automáticamente)
python evolutia/config_manager.py

# Uso con archivo específico
python evolutia/config_manager.py --config ./evolutia_config.yaml
```

Ejecuta este script cada vez que agregues nuevos temas o modifiques las palabras clave en los materiales de lectura.

### Validación de Configuración (Schema)

Evolutia incluye un sistema de validación estricta para el archivo de configuración (`evolutia_config.yaml`).

- **JSON Schema**: La estructura válida se define en `evolutia/schemas/config.schema.json`.
- **Validación Automática**: Cada vez que ejecutas `evolutia.py` o `config_manager.py`, el sistema verifica que tu archivo de configuración cumpla con el esquema.
- **Errores Claros**: Si tu configuración tiene errores (campos faltantes, tipos incorrectos), el sistema detendrá la ejecución y te indicará exactamente dónde está el problema.

Esto facilita la adopción de la herramienta por nuevos usuarios, reduciendo errores de configuración inicial.

## Estructura del repositorio (Contexto)

El generador está diseñado para funcionar dentro de la estructura estándar del curso. A continuación se muestra el esquema de directorios esperado:

```
.
├── tema1/                    # Carpeta del primer tema (ej: analisis_vectorial)
├── tema2/                    # Carpeta del segundo tema
├── ...                       # Otros temas
├── tareas/                   # Tareas evaluadas (fuente de ejercicios)
├── proyecto/                 # Enunciados de proyectos
├── examenes/                 # Directorio de salida para exámenes generados
├── evolutia/                 # Este sistema de generación
├── myst.yml                  # Configuración del sitio Curvenote
└── programa-curso.md         # Información general del curso
```

### Estructura interna de cada tema

Cada carpeta de tema (ej: `tema1/`) debe seguir una estructura similar para que el extractor encuentre los materiales:

```
tema1/
├── semana1_lectura.md        # Material teoría (puede contener ejemplos)
├── semana1_practica.md       # Ejercicios de práctica
├── semana2_lectura.md
├── semana2_practica.md
└── otros_archivos.md         # Otros materiales complementarios
```

## Estructura del código (generador)

```
evolutia/
├── evolutia.py               # Script principal (CLI Wrapper)
├── evolutia_engine.py        # Motor central de orquestación
├── config_manager.py         # Gestor de configuración automática
├── material_extractor.py     # Extracción de materiales
├── exercise_analyzer.py      # Análisis de complejidad
├── variation_generator.py    # Generación de variaciones
├── llm_providers.py          # Proveedores de LLM (OpenAI, Anthropic, Gemini, Local)
├── complexity_validator.py   # Validación de complejidad
├── exam_generator.py         # Generación de archivos
├── rag/                      # Sistema RAG (opcional)
│   ├── rag_indexer.py        # Indexación de materiales
│   ├── rag_retriever.py      # Búsqueda semántica
│   ├── context_enricher.py   # Enriquecimiento de contexto
│   ├── enhanced_variation_generator.py  # Generador con RAG
│   ├── consistency_validator.py  # Validación de consistencia
│   └── rag_manager.py        # Gestor principal
├── storage/
│   └── vector_store/         # Base de datos vectorial (RAG)
├── config/
│   └── config.yaml          # Configuración
├── templates/
│   ├── exam_template.md      # Plantilla de examen
│   └── exercise_template.md  # Plantilla de ejercicio
├── utils/
│   ├── markdown_parser.py    # Parser de Markdown
│   ├── math_extractor.py     # Extracción de matemáticas
│   └── json_parser.py        # Parser robusto de JSON (LaTeX friendly)
├── requirements.txt          # Dependencias
└── README.md                 # Esta documentación
```

## Contribuciones

Para mejorar el sistema:

1. Ajusta los prompts en `variation_generator.py` para mejor generación
2. Agrega nuevos patrones de conceptos en `exercise_analyzer.py`
3. Mejora las métricas de complejidad en `complexity_validator.py`
4. Personaliza las plantillas en `templates/`

## Licencia

Este proyecto está bajo la Licencia Apache 2.0. Consulta el archivo [LICENSE](LICENSE) para más detalles.

## Reconocimientos

Este proyecto fue desarrollado utilizando asistencia de Inteligencia Artificial:

- **Cursor**: Entorno de desarrollo asistido por IA.
- **Antigravity** (Google DeepMind): Agente de codificación y planificación avanzado.

