simulate

엔진 역할

simulate는 회사 원자료와 매크로 시나리오를 macro.path -> rev.path -> proforma -> dcf 결정론 드라이버 시트로 연결하는 L3 엔진이다. 난수를 쓰지 않으며 같은 target, scenario, asOf는 같은 노드별 inputsHash를 만든다. 결과는 미래 확정치가 아니라 입력 가정에 조건부인 변환 결과다.

공개 호출 방식

import dartlab

baseline = dartlab.simulate(
    "005930",
    scenario="baseline",
    horizon=3,
    asOf="2024",
)
adverse = dartlab.simulate(
    "005930",
    scenario="adverse",
    horizon=3,
    asOf="2024",
)

c = dartlab.Company("005930")
company_result = c.simulate(scenario="adverse", horizon=3, asOf="2024")

설치형 AI 런타임은 다음 canonical 계약을 쓴다.

{
  "apiRef": "simulate",
  "args": {
    "target": "005930",
    "scenario": "adverse",
    "horizon": 3,
    "asOf": "2024"
  }
}

호출 동작

1. target을 KR Company로 해소하고 지원하지 않는 시장과 시나리오를 차단한다.
2. 회사 snapshot과 매크로 preset을 같은 asOf 경계에 고정한다.
3. DriverSheet를 위상 순서로 평가해 매출, 마진, proforma, FCF, DCF 노드를 계산한다.
4. 각 노드에 provenance, refs, inputsHash, 품질 상태와 gap을 남긴다.
5. base와 stress 비교는 target, horizon, asOf를 동일하게 유지하고 scenario만 변경한다.

partial은 실패 값을 0으로 채운 상태가 아니다. 필요한 leaf가 없어서 해당 값이 None인 정직한 결손 상태다.

대표 반환 형태

SimulationResult
  scenarioName: str
  horizon: int
  latestAsOf: str | None
  revenuePath: list[float | None]
  marginPath: list[float | None]
  fcfPath: list[float | None]
  dcfPerShare: float | None
  quality: ok | partial
  gaps: list
  audit: list[NodeAudit]
  assumptionLedger: dict
  lensProducts: dict

답변은 시나리오 이름과 가정, 기준 기간, 조건부 값, 노드 근거를 함께 제시한다. dcfPerShare는 해당 시나리오 가정 아래의 계산값이며 목표주가나 성과 보장이 아니다.

기본 검증

• quality, gaps, latestAsOf, inputsHash가 함께 존재하는지 확인한다.
• 답변에 인용한 경로와 DCF 수치는 해당 valueRef, dateRef, executionRef와 직접 연결한다.
• base와 stress 비교는 target, horizon, asOf가 동일한지 확인한다.
• partial의 결손값을 0으로 바꾸지 않고 제한과 필요한 입력을 명시한다.

기대 원장과 거시 상태

• expectation ledger (dartlab.simulate.expectationCycle, 주기 실행 .github/workflows/expectationCycle.yml) 는 관측값, prior, 검증 상태를 분리 보관한다. 표본이 부족하면 검증된 것처럼 표시하지 않는다.
• 거시 시뮬레이션은 regime transition 과 결과 container 를 공통 타입으로 유지한다. 시나리오 가정과 실제 관측값을 같은 필드에 섞지 않는다.