기업 공시 통합 분석 라이브러리 DartLab 가이드

종목코드 하나로 세상의 모든 공시를 꿰뚫다: 한미 통합 분석 엔진 'DartLab' 사용 설명서

Concept

1. DartLab이란 무엇인가?

주식 시장의 수많은 데이터 속에서 투자 인사이트를 건져 올리기 위해 가장 신뢰할 수 있는 소스는 다름 아닌 기업의 공정 공시입니다. 한국의 K-DART와 미국의 SEC EDGAR 공시는 최고의 팩트 저장소이지만, 서로 다른 포맷과 복잡한 목차 체계 때문에 수평적으로 나란히 놓고 비교하기가 무척 까다로웠습니다.

DartLab은 이 귀찮고 고된 작업을 단 한 줄의 Python 코드로 해결해 주는 오픈소스 라이브러리입니다. 회사마다 각양각색으로 명명해 놓은 XBRL 재무제표 계정과 공시 목차를 자동으로 구조화하여, topic × period와 account × period 형태의 수평적 시계열 데이터 격자로 재배치합니다.

공시 수집·가공의 전후(Before & After) 비교

분석 단계	기존 방식 (Before)	DartLab 방식 (After)
기간 비교	여러 해의 사업보고서를 개별 다운로드하여 목차 대조	c.panel() 호출로 전 기간 한눈에 격자 배치
계정 정밀 매핑	복잡한 표준 XBRL 계정과 한글 항목 직접 대조	c.panel("IS") 호출로 표준 손익계산서 즉시 수합
재무비율 산출	전 종목의 데이터를 크롤링하고 수작업으로 정규화	dartlab.scan("profitability")로 표준화 비율 조회
AI 답변 신뢰성	LLM이 할루시네이션(환각)을 보이며 틀린 숫자 제시	dartlab.ask() 호출 시 실제 계산 근거 레퍼런스 동시 출력

Pathways

2. 어떤 방식으로든 자유롭게: 세 가지 시작점

DartLab은 분석가가 처한 환경과 선호에 맞게 데이터를 다룰 수 있도록 세 가지 핵심 경로를 동시에 제공합니다. 어떤 경로로 접근하든 데이터 조회와 연산의 기반이 되는 내부 엔진은 동일하게 작동합니다.

• AI로 바로 사용 (1분 완정복) : 분석 시나리오 설계와 숫자의 신뢰성 검산에 적합합니다. 질문을 던지면 분석 엔진이 계산 근거가 담긴 ref를 함께 제시합니다.
• Python 코드로 사용 (3분 코드 빌드) : 가공되지 않은 기본 재무제표나 가치 평가 모델, 퀀트 알고리즘을 설계하는 개발자들에게 강력한 인터페이스를 부여합니다.
• CLI(커맨드 라인)로 사용 (2분 스크립트화) : 셸 파이프라인 연동과 단발성 터미널 조회를 원하는 엔지니어들이 셸에서 즉시 데이터 파이프라인을 구축할 수 있게 돕습니다.

진입 경로 요약 표

사용 경로	코드 길이	첫 결과 도출	추천 대상
AI / 자연어	1줄 (질의)	약 1분 이내	근거 중심의 답변이 필요한 비즈니스 분석가
Python API	3~5줄	약 3분 이내	재무 수치와 스캔 데이터를 세부 가공할 개발자
CLI 명령	1 명령	약 2분 이내	셸 자동화 스크립트 작성 및 빠른 조회 희망자

Usage - Python

3. Python 코드로 실전 활용하기

기본적인 사용은 매우 심플합니다. 별도의 복잡한 API 키 발급이 전혀 필요 없으며, 사전 정제된 대용량 공시 데이터는 HuggingFace 저장소로부터 로컬 환경에 자동으로 다운로드 및 캐싱됩니다.

import dartlab

# 1. 기업분석의 중심이 되는 Company 객체 생성 (예: 삼성전자)
c = dartlab.Company("005930")

# 2. 전체 공시를 항목 x 기간 형태의 시계열 격자로 정렬
c.panel()

# 3. 정규화된 표준 손익계산서(IS) 호출
c.panel("IS")

# 4. 사업보고서 항목 그대로의 손실 및 이익 데이터 호출 (2013년~)
c.panel("is")

# 5. 핵심 재무비율 조회
c.panel("ratios")

# 6. 사업의 개요 등 공시 본문에서 텍스트 행 검색
c.panel("사업")

DartLab의 진짜 놀라운 점은 다국적 통합 인터페이스를 지원한다는 점입니다. 한국 기업(DART)과 미국 기업(EDGAR)을 호출할 때 개발자가 느끼는 코드상의 장벽이 완벽히 사라집니다.

kr = dartlab.Company("005930")  # 삼성전자
us = dartlab.Company("AAPL")    # 애플

# 국가 구분 없이 일관성 있는 호출 인터페이스 제공
kr.panel("IS")
us.panel("IS")

Deep Dive

4. 총액 이면의 비밀을 풀다: 12대 주석(Notes) 토픽

재무상태표($\text{BS}$)나 손익계산서($\text{IS}$)상의 단순 총합만으로는 기업의 진짜 속사정을 파악하기 어렵습니다. DartLab은 K-IFRS HTML 파싱 엔진과 US-GAAP XBRL 태그 처리 기술을 통해 재무제표 주석에 숨겨진 세부 명세까지 완벽하게 분해하여 제공합니다.

