feat: python-kis v3 — 2-layer architecture with codegen pipeline, streaming, and service layer

[Soju06]

Summary

python-kis를 v3로 전면 재설계합니다. KIS (한국투자증권) Open API의 국내/해외 간 구조적 차이(필드명, enum 코드, 응답 구조, 호출 패턴)를 극복하기 위해, 2-Layer Architecture 기반의 새로운 SDK를 처음부터 구축했습니다.

핵심 변경

• 2-Layer Architecture (L0 Raw → L1 Service → Public API)
• Codegen Pipeline: KIS API 문서에서 294개 Pydantic 모델을 자동 생성
• Streaming System: 실시간 WebSocket 시세를 정규화 모델로 변환
• L1 Service Layer: Quote 도메인 vertical slice (국내/해외 통합)
• L0 Drift Detection: 구조적 시그니처 기반 변동 감지 시스템
• Store Module: SQLite 기반 마스터 데이터 관리
• Async-First: unasync 기반 sync 코드 자동 생성

---

Architecture

KIS API Response
       │
       ▼
┌─────────────────────────────────┐
│  L0 — Raw                       │  Generated Pydantic models (294 endpoints)
│  API 원형 보존                   │  codegen pipeline output
│  src/pykis/api/raw/             │  alias + extra="ignore" for forward compat
└─────────┬───────────────────────┘
          │
          ▼
┌─────────────────────────────────┐
│  L1 — Service                    │  Unified domain models + service logic
│  Type System (YAML)             │  → enums, model schemas, metadata
│  Service Modules (Python)       │  → mapping, orchestration, enrichment
│  src/pykis/service/             │
└─────────┬───────────────────────┘
          │
          ▼
┌─────────────────────────────────┐
│  Public API                      │  KisClient / KisAsyncClient
│  src/pykis/client/              │
└─────────────────────────────────┘

왜 2-Layer인가? (ADR-012)

v2 분석 결과, 국내/해외 통합은 단순 필드 매핑이 아닌 절차적 서비스 로직을 요구합니다:

패턴	예시	선언적 YAML로 해결?
Multi-call 조합	해외 분봉: 최대 12회 호출 + 중복 제거 + 시간순 정렬	✗
Request→Response 전사	잔고: 계좌번호를 request에서 response에 주입	✗
조건부 라우팅	exchange.is_domestic → 다른 endpoint 호출	✗
Computed properties	등락률, 전일대비 등 API마다 다른 계산 방식	✗

결론: L1 Normalize + L2 System을 L1 Service로 통합. YAML은 "what" (모델 정의), Python은 "how" (변환 로직)을 담당합니다.

---

Module Breakdown

1. Codegen Pipeline (src/codegen/, 67 files)

KIS API 문서(YAML/MD)에서 타입 안전한 Pydantic 모델을 자동 생성합니다.

data/kis/ (API specs)
    │
    ▼
┌─────────────────────┐     ┌─────────────────────┐
│ Smoke → Normalize   │ ──▶ │ Validate → Augment  │
│ (parse, clean)      │     │ (type infer, enums)  │
└─────────────────────┘     └─────────┬───────────┘
                                      │
                                      ▼
                            ┌─────────────────────┐
                            │ Generate             │
                            │ (Jinja templates)    │
                            └─────────┬───────────┘
                                      │
                                      ▼
                            src/pykis/api/raw/
                            (294 endpoints, Pydantic models)

파이프라인 품질 게이트:

• smoke.errors: 0 — 파싱 오류 없음
• validation.errors: 0 — 타입/스키마 검증 통과
• augment.errors: 0 — enum/타입 추론 오류 없음

2. L0 Raw Models (src/pykis/api/raw/, 294 files)

• KIS API 원형을 1:1 보존하는 Pydantic 모델
• alias로 한글 원본 필드명 유지, Python snake_case 접근
• extra="ignore"로 미래 필드에 대한 전방 호환성
• UUID 기반 endpoint registry (registry.py)
• 국내주식, 해외주식, 선물옵션, 장내채권, ETF/ETN 등 전 도메인 커버

3. Streaming System (src/pykis/streaming/, 71 files)

실시간 WebSocket 시세를 3단계로 처리합니다:

WebSocket Frame ("|" delimited)
       │
       ▼
