Scripts, CSV de EMMa y guia de peso

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 modelos_entrenados/models--facebook--sam3/snapshots/image.png filter=lfs diff=lfs merge=lfs -text
+datos/externos/emma_mat.csv filter=lfs diff=lfs merge=lfs -text

datos/externos/emma_mat.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5a5d59d31f118cc50905007780f77a93637eaa16bc12de0ab9d51f1e9c805ce0
+size 37568651

datos/peso/caracteristicas.csv

@@ -0,0 +1,13 @@
+foto,sesion,tipo_objeto,material,n_piezas,area_cm2_total,largo_cm_medio,ancho_cm_medio,largo_cm_max,peso_real_g,espesor_cm
+img_001.jpg,s1,barra_acero_12mm,metal,1,120,100,1.2,101,888,1.2
+img_002.jpg,s1,barra_acero_12mm,metal,2,240,100,1.2,101,1780,1.2
+img_003.jpg,s1,barra_acero_12mm,metal,3,360,100,1.2,101,2650,1.2
+img_004.jpg,s1,barra_acero_12mm,metal,5,600,100,1.2,101,4450,1.2
+img_005.jpg,s2,barra_acero_12mm,metal,1,120,100,1.2,101,895,1.2
+img_006.jpg,s2,barra_acero_12mm,metal,2,240,100,1.2,101,1770,1.2
+img_007.jpg,s2,barra_acero_12mm,metal,3,360,100,1.2,101,2680,1.2
+img_008.jpg,s2,barra_acero_12mm,metal,5,600,100,1.2,101,4430,1.2
+img_009.jpg,s3,barra_acero_12mm,metal,1,120,100,1.2,101,885,1.2
+img_010.jpg,s3,barra_acero_12mm,metal,2,240,100,1.2,101,1790,1.2
+img_011.jpg,s3,barra_acero_12mm,metal,3,360,100,1.2,101,2660,1.2
+img_012.jpg,s3,barra_acero_12mm,metal,5,600,100,1.2,101,4460,1.2

entrenamiento/README.md

