dartlab 0.8.7

DART 전자공시 + EDGAR 공시를 하나의 회사 맵으로 — Python 재무 분석 라이브러리

DartLab

One stock code. The whole story.

DART + EDGAR filings, structured and comparable — in one line of Python.

Docs · Blog · Live Demo · Open in Colab · Open in Molab · 한국어 · Sponsor

The Problem

A public company files hundreds of pages every quarter. Revenue trends, risk warnings, management strategy, competitive position — the complete truth about a company, written by the company itself.

Nobody reads it.

Not because they don't want to. Because the same information is named differently by every company, structured differently every year, and scattered across formats designed for regulators, not readers. The same "revenue" appears as ifrs-full_Revenue, dart_Revenue, SalesRevenue, or dozens of Korean variations. The same "business overview" is titled differently in every filing.

DartLab is built on one premise: every period must be comparable, and every company must be comparable. It normalizes disclosure sections into a topic-period grid (~95% mapping rate) and standardizes XBRL accounts into canonical names (~97% mapping rate) — so you compare companies, not filing formats.

Quick Start

uv add dartlab

pip install dartlab              # core + AI (openai, gemini included)
pip install dartlab[server]      # + web server (FastAPI, MCP)
pip install dartlab[viz]         # + charts (Plotly)
pip install dartlab[all]         # everything

import dartlab

c = dartlab.Company("005930")       # Samsung Electronics

c.sections                          # every topic, every period, side by side
# shape: (41, 12) — 41 topics across 12 periods
#                     2025Q4  2024Q4  2024Q3  2023Q4  ...
# companyOverview       v       v       v       v
# businessOverview      v       v       v       v
# riskManagement        v       v       v       v

c.show("businessOverview")          # what this company actually does
c.diff("businessOverview")          # what changed since last year
c.BS                                # standardized balance sheet
c.ratios                            # financial ratios, already calculated

# Same interface, different country
us = dartlab.Company("AAPL")
us.show("business")
us.ratios

# Ask in natural language
dartlab.ask("Analyze Samsung Electronics financial health")

No API key needed. Data auto-downloads from HuggingFace on first use, then loads instantly from local cache.

What DartLab Is

Two engines turn raw filings into one comparable map:

Layer	Engine	What it does	Entry point
Data	Data	Pre-built HuggingFace datasets, auto-download	Company("005930")
L0/L1	Company	Sections horizontalization + account standardization	c.show(), c.select()
L1	Scan	Cross-company comparison across 13 axes	dartlab.scan()
L1	Gather	External market data (price, flow, macro, news)	dartlab.gather()
L2	Analysis	14-axis financial + valuation + forecast + quant	c.analysis("financial", "수익성")
L2	Credit	Independent credit rating (dCR 20-grade)	c.credit()
L2	Review	Block composition (analysis + credit)	c.review()
L0	Search	Semantic filing search (alpha)	dartlab.search()
L3	AI	Active analyst — code execution + interpretation	dartlab.ask()
L4	UI	VSCode extension	dartlab chat --stdio

Company

Design: ops/company.md

Three data sources — docs (full-text disclosures), finance (XBRL statements), report (DART API) — merged into one object. Data auto-downloads from HuggingFace, no setup needed.

c = dartlab.Company("005930")

c.index                         # what's available -- topic list + periods
c.show("BS")                    # view data -- DataFrame per topic
c.select("IS", ["매출액"])       # extract data -- finance or docs, same pattern
c.trace("BS")                   # where it came from -- source provenance
c.diff()                        # what changed -- text changes across periods

Scan — Cross-Company Comparison

Design: ops/scan.md

13 axes across 2,700+ companies. Governance, workforce, capital, debt, cashflow, audit, insider, quality, liquidity, digest, network, account, ratio.

dartlab.scan("governance")            # governance across all firms
dartlab.scan("ratio", "roe")          # ROE across all firms
dartlab.scan("cashflow")              # OCF/ICF/FCF + 8-pattern classification

Gather — External Market Data

Design: ops/gather.md

Price, flow, macro, news — all as Polars DataFrames.

dartlab.gather("price", "005930")             # KR OHLCV
dartlab.gather("price", "AAPL", market="US")  # US stock
dartlab.gather("macro", "FEDFUNDS")           # auto-detects US
dartlab.gather("news", "삼성전자")             # Google News RSS

Analysis — 14-Axis Financial Analysis

Design: ops/analysis.md

Revenue structure, profitability, growth, stability, cash flow, capital allocation — 14 axes that turn raw statements into a causal narrative. Each axis feeds into Review (reports), AI (interpretation), and humans (direct reading).

c.analysis("financial", "수익성")       # profitability analysis
c.analysis("financial", "현금흐름")    # cash flow analysis

c.credit()                                  # dCR-AA, healthScore 93/100
c.credit(detail=True)                       # 7-axis narrative + metrics

Credit

Design: ops/credit.md

Independent credit rating engine. 7-axis weighted scoring with sector-specific thresholds, CHS default probability, and narrative generation.

cr = c.credit()
print(cr["grade"])          # dCR-AA
print(cr["healthScore"])    # 93.36 (0-100, higher is better)
print(cr["pdEstimate"])     # 0.02% default probability

