# Reconocimiento visual — scripts one-off

Scripts de **línea de comandos** (tienen guard: por web devuelven 403) que preparan
el índice del *Frente B* — la identificación abierta de llaves. El control de pedido
con cámara **no los necesita**: anda sin ninguno de estos.

Antes de correr cualquiera hay que tener aplicada la migración
`distribuidora/sql/reconocimiento_visual.sql`.

## Orden

```bash
# 1. Limpiar las imágenes de catálogo (saca marca de agua y rótulo del modelo).
#    Sin esto el índice codifica el rótulo, no el producto: no es opcional.
php scripts/reconocimiento/limpiar_imagenes_catalogo.php --categoria=57
#    → uploads/catalogo_siluetas/    (los originales no se tocan)

# 2. Indexar los embeddings multimodales. Necesita VOYAGE_API_KEY.
php scripts/reconocimiento/indexar_embeddings.php --categoria=57 --fuente=silueta
#    → c2070042_distri.productos_embeddings

# 3. Atributos visuales estructurados (marca grabada, forma de cabeza, paleta).
#    Esto SE PAGA por imagen: mirá el costo con --limite=10 antes de largarlo.
php scripts/reconocimiento/atributos_visuales.php --categoria=57
#    → c2070042_distri.productos_atributos_visuales
```

Todos aceptan `--dry-run` (no escribe nada), `--limite=N` y `--forzar` (rehace lo
que ya estaba). La categoría 57 es *A Llaves*: 732 productos, 728 con imagen.

## Por qué la categoría 57 primero

Las llaves son el caso difícil y el que motivó todo esto: 732 modelos que se
distinguen por milímetros del perfil de la paleta. El resto del catálogo
(cerraduras, candados, cierrapuertas) trae marca y modelo impresos y se resuelve
con la etapa barata de lectura de texto, sin necesidad de índice.

## Costo

- **Voyage** factura por píxeles y el free tier son 150.000 millones. El catálogo
  entero son ~1.200 millones: la indexación completa entra gratis, y las consultas
  también.
- **Atributos visuales** usa `claude-opus-5`, ~0,01 USD por imagen. Las 732 llaves
  son del orden de 7-8 USD, una sola vez.

## Dónde va la salida

`uploads/` está en `.gitignore` **y** en `.deployignore`: las siluetas generadas
acá no viajan en el deploy. Hay que correr el paso 1 en cada entorno donde se
quiera usar el índice, o copiar la carpeta a mano.