viz

엔진 역할

viz 는 분석 결과를 차트 spec 으로 변환한다. 직접 차트 이미지를 그리지 않고 — spec dict 를 만들어 (a) emit_chart(spec) 로 stdout 마커 출력 → AI tool result 로 인라인 렌더 또는 (b) landing/static/charts/{code}/manifest.json 정적 빌드 → svelte ChartRenderer 가 등록 chartType 단일 분기 렌더.

evidence 회로 강제 — 모든 ChartSpec 은 evidenceBinding 또는 evidenceIds 가 채워져야 emit. drill-back 으로 차트 점 클릭 시 source 데이터 패널 진입.

공개 호출 방식

# RunPython 안에서
from dartlab.viz import emit_chart, emit_diagram
import dartlab

c = dartlab.Company("005930")
ratios = c.panel("ratios", freq="Q")

# 1. 시계열 line
emit_chart({
    "chartType": "line",
    "title": "영업이익률 추이",
    "data": [{"period": p, "value": v}
             for p, v in zip(ratios["period"], ratios["operatingMargin"])],
    "xAxis": "period",
    "yAxis": "value",
    "unit": "%",
    "evidenceBinding": {
        "tableRef": "table:005930:ratios:Q",
        "source": "dart",
        "stockCode": "005930",
        "topic": "ratios",
    },
})

# 2. peer 비교 bar
emit_chart({
    "chartType": "bar",
    "title": "peer ROE",
    "data": peer_rows,
    "xAxis": "stockCode",
    "yAxis": "roe",
    "evidenceIds": ["scan:profitability:2025Q3"],
})

# 3. 다이어그램 (mermaid)
emit_diagram("mermaid", "graph LR\n  A-->B\n  B-->C")

# 4. CompileVisual tool (AI 도구 경로 — auto evidence)
# LLM 이 자율 호출

# 회사 페이지 정적 차트 빌드
uv run python -X utf8 landing/_scripts/buildCompanyCharts.py --code 005930
# → landing/static/charts/005930/manifest.json + section JSON

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

차트 시각화에서 다음 4 룰 강행:

1. 차트 생성은 CompileVisual tool 1 회 — chartType + data + 인자. RunPython 직접 matplotlib/plotly 호출 금지 (visualRef 미발급 → UI 렌더 실패).
2. 모든 차트의 evidenceBinding 필수 — 차트 안 모든 값에 ref 박힌 source 명시. evidenceBinding 누락 시 거부 (해결책 포함 경고).
3. 데이터 부족 시 차트 만들지 마라 — 표 + coverage note 로 낮춘다. 환각 차트 (X 값 없는 그래프, peer 4 개 미만 분포 등) 금지.
4. 본문 안 차트 인용에 [visualRef:...] 표기 — UI 가 inline 렌더링하므로 ref id 필수.

호출 동작

emit_chart(spec) — ChartSpec dict 를 stdout 에 [VIZ_SPEC_START]...[VIZ_SPEC_END] 마커로 출력. agent 가 extract_viz_specs(stdout) 로 추출 → view_spec TraceEvent → 클라이언트 ChartRenderer 가 인라인 렌더. evidenceBinding 또는 evidenceIds 누락 시 거부 (해결책 포함 경고).