analysis

Imported from eddmpython/dartlab (src/dartlab/skills/specs/engines/analysis/SKILL.md). Install upstream with npx skills add eddmpython/dartlab --skill analysis. Copyright stays with the author.

엔진 역할

analysis는 단일 기업을 재무제표의 인과 구조로 읽는 L2 엔진이다. 이 엔진은 매출과 비용, 자산과 부채, 현금흐름, 수익성, 성장성, 안정성, 효율성, 가치평가, 지배구조, 전망 신호를 축별로 계산하고 해석한다.

담당하는 질문은 "이 회사는 무엇으로 돈을 벌고, 그 돈은 진짜 현금으로 남고, 그 성장은 지속 가능하며, 지금 가격은 어느 정도인가"이다. 시장 전체 매크로 전망은 engines.macro, 신용등급/부도위험 중심 평가는 engines.credit, 여러 종목을 찾는 작업은 engines.scan, 최종 보고서 조합은 engines.story가 담당한다.

공개 호출 방식

기본 호출은 Company.analysis()이다. 축을 모르면 먼저 가이드를 보고, 축을 알면 group과 axis를 지정한다.

import dartlab

c = dartlab.Company("005930")

# 1. 전체 분석 축 가이드
guide = c.analysis()

# 2. 그룹 가이드 또는 그룹 내 계산 항목 확인
financial = c.analysis("financial")

# 3. 특정 분석 축 실행
profitability = c.analysis("financial", "수익성")
cashflow = c.analysis("financial", "현금흐름")
valuation = c.analysis("valuation", "가치평가")
forecast = c.analysis("forecast", "매출전망")

# 4. 축 이름만으로 실행 가능한 경우
profitability = c.analysis("수익성")

# 5. 모듈 함수형 호출 — Company 객체는 company= keyword (positional 3 번째 안 받음)
profitability = dartlab.analysis("financial", "수익성", company=c)
valuation = dartlab.analysis("valuation", "가치평가", company=c)
# stockCode 단독 호출도 가능
profitability = dartlab.analysis("financial", "수익성", stockCode="005930")

노트북이나 MCP에서 사람이 따라 할 때도 같은 순서로 쓴다. 먼저 c.analysis()로 가능한 축을 확인하고, 그 다음 실제 축을 호출한다.

강행 호출 룰 (agent 답변 품질 회귀 차단)

22 axis 질문 (수익성·밸류에이션·안정성·효율성·종합평가·이익품질·자본배분·성장성 등) 에서 다음 4 룰은 강행이다 — 위반 시 refs=0 회귀로 답변 품질 65 점 이하 하락.

1. 1 차 도구는 EngineCall 강제. axis 명이 질문에 있거나 22 axis 가이드 표에 매칭되면 EngineCall(apiRef="Company.analysis", args={...}) 또는 EngineCall(apiRef="Company.panel", args={...}) 가 첫 호출. RunPython 직접 ratio 계산은 engine 호출 결과가 부재할 때만 fallback — 처음부터 raw 계산 금지.

   이유: EngineCall 결과 dict 는 @tagConfidence 데코레이터로 tableRef·valueRef·dateRef·executionRef 자동 발급. RunPython 은 raw eval — refs 0 발급. 답변 본문 인용 가치체인이 깨진다.

2. 본문 안 모든 숫자에는 inline ref 표기 필수. 형식: 13.07% [ref:vr_...] 또는 [tableRef: tr_...]. ref 없는 숫자는 답변에 적지 않거나 "EngineCall 재시도 필요" 명시.

3. dataAsOf 확인 → 답변 첫 줄 명시. 결과 dict 의 dataAsOf 가 stale (3 분기 이상 전) 이면 "현재 시점 단정 X — dataAsOf 기준" 명시.

4. flags / assumptions / freshness 누락 시 답변 보류. 결과의 flags 가 non-empty 면 "데이터 제한" 으로 답변에 인용. assumptions 가 있는 축 (valuation 등) 은 항상 본문에 노출.

분기 추세가 필요한 경우 (axis 22 종은 연간 한정)

Company.analysis(axis=...) 의 22 axis 분석은 연간 시계열 기반. analyzeProfitability 등 내부 함수는 aSeries: dict (annual series) 만 받는다. 즉 "최근 분기 수익성 어땠어 / Q1 회복 신호 있어" 류 질문은 engine 의 axis 함수 단독으로 답할 수 없다.

조합 패턴:

