Flamehaven Tensor-Canon v0.1.4 - validador ligero de Shape + Drift (MMD) para tensores de PyTorch/NumPy

Hola.
Esta semana comparto Flamehaven Tensor-Canon (v0.1.4).

---

Cuando desarrollas con PyTorch, siempre estás pendiente del shape de los tensores.
Por ejemplo, si la entrada es una imagen, normalmente tiene forma NCHW
(lote N, canal C, altura H, ancho W).

Pero en operación (producción), el problema de abajo da aún más miedo.

• El shape coincide, pero la distribución de los datos cambia silenciosamente
• El modelo sigue corriendo, pero el rendimiento/las métricas se deterioran poco a poco

Por eso creé Tensor-Canon no solo para hacer un “check de shape”, sino también para verificar de forma ligera y rápida si la distribución de entrada cambió.

---

Las herramientas existentes ya son potentes, pero cumplen roles distintos

• Einops
  Convierte/manipula shapes de forma intuitiva basada en cadenas
  → Está más optimizada para operaciones/transformaciones que para validación

• Jaxtyping
  Validación basada en type hints (amigable con el IDE)
  → Pero la sintaxis de genéricos en Python puede volverse larga fácilmente

• Torchtyping
  Validación ligera de shape
  → Su alcance está centrado en el shape

• Pydantic
  El estándar para validación de datos generales
  → Pero para validar arreglos multidimensionales como tensores puede resultar algo pesado y engorroso

---

Pero Flamehaven Tensor-Canon se diferencia por sus “guardrails de entrada”

Tensor-Canon no es un framework,
sino un guardrail ligero para usar en el borde de entrada del modelo.

• ✅ Validación de shape (básica)
• ✅ Resonance (detección de drift)
  • Detección de cambios de distribución basada en MMD
  • Uso sin herramientas pesadas de MLOps
• ✅ Covenant DSL (contrato en cadena)
  • En lugar de genéricos de tipos complejos como Typing[Float, ...]
  • una especificación legible al instante como "batch channels 224 224"
• ✅ Dual Backend
  • preprocesamiento en NumPy e inferencia en PyTorch,
    protegiendo con una sola sintaxis un pipeline real de trabajo
  • aplicación consistente del contrato desde el data loader hasta la entrada del modelo

---

🔹 Probar Tensor-Canon en solo 3 minutos (PyTorch)

1️⃣ Instalación (30 segundos)

pip install flamehaven-tensor-canon  

---

2️⃣ Validación de shape (1 minuto)

import torch  
from tensor_canon import validate  
  
# Especificación de entrada esperada (NCHW)  
spec = "batch channels 224 224"  
  
x = torch.randn(32, 3, 224, 224)  
  
# Si el shape no coincide, lanza ValueError  
validate(x, spec, key="image_input")  
  
print("OK: se cumple el contrato de shape")  

---

3️⃣ Detección de distribución (Drift) (1 minuto 30 segundos)

import torch  
from tensor_canon import TensorCanonPrime  
  
engine = TensorCanonPrime(drift_threshold=0.05)  
  
# Registrar la referencia de los datos de entrenamiento  
train = torch.randn(100, 512)  
engine.register_golden("embedding", train)  
  
# Verificar datos de producción  
prod = torch.randn(10, 512) + 0.5  # desplazamiento sutil en la distribución  
score = engine.check_resonance("embedding", prod)  
  
print("drift score:", score)  
  
if score > 0.05:  
    print("⚠️ se detectó drift")  

---

Cuándo conviene usarlo

• Pipeline de preprocesamiento en NumPy → entrada del modelo en PyTorch
• Sanity check de entradas en DataLoader
• Cuando “el shape coincide, pero las métricas bajan”
• Guardrail mínimo antes de adoptar MLOps pesado

---

🔹 Política de distribución / releases (referencia)

• Se puede instalar directamente como paquete de PyPI
• Los releases de GitHub se gestionan por tags (tag-based)
• Solo para tags verificados, CI construye wheel / sdist
  y los adjunta al GitHub Release
• Para garantizar estabilidad y reproducibilidad,
  se mantiene una política de distribuir solo builds verificados en lugar de despliegues automáticos y frecuentes

---

Bienvenidos el feedback / issues / PR

En especial, si tienen casos de “el shape coincidía, pero falló en producción”,
me gustaría evolucionar juntos los patrones de contrato (DSL) a partir de esos casos.

Y además, ⭐ las estrellas realmente ayudan mucho.
Este proyecto se desarrolla cada semana impulsado por cada estrella.
Si lo prueban y les parece bueno, ¡les agradecería mucho que le dieran una estrella como muestra de apoyo!