┌──────────────────┐
│  Raw Parser      │  바이트 → L0 raw dataclass
│  (auto-generated)│  시세/호가/체결통보 분류
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│  Normalize       │  L0 → NormalizedTrade / NormalizedOrderBook
│  (frozen DC)     │  국내/해외 통합, UTC datetime, Decimal
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│  System          │  이벤트 디스패치, 구독 관리
│  (event mapper)  │
└──────────────────┘

NormalizedTrade (통합 시세 모델):

• symbol, market, timestamp_utc
• price, volume, open, high, low, close (all Decimal)
• change, change_rate, change_sign
• bid_price, ask_price, bid_size, ask_size

NormalizedOrderBook (통합 호가 모델):

• 최대 10단계 bid/ask (price + size tuple)
• 매도/매수 합계

4. L1 Service Layer (src/pykis/service/, 10 files)

국내/해외를 단일 인터페이스로 통합하는 도메인 서비스 계층입니다.

Infrastructure

모듈	역할
enums.py	통합 enum: Exchange (16개), ChangeSign (5개), MarketWarning (4개)
_enum_map.py	L0↔L1 양방향 변환 테이블
_convert.py	Decimal 변환 헬퍼 (decimal_required, decimal_optional)
_types.py	Market = Literal["domestic", "overseas"]

Exchange Enum (통합 거래소)

class Exchange(StrEnum):
    # 국내
    KRX = "KRX"          # 한국거래소
    NXT = "NXT"          # 넥스트레이드

    # 해외
    NYSE = "NYSE"        # 뉴욕증권거래소
    NASDAQ = "NASDAQ"    # 나스닥
    AMEX = "AMEX"        # 아멕스
    TSE = "TSE"          # 도쿄증권거래소
    SEHK = "SEHK"        # 홍콩거래소
    SSE = "SSE"          # 상하이증권거래소
    SZSE = "SZSE"        # 선전증권거래소
    HSX = "HSX"          # 호치민증권거래소
    HNX = "HNX"          # 하노이증권거래소

    # 시간외
    NYSE_EXTENDED = "NYSE_EXT"
    NASDAQ_EXTENDED = "NASDAQ_EXT"
    AMEX_EXTENDED = "AMEX_EXT"

    @property
    def is_domestic(self) -> bool: ...
    @property
    def is_overseas(self) -> bool: ...
    @property
    def is_extended_hours(self) -> bool: ...

Quote Domain (첫 번째 vertical slice)

src/pykis/service/quote/
    models.py        # Quote (frozen dataclass, 17 fields)
    service.py       # get_quote() / get_quote_sync()
    _domestic.py     # 국내 L0 → Quote 매핑 (Protocol 기반)
    _overseas.py     # 해외 L0 → Quote 매핑 (Protocol 기반)

Quote 모델 — 국내/해외 통합 현재가:

@dataclass(frozen=True, slots=True)
class Quote:
    symbol: str
    exchange: Exchange
    price: Decimal              # 현재가
    previous_close: Decimal     # 전일종가
    change: Decimal             # 전일대비
    change_rate: Decimal        # 등락률
    change_sign: ChangeSign     # 등락부호
    open: Decimal               # 시가
    high: Decimal               # 고가
    low: Decimal                # 저가
    volume: int                 # 누적거래량
    turnover: Decimal           # 누적거래대금
    previous_volume: int        # 전일거래량
    upper_limit: Decimal | None # 상한가 (국내 전용)
    lower_limit: Decimal | None # 하한가 (국내 전용)
    market_warning: MarketWarning | None  # 시장경고 (국내 전용)
    is_trading_halted: bool | None        # 거래정지 (국내 전용)
    is_orderable: bool | None             # 주문가능 (해외 전용)

서비스 라우팅 패턴:

async def get_quote(client, symbol, exchange) -> Quote:
    if exchange.is_domestic:
        # L0: /uapi/domestic-stock/v1/quotations/inquire-price-2
        response = await endpoint.acall(client, {...})
        return map_domestic_quote(response.output, symbol, exchange)
    else:
        # L0: /uapi/overseas-price/v1/quotations/price
        response = await endpoint.acall(client, {...})
        return map_overseas_quote(response.output, symbol, exchange)

Protocol 기반 매퍼 — L0 코드와의 결합도를 최소화:

class DomesticQuoteRaw(Protocol):
    """L0 국내 현재가 응답의 구조적 계약."""
    stck_prpr: Decimal
    stck_prdy_clpr: int
    prdy_vrss: int
    prdy_ctrt: Decimal
    ...