@@ -0,0 +1,72 @@
+# Entrenamiento
+
+Crea `modelos_entrenados/material_estado/` (material + estado) y calibra el conteo de SAM 3.
+
+## Credenciales (una vez)
+
+| Para | Qué hacer |
+|---|---|
+| Backbone DINOv3 y SAM 3 | Aceptar la licencia en [dinov3-convnext-tiny](https://huggingface.co/facebook/dinov3-convnext-tiny-pretrain-lvd1689m) y [sam3](https://huggingface.co/facebook/sam3); después `uv run hf auth login` |
+| Datasets de Kaggle | Kaggle → Settings → API → *Create New Token*; guardar `kaggle.json` en `C:\Users\<usuario>\.kaggle\` |
+| Datasets de Roboflow | Roboflow → Settings → API Keys; `setx ROBOFLOW_API_KEY "clave"` y abrir una terminal nueva |
+
+Sin Kaggle o Roboflow el pipeline funciona igual con menos datos: esas fuentes se omiten
+con aviso. Sin Roboflow no hay madera ni defectos, así que la nota de estado no se valida.
+
+## Pasos
+
+```bash
+uv run python -m entrenamiento.descargar          # 1. datasets → datos/crudos/      (minutos)
+uv run python -m entrenamiento.preparar           # 2. une, limpia y reparte         (minutos)
+uv run python -m entrenamiento.caracteristicas    # 3. pasa cada foto por DINOv3     (horas en CPU, reanudable)
+uv run python -m entrenamiento.entrenar           # 4. entrena las 2 cabezas y exporta (minutos)
+uv run python -m entrenamiento.evaluar_conteo     # 5. mide y calibra el conteo de SAM 3 (~1 h)
+```
+
+El paso 4 escribe `modelos_entrenados/material_estado/informe.md` con las métricas sobre el
+conjunto de prueba (fotos que el modelo nunca vio). El paso 5 escribe
+`modelos_entrenados/conteo/informe.md` y el umbral elegido.
+
+### Mejor precisión: ajuste fino completo en Colab (GPU gratis)
+
+Los pasos 3-4 dejan el backbone congelado para que se pueda entrenar sin GPU. Ajustar
+también el backbone suele mejorar varios puntos, sobre todo en defectos finos:
+
+```bash
+uv run python -m entrenamiento.empaquetar_colab   # → datos/revalora_colab.zip
+```
+
+Abre [colab_entrenamiento.ipynb](colab_entrenamiento.ipynb) en Google Colab, sube el zip y
+ejecuta las celdas. Descarga `material_estado.zip` y sustituye `modelos_entrenados/material_estado/`.
+
+## Datos
+
+Las fuentes están en [fuentes.py](fuentes.py). **Solo se usan datasets con licencia que permite
+uso comercial** (MIT, CC0, CC BY 4.0, ODbL); la licencia se comprueba al descargar y las fuentes
+no comerciales se descartan. El resultado de cada fuente queda en `datos/procesados/fuentes.json`
+y en la tabla final del informe.
+
+| Tipo | Ejemplos | Qué enseña |
+|---|---|---|
+| Material | TrashNet, RealWaste, Garbage Classification | qué material es |
+| Defectos | Roboflow: madera (Kodytek), óxido, telas, cajas dañadas, vidrio roto, abolladuras | qué defectos tiene |
+
+Las etiquetas de cada dataset se traducen a nuestros defectos en [mapeo.py](mapeo.py)
+("Dead_Knot" → nudo, "rust" → óxido, "non-damaged" → sin defectos...). Cada imagen solo enseña
+los defectos que su dataset etiqueta; el resto no cuenta.
+
+Para **añadir fotos propias** (lo que más mejora el modelo con fotos reales de la plataforma):
+crea una carpeta por material con las fotos dentro, añádela a `fuentes.py` como fuente de
+material con `origen="url"` o cópiala a `datos/crudos/<nombre>/` con un archivo `.completo`, y
+repite los pasos 2-4.
+
+## Decisiones
+
+- **ConvNeXt-Tiny DINOv3** (Meta, 2025): misma red y velocidad que el ConvNeXt-Tiny original,
+  con mejores pesos de partida. Licencia DINOv3 (uso comercial permitido, sin usos militares).
+- **384 px**: deja ver defectos pequeños; ~0.4 s por imagen en CPU.
+- **Características globales + máximo local**: el máximo conserva un defecto pequeño que el
+  promedio diluiría.
+- **Reparto por grupo**: las variantes aumentadas de una misma foto (Roboflow) nunca quedan a la
+  vez en entrenamiento y en prueba.
+- **Defectos sin datos suficientes** (< 30 ejemplos con y sin él) no se usan en la nota.

entrenamiento/__init__.py

@@ -0,0 +1,8 @@
+"""Entrenamiento del modelo de material y estado. Ver entrenamiento/README.md."""
+
+import sys
+
+# La consola de Windows usa cp1252 y falla con tildes o flechas en los mensajes.
+for _flujo in (sys.stdout, sys.stderr):
+    if hasattr(_flujo, "reconfigure"):
+        _flujo.reconfigure(encoding="utf-8", errors="replace")

entrenamiento/afinar_completo.py

@@ -0,0 +1,260 @@
+"""Ajuste fino completo (backbone + cabezas). Pensado para una GPU (Google Colab).
+
+    python -m entrenamiento.afinar_completo            # en Colab, ver colab_entrenamiento.ipynb
+
+A diferencia de entrenar.py (backbone congelado, apto para CPU), aquí también se ajusta el
+ConvNeXt, con una tasa de aprendizaje mucho menor que la de las cabezas para no "olvidar"
+lo que aprendió DINOv3. Suele mejorar varios puntos, sobre todo en defectos finos.
+
+- Parte de las cabezas de entrenar.py si existen (arranque en caliente).
+- Época 1: solo cabezas. Después: toda la red.
+- Mismas pérdidas, métricas, calibración, informe y formato de salida que entrenar.py, así
+  que el servicio carga el resultado igual.
+"""
+
+import json
+import math
+import time
+from datetime import date
+
+import torch
+import torch.nn.functional as F
+from PIL import Image, ImageOps
+from torch.utils.data import DataLoader, Dataset
+
+from app.ml.estado.defectos import ORDEN_DEFECTOS
+from app.ml.materiales import ORDEN_MATERIALES
+from app.ml.vision.red_material_estado import (
+    CabezasMaterialEstado,
+    Metadatos,
+    RedMaterialEstado,
+    a_tensor,
+    cargar,
+    dim_caracteristicas,
+    guardar,
+)
+from entrenamiento.caracteristicas import AUMENTO
+from entrenamiento.entrenar import (
+    DIM_OCULTA,
+    DROPOUT,
+    PESO_DEFECTOS,
+    SUAVIZADO,
+    Datos,
+    ajustar_temperatura,
+    defectos_entrenables,
+    escribir_informe,
+    estado_por_material,
+    metricas_defectos,
+    metricas_material,
+    peso_positivos,
+    pesos_material,
+    puntuacion,
+)
+from entrenamiento.fuentes import FUENTES
+from entrenamiento.rutas import (
+    BACKBONE,
+    IMAGENES,
+    INFORME_FUENTES,
+    MANIFIESTO,
+    SALIDA_MODELO,
+    TAMANO_IMAGEN,
+)
+
+EPOCAS = 12
+TAMANO_LOTE = 32
+LR_BACKBONE = 2e-5
+LR_CABEZAS = 5e-4
+MATERIAL_DE_FUENTE = {f.nombre: f.material for f in FUENTES}
+
+
+def etiquetas(registros: list[dict]) -> Datos:
+    n, k = len(registros), len(ORDEN_DEFECTOS)
+    material = torch.full((n,), -1, dtype=torch.long)
+    defectos, mascara = torch.zeros(n, k), torch.zeros(n, k, dtype=torch.bool)
+    for i, r in enumerate(registros):
+        if r["material"] is not None:
+            material[i] = ORDEN_MATERIALES.index(r["material"])
+        for codigo, valor in r["defectos"].items():
+            j = ORDEN_DEFECTOS.index(codigo)
+            defectos[i, j], mascara[i, j] = float(valor), True
+    material_estado = [r["material"] or MATERIAL_DE_FUENTE.get(r["fuente"]) for r in registros]
+    return Datos(
+        [r["id"] for r in registros], torch.empty(0), material, defectos, mascara, material_estado
+    )
+
+
+class Fotos(Dataset):
+    def __init__(self, registros: list[dict], aumentar: bool) -> None:
+        self.registros, self.aumentar = registros, aumentar
+        self.etiquetas = etiquetas(registros)
+
+    def __len__(self) -> int:
+        return len(self.registros)
+
+    def __getitem__(self, i: int):
+        with Image.open(IMAGENES / f"{self.registros[i]['id']}.jpg") as imagen:
+            imagen = imagen.convert("RGB")
+        vistas = [AUMENTO(imagen)] if self.aumentar else [imagen, ImageOps.mirror(imagen)]
+        return (
+            a_tensor(vistas, TAMANO_IMAGEN),
+            self.etiquetas.material[i],
+            self.etiquetas.defectos[i],
+            self.etiquetas.mascara[i],
+        )
+
+
+def crear_red() -> RedMaterialEstado:
+    from transformers import DINOv3ConvNextModel
+
+    backbone = DINOv3ConvNextModel.from_pretrained(BACKBONE)
+    dim = dim_caracteristicas(backbone.config)
+    cabezas = CabezasMaterialEstado(
+        dim, len(ORDEN_MATERIALES), len(ORDEN_DEFECTOS), DIM_OCULTA, DROPOUT
+    )
+    if (SALIDA_MODELO / "modelo.safetensors").is_file():
+        previa, _ = cargar(SALIDA_MODELO)
+        cabezas.load_state_dict(previa.cabezas.state_dict())
+        print("Arranque en caliente con las cabezas de entrenar.py")
+    return RedMaterialEstado(backbone, cabezas)
+
+
+@torch.no_grad()
+def predecir(red, cargador, dispositivo) -> tuple[torch.Tensor, torch.Tensor]:
+    red.eval()
+    logits_m, prob_d = [], []
+    for x, *_ in cargador:
+        b, v = x.shape[:2]
+        with torch.autocast(dispositivo.type, enabled=dispositivo.type == "cuda"):
+            lm, ld = red(x.flatten(0, 1).to(dispositivo))
+        logits_m.append(lm.float().reshape(b, v, -1).mean(1).cpu())
+        prob_d.append(ld.float().sigmoid().reshape(b, v, -1).mean(1).cpu())
+    return torch.cat(logits_m), torch.cat(prob_d)
+
+
+def main() -> None:
+    dispositivo = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"Dispositivo: {dispositivo}")
+    registros = [json.loads(linea) for linea in MANIFIESTO.read_text(encoding="utf-8").splitlines()]
+    por_split = {
+        s: [r for r in registros if r["split"] == s]
+        for s in ("entrenamiento", "validacion", "prueba")
+    }
+    conjuntos = {s: Fotos(rs, aumentar=s == "entrenamiento") for s, rs in por_split.items()}
+    cargadores = {
+        s: DataLoader(
+            c,
+            batch_size=TAMANO_LOTE if s == "entrenamiento" else TAMANO_LOTE // 2,
+            shuffle=s == "entrenamiento",
+            num_workers=4,
+            pin_memory=dispositivo.type == "cuda",
+            drop_last=s == "entrenamiento",
+        )
+        for s, c in conjuntos.items()
+    }
+    entrenamiento = conjuntos["entrenamiento"].etiquetas
+    w_material = pesos_material(entrenamiento.material).to(dispositivo)
+    w_positivos = peso_positivos(entrenamiento).to(dispositivo)
+
+    red = crear_red().to(dispositivo)
+    optimizador = torch.optim.AdamW(
+        [
+            {"params": red.backbone.parameters(), "lr": LR_BACKBONE},
+            {"params": red.cabezas.parameters(), "lr": LR_CABEZAS},
+        ],
+        weight_decay=0.05,
+    )
+    pasos = EPOCAS * len(cargadores["entrenamiento"])
+    planificador = torch.optim.lr_scheduler.LambdaLR(
+        optimizador, lambda p: 0.5 * (1 + math.cos(math.pi * min(p, pasos) / pasos))
+    )
+    escalador = torch.amp.GradScaler(enabled=dispositivo.type == "cuda")
+
+    mejor, mejor_estado = -1.0, None
+    for epoca in range(1, EPOCAS + 1):
+        red.train()
+        red.backbone.requires_grad_(epoca > 1)  # época 1: solo cabezas
+        inicio, total = time.time(), 0.0
+        for x, y_m, y_d, mascara in cargadores["entrenamiento"]:
+            x = x[:, 0].to(dispositivo, non_blocking=True)
+            y_m, y_d = y_m.to(dispositivo), y_d.to(dispositivo)
+            mascara = mascara.to(dispositivo).float()
+            with torch.autocast(dispositivo.type, enabled=dispositivo.type == "cuda"):
+                logits_m, logits_d = red(x)
+            logits_m, logits_d = logits_m.float(), logits_d.float()
+            validos = y_m >= 0
+            perdida_m = (
+                F.cross_entropy(
+                    logits_m[validos],
+                    y_m[validos],
+                    weight=w_material,
+                    label_smoothing=SUAVIZADO,
+                )
+                if validos.any()
+                else logits_m.sum() * 0
+            )
+            perdida_d = (
+                F.binary_cross_entropy_with_logits(
+                    logits_d, y_d, pos_weight=w_positivos, reduction="none"
+                )
+                * mascara
+            ).sum() / mascara.sum().clamp(min=1)
+            perdida = perdida_m + PESO_DEFECTOS * perdida_d
+            optimizador.zero_grad(set_to_none=True)
+            escalador.scale(perdida).backward()
+            escalador.step(optimizador)
+            escalador.update()
+            planificador.step()
+            total += perdida.item()
+
+        logits_m, prob_d = predecir(red, cargadores["validacion"], dispositivo)
+        valor = puntuacion(logits_m, prob_d, conjuntos["validacion"].etiquetas)
+        print(
+            f"época {epoca:2d}  pérdida {total / len(cargadores['entrenamiento']):.4f}  "
+            f"validación {valor:.4f}  ({time.time() - inicio:.0f} s)",
+            flush=True,
+        )
+        if valor > mejor:
+            mejor = valor
+            mejor_estado = {k: v.detach().cpu().clone() for k, v in red.state_dict().items()}
+
+    red.load_state_dict(mejor_estado)
+    red = red.cpu().eval()
+    dispositivo = torch.device("cpu")
+    logits_val, _ = predecir(red, cargadores["validacion"], dispositivo)
+    temperatura = ajustar_temperatura(logits_val, conjuntos["validacion"].etiquetas.material)
+
+    prueba = conjuntos["prueba"].etiquetas
+    logits_m, prob_d = predecir(red, cargadores["prueba"], dispositivo)
+    estado = estado_por_material(prob_d, prueba)
+    conteo = {s: len(c) for s, c in conjuntos.items()}
+    metadatos = Metadatos(
+        materiales=list(ORDEN_MATERIALES),
+        defectos=list(ORDEN_DEFECTOS),
+        tamano_imagen=TAMANO_IMAGEN,
+        dim_caracteristicas=dim_caracteristicas(red.backbone.config),
+        dim_oculta=DIM_OCULTA,
+        backbone_origen=f"{BACKBONE} (ajuste fino completo)",
+        temperatura_material=temperatura,
+        defectos_entrenados=defectos_entrenables(entrenamiento),
+        estado_validado_en=[m for m, e in estado.items() if e["validado"]],
+        version="2",
+        evaluacion={
+            "fecha": date.today().isoformat(),
+            "imagenes": conteo,
+            "material": metricas_material(logits_m, prueba.material, temperatura),
+            "defectos": metricas_defectos(prob_d, prueba),
+            "estado_por_material": estado,
+            "epocas": EPOCAS,
+        },
+    )
+    guardar(red, metadatos, SALIDA_MODELO)
+    fuentes = (
+        json.loads(INFORME_FUENTES.read_text(encoding="utf-8")) if INFORME_FUENTES.is_file() else {}
+    )
+    informe = escribir_informe(metadatos, conteo, fuentes)
+    (SALIDA_MODELO / "informe.md").write_text(informe, encoding="utf-8")
+    print(informe)
+
+
+if __name__ == "__main__":
+    main()

entrenamiento/buscar_roboflow.py

@@ -0,0 +1,85 @@
+"""Busca datasets en Roboflow Universe para ampliar fuentes.py.
+
+    uv run python -m entrenamiento.buscar_roboflow "rust" "corrosion"
+    uv run python -m entrenamiento.buscar_roboflow --todo      # todas las búsquedas predefinidas
+
+Muestra, de mayor a menor número de imágenes, los proyectos con licencia de uso comercial,
+con sus clases, para elegir cuáles añadir a fuentes.py. No descarga nada.
+"""
+
+import sys
+import time
+
+import requests
+
+from entrenamiento.fuentes import licencia_comercial
+from entrenamiento.rutas import leer_env_local
+
+URL = "https://api.roboflow.com/universe/search"
+MIN_IMAGENES = 150
+
+BUSQUEDAS = {
+    "óxido (metal)": ["rust", "corrosion", "rusty metal", "steel corrosion"],
+    "abolladuras/rayones (metal)": ["dent", "scratch metal", "metal surface defect"],
+    "madera (material)": ["wood plank", "timber", "scrap wood", "plywood", "wood pallet"],
+    "madera (defectos)": ["wood defect", "wood crack", "lumber defect"],
+    "tela (defectos)": ["fabric defect", "textile defect", "stain clothes", "torn clothes"],
+    "cartón": ["damaged box", "damaged package", "cardboard box", "wet cardboard"],
+    "vidrio": ["broken glass", "cracked glass", "glass bottle"],
+    "plástico": ["plastic bottle", "crushed plastic bottle", "plastic waste"],
+    "papel": ["paper waste", "crumpled paper", "newspaper"],
+    "otro": ["tire", "rubber waste", "e-waste", "ceramic tile defect"],
+}
+
+
+def buscar(consulta: str, clave: str, paginas: int = 2) -> list[dict]:
+    resultados = []
+    for pagina in range(1, paginas + 1):
+        for espera in (0, 5, 15, 40):  # Roboflow limita las peticiones por minuto (429)
+            time.sleep(espera or 1)
+            respuesta = requests.get(
+                URL, params={"api_key": clave, "q": consulta, "page": pagina}, timeout=30
+            )
+            if respuesta.status_code != 429:
+                break
+        if respuesta.status_code != 200:  # sin raise_for_status: la URL lleva la clave
+            print(f"  (búsqueda '{consulta}' falló: {respuesta.status_code})")
+            break
+        lote = respuesta.json().get("results", [])
+        resultados += lote
+        if len(lote) < 12:
+            break
+    return resultados
+
+
+def ref(proyecto: dict) -> str:
+    return proyecto["url"].removeprefix("https://universe.roboflow.com/")
+
+
+def candidatos(consultas: list[str], clave: str) -> list[dict]:
+    vistos: dict[str, dict] = {}
+    for consulta in consultas:
+        for p in buscar(consulta, clave):
+            if (
+                licencia_comercial(p.get("license") or "")
+                and (p.get("images") or 0) >= MIN_IMAGENES
+                and p.get("latestVersion")
+            ):
+                vistos[ref(p)] = p
+    return sorted(vistos.values(), key=lambda p: p["images"], reverse=True)
+
+
+def main(argumentos: list[str]) -> None:
+    clave = leer_env_local("ROBOFLOW_API_KEY")
+    if not clave:
+        raise SystemExit("Falta ROBOFLOW_API_KEY")
+    grupos = BUSQUEDAS if argumentos == ["--todo"] else {"búsqueda": argumentos}
+    for grupo, consultas in grupos.items():
+        print(f"\n## {grupo}")
+        for p in candidatos(consultas, clave)[:10]:
+            clases = ", ".join(p.get("classes", [])[:8])
+            print(f"  {p['images']:6d}  {p['type']:22} {ref(p):55} [{clases}]")
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

entrenamiento/caracteristicas.py

@@ -0,0 +1,123 @@
+"""Extrae las características de cada imagen con el ConvNeXt-Tiny DINOv3 congelado.
+
+    uv run python -m entrenamiento.caracteristicas
+
+Entrenar la red completa en CPU tardaría días. En su lugar, el backbone se deja
+congelado (no se modifica) y cada imagen se pasa por él una sola vez; después solo se
+entrenan las cabezas sobre esas características, lo que tarda minutos.
+
+Vistas por imagen (cada una es un vector de 1536 números):
+- validación y prueba: original + reflejo (lo mismo que hace el servicio al predecir).
+- entrenamiento: original + VISTAS_AUMENTADAS versiones con recortes, giros y cambios de
+  luz y color, para que el modelo no dependa de un encuadre o iluminación concretos.
+
+Es reanudable: guarda por bloques en datos/procesados/caracteristicas/ y, si se
+interrumpe, continúa por el último bloque terminado. Con CPU, ~0.4 s por vista.
+"""
+
+import json
+import sys
+import time
+
+import torch
+from PIL import Image, ImageOps
+from torchvision.transforms import v2
+
+from app.ml.vision.red_material_estado import a_tensor, resumir_tokens
+from entrenamiento.rutas import BACKBONE, CARACTERISTICAS, IMAGENES, MANIFIESTO, TAMANO_IMAGEN
+
+VISTAS_AUMENTADAS = 2
+TAMANO_BLOQUE = 256
+TAMANO_LOTE = 16
+SPLITS = ("validacion", "prueba", "entrenamiento")
+
+AUMENTO = v2.Compose(
+    [
+        v2.RandomResizedCrop(TAMANO_IMAGEN, scale=(0.45, 1.0), ratio=(0.75, 1.33), antialias=True),
+        v2.RandomHorizontalFlip(),
+        v2.RandomVerticalFlip(p=0.2),
+        v2.RandomApply([v2.RandomRotation(20)], p=0.4),
+        v2.ColorJitter(brightness=0.35, contrast=0.35, saturation=0.3, hue=0.03),
+        v2.RandomGrayscale(p=0.05),
+        v2.RandomApply([v2.GaussianBlur(5, sigma=(0.1, 1.5))], p=0.2),
+    ]
+)
+
+
+def vistas(imagen: Image.Image, aumentar: bool) -> list[Image.Image]:
+    lista = [imagen, ImageOps.mirror(imagen)] if not aumentar else [imagen]
+    if aumentar:
+        lista += [AUMENTO(imagen) for _ in range(VISTAS_AUMENTADAS)]
+    return lista
+
+
+def cargar_backbone():
+    from transformers import DINOv3ConvNextModel
+
+    try:
+        return DINOv3ConvNextModel.from_pretrained(BACKBONE).eval()
+    except OSError as exc:
+        raise SystemExit(
+            f"No se pudo descargar {BACKBONE}: {exc}\n"
+            "Pide acceso en https://huggingface.co/" + BACKBONE + " y ejecuta "
+            "`uv run hf auth login`."
+        ) from exc
+
+
+@torch.inference_mode()
+def extraer(backbone, imagenes: list[Image.Image]) -> torch.Tensor:
+    salidas = []
+    for inicio in range(0, len(imagenes), TAMANO_LOTE):
+        lote = a_tensor(imagenes[inicio : inicio + TAMANO_LOTE], TAMANO_IMAGEN)
+        salidas.append(resumir_tokens(backbone(pixel_values=lote).last_hidden_state))
+    return torch.cat(salidas)
+
+
+def _cache(split: str) -> dict[str, torch.Tensor]:
+    """Características ya extraídas de este reparto, por id de imagen."""
+    cache: dict[str, torch.Tensor] = {}
+    for archivo in sorted(CARACTERISTICAS.glob(f"cache_{split}_*.pt")):
+        parte = torch.load(archivo)
+        cache.update(zip(parte["ids"], parte["x"], strict=True))
+    return cache
+
+
+def procesar_split(backbone, split: str, ids: list[str]) -> None:
+    aumentar = split == "entrenamiento"
+    n_vistas = 1 + VISTAS_AUMENTADAS if aumentar else 2
+    cache = _cache(split)
+    pendientes = [i for i in ids if i not in cache]
+    print(f"{split}: {len(ids)} imágenes, {len(pendientes)} por extraer", flush=True)
+    inicio = time.time()
+    siguiente = len(list(CARACTERISTICAS.glob(f"cache_{split}_*.pt")))
+    for numero in range(0, len(pendientes), TAMANO_BLOQUE):
+        bloque = pendientes[numero : numero + TAMANO_BLOQUE]
+        torch.manual_seed(int(bloque[0], 16) % 2**31)  # aumentos reproducibles
+        imagenes = []
+        for id_ in bloque:
+            with Image.open(IMAGENES / f"{id_}.jpg") as imagen:
+                imagenes += vistas(imagen.convert("RGB"), aumentar)
+        x = extraer(backbone, imagenes).reshape(len(bloque), n_vistas, -1).half()
+        torch.save({"ids": bloque, "x": x}, CARACTERISTICAS / f"cache_{split}_{siguiente:04d}.pt")
+        siguiente += 1
+        cache.update(zip(bloque, x, strict=True))
+        hechos = min(numero + TAMANO_BLOQUE, len(pendientes))
+        restante = (time.time() - inicio) / hechos * (len(pendientes) - hechos)
+        print(f"{split}: {hechos}/{len(pendientes)} (quedan ~{restante / 60:.0f} min)", flush=True)
+    torch.save(
+        {"ids": ids, "x": torch.stack([cache[i] for i in ids])}, CARACTERISTICAS / f"{split}.pt"
+    )
+    print(f"{split}: listo → {CARACTERISTICAS / f'{split}.pt'}")
+
+
+def main(splits: list[str]) -> None:
+    CARACTERISTICAS.mkdir(parents=True, exist_ok=True)
+    registros = [json.loads(linea) for linea in MANIFIESTO.read_text(encoding="utf-8").splitlines()]
+    backbone = cargar_backbone()
+    torch.set_num_threads(max(1, torch.get_num_threads()))
+    for split in splits or SPLITS:
+        procesar_split(backbone, split, [r["id"] for r in registros if r["split"] == split])
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

entrenamiento/colab_entrenamiento.ipynb

@@ -0,0 +1,137 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# REVALORA · Ajuste fino completo del modelo de material y estado\n",
+    "\n",
+    "Entrena el ConvNeXt-Tiny DINOv3 completo (backbone + 2 cabezas) con GPU gratuita.\n",
+    "\n",
+    "**Antes**, en tu equipo: `uv run python -m entrenamiento.empaquetar_colab` → genera `datos/revalora_colab.zip`.\n",
+    "\n",
+    "**Aquí**: *Entorno de ejecución → Cambiar tipo de entorno → GPU (T4)* y ejecuta las celdas en orden.\n",
+    "Tarda ~1-2 h con unas 25 000 imágenes. Al final descarga `material_estado.zip` y descomprímelo en\n",
+    "`revalora-ia-service/modelos_entrenados/` (sustituye la carpeta `material_estado`)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!nvidia-smi --query-gpu=name,memory.total --format=csv"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Sube el paquete\n",
+    "Opción A (recomendada si pesa más de 500 MB): súbelo a tu Google Drive y monta Drive.\n",
+    "Opción B: súbelo directamente (más lento)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "USAR_DRIVE = True  # False para subirlo directamente\n",
+    "\n",
+    "if USAR_DRIVE:\n",
+    "    from google.colab import drive\n",
+    "\n",
+    "    drive.mount(\"/content/drive\")\n",
+    "    ZIP = (\n",
+    "        \"/content/drive/MyDrive/revalora_colab.zip\"  # ajusta la ruta si lo pusiste en otra carpeta\n",
+    "    )\n",
+    "else:\n",
+    "    from google.colab import files\n",
+    "\n",
+    "    files.upload()\n",
+    "    ZIP = \"/content/revalora_colab.zip\"\n",
+    "\n",
+    "!unzip -q -o \"$ZIP\" -d /content/revalora\n",
+    "os.chdir(\"/content/revalora\")\n",
+    "!ls"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Dependencias y acceso a DINOv3\n",
+    "El modelo base tiene acceso restringido: usa un token de Hugging Face de una cuenta que ya tenga acceso a\n",
+    "`facebook/dinov3-convnext-tiny-pretrain-lvd1689m`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install -q \"transformers>=5.0\" safetensors pydantic-settings scikit-learn\n",
+    "from huggingface_hub import notebook_login\n",
+    "\n",
+    "notebook_login()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Entrenamiento\n",
+    "Muestra la pérdida y la puntuación de validación por época, y al final el informe con las métricas del conjunto de prueba."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!python -m entrenamiento.afinar_completo"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Descarga el modelo"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!cd modelos_entrenados && zip -q -r /content/material_estado.zip material_estado\n",
+    "from google.colab import files\n",
+    "\n",
+    "files.download(\"/content/material_estado.zip\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

entrenamiento/descargar.py

@@ -0,0 +1,230 @@
+"""Descarga los datasets de fuentes.py en datos/crudos/<nombre>/.
+
+    uv run python -m entrenamiento.descargar            # todas las fuentes
+    uv run python -m entrenamiento.descargar trashnet   # solo algunas
+
+Es reanudable: una fuente ya descargada (con el archivo .completo) no se vuelve a bajar.
+Las fuentes que necesitan credenciales que no están configuradas se omiten con aviso:
+- Kaggle:   C:\\Users\\<usuario>\\.kaggle\\kaggle.json  (o KAGGLE_USERNAME/KAGGLE_KEY)
+- Roboflow: variable ROBOFLOW_API_KEY
+- Hugging Face: `uv run hf auth login` (solo para el modelo DINOv3, no para los datos)
+Al terminar escribe datos/procesados/fuentes.json con el resultado de cada fuente.
+"""
+
+import json
+import os
+import re
+import shutil
+import sys
+import time
+import zipfile
+from dataclasses import asdict
+from pathlib import Path
+
+import requests
+
+from entrenamiento.fuentes import FUENTES, Fuente, licencia_comercial
+from entrenamiento.rutas import CRUDOS, INFORME_FUENTES, asegurar_carpetas, leer_env_local
+
+MARCA = ".completo"
+API_ROBOFLOW = "https://api.roboflow.com"
+
+
+class FuenteOmitida(Exception):
+    """La fuente no se puede usar (credenciales, licencia, no existe...)."""
+
+
+def _descargar_url(url: str, destino: Path) -> Path:
+    destino.parent.mkdir(parents=True, exist_ok=True)
+    temporal = destino.with_suffix(destino.suffix + ".parcial")
+    with requests.get(url, stream=True, timeout=60) as respuesta:
+        respuesta.raise_for_status()
+        with temporal.open("wb") as archivo:
+            for bloque in respuesta.iter_content(chunk_size=1 << 20):
+                archivo.write(bloque)
+    temporal.replace(destino)
+    return destino
+
+
+def _extraer(zip_path: Path, carpeta: Path) -> None:
+    with zipfile.ZipFile(zip_path) as zf:
+        zf.extractall(carpeta)
+    zip_path.unlink()
+    # Algunos zips traen otros zips dentro (TrashNet en HF).
+    for interno in list(carpeta.rglob("*.zip")):
+        _extraer(interno, interno.parent)
+
+
+# ----------------------------------------------------------------------------- orígenes
+
+
+def _hf(fuente: Fuente, carpeta: Path) -> dict:
+    from huggingface_hub import hf_hub_download
+
+    ruta = hf_hub_download(
+        fuente.ref, fuente.archivo, repo_type="dataset", local_dir=str(carpeta / "_hf")
+    )
+    _extraer(Path(ruta), carpeta)
+    shutil.rmtree(carpeta / "_hf", ignore_errors=True)
+    return {"licencia": fuente.licencia}
+
+
+def _url(fuente: Fuente, carpeta: Path) -> dict:
+    _extraer(_descargar_url(fuente.ref, carpeta / "descarga.zip"), carpeta)
+    return {"licencia": fuente.licencia}
+
+
+def _kaggle(fuente: Fuente, carpeta: Path) -> dict:
+    # La librería lee las variables del proceso; si se guardaron con `setx` y la terminal
+    # no se reinició, no las ve: se copian desde las variables de usuario de Windows.
+    for variable in ("KAGGLE_API_TOKEN", "KAGGLE_USERNAME", "KAGGLE_KEY"):
+        valor = leer_env_local(variable)
+        if valor and not os.environ.get(variable):
+            os.environ[variable] = valor
+    carpeta_kaggle = Path.home() / ".kaggle"
+    if not (
+        (carpeta_kaggle / "kaggle.json").is_file()
+        or (carpeta_kaggle / "access_token").is_file()
+        or os.environ.get("KAGGLE_API_TOKEN")
+        or (os.environ.get("KAGGLE_USERNAME") and os.environ.get("KAGGLE_KEY"))
+    ):
+        raise FuenteOmitida("faltan las credenciales de Kaggle (KAGGLE_API_TOKEN o kaggle.json)")
+    from kaggle.api.kaggle_api_extended import KaggleApi
+
+    api = KaggleApi()
+    api.authenticate()
+    # El nombre completo de la licencia ("Database: Open Database, Contents: © Original
+    # Authors") distingue la licencia de la base de datos de la de las fotos.
+    propietario, nombre = fuente.ref.split("/")
+    licencia = next(
+        (
+            d.license_name
+            for d in api.dataset_list(search=nombre, user=propietario)
+            if d.ref == fuente.ref
+        ),
+        None,
+    )
+    if not licencia:
+        api.dataset_metadata(fuente.ref, path=str(carpeta))
+        meta = json.loads((carpeta / "dataset-metadata.json").read_text(encoding="utf-8"))
+        info = meta.get("info", meta)
+        licencia = ", ".join(lic.get("name", "") for lic in info.get("licenses", []))
+    licencia = licencia or "desconocida"
+    if not licencia_comercial(licencia):
+        raise FuenteOmitida(f"licencia no compatible con uso comercial: {licencia}")
+    api.dataset_download_files(fuente.ref, path=str(carpeta), unzip=True, quiet=True)
+    return {"licencia": licencia}
+
+
+def _licencia_roboflow(info: dict, ref: str) -> str:
+    for clave in ("license", "licence"):
+        if isinstance(info.get("project", {}).get(clave), str):
+            return info["project"][clave]
+    # La API no siempre la incluye: se lee de la página pública del proyecto.
+    html = requests.get(f"https://universe.roboflow.com/{ref}", timeout=30).text
+    encontrada = re.search(
+        r"(CC BY[- ](?:NC[- ])?(?:SA[- ])?4\.0|CC0[^<\"]{0,12}|Public Domain|MIT|"
+        r"BY-NC-SA 4\.0|ODbL[^<\"]{0,8}|Private)",
+        html,
+    )
+    return encontrada.group(1) if encontrada else "desconocida"
+
+
+def _get_roboflow(url: str, clave: str, timeout: int = 60) -> requests.Response:
+    """GET con reintentos si Roboflow limita las peticiones (429)."""
+    for espera in (0, 10, 30, 60, 120):
+        time.sleep(espera)
+        respuesta = requests.get(url, params={"api_key": clave}, timeout=timeout)
+        if respuesta.status_code != 429:
+            return respuesta
+    return respuesta
+
+
+def _roboflow(fuente: Fuente, carpeta: Path) -> dict:
+    clave = leer_env_local("ROBOFLOW_API_KEY")
+    if not clave:
+        raise FuenteOmitida("falta la variable ROBOFLOW_API_KEY")
+    respuesta = _get_roboflow(f"{API_ROBOFLOW}/{fuente.ref}", clave)
+    if respuesta.status_code in (401, 403, 404):
+        raise FuenteOmitida(f"el proyecto no existe o no es público ({respuesta.status_code})")
+    if respuesta.status_code != 200:  # sin raise_for_status: su mensaje incluye la clave
+        raise FuenteOmitida(f"Roboflow respondió {respuesta.status_code}")
+    info = respuesta.json()
+    licencia = _licencia_roboflow(info, fuente.ref)
+    if not licencia_comercial(licencia):
+        raise FuenteOmitida(f"licencia no compatible con uso comercial: {licencia}")
+
+    proyecto = info.get("project", {})
+    versiones = sorted(
+        info.get("versions", []), key=lambda v: int(v["id"].rsplit("/", 1)[1]), reverse=True
+    )
+    if not versiones:
+        raise FuenteOmitida("el proyecto no tiene versiones publicadas")
+    tipo = proyecto.get("type", "object-detection")
+    formato = "folder" if tipo == "classification" else "coco"
+    version = versiones[0]["id"].rsplit("/", 1)[1]
+
+    url_export = f"{API_ROBOFLOW}/{fuente.ref}/{version}/{formato}"
+    for _ in range(60):  # Roboflow genera el export bajo demanda
+        datos = _get_roboflow(url_export, clave, timeout=120).json()
+        enlace = datos.get("export", {}).get("link")
+        if enlace:
+            break
+        time.sleep(5)
+    else:
+        raise FuenteOmitida("Roboflow no terminó de generar la exportación")
+    _extraer(_descargar_url(enlace, carpeta / "descarga.zip"), carpeta)
+    return {
+        "licencia": licencia,
+        "tipo": tipo,
+        "formato": formato,
+        "version": version,
+        "clases": list(proyecto.get("classes", {}).keys()),
+        "imagenes": versiones[0].get("images"),
+    }
+
+
+ORIGENES = {"hf": _hf, "url": _url, "kaggle": _kaggle, "roboflow": _roboflow}
+
+
+def descargar(fuente: Fuente) -> dict:
+    carpeta = CRUDOS / fuente.nombre
+    marca = carpeta / MARCA
+    if marca.is_file():
+        return {"estado": "descargada", **json.loads(marca.read_text(encoding="utf-8"))}
+    shutil.rmtree(carpeta, ignore_errors=True)
+    carpeta.mkdir(parents=True, exist_ok=True)
+    try:
+        meta = ORIGENES[fuente.origen](fuente, carpeta)
+    except FuenteOmitida as exc:
+        shutil.rmtree(carpeta, ignore_errors=True)
+        return {"estado": "omitida", "motivo": str(exc)}
+    except Exception as exc:  # red, formato inesperado...
+        shutil.rmtree(carpeta, ignore_errors=True)
+        # Las URLs de Roboflow llevan la clave: nunca se guardan ni se muestran.
+        motivo = re.sub(r"api_key=[^&\s]+", "api_key=***", f"{type(exc).__name__}: {exc}")
+        return {"estado": "error", "motivo": motivo}
+    marca.write_text(json.dumps(meta, ensure_ascii=False), encoding="utf-8")
+    return {"estado": "descargada", **meta}
+
+
+def main(nombres: list[str]) -> None:
+    asegurar_carpetas()
+    informe = json.loads(INFORME_FUENTES.read_text("utf-8")) if INFORME_FUENTES.is_file() else {}
+    for fuente in FUENTES:
+        if nombres and fuente.nombre not in nombres:
+            continue
+        print(f"- {fuente.nombre} ({fuente.origen}: {fuente.ref}) ...", flush=True)
+        resultado = descargar(fuente)
+        informe[fuente.nombre] = {**asdict(fuente), **resultado}
+        print(f"    {resultado['estado']}: {resultado.get('motivo', resultado.get('licencia'))}")
+        INFORME_FUENTES.write_text(json.dumps(informe, ensure_ascii=False, indent=2), "utf-8")
+    resumen = {
+        e: sum(1 for r in informe.values() if r["estado"] == e)
+        for e in ("descargada", "omitida", "error")
+    }
+    print(f"\nResumen: {resumen}. Detalle en {INFORME_FUENTES}")
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

entrenamiento/empaquetar_colab.py

@@ -0,0 +1,40 @@
+"""Empaqueta código y datos para entrenar en Google Colab.
+
+    uv run python -m entrenamiento.empaquetar_colab
+
+Crea datos/revalora_colab.zip con:
+- app/ y entrenamiento/ (el código, para usar exactamente las mismas funciones),
+- datos/procesados/ (manifiesto + imágenes ya reducidas a 512 px),
+- modelos_entrenados/material_estado/ si existe (arranque en caliente).
+Súbelo a Colab y sigue entrenamiento/colab_entrenamiento.ipynb.
+"""
+
+import zipfile
+
+from app.core.config import BASE_DIR
+from entrenamiento.rutas import DATOS, IMAGENES, INFORME_FUENTES, MANIFIESTO, SALIDA_MODELO
+
+DESTINO = DATOS / "revalora_colab.zip"
+
+
+def main() -> None:
+    if not MANIFIESTO.is_file():
+        raise SystemExit("Ejecuta antes: python -m entrenamiento.preparar")
+    archivos = [
+        *(BASE_DIR / "app").rglob("*.py"),
+        *(BASE_DIR / "app").rglob("*.json"),
+        *(BASE_DIR / "entrenamiento").rglob("*.py"),
+        MANIFIESTO,
+        *([INFORME_FUENTES] if INFORME_FUENTES.is_file() else []),
+        *IMAGENES.glob("*.jpg"),
+        *(SALIDA_MODELO.glob("*") if SALIDA_MODELO.is_dir() else []),
+    ]
+    with zipfile.ZipFile(DESTINO, "w", zipfile.ZIP_STORED) as zf:
+        for archivo in archivos:
+            if "__pycache__" not in archivo.parts:
+                zf.write(archivo, archivo.relative_to(BASE_DIR).as_posix())
+    print(f"{DESTINO} ({DESTINO.stat().st_size / 1e6:.0f} MB, {len(archivos)} archivos)")
+
+
+if __name__ == "__main__":
+    main()

entrenamiento/entrenar.py

@@ -0,0 +1,460 @@
+"""Entrena las dos cabezas (material y defectos), las evalúa y exporta el modelo.
+
+    uv run python -m entrenamiento.entrenar
+
+Requiere haber ejecutado antes descargar → preparar → caracteristicas.
+
+- Cabeza de material: entropía cruzada con pesos por clase (las clases con menos fotos
+  pesan más) y suavizado de etiquetas.
+- Cabeza de defectos: entropía cruzada binaria con máscara: cada imagen solo enseña los
+  defectos que su dataset etiqueta; el resto no cuenta (ni a favor ni en contra).
+- En cada época se usa una vista aleatoria de cada imagen (original o aumentada).
+- Se queda con la época que mejor puntúa en validación y para si deja de mejorar.
+- Calibra la confianza del material (temperatura) con la validación.
+- Evalúa con el conjunto de prueba, que no se usó para nada antes, y escribe el informe.
+"""
+
+import json
+import math
+from dataclasses import dataclass
+from datetime import date
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from sklearn.metrics import (
+    accuracy_score,
+    average_precision_score,
+    confusion_matrix,
+    f1_score,
+    precision_recall_fscore_support,
+    roc_auc_score,
+)
+
+from app.ml.estado.defectos import GRAVEDAD, ORDEN_DEFECTOS
+from app.ml.materiales import ORDEN_MATERIALES
+from app.ml.vision.red_material_estado import (
+    CabezasMaterialEstado,
+    Metadatos,
+    RedMaterialEstado,
+    guardar,
+)
+from entrenamiento.fuentes import FUENTES
+from entrenamiento.rutas import (
+    BACKBONE,
+    CARACTERISTICAS,
+    INFORME_FUENTES,
+    MANIFIESTO,
+    SALIDA_MODELO,
+    TAMANO_IMAGEN,
+)
+
+DIM_OCULTA = 512
+DROPOUT = 0.3
+EPOCAS = 150
+TAMANO_LOTE = 256
+TASA_APRENDIZAJE = 1e-3
+PACIENCIA = 25
+PESO_DEFECTOS = 1.0
+SUAVIZADO = 0.1
+# Para dar por "validada" la nota de estado de un material en el conjunto de prueba:
+MIN_MUESTRAS_ESTADO = 30
+MIN_POR_CLASE_AUC = 5
+# Un defecto se usa en el servicio solo si tuvo al menos esto de ejemplos con y sin él.
+MIN_EJEMPLOS_DEFECTO = 30
+AUC_MINIMA_ESTADO = 0.80
+
+MATERIAL_DE_FUENTE = {f.nombre: f.material for f in FUENTES}
+
+
+@dataclass
+class Datos:
+    ids: list[str]
+    x: torch.Tensor  # [N, vistas, D]
+    material: torch.Tensor  # [N] índice o -1 si no se usa
+    defectos: torch.Tensor  # [N, K] 0/1
+    mascara: torch.Tensor  # [N, K] True si el defecto es conocido
+    material_estado: list[str | None]  # material para evaluar el estado (aunque no se entrene)
+
+
+def cargar_split(split: str, registros: dict[str, dict]) -> Datos:
+    guardado = torch.load(CARACTERISTICAS / f"{split}.pt")
+    ids = guardado["ids"]
+    n, k = len(ids), len(ORDEN_DEFECTOS)
+    material = torch.full((n,), -1, dtype=torch.long)
+    defectos = torch.zeros(n, k)
+    mascara = torch.zeros(n, k, dtype=torch.bool)
+    material_estado: list[str | None] = []
+    for i, id_ in enumerate(ids):
+        r = registros[id_]
+        if r["material"] is not None:
+            material[i] = ORDEN_MATERIALES.index(r["material"])
+        for codigo, valor in r["defectos"].items():
+            j = ORDEN_DEFECTOS.index(codigo)
+            defectos[i, j] = float(valor)
+            mascara[i, j] = True
+        material_estado.append(r["material"] or MATERIAL_DE_FUENTE.get(r["fuente"]))
+    return Datos(ids, guardado["x"].float(), material, defectos, mascara, material_estado)
+
+
+def pesos_material(material: torch.Tensor) -> torch.Tensor:
+    conteo = torch.bincount(material[material >= 0], minlength=len(ORDEN_MATERIALES)).float()
+    pesos = torch.where(conteo > 0, conteo.clamp(min=1).rsqrt(), torch.zeros_like(conteo))
+    return pesos / pesos[conteo > 0].mean()
+
+
+def defectos_entrenables(datos: Datos) -> list[str]:
+    """Defectos con ejemplos suficientes con y sin el defecto para aprender algo útil."""
+    positivos = (datos.defectos * datos.mascara).sum(0)
+    negativos = ((1 - datos.defectos) * datos.mascara).sum(0)
+    return [
+        codigo
+        for j, codigo in enumerate(ORDEN_DEFECTOS)
+        if positivos[j] >= MIN_EJEMPLOS_DEFECTO and negativos[j] >= MIN_EJEMPLOS_DEFECTO
+    ]
+
+
+def peso_positivos(datos: Datos) -> torch.Tensor:
+    positivos = (datos.defectos * datos.mascara).sum(0)
+    negativos = ((1 - datos.defectos) * datos.mascara).sum(0)
+    return torch.where(
+        positivos > 0, negativos / positivos.clamp(min=1), torch.ones_like(positivos)
+    ).clamp(1, 20)
+
+
+@torch.no_grad()
+def predecir(cabezas: CabezasMaterialEstado, x: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+    """Promedia las vistas, igual que el servicio con la foto y su reflejo."""
+    cabezas.eval()
+    n, v, d = x.shape
+    logits_m, logits_d = cabezas(x.reshape(n * v, d))
+    return logits_m.reshape(n, v, -1).mean(1), logits_d.sigmoid().reshape(n, v, -1).mean(1)
+
+
+# --------------------------------------------------------------------------------- métricas
+
+
+def metricas_material(logits: torch.Tensor, y: torch.Tensor, temperatura: float = 1.0) -> dict:
+    validos = y >= 0
+    if not validos.any():
+        return {}
+    y_real = y[validos].numpy()
+    prob = (logits[validos] / temperatura).softmax(-1)
+    y_pred = prob.argmax(-1).numpy()
+    presentes = sorted(set(y_real))
+    precision, recall, f1, soporte = precision_recall_fscore_support(
+        y_real, y_pred, labels=presentes, zero_division=0
+    )
+    confianza = prob.max(-1).values.numpy()
+    return {
+        "exactitud": float(accuracy_score(y_real, y_pred)),
+        "f1_macro": float(f1_score(y_real, y_pred, labels=presentes, average="macro")),
+        "confianza_media": float(confianza.mean()),
+        "por_clase": {
+            ORDEN_MATERIALES[c]: {
+                "precision": float(p),
+                "recall": float(r),
+                "f1": float(f),
+                "muestras": int(s),
+            }
+            for c, p, r, f, s in zip(presentes, precision, recall, f1, soporte, strict=True)
+        },
+        "matriz_confusion": {
+            "clases": [ORDEN_MATERIALES[c] for c in presentes],
+            "valores": confusion_matrix(y_real, y_pred, labels=presentes).tolist(),
+        },
+    }
+
+
+def _auc(y: np.ndarray, p: np.ndarray) -> float | None:
+    if (y == 1).sum() < MIN_POR_CLASE_AUC or (y == 0).sum() < MIN_POR_CLASE_AUC:
+        return None
+    return float(roc_auc_score(y, p))
+
+
+def metricas_defectos(prob: torch.Tensor, datos: Datos) -> dict:
+    resultado = {}
+    for j, codigo in enumerate(ORDEN_DEFECTOS):
+        conocidos = datos.mascara[:, j].numpy()
+        y = datos.defectos[conocidos, j].numpy()
+        p = prob[conocidos, j].numpy()
+        auc = _auc(y, p)
+        resultado[codigo] = {
+            "conocidos": int(conocidos.sum()),
+            "positivos": int(y.sum()),
+            "auc": auc,
+            "precision_media": float(average_precision_score(y, p)) if auc is not None else None,
+            "exactitud_0_5": float(((p >= 0.5) == y).mean()) if len(y) else None,
+        }
+    return resultado
+
+
+def estado_por_material(prob: torch.Tensor, datos: Datos) -> dict:
+    """AUC media de los defectos relevantes de cada material, con las fotos de prueba."""
+    resultado = {}
+    for material in ORDEN_MATERIALES:
+        filas = np.array([m == material for m in datos.material_estado])
+        aucs, muestras = {}, 0
+        for j, codigo in enumerate(ORDEN_DEFECTOS):
+            if GRAVEDAD.get(material, {}).get(codigo, 0) <= 0:
+                continue
+            conocidos = filas & datos.mascara[:, j].numpy()
+            muestras = max(muestras, int(conocidos.sum()))
+            auc = _auc(datos.defectos[conocidos, j].numpy(), prob[conocidos, j].numpy())
+            if auc is not None:
+                aucs[codigo] = round(auc, 4)
+        media = float(np.mean(list(aucs.values()))) if aucs else None
+        resultado[material] = {
+            "muestras": muestras,
+            "auc_por_defecto": aucs,
+            "auc_media": media,
+            "validado": bool(
+                media is not None and muestras >= MIN_MUESTRAS_ESTADO and media >= AUC_MINIMA_ESTADO
+            ),
+        }
+    return resultado
+
+
+def puntuacion(logits_m, prob_d, datos: Datos) -> float:
+    material = metricas_material(logits_m, datos.material).get("f1_macro", 0.0)
+    aucs = [m["auc"] for m in metricas_defectos(prob_d, datos).values() if m["auc"] is not None]
+    return material + (0.5 * float(np.mean(aucs)) if aucs else 0.0)
+
+
+# ---------------------------------------------------------------------------- entrenamiento
+
+
+def entrenar(entrenamiento: Datos, validacion: Datos) -> tuple[CabezasMaterialEstado, list[dict]]:
+    torch.manual_seed(2026)
+    n, n_vistas, dim = entrenamiento.x.shape
+    cabezas = CabezasMaterialEstado(
+        dim, len(ORDEN_MATERIALES), len(ORDEN_DEFECTOS), DIM_OCULTA, DROPOUT
+    )
+    optimizador = torch.optim.AdamW(cabezas.parameters(), lr=TASA_APRENDIZAJE, weight_decay=0.05)
+    pasos_por_epoca = math.ceil(n / TAMANO_LOTE)
+    total = EPOCAS * pasos_por_epoca
+    calentamiento = 3 * pasos_por_epoca
+    planificador = torch.optim.lr_scheduler.LambdaLR(
+        optimizador,
+        lambda paso: (
+            min(1.0, (paso + 1) / calentamiento)
+            * 0.5
+            * (1 + math.cos(math.pi * min(paso, total) / total))
+        ),
+    )
+    w_material = pesos_material(entrenamiento.material)
+    w_positivos = peso_positivos(entrenamiento)
+
+    mejor, mejor_estado, sin_mejora, historial = -1.0, None, 0, []
+    for epoca in range(1, EPOCAS + 1):
+        cabezas.train()
+        orden = torch.randperm(n)
+        perdida_total = 0.0
+        for inicio in range(0, n, TAMANO_LOTE):
+            idx = orden[inicio : inicio + TAMANO_LOTE]
+            vista = torch.randint(0, n_vistas, (len(idx),))
+            x = entrenamiento.x[idx, vista]
+            logits_m, logits_d = cabezas(x)
+
+            y_m = entrenamiento.material[idx]
+            validos = y_m >= 0
+            perdida_m = (
+                F.cross_entropy(
+                    logits_m[validos], y_m[validos], weight=w_material, label_smoothing=SUAVIZADO
+                )
+                if validos.any()
+                else logits_m.sum() * 0
+            )
+            mascara = entrenamiento.mascara[idx].float()
+            perdida_d = (
+                F.binary_cross_entropy_with_logits(
+                    logits_d, entrenamiento.defectos[idx], pos_weight=w_positivos, reduction="none"
+                )
+                * mascara
+            ).sum() / mascara.sum().clamp(min=1)
+            perdida = perdida_m + PESO_DEFECTOS * perdida_d
+
+            optimizador.zero_grad()
+            perdida.backward()
+            optimizador.step()
+            planificador.step()
+            perdida_total += perdida.item() * len(idx)
+
+        logits_m, prob_d = predecir(cabezas, validacion.x)
+        valor = puntuacion(logits_m, prob_d, validacion)
+        historial.append({"epoca": epoca, "perdida": perdida_total / n, "validacion": valor})
+        if valor > mejor + 1e-4:
+            mejor, sin_mejora = valor, 0
+            mejor_estado = {k: v.clone() for k, v in cabezas.state_dict().items()}
+        else:
+            sin_mejora += 1
+        if epoca % 10 == 0 or sin_mejora == 0:
+            print(
+                f"  época {epoca:3d}  pérdida {perdida_total / n:.4f}  validación {valor:.4f}",
+                flush=True,
+            )
+        if sin_mejora >= PACIENCIA:
+            print(f"  sin mejora en {PACIENCIA} épocas: se para en la {epoca}")
+            break
+
+    cabezas.load_state_dict(mejor_estado)
+    return cabezas.eval(), historial
+
+
+def ajustar_temperatura(logits: torch.Tensor, y: torch.Tensor) -> float:
+    """Temperatura que hace que la confianza del material refleje su tasa real de acierto."""
+    validos = y >= 0
+    if validos.sum() < 20:
+        return 1.0
+    log_t = torch.zeros(1, requires_grad=True)
+    optimizador = torch.optim.LBFGS([log_t], lr=0.1, max_iter=100)
+
+    def cierre():
+        optimizador.zero_grad()
+        perdida = F.cross_entropy(logits[validos] / log_t.exp(), y[validos])
+        perdida.backward()
+        return perdida
+
+    optimizador.step(cierre)
+    return float(log_t.detach().exp().clamp(0.5, 5.0))
+
+
+# ---------------------------------------------------------------------------------- informe
+
+
+def _pct(valor: float | None) -> str:
+    return "—" if valor is None else f"{valor * 100:.1f} %"
+
+
+def escribir_informe(metadatos: Metadatos, conteo: dict, fuentes: dict) -> str:
+    ev = metadatos.evaluacion
+    lineas = [
+        "# Informe del modelo de material y estado",
+        "",
+        f"- Fecha: {ev['fecha']}",
+        f"- Backbone: `{metadatos.backbone_origen}` + 2 cabezas (material y defectos)",
+        f"- Tamaño de imagen: {metadatos.tamano_imagen} px · Temperatura: {metadatos.temperatura_material:.3f}",
+        f"- Imágenes: {conteo['entrenamiento']} entrenamiento · {conteo['validacion']} validación · {conteo['prueba']} prueba",
+        "",
+        "## Material (conjunto de prueba)",
+        "",
+        f"**Exactitud: {_pct(ev['material'].get('exactitud'))}** · F1 macro: {_pct(ev['material'].get('f1_macro'))}",
+        "",
+        "| Material | Precisión | Recall | F1 | Fotos de prueba |",
+        "|---|---|---|---|---|",
+    ]
+    for material in ORDEN_MATERIALES:
+        c = ev["material"].get("por_clase", {}).get(material)
+        if c:
+            lineas.append(
+                f"| {material} | {_pct(c['precision'])} | {_pct(c['recall'])} | {_pct(c['f1'])} | {c['muestras']} |"
+            )
+        else:
+            lineas.append(f"| {material} | — | — | — | 0 (sin datos) |")
+    lineas += [
+        "",
+        "## Defectos (conjunto de prueba)",
+        "",
+        "AUC: probabilidad de que una foto con el defecto puntúe más que una sin él (50 % = azar, 100 % = perfecto).",
+        "",
+        f"Solo se usan en la nota los defectos con ≥ {MIN_EJEMPLOS_DEFECTO} ejemplos con y sin "
+        "el defecto en entrenamiento.",
+        "",
+        "| Defecto | Se usa | AUC | Precisión media | Positivos / conocidos (prueba) |",
+        "|---|---|---|---|---|",
+    ]
+    for codigo, m in ev["defectos"].items():
+        usado = "sí" if codigo in metadatos.defectos_entrenados else "no"
+        lineas.append(
+            f"| {codigo} | {usado} | {_pct(m['auc'])} | {_pct(m['precision_media'])} | "
+            f"{m['positivos']} / {m['conocidos']} |"
+        )
+    lineas += [
+        "",
+        "## Nota de estado por material",
+        "",
+        f"Se marca como validada si hay ≥ {MIN_MUESTRAS_ESTADO} fotos de prueba con defectos etiquetados "
+        f"y la AUC media de sus defectos es ≥ {AUC_MINIMA_ESTADO:.0%}. Si no, la API devuelve `fiable: false`.",
+        "",
+        "| Material | Validada | AUC media | Fotos | AUC por defecto |",
+        "|---|---|---|---|---|",
+    ]
+    for material, m in ev["estado_por_material"].items():
+        detalle = ", ".join(f"{d} {_pct(a)}" for d, a in m["auc_por_defecto"].items()) or "—"
+        lineas.append(
+            f"| {material} | {'sí' if m['validado'] else 'no'} | {_pct(m['auc_media'])} | {m['muestras']} | {detalle} |"
+        )
+    lineas += [
+        "",
+        "## Fuentes de datos",
+        "",
+        "| Fuente | Estado | Licencia | Web |",
+        "|---|---|---|---|",
+    ]
+    for nombre, f in fuentes.items():
+        estado = (
+            f["estado"] if f["estado"] == "descargada" else f"{f['estado']}: {f.get('motivo', '')}"
+        )
+        lineas.append(f"| {nombre} | {estado} | {f.get('licencia', '')} | {f['web']} |")
+    return "\n".join(lineas) + "\n"
+
+
+def main() -> None:
+    registros = {
+        r["id"]: r
+        for r in (
+            json.loads(linea) for linea in MANIFIESTO.read_text(encoding="utf-8").splitlines()
+        )
+    }
+    datos = {s: cargar_split(s, registros) for s in ("entrenamiento", "validacion", "prueba")}
+    conteo = {s: len(d.ids) for s, d in datos.items()}
+    print(f"Imágenes: {conteo}")
+
+    print("Entrenando las cabezas ...")
+    cabezas, historial = entrenar(datos["entrenamiento"], datos["validacion"])
+
+    logits_val, _ = predecir(cabezas, datos["validacion"].x)
+    temperatura = ajustar_temperatura(logits_val, datos["validacion"].material)
+    print(f"Temperatura de calibración: {temperatura:.3f}")
+
+    prueba = datos["prueba"]
+    logits_m, prob_d = predecir(cabezas, prueba.x)
+    estado = estado_por_material(prob_d, prueba)
+    evaluacion = {
+        "fecha": date.today().isoformat(),
+        "imagenes": conteo,
+        "material": metricas_material(logits_m, prueba.material, temperatura),
+        "defectos": metricas_defectos(prob_d, prueba),
+        "estado_por_material": estado,
+        "epocas": len(historial),
+    }
+
+    from transformers import DINOv3ConvNextModel
+
+    backbone = DINOv3ConvNextModel.from_pretrained(BACKBONE).eval()
+    metadatos = Metadatos(
+        materiales=list(ORDEN_MATERIALES),
+        defectos=list(ORDEN_DEFECTOS),
+        tamano_imagen=TAMANO_IMAGEN,
+        dim_caracteristicas=datos["entrenamiento"].x.shape[-1],
+        dim_oculta=DIM_OCULTA,
+        backbone_origen=f"{BACKBONE} (congelado)",
+        temperatura_material=temperatura,
+        defectos_entrenados=defectos_entrenables(datos["entrenamiento"]),
+        estado_validado_en=[m for m, e in estado.items() if e["validado"]],
+        evaluacion=evaluacion,
+    )
+    guardar(RedMaterialEstado(backbone, cabezas), metadatos, SALIDA_MODELO)
+
+    fuentes = (
+        json.loads(INFORME_FUENTES.read_text(encoding="utf-8")) if INFORME_FUENTES.is_file() else {}
+    )
+    informe = escribir_informe(metadatos, conteo, fuentes)
+    (SALIDA_MODELO / "informe.md").write_text(informe, encoding="utf-8")
+    (SALIDA_MODELO / "historial.json").write_text(json.dumps(historial, indent=1), encoding="utf-8")
+    print(f"\nModelo guardado en {SALIDA_MODELO}\n")
+    print(informe)
+
+
+if __name__ == "__main__":
+    main()

entrenamiento/entrenar_peso.py

@@ -0,0 +1,85 @@
+from pathlib import Path
+import joblib
+import numpy as np
+import pandas as pd
+from lightgbm import LGBMRegressor
+from sklearn.compose import TransformedTargetRegressor
+from sklearn.linear_model import Ridge
+from sklearn.model_selection import GroupKFold, train_test_split
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+CSV_PROPIO = Path("datos/peso/caracteristicas.csv")
+CSV_EXT = Path("datos/externos/emma_mat.csv")
+SALIDA = Path("modelos_entrenados/peso")
+MAX_EXT = 300000
+W_PROPIO = 20.0
+NUM = ["area_pieza", "largo_cm_medio", "ancho_cm_medio", "largo_cm_max",
+       "relacion", "espesor_cm", "volumen_cm3"]
+CAT = ["material"]
+
+def preparar(df):
+    df = df.copy()
+    n = df["n_piezas"].clip(lower=1)
+    df["area_pieza"] = df["area_cm2_total"] / n
+    df["relacion"] = df["largo_cm_medio"] / df["ancho_cm_medio"]
+    df["volumen_cm3"] = df["area_pieza"] * df["espesor_cm"]
+    df["pieza_g"] = df["peso_real_g"] / n
+    return df
+
+propio = preparar(pd.read_csv(CSV_PROPIO)); propio["fuente"] = "propio"
+ext = pd.read_csv(CSV_EXT)
+ext = preparar(ext.sample(min(MAX_EXT, len(ext)), random_state=0)); ext["fuente"] = "externo"
+ext["sesion"] = "ext"
+df = pd.concat([propio, ext], ignore_index=True)
+
+X = pd.get_dummies(df[NUM + CAT], columns=CAT).astype(float)
+y = df["pieza_g"]
+n = df["n_piezas"].clip(lower=1)
+es_p = (df["fuente"] == "propio").to_numpy()
+idx_p, idx_e = np.where(es_p)[0], np.where(~es_p)[0]
+print(f"Filas propias: {len(idx_p)} | externas: {len(idx_e)}")
+print("Features:", list(X.columns))
+
+def lgbm():
+    return TransformedTargetRegressor(
+        regressor=LGBMRegressor(n_estimators=600, learning_rate=0.05, num_leaves=63,
+                                min_child_samples=30, subsample=0.8, subsample_freq=1,
+                                colsample_bytree=0.9, random_state=0, verbose=-1),
+        func=np.log1p, inverse_func=np.expm1)
+
+def metricas(pred, real):
+    err = np.abs(pred - real)
+    return err.mean(), np.median(err / real) * 100
+
+tr_e, te_e = train_test_split(idx_e, test_size=0.2, random_state=0)
+m = lgbm().fit(X.iloc[tr_e], y.iloc[tr_e])
+mae, mape = metricas(m.predict(X.iloc[te_e]), y.iloc[te_e].to_numpy())
+print(f"[EMMA holdout] MAE = {mae:.1f} g | error mediano = {mape:.1f} %")
+
+sesiones = df.loc[idx_p, "sesion"].nunique()
+if sesiones >= 2:
+    cv = GroupKFold(n_splits=min(5, sesiones))
+    r = {"lineal (solo propio)": [], "lightgbm (EMMA+propio)": []}
+    for tr, te in cv.split(idx_p, groups=df.loc[idx_p, "sesion"]):
+        tr_i, te_i = idx_p[tr], idx_p[te]
+        lin = make_pipeline(StandardScaler(), Ridge(alpha=1.0)).fit(X.iloc[tr_i], y.iloc[tr_i])
+        ids = np.r_[tr_i, tr_e]
+        w = np.r_[np.full(len(tr_i), W_PROPIO), np.ones(len(tr_e))]
+        gb = lgbm().fit(X.iloc[ids], y.iloc[ids], sample_weight=w)
+        real, k = df["peso_real_g"].iloc[te_i].to_numpy(), n.iloc[te_i].to_numpy()
+        for nom, mod in (("lineal (solo propio)", lin), ("lightgbm (EMMA+propio)", gb)):
+            r[nom].append((np.abs(mod.predict(X.iloc[te_i]) * k - real), real))
+    for nom, lst in r.items():
+        e = np.concatenate([a for a, _ in lst]); rl = np.concatenate([b for _, b in lst])
+        print(f"[propio] {nom:24s} MAE = {e.mean():8.1f} g | error = {(e / rl).mean() * 100:5.1f} %")
+else:
+    print("[propio] Menos de 2 sesiones: no se puede validar con tus datos.")
+
+w = np.where(es_p, W_PROPIO, 1.0)
+final = lgbm().fit(X, y, sample_weight=w)
+SALIDA.mkdir(parents=True, exist_ok=True)
+joblib.dump({"modelo": final, "columnas": list(X.columns), "cat": CAT}, SALIDA / "lgbm_peso.joblib")
+print("Guardado en", SALIDA / "lgbm_peso.joblib")
+
+

entrenamiento/evaluar_conteo.py

@@ -0,0 +1,136 @@
+"""Mide el error del conteo con SAM 3 y elige el umbral de confianza con datos.
+
+    uv run python -m entrenamiento.evaluar_conteo            # 25 fotos por material
+    uv run python -m entrenamiento.evaluar_conteo 60         # 60 fotos por material
+
+SAM 3 no se entrena, pero sí se puede medir: se usan datasets de detección donde cada
+recuadro etiquetado es una pieza (Fuente.piezas), así se sabe la cantidad real de cada foto.
+
+1. Se ejecuta SAM 3 con un umbral bajo (0.1) y se guardan todas las detecciones.
+2. Para cada umbral entre 0.1 y 0.9 se recalcula la cantidad (sin volver a ejecutar SAM 3)
+   y se mide el error medio. Se elige el umbral con menor error.
+3. Se escribe modelos_entrenados/conteo/informe.md y umbral.json; el servicio usa ese
+   umbral si existe (CONTEO_UMBRAL del .env tiene prioridad si se define).
+"""
+
+import json
+import random
+import re
+import sys
+import time
+from collections import defaultdict
+from pathlib import Path
+
+import numpy as np
+from PIL import Image, ImageOps
+
+from app.core.config import settings
+from app.ml.materiales import MATERIAL_POR_CODIGO
+from app.ml.vision.contador_piezas import ContadorSam3, Pieza, filtrar_piezas
+from entrenamiento.descargar import MARCA
+from entrenamiento.fuentes import FUENTES
+from entrenamiento.rutas import CRUDOS
+
+SALIDA = settings.ruta_modelos / "conteo"
+UMBRALES = [round(u, 2) for u in np.arange(0.1, 0.91, 0.05)]
+LADO = 1024
+
+
+def muestras(por_material: int) -> dict[str, list[tuple[Path, int]]]:
+    """(foto, cantidad real) por material, de las fuentes con piezas etiquetadas."""
+    rng = random.Random(7)
+    resultado: dict[str, list[tuple[Path, int]]] = defaultdict(list)
+    for fuente in FUENTES:
+        carpeta = CRUDOS / fuente.nombre
+        if not fuente.piezas or not (carpeta / MARCA).is_file():
+            continue
+        candidatas = []
+        for archivo in carpeta.rglob("_annotations.coco.json"):
+            coco = json.loads(archivo.read_text(encoding="utf-8"))
+            ids_pieza = {
+                c["id"] for c in coco["categories"] if re.search(fuente.piezas, c["name"], re.I)
+            }
+            cuenta = defaultdict(int)
+            for a in coco["annotations"]:
+                if a["category_id"] in ids_pieza:
+                    cuenta[a["image_id"]] += 1
+            for img in coco["images"]:
+                ruta = archivo.parent / img["file_name"]
+                # Variantes aumentadas de Roboflow fuera: solo una por foto original.
+                if ruta.is_file() and ".rf." in ruta.name and 1 <= cuenta[img["id"]] <= 40:
+                    candidatas.append((ruta, cuenta[img["id"]]))
+        vistas: set[str] = set()
+        unicas = []
+        for ruta, n in candidatas:
+            clave = ruta.name.split(".rf.")[0]
+            if clave not in vistas:
+                vistas.add(clave)
+                unicas.append((ruta, n))
+        rng.shuffle(unicas)
+        # Las fuentes por recortes no tienen `material`: se usa el de sus recortes.
+        materiales = {fuente.material} if fuente.material else set(fuente.recortes.values())
+        if len(materiales) != 1:
+            raise SystemExit(f"{fuente.nombre}: las piezas deben ser de un solo material")
+        resultado[materiales.pop()] += unicas
+    return {m: lista[:por_material] for m, lista in resultado.items()}
+
+
+def main(por_material: int) -> None:
+    SALIDA.mkdir(parents=True, exist_ok=True)
+    datos = muestras(por_material)
+    if not datos:
+        raise SystemExit("No hay fuentes de conteo descargadas (Fuente.piezas).")
+    contador = ContadorSam3(settings.conteo_modelo, settings.ruta_modelos, umbral=0.1)
+
+    detecciones: dict[str, list[tuple[int, list[Pieza]]]] = defaultdict(list)
+    tiempos = []
+    for material, lista in datos.items():
+        consultas = MATERIAL_POR_CODIGO[material].consultas_conteo
+        for i, (ruta, real) in enumerate(lista, 1):
+            with Image.open(ruta) as original:
+                imagen = ImageOps.exif_transpose(original).convert("RGB")
+            imagen.thumbnail((LADO, LADO))
+            inicio = time.time()
+            piezas = contador.detectar(imagen, consultas)
+            tiempos.append(time.time() - inicio)
+            detecciones[material].append((real, piezas))
+            print(
+                f"{material} {i}/{len(lista)}: real {real}, detectadas (≥0.1) {len(piezas)}",
+                flush=True,
+            )
+
+    def errores(umbral: float, material: str | None = None) -> np.ndarray:
+        filas = [
+            abs(len(filtrar_piezas([p for p in piezas if p.confianza >= umbral])) - real)
+            for m, lista in detecciones.items()
+            if material in (None, m)
+            for real, piezas in lista
+        ]
+        return np.array(filas)
+
+    mejor = min(UMBRALES, key=lambda u: errores(u).mean())
+    lineas = [
+        "# Evaluación del conteo (SAM 3, sin entrenar)",
+        "",
+        f"- Fotos: {sum(len(v) for v in detecciones.values())} · Tiempo medio por foto (CPU): {np.mean(tiempos):.1f} s",
+        f"- **Umbral elegido: {mejor}** (menor error medio)",
+        "",
+        "| Material | Fotos | Error medio (piezas) | Exacto | ±1 pieza |",
+        "|---|---|---|---|---|",
+    ]
+    for material in [*detecciones, None]:
+        e = errores(mejor, material)
+        nombre = material or "**Total**"
+        lineas.append(
+            f"| {nombre} | {len(e)} | {e.mean():.2f} | {(e == 0).mean():.0%} | {(e <= 1).mean():.0%} |"
+        )
+    lineas += ["", "Error medio según el umbral:", "", "| Umbral | Error medio |", "|---|---|"]
+    lineas += [f"| {u} | {errores(u).mean():.2f} |" for u in UMBRALES]
+    informe = "\n".join(lineas) + "\n"
+    (SALIDA / "informe.md").write_text(informe, encoding="utf-8")
+    (SALIDA / "umbral.json").write_text(json.dumps({"umbral": mejor}), encoding="utf-8")
+    print("\n" + informe)
+
+
+if __name__ == "__main__":
+    main(int(sys.argv[1]) if len(sys.argv) > 1 else 25)

entrenamiento/fuentes.py

@@ -0,0 +1,311 @@
+"""Catálogo de datasets públicos usados para entrenar y evaluar.
+
+Solo se incluyen datasets cuya licencia permite uso comercial (MIT, CC0, CC BY 4.0...).
+La licencia se vuelve a comprobar al descargar (Roboflow, Kaggle) y la fuente se descarta
+si no es compatible. Para buscar más: `python -m entrenamiento.buscar_roboflow --todo`.
+
+Tres formas de aprovechar un dataset:
+- Material por carpetas (`clases`): carpeta/clase → material. Foto entera.
+- Material por recortes (`recortes`): datasets de detección donde cada recuadro es un
+  objeto (botella, caja, lata...). Cada objeto se recorta y se usa como una foto de ese
+  material; así un dataset de escenas con varios objetos da muchas fotos limpias.
+- Defectos (`material` fijo): cada imagen trae las clases de defecto que contiene. Las
+  clases se traducen con mapeo.defectos_de_clase. Para los defectos que el dataset sí
+  etiqueta, una imagen sin esa etiqueta cuenta como "no lo tiene"; los demás defectos
+  quedan como "desconocidos" y no se entrenan con ella.
+Además, `piezas` marca los datasets cuyos recuadros son piezas contables: sirven para medir
+el conteo de SAM 3 (evaluar_conteo.py).
+"""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+Origen = Literal["hf", "url", "kaggle", "roboflow"]
+
+# Licencias aceptadas (en minúsculas, por subcadena). Se excluye todo lo "NC" (no
+# comercial), "other", "unknown" y las que reservan los derechos de las fotos.
+LICENCIAS_COMERCIALES = (
+    "mit",
+    "cc0",
+    "public domain",
+    "cc by 4.0",
+    "cc-by-4.0",
+    "apache",
+    "odbl",
+)
+
+
+@dataclass(frozen=True)
+class Fuente:
+    nombre: str
+    origen: Origen
+    ref: str  # repo de HF, URL, slug de Kaggle o "workspace/proyecto" de Roboflow
+    licencia: str
+    web: str
+    # Material por carpetas: carpeta/clase → código de material (None = descartar la clase).
+    clases: dict[str, str | None] = field(default_factory=dict)
+    # Material por recortes: expresión regular sobre el nombre de la clase → material.
+    recortes: dict[str, str] = field(default_factory=dict)
+    # Defectos: material de todas sus imágenes (también se usa para evaluar el estado).
+    material: str | None = None
+    usar_para_material: bool = True
+    # Defectos que se pueden dar por ausentes en todo el dataset (fotos de objetos limpios).
+    defectos_ausentes: tuple[str, ...] = ()
+    max_por_clase: int = 1500
+    archivo: str | None = None  # archivo concreto dentro del repo de HF
+    # Expresión regular de las clases que son piezas contables (para evaluar el conteo).
+    piezas: str | None = None
+    # False si el dataset solo sirve para evaluar el conteo (no para entrenar).
+    entrenar: bool = True
+
+    @property
+    def es_de_defectos(self) -> bool:
+        return not self.clases and not self.recortes
+
+
+# ------------------------------------------------------------------- material por carpetas
+
+TRASHNET = Fuente(
+    nombre="trashnet",
+    origen="hf",
+    ref="garythung/trashnet",
+    archivo="dataset-resized.zip",
+    licencia="MIT",
+    web="https://huggingface.co/datasets/garythung/trashnet",
+    clases={
+        "cardboard": "carton",
+        "glass": "vidrio",
+        "metal": "metal",
+        "paper": "papel",
+        "plastic": "plastico",
+        "trash": "otro",
+    },
+    # Objetos limpios fotografiados sobre fondo blanco.
+    defectos_ausentes=("oxido", "podredumbre"),
+)
+
+REALWASTE = Fuente(
+    nombre="realwaste",
+    origen="url",
+    ref="https://archive.ics.uci.edu/static/public/908/realwaste.zip",
+    licencia="CC BY 4.0",
+    web="https://archive.ics.uci.edu/dataset/908/realwaste",
+    clases={
+        "cardboard": "carton",
+        "food organics": None,
+        "glass": "vidrio",
+        "metal": "metal",
+        "miscellaneous trash": "otro",
+        "paper": "papel",
+        "plastic": "plastico",
+        "textile trash": "tela",
+        "vegetation": None,
+    },
+)
+
+# Nota: "mostafaabla/garbage-classification" (Kaggle) se descartó: su licencia ODbL cubre la
+# base de datos, pero las fotos son "© de sus autores" (recogidas de internet, sin fines de lucro).
+GARBAGE_V2 = Fuente(
+    nombre="garbage-v2",
+    origen="kaggle",
+    ref="sumn2u/garbage-classification-v2",
+    licencia="(se comprueba al descargar)",
+    web="https://www.kaggle.com/datasets/sumn2u/garbage-classification-v2",
+    clases={
+        "battery": "otro",
+        "biological": None,
+        "cardboard": "carton",
+        "clothes": "tela",
+        "glass": "vidrio",
+        "metal": "metal",
+        "paper": "papel",
+        "plastic": "plastico",
+        "shoes": "otro",
+        "trash": "otro",
+    },
+    max_por_clase=1200,
+)
+
+
+def _rf(nombre: str, ref: str, material: str | None = None, **extra) -> Fuente:
+    return Fuente(
+        nombre=nombre,
+        origen="roboflow",
+        ref=ref,
+        licencia="(se comprueba al descargar)",
+        web=f"https://universe.roboflow.com/{ref}",
+        material=material,
+        **extra,
+    )
+
+
+# ------------------------------------------------------------------- material por recortes
+
+RECORTES = (
+    _rf(
+        "rf-cajas-carton",
+        "ece4191-xcxot/cardboard-box-detection-mxqjh",
+        recortes={r"box": "carton"},
+        piezas=r"box",
+    ),
+    _rf(
+        "rf-plastico-residuos",
+        "edwin-daza-saavedra-s-workspace/plastic-waste-ag4eg",
+        recortes={r"plastic": "plastico"},
+        piezas=r"plastic bottle|plastic cup",
+    ),
+    _rf(
+        "rf-botellas-plastico",
+        "fyp-li8zz/plastic-bottle-2.0",
+        recortes={r"bottle": "plastico"},
+        piezas=r"bottle",
+    ),
+    _rf(
+        "rf-frascos-vidrio",
+        "gdp27/glass-jars",
+        recortes={r"jar|glass": "vidrio"},
+        piezas=r"jar",
+    ),
+    _rf(
+        "rf-vidrio-residuos",
+        "waste-seregation/glass-detection-1jobo",
+        recortes={r"glass": "vidrio"},
+        piezas=r"glass",
+    ),
+    _rf("rf-latas", "albaath2/can-o9wiu", recortes={r"metal": "metal"}, piezas=r"metal"),
+    _rf("rf-tubos", "john-tai-fa0rl/pipe-detector3", recortes={r"pipe": "metal"}, piezas=r"pipe"),
+    _rf(
+        "rf-chatarra",
+        "moses-orjyo/steel-scrap-sowop",
+        recortes={r"scrap|steel|rebar": "metal"},
+    ),
+    _rf("rf-papel", "trashdetection-bhjmn/paper-2jpbv", recortes={r"paper": "papel"}),
+    _rf(
+        "rf-papel-periodico",
+        "mmt-kcsv2/paper-nitaa",
+        recortes={r"^newspaper$|^paper$": "papel", r"cardboard": "carton"},
+    ),
+    _rf(
+        "rf-materiales-mixtos",
+        "material-identification/cardboard-1hdgz",
+        recortes={
+            r"^cardboard$": "carton",
+            r"^metal$": "metal",
+            r"^paper$": "papel",
+            r"^plastic$": "plastico",
+            r"^glass$": "vidrio",
+        },
+    ),
+    _rf(
+        "rf-ropa",
+        "grad-proj-nakmt/clothes-liagy",
+        recortes={r"dress|outwear|shirt|shorts|trousers|skirt|vest|sling": "tela"},
+        piezas=r"dress|outwear|shirt|shorts|trousers|skirt|vest|sling",
+    ),
+    _rf(
+        "rf-tablas-madera",
+        "davids-workspace-rc8oh/lumber-board-ident",
+        recortes={r"wood|lumber": "madera"},
+        piezas=r"wood|lumber",
+    ),
+    _rf(
+        "rf-residuos-electronicos",
+        "mehmet-wswds/e-waste-qmxtt",
+        recortes={r"battery|keyboard|laptop|phone|monitor|mouse|printer|electronic": "otro"},
+    ),
+)
+
+# ---------------------------------------------------------------------------- defectos
+
+# Madera: material (tablas, estibas, contrachapado) y defectos (grietas, nudos, manchas).
+MADERA = (
+    _rf(
+        "rf-madera-tablas",
+        "masood/wood-w4h97",
+        "madera",
+        piezas=r"plank|timber|plywood|pallet|wood",
+    ),
+    _rf("rf-madera-planchas", "rolos/wood_plank_final-69kb7", "madera"),
+    _rf("rf-madera-estibas", "pallets-dzqdc/only-wood", "madera"),
+    _rf("rf-madera-defectos-kodytek", "tim-4ijf0/wood-surface-defect-detection", "madera"),
+    _rf("rf-madera-defectos-11", "alima-aife2/wood-defect-detection-dxzor", "madera"),
+    _rf("rf-madera-defectos-5", "detect-detect/new-defects-in-wood", "madera"),
+    _rf("rf-madera-defectos-10k", "ye-csex5/wood-defect-o06zb", "madera"),
+    _rf(
+        "rf-madera-defectos-tarumt",
+        "tunku-abdul-rahman-university-of-management-and-technology-ttt1n/wood-defects-8lcdv",
+        "madera",
+    ),
+    _rf("rf-madera-sana", "school-mys25/wood-7ao2p", "madera"),
+    _rf("rf-madera-estibas-agujeros", "deep-learning-exxwi/wood-pallet-deep-learning", "madera"),
+)
+
+# Metal: óxido; abolladuras, rayones y agujeros (carrocerías: solo para defectos).
+METAL = (
+    _rf("rf-oxido-1", "qp-55vgp/rust-2-qtreu", "metal"),
+    _rf("rf-oxido-2", "personal-iisqb/rust-detection-xj8bu", "metal"),
+    _rf("rf-oxido-3", "workspacesteijn/rust-hbbwg", "metal"),
+    _rf("rf-oxido-niveles", "zenil/rust-detection-4cr1b", "metal"),
+    _rf("rf-metal-superficie", "university-of-bristol-kxv0a/metal-surface-7ng08", "metal"),
+    _rf(
+        "rf-metal-superficie-2",
+        "vision-oi1kw/metal-surface-defect-detection-n7x0l",
+        "metal",
+    ),
+    _rf("rf-abolladuras-1", "mesors-workspace/dent-ggvqt", "metal", usar_para_material=False),
+    _rf(
+        "rf-abolladuras-2",
+        "roboflow-demo/car-dents-and-scratches",
+        "metal",
+        usar_para_material=False,
+    ),
+)
+
+# Tela: agujeros, manchas, arrugas.
+TELA = (
+    _rf("rf-tela-defectos-1", "fabric-defect-detection-jq7gf/fabric-defect-detection-v2", "tela"),
+    _rf("rf-tela-defectos-3", "datasetannot/fabric-defect-detection-lfyix", "tela"),
+    _rf(
+        "rf-tela-agujeros", "textile-defect-detection-plje9/textile-defect-detection-yvgmo", "tela"
+    ),
+    _rf("rf-tela-agujeros-manchas", "iicl-31hjn/textile-ofqd1", "tela"),
+    _rf("rf-tela-manchas-arrugas", "zco/textile-defect-detection-ixt2r", "tela"),
+)
+
+# Cartón: cajas dañadas (aplastadas, rotas, mojadas) y en buen estado.
+CARTON = (
+    _rf("rf-cajas-1", "bekarys0504-gmail-com/damaged_box", "carton"),
+    _rf("rf-cajas-3", "project-33xgh/damaged-box-auh4b", "carton"),
+    _rf("rf-cajas-4", "robot-arm-xlohb/boxcondition", "carton"),
+    _rf("rf-cajas-5", "project-33xgh/damaged-box-detection", "carton"),
+)
+
+# Vidrio: roto o agrietado y en buen estado.
+VIDRIO = (
+    _rf("rf-vidrio-1", "focus/detect_broken_glass", "vidrio"),
+    _rf("rf-vidrio-2", "nhabduls-workspace/cracked-glass-detection", "vidrio"),
+    _rf("rf-vidrio-3", "glassdefectsdetection/glassdefectscheckingmodel", "vidrio"),
+)
+
+FUENTES: tuple[Fuente, ...] = (
+    TRASHNET,
+    REALWASTE,
+    GARBAGE_V2,
+    *RECORTES,
+    *MADERA,
+    *METAL,
+    *TELA,
+    *CARTON,
+    *VIDRIO,
+)
+
+
+def licencia_comercial(licencia: str) -> bool:
+    texto = licencia.lower()
+    no_comercial = "-nc" in texto or " nc" in texto or "noncommercial" in texto
+    derechos_reservados = "©" in texto or "original authors" in texto
+    return (
+        any(lic in texto for lic in LICENCIAS_COMERCIALES)
+        and not no_comercial
+        and not derechos_reservados
+    )

entrenamiento/hf_sync.py

@@ -0,0 +1,32 @@
+import sys
+from huggingface_hub import snapshot_download, upload_folder
+
+REPO = "EagleDev-Innovation/Modelos-EagleDev-Innovation"
+CARPETA = "modelos_entrenados"
+
+def bajar():
+    snapshot_download(
+        repo_id=REPO,
+        repo_type="model",
+        allow_patterns=f"{CARPETA}/**",
+        local_dir=".",
+    )
+    print("Modelos descargados en", CARPETA)
+
+def subir(mensaje):
+    upload_folder(
+        repo_id=REPO,
+        repo_type="model",
+        folder_path=CARPETA,
+        path_in_repo=CARPETA,
+        commit_message=mensaje,
+        ignore_patterns=[".locks/**", ".cache/**", "__pycache__/**", "*.tmp"],
+    )
+    print("Cambios subidos")
+
+if __name__ == "__main__":
+    accion = sys.argv[1]
+    if accion == "bajar":
+        bajar()
+    elif accion == "subir":
+        subir(sys.argv[2] if len(sys.argv) > 2 else "Actualizar modelos")

entrenamiento/hf_sync_datos.py

@@ -0,0 +1,28 @@
+import sys
+from huggingface_hub import snapshot_download, upload_folder
+
+REPO = "EagleDev-Innovation/Modelos-EagleDev-Innovation"
+PATRONES = [
+    "entrenamiento/*.py", "entrenamiento/*.md", "entrenamiento/*.ipynb",
+    "datos/peso/*.csv",
+    "datos/externos/emma_mat.csv",
+    "datos/externos/emma_clip.*",
+]
+
+def bajar():
+    snapshot_download(repo_id=REPO, repo_type="model",
+                      allow_patterns=PATRONES, local_dir=".")
+    print("Código y datos descargados")
+
+def subir(mensaje):
+    upload_folder(repo_id=REPO, repo_type="model", folder_path=".",
+                  allow_patterns=PATRONES,
+                  ignore_patterns=[".venv/**", "**/__pycache__/**"],
+                  commit_message=mensaje)
+    print("Código y datos subidos")
+
+if __name__ == "__main__":
+    if sys.argv[1] == "bajar":
+        bajar()
+    elif sys.argv[1] == "subir":
+        subir(sys.argv[2] if len(sys.argv) > 2 else "Actualizar código y datos")

entrenamiento/importar_emma.py

@@ -0,0 +1,59 @@
+import pickle, zlib
+import numpy as np
+import pandas as pd
+
+RUTA = "datos/externos/EMMa_v1.1.fdd"
+SALIDA = "datos/externos/emma_peso.csv"
+IN_A_CM = 2.54      # supongo dimensiones en pulgadas
+KG_A_G = 1000       # supongo masa en kg
+
+f = open(RUTA, "rb")
+f.seek(-8, 2)
+n = int.from_bytes(f.read(8), "little")
+f.seek(-(8 + n), 2)
+idx = pickle.loads(f.read(n))
+items = sorted(idx.items(), key=lambda kv: kv[1][0])  # lectura secuencial
+print("Registros:", len(items))
+
+def leer(ini, largo):
+    f.seek(ini)
+    b = f.read(largo)
+    try:
+        return pickle.loads(b)
+    except Exception:
+        return pickle.loads(zlib.decompress(b))
+
+filas = []
+for i, (asin, (ini, largo)) in enumerate(items):
+    if i % 200000 == 0:
+        print(i, "leidos,", len(filas), "validos")
+    try:
+        r = leer(ini, largo)
+    except Exception:
+        continue
+    mass = r.get("mass")
+    dims = r.get("dimensions")
+    if not mass or not dims or len(dims) != 1 or r.get("quantity", 1) != 1:
+        continue
+    d = sorted(dims[0], reverse=True)
+    a, b = d[0] * IN_A_CM, d[1] * IN_A_CM
+    mat = r.get("materials")
+    material = f"emma_{int(np.argmax(mat))}" if mat is not None else "desconocido"
+    filas.append({
+        "foto": "externo",
+        "sesion": "externo",
+        "tipo_objeto": "externo",
+        "material": material,
+        "n_piezas": 1,
+        "area_cm2_total": a * b,
+        "largo_cm_medio": a,
+        "ancho_cm_medio": b,
+        "largo_cm_max": a,
+        "peso_real_g": mass * KG_A_G,
+    })
+
+df = pd.DataFrame(filas)
+df = df[(df.peso_real_g > 1) & (df.peso_real_g < 50000) & (df.largo_cm_medio > 0) & (df.ancho_cm_medio > 0)]
+df.to_csv(SALIDA, index=False)
+print("Filas guardadas:", len(df), "->", SALIDA)
+print(df.describe())

entrenamiento/importar_emma_mat.py

@@ -0,0 +1,73 @@
+import pickle, zlib, re
+import numpy as np
+import pandas as pd
+
+RUTA = "datos/externos/EMMa_v1.1.fdd"
+SALIDA = "datos/externos/emma_mat.csv"
+IN_A_CM, KG_A_G = 2.54, 1000
+
+CLAVES = {
+    "metal": ["steel", "stainless", "iron", "aluminum", "aluminium", "brass", "copper", "metal"],
+    "plastico": ["plastic", "pvc", "abs", "acrylic", "silicone", "rubber"],
+    "madera": ["wood", "wooden", "bamboo", "oak", "pine", "plywood"],
+    "vidrio": ["glass"],
+    "ceramica": ["ceramic", "porcelain", "stoneware"],
+    "carton": ["cardboard", "paper", "kraft"],
+    "tela": ["cotton", "fabric", "leather", "polyester", "canvas", "wool"],
+}
+
+def material_de(texto):
+    t = texto.lower()
+    hits = {m: sum(len(re.findall(r"\b" + k + r"\b", t)) for k in ks) for m, ks in CLAVES.items()}
+    hits = {m: h for m, h in hits.items() if h > 0}
+    if len(hits) != 1:
+        return None
+    return next(iter(hits))
+
+f = open(RUTA, "rb")
+f.seek(-8, 2)
+n = int.from_bytes(f.read(8), "little")
+f.seek(-(8 + n), 2)
+idx = pickle.loads(f.read(n))
+items = sorted(idx.items(), key=lambda kv: kv[1][0])
+
+def leer(ini, largo):
+    f.seek(ini)
+    b = f.read(largo)
+    try:
+        return pickle.loads(b)
+    except Exception:
+        return pickle.loads(zlib.decompress(b))
+
+filas = []
+for i, (asin, (ini, largo)) in enumerate(items):
+    if i % 200000 == 0:
+        print(i, "leidos,", len(filas), "validos")
+    try:
+        r = leer(ini, largo)
+    except Exception:
+        continue
+    mass, dims = r.get("mass"), r.get("dimensions")
+    if not mass or not dims or len(dims) != 1 or r.get("quantity", 1) != 1:
+        continue
+    texto = str(r.get("title", "")) + " " + " ".join(map(str, r.get("features") or []))
+    mat = material_de(texto)
+    if mat is None:
+        continue
+    d = sorted(dims[0], reverse=True)
+    a, b = d[0] * IN_A_CM, d[1] * IN_A_CM
+    if not (1 <= a <= 150 and 0.5 <= b <= 150 and d[2] * IN_A_CM >= 0.1):
+        continue
+    peso = mass * KG_A_G
+    if not (5 <= peso <= 30000):
+        continue
+    filas.append({"material": mat, "n_piezas": 1, "area_cm2_total": a * b,
+                  "largo_cm_medio": a, "ancho_cm_medio": b, "largo_cm_max": a,
+                  "espesor_cm": d[2] * IN_A_CM, "peso_real_g": peso})
+
+df = pd.DataFrame(filas)
+df.to_csv(SALIDA, index=False)
+print("Filas:", len(df))
+print(df.material.value_counts())
+print(df.groupby("material").peso_real_g.median())
+

entrenamiento/importar_externos.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+import numpy as np
+import pandas as pd
+
+ENTRADA = Path("datos/externos")
+SALIDA = Path("datos/peso/externo.csv")
+
+# EDITA ESTO tras la primera ejecución, cuando veas los nombres de columnas
+COL = {"peso": None, "largo": None, "ancho": None, "material": None}
+A_GRAMOS = 1.0   # libras = 453.592 | kg = 1000 | gramos = 1
+A_CM = 1.0       # pulgadas = 2.54 | cm = 1
+
+def leer(p):
+    s = p.suffix.lower()
+    if s == ".parquet":
+        return pd.read_parquet(p)
+    if s == ".csv":
+        return pd.read_csv(p)
+    if s in (".json", ".jsonl"):
+        return pd.read_json(p, lines=(s == ".jsonl"))
+    return None
+
+tablas = []
+for p in sorted(ENTRADA.rglob("*")):
+    if p.is_file():
+        t = leer(p)
+        if t is not None:
+            print("Leído:", p, t.shape)
+            tablas.append(t)
+if not tablas:
+    raise SystemExit("No hay archivos .csv/.parquet/.json en datos/externos")
+
+df = pd.concat(tablas, ignore_index=True)
+if not all(COL.values()):
+    print("\nColumnas disponibles:", list(df.columns))
+    print(df.head(3).T)
+    raise SystemExit("\nEdita COL (y las unidades) en este script y vuelve a ejecutarlo.")
+
+def primero(v):
+    if isinstance(v, str):
+        return v.lower()
+    if hasattr(v, "__len__") and len(v) > 0:
+        return str(v[0]).lower()
+    return "otro"
+
+peso = pd.to_numeric(df[COL["peso"]], errors="coerce") * A_GRAMOS
+a = pd.to_numeric(df[COL["largo"]], errors="coerce") * A_CM
+b = pd.to_numeric(df[COL["ancho"]], errors="coerce") * A_CM
+out = pd.DataFrame({
+    "foto": "externo",
+    "sesion": "externo",
+    "tipo_objeto": "externo",
+    "material": df[COL["material"]].apply(primero),
+    "n_piezas": 1,
+    "area_cm2_total": a * b,
+    "largo_cm_medio": np.maximum(a, b),
+    "ancho_cm_medio": np.minimum(a, b),
+    "largo_cm_max": np.maximum(a, b),
+    "peso_real_g": peso,
+}).replace([np.inf, -np.inf], np.nan).dropna()
+out = out[(out.peso_real_g > 0) & (out.largo_cm_medio > 0) & (out.ancho_cm_medio > 0)]
+out.to_csv(SALIDA, index=False)
+print("Filas guardadas:", len(out), "->", SALIDA)

entrenamiento/indexar_emma.py

@@ -0,0 +1,53 @@
+import pickle, zlib, random
+import numpy as np
+import pandas as pd
+from sentence_transformers import SentenceTransformer
+
+RUTA = "datos/externos/EMMa_v1.1.fdd"
+N = 150000
+
+f = open(RUTA, "rb")
+f.seek(-8, 2)
+n = int.from_bytes(f.read(8), "little")
+f.seek(-(8 + n), 2)
+idx = pickle.loads(f.read(n))
+items = list(idx.items())
+random.seed(0)
+items = sorted(random.sample(items, 600000), key=lambda kv: kv[1][0])
+
+def leer(ini, largo):
+    f.seek(ini)
+    b = f.read(largo)
+    try:
+        return pickle.loads(b)
+    except Exception:
+        return pickle.loads(zlib.decompress(b))
+
+filas = []
+for asin, (ini, largo) in items:
+    try:
+        r = leer(ini, largo)
+    except Exception:
+        continue
+    mass, title = r.get("mass"), str(r.get("title", "")).strip()
+    if not mass or not title or r.get("quantity", 1) != 1:
+        continue
+    peso = mass * 1000
+    if not (5 <= peso <= 30000):
+        continue
+    dims = r.get("dimensions")
+    d = ""
+    if dims and len(dims) == 1:
+        d = " x ".join(f"{x * 2.54:.1f}" for x in sorted(dims[0], reverse=True))
+    filas.append({"asin": asin, "title": title, "peso_g": peso, "dims_cm": d})
+    if len(filas) >= N:
+        break
+
+df = pd.DataFrame(filas)
+print("Productos:", len(df))
+model = SentenceTransformer("clip-ViT-B-32")
+emb = model.encode(df["title"].tolist(), batch_size=256, show_progress_bar=True,
+                   normalize_embeddings=True, convert_to_numpy=True)
+np.save("datos/externos/emma_clip.npy", emb.astype("float16"))
+df.to_csv("datos/externos/emma_clip.csv", index=False)
+print("Listo")

entrenamiento/limpiar_emma.py

@@ -0,0 +1,15 @@
+import pandas as pd, numpy as np
+
+RUTA = "datos/externos/emma_peso.csv"
+df = pd.read_csv(RUTA)
+print("Antes:", len(df))
+
+df = df.replace([np.inf, -np.inf], np.nan).dropna()
+df = df[(df.largo_cm_medio >= 1) & (df.largo_cm_medio <= 150)]
+df = df[(df.ancho_cm_medio >= 0.5) & (df.ancho_cm_medio <= 150)]
+df = df[(df.peso_real_g >= 5) & (df.peso_real_g <= 30000)]
+df["area_cm2_total"] = df.largo_cm_medio * df.ancho_cm_medio
+
+print("Después:", len(df))
+print(df.describe())
+df.to_csv(RUTA, index=False)

entrenamiento/mapeo.py

@@ -0,0 +1,58 @@
+"""Traduce las etiquetas de cada dataset a nuestros defectos.
+
+Cada dataset nombra sus clases a su manera ("Dead_Knot", "rust", "damaged", "Normal_Glass").
+Aquí se convierten en los códigos de app/ml/estado/defectos.py, o en LIMPIO si la clase
+indica que la pieza está en buen estado. Las clases que no se reconocen se ignoran.
+"""
+
+import re
+
+LIMPIO = "__limpio__"
+
+# Clases que significan "sin defecto". Se comparan con el nombre entero (normalizado).
+_SIN_DEFECTO = re.compile(
+    r"^(no ?defects?|non ?damaged|not ?damaged|undamaged( ?packages?)?|normal( ?glass)?|"
+    r"good( ?box)?|ok|intact|defect ?free|clean|perfect|without ?defects?|sound|healthy)$"
+)
+
+# "car no damage", "without defects"... en cualquier parte del nombre.
+_NEGACION = re.compile(r"\b(no|non|not|without) ?(damages?|damaged|defects?|defective)\b")
+
+# Una clase puede activar varios defectos ("knot with crack" → nudo + grieta).
+# \b = límite de palabra: "ink" no debe activarse con "wrinkle", ni "rot" con "protection".
+_REGLAS: tuple[tuple[re.Pattern[str], str], ...] = tuple(
+    (re.compile(patron), defecto)
+    for patron, defecto in (
+        (r"crack|fissure|fracture|\bsplit|\bchecks?\b|\bchecked\b|cassure", "grieta"),
+        (
+            r"broken|\bholes?\b|\btear\b|\btorn\b|\bripped\b|\brip\b|puncture|shatter|"
+            r"missing|\bcut\b",
+            "rotura",
+        ),
+        (r"\brust|corros|oxid|pitting", "oxido"),
+        (
+            r"stain|\bspots?\b|\bspot\b|discolou?r|\bdirt|\bresin\b|\boil\b|\bink\b|\btache\b",
+            "mancha",
+        ),
+        (
+            r"\brot\b|\brotten\b|\brotting\b|\bmou?ld|\bfung|\bdecay|\bwet\b|moist|water damage",
+            "podredumbre",
+        ),
+        (r"\bdent|crush|deform|\bbent\b|wrinkl|crease|bulg|damage", "deformacion"),
+        (r"scratch|abrasion|scuff|\bwear\b|\bpeel", "rayon"),
+        (r"\bknots?\b", "nudo"),
+    )
+)
+
+
+def normalizar(nombre: str) -> str:
+    """Minúsculas y palabras separadas por un espacio: "Dead_Knot" → "dead knot"."""
+    return re.sub(r"[^a-z0-9]+", " ", nombre.lower()).strip()
+
+
+def defectos_de_clase(nombre: str) -> set[str]:
+    """Defectos que indica una clase (vacío si no se reconoce). Puede devolver {LIMPIO}."""
+    texto = normalizar(nombre)
+    if _SIN_DEFECTO.match(texto) or _NEGACION.search(texto):
+        return {LIMPIO}
+    return {defecto for patron, defecto in _REGLAS if patron.search(texto)}

entrenamiento/preparar.py

@@ -0,0 +1,347 @@
+"""Une las fuentes descargadas en un solo conjunto de datos.
+
+    uv run python -m entrenamiento.preparar
+
+1. Lee cada fuente descargada y traduce sus etiquetas a material y defectos.
+2. Quita imágenes repetidas (mismo contenido aunque vengan de fuentes distintas).
+3. Limita cuántas imágenes aporta cada clase de cada fuente y cada material, para que
+   ninguna domine el entrenamiento.
+4. Reparte en entrenamiento / validación / prueba (80/10/10) por "grupo": las variantes
+   aumentadas de una misma foto (Roboflow las nombra foto_jpg.rf.<hash>.jpg) quedan siempre
+   en el mismo lado, para que la evaluación no sea tramposa.
+5. Guarda una copia reducida (512 px) de cada imagen en datos/procesados/imagenes/ y el
+   listado en datos/procesados/manifiesto.jsonl.
+"""
+
+import hashlib
+import json
+import random
+import re
+from collections import Counter, defaultdict
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from PIL import Image, ImageOps
+
+from app.ml.estado.defectos import ORDEN_DEFECTOS
+from app.ml.materiales import ORDEN_MATERIALES
+from entrenamiento.descargar import MARCA
+from entrenamiento.fuentes import FUENTES, Fuente
+from entrenamiento.mapeo import LIMPIO, defectos_de_clase
+from entrenamiento.rutas import (
+    CRUDOS,
+    IMAGENES,
+    LADO_GUARDADO,
+    MANIFIESTO,
+    asegurar_carpetas,
+)
+
+EXTENSIONES = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}
+MAX_POR_MATERIAL = 4000
+SEMILLA = 2026
+Image.MAX_IMAGE_PIXELS = 60_000_000
+
+
+@dataclass
+class Registro:
+    fuente: str
+    ruta: str  # archivo original
+    material: str | None
+    # Solo los defectos conocidos: 1 = presente, 0 = ausente. Los que faltan, desconocidos.
+    defectos: dict[str, int] = field(default_factory=dict)
+    grupo: str = ""
+    id: str = ""
+    split: str = ""
+    # Recuadro (x1, y1, x2, y2) si el registro es un objeto recortado de una foto mayor.
+    recorte: list[int] | None = None
+
+    @property
+    def clave_cupo(self) -> str:
+        positivos = sorted(d for d, v in self.defectos.items() if v)
+        return f"{self.material}|{'+'.join(positivos) or ('limpio' if self.defectos else '-')}"
+
+
+def _norm(texto: str) -> str:
+    return re.sub(r"[\s_\-]+", " ", texto.lower()).strip()
+
+
+def _grupo(fuente: str, ruta: Path) -> str:
+    # Roboflow: "IMG_123_jpg.rf.abc123.jpg" → todas las variantes comparten "IMG_123_jpg".
+    return f"{fuente}/{ruta.name.split('.rf.')[0]}"
+
+
+def _imagenes(carpeta: Path):
+    for ruta in carpeta.rglob("*"):
+        if (
+            ruta.suffix.lower() in EXTENSIONES
+            and "__MACOSX" not in ruta.parts
+            and not ruta.name.startswith("._")
+        ):
+            yield ruta
+
+
+# ------------------------------------------------------------------------------ lectores
+
+
+def _leer_carpetas_material(fuente: Fuente, carpeta: Path) -> list[Registro]:
+    clases = {_norm(k): v for k, v in fuente.clases.items()}
+    ausentes = dict.fromkeys(fuente.defectos_ausentes, 0)
+    registros = []
+    for ruta in _imagenes(carpeta):
+        clase = next((_norm(p) for p in reversed(ruta.parts[:-1]) if _norm(p) in clases), None)
+        if clase is None or clases[clase] is None:
+            continue
+        registros.append(
+            Registro(
+                fuente.nombre, str(ruta), clases[clase], dict(ausentes), _grupo(fuente.nombre, ruta)
+            )
+        )
+    return registros
+
+
+def _defectos_conocidos(nombres_clase: list[str]) -> set[str]:
+    conocidos: set[str] = set()
+    for nombre in nombres_clase:
+        conocidos |= defectos_de_clase(nombre) - {LIMPIO}
+    return conocidos
+
+
+def _etiquetar(clases_imagen: set[str], conocidos: set[str]) -> dict[str, int]:
+    presentes: set[str] = set()
+    for nombre in clases_imagen:
+        presentes |= defectos_de_clase(nombre) - {LIMPIO}
+    return {d: int(d in presentes) for d in conocidos}
+
+
+def _leer_coco(fuente: Fuente, carpeta: Path) -> list[Registro]:
+    anotaciones = list(carpeta.rglob("_annotations.coco.json"))
+    categorias_todas: list[str] = []
+    datos = []
+    for archivo in anotaciones:
+        coco = json.loads(archivo.read_text(encoding="utf-8"))
+        categorias = {c["id"]: c["name"] for c in coco.get("categories", [])}
+        categorias_todas += list(categorias.values())
+        datos.append((archivo.parent, coco, categorias))
+    conocidos = _defectos_conocidos(categorias_todas)
+
+    registros = []
+    material = fuente.material if fuente.usar_para_material else None
+    for carpeta_split, coco, categorias in datos:
+        por_imagen: dict[int, set[str]] = defaultdict(set)
+        for anotacion in coco.get("annotations", []):
+            por_imagen[anotacion["image_id"]].add(categorias.get(anotacion["category_id"], ""))
+        for imagen in coco.get("images", []):
+            ruta = carpeta_split / imagen["file_name"]
+            if ruta.is_file():
+                registros.append(
+                    Registro(
+                        fuente.nombre,
+                        str(ruta),
+                        material,
+                        _etiquetar(por_imagen.get(imagen["id"], set()), conocidos),
+                        _grupo(fuente.nombre, ruta),
+                    )
+                )
+    return registros
+
+
+MAX_RECORTES_POR_IMAGEN = 2
+LADO_MINIMO_RECORTE = 48
+MARGEN_RECORTE = 0.1
+
+
+def _leer_recortes(fuente: Fuente, carpeta: Path) -> list[Registro]:
+    """Un registro por objeto etiquetado (los más grandes de cada foto), con su material."""
+    patrones = [(re.compile(p, re.I), m) for p, m in fuente.recortes.items()]
+    ausentes = dict.fromkeys(fuente.defectos_ausentes, 0)
+    registros = []
+    for archivo in carpeta.rglob("_annotations.coco.json"):
+        coco = json.loads(archivo.read_text(encoding="utf-8"))
+        material_de = {}
+        for c in coco.get("categories", []):
+            material_de[c["id"]] = next((m for p, m in patrones if p.search(c["name"])), None)
+        imagenes = {i["id"]: i for i in coco.get("images", [])}
+        por_imagen: dict[int, list[tuple[float, list[int], str]]] = defaultdict(list)
+        for a in coco.get("annotations", []):
+            material = material_de.get(a["category_id"])
+            imagen = imagenes.get(a["image_id"])
+            if material is None or imagen is None:
+                continue
+            x, y, w, h = a["bbox"]
+            if min(w, h) < LADO_MINIMO_RECORTE:
+                continue
+            mx, my = w * MARGEN_RECORTE, h * MARGEN_RECORTE
+            caja = [
+                max(0, int(x - mx)),
+                max(0, int(y - my)),
+                min(imagen["width"], int(x + w + mx)),
+                min(imagen["height"], int(y + h + my)),
+            ]
+            por_imagen[a["image_id"]].append((w * h, caja, material))
+        for id_imagen, objetos in por_imagen.items():
+            ruta = archivo.parent / imagenes[id_imagen]["file_name"]
+            if not ruta.is_file():
+                continue
+            for _, caja, material in sorted(objetos, reverse=True)[:MAX_RECORTES_POR_IMAGEN]:
+                registros.append(
+                    Registro(
+                        fuente.nombre,
+                        str(ruta),
+                        material,
+                        dict(ausentes),
+                        _grupo(fuente.nombre, ruta),
+                        recorte=caja,
+                    )
+                )
+    return registros
+
+
+def _leer_clasificacion_rf(fuente: Fuente, carpeta: Path) -> list[Registro]:
+    rutas = [r for r in _imagenes(carpeta)]
+    conocidos = _defectos_conocidos(sorted({r.parent.name for r in rutas}))
+    material = fuente.material if fuente.usar_para_material else None
+    registros = []
+    for ruta in rutas:
+        clase = ruta.parent.name
+        if not defectos_de_clase(clase) and conocidos:
+            continue  # clase que no dice nada del estado
+        registros.append(
+            Registro(
+                fuente.nombre,
+                str(ruta),
+                material,
+                _etiquetar({clase}, conocidos),
+                _grupo(fuente.nombre, ruta),
+            )
+        )
+    return registros
+
+
+def leer_fuente(fuente: Fuente) -> list[Registro]:
+    carpeta = CRUDOS / fuente.nombre
+    if not fuente.entrenar or not (carpeta / MARCA).is_file():
+        return []
+    if fuente.recortes:
+        return _leer_recortes(fuente, carpeta)
+    if fuente.clases:
+        return _leer_carpetas_material(fuente, carpeta)
+    if any(carpeta.rglob("_annotations.coco.json")):
+        return _leer_coco(fuente, carpeta)
+    return _leer_clasificacion_rf(fuente, carpeta)
+
+
+# ---------------------------------------------------------------------- limpieza y reparto
+
+
+def _limitar(
+    registros: list[Registro], fuentes: dict[str, Fuente], rng: random.Random
+) -> list[Registro]:
+    # 1) cupo por (fuente, material, tipo de defecto)
+    por_clave: dict[tuple[str, str], list[Registro]] = defaultdict(list)
+    for r in registros:
+        por_clave[(r.fuente, r.clave_cupo)].append(r)
+    elegidos: list[Registro] = []
+    for (fuente, _), lista in por_clave.items():
+        rng.shuffle(lista)
+        elegidos += lista[: fuentes[fuente].max_por_clase]
+
+    # 2) cupo por material: se priorizan las imágenes que también enseñan defectos
+    por_material: dict[str | None, list[Registro]] = defaultdict(list)
+    for r in elegidos:
+        por_material[r.material].append(r)
+    final: list[Registro] = []
+    for material, lista in por_material.items():
+        if material is None:
+            final += lista
+            continue
+        con_defectos = [r for r in lista if any(r.defectos.values()) or "limpio" in r.clave_cupo]
+        resto = [r for r in lista if r not in con_defectos]
+        rng.shuffle(con_defectos)
+        rng.shuffle(resto)
+        final += (con_defectos + resto)[:MAX_POR_MATERIAL]
+    return final
+
+
+def _split(grupo: str) -> str:
+    valor = int(hashlib.md5(grupo.encode()).hexdigest(), 16) % 100
+    return "entrenamiento" if valor < 80 else "validacion" if valor < 90 else "prueba"
+
+
+def _guardar_copia(registro: Registro) -> tuple[Registro, str | None]:
+    """Guarda la copia reducida. Devuelve (registro, huella del contenido) o None si falla."""
+    try:
+        with Image.open(registro.ruta) as original:
+            if registro.recorte:
+                # Las cajas de COCO se refieren a los píxeles tal como están guardados.
+                imagen = original.convert("RGB").crop(tuple(registro.recorte))
+            else:
+                imagen = ImageOps.exif_transpose(original).convert("RGB")
+        if min(imagen.size) < 32:
+            return registro, None
+        imagen.thumbnail((LADO_GUARDADO, LADO_GUARDADO), Image.Resampling.LANCZOS)
+        huella = hashlib.md5(imagen.resize((16, 16)).convert("L").tobytes()).hexdigest()
+        imagen.save(IMAGENES / f"{registro.id}.jpg", quality=92)
+        return registro, huella
+    except Exception:
+        return registro, None
+
+
+def main() -> None:
+    asegurar_carpetas()
+    rng = random.Random(SEMILLA)
+    fuentes = {f.nombre: f for f in FUENTES}
+
+    registros: list[Registro] = []
+    for fuente in FUENTES:
+        leidos = leer_fuente(fuente)
+        if leidos:
+            print(f"- {fuente.nombre}: {len(leidos)} imágenes")
+        registros += leidos
+    if not registros:
+        raise SystemExit(
+            "No hay fuentes descargadas. Ejecuta antes: python -m entrenamiento.descargar"
+        )
+
+    registros = _limitar(registros, fuentes, rng)
+    for r in registros:
+        r.id = hashlib.md5(f"{r.ruta}|{r.recorte}".encode()).hexdigest()[:16]
+        r.split = _split(r.grupo)
+
+    print(f"Guardando {len(registros)} copias reducidas en {IMAGENES} ...")
+    vistos: set[str] = set()
+    validos: list[Registro] = []
+    with ThreadPoolExecutor(max_workers=6) as pool:
+        for registro, huella in pool.map(_guardar_copia, registros):
+            if huella is None:
+                continue
+            if huella in vistos:  # misma imagen en dos fuentes o repetida
+                (IMAGENES / f"{registro.id}.jpg").unlink(missing_ok=True)
+                continue
+            vistos.add(huella)
+            validos.append(registro)
+
+    with MANIFIESTO.open("w", encoding="utf-8") as salida:
+        for r in sorted(validos, key=lambda r: r.id):
+            salida.write(json.dumps(asdict(r), ensure_ascii=False) + "\n")
+
+    print(f"\nManifiesto: {MANIFIESTO} ({len(validos)} imágenes)")
+    print("\nMaterial por reparto:")
+    tabla = Counter((r.material, r.split) for r in validos)
+    for material in (*ORDEN_MATERIALES, None):
+        print(
+            f"  {str(material):10} "
+            + "  ".join(
+                f"{s[:5]}={tabla[(material, s)]:5}"
+                for s in ("entrenamiento", "validacion", "prueba")
+            )
+        )
+    print("\nDefectos (positivos / conocidos):")
+    for d in ORDEN_DEFECTOS:
+        conocidos = sum(1 for r in validos if d in r.defectos)
+        positivos = sum(r.defectos.get(d, 0) for r in validos)
+        print(f"  {d:12} {positivos:5} / {conocidos:5}")
+
+
+if __name__ == "__main__":
+    main()

entrenamiento/probar_foto.py

@@ -0,0 +1,37 @@
+import sys
+import joblib
+import pandas as pd
+from pathlib import Path
+
+ruta, material = sys.argv[1], sys.argv[2]
+largo, ancho, espesor = map(float, sys.argv[3:6])
+n_piezas = int(sys.argv[6]) if len(sys.argv) > 6 else 1
+
+foto = Path(ruta)
+if not foto.exists():
+    sys.exit(f"No existe la foto: {foto}")
+try:
+    from PIL import Image
+    w, h = Image.open(foto).size
+    print(f"Foto: {foto.name} ({w}x{h} px)")
+except ImportError:
+    print(f"Foto encontrada: {foto.name}")
+
+M = joblib.load("modelos_entrenados/peso/lgbm_peso.joblib")
+modelo, columnas = M["modelo"], M["columnas"]
+
+area = largo * ancho
+fila = {
+    "area_pieza": area, "largo_cm_medio": largo, "ancho_cm_medio": ancho,
+    "largo_cm_max": largo * 1.01, "relacion": largo / ancho,
+    "espesor_cm": espesor, "volumen_cm3": area * espesor,
+}
+X = pd.DataFrame([fila])
+for c in columnas:
+    if c.startswith("material_"):
+        X[c] = 1.0 if c == f"material_{material}" else 0.0
+X = X.reindex(columns=columnas, fill_value=0.0)
+
+peso = float(modelo.predict(X)[0]) * n_piezas
+print(f"Material: {material} | {largo}x{ancho}x{espesor} cm | piezas: {n_piezas}")
+print(f"Peso estimado: {peso:.0f} g")

entrenamiento/probar_peso.py

@@ -0,0 +1,39 @@
+import sys
+import joblib
+import pandas as pd
+
+M = joblib.load("modelos_entrenados/peso/lgbm_peso.joblib")
+modelo, columnas = M["modelo"], M["columnas"]
+
+def predecir(material, largo, ancho, espesor, n_piezas=1):
+    area = largo * ancho
+    fila = {
+        "area_pieza": area, "largo_cm_medio": largo, "ancho_cm_medio": ancho,
+        "largo_cm_max": largo * 1.01, "relacion": largo / ancho,
+        "espesor_cm": espesor, "volumen_cm3": area * espesor,
+    }
+    X = pd.DataFrame([fila])
+    for c in columnas:
+        if c.startswith("material_"):
+            X[c] = 1.0 if c == f"material_{material}" else 0.0
+    X = X.reindex(columns=columnas, fill_value=0.0)
+    return float(modelo.predict(X)[0]) * n_piezas
+
+if len(sys.argv) >= 5:
+    mat, l, a, e = sys.argv[1], *map(float, sys.argv[2:5])
+    n = int(sys.argv[5]) if len(sys.argv) > 5 else 1
+    print(f"{mat} {l}x{a}x{e} cm, {n} pieza(s): {predecir(mat, l, a, e, n):.0f} g")
+else:
+    casos = [
+        ("metal", 100, 1.2, 1.2, 1, 888),     # tu barra de acero (peso real conocido)
+        ("metal", 100, 1.2, 1.2, 3, 2650),    # 3 barras
+        ("madera", 30, 20, 2, 1, None),
+        ("plastico", 20, 10, 5, 1, None),
+        ("carton", 40, 30, 20, 1, None),
+        ("vidrio", 20, 8, 8, 1, None),
+    ]
+    for mat, l, a, e, n, real in casos:
+        p = predecir(mat, l, a, e, n)
+        extra = f" | real: {real} g" if real else ""
+        print(f"{mat:9s} {l}x{a}x{e} cm x{n}: {p:7.0f} g{extra}")
+

entrenamiento/rutas.py

@@ -0,0 +1,62 @@
+"""Rutas y constantes del entrenamiento."""
+
+from pathlib import Path
+
+from app.core.config import BASE_DIR, settings
+
+DATOS = BASE_DIR / "datos"
+CRUDOS = DATOS / "crudos"  # descargas tal cual vienen de cada fuente
+PROCESADOS = DATOS / "procesados"
+IMAGENES = PROCESADOS / "imagenes"  # copias reducidas y normalizadas (JPEG)
+MANIFIESTO = PROCESADOS / "manifiesto.jsonl"
+CARACTERISTICAS = PROCESADOS / "caracteristicas"
+INFORME_FUENTES = PROCESADOS / "fuentes.json"
+
+SALIDA_MODELO = settings.ruta_material_estado
+
+# Backbone preentrenado (acceso restringido en Hugging Face: aceptar la licencia de DINOv3).
+BACKBONE = "facebook/dinov3-convnext-tiny-pretrain-lvd1689m"
+TAMANO_IMAGEN = 384
+# Lado máximo de las copias guardadas en IMAGENES (deja margen para recortes aleatorios).
+LADO_GUARDADO = 512
+
+
+def asegurar_carpetas() -> None:
+    for carpeta in (CRUDOS, IMAGENES, CARACTERISTICAS):
+        carpeta.mkdir(parents=True, exist_ok=True)
+
+
+def leer_env_local(nombre: str) -> str | None:
+    """Lee una variable del entorno o, en Windows, de las variables de usuario (setx)."""
+    import os
+
+    valor = os.environ.get(nombre)
+    if valor:
+        return valor
+    if os.name == "nt":
+        import winreg
+
+        try:
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as clave:
+                return str(winreg.QueryValueEx(clave, nombre)[0]) or None
+        except OSError:
+            return None
+    return None
+
+
+__all__ = [
+    "BACKBONE",
+    "CARACTERISTICAS",
+    "CRUDOS",
+    "DATOS",
+    "IMAGENES",
+    "INFORME_FUENTES",
+    "LADO_GUARDADO",
+    "MANIFIESTO",
+    "PROCESADOS",
+    "SALIDA_MODELO",
+    "TAMANO_IMAGEN",
+    "Path",
+    "asegurar_carpetas",
+    "leer_env_local",
+]

entrenamiento/splits_emma.py

@@ -0,0 +1,11 @@
+import sys
+from freeze_dried_data import RFDD
+
+try:
+    RFDD(sys.argv[1])
+except KeyError as e:
+    tb = e.__traceback__
+    while tb.tb_next:
+        tb = tb.tb_next
+    obj = tb.tb_frame.f_locals["self"]
+    print("Splits:", list(obj.split_to_index.keys()))

entrenamiento/ver_emma.py

@@ -0,0 +1,26 @@
+import sys, pickle, zlib
+f = open(sys.argv[1], "rb")
+f.seek(-8, 2)
+n = int.from_bytes(f.read(8), "little")
+f.seek(-(8 + n), 2)
+idx = pickle.loads(f.read(n))
+print("Registros:", len(idx))
+
+def leer(inicio, largo):
+    f.seek(inicio)
+    b = f.read(largo)
+    try:
+        return pickle.loads(b)
+    except Exception:
+        return pickle.loads(zlib.decompress(b))
+
+for i, (k, v) in enumerate(idx.items()):
+    print("\n--- asin:", k, "pos:", v)
+    r = leer(v[0], v[1])
+    if isinstance(r, dict):
+        for c, x in r.items():
+            print(f"{c}: {str(x)[:200]}")
+    else:
+        print(type(r), str(r)[:500])
+    if i >= 2:
+        break