2026-03-04 Model Registry architecture, eliminate 5-place coupling

Author: eddmpython

CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to Vectrix will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.13] - 2026-03-04
+
+Model Registry architecture — eliminates coupling between model metadata, model creation, and orchestration. Adding a new model now requires editing only 1 file instead of 5.
+
+### Changed
+
+**Architecture: Model Registry Pattern (`engine/registry.py`)**
+- Created `engine/registry.py` as the Single Source of Truth for all model metadata
+- `ModelSpec` dataclass: modelId, name, description, factory, needsPeriod, minData, flatResistance, bestFor, refitStrategy
+- `createModel(modelId, period)`: unified model instantiation — replaces 200-line if/elif chain in vectrix.py
+- `getRegistry()`, `getModelSpec()`, `listModelIds()`, `getModelInfo()`: centralized access to model information
+- Adding a new forecasting model now requires only 1 edit: add a `ModelSpec` entry to `registry.py`
+
+**vectrix.py Refactored (959 → 709 lines, -26%)**
+- Removed `NATIVE_MODELS` class dict (80+ lines) — replaced by `getRegistry()`
+- Removed `_fitAndPredictNativeWithCache` 200-line if/elif chain — replaced by `createModel()` + `fit()` + `predict()`
+- Refit strategies now driven by `ModelSpec.refitStrategy` field instead of model-specific if/elif
+- `_getModelName()` static method replaces repeated dict lookups
+
+**types.py MODEL_INFO Unified**
+- `MODEL_INFO` is now a lazy-loading proxy that reads from `engine/registry.py` on first access
+- Backward compatible: all existing code using `MODEL_INFO[modelId]` continues to work
+- Eliminates duplicate model metadata between types.py and vectrix.py
+
+### Added
+
+- `engine/registry.py`: Model registry module with `ModelSpec`, `getRegistry()`, `createModel()`, `getModelInfo()`
+- `CLAUDE.md`: Architecture design philosophy section documenting registry pattern, module roles, dependency direction, and engine interface contract
+
+[0.0.13]: https://github.com/eddmpython/vectrix/compare/v0.0.12...v0.0.13
+
 ## [0.0.12] - 2026-03-04
 
 DOT-Hybrid holdout validation release — 8-way config selection for period>1 data now uses holdout validation instead of in-sample MAE, reducing overfitting on Quarterly (-1.25%) and Monthly (-2.55%) forecasts. AVG OWA improved from 0.8831 to ~0.876.

CLAUDE.md

@@ -355,31 +355,90 @@ src/vectrix/
 - 구현: numpy + scipy.optimize, 난이도 중
 - 기대: "가장 놀랍지 않은" 예측 = 과적합 방지
 
-## 확장/유지보수 원칙 (2026-03-04 확정)
+## 아키텍처 설계 사상 (2026-03-04 확정)
 
