Cluefin
한국 금융 투자 분석 툴킷. KIS/키움/NH PLUG/DART API 클라이언트, 기술적 분석, ML 예측을 제공합니다.
이 프로젝트는 교육 및 연구 목적으로만 제공됩니다. 금융 자문을 구성하지 않으며 어떤 결과도 보장하지 않습니다.
빠른 시작
brew install lightgbm # macOS 시스템 의존성
git clone https://github.com/kgcrom/cluefin.git && cd cluefin
uv sync --all-packages
cp packages/cluefin-openapi/.env.sample .env # API 키 설정사전 요구사항: uv, Python 3.11+
프로젝트 구조
uv 워크스페이스 모노레포:
| 패키지 | 설명 |
|--------|------|
| cluefin-openapi | KIS/키움/NH PLUG/DART Python API 클라이언트 (Pydantic, 속도 제한, 인증, 웹소켓) |
| cluefin-openapi-ts | KIS/키움/NH PLUG TypeScript API 클라이언트 (Node 20+, Zod, ESM/CJS) |
| cluefin-ta | 순수 Python 기술적 분석 (TA-Lib 호환, 38개 함수) |
| cluefin-xbrl | DART XBRL 재무제표 파서 |
| cluefin-dart-notes | DART 공시 원문(dart4 XML) 파서 — 섹션·표·주석 노트 (XBRL에 없는 서술형 내용) |
| cluefin-sec-notes | SEC EDGAR 공시 원문 파서 — 10-K/10-Q/8-K HTML의 Item 단위 본문, Form 3·4·5 내부자 소유 신고·13F 기관 보유 보고(XML) |
| cluefin-openapi-cli | Agent-friendly broker CLI (list, describe, broker-first command path) |
| cluefin-desk | TUI 대시보드 (기술적 분석, KIS·DART·XBRL 재무, LightGBM + SHAP 예측) |
개발
uv run lefthook install # Git hooks 설정 (최초 1회)
uv run pytest -m "not integration and not slow" # 단위 테스트 (빠른 로컬 체크)
uv run pytest -m integration # 통합 테스트 (API 키 또는 외부 provider 사이트 의존)
uv run ruff format . && uv run ruff check . --fix # 린트TypeScript (cluefin-openapi-ts)
cd packages/cluefin-openapi-ts
npm install && npm run build
npm run check && npm run test:unitGit Hooks (Lefthook)
| Hook | 대상 | 실행 내용 |
|------|------|-----------|
| pre-commit | *.py | ruff format --check + ruff check (자동 수정 없음) |
| pre-commit | *.{ts,tsx,js} | biome check |
| pre-push | *.py | pytest (integration·slow 제외) |
| pre-push | *.{ts,tsx,js} | vitest (단위 테스트) |
npm 배포 (cluefin-openapi-ts)
cd packages/cluefin-openapi-ts
npm version patch
npm run publish:check && npm pack --dry-run
npm publish --access public