Beyond the numbers — Extract both financials and text from DART filings
DartLab is a Python package for parsing and analyzing DART (Data Analysis, Retrieval and Transfer System) — Korea's official electronic disclosure system. Its stable core is built around DART company analysis, with a unified dartlab.Company(...) facade, CLI, and AI web interface on top.
Today, the package message is simple: DART core is the stable default, while EDGAR and mixed-market paths are still expansion tracks. DartLab extracts both financial numbers and narrative text from corporate filings and exposes them through comparable tables, company facades, and CLI workflows.
Every listed company in Korea reports financials through XBRL, but each company uses different account IDs and names for the same economic concept. "Revenue" alone appears as dozens of variations across 2,700+ companies.
DartLab maintains its own unified account schema — built through a 7-stage mapping pipeline covering 34,000+ learned synonyms. The result: 98.7% of all financial statement rows (15.8 million rows tested) across 2,700+ companies are successfully mapped to standardized accounts. This means you can directly compare Samsung Electronics' revenue with any other listed company using the same revenue key.
Raw XBRL (company-specific) DartLab (standardized)
───────────────────────────── ──────────────────────
ifrs-full_Revenue → revenue
dart_OperatingIncomeLoss → operating_income
dart_ConstructionRevenue → revenue
ifrs_ProfitLoss → net_income
매출액, 수익(매출액), 영업수익 → revenue
One stock code is all you need. 40 modules extract structured DataFrames from disclosure filings — financial statements, notes, dividends, executives, governance, risk, and narrative text. All accessed through simple properties on a Company object, following the yfinance-style API.
uv is required — a fast Python package manager written in Rust. It handles Python version management and virtual environments automatically.
# 1. Install uv (skip if already installed)
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Create a project
uv init my-analysis && cd my-analysis
# 3. Install DartLab — pick the extras you need
uv add dartlab # Core (financial statement parsing)
uv add dartlab[ai] # + AI analysis web interface (dartlab ai)
uv add dartlab[llm] # + OpenAI/Ollama LLM (CLI analysis)
uv add dartlab[charts] # + Plotly charts
uv add dartlab[all] # Everything
# 4. Verify
uv run python -c "import dartlab; c = dartlab.Company('005930'); print(c.corpName)"
# → 삼성전자
# 5. Launch AI analysis (requires dartlab[ai])
uv run dartlab ai
# → http://localhost:8400import dartlab
c = dartlab.Company("005930") # by stock code
c = dartlab.Company("삼성전자") # by company name (Korean)
c.corpName # "삼성전자"
# EDGAR path exists through the same facade, but DART remains the stable default
c = dartlab.Company("AAPL")Creating a Company object prints a usage guide. For the full guide, call c.guide().
Data is auto-downloaded from GitHub Releases when not found locally.
from dartlab.core.dataLoader import downloadAll
downloadAll("docs") # 260+ companies — disclosure documents
downloadAll("finance") # 2,700+ companies — financial numbers
downloadAll("report") # 2,700+ companies — periodic reports
downloadAll("finance", forceUpdate=True) # re-download if remote is newerThe dartlab command is a public interface, not just a helper for the web UI.
uv run dartlab status
uv run dartlab setup codex
uv run dartlab ask 005930 "Summarize debt risk"
uv run dartlab excel 005930
uv run dartlab aidartlab ai launches the web interface. ask, status, setup, and excel are supported CLI commands with stable entrypoint behavior.
The current public flow is simple:
indexshows the company structure firstshow(topic)opens the actual payloadtrace(topic)explains whetherdocs,finance, orreportwon
import dartlab
c = dartlab.Company("005930")
c.index # structure index dataframe
c.show("BS") # show one topic
c.trace("dividend") # source trace
c.docs.sections # pure docs source spine
c.finance.BS # authoritative financial statement
c.report.dividend # authoritative report seriesprofile is intentionally held back for a future report-style view. The plan is a terminal/notebook-friendly company report that emphasizes change points instead of repeating unchanged text.
c.BS # Balance Sheet (DataFrame)
c.IS # Income Statement (DataFrame)
c.CIS # Comprehensive Income Statement (DataFrame)
c.CF # Cash Flow Statement (DataFrame)
c.SCE # Statement of Changes in EquityEvery company's XBRL data is mapped through the unified account schema (98.7% coverage), then converted to standalone quarterly time series. Cumulative figures from semi-annual and annual reports are reverse-engineered into individual quarters.
series, periods = c.timeseries
# periods = ["2016_Q1", "2016_Q2", ..., "2024_Q4"]
# series["IS"]["revenue"] # quarterly revenue
# series["BS"]["total_assets"] # quarterly total assets
# series["CF"]["operating_cashflow"] # quarterly operating cash flow
r = c.ratios
r.roe # 8.29 (%)
r.operatingMargin # 9.51 (%)
r.debtRatio # 27.4 (%)
r.fcf # Free Cash Flow (KRW)2,700+ listed companies share the same snakeId schema. Compare any two companies directly — no manual mapping required.
Extracts summary financial time series, automatically tracking accounts even when names change due to K-IFRS revisions.
result = c.fsSummary()
result.FS # Full financial time series (Polars DataFrame)
result.BS # Balance Sheet
result.IS # Income Statement
result.allRate # Overall match rate (e.g. 0.97)
result.breakpoints # List of detected breakpointsc.notes.inventory # Inventories
c.notes["재고자산"] # Korean key also works
c.notes.receivables # Trade receivables
c.notes.tangibleAsset # Property, plant & equipment
c.notes.intangibleAsset # Intangible assets
c.notes.investmentProperty # Investment property
c.notes.affiliates # Associates
c.notes.borrowings # Borrowings
c.notes.provisions # Provisions
c.notes.eps # Earnings per share
c.notes.lease # Leases
c.notes.segments # Operating segments
c.notes.costByNature # Expenses by naturec.dividend
# ┌──────┬───────────┬───────┬──────────────┬─────────────┬──────────────┬──────┐
# │ year ┆ netIncome ┆ eps ┆ totalDividend┆ payoutRatio ┆ dividendYield┆ dps │
# └──────┴───────────┴───────┴──────────────┴─────────────┴──────────────┴──────┘c.majorHolder # Largest shareholder + related parties ownership (time series)For the full Result object: c.get("majorHolder")
result = c.get("majorHolder")
result.majorHolder # "이재용"
result.majorRatio # 20.76
result.timeSeries # Ownership ratio time seriesc.employee # year, totalEmployees, avgSalary, avgTenure, ...c.sections # merged topic x period company table
c.index # same structure index dataframe
c.docs.sections # pure docs horizontalization source
c.retrievalBlocks # long DataFrame of source markdown blocks
c.contextSlices # LLM-ready slices with semantic/detail metadatasections is the company spine. Columns are time series. The row structure
comes from disclosure sections, then finance fills BS / IS / CIS / CF / SCE
and report fills better structured periodic disclosure rows.
retrievalBlocks() and contextSlices() keep raw markdown and table evidence
so the text layer stays lossless while runtime still returns DataFrames
directly.
DartLab does not store per-stock result tables as package data. Learned rules ship with the package, and runtime returns DataFrames directly from the current stock's disclosure parquet.
c.audit # year, auditor, opinion, keyAuditMattersc.executive # year, totalRegistered, insideDirectors, outsideDirectors, ...
c.executivePay # year, category, headcount, totalPay, avgPayc.shareCapital # Issued, treasury, outstanding shares
c.capitalChange # Capital changes
c.fundraising # Capital increases/decreasesc.subsidiary # Investments in other corporations
c.affiliateGroup # Affiliate group companies
c.investmentInOther # Investee, ownership ratio, book valuec.boardOfDirectors # Board composition, attendance
c.shareholderMeeting # Shareholder meeting agendas, resolutions
c.auditSystem # Audit committee, audit activities
c.internalControl # Internal control assessmentc.contingentLiability # Contingent liabilities, lawsuits
c.relatedPartyTx # Related party transactions
c.sanction # Sanctions, penalties
c.riskDerivative # FX sensitivity, derivativesc.bond # Debt securities
c.rnd # R&D expenses
c.otherFinance # Allowance for bad debt, etc.
c.productService # Major products/services
c.salesOrder # Sales performance, order backlog
c.articlesOfIncorporation # Articles of incorporation amendmentsc.companyHistory # Corporate history
c.companyOverviewDetail # Incorporation date, listing date, CEO, addressc.business # Business overview (sections + change detection)
c.overview # Company overview (incorporation, address, credit rating)
c.mdna # Management Discussion & Analysis
c.rawMaterial # Raw materials, tangible assets, capexc.rawDocs # Original docs parquet (unprocessed)
c.rawFinance # Original finance parquet (unprocessed)
c.rawReport # Original periodic report parquet (unprocessed)Chat with an LLM over DartLab's structured data to analyze companies interactively — uv run dartlab ai opens the web UI at http://localhost:8400.
All extracted data (financial statements, notes, dividends, executives, governance) is provided as context for natural-language Q&A with streaming responses. Data Explorer lets you browse raw data directly in the browser.
The web UI is one public surface. The same runtime also exposes CLI entrypoints such as dartlab ask, dartlab status, dartlab setup, and dartlab excel.
| Provider | Auth | Description |
|---|---|---|
| ChatGPT | OAuth (browser login) | ChatGPT Plus/Pro subscription — no API key needed |
| Ollama | None (local) | Free, offline, private — GPU auto-detected |
| OpenAI API | API key | GPT-4o, o3, o4-mini and more |
| Anthropic API | API key | Claude Opus, Sonnet, Haiku |
| Codex CLI | CLI auth | ChatGPT subscription via Codex CLI |
| Claude Code | CLI auth | Claude subscription via Claude Code CLI |
uv run dartlab ai # http://localhost:8400
uv run dartlab ai --port 9000 # custom portd = c.all() # All module data as dict (with progress bar)
# {"BS": df, "IS": df, "CF": df, "dividend": df, "notes": {...},
# "timeseries": (series, periods), "ratios": RatioResult, ...}import dartlab
dartlab.verbose = False # Suppress progress output
d = c.all() # Silent extractionProperties return the primary DataFrame. For the full Result object, use c.get().
# property — returns DataFrame directly
c.audit # opinionDf (audit opinion DataFrame)
# get() — returns full Result object
result = c.get("audit")
result.opinionDf # Audit opinion
result.feeDf # Audit feesimport dartlab
dartlab.Company.search("삼성")
# ┌──────────────┬──────────┬────────────────┐
# │ 회사명 ┆ 종목코드 ┆ 업종 │
# └──────────────┴──────────┴────────────────┘
dartlab.Company.listing() # Full KRX listed companies
dartlab.Company.status() # Local data index
c.filings() # Filing list + DART viewer linksDART filings cover different periods depending on report type:
Q1 Q2 Q3 Q4
┌──────┐
Q1 Report │ Q1 │
└──────┘
┌──────────────┐
Semi-Annual │ Q1 + Q2 │
└──────────────┘
┌─────────────────────┐
Q3 Report │ Q1 + Q2 + Q3 │
└─────────────────────┘
┌──────────────────────────────┐
Annual Report │ Q1 + Q2 + Q3 + Q4 │
└──────────────────────────────┘
Q1 reports contain only Q1, semi-annual reports contain cumulative Q1+Q2, and annual reports contain the full year. DartLab reverse-engineers standalone quarterly figures from these cumulative structures, and tracks accounts even when names change between filings.
K-IFRS revisions and internal restructuring frequently cause account name changes within the same company. Bridge Matching combines amount matching and name similarity across adjacent years to automatically link identical accounts.
2022 2023 2024
────── ────── ──────
매출액 ────────────── 매출액 ────────────── 수익(매출액)
↑ name change ↑ name change
영업이익 ──────────── 영업이익 ──────────── 영업이익
당기순이익 ────────── 당기순이익 ────────── 당기순이익(손실)
Four-stage matching process:
- Exact match — identical amounts
- Restatement match — within 0.5 tolerance
- Name change match — amount error < 5% AND name similarity > 60%
- Special item match — decimal-unit items like EPS
When match rate drops below 85%, a breakpoint is detected and the segment is split.
All data originates from OpenDART and DART, Korea's official electronic disclosure system. The developer has not modified a single number — only metadata columns (stock code, year, report type, etc.) have been added for structural organization.
If you want to verify, you can cross-check any value against the original filings using the package's built-in DART viewer links (c.filings()).
Each Parquet file contains all filings for a single company:
- Metadata: stock code, company name, report type, filing date, business year
- Quantitative: summary financials, financial statement body, notes
- Narrative: business description, audit opinion, risk management, executive/shareholder status
| Category | Release Tags | Description | Count |
|---|---|---|---|
| Disclosure | data-docs |
Parsed annual report sections | 260+ |
| Finance | data-finance-1 2 3 4 |
XBRL financial statement numbers | 2,700+ |
| Report | data-report-1 2 3 4 |
Periodic report data | 2,700+ |
Finance and Report data are split into 4 tags by stock code range (GitHub's 1000-asset-per-release limit). loadData() and downloadAll() handle this automatically.
If you structure your own Parquet files to match DartLab's schema, all existing features work out of the box. Place files as data/{category}/{stockCode}.parquet and every property, extraction module, and analysis tool will function normally.
This project is licensed under MIT. While the data faithfully mirrors OpenDART public disclosures, no guarantee of commercial reliability is provided. Always verify against official sources for investment or compliance decisions.
Update frequency
Data is collected directly without paid proxies, so updates may be slow. Adding new companies or reflecting the latest filings may take time.
DART filings contain far more than financial numbers — business descriptions, risk factors, audit opinions, litigation status, and governance changes are all embedded in the text. Most tools only extract the numbers. The rest is discarded.
DartLab extracts both. It aligns quarterly, semi-annual, and annual reports on a single time axis, and automatically tracks accounts even when K-IFRS revisions or restructuring changes their names.
Current scope
Bridge Matching tracks account name changes within a single company across years. The finance engine enables cross-company comparison by mapping XBRL accounts to standardized snakeIds. 2,700+ listed companies are normalized to the same structure.
The insight engine grades each company across 7 areas (performance, profitability, financial health, cash flow, governance, risk), detects anomalies, and the rank engine computes market-wide size rankings.
Text analysis capabilities are being developed in a separate project and will be integrated into DartLab.
The ultimate goal is a tool that can analyze the entire market at once, not just one company.
- Summary financial time series (Bridge Matching)
- Consolidated BS, IS, CF
- Segment revenue, associates, dividends, employees, shareholders, subsidiaries
- Debt securities, expenses by nature, raw materials/capex
- Audit opinion, executive status, executive compensation
- PPE movement, note details (23 keywords)
- Board of directors, capital changes, contingent liabilities, related party tx, sanctions, R&D, internal control
- Affiliate groups, capital raises, sales/orders, products, risk management/derivatives
- MD&A, business description, company overview
- Company property API + Notes integration + all()
- Rich terminal output (avatar + usage guide)
- Account standardization engine — 2,700+ companies cross-comparable
- Quarterly time series + financial ratios (c.timeseries, c.ratios)
- Periodic report data engine (dividend, employees, major holders, audit, executives)
- Sector classification (WICS 11 sectors — KSIC + keyword + override)
- Insight grading engine (7 areas: performance, profitability, health, cashflow, governance, risk + overall)
- Anomaly detection (Z-score + domain rules across 30+ financial metrics)
- Market-wide size ranking (revenue, assets, growth — total + within-sector)
- AI analysis web interface (dartlab ai) — Ollama local LLM
- Cloud LLM providers (OpenAI, Anthropic, ChatGPT OAuth, Codex CLI, Claude Code)
- Data Explorer — full-screen data browser with Korean/English label toggle
- Excel export with templates
- Company
profilereport view (terminal/notebook document view focused on change points) - Compare UX overhaul around the same
index/show/tracephilosophy - EDGAR Company UX alignment with the DART
Companysurface - EDGAR (US SEC) financial data integration
- Text analysis module integration (from separate project)
- Quantitative + qualitative cross-validation
- Visualization
src/dartlab/
├── company.py # Company class — property → DataFrame (yfinance pattern)
├── core/ # Data loading, report selection, table parsing
│ ├── dataLoader.py # GitHub Releases ↔ local cache
│ ├── dataConfig.py # Release tags, shard mapping
│ └── registry.py # DataEntry — single source of truth for all modules
│
├── engines/
│ ├── dart/ # L1: DART data source
│ │ ├── docs/ # Filing document parsing
│ │ │ ├── finance/ # 36 quantitative modules (BS, IS, CF, dividend, ...)
│ │ │ ├── disclosure/ # 4 narrative modules (business, MD&A, overview, ...)
│ │ │ └── notes.py # K-IFRS notes wrapper (12 items)
│ │ ├── finance/ # XBRL normalization — 34K synonyms → unified snakeId
│ │ └── report/ # Periodic report API (dividend, employee, audit, ...)
│ │
│ ├── sector/ # L2: WICS 11-sector classification
│ ├── insight/ # L2: 7-area grading (A~F) + anomaly detection
│ ├── rank/ # L2: Market-wide size ranking
│ │
│ └── ai/ # L3: LLM-powered analysis
│ ├── providers/ # ChatGPT, Ollama, OpenAI, Anthropic, Codex, Claude Code
│ ├── context.py # Engine data → LLM context assembly
│ └── prompts.py # System prompts (KR/EN)
│
├── server/ # FastAPI backend for web UI
└── ui/ # Svelte 5 SPA (Data Explorer, chat)
Layer principles: L1 defines the data (labels, ordering, units). L2 and L3 consume L1 without modification. Changes to data quality always start at L1.
Issues and pull requests are welcome. Before submitting:
- Test new features in
experiments/first — verify the approach before modifyingsrc/ - For data mapping improvements (e.g.,
accountMappings.json), include experiment results showing the before/after impact
Questions or ideas? Open an issue. Both Korean and English are fine.
MIT License
