Dartlab

DartLab

종목코드 하나. 기업의 전체 이야기. Korean DART + US SEC EDGAR 공시를 한 줄의 Python 으로 읽고 비교한다.

문서 · Skill OS · Skill Market · 블로그 · Colab에서 열기 · Molab에서 열기 · English · 후원

  

터미널: 블룸버그식에 도전하다

종목 하나로 재무·주가·공시·신용·산업·매크로를 한 화면에서 읽는 블룸버그식 터미널에 도전하는 DartLab 터미널. 라이브러리가 만든 비교 가능한 데이터를 그대로 화면 위에 올렸다.

> 이 터미널은 @youngchangjo 님의 스레드에서 받은 영감으로 시작됐습니다.

DartLab 무엇을 해주는가

DartLab은 DART와 EDGAR 공시를 종목코드 하나로 비교 가능한 데이터로 바꾸는 Python 라이브러리다. 재무제표, 사업보고서 본문, 공시 목록, 비율, 신용위험, 산업 맵, 매크로 맥락을 같은 Company 인터페이스로 읽는다.

핵심은 단순 수집이 아니다. 회사마다 다른 계정명과 공시 목차를 topic × period, account × period 형태로 수평화해서 작년과 올해, 삼성전자와 애플, 한 종목과 전체 시장을 같은 질문으로 비교하게 만든다.

| Before | After | |---|---| | 사업보고서 여러 해를 열고 목차를 맞춘다 | c.panel() | | XBRL 계정명과 한글 항목명을 직접 매핑한다 | c.panel("IS") | | 전 종목 재무비율을 직접 수집·정규화한다 | dartlab.scan("profitability") | | AI 답변의 숫자를 다시 검산한다 | dartlab.ask(...) + 실행 근거 ref |

세 가지 시작점

DartLab은 AI / Python / CLI 세 길을 같은 데이터·같은 엔진 위에 올려놓는다. 자기 맥락에 맞는 길로 진입하면 된다.

