Show GN: Flamehaven Tensor-Canon v0.1.4 - 파이토치/넘파이 텐서 Shape + Drift(MMD) 경량 검증기

안녕하세요.
이번 주에는 Flamehaven Tensor-Canon (v0.1.4) 를 공유합니다.

---

파이토치(PyTorch)로 개발하다 보면 텐서 shape가 늘 신경 쓰입니다.
예를 들어 이미지 입력이면 보통 NCHW
(배치 N, 채널 C, 높이 H, 너비 W) 같은 형태죠.

그런데 실제 운영(프로덕션) 에서는 아래 문제가 더 무섭습니다.

• shape은 맞는데, 데이터 분포가 조용히 바뀜
• 모델은 계속 돌아가는데, 성능/지표만 서서히 무너짐

그래서 저는
“shape 체크”만이 아니라, 입력 분포가 바뀌었는지까지
가볍고 빠르게 확인하는 용도로 Tensor-Canon을 만들었습니다.

---

기존 도구들은 이미 강력하지만, 역할이 다릅니다

• Einops
  문자열 기반으로 shape을 직관적으로 변환/조작
  → 검증이라기보다 연산/변환에 최적

• Jaxtyping
  타입 힌트 기반 검증 (IDE 친화)
  → 다만 파이썬 제네릭 문법이 길어지기 쉬움

• 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에 첨부
• 안정성과 재현성 확보를 위해
  자동·빈번한 배포 대신, 검증된 빌드만 배포하는 방식을 유지합니다

---

피드백 / 이슈 / PR 환영합니다

특히 “shape은 맞는데 운영에서 망했던 케이스”가 있다면,
그 사례를 바탕으로 계약(DSL) 패턴을 같이 발전시키고 싶습니다.

그리고 ⭐ 스타는 정말 큰 힘이 됩니다.
이 프로젝트는 매주 스타 하나하나를 동력 삼아 개발하고 있습니다.
써보시고 괜찮다면, 응원의 의미로 스타 한 번 눌러주시면 감사하겠습니다!