# DartLab — DART + EDGAR Disclosure Analysis Python Library

> Turn Korean DART and US SEC EDGAR filings into one structured company map.
> 한국 DART 전자공시와 미국 SEC EDGAR 공시를 하나의 회사 맵으로 바꾸는 Python 라이브러리.

DartLab parses corporate disclosure filings — annual reports, 10-K, 10-Q — into structured,
comparable data. Financial statements (BS/IS/CF), financial ratios, insight grades,
narrative text, and structured reports are all accessible with a single stock code.
Covers Korean DART and US SEC EDGAR listed companies.

## Install

```bash
pip install dartlab
# or
uv add dartlab
```

## Quick Start

```python
import dartlab

# Korean company (DART)
c = dartlab.Company("005930")       # Samsung Electronics
c.index                              # company structure index
c.show("BS")                         # balance sheet
c.show("executiveCompensation")      # topic payload
c.trace("dividend")                  # source provenance
c.ratios                             # 47 financial ratios
c.insights                           # 7-area A~F grades

# US company (EDGAR)
us = dartlab.Company("AAPL")         # Apple Inc.
us.BS                                # balance sheet
us.ratios                            # financial ratios
us.sections                          # 10-K sections map
```

## Key Features

- **Sections-first architecture**: Every company becomes a topic x period DataFrame
- **Dual market**: DART (Korea) + EDGAR (US) with identical interface
- **One stock code**: `dartlab.Company('005930')` or `dartlab.Company('AAPL')`
- **Financial statements**: BS, IS, CF, CIS, SCE — XBRL-normalized, quarterly standalone
- **47 financial ratios**: ROE, ROA, operating margin, debt ratio, PER, PBR, FCF, etc.
- **7-area insight grades**: Performance, profitability, stability, cash flow, governance, risk, opportunity
- **AI analysis**: `dartlab ask '삼성전자 분석해줘'` — natural language company analysis
- **MCP server**: Expose company data as MCP tools for Claude Desktop, ChatGPT, Cursor
- **329 topics per company**: From dividend policy to segment breakdown

## Data Modules

### 시계열 재무제표

- **annual.IS** (손익계산서(연도별)): 연도별 손익계산서 시계열. 매출액, 영업이익, 순이익 등 전체 계정.
- **annual.BS** (재무상태표(연도별)): 연도별 재무상태표 시계열. 자산, 부채, 자본 전체 계정.
- **annual.CF** (현금흐름표(연도별)): 연도별 현금흐름표 시계열. 영업/투자/재무활동 현금흐름.
- **timeseries.IS** (손익계산서(분기별)): 분기별 손익계산서 standalone 시계열.
- **timeseries.BS** (재무상태표(분기별)): 분기별 재무상태표 시점잔액 시계열.
- **timeseries.CF** (현금흐름표(분기별)): 분기별 현금흐름표 standalone 시계열.

### 공시 파싱 모듈

- **BS** (재무상태표): K-IFRS 연결 재무상태표. finance XBRL 정규화(snakeId) 기반, 회사간 비교 가능. finance 없으면 docs fallback.
- **IS** (손익계산서): K-IFRS 연결 손익계산서. finance XBRL 정규화 기반. 매출액, 영업이익, 순이익 등 전체 계정 포함.
- **CF** (현금흐름표): K-IFRS 연결 현금흐름표. finance XBRL 정규화 기반. 영업/투자/재무활동 현금흐름.
- **fsSummary** (요약재무정보): DART 공시 요약재무정보. 다년간 주요 재무지표 비교.
- **segments** (부문정보): 사업부문별 매출·이익 데이터. 부문간 수익성 비교 가능.
- **tangibleAsset** (유형자산): 유형자산 변동표. 취득/처분/감가상각 내역.
- **costByNature** (비용성격별분류): 비용을 성격별로 분류한 시계열. 원재료비, 인건비, 감가상각비 등.
- **dividend** (배당): 배당 시계열. 연도별 DPS, 배당총액, 배당성향, 배당수익률.
- **majorHolder** (최대주주): 최대주주 지분율 시계열. 지분 변동은 경영권 안정성의 핵심 지표.
- **employee** (직원현황): 직원 수, 평균 근속연수, 평균 연봉 시계열.
- **subsidiary** (자회사투자): 종속회사 투자 시계열. 지분율, 장부가액 변동.
- **bond** (채무증권): 사채, CP 등 채무증권 발행·상환 시계열.
- **shareCapital** (주식현황): 발행주식수, 자기주식, 유통주식수 시계열.
- **executive** (임원현황): 등기임원 구성 시계열. 사내이사/사외이사/비상무이사 구분.
- **executivePay** (임원보수): 임원 유형별 보수 시계열. 등기이사/사외이사/감사 구분.
- **audit** (감사의견): 외부감사인의 감사의견과 감사보수 시계열. 적정 외 의견은 중대 위험 신호.
- **boardOfDirectors** (이사회): 이사회 구성 및 활동 시계열. 개최횟수, 출석률 포함.
- **capitalChange** (자본변동): 자본금 변동 시계열. 보통주/우선주 주식수·액면 변동.
- **contingentLiability** (우발부채): 채무보증, 소송 현황. 잠재적 재무 리스크 지표.
- **internalControl** (내부통제): 내부회계관리제도 감사의견 시계열.
- **relatedPartyTx** (관계자거래): 대주주 등과의 매출·매입 거래 시계열. 이전가격 리스크 확인.
- **rnd** (R&D): 연구개발비용 시계열. 기술 투자 강도 판단.
- **sanction** (제재현황): 행정제재, 과징금, 영업정지 등 규제 조치 이력.
- **affiliateGroup** (계열사): 기업집단 소속 계열회사 현황. 상장/비상장 구분.
- **fundraising** (증자감자): 유상증자, 무상증자, 감자 이력.
- **productService** (주요제품): 주요 제품/서비스별 매출액과 비중.
- **salesOrder** (매출수주): 매출실적 및 수주 현황.
- **riskDerivative** (위험관리): 환율·이자율·상품가격 리스크 관리. 파생상품 보유 현황.
- **articlesOfIncorporation** (정관): 정관 변경 이력. 사업목적 추가·변경으로 신사업 진출 파악.
- **otherFinance** (기타재무): 대손충당금, 재고자산 관련 기타 재무 데이터.
- **companyHistory** (연혁): 회사 주요 연혁 이벤트 목록.
- **shareholderMeeting** (주주총회): 주주총회 안건 및 의결 결과.
- **auditSystem** (감사제도): 감사위원회 구성 및 활동 현황.
- **affiliate** (관계기업투자): 관계기업/공동기업 투자 변동 시계열. 지분법손익, 기초/기말 장부가 포함.
- **investmentInOther** (타법인출자): 타법인 출자 현황. 투자목적, 지분율, 장부가 등.
- **companyOverviewDetail** (회사개요): 설립일, 상장일, 대표이사, 주소, 주요사업 등 기본 정보.
- **holderOverview** (주주현황): 5% 이상 주주, 소액주주 현황, 의결권 현황. majorHolder보다 상세한 주주 구성.