-### API 설계 원칙
+### [최우선] 결합도 최소화 — "1곳 수정 = 1곳만 수정"
+
+**과거 문제**: 모델 추가 시 5곳 수정 필요 (NATIVE_MODELS, _fitAndPredictNativeWithCache, _refitModelOnFullData, _selectNativeModels, MODEL_INFO) → 스파게티 코드, 연쇄 버그
+
+**해결: 레지스트리 패턴 (engine/registry.py)**
+
+```
+engine/registry.py  ← 모든 모델 메타데이터의 Single Source of Truth
+  │
+  ├── ModelSpec: modelId, name, description, factory, needsPeriod, minData, flatResistance, bestFor
+  ├── getRegistry() → Dict[str, ModelSpec]
+  ├── createModel(modelId, period) → model instance
+  └── getModelInfo() → backward-compatible MODEL_INFO dict
+```
+
+**새 모델 추가 절차 (1곳만 수정)**:
+1. `engine/newmodel.py` 작성 (fit/predict 인터페이스)
+2. `engine/registry.py`에 ModelSpec 1개 추가
+3. 끝. vectrix.py, types.py, easy.py, docs 자동 반영
+
+**절대 금지**:
+- vectrix.py에 모델별 if/elif 분기 추가
+- types.py에 모델 메타데이터 중복
+- easy.py에 모델 로직 중복 구현
+
+### 모듈 역할 분리 — 단방향 의존성
+
+```
+easy.py → vectrix.py → engine/registry.py → engine/*.py
+   │                         │
+   └── types.py ←────────────┘
+```
+
+- **easy.py**: 사용자 인터페이스 전용. 데이터 파싱 + Vectrix 래핑. 자체 로직 없음
+- **vectrix.py**: 오케스트레이터. 분석/모델선택/학습/앙상블 조율. 모델 생성은 registry 위임
+- **engine/registry.py**: 모델 메타데이터 중앙 저장소. 모든 모델 정보의 유일한 출처
+- **engine/*.py**: 순수 예측 엔진. 외부 의존성 없음. fit(y) → predict(steps) 계약만 준수
+- **types.py**: 데이터 타입 정의만. 모델 메타데이터 보관 금지 (registry.py로 이전)
+
+### 엔진 인터페이스 계약
+
+모든 예측 모델은 이 계약을 반드시 준수:
+
+```python
+class ForecastModel:
+    def fit(self, y: np.ndarray) -> self:
+        """학습. y는 1D float64 배열."""
+
+    def predict(self, steps: int) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """예측. (predictions, lower95, upper95) 반환."""
+```
+
+- `fit()`은 `self` 반환 (체이닝 가능)
+- `predict()`는 항상 3-tuple 반환
+- 생성자에서 `period` 파라미터는 선택적 (registry.ModelSpec.needsPeriod로 관리)
+- 학습 전 predict() 호출 시 ValueError raise
+
+### 확장/유지보수 원칙
+
+#### API 설계 원칙
 1. **Progressive Disclosure**: Level 1(제로설정) → Level 2(가이드 제어) → Level 3(엔진 직접)
 2. **새 파라미터 추가 시 반드시 기본값 제공** — `forecast(data, steps=12)`는 영원히 동작해야 함
 3. **Easy API 파라미터는 Vectrix 클래스의 기능을 투과** — easy.py가 vectrix.py를 래핑, 중복 구현 금지
 4. **파라미터 네이밍**: Easy API는 snake_case 허용 (models, ensemble, confidence), 내부는 camelCase
 
-### 엔진 확장 원칙
-1. **새 모델 추가 시**: engine/ 아래 독립 파일, `fit(data)` + `predict(steps)` 인터페이스 준수
+#### 엔진 확장 원칙
+1. **새 모델 = registry.py에 ModelSpec 1개 추가** — 다른 파일 수정 불필요
 2. **M4 100K 벤치마크 통과 필수** — OWA < 1.0 (Naive2 대비) 확인 후 통합
-3. **NATIVE_MODELS dict에 등록** + `__init__.py` export + 테스트 추가
-4. **잔차 다양성 우선** — 기존 모델과 잔차 상관 < 0.5인 모델이 앙상블에 가치 있음
+3. **잔차 다양성 우선** — 기존 모델과 잔차 상관 < 0.5인 모델이 앙상블에 가치 있음
+4. **engine/__init__.py에서 export** + tests/ 테스트 추가
 
-### 속도 확장 원칙
+#### 속도 확장 원칙
 1. **핫 루프 식별 → Rust 이전** — profiling으로 병목 확인 후 rust/src/lib.rs에 추가
 2. **Python 오버헤드 최소화** — 모델 선택/CV 로직의 불필요한 복사/변환 제거
 3. **벤치마크 측정 필수** — 변경 전후 `forecast()` 전체 latency 비교
 
-### 정확도 확장 원칙
+#### 정확도 확장 원칙
 1. **앙상블 전략이 단일 모델보다 중요** — DNA 기반 가중치, 잔차 다양성 활용
 2. **빈도별 전략 분리** — Yearly/Quarterly는 Theta계열, Hourly/Daily는 다중 계절성 특화
 3. **실험 → 검증 → 통합 파이프라인** — experiments/에서 실험, M4로 검증, engine/으로 통합
 
-### 문서/마케팅 원칙
+#### 문서/마케팅 원칙
 1. **모든 주장에 벤치마크 수치 첨부** — "빠르다"가 아닌 "5.6x faster (295ms → 52ms)"
 2. **블로그는 교육 중심** — 기초부터 설명, Vectrix 홍보는 자연스럽게 녹여냄
 3. **비교 표는 공정하게** — 경쟁사의 장점도 인정, 우리가 약한 부분도 투명하게 공개

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vectrix"
-version = "0.0.10"
+version = "0.0.13"
 edition = "2021"
 license-file = "LICENSE"
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vectrix"
-version = "0.0.12"
+version = "0.0.13"
 description = "Zero-config time series forecasting & analysis library. 30+ models with built-in Rust engine for blazing-fast performance."
 readme = "README.md"
 license = {file = "LICENSE"}

src/vectrix/__init__.py

@@ -83,7 +83,7 @@
 )
 from .vectrix import Vectrix
 
-__version__ = "0.0.12"
+__version__ = "0.0.13"
 __all__ = [
     "Vectrix",
     "ForecastResult",

src/vectrix/engine/__init__.py

@@ -33,6 +33,7 @@
 from .tbats import TBATS, AutoTBATS
 from .theta import ThetaModel
 from .tsfeatures import TSFeatureExtractor
+from .registry import ModelSpec, createModel, getModelInfo, getModelSpec, getRegistry, listModelIds
 from .turbo import TurboCore
 from .var import VARModel, VECMModel
 
@@ -86,4 +87,10 @@
     "AdaptiveThetaEnsemble",
     "EchoStateForecaster",
     "DynamicTimeScanForecaster",
+    "ModelSpec",
+    "getRegistry",
+    "getModelSpec",
+    "listModelIds",
+    "createModel",
+    "getModelInfo",
 ]