# 1. 분기 raw (show 는 freq='Q' 지원)
isQ = c.panel("IS", freq="Q")  # 분기 손익
bsQ = c.panel("BS", freq="Q")  # 분기 재무상태

# 2. 연간 axis 분석 (grade + 임계값 + 추세)
profit = c.analysis("financial", "수익성")  # 연간 grade A~F + DuPont

# 3. ai 가 1+2 결합해 narrative — 연간 grade + 분기 최신 추세 동시 인용

agent EngineCall 양식:

# 분기 raw
EngineCall(apiRef="Company.panel", args={"stockCode": "005930", "stmt": "IS", "freq": "Q"})
EngineCall(apiRef="Company.panel", args={"stockCode": "005930", "stmt": "BS", "freq": "Q"})

# 연간 axis
EngineCall(apiRef="Company.analysis", args={"stockCode": "005930", "group": "financial", "axis": "수익성"})

분기-축 통합은 engine 미지원 — 3 호출 결과를 ai 가 답변에 직접 엮는다. panel 결과의 tableRef·valueRef 와 analysis 결과의 executionRef 가 함께 발급되어 refs 가치체인 유지.

호출 동작

axis가 없으면 실행 가능한 분석 축 가이드 DataFrame을 반환한다. 이 가이드는 사람이 어떤 축을 골라야 하는지 보여주는 공개 메뉴다.

group만 주면 해당 그룹의 축 또는 계산 항목 가이드를 반환한다. 회사 객체가 없는 함수형 호출에서는 계산 목록을 탐색하는 용도로 쓰이고, 회사 객체가 있는 호출에서는 해당 회사 기준으로 축 실행을 준비한다.

group과 axis가 함께 있거나 축 이름만 들어오면 해당 축을 실행한다. 엔진은 Company가 가진 재무제표, 시계열, 공시/시장 데이터 snapshot, 내부 계산 registry를 읽고 축별 계산을 수행한다.

데이터가 충분하면 축별 분석 dict를 반환한다. 데이터가 부족하면 결손을 0으로 채우지 않고, flags, assumptions, dataAsOf, 빈 history, null 값, 제한 메시지 등으로 표현한다. 호출한 group 또는 axis가 없으면 사용 가능한 group/axis를 확인할 수 있는 오류를 낸다.

analysis는 다른 L2 엔진 (credit · macro · quant · industry) 을 내부에서 import 해 조합하지 않으며, L1.5 (scan) · L3 조합기 (story) 도 직접 사용하지 않는다. 필요한 원천 데이터는 Company (L1) / core (L0) 계층에서 직접 읽고, 최종 조합은 story 가 단독으로 짊어진다 (L2 끼리의 import 가 만드는 순환참조 방지).

분석 축 전체

대표 반환 형태

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

c.analysis()
-> DataFrame
   axis, description, example, group, items, apiKey

특정 축 실행은 dict를 반환한다. 공통적으로 다음 계열을 확인한다.

c.analysis("financial", "수익성")
-> dict
   items: 축별 계산 항목과 결과
   history: 기간별 핵심 값
   displayHints: 표/차트 표시 힌트
   turningPoints: 변곡점 또는 변화 감지 결과
   dataAsOf: 데이터 기준일과 snapshot 정보
   assumptions: 계산 가정과 제한
   flags: 결손, 이상치, 비교 불가, 제한 상태
   _summary: 사람이 읽을 요약
   tableRef/valueRef/dateRef/executionRef: 근거 연결용 참조

축별 dict에는 공통 키 외에 전용 블록이 붙을 수 있다. 예를 들어 수익성은 매출총이익률, 영업이익률, 순이익률, ROE/ROA 흐름을 포함하고, 현금흐름은 영업/투자/재무 현금흐름과 잉여현금흐름을 포함한다. 안정성은 부채비율, 유동성, 이자보상 성격의 지표를 포함한다.

가치평가 축은 valuationSummary, targetPrice, relativeValue, dcf, ddm, rim, sensitivity, valuationFlags 같은 블록을 반환할 수 있다. 매출전망/예측신호 축은 forecastRevenue, scenario, signal, forecastFlags 같은 전망 관련 블록을 반환할 수 있다.

단위는 원천 데이터와 계산 항목의 성격을 따른다. 금액은 원천 table의 통화/단위를 보존하고, 비율은 percent 또는 ratio 여부를 명확히 표시해야 한다. 스킬에 적힌 대표 키와 실제 공개 API가 충돌하면 스킬이 오래된 것이므로 같은 변경에서 갱신한다.