토픽 명칭(Topic)	분석 대상 및 제공 정보	DART (KO)	EDGAR (US)
"inventory"	원재료, 재공품, 제품 등의 재고자산 상세 분해	✅ 지원	✅ 지원
"borrowings"	단기 및 장기 차입금, 사채 등의 조달 구성 요소	✅ 지원	✅ 지원
"tangibleAsset"	유형자산 취득원가, 감가상각 누계액, 장부가액 추이	✅ 지원	✅ 지원
"intangibleAsset"	영업권, 개발비 등의 무형자산 구성과 상각	✅ 지원	✅ 지원
"receivables"	매출채권 총액 및 대손충당금 설정 현황 분석	✅ 지원	✅ 지원
"provisions"	보증 비용, 소송 저지용 충당부채 현황	✅ 지원	✅ 지원
"eps"	기본주당이익과 희석주당이익 계산 상세	✅ 지원	✅ 지원
"segments"	사업 부문별 세부 매출 및 이익 기여도 분석	✅ 지원	✅ 지원
"costByNature"	원재료, 종업원 급여, 감가상각 등 성격별 비용 분류	✅ 지원	✅ 지원
"lease"	사용권자산과 관련된 리스 부채 분석	✅ 지원	✅ 지원
"affiliates"	관계기업 지분법 투자주식 명세 정보	✅ 지원	✅ 지원
"investmentProperty"	투자부동산의 공정가치 및 장부가액 추이	✅ 지원	✅ 지원

System Architecture

5. 세 겹으로 쌓아 올린 DartLab 분석 프레임워크

DartLab은 단순히 날것의 로 데이터를 가져오는 스크래핑 도구가 아닙니다. 정확성, 인과 관계, 입체적 정황을 보장하기 위해 체계적으로 설계된 다차원 분석 아키텍처를 자랑합니다.

분석 엔진의 세 가지 레이어

• 분석 엔진 (L2~L3) : 마진 흐름, 현금 흐름 분석, 신용부도 예측 모델($\text{dCR}$ 모델 및 부도 확률 계산), 국가 거시 경제 지표($\text{Macro}$) 등의 정량적 수치 및 근거 원본을 가공하고 조율합니다.
• 스토리 조합기 (L3 Story) : L2의 개별 엔진들이 순환 참조를 발생시키지 않도록 분리하고 결합 책임을 지는 단독 모듈입니다. 수집 가공된 지표 블록들을 시계열에 맞춰 유기적으로 엮어 6막 스토리텔링 보고서로 탈바꿈시킵니다.
• 자율적 AI (L4 Ask) : 결과를 맹신하지 않고, LLM이 직접 파이썬 코드를 실행하여 얻은 계산 결과 원문과 이상 징후를 교차 확인하며 적극적으로 가정을 수정·보완해 가는 도구 세트입니다.

기업 간 격차 극복 기술 (Compare Engine)

서로 다른 회사 간의 비교 시 흔히 발생하는 라벨 어긋남(Label Drift)을 자동으로 무력화합니다. 예를 들어 삼성전자의 '7. 유형자산' 항목과 SK하이닉스의 '11. 유형자산' 항목이 서로 다른 절 번호를 갖고 있더라도, 의미론적으로 동일 계정임을 판단하여 한 개의 행으로 매끄럽게 정렬해 냅니다.

DartLab-Lite

6. 설치 없이 엑셀과 웹에서 즉시 사용하는 'Pyodide'

로컬 PC에 파이썬을 설치하지 않았거나, 개발 환경 구성이 어려운 분석가들을 위해 WebAssembly로 이식된 dartlab-lite 버전을 제공합니다. 엑셀 워크북(xlwings Lite, Anaconda Code), Google Colab WASM 등에서 가벼운 패키지 설치 한 줄로 네이티브 성능 그대로 이용할 수 있습니다.

엑셀에서 사용하는 수식형(@func)의 환상적인 생산성

파이썬 가상환경 세팅 없이도, 엑셀 셀 안에 수식 형태로 함수를 선언해 시트에 즉각적으로 전 분기 재무제표가 채워지는 역동적인 자동 스필 기능을 구현할 수 있습니다.

# 엑셀 셀에 =GETFINANCE("005930")만 쳐도 5개 분기 IS 정보가 셀에 즉시 안착!
@func
def getFinance(code: str):
    c = dartlab.Company(code)
    df = c.panel('IS')
    data = [list(df.columns)] + [list(r) for r in df.iter_rows()]
    return data

이러한 접근성은 기존 기업 회계 담당자나 전업 투자자들에게 장벽이 낮고 강력한 데이터 자유도를 선사합니다.

Future & Collaboration

7. AI 어시스턴트(MCP)와의 시너지, 그리고 기여하기

DartLab은 최신 MCP(Model Context Protocol) 서버를 내장하고 있습니다. 이를 통해 Claude Desktop, Claude Code, Cursor 등 외부 LLM 분석가 어시스턴트에게 라이브러리를 직접 제공하여 효율적인 데이터 연산 및 챗 루프를 돌릴 수 있게 해줍니다.

가치를 창출하는 재투자가 성공적으로 일어나는 기업인지 여부($\text{ROIC} > \text{WACC}$), 매출 및 영업이익률의 반등 여부($8.6\% \rightarrow 21.4\%$) 등을 AI 비서가 스스로 코드를 기동하며 수학적 검증을 거친 뒤 고품질 보고서를 우리에게 선사하는 미래적 작업 환경을 구현해 보십시오.

아파치 2.0 라이선스로 배포되는 이 위대한 오픈소스 프로젝트에 여러분만의 고유한 분석 아이디어를 더해보는 것도 권장합니다.