cr = c.credit(detail=True)  # includes 7-axis narrative
for n in cr["narratives"]["axes"]:
    print(f"[{n['severity']}] {n['axis']}: {n['summary']}")

Review — Analysis to Report

Design: ops/review.md

Assembles analysis into a structured report. 4 output formats: rich (terminal), html, markdown, json.

c.review()              # full report
c.reviewer()            # report + AI interpretation

Sample reports: Samsung Electronics · SK Hynix · Kia · HD Hyundai Heavy Industries · SK Telecom · LG Chem · NCSoft · Amorepacific

Search — Find Filings by Meaning (alpha)

Design: ops/search.md

No model, no GPU, no cold start. 95% precision on 4M documents — better than neural embeddings at 1/100th the cost.

dartlab.search("유상증자 결정")                     # find capital raise filings
dartlab.search("대표이사 변경", corp="005930")       # filter by company
dartlab.search("회사가 돈을 빌렸다")                 # natural language works too

AI — Active Analyst

Design: ops/ai.md

The AI writes and executes Python code using dartlab's full API. You see every line of code it runs. 60+ questions validated, 95%+ first-try success.

dartlab.ask("Analyze Samsung Electronics financial health")
dartlab.ask("Samsung analysis", provider="gemini")  # free providers available

Providers: gemini (free), groq (free), cerebras (free), oauth-codex (ChatGPT subscription), openai, ollama (local), and more. Auto-fallback across providers when rate-limited.

Architecture

L0  core/        Protocols, finance utils, docs utils, registry
L1  providers/   Country-specific data (DART, EDGAR, EDINET)
    gather/      External market data (Naver, Yahoo, FRED)
    scan/        Market-wide analysis — scan("group", "axis")
L2  analysis/    Financial + forecast + valuation + quant — analysis("group", "axis")
    credit/      Independent credit rating — c.credit()
    review/      Block composition (analysis + credit)
L3  ai/          Active analyst — dartlab.ask()
L4  vscode/      VSCode extension (dartlab chat --stdio)

Import direction enforced by CI. Adding a new country means one provider package — zero core changes.

EDGAR (US)

Same interface, different data source. Auto-fetched from SEC API — no pre-download needed.

# Korea (DART)                          # US (EDGAR)
c = dartlab.Company("005930")           c = dartlab.Company("AAPL")
c.sections                              c.sections
c.show("businessOverview")              c.show("business")
c.BS                                    c.BS
c.ratios                                c.ratios
c.diff("businessOverview")              c.diff("10-K::item7Mdna")

MCP — AI Assistant Integration

Built-in MCP server for Claude Desktop, Claude Code, Cursor, and any MCP-compatible client.

# Claude Code — one line setup
claude mcp add dartlab -- uv run dartlab mcp

# Codex CLI
codex mcp add dartlab -- uv run dartlab mcp

Claude Desktop / Cursor config

Add to claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "dartlab": {
      "command": "uv",
      "args": ["run", "dartlab", "mcp"]
    }
  }
}

Or auto-generate: dartlab mcp --config claude-desktop

OpenAPI — Raw Public APIs

from dartlab import OpenDart, OpenEdgar

# Korea (requires free API key from opendart.fss.or.kr)
d = OpenDart()
d.filings("삼성전자", "2024")
d.finstate("삼성전자", 2024)

# US (no API key needed)
e = OpenEdgar()
e.filings("AAPL", forms=["10-K", "10-Q"])

Data

All data is pre-built on HuggingFace — auto-downloads on first use. EDGAR data comes directly from the SEC API.

Dataset	Coverage	Size
DART docs	2,500+ companies	~8 GB
DART finance	2,700+ companies	~600 MB
DART report	2,700+ companies	~320 MB
EDGAR	On-demand	SEC API

Pipeline: local cache (instant) → HuggingFace (auto-download) → DART API (with your key). Most users never leave the first two.

Try It Now

Live Demo — no install, no Python

Notebooks: Company · Scan · Review · Gather · Analysis · Ask (AI)

Documentation

Docs · Quick Start · API Overview · Blog (120+ articles)

Stability

Tier	Scope
Stable	DART Company (sections, show, trace, diff, BS/IS/CF, CIS, index, filings, profile), EDGAR Company core, valuation, forecast, simulation
Beta	EDGAR power-user (SCE, notes, freq, coverage), credit, insights, distress, ratios, timeseries, network, governance, workforce, capital, debt, chart/table/text tools, ask/chat, OpenDart, OpenEdgar, Server API, MCP
Experimental	AI tool calling, export, viz (charts)

See docs/stability.md.

Contributing

Contributors are very welcome. Whether it's a bug report, a new analysis axis, a mapping fix, or a documentation improvement — every contribution makes dartlab better for everyone.

The one rule: experiment first, engine second. Validate your idea in experiments/ before changing the engine. This keeps the core stable while making it easy to try bold ideas.

• Experiment folder: experiments/XXX_name/ — each file must be independently runnable with actual results in its docstring
• Data contributions (e.g. accountMappings.json, sectionMappings.json): accepted when backed by experiment evidence
• Issues and PRs in Korean or English are both welcome
• Not sure where to start? Open an issue — we'll help you find the right place

License

MIT