API 안정성 정책 (tier · deprecation · semver)

dartlab 은 현재 DART core 가 stable. 본 문서는 변경 시 적용할 tier 와 호환성 정책이다.

Tier 분류

Tier 1: Stable

변경 시 deprecation 기간 + 마이그레이션 가이드 동반.

API	설명
dartlab.Company(code)	Company 객체 생성 facade
Company.sections	회사 지도 (topic × 기간 Polars DataFrame)
Company.show()	topic payload 조회 (source-aware)
Company.trace()	source provenance 조회
Company.diff()	기간 간 텍스트 변화 감지
Company.topics	사용 가능 topic 리스트
dartlab.listing()	전체 상장사 디렉터리
`Company.show(“BS”	“IS”
Company.show("ratios")	재무비율 조회
Company.select(topic, accounts)	topic 의 행/열 선택
Company.index	topic × 기간 정형 보드 DataFrame
Company.filings()	공시 문서 리스트
dartlab CLI 진입점	공개 CLI 명령 진입점
dartlab.Company("AAPL")	EDGAR Company facade (US 종목)
engines.edgar.docs	EDGAR 10-K/10-Q/20-F 섹션 가로화
engines.edgar.docs.retrievalBlocks	EDGAR 블록 단위 LLM 검색
engines.edgar.docs.contextSlices	EDGAR LLM context window 슬라이싱
engines.edgar.finance	SEC XBRL 재무제표 (BS/IS/CF)
engines.edgar.profile	EDGAR docs + finance 병합 레이어
c.analysis("valuation", "가치평가")	다중 가치평가 (DCF · DDM · 상대) — KRW/USD 자동 감지
c.analysis("forecast", "매출전망")	매출 전망 (시계열 · 컨센서스 · 매크로 · ROIC)

Tier 2: Beta

경고 후 변경 가능. CHANGELOG 기록.

API	설명
dartlab.search()	DART 공시 ngram/BM25 검색 — 인덱스 신선도 제한 (일별 delta 자동화 보류). 단일 종목 공시는 Company.disclosure / liveFilings 권장.
engines.edgar.finance.SCE	자본변동표 (BS delta + CF)
engines.edgar.finance.explore()	XBRL Fact Explorer (tag 단위 history)
engines.edgar.finance.listTags()	XBRL tag 인벤토리
engines.edgar.docs.notes()	XBRL TextBlock 주석 추출
engines.edgar.docs.freq()	topic × 기간 분포 매트릭스
engines.edgar.docs.coverage()	topic 커버리지 요약
Company.insights	인사이트 등급 (7 영역)
Company.insights.distress	부실 예측 스코어카드 (4 축, 신용 등급, 현금 런웨이)
Company.rank	시장 규모 랭킹
Company.ask()	LLM 기반 분석
dartlab 서브커맨드	ask, status, setup, ai, excel UX
Server API /api/*	웹 서버 엔드포인트
engines.ai.*	AI/LLM 엔진
Company.show("SCE")	자본변동표 (DART)
Company.show("ratioSeries")	비율 시계열
Company.network()	계열사 네트워크 그래프
Company.governance()	지배구조 데이터
Company.workforce()	인력 데이터
Company.capital()	자본 구조
Company.debt()	부채 상세
Company.table()	인라인 표 추출
dartlab.chart	chart 도구 모듈
dartlab.ai.tools.table	table 도구 모듈
dartlab.text	text 도구 모듈
MCP server	MCP protocol 서버 (60 tools, stdio)
dartlab mcp	MCP CLI 명령

Tier 3: Experimental

Breaking 변경 허용. 프로덕션 비권장.

API	설명
export.*	Excel export
engines.ai.tools.*	LLM tool calling

Tier 4: Alpha

초기 단계. 동작은 하지만 미완성.

기능	설명
Desktop App (Windows .exe)	독립 데스크탑 앱 — 동작 가능, 미완성
Sections Viewer	가로화 공시 뷰어 — 핵심 컨셉 동작, 구조 미정

Deprecation 정책

Tier	안내	제거
Tier 1	2 minor 사전	DeprecationWarning → 다음 minor 에서 제거
Tier 2	1 minor 사전	CHANGELOG 후 변경
Tier 3	즉시	CHANGELOG 만
Tier 4	없음	통보 없이 변경/소멸 가능

DeprecationWarning 예시:

import warnings
warnings.warn(
    "Company.oldMethod() will be removed in v0.5.0. "
    "Use Company.newMethod() instead.",
    DeprecationWarning,
    stacklevel=2,
)

Stability 기준

DART core stable 기준:

• CI 테스트 커버리지 80%+ (core 엔진).
• API Tier 1 테스트 100% 통과.
• sections raw residual 0 유지 (대표 종목 셋).
• BS identity check 95%+ 통과.
• Tier 1 breaking change 3 개월 부재.
• PyPI 다운로드 안정 추세.
• 외부 사용자 피드백 수렴 (2 건+).

버전 정책

• semver 준수: major = breaking, minor = feature, patch = bugfix.
• DART core stable 범위는 minor 안에서 호환성 우선.
• EDGAR 와 일부 AI 기능은 tier 정책에 따라 더 빨리 변할 수 있다.
• 내부 profile merge 레이어는 docs spine 위. c.sections 와 c.show() 가 공식 사용 경로.

CLI 호환성 규칙

• 최상위 dartlab 진입점은 Tier 1.
• 공개 서브커맨드와 주요 옵션 변경은 1 minor 이상 deprecation 사전 안내.
• exit code 는 계약: 0 성공, 1 런타임 에러, 2 사용 에러, 130 사용자 인터럽트.
• deprecated 별칭은 help 에서 숨겨도 제거 전까지는 실행 가능 유지.

EDGAR Topic Naming

EDGAR topic 은 {formType}::{itemId} 형식.

• 10-K::item1Business — 사업 설명.
• 10-K::item1ARiskFactors — 위험 요인.
• 10-K::item7Mdna — 경영진 토의.

짧은 별칭도 동작: business, risk, mdna, governance.

DART · EDGAR Namespace 차이

• EDGAR 는 accessor 분리 (_DocsAccessor, _FinanceAccessor, _ProfileAccessor) + retrievalBlocks + contextSlices + 서버 API 지원 — DART 아키텍처와 같은 핵심.
• DART docs namespace 는 추가 sections 분석 (coverage, freq, semanticRegistry, structureRegistry) — EDGAR 미지원, Tier 2.
• DART report namespace (28 종 정형 공시 API) 는 EDGAR 에 없다 — DART 와 SEC 의 구조적 차이.

다음 단계

• operation.code — 코드 품질 · 독스트링 · 릴리즈.
• operation.apiContract — 새 함수 추가 시 API 계약.
• operation.cliMaintenance — CLI 유지보수 규칙.