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

> Clean Markdown view of GeekNews topic #25233. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=25233](https://news.hada.io/topic?id=25233)
- GeekNews Markdown: [https://news.hada.io/topic/25233.md](https://news.hada.io/topic/25233.md)
- Type: show
- Author: [flamehaven01](https://news.hada.io/@flamehaven01)
- Published: 2025-12-22T03:35:07+09:00
- Updated: 2025-12-22T03:35:07+09:00
- Original source: [github.com/flamehaven01](https://github.com/flamehaven01/Flamehaven-Tensor-Canon)
- Points: 2
- Comments: 0

## Topic Body

안녕하세요.  
이번 주에는 **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초)  
  
```bash  
pip install flamehaven-tensor-canon  
````  
  
---  
  
##### 2️⃣ Shape 검증 (1분)  
  
```python  
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초)  
  
```python  
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) 패턴을 같이 발전**시키고 싶습니다.  
  
그리고 ⭐ **스타는 정말 큰 힘이 됩니다.**  
이 프로젝트는 **매주 스타 하나하나를 동력 삼아 개발**하고 있습니다.  
써보시고 괜찮다면, 응원의 의미로 스타 한 번 눌러주시면 감사하겠습니다!  
  
```  
```

## Comments



_No public comments on this page._