Flamehaven Tensor-Canon v0.1.4 - PyTorch/NumPyテンソル Shape + Drift(MMD) 軽量バリデーター

こんにちは。
今週は Flamehaven Tensor-Canon (v0.1.4) を共有します。

---

PyTorchで開発していると、テンソルの shape は常に気になります。
たとえば画像入力なら、通常は NCHW
（バッチ N、チャネル C、高さ H、幅 W）のような形です。

しかし実際の 運用（プロダクション） では、次の問題のほうがより厄介です。

• shape は合っているのに、データ分布が静かに変化する
• モデルは動き続けるのに、性能/指標だけが徐々に崩れる

そこで私は、
「shape チェック」だけでなく、入力分布が変わったかどうかまで
軽量かつ高速に確認する用途で Tensor-Canon を作りました。

---

既存ツールはすでに強力ですが、役割が異なります

• Einops
  文字列ベースで shape を直感的に変換/操作
  → 検証というより 演算/変換 に最適

• Jaxtyping
  型ヒントベースの検証（IDEフレンドリー）
  → ただし Python のジェネリクス構文が長くなりがち

• Torchtyping
  軽量な shape 検証
  → 範囲は shape 中心

• Pydantic
  一般データ検証の標準
  → テンソルのような多次元配列の検証にはやや重く煩雑

---

しかし Flamehaven Tensor-Canon の「入力ガードレール」は異なります

Tensor-Canon はフレームワークではなく、
モデル入力境界で使う軽量ガードレールです。

• ✅ Shape 検証（基本）
• ✅ Resonance（ドリフト検知）
  • MMD ベースの分布変化検知
  • 重い MLOps ツールなしで利用可能
• ✅ Covenant DSL（文字列契約）
  • Typing[Float, ...] のような複雑な型ジェネリクスの代わりに
  • "batch channels 224 224" のようにそのまま読める仕様
• ✅ Dual Backend
  • 前処理は NumPy、推論は PyTorch に分かれる
    実務パイプラインを 単一の構文で防御
  • データローダーからモデル入力まで一貫した契約を適用

---

🔹 わずか3分で Tensor-Canon を試す（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 契約を満たしました")  

---

3️⃣ 分布（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  # 微妙な分布シフト  
score = engine.check_resonance("embedding", prod)  
  
print("drift score:", score)  
  
if score > 0.05:  
    print("⚠️ drift が検知されました")  

---

どんなときに有用か

• NumPy 前処理 → PyTorch モデル入力パイプライン
• DataLoader 入力の sanity check
• 「shape は合っているのに指標が落ちるとき」
• 重い MLOps 導入前の 最小ガードレール

---

🔹 配布 / リリース方針（参考）

• PyPI パッケージとしてすぐにインストール可能
• GitHub リリースは タグベース（tag-based） で管理
• 検証済みタグに対してのみ CI で wheel / sdist をビルドし、
  GitHub Release に添付
• 安定性と再現性を確保するため
  自動・高頻度な配布ではなく、検証済みビルドのみを配布する方式を維持します

---

フィードバック / issue / PR を歓迎します

特に「shape は合っているのに運用で壊れたケース」があれば、
その事例をもとに 契約（DSL）パターンを一緒に発展させたいです。

そして ⭐ スターは本当に大きな力になります。
このプロジェクトは 毎週一つひとつのスターを原動力にして開発しています。
試してみて良ければ、応援の意味でスターを一つ押していただけるとうれしいです！