Flamehaven Tensor-Canon v0.1.4 - Validator ringan untuk Shape + Drift (MMD) tensor PyTorch/NumPy

Halo.
Minggu ini saya ingin membagikan Flamehaven Tensor-Canon (v0.1.4).

---

Saat mengembangkan dengan PyTorch, shape tensor selalu perlu diperhatikan.
Sebagai contoh, untuk input gambar biasanya berbentuk NCHW
(seperti batch N, channel C, tinggi H, lebar W).

Namun di operasional (production) nyata, masalah berikut justru lebih menakutkan.

• shape benar, tetapi distribusi data diam-diam berubah
• model terus berjalan, tetapi performa/metrik perlahan runtuh

Karena itu, saya membuat Tensor-Canon bukan hanya untuk pengecekan shape,
melainkan juga untuk memeriksa secara ringan dan cepat apakah distribusi input berubah.

---

Tool yang sudah ada memang kuat, tetapi perannya berbeda

• Einops
  Mengubah/memanipulasi shape secara intuitif berbasis string
  → lebih optimal untuk operasi/transformasi daripada validasi

• Jaxtyping
  Validasi berbasis type hint (ramah IDE)
  → tetapi sintaks generic Python bisa mudah menjadi panjang

• Torchtyping
  Validasi shape yang ringan
  → cakupannya berfokus pada shape

• Pydantic
  Standar untuk validasi data umum
  → agak berat dan merepotkan untuk validasi array multidimensi seperti tensor

---

Namun Flamehaven Tensor-Canon berbeda dalam hal “guardrail input”

Tensor-Canon bukan framework,
melainkan guardrail ringan yang digunakan di batas input model.

• ✅ Validasi shape (dasar)
• ✅ Resonance (deteksi drift)
  • deteksi perubahan distribusi berbasis MMD
  • dapat digunakan tanpa tool MLOps yang berat
• ✅ Covenant DSL (kontrak berbasis string)
  • alih-alih generic type yang kompleks seperti Typing[Float, ...]
  • spesifikasi yang langsung terbaca seperti "batch channels 224 224"
• ✅ Dual Backend
  • preprocessing dengan NumPy, inferensi dengan PyTorch
    dapat dilindungi dalam satu sintaks untuk pipeline kerja nyata
  • kontrak yang konsisten diterapkan dari data loader hingga input model

---

🔹 Coba Tensor-Canon hanya dalam 3 menit (PyTorch)

1️⃣ Instalasi (30 detik)

pip install flamehaven-tensor-canon  

---

2️⃣ Validasi shape (1 menit)

import torch  
from tensor_canon import validate  
  
# Spesifikasi input yang diharapkan (NCHW)  
spec = "batch channels 224 224"  
  
x = torch.randn(32, 3, 224, 224)  
  
# Jika shape tidak cocok, akan memunculkan ValueError  
validate(x, spec, key="image_input")  
  
print("OK: kontrak shape terpenuhi")  

---

3️⃣ Deteksi distribusi (Drift) (1 menit 30 detik)

import torch  
from tensor_canon import TensorCanonPrime  
  
engine = TensorCanonPrime(drift_threshold=0.05)  
  
# Mendaftarkan baseline data training  
train = torch.randn(100, 512)  
engine.register_golden("embedding", train)  
  
# Mengecek data produksi  
prod = torch.randn(10, 512) + 0.5  # pergeseran distribusi yang halus  
score = engine.check_resonance("embedding", prod)  
  
print("drift score:", score)  
  
if score > 0.05:  
    print("⚠️ drift terdeteksi")  

---

Kapan cocok digunakan

• Pipeline preprocessing NumPy → input model PyTorch
• Sanity check input DataLoader
• Saat “shape benar tetapi metrik menurun”
• Guardrail minimum sebelum mengadopsi MLOps yang berat

---

🔹 Kebijakan deployment / rilis (referensi)

• Bisa langsung diinstal sebagai paket PyPI
• Rilis GitHub dikelola dengan basis tag-based
• Hanya untuk tag yang telah tervalidasi, CI akan membangun wheel / sdist
  lalu melampirkannya ke GitHub Release
• Untuk menjamin stabilitas dan reproduksibilitas,
  alih-alih deployment otomatis yang sering, pendekatan yang dipertahankan adalah hanya merilis build yang sudah tervalidasi

---

Feedback / issue / PR sangat diterima

Terutama jika ada kasus “shape benar tetapi gagal di production”,
saya ingin mengembangkan bersama pola kontrak (DSL) berdasarkan kasus-kasus tersebut.

Dan ⭐ star benar-benar sangat berarti.
Proyek ini dikembangkan setiap minggu dengan setiap star sebagai tenaga pendorong.
Jika Anda mencobanya dan merasa bagus, saya akan berterima kasih jika Anda memberi satu star sebagai bentuk dukungan!