def map_domestic_quote(raw: DomesticQuoteRaw, symbol: str, exchange: Exchange) -> Quote:
    ...

5. L0 Drift Detection (scripts/check_l0_drift.py)

codegen이 L0 모델을 재생성하면 L1 Service와의 정합성이 깨질 수 있습니다.
구조적 시그니처 비교로 변동을 감지합니다.

시그니처 계산

def compute_endpoint_signature(endpoint) -> str:
    shape = {
        "meta": {"method", "path", "tr_id"},
        "request": extract_model_shape(request_model),
        "response": extract_model_shape(response_model),
    }
    return f"sha256:{hashlib.sha256(canonical_json).hexdigest()}"

해시에 포함 (structural shape):

• 필드명, 타입, alias, required, default
• Enum 멤버 (name → value)
• 중첩 모델 (재귀)
• Endpoint meta (method, path, tr_id)

해시에 미포함 (documentation):

• 한글 설명, docstring, 주석

매니페스트 (data/service/_l0_manifest.yaml)

endpoints:
  "995f745a-aa8a-491b-85ef-0d4697094b58":
    name: "주식현재가 시세2 [v1_국내주식-065]"
    path: "/uapi/domestic-stock/v1/quotations/inquire-price-2"
    signature: "sha256:a1b2c3..."
    consumers:
      - quote              # ← 이 L0를 사용하는 L1 도메인

  "3eeac674-072d-4674-a5a7-f0ed01194a81":
    name: "해외주식 현재체결가 [v1_해외주식-009]"
    path: "/uapi/overseas-price/v1/quotations/price"
    signature: "sha256:d4e5f6..."
    consumers:
      - quote

268개 endpoint의 구조적 시그니처를 추적합니다.

Pre-commit Hook 연동

# .pre-commit-config.yaml
- id: l0-drift-check
  name: L0 drift detection
  entry: .venv/bin/python scripts/check_l0_drift.py
  files: (src/pykis/api/raw/|src/pykis/service/|data/service/_l0_manifest)

git commit
  ↓
ruff → ruff-format → ty → l0-drift-check
                              ↓
                     exit 0 → ✅ pass
                     exit 1 → ❌ block (L1 consumer 영향)
                     exit 2 → ⚠️ pass (consumer 없는 변동, warning)

6. Store Module (src/pykis/store/, 64 files)

SQLite 기반 마스터 데이터(종목 코드, 거래소 정보 등) 관리.

7. Transport & Client (src/pykis/client/)

• Async-first: /_async/client.py가 canonical source
• Sync auto-generated: scripts/build_unasync.py가 /_sync/ 생성
• Rate limiter, token refresh, retry logic
• asyncio.Lock → threading.Lock 자동 변환

---

Specifications & Governance

문서	역할
specs/project.md	프로젝트 정의
specs/stakeholder-requirements.md	SDK 사용자 요구사항 (SR-xxx)
specs/srs/	시스템 요구사항 (SyRS-xxx)
specs/architecture/layered-model.md	2-Layer 아키텍처
specs/architecture/adr/ADR-012-service-layer.md	L1+L2 통합 결정
specs/governance/	거버넌스 정책

---

Agent Skills

Skill	역할
/service-build	L1 서비스 도메인 구축 5단계 워크플로우
/pipeline-run	codegen 파이프라인 실행 + 검증
/override-review	Override 후보 HITL 승인
/api-audit	KIS API 스펙-실응답 정합성 감사
/explore-kis-api	KIS API 레퍼런스 탐색

---

Stats

영역	파일 수	변경량
L0 Raw Models	294	+59,065
Streaming	71	+10,335
Codegen	67	+14,978
Store	64	new
L1 Service	10	+529
Specs	28	new
Data (API specs)	718	new
Tests	17	+3,465 / -261
Scripts	3	+600
총합	1,487 files	+403,067 / -21,397

---

Test Plan

• pytest — 140 tests passed (11.66s)
• ruff check — clean
• ty check — clean
• L0 drift detection — 268 endpoints baselined, 0 drift
• Pre-commit hooks — ruff + ruff-format + ty + l0-drift-check

Next Steps (Future PRs)

• Chart domain (multi-call orchestration, 해외 12-call 패턴)
• Order + Balance domains (request→response 전사)
• Public API surface (KisClient / KisAsyncClient)
• Integration tests with mock server