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

Olá.
Nesta semana, compartilho o Flamehaven Tensor-Canon (v0.1.4).

---

Ao desenvolver com PyTorch, o shape do tensor é sempre algo que exige atenção.
Por exemplo, para entrada de imagem, normalmente usamos um formato como NCHW
(batch N, canal C, altura H, largura W).

Mas em produção, os problemas abaixo são ainda mais assustadores.

• o shape está correto, mas a distribuição dos dados muda silenciosamente
• o modelo continua rodando, mas desempenho/métricas vão se degradando aos poucos

Por isso, criei o Tensor-Canon para verificar de forma leve e rápida
não apenas o “check de shape”, mas também se a distribuição de entrada mudou.

---

As ferramentas existentes já são poderosas, mas têm papéis diferentes

• Einops
  Converte/manipula shapes de forma intuitiva com base em strings
  → é mais otimizado para operações/transformações do que para validação

• Jaxtyping
  Validação baseada em type hints (amigável para IDE)
  → porém a sintaxe de genéricos em Python tende a ficar longa

• Torchtyping
  Validação leve de shape
  → o escopo é centrado em shape

• Pydantic
  O padrão para validação de dados em geral
  → para validar arrays multidimensionais como tensores, pode ser relativamente pesado e trabalhoso

---

Mas o diferencial do Flamehaven Tensor-Canon está no “guardrail de entrada”

O Tensor-Canon não é um framework,
é um guardrail leve usado na fronteira de entrada do modelo.

• ✅ Validação de shape (básico)
• ✅ Resonance (detecção de drift)
  • detecção de mudança de distribuição baseada em MMD
  • uso sem ferramentas pesadas de MLOps
• ✅ Covenant DSL (contrato em string)
  • em vez de genéricos complexos de tipo como Typing[Float, ...]
  • uma especificação legível imediatamente como "batch channels 224 224"
• ✅ Dual Backend
  • protege com uma única sintaxe pipelines reais
    em que o pré-processamento é feito com NumPy e a inferência com PyTorch
  • aplica contratos consistentes do data loader até a entrada do modelo

---

🔹 Experimente o Tensor-Canon em apenas 3 minutos (PyTorch)

1️⃣ Instalação (30 segundos)

pip install flamehaven-tensor-canon  

---

2️⃣ Validação de shape (1 minuto)

import torch  
from tensor_canon import validate  
  
# especificação de entrada esperada (NCHW)  
spec = "batch channels 224 224"  
  
x = torch.randn(32, 3, 224, 224)  
  
# gera ValueError se o shape não corresponder  
validate(x, spec, key="image_input")  
  
print("OK: contrato de shape atendido")  

---

3️⃣ Detecção de distribuição (Drift) (1 minuto e 30 segundos)

import torch  
from tensor_canon import TensorCanonPrime  
  
engine = TensorCanonPrime(drift_threshold=0.05)  
  
# registra a referência com base nos dados de treino  
train = torch.randn(100, 512)  
engine.register_golden("embedding", train)  
  
# checa os dados de produção  
prod = torch.randn(10, 512) + 0.5  # deslocamento sutil de distribuição  
score = engine.check_resonance("embedding", prod)  
  
print("drift score:", score)  
  
if score > 0.05:  
    print("⚠️ drift detectado")  

---

Quando vale a pena usar

• Pipeline de pré-processamento em NumPy → entrada de modelo em PyTorch
• Sanity check da entrada do DataLoader
• Quando “o shape está certo, mas as métricas caem”
• Guardrail mínimo antes de adotar MLOps mais pesado

---

🔹 Política de distribuição / release (referência)

• Pode ser instalado diretamente como pacote no PyPI
• Os releases no GitHub são gerenciados em modelo baseado em tags (tag-based)
• Apenas para tags validadas, o CI gera wheel / sdist
  e anexa ao GitHub Release
• Para garantir estabilidade e reprodutibilidade,
  em vez de distribuição automática e frequente, mantém-se a política de distribuir apenas builds validadas

---

Feedback / issues / PRs são bem-vindos

Especialmente se você tiver algum caso em que “o shape estava certo, mas deu ruim em produção”,
gostaria de evoluir junto os padrões de contrato (DSL) com base nesses exemplos.

E ⭐ stars realmente ajudam muito.
Este projeto está sendo desenvolvido toda semana, movido por cada star recebida.
Se testar e achar interessante, agradeço se puder deixar uma star como forma de apoio!