Scan

엔진 역할

scan은 여러 기업을 한 번에 훑어 후보를 찾는 L2 엔진이다. 질문의 단위가 “삼성전자를 분석해줘”이면 Company/analysis가 우선이고, “조건에 맞는 종목을 찾아줘”, “전종목에서 상위 기업을 골라줘”이면 scan이 우선이다.

account와 ratio는 primitive다. 복합 투자 질문은 screen preset/spec 또는 quality, valuation, growth, profitability 같은 축으로 시작하고, 최종 판단은 후보별 analysis, credit, quant로 검증한다.

공개 호출 방식

import dartlab

# 전체 스캔 축 가이드
guide = dartlab.scan()

# 축 실행
quality = dartlab.scan("quality")
valuation = dartlab.scan("valuation")
cashflow = dartlab.scan("cashflow")

# primitive
revenue = dartlab.scan("account", "매출액")
roe = dartlab.scan("ratio", "roe")

# 조건형 스크리닝
fields = dartlab.scan("fields", "roe")
value = dartlab.scan("screen", "value")
custom = dartlab.scan("screen", spec={"filters": []})

호출 동작

무인자 dartlab.scan()은 실행 가능한 스캔 축 가이드 DataFrame을 반환한다. 특정 axis를 주면 해당 유니버스의 prebuilt parquet 또는 provider scan 함수를 읽어 DataFrame을 반환한다.

account와 ratio는 전종목 단일 계정/비율 시계열을 조회하는 원자 축이다. fields는 조건형 screen에 넣을 필드를 찾는 축이고, screen은 preset 또는 spec 기반 조건식을 실행한다.

데이터가 없거나 snapshot이 제한되면 값을 추정하지 않는다. 빈 DataFrame, 결손 컬럼, 제한 메시지, 기준일 누락을 그대로 드러내고 필요한 수집/필드 확인 경로를 말한다.

전체 축/메서드 목록

axis	label	group	대표 호출
governance	거버넌스	DART	dartlab.scan("governance")
workforce	인력/급여	DART	dartlab.scan("workforce")
capital	주주환원	DART+EDGAR	dartlab.scan("capital")
debt	부채구조	DART+EDGAR	dartlab.scan("debt")
account	계정	DART+EDGAR	dartlab.scan("account", "매출액")
ratio	비율	DART+EDGAR	dartlab.scan("ratio", "roe")
network	네트워크	DART	dartlab.scan("network")
cashflow	현금흐름	financial	dartlab.scan("cashflow")
audit	감사리스크	DART	dartlab.scan("audit")
insider	내부자지분	DART	dartlab.scan("insider")
quality	이익의 질	financial	dartlab.scan("quality")
liquidity	유동성	financial	dartlab.scan("liquidity")
growth	성장성	financial	dartlab.scan("growth")
profitability	수익성	financial	dartlab.scan("profitability")
efficiency	효율성	financial	dartlab.scan("efficiency")
valuation	밸류에이션	financial	dartlab.scan("valuation")
dividendTrend	배당추이	financial	dartlab.scan("dividendTrend")
macroBeta	거시베타	DART	dartlab.scan("macroBeta")
fields	필드카탈로그	DART	dartlab.scan("fields", "roe")
screen	스크리닝	DART	dartlab.scan("screen", "value")
disclosureRisk	공시리스크	DART	dartlab.scan("disclosureRisk")

대표 반환 형태

가이드 호출은 DataFrame을 반환한다.

dartlab.scan()
-> DataFrame
   axis, label, group, description, example, apiKey

축 실행도 대부분 DataFrame을 반환한다. 축마다 세부 컬럼은 다르지만 후보 발굴 답변에는 최소 다음 성격의 필드가 있어야 한다.

stockCode/ticker, corpName/name, market/universe, latestAsOf/asOf,
metric/value/score, rank, basis/source, flags

screen은 조건식과 통과 여부, account/ratio는 계정명 또는 ratio id, 기간별 값, 기준일을 포함해야 한다. ranking/filter 결과를 말할 때는 원값과 rank를 함께 제시한다.

evidence 기준

후보 발굴 결과에는 universe, datasetAsOf, filter, formula, table, executionRef가 필요하다. 최종 답변은 회사명만 나열하지 말고 evidence table을 포함한다.

기본 실행 순서

1. 질문이 후보 발굴인지 단일 기업 분석인지 구분한다.
2. 후보 발굴이면 dartlab.scan()으로 axis를 확인한다.
3. primitive가 필요한지 preset/spec가 필요한지 고른다.
4. dartlab.scan(axis, target/spec)를 실행한다.
5. 기준일, 유니버스, 필터, 계산식, rank를 검산한다.
6. 상위 후보는 Company(...).analysis(), credit, quant로 심층 검증한다.

기본 검증

스킬은 공개 실행 문서다. dartlab.scan()의 guide 축, 공개 호출, 대표 반환 컬럼이 바뀌면 이 파일과 관련 응용 스킬을 같은 변경에서 갱신한다.