### 서술형 공시

- **business** (사업의내용): 사업보고서 '사업의 내용' 서술. 사업 구조와 현황 파악.
- **companyOverview** (회사개요정량): 공시 기반 회사 정량 개요 데이터.
- **mdna** (MD&A): 이사의 경영진단 및 분석의견. 경영진 시각의 실적 평가와 전망.
- **rawMaterial** (원재료설비): 원재료 매입, 유형자산 현황, 시설투자 데이터.
- **sections** (사업보고서섹션): 사업보고서 전체 섹션 텍스트를 topic(행) × period(열) DataFrame으로 구조화. leaf title 기준 수평 비교 가능. 연간+분기+반기 전 기간 포함.

### K-IFRS 주석

- **notes.receivables** (매출채권): K-IFRS 매출채권 주석. 채권 잔액 및 대손충당금 내역.
- **notes.inventory** (재고자산): K-IFRS 재고자산 주석. 원재료/재공품/제품 내역별 금액.
- **notes.tangibleAsset** (유형자산(주석)): K-IFRS 유형자산 변동 주석. 토지, 건물, 기계 등 항목별 변동.
- **notes.intangibleAsset** (무형자산): K-IFRS 무형자산 주석. 영업권, 개발비 등 항목별 변동.
- **notes.investmentProperty** (투자부동산): K-IFRS 투자부동산 주석. 공정가치 및 변동 내역.
- **notes.affiliates** (관계기업(주석)): K-IFRS 관계기업 투자 주석. 지분법 적용 내역.
- **notes.borrowings** (차입금): K-IFRS 차입금 주석. 단기/장기 차입 잔액 및 이자율.
- **notes.provisions** (충당부채): K-IFRS 충당부채 주석. 판매보증, 소송, 복구 등.
- **notes.eps** (주당이익): K-IFRS 주당이익 주석. 기본/희석 EPS 계산 내역.
- **notes.lease** (리스): K-IFRS 리스 주석. 사용권자산, 리스부채 내역.
- **notes.segments** (부문정보(주석)): K-IFRS 부문정보 주석. 사업부문별 상세 데이터.
- **notes.costByNature** (비용의성격별분류(주석)): K-IFRS 비용의 성격별 분류 주석.

### 원본 데이터

- **rawDocs** (공시 원본): 공시 문서 원본 parquet. 가공 전 전체 테이블과 텍스트.
- **rawFinance** (XBRL 원본): XBRL 재무제표 원본 parquet. 매핑/정규화 전 원본 데이터.
- **rawReport** (보고서 원본): 정기보고서 API 원본 parquet. 파싱 전 원본 데이터.

### 분석 엔진

- **ratios** (재무비율): financeEngine이 자동계산한 수익성·안정성·밸류에이션 비율.
- **insight** (인사이트): 7영역 A~F 등급 분석 (실적, 수익성, 건전성, 현금흐름, 지배구조, 리스크, 기회).
- **sector** (섹터분류): WICS 11대 섹터 분류. 대분류/중분류 + 섹터별 파라미터.
- **rank** (시장순위): 전체 시장 및 섹터 내 매출/자산/성장률 순위.
- **keywordTrend** (키워드 트렌드): 공시 텍스트 키워드 빈도 추이 (topic × period × keyword). 54개 내장 키워드 또는 사용자 지정.
- **news** (뉴스): 최근 뉴스 수집 (KR: Google News 한국어, US: Google News 영어). 날짜/제목/출처/URL.

## Analysis Engines

- **Sector classification**: WICS 11 sectors (override -> keyword -> KSIC 3-stage)
- **Insight grades**: 7-area A~F grades (performance, profitability, stability, cash flow, governance, risk, opportunity)
- **Market rank**: Revenue/assets/growth ranking — overall + within sector
- **Financial ratios**: ROE, ROA, operating margin, debt ratio, PER, PBR, FCF — auto-calculated
- **Supply chain**: Disclosed supplier/customer relationship mapping
- **ESG**: ESG disclosure extraction and scoring
- **Event study**: Abnormal return around disclosure dates

## Links

- Documentation: https://eddmpython.github.io/dartlab/docs/
- GitHub: https://github.com/eddmpython/dartlab
- PyPI: https://pypi.org/project/dartlab/
