342 lines
15 KiB
Markdown
342 lines
15 KiB
Markdown
# AVAP MAP-Elites Dataset Pipeline — Documentación
|
||
|
||
> Scripts para la síntesis de datasets de benchmarks AVAP mediante cobertura de gramática garantizada y priors estadísticos extraídos de código real de producción.
|
||
|
||
---
|
||
|
||
## Índice
|
||
|
||
- [Visión general del sistema](#visión-general-del-sistema)
|
||
- [Requisitos e instalación](#requisitos-e-instalación)
|
||
- [construct_prior.py](#construct_priorpy)
|
||
- [Uso](#uso-construct_prior)
|
||
- [Cómo funciona](#cómo-funciona-construct_prior)
|
||
- [generate_mbap_v2.py](#generate_mbap_v2py)
|
||
- [Uso](#uso-generate_mbap_v2)
|
||
- [Cómo funciona](#cómo-funciona-generate_mbap_v2)
|
||
- [Flujo de trabajo recomendado](#flujo-de-trabajo-recomendado)
|
||
- [Archivos generados](#archivos-generados)
|
||
|
||
---
|
||
|
||
## Visión general del sistema
|
||
|
||
El pipeline consta de dos scripts que trabajan en conjunto:
|
||
|
||
```
|
||
construct_prior.py → construct_map.yaml
|
||
↓ ↓
|
||
generate_mbap_v2.py ←─────────────────┘
|
||
↓
|
||
dataset .json + coverage_stats .json
|
||
```
|
||
|
||
1. **`construct_prior.py`** analiza codebases reales en GitHub para extraer con qué frecuencia co-ocurren los 38 comandos AVAP en código de producción real. El resultado es un fichero `construct_map.yaml` con pesos estadísticos.
|
||
|
||
2. **`generate_mbap_v2.py`** usa esos pesos para dirigir un generador MAP-Elites que llama a la API de Claude, garantizando cobertura uniforme de todas las combinaciones de pares y tríos del DSL AVAP.
|
||
|
||
---
|
||
|
||
## Requisitos e instalación
|
||
|
||
```bash
|
||
pip install requests pyyaml anthropic
|
||
pip install datasets huggingface_hub # solo si usas --prior-sources huggingface
|
||
|
||
export ANTHROPIC_API_KEY=sk-ant-...
|
||
export GITHUB_TOKEN=ghp_... # opcional pero recomendado
|
||
```
|
||
|
||
El parser AVAP debe estar en ejecución si se desea validación AST real (opcional; si no está disponible, se usa keyword scanning como fallback):
|
||
|
||
```bash
|
||
# El parser debe escuchar en el puerto configurado (por defecto 8080)
|
||
# Ejemplo: http://localhost:8080
|
||
```
|
||
|
||
---
|
||
|
||
## `construct_prior.py`
|
||
|
||
### Uso (construct_prior)
|
||
|
||
El script tiene dos modos de operación: **generación** del mapa y **verificación** de uno existente.
|
||
|
||
#### Generar `construct_map.yaml` (ejecutar una vez, o cuando cambie la gramática AVAP)
|
||
|
||
```bash
|
||
# Ejecución básica (sin token: límite de 10 req/min en GitHub)
|
||
python construct_prior.py --generate-map
|
||
|
||
# Con token de GitHub (recomendado — 30 req/min)
|
||
python construct_prior.py --generate-map --github-token ghp_...
|
||
|
||
# Analizar más ficheros para un prior más rico
|
||
python construct_prior.py --generate-map --max-files 200 --github-token ghp_...
|
||
|
||
# Ruta de salida personalizada
|
||
python construct_prior.py --generate-map --output /ruta/construct_map.yaml
|
||
```
|
||
|
||
#### Verificar un `construct_map.yaml` existente
|
||
|
||
```bash
|
||
python construct_prior.py --verify --map construct_map.yaml
|
||
```
|
||
|
||
#### Uso como módulo desde `generate_mbap_v2.py`
|
||
|
||
```python
|
||
from construct_prior import ConstructPrior
|
||
|
||
# Cargar desde YAML generado
|
||
prior = ConstructPrior.from_yaml("construct_map.yaml")
|
||
|
||
# Consultar el peso de una celda (par o trío de comandos AVAP)
|
||
w = prior.cell_weight(frozenset({"try", "ormAccessSelect"}))
|
||
|
||
# Fallback estático (sin necesidad de YAML)
|
||
prior = ConstructPrior.static_fallback()
|
||
```
|
||
|
||
#### Parámetros CLI
|
||
|
||
| Parámetro | Tipo | Por defecto | Descripción |
|
||
|---|---|---|---|
|
||
| `--generate-map` | flag | — | Activa el modo de extracción desde GitHub |
|
||
| `--verify` | flag | — | Carga y muestra estadísticas de un YAML existente |
|
||
| `--github-token` | str | `$GITHUB_TOKEN` | Token de acceso personal de GitHub |
|
||
| `--max-files` | int | `100` | Número máximo de ficheros a analizar |
|
||
| `--output` | str | `construct_map.yaml` | Ruta de salida del YAML |
|
||
| `--map` | str | `construct_map.yaml` | Ruta del YAML a verificar (solo con `--verify`) |
|
||
|
||
---
|
||
|
||
### Cómo funciona (construct_prior)
|
||
|
||
El objetivo del script es responder a la pregunta: **¿qué combinaciones de comandos AVAP aparecen juntas con más frecuencia en código API real de producción?** Esa información sirve para sesgar el generador de datasets hacia patrones realistas.
|
||
|
||
#### 1. Vocabulario AVAP (`AVAP_NODE_NAMES`)
|
||
|
||
Se define una lista canónica de 38 comandos AVAP organizados por categoría (variables, ORM, HTTP, criptografía, concurrencia, etc.). Esta lista es la única fuente de verdad del módulo y es importada también por `generate_mbap_v2.py`.
|
||
|
||
#### 2. Tabla de equivalencias de lenguaje (`LANGUAGE_MAPPINGS`)
|
||
|
||
Cada comando AVAP se mapea a sus equivalentes en Python (detección por AST), Go (keywords) y SQL. Esta tabla, verificada manualmente, define *qué buscar* al escanear los codebases. Por ejemplo:
|
||
|
||
- `ormAccessSelect` → llamadas como `.fetchall()`, `.query()`, `.filter()`
|
||
- `RequestPost` → `requests.post`, `httpx.post`, `session.post`
|
||
- `try` → nodo `ast.Try` en el AST de Python
|
||
|
||
#### 3. Extracción desde GitHub (`GitHubFetcher`)
|
||
|
||
Se lanzan 16 queries predefinidas contra la GitHub Code Search API, cada una orientada a un patrón típico de microservicio (ORM + manejo de errores, clientes HTTP, autenticación con crypto, concurrencia async, JSON, fechas, etc.). Los ficheros encontrados se descargan en base64 y se decodifican en memoria.
|
||
|
||
El fetcher respeta automáticamente el rate limit de la API (10 req/min sin token, 30 req/min con token) con esperas adaptativas entre peticiones.
|
||
|
||
#### 4. Detección AST de Python (`PythonASTDetector`)
|
||
|
||
Cada fichero descargado se parsea con el módulo estándar `ast` de Python. El walker del AST recorre todos los nodos y detecta qué comandos AVAP están presentes según su equivalente estructural:
|
||
|
||
- `ast.Try` → `"try"` + `"exception"`
|
||
- `ast.FunctionDef` → `"function"` + `"addParam"` (si tiene argumentos)
|
||
- `ast.For` / `ast.AsyncFor` → `"startLoop"`
|
||
- `ast.Call` con callee `.fetchall` → `"ormAccessSelect"`
|
||
- etc.
|
||
|
||
Este enfoque es **AST-level**, no keyword scanning, lo que elimina falsos positivos por nombres de variable, strings o comentarios. Si el fichero tiene errores de sintaxis, cae automáticamente a un keyword fallback.
|
||
|
||
#### 5. Acumulación de co-ocurrencias (`CooccurrenceExtractor`)
|
||
|
||
Por cada fichero analizado se obtiene un conjunto de comandos AVAP detectados. Se calculan todas las combinaciones de pares y tríos posibles de ese conjunto y se incrementan sus contadores. Por ejemplo, si un fichero contiene `{try, ormAccessSelect, return}`, se incrementan los contadores de `(try, ormAccessSelect)`, `(try, return)`, `(ormAccessSelect, return)` y el trío `(try, ormAccessSelect, return)`.
|
||
|
||
#### 6. Normalización y escritura del YAML (`generate_construct_map`)
|
||
|
||
Los contadores de co-ocurrencia se normalizan a `[0, 1]` dividiéndolos por el máximo observado. El resultado se escribe en `construct_map.yaml` con dos secciones:
|
||
|
||
- `language_mappings` — la tabla de equivalencias (trazabilidad)
|
||
- `pair_weights` / `trio_weights` — pesos empíricos extraídos
|
||
|
||
#### 7. Propagación de pesos a subsets (`_propagate_subset_weights`)
|
||
|
||
Los tríos que contienen pares con alto peso heredan el 60% del peso del par más relevante que contienen. Esto garantiza que los tríos formados por pares comunes sean visitados antes que tríos de combinaciones raras.
|
||
|
||
#### 8. Fallback estático
|
||
|
||
Si no se dispone de conexión a GitHub o de un YAML previo, `ConstructPrior.static_fallback()` retorna un conjunto de 40+ pesos hard-coded basados en conocimiento experto (por ejemplo, `(try, exception)` = 1.0, `(function, return)` = 0.98).
|
||
|
||
---
|
||
|
||
## `generate_mbap_v2.py`
|
||
|
||
### Uso (generate_mbap_v2)
|
||
|
||
#### Invocación básica
|
||
|
||
```bash
|
||
# Modo por defecto: MAP-Elites + ConstructPrior (Candidato F)
|
||
python generate_mbap_v2.py --lrm avap.md --parser http://localhost:8080
|
||
|
||
# Generar 5000 ejemplos con celdas de hasta 3 comandos
|
||
python generate_mbap_v2.py --lrm avap.md --parser http://localhost:8080 \
|
||
--problems 5000 --cell-size 3 --mode map-elites-prior
|
||
```
|
||
|
||
#### Opciones del prior
|
||
|
||
```bash
|
||
# Usar datos reales de GitHub para el prior (AST-level, requiere red)
|
||
python generate_mbap_v2.py --lrm avap.md --mode map-elites-prior \
|
||
--prior-sources github
|
||
|
||
# Guardar el prior tras la extracción (para reutilizarlo después)
|
||
python generate_mbap_v2.py --lrm avap.md --mode map-elites-prior \
|
||
--prior-sources github --prior-save prior_weights.json
|
||
|
||
# Cargar un prior pre-extraído (sin peticiones a GitHub)
|
||
python generate_mbap_v2.py --lrm avap.md --mode map-elites-prior \
|
||
--prior-load prior_weights.json
|
||
|
||
# Usar el prior generado por construct_prior.py
|
||
python generate_mbap_v2.py --lrm avap.md --mode map-elites-prior \
|
||
--prior-map construct_map.yaml
|
||
```
|
||
|
||
#### Modos de generación
|
||
|
||
```bash
|
||
# Candidato F: MAP-Elites + ConstructPrior (por defecto, recomendado)
|
||
python generate_mbap_v2.py --lrm avap.md --mode map-elites-prior
|
||
|
||
# Candidato E: MAP-Elites con pesos uniformes (baseline sin prior)
|
||
python generate_mbap_v2.py --lrm avap.md --mode map-elites
|
||
|
||
# Candidato A: CW-Reward pool (no implementado en v2, usar generate_mbap.py)
|
||
python generate_mbap_v2.py --lrm avap.md --mode reward
|
||
```
|
||
|
||
#### Parámetros CLI completos
|
||
|
||
| Parámetro | Tipo | Por defecto | Descripción |
|
||
|---|---|---|---|
|
||
| `--lrm` | str | `avap.md` | Ruta al Language Reference Manual de AVAP |
|
||
| `--output` | str | `output/mbpp_avap_v2.json` | Ruta del dataset de salida |
|
||
| `--problems` | int | `5000` | Número de ejemplos a generar |
|
||
| `--parser` | str | `http://localhost:8080` | URL del parser AVAP |
|
||
| `--cell-size` | int | `3` | Tamaño máximo de celda: 2=solo pares, 3=pares+tríos |
|
||
| `--quality-threshold` | float | `0.80` | Calidad mínima para considerar una celda "buena" |
|
||
| `--alpha` | float | `0.30` | Peso de los comandos bonus en la calidad |
|
||
| `--beta` | float | `0.20` | Peso de la calidad de los tests en la calidad |
|
||
| `--gamma` | float | `0.10` | Peso de la riqueza del código en la calidad |
|
||
| `--mode` | choice | `map-elites-prior` | Modo de generación (ver arriba) |
|
||
| `--prior-map` | str | `construct_map.yaml` | Ruta al YAML generado por `construct_prior.py` |
|
||
| `--prior-epsilon` | float | `0.05` | Peso mínimo para celdas cola (tail cells) |
|
||
| `--prior-phase3-threshold` | float | `0.70` | Calidad a partir de la cual se activa la Fase 3 (tail) |
|
||
| `--api-key` | str | `$ANTHROPIC_API_KEY` | API key de Anthropic |
|
||
|
||
---
|
||
|
||
### Cómo funciona (generate_mbap_v2)
|
||
|
||
El generador implementa un algoritmo de **Quality-Diversity (QD)** llamado MAP-Elites aplicado a la generación de ejemplos de código AVAP. El objetivo es producir un dataset que cubra de forma garantizada todas las combinaciones de pares y tríos de los 38 comandos del DSL, sin sesgos de distribución.
|
||
|
||
#### 1. Vocabulario y detección de constructs (`AVAP_NODE_TYPES`, `CellValidator`)
|
||
|
||
Se define un diccionario que mapea cada comando AVAP a sus patrones de keyword. `CellValidator` detecta qué comandos están presentes en un ejemplo generado usando dos estrategias:
|
||
|
||
- **Desde el AST del parser AVAP**: se recorre el árbol recursivamente buscando nodos por `type`.
|
||
- **Desde el código fuente** (fallback): se buscan los patrones de keyword del diccionario. `if_mode2` se comprueba antes que `if_mode1` para evitar ambigüedad.
|
||
|
||
Además calcula una **puntuación de calidad** compuesta:
|
||
|
||
```
|
||
quality = fidelity
|
||
+ alpha * bonus_constructs_ratio
|
||
+ beta * test_quality
|
||
+ gamma * code_richness
|
||
```
|
||
|
||
- `fidelity`: fracción de los constructs requeridos por la celda que están presentes (componente principal).
|
||
- `bonus_ratio`: constructs adicionales más allá de los requeridos.
|
||
- `test_quality`: proporción de tests con patrón `re.match()` y longitud > 10.
|
||
- `richness`: número de líneas normalizadas a 30 (proxy de complejidad).
|
||
|
||
#### 2. Mapa de cobertura MAP-Elites (`CoverageMap`)
|
||
|
||
Es la estructura central del algoritmo. Mantiene **una celda por cada combinación posible de 2 o 3 comandos AVAP** (con `cell_size=3`: 703 pares + N tríos de un total de 38 comandos). Cada celda almacena el mejor ejemplo encontrado hasta el momento para esa combinación.
|
||
|
||
Una celda solo se considera válida si el ejemplo que contiene usa **todos** los constructs de su clave. El mapa expone métricas en tiempo real: tasa de llenado, entropía de distribución (Shannon), y celdas de baja calidad.
|
||
|
||
#### 3. Selector de celdas — Candidato E (`CellSelector`)
|
||
|
||
Implementa la estrategia de selección sin prior en tres fases:
|
||
|
||
- **Fase 1**: Celdas vacías (round-robin aleatorio con semilla fija para reproducibilidad).
|
||
- **Fase 2**: Celdas con calidad por debajo del umbral.
|
||
- **Fase 3**: UCB (Upper Confidence Bound) sobre todas las celdas — equilibrio entre explotar celdas de alta calidad y explorar celdas poco visitadas.
|
||
|
||
#### 4. Selector con prior — Candidato F (`CellSelectorPrior`)
|
||
|
||
Extiende `CellSelector` incorporando los pesos de `ConstructPrior`:
|
||
|
||
- **Fase 1**: Las celdas vacías con peso de prior alto (> 1.5× epsilon) se priorizan mediante muestreo ponderado. Esto hace que el dataset sea útil para RAG desde los primeros ejemplos (los patrones más frecuentes en producción se cubren primero).
|
||
- **Fase 2**: Las celdas de baja calidad se seleccionan con UCB multiplicado por el peso del prior.
|
||
- **Fase 3**: Una vez que las celdas de prior alto alcanzan el umbral de calidad, se activa la cobertura de las celdas cola (tail cells, prior ≈ epsilon).
|
||
|
||
#### 5. Construcción del prompt y llamada a la API (`Generator`)
|
||
|
||
Para cada celda seleccionada se construye un prompt estructurado que incluye el LRM completo de AVAP y una especificación precisa: "genera UN problema de benchmark estilo MBPP que use **exactamente** estos constructs: `{cell}`". El generador nunca pide exploración libre — cada llamada tiene una especificación de cobertura forzada.
|
||
|
||
La respuesta se parsea esperando JSON con campos `prompt`, `code`, y `tests`.
|
||
|
||
#### 6. Validación y actualización del mapa
|
||
|
||
Cada ejemplo generado pasa por `CellValidator`:
|
||
|
||
1. Se intenta parsear con el parser AVAP (si está disponible).
|
||
2. Se detectan los constructs presentes.
|
||
3. Se calcula la puntuación de calidad.
|
||
4. Si la calidad supera el ejemplo actual de la celda (o la celda está vacía), el mapa se actualiza.
|
||
|
||
#### 7. Checkpoints y métricas
|
||
|
||
Cada 100 llamadas a la API se imprime un checkpoint con: tamaño del dataset, tasa de éxito, estado del mapa, entropía de distribución, y divergencia KL entre el dataset y el prior (KL = 0 significa alineación perfecta con patrones de producción).
|
||
|
||
#### 8. Guardado (`_save`)
|
||
|
||
Al finalizar se guardan dos ficheros:
|
||
|
||
- `<output>.json` — el dataset completo.
|
||
- `<output>_coverage_stats.json` — estadísticas de cobertura, entropía, frecuencia por nodo, y KL-divergence respecto al prior.
|
||
|
||
---
|
||
|
||
## Flujo de trabajo recomendado
|
||
|
||
```bash
|
||
# Paso 1: Generar el prior estadístico (una sola vez, o al actualizar la gramática)
|
||
python construct_prior.py --generate-map --github-token $GITHUB_TOKEN --max-files 200
|
||
|
||
# Paso 2: Verificar el prior generado
|
||
python construct_prior.py --verify --map construct_map.yaml
|
||
|
||
# Paso 3: Generar el dataset
|
||
python generate_mbap_v2.py \
|
||
--lrm avap.md \
|
||
--parser http://localhost:8080 \
|
||
--prior-map construct_map.yaml \
|
||
--problems 5000 \
|
||
--output output/dataset_v2.json \
|
||
--mode map-elites-prior
|
||
```
|
||
|
||
---
|
||
|
||
## Archivos generados
|
||
|
||
| Fichero | Generado por | Descripción |
|
||
|---|---|---|
|
||
| `construct_map.yaml` | `construct_prior.py` | Pesos de co-ocurrencia de pares/tríos AVAP extraídos de GitHub |
|
||
| `<output>.json` | `generate_mbap_v2.py` | Dataset de ejemplos AVAP estilo MBPP |
|
||
| `<output>_coverage_stats.json` | `generate_mbap_v2.py` | Estadísticas de cobertura, entropía y KL-divergence |
|