| 사용 방식 | 코드 길이 | 첫 결과 | 이런 사람에게 맞다 | |---|---|---|---| | [AI로 바로 사용](#ai로-바로-사용) | 1 줄 | ~1 분 | 질문을 던지고 근거 있는 답변을 받고 싶은 분석가 | | [Python 코드로 사용](#python-코드로-사용) | 3-5 줄 | ~3 분 | 재무제표·공시·스캔 데이터를 직접 다루는 개발자 | | [CLI 로 사용](#cli-로-사용) | 1 명령 | ~2 분 | 단발 조회·자동화 스크립트·셸 파이프라인 사용자 |

각 경로는 모두 dartlab.Company 와 같은 분석 엔진을 호출한다. 출발점만 다를 뿐 결과는 같다.

AI로 바로 사용

기업 이름이나 종목코드를 넣고 자연어로 물어보면, DartLab AI는 내부에서 Company, analysis, credit, scan, macro 같은 도구를 직접 실행한다. 답변만 만드는 것이 아니라 어떤 데이터와 계산을 썼는지 추적 가능한 ref를 함께 남긴다.

import dartlab

dartlab.ask("삼성전자 재무건전성 분석해줘")
# AI가 필요한 데이터를 직접 조회하고, 계산 결과와 근거 ref를 함께 반환

AI 경로의 장점:

• 분석 흐름을 직접 설계: 질문에 맞춰 공시, 재무제표, 신용, 매크로, peer 비교 도구를 조합한다.
• 숫자 검산 가능: 답변 속 숫자와 표는 실행 결과 ref에 연결된다.
• 공시 본문은 데이터로만 처리: DART/EDGAR/웹 본문 안의 지시는 따르지 않고 분석 근거로만 쓴다.
• 외부 LLM 연동 가능: MCP로 Claude Code, Codex CLI, Cursor 같은 도구에서 같은 표면을 호출한다.

claude mcp add dartlab -- dartlab mcp
codex  mcp add dartlab -- dartlab mcp

> Claude Desktop · 원격 SSE · 절대 경로 옵션은 [MCP 섹션](#mcp--ai-어시스턴트-연동) 참조.

Python 코드로 사용

코드 경로는 Company가 중심이다. 종목코드 하나로 재무제표, 공시 본문, 정형 보고서, 비율을 c.panel 단일 표면에서 같은 방식으로 호출한다. c.panel 을 잡는 순간 항목×기간 격자가 된다.

uv add dartlab

import dartlab

c = dartlab.Company("005930")       # 삼성전자

c.panel()                           # 전체 공시 수평화 격자 (항목 × 기간)
c.panel("IS")                       # 손익계산서 (finance 정규화 숫자)
c.panel("is")                       # native 손익 — 사업보고서 항목 그대로 (XBRL+옛 통합 2013~)
c.panel("ratios")                   # native 재무비율 (5표 항목으로 계산)
c.panel("사업")                      # 사업 개요 등 공시 본문 행 검색
c.filings()                         # 원문 공시 링크

# 같은 인터페이스, 다른 시장
kr = dartlab.Company("005930")
us = dartlab.Company("AAPL")

kr.panel("IS")
us.panel("IS")

Python 경로의 장점:

• API 키 없이 시작: 사전 구축 데이터는 HuggingFace에서 자동 다운로드하고 로컬에 캐시한다.
• 기간 비교가 기본: 공시 본문과 재무제표를 기간 축으로 맞춘다.
• 한국과 미국을 같은 인터페이스로 조회: DART와 EDGAR의 차이는 provider가 흡수한다.
• 엔진 결과를 재사용 가능: analysis, credit, macro, quant, industry, story 결과를 코드에서 직접 다룬다.

CLI 로 사용

설치 후 셸에서 dartlab 명령으로 같은 엔진을 호출한다. 단발 조회·셸 자동화·파이프라인 친화적.

uv add dartlab

dartlab help "외인 매수"            # 도움말 + 매칭 capability 탐색
dartlab list scan                    # scan 카테고리 recipe 인덱스
dartlab show 005930 IS               # 손익계산서 출력 (Python c.panel("IS") 등가)
dartlab analyze 005930 --aspect credit
dartlab mcp                          # MCP 서버 진입 (외부 LLM 도구 등록용)

CLI 경로의 장점:

• API 키 없이 단발 호출: HuggingFace 캐시 자동 사용
• 셸 파이프라인 친화: dartlab show ... --json | jq ... 식으로 합성
• MCP 서버 진입점 동일: dartlab mcp 한 명령으로 외부 어시스턴트 도구 노출

> CLI 명령 전체 목록 + 옵션은 dartlab --help 또는 Skill OS (src/dartlab/skills/specs/operation/code.md) 참조.

결과 예시

아래는 Python 경로에서 바로 얻는 대표 결과다. 공시 본문, 재무제표, 원문 링크가 같은 Company 객체에서 나온다.

import dartlab

c = dartlab.Company("005930")       # 삼성전자

c.panel()                           # 모든 항목, 모든 기간, 나란히 — 잡는 순간 격자
# shape: (223, 14) — 공시 항목 × 기간
#                     2026Q1  2025Q4  2025Q3  2024Q4  ...
# (표지)                  v       v       v       v
# 사업의 내용             v       v       v       v
# 재무상태표              v       v       v       v

> 텍스트와 숫자의 시계열 수평화: 전 기간 비교 가능성의 핵심 > >

c.panel("IS")                       # 손익계산서 — finance 정규화 (분기 기본)
c.panel("IS", freq="year")          # freq로 연간 합산

> finance 정규화: XBRL 표준계정(snakeId) + 한글 항목명, 원 단위 정밀 숫자 > >

c.panel("is", freq="year")          # native 손익 — 사업보고서 항목 그대로 (2013~)
c.panel("ratios")                   # native 재무비율, 5표 항목으로 계산

> 소문자=native: 사업보고서 항목 그대로, XBRL 이전까지 닿는 깊은 history (2013~) > >

c.panel("사업")                      # 사업 개요 등 공시 본문 행 검색
c.panel.search("재고")               # 본문 전체 검색

c.filings()                         # 모든 보고서 — DART 뷰어로 바로 연결

> 사업보고서부터 분기보고서까지, dartUrl로 원문 즉시 확인 > >

# 같은 인터페이스, 다른 나라
us = dartlab.Company("AAPL")
us.panel("business")
us.panel("ratios")

# 자연어로 질문
dartlab.ask("삼성전자 재무건전성 분석해줘")
# → AI가 코드를 실행하며 분석: "영업이익률이 8.6%→21.4%로 반등..."

API 키 불필요. HuggingFace에서 자동 다운로드, 로컬 캐시로 즉시 로드.

세 겹의 분석

Company가 종목코드 하나로 데이터를 준비하면, 세 겹이 분석한다.

1. 분석 엔진: 숫자를 만든다. 마진 추이, 현금흐름 패턴, 부도 확률, 업종 비교, 매크로 사이클. 해석하지 않는다. 숫자와 근거만 제공한다.
2. story (L3 조합기): 분석엔진 X. L2 5 분석엔진 끼리의 import 순환을 막기 위해, story 가 단독으로 다중 결합 책임을 짊어진다. 엔진 데이터를 블록 단위로 조합하여 11가지 보고서 타입 × 7가지 기업유형 템플릿. 해석은 제공하지 않는다. 다양한 관점의 근거를 체계적으로 배치한다.
3. AI: 엔진을 직접 쓰고 판단한다. 결과를 의심하고, 원본으로 검증하고, 이상하면 가정을 바꿔서 재계산한다. dartlab을 대표하는 적극적 분석가.

DartLab은 무엇인가

하나의 호출 계약. dartlab.엔진() 으로 가이드 보고 dartlab.엔진("축") 으로 실행.

> 처음이라면? Company → Story → Ask 순서로. 종목코드로 데이터를 보고, 보고서를 만들고, AI에게 물어본다.

> 엔진 이름을 클릭하면 사용법 4 섹션 (공개 호출 방식 · 호출 동작 · 대표 반환 형태 · 기본 검증) 으로 진입한다. 모든 엔진이 같은 4 섹션을 갖는다.

| 레이어 | 엔진 | 하는 일 | 진입점 | 노트북 | |--------|------|---------|--------|--------| | Data | Data | HuggingFace 사전 구축, 자동 다운로드 | Company("005930") | — | | L1 | Company | provider facade: 공시 + 재무제표 + 정형 데이터를 종목코드 하나로 통합 | c.panel() | Colab · marimo | | L1 | Gather | 외부 시장 데이터 (주가/수급/매크로/뉴스) | dartlab.gather() | Colab · marimo | | L1.5 | Scan | 전 종목 사전 빌드 (거버넌스/비율/현금흐름 등 parquet) | dartlab.scan() | Colab · marimo | | L2 | Analysis | 재무 심층 분석 (수익성/안정성/현금흐름) + 가치평가 + 전망 | c.analysis("financial", "수익성") | Colab · marimo | | L2 | Quant | 가격 기반 정량 신호 (기술/리스크/팩터/백테스트) | c.quant() | Colab · marimo | | L2 | Credit | 독립 신용평가 (dCR 등급, 부도확률, 건전도) | c.credit("등급") | Colab · marimo | | L2 | Macro | 시장 레벨 매크로 (사이클/금리/유동성/심리/자산 + 시나리오 110) | dartlab.macro("사이클") | Colab · marimo | | L2 | Industry | 산업 매퍼: 전 상장사 × 공정·역할·스트림 + 공급망 엣지 (산업지도 /map) | c.industry(), dartlab.industry("semiconductor") | — | | L3 | Story | 조합기 (분석엔진 X): L2 5엔진 (analysis · credit · macro · quant · industry) + L1.5 scan 블록 조합. 순환참조 방지 책임자. 11 타입 × 7 템플릿 (해석 안 함) | c.story("수익성") | Colab · marimo | | L4 | AI/Skills | skills 검색 + DartLab 실행 + ref 검산을 쓰는 분석 작업대 (사람도 L4) | dartlab.ask() | Colab · marimo | | L4 | Channel | 외부 공유: dartlab channel 한 줄로 폰에서 PC dartlab 사용 | dartlab channel | — | | core | Search | 공시 시맨틱 검색 (beta: 인덱스 신선도 부족) | dartlab.search() | Colab · marimo | | facade | Listing | 종목/공시/topic 카탈로그 API | dartlab.listing() | Colab · marimo | | viz | Viz | 차트/다이어그램 (emit_chart) | emit_chart({...}) | — |

> 모든 노트북: [marimo](notebooks/marimo/) · [colab](notebooks/colab/) · [](https://marimo.app/github.com/eddmpython/dartlab/blob/master/notebooks/marimo)

Company

> 설계: engines.company

세 가지 데이터 소스(docs=전문 공시, finance=XBRL 재무제표, report=DART API 정형 데이터)를 하나의 객체로 통합. HuggingFace에서 자동 다운로드, 설정 불필요.

c = dartlab.Company("005930")

c.panel()                       # 잡는 순간 격자 -- 공시 항목 × 기간 전체
c.panel("BS")                   # 재무상태표 -- finance 정규화 숫자
c.panel("bs")                   # native 재무상태표 -- 사업보고서 항목 그대로 (2013~)
c.panel("ratios")               # native 재무비율 -- 5표 항목으로 계산
c.panel("매출")                  # 항목명 행 검색 (raw 공시)

주석(Notes): BS/IS 총액 이면의 항목별 분해. c.panel("topic")으로 재무제표와 같은 패턴으로 접근. DART(K-IFRS HTML 파싱)와 EDGAR(US-GAAP XBRL 태그) 동일 인터페이스.

| c.panel(...) | 내용 | DART | EDGAR | |---------------|------|:----:|:-----:| | "inventory" | 원재료/재공품/제품 분해 | ✅ | ✅ | | "borrowings" | 단기/장기 차입금 분해 | ✅ | ✅ | | "tangibleAsset" | 유형자산 취득원가/감가상각/장부가 | ✅ | ✅ | | "intangibleAsset" | 영업권/개발비 등 | ✅ | ✅ | | "receivables" | 매출채권 + 대손충당금 | ✅ | ✅ | | "provisions" | 보증/소송/구조조정 충당부채 | ✅ | ✅ | | "eps" | 기본/희석 주당이익 | ✅ | ✅ | | "segments" | 부문별 매출/이익 | ✅ | ✅ | | "costByNature" | 원재료/급여/감가상각 성격별 비용 | ✅ | ✅ | | "lease" | 사용권자산/리스부채 | ✅ | ✅ | | "affiliates" | 관계기업 지분법 투자 | ✅ | ✅ | | "investmentProperty" | 투자부동산 공정가치/장부가 | ✅ | ✅ |

> [](https://marimo.app/github.com/eddmpython/dartlab/blob/master/notebooks/marimo/01company.py) [](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/colab/01company.ipynb)

Scan: 전 종목 횡단 비교

> 설계: engines.scan

전 종목 대상 횡단 분석. 거버넌스, 인력, 주주환원, 부채, 현금흐름, 감사, 내부자, 이익의 질, 유동성, 네트워크, 계정/비율 비교 등.

dartlab.scan("governance")            # 전종목 지배구조
dartlab.scan("ratio", "roe")          # 전종목 ROE
dartlab.scan("account", "매출액")      # 전종목 매출액 시계열

> 2,500+ 종목의 매출액을 한 번에: 분기별 시계열로 즉시 비교 > >

Compare: 회사 간 N사 비교

> 설계: engines.panel

Company.panel이 한 회사를 항목×기간으로 수평화한다면, dartlab.compare는 2~6개 회사를 같은 토픽·시점 격자로 정렬한다. scan처럼 단어 하나로 부르는 톱레벨 verb: 회사 간 비교의 공식 표면이다.

import dartlab

# 주석·서술 비교 — disclosureKey·scope·leafType 정렬키로 회사 간 한 행 정렬
dartlab.compare(["005930", "000660"], topic="재고")

# 재무제표 셀 비교 — acode 단위, 값은 원 환산 (단위·라벨 착시 제거)
dartlab.compare(["005930", "000660"], topic="is", freq="year")

# 다기간 — 셀 컬럼이 {code}␟{period} 로 회사·시점 namespace
dartlab.compare(["005930", "000660"], topic="유형자산", period=["2025Q4", "2024Q4"])

• label-drift 자동 해소: 같은 항목이 회사마다 다른 절 번호(삼성 "7. 유형자산" ↔ SK "11. 유형자산")여도 한 행에 정렬한다.
• 확신 오정렬 차단: 연결↔별도(scope)·표↔서술(leafType)이 다르면 같은 행에 병치하지 않는다.
• 결손은 NaN 유지: 0 채움·forward-fill 없이 빈 칸을 그대로 둔다(honest-gap, 추세 왜곡 방지).
• 시장 경계: KO↔US 혼합은 막는다. US(EDGAR)는 현재 row 비교만, 재무 셀 비교는 DART(원 환산)만 열려 있다.

Gather: 외부 시장 데이터

> 설계: engines.gather

주가, 수급, 거시지표, 뉴스를 Polars DataFrame으로.

dartlab.gather("price", "005930")             # KR OHLCV
dartlab.gather("price", "AAPL", market="US")  # US 주가
dartlab.gather("macro", "FEDFUNDS")           # 자동 US 감지
dartlab.gather("news", "삼성전자")             # Google News RSS

대량 데이터 batch 순회: 인사이더 거래·지분·뉴스를 generator 로 분할 yield (메모리 안전, 전 종목 스캔용):

from dartlab.gather.accessors import DefaultFinanceAccessor
a = DefaultFinanceAccessor()
for batch in a.iterNews("삼성전자", days=30, batchSize=100):
    process(batch)
# 동행: a.iterInsiderTrades("005930") · a.iterOwnership("005930")
# 일괄: a.fetchInsiderTrades / fetchOwnership / fetchNews

getDefaultGather() 싱글턴은 thread-safe (멀티스레드 환경 단일 인스턴스 보장). 캐시 통계·source fallback 신호는 getCacheStatsSnapshot() · DARTLAB_TELEMETRY=stdout 으로 추적.

Analysis: 재무 인과 분석

> 설계: engines.analysis

수익구조 → 수익성 → 성장성 → 안정성 → 현금흐름 → 자본배분 → 가치평가 → 전망. 원본 재무제표를 인과 서사로 가공한다.

c.analysis("financial", "수익성")       # 수익성 분석
c.analysis("수익성")                     # 단축형 (financial 자동)

print(c.credit())                            # 사용 가능한 축 가이드 DataFrame (self-discovery)
c.credit("등급")                             # dCR-AA, 건전도 93/100
c.credit("등급", detail=True)                # 등급 + 서사 + 지표 시계열

Credit: 독립 신용분석

> 설계: engines.credit | 보고서: eddmpython.github.io/dartlab/blog/credit-reports

3-Track 모델(일반/금융/지주) + Notch Adjustment + CHS 시장 보정 + 별도재무 블렌딩.

79개사 검증: 대기업 87% (26/30), 중대형 82% (41/50), 전체 70% (55/79, v5.0 과대평가 수정 후 재측정 예정). 삼성전자 AA+ 정확 일치. 검증 방법론은 methodology 참조.

print(c.credit())            # self-discovery — 사용 가능한 축 + 종합 등급

cr = c.credit("등급")        # 종합 등급
print(cr["grade"])          # dCR-AA+
print(cr["healthScore"])    # 96 (0-100, 높을수록 건전)
print(cr["pdEstimate"])     # 0.01% 부도확률

cr = c.credit("등급", detail=True)  # 등급 + 서사 + 지표 + 괴리 설명
print(cr["divergenceExplanation"])  # 신평사와 왜 다른지

신용분석 보고서 발간 (credit 서사 + 신평사 대조가 story 5막에 자동 통합):

from dartlab.story.publisher import publishReport
publishReport("005930")               # 6막 보고서 (credit narrative + audit 포함)

Macro: 종목코드 없

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: eddmpython
• Source: eddmpython/dartlab
• License: Apache-2.0
• Homepage: https://eddmpython.github.io/dartlab

Install and usage instructions live in the source repository linked above.