Flamehaven Tensor-Canon v0.1.4 – schlanker Validator für PyTorch-/NumPy-Tensor-Shape + Drift (MMD)

Hallo.
Diese Woche möchte ich Flamehaven Tensor-Canon (v0.1.4) vorstellen.

---

Wenn man mit PyTorch entwickelt, muss man die Shape von Tensoren ständig im Blick behalten.
Bei Bildeingaben ist das zum Beispiel meist NCHW
(Charge N, Kanäle C, Höhe H, Breite W).

In der tatsächlichen Produktion sind aber die folgenden Probleme noch beängstigender.

• Die Shape stimmt, aber die Datenverteilung verändert sich unbemerkt
• Das Modell läuft weiter, aber Leistung/Kennzahlen brechen schleichend ein

Deshalb habe ich Tensor-Canon entwickelt – nicht nur für einen Shape-Check, sondern auch dafür, leichtgewichtig und schnell zu prüfen, ob sich die Eingabeverteilung verändert hat.

---

Bestehende Tools sind bereits leistungsstark, aber ihre Rolle ist eine andere

• Einops
  Intuitive Shape-Transformation/Manipulation auf String-Basis
  → Eher für Operationen/Transformationen optimiert als für Validierung

• Jaxtyping
  Validierung auf Basis von Type Hints (IDE-freundlich)
  → Allerdings wird die Python-Generic-Syntax leicht lang und unübersichtlich

• Torchtyping
  Leichtgewichtige Shape-Validierung
  → Fokus liegt vor allem auf Shape

• Pydantic
  Der Standard für allgemeine Datenvalidierung
  → Für die Validierung mehrdimensionaler Arrays wie Tensoren etwas schwergewichtig und umständlich

---

Flamehaven Tensor-Canon unterscheidet sich jedoch bei den „Input-Guardrails“

Tensor-Canon ist kein Framework,
sondern ein leichtgewichtiges Guardrail für die Eingabegrenze von Modellen.

• ✅ Shape-Validierung (Basis)
• ✅ Resonance (Drift-Erkennung)
  • MMD-basierte Erkennung von Verteilungsänderungen
  • Einsetzbar ohne schwere MLOps-Tools
• ✅ Covenant DSL (String-Vertrag)
  • Statt komplexer Type-Generics wie Typing[Float, ...]
  • direkt lesbare Spezifikationen wie "batch channels 224 224"
• ✅ Dual Backend
  • Preprocessing mit NumPy, Inferenz mit PyTorch
    in realen Praxis-Pipelines wird mit einer einheitlichen Syntax abgesichert
  • Konsistente Verträge vom Data Loader bis zur Modelleingabe

---

🔹 Tensor-Canon in nur 3 Minuten ausprobieren (PyTorch)

1️⃣ Installation (30 Sekunden)

pip install flamehaven-tensor-canon  

---

2️⃣ Shape-Validierung (1 Minute)

import torch  
from tensor_canon import validate  
  
# Erwartete Eingabespezifikation (NCHW)  
spec = "batch channels 224 224"  
  
x = torch.randn(32, 3, 224, 224)  
  
# Bei einer falschen Shape wird ein ValueError ausgelöst  
validate(x, spec, key="image_input")  
  
print("OK: Shape-Vertrag erfüllt")  

---

3️⃣ Verteilungsänderung (Drift) erkennen (1 Minute 30 Sekunden)

import torch  
from tensor_canon import TensorCanonPrime  
  
engine = TensorCanonPrime(drift_threshold=0.05)  
  
# Trainingsdaten als Referenz registrieren  
train = torch.randn(100, 512)  
engine.register_golden("embedding", train)  
  
# Produktionsdaten prüfen  
prod = torch.randn(10, 512) + 0.5  # subtile Verschiebung der Verteilung  
score = engine.check_resonance("embedding", prod)  
  
print("drift score:", score)  
  
if score > 0.05:  
    print("⚠️ drift erkannt")  

---

Wann ist es sinnvoll?

• NumPy-Preprocessing → PyTorch-Modelleingabe-Pipeline
• Sanity Check für DataLoader-Eingaben
• Wenn „die Shape stimmt, aber die Metriken fallen“
• Minimales Guardrail, bevor schwere MLOps eingeführt werden

---

🔹 Deployment-/Release-Policy (Hinweis)

• Direkt als PyPI-Paket installierbar
• GitHub-Releases werden tag-basiert verwaltet
• Nur für validierte Tags werden in der CI wheel / sdist gebaut und
  an GitHub Release angehängt
• Um Stabilität und Reproduzierbarkeit sicherzustellen,
  werden statt automatischer und häufiger Deployments nur validierte Builds veröffentlicht

---

Feedback / Issues / PRs willkommen

Wenn es insbesondere Fälle gibt, in denen „die Shape stimmte, aber es in Produktion schiefging“,
würde ich auf Basis solcher Beispiele gern Vertrags-(DSL-)Muster gemeinsam weiterentwickeln.

Und ⭐ Stars sind wirklich eine große Hilfe.
An diesem Projekt wird jede Woche weiterentwickelt, angetrieben von jedem einzelnen Star.
Wenn ihr es ausprobiert und es euch zusagt, würde ich mich freuen, wenn ihr als Zeichen der Unterstützung einen Star dalasst!