표 기반 시각 설명

절차

• 먼저 실행 결과에서 tableRef가 있는지 확인한다.
• category와 metric이 각각 2개 이상 비교 가능한지 확인한다.
• CompileVisual은 tableRef 기반으로만 호출한다.
• visual이 실패하면 답변에 차트를 주장하지 않는다.
• ChartSpec 직접 만들 때는 dartlab.viz.refs.chartEvidenceBinding(...) 으로 evidenceBinding 을 채운다 — emit_chart 는 evidence 회로 진입점이 없는 spec 을 거부한다.
• datapoint 단위 drill-back 이 필요한 series 는 seriesPointRefs(...) 로 series[i].pointRefs 를 채운다.

공개 호출 방식

from dartlab.ai.tools.compileVisual import compileVisual

chart = compileVisual(
    chartType="bar",
    title="peer ROE 비교",
    data=peer_rows,
    xAxis="corpName",
    yAxis="roe",
    evidenceBinding={
        "tableRef": "table:peer:roe:latest",
        "source": "scan",
        "topic": "peerComparison",
    },
)

호출 동작

• 표에서 파생 가능한 차트만 만든다. 단일값/근거 없는 장식 시각화는 만들지 않는다.
• 실행 전에 target, period/date, metric, source 또는 universe를 확인한다.
• 데이터가 없거나 runtime 제한이 있으면 값을 추정하지 않고 한계와 필요한 다음 수집 경로를 말한다.

대표 반환 형태

• ChartResult 또는 visual spec dict를 반환한다. 핵심 키는 data/tableRef, marks, x, y, unit, title, warnings다.
• 전체 세부 필드는 공개 docstring/capability와 동기화한다. 코드/API 변경으로 이 설명이 오래되면 skill 갱신 누락으로 본다.

기본 검증

• 실행 결과는 tableRef, valueRef, dateRef, executionRef 중 필요한 근거로 남긴다.
• 최종 판단의 숫자 claim은 해당 table/value ref에 직접 묶는다.
• 스킬과 실제 공개 API의 호출 방식, 대표 반환 형태, 오류/제한 동작이 다르면 같은 변경에서 스킬을 갱신한다.