Flamehaven Tensor-Canon v0.1.4 - ตัวตรวจสอบน้ำหนักเบาสำหรับ Shape + Drift (MMD) ของเทนเซอร์ใน PyTorch/NumPy

สวัสดีครับ
สัปดาห์นี้ขอแชร์ Flamehaven Tensor-Canon (v0.1.4) ครับ

---

เวลาพัฒนาด้วย PyTorch มักต้องคอยกังวลเรื่อง shape ของเทนเซอร์อยู่เสมอ
ตัวอย่างเช่น ถ้าเป็นอินพุตภาพ ก็มักจะอยู่ในรูปแบบ NCHW
(แบตช์ N, แชนเนล C, ความสูง H, ความกว้าง W)

แต่ใน ระบบโปรดักชัน ปัญหาด้านล่างนี้น่ากลัวกว่าอีกครับ

• shape ถูกต้อง แต่ การกระจายของข้อมูลเปลี่ยนไปแบบเงียบ ๆ
• โมเดลยังทำงานต่อเนื่อง แต่ ประสิทธิภาพ/ตัวชี้วัดค่อย ๆ พังลง

เพราะแบบนี้
ผมจึงสร้าง Tensor-Canon ขึ้นมาเพื่อใช้ตรวจสอบแบบเบาและรวดเร็ว
ไม่ใช่แค่ “เช็ก shape” แต่ยังรวมถึง การดูว่า distribution ของอินพุตเปลี่ยนไปหรือไม่ ด้วย

---

เครื่องมือเดิมก็ทรงพลังอยู่แล้ว แต่มีบทบาทต่างกัน

• Einops
  แปลง/จัดการ shape ได้อย่างเข้าใจง่ายด้วยสตริง
  → เหมาะกับ การคำนวณ/การแปลง มากกว่าการตรวจสอบ

• Jaxtyping
  การตรวจสอบที่อิง type hint (เป็นมิตรกับ IDE)
  → แต่ syntax ของ Python generic มักยาวได้ง่าย

• Torchtyping
  การตรวจสอบ shape แบบเบา
  → ขอบเขตยังเน้นที่ shape เป็นหลัก

• Pydantic
  มาตรฐานสำหรับการตรวจสอบข้อมูลทั่วไป
  → แต่สำหรับการตรวจสอบอาร์เรย์หลายมิติอย่างเทนเซอร์อาจค่อนข้างหนักและยุ่งยาก

---

แต่สิ่งที่ต่างของ Flamehaven Tensor-Canon คือ “guardrail สำหรับอินพุต”

Tensor-Canon ไม่ใช่เฟรมเวิร์ก
แต่เป็น guardrail น้ำหนักเบาที่ใช้ตรงขอบเขตอินพุตของโมเดล

• ✅ ตรวจสอบ Shape (พื้นฐาน)
• ✅ Resonance (การตรวจจับ drift)
  • ตรวจจับการเปลี่ยนแปลงของ distribution บนพื้นฐาน MMD
  • ใช้งานได้โดยไม่ต้องมีเครื่องมือ MLOps ขนาดใหญ่
• ✅ Covenant DSL (สัญญาแบบสตริง)
  • แทนการใช้ type generic ที่ซับซ้อนอย่าง Typing[Float, ...]
  • ใช้สเปกที่อ่านออกทันทีอย่าง "batch channels 224 224"
• ✅ Dual Backend
  • รองรับการป้องกันด้วย ไวยากรณ์เดียว สำหรับไปป์ไลน์งานจริง
    ที่ preprocessing ใช้ NumPy และ inference ใช้ PyTorch
  • ใช้สัญญาเดียวกันได้อย่างสม่ำเสมอตั้งแต่ data loader ไปจนถึงอินพุตของโมเดล

---

🔹 ลองใช้ Tensor-Canon ใน 3 นาที (PyTorch)

1️⃣ ติดตั้ง (30 วินาที)

pip install flamehaven-tensor-canon  

---

2️⃣ ตรวจสอบ Shape (1 นาที)

import torch  
from tensor_canon import validate  
  
# สเปกอินพุตที่คาดหวัง (NCHW)  
spec = "batch channels 224 224"  
  
x = torch.randn(32, 3, 224, 224)  
  
# ถ้า shape ไม่ตรง จะเกิด ValueError  
validate(x, spec, key="image_input")  
  
print("OK: shape contract ผ่าน")  

---

3️⃣ ตรวจจับ distribution (Drift) (1 นาที 30 วินาที)

import torch  
from tensor_canon import TensorCanonPrime  
  
engine = TensorCanonPrime(drift_threshold=0.05)  
  
# ลงทะเบียนข้อมูลอ้างอิงจากชุดฝึก  
train = torch.randn(100, 512)  
engine.register_golden("embedding", train)  
  
# ตรวจสอบข้อมูลโปรดักชัน  
prod = torch.randn(10, 512) + 0.5  # การเลื่อนของ distribution แบบเล็กน้อย  
score = engine.check_resonance("embedding", prod)  
  
print("drift score:", score)  
  
if score > 0.05:  
    print("⚠️ ตรวจพบ drift")  

---

เหมาะใช้เมื่อไร

• ไปป์ไลน์ preprocessing ด้วย NumPy → อินพุตโมเดล PyTorch
• sanity check สำหรับอินพุตของ DataLoader
• กรณีที่ “shape ถูก แต่ตัวชี้วัดตก”
• ใช้เป็น guardrail ขั้นต่ำ ก่อนนำ MLOps แบบหนักเข้ามา

---

🔹 นโยบายการเผยแพร่ / รีลีส (อ้างอิง)

• ติดตั้งได้ทันทีผ่านแพ็กเกจบน PyPI
• GitHub release จัดการแบบ tag-based
• จะ build wheel / sdist ใน CI และแนบเข้า GitHub Release
  เฉพาะกับแท็กที่ผ่านการตรวจสอบแล้วเท่านั้น
• เพื่อให้มั่นใจในความเสถียรและความสามารถในการทำซ้ำ
  จึงคงแนวทางเผยแพร่เฉพาะ build ที่ผ่านการตรวจสอบ แทนการปล่อยอัตโนมัติแบบถี่ ๆ

---

ยินดีรับฟีดแบ็ก / issue / PR

โดยเฉพาะถ้าคุณมีเคสแบบ “shape ถูกต้อง แต่พังในโปรดักชัน”
ผมอยากนำกรณีนั้นมาช่วยกันพัฒนา แพตเทิร์นของสัญญา (DSL) ให้ดีขึ้นครับ

และ ⭐ การกดดาวคือกำลังใจที่มีความหมายมากจริง ๆ
โปรเจกต์นี้ พัฒนาต่อทุกสัปดาห์ด้วยแรงสนับสนุนจากทุกดาว
หากลองใช้แล้วรู้สึกว่าโอเค รบกวนช่วยกดดาวเพื่อเป็นกำลังใจด้วยครับ!