axis-specific 회피 (회귀 가드)

각 axis 의 sub-spec 본문은 base SKILL.md 의 axis 표에 흡수됨 (2026-05-18 Phase C-3 정리). 22 axis 모두 inline (standalone 없음 — algorithm 구체 본문은 capability Company.analysis payload + engines.analysis.{valuation,profitability} 의 14 keys / OPM 양식 본문이 본문 § "valuation 축 — 14 top-level keys" 섹션으로 보존).

공통 forbidden (모든 axis): 숫자 없는 수익성 판단 X · 결손값을 0 으로 대체 X · 단일 종목 분석을 scan/screen 으로 바꾸기 X.

valuation 축 — 14 top-level keys (기존 engines.analysis.valuation)

c.analysis("valuation", "가치평가") 1 회 결과 dict 의 핵심 키 (값 그대로 인용, 추가 호출 X):

답변 양식 7 단: 결론 (verdict + weightedFairValue) → 4 방법론 표 → 시나리오 가격 (priceTarget.percentiles) → DCF 정규화 경고 (mid-cycle FCF) → plausibility band peer percentile → lifeCycle modelHint → 한계.

EngineCall (agent 경로) args 매핑

agent (ai/mcp/server) 가 본 엔진을 호출할 때는 EngineCall(apiRef="Company.analysis", args={...}) 양식. positional 인자를 args dict 의 key 로 변환:

guard — group 과 axis 를 점 표기로 합쳐 apiRef="analysis.financial.profitability" 호출 금지. apiRef="Company.analysis" 고정 + args 에 분리.

Company.panel vs Company.analysis — 어느 쪽?

핵심 차이 — Company.panel 는 원자료 + 자동 부착 badge (dcrBadge / industryBadge), Company.analysis 는 해석 결과 (assumptions · narrative · history). 단순 숫자 조회면 panel, 해석/근거 chain 이 필요하면 analysis. 단일 종목 신용 질문은 panel 1 회만으로 7 축 분해 완성 — analysis credit 또는 EngineCall("credit") 추가 불필요.

축 선택 규칙

수익구조, 비용구조, 이익품질, 현금흐름처럼 재무제표 안에서 인과를 읽는 질문은 financial 그룹을 쓴다.

적정가, 멀티플, DCF/DDM/RIM, 목표가 범위는 valuation 그룹을 쓴다. 단, 가치평가 결과를 말할 때는 수익성, 성장성, 현금흐름, 자본배분의 근거를 같이 확인한다.

주주, 이사회, 공시 변화, 동종 비교는 governance 그룹을 쓴다. 업종 전체 구조 분석은 engines.industry, 보고서 문장 조합은 engines.story로 넘긴다.

매출 전망과 실적 방향은 forecast 그룹을 쓴다. 시장 전체 금리/환율/물가 전망은 engines.macro가 담당하고, analysis의 macro 그룹은 기업 단위 민감도와 밴드 확인에 한정한다.

여러 종목을 조건으로 찾는 일은 analysis가 아니라 engines.scan이 담당한다. scan으로 후보를 찾고, 각 후보를 analysis로 깊게 읽는다.

기본 실행 순서

1. 대상 기업을 확정한다: c = dartlab.Company("005930").
2. 축이 불명확하면 c.analysis()로 전체 가이드를 확인한다.
3. 질문 성격에 맞는 group/axis를 고른다.
4. 실제 축을 호출한다: c.analysis("financial", "수익성").
5. history, items, flags, assumptions, dataAsOf를 먼저 확인한다.
6. 숫자를 말할 때 tableRef, valueRef, dateRef, executionRef를 연결한다.
7. 여러 축을 보고서로 엮을 때는 story가 조합한다.

기본 검증

분석 결과는 최소한 대상, 기간, 지표명, 값, 단위, 기준일을 함께 확인한다. 기간 비교가 필요한 축은 전년동기, 전기, 최근 3년/5년 흐름 중 어떤 기준을 썼는지 밝혀야 한다.

결손값, 음수 전환, 회계 기준 변경, 사업 분할/합병, 상장 기간 부족, 데이터 snapshot 제한은 정상 값처럼 포장하지 않는다. 계산이 제한되면 flags와 assumptions를 결과의 일부로 취급한다.

스킬은 공개 실행 문서다. Company.analysis() 또는 dartlab.analysis()의 호출 방식, 대표 반환 키, 오류/제한 동작이 바뀌면 이 파일과 관련 응용 스킬을 같은 변경에서 갱신해야 한다.