microsoft/flint-chart 딥다이브
— 열 줄짜리 "차트 설계도"로 Vega-Lite·ECharts·Chart.js를 한 번에 뽑는 시각화 컴파일러

1프로젝트 한 줄 요약

microsoft/flint-chart(줄여서 Flint)는 차트를 "어떻게 그릴지" 일일이 지정하는 대신, "데이터가 무엇을 뜻하는지"와 "어떤 차트인지"만 짧게 선언하면 되도록 만든 오픈소스 시각화 도구다. 저장소가 내건 한 줄은 이것 — "Flint is a visualization language that lets AI agents reliably create expressive, good-looking charts from simple, human-editable chart specs."(AI 에이전트가 간단하고 사람이 편집 가능한 차트 스펙으로부터 표현력 있고 보기 좋은 차트를 안정적으로 만들게 해 주는 시각화 언어).

핵심은 두 개의 선언을 나눠 준다는 것이다. ① semantic_types — 각 데이터 열이 무슨 의미인지(예: price는 "금액", 202401은 "연월", rank는 "순위"). ② chart_spec — 어떤 차트 타입에 어떤 열을 어느 채널(x·y·color·size…)에 꽂을지. 대개 10줄 안팎이다. 그러면 Flint 컴파일러가 스케일·축·0 기준선·집계 방식·통화/퍼센트/날짜 포맷·색상 스킴·범례·여백·facet 격자·종횡비까지 전부 데이터 + 의미 + 차트타입으로부터 유도해, Vega-Lite / ECharts / Chart.js 각각의 완성된 네이티브 스펙을 뽑아낸다.

2왜 지금 주목받는가

Flint이 2개월 만에 별 1,800+를 모으며 트렌딩에 오른 이유는 "또 하나의 차트 라이브러리"여서가 아니다. 기존 선언형 문법(Vega-Lite·ECharts)이 의미와 저장표현이 어긋날 때 취약하다는 오래된 문제와, LLM 에이전트가 장황한 차트 스펙을 안정적으로 못 만든다는 새 문제를 동시에 겨냥했기 때문이다. 제작자는 Microsoft Research와 런민대(Renmin University) IDEAS Lab이며, 논문도 "coming soon"으로 예고돼 있다.

주목 포인트 1 — "선언형 문법이 의미를 모른다"는 근본 문제

Vega-Lite·ECharts 같은 문법은 저장 타입이 시각 매핑과 맞아떨어질 때는 훌륭하다. 문제는 의미가 저장표현과 어긋날 때 생긴다. 저장소 문서가 든 대표 실패 사례 세 가지 — ① 정수 202001은 사실 연월(시간 밴드)인데 크기 값으로 그려진다. ② 온도·비율처럼 더할 수 없는(non-additive) 측정값을 문법은 아무렇지 않게 스태킹해 버린다. ③ 손익·상관계수처럼 발산형(diverging) 필드를 순차 색상 램프에 잘못 매핑한다. 전문가는 긴 스펙을 손수 짜서 고칠 수 있지만, 필드 하나만 바꿔도 그 스펙이 통째로 깨진다. Flint은 "의미"를 1급으로 올려 이 취약성을 컴파일러가 책임지게 했다.

주목 포인트 2 — LLM 에이전트에게는 문제가 더 크다

에이전트가 차트를 그리려고 완전한 Vega-Lite 스펙을 통째로 생성하면 토큰이 비싸고, 작은 수정에도 스펙 전체를 다시 뱉어야 하며, 틀리기 쉽다. Flint의 접근은 정반대다 — 에이전트는 컴팩트하고 안정적인 프로그램(짧은 스펙)만 내보내고, "정확성"은 컴파일러가 맡는다. 그래서 MCP 서버·에이전트 스킬이 부록이 아니라 설계의 중심에 있다. "AI가 데이터로 차트를 그리는" 워크플로가 폭증하는 지금, 정확히 그 지점의 신뢰성 도구라는 점이 트렌딩의 동력이다.

3기술 스택 전체 지도

Flint은 npm workspaces 모노레포다("name": "flint-chart-monorepo"). 네 개의 워크스페이스로 나뉘고, 엔진 요구사항은 Node ≥ 18이다. 흥미로운 설계 결정 하나 — 코어 라이브러리는 런타임 의존성이 0개이고, 실제 렌더러(Vega·ECharts·Chart.js)는 전부 선택적 peer dependency다. 즉 코어는 순수 TypeScript로 "스펙 객체"만 뱉고, 무거운 렌더링 라이브러리는 그걸 쓰는 쪽이 골라 설치한다.

코어 flint-chart (packages/flint-js)

언어는 TypeScript ^5.6, ESM 우선("type": "module", "sideEffects": false)에 CJS/ESM 이중 출력. 빌드는 tsup ^8.3, 테스트는 vitest ^4.1, 린트는 eslint ^9 + typescript-eslint ^8. 서브패스 export(./core, ./vegalite, ./echarts, ./chartjs, ./test-data, ./gallery)로 필요한 부분만 가져온다.

// packages/flint-js — peerDependencies (전부 optional: 쓰는 렌더러만 설치)
"peerDependencies": {
  "chart.js":  "^4.0.0",
  "echarts":   "^5.0.0 || ^6.0.0",
  "vega":      "^5.0.0 || ^6.0.0",
  "vega-lite": "^5.0.0 || ^6.0.0"
}
// ★ 코어 자체의 runtime dependencies = 0개 (순수 TS가 plain 객체를 반환)

MCP 서버 flint-chart-mcp (packages/flint-mcp)

바이너리 flint-chart-mcp(→ dist/cli.js)로 실행한다. 여기는 렌더러들을 실제 의존성으로 품는다 — 서버가 직접 PNG/SVG를 그려 에이전트에 돌려줘야 하기 때문이다.

Python 포팅 flint-py · 데모 사이트

flint-py는 코어의 near 1:1 이식(파이썬 ≥ 3.10, 유일 런타임 의존성 python-dateutil). 도구체인은 uv(락파일) + ruff + pytest. JS 구현과의 "갤러리 패리티(parity)"를 자동 평가하는 하니스(tools/run_full_eval.py)까지 있어, 두 구현이 같은 결과를 내는지 공유 픽스처로 검증한다. 데모 site/는 Vega-Lite/ECharts/Chart.js 세 뷰 컴포넌트 + JSON 라이브 에디터로, flint-chart를 소스(packages/flint-js/src)로 alias 걸어 라이브러리 수정이 바로 hot-reload 된다.

4아키텍처 심화 분석

Flint은 스스로를 컴파일러로 명시한다. 공유되는 프론트엔드 + 옵티마이저가 있고, 백엔드마다 코드 생성기가 따로 있다. 핵심 통찰은 1·2단계(시맨틱 + 레이아웃)는 100% 백엔드 독립이고, 오직 3단계만 백엔드별로 다르다는 것. 그래서 새 렌더링 백엔드(예: Plotly)를 추가하려면 3단계만 구현하면 된다.

이 파이프라인의 중심 오케스트레이션은 packages/flint-js/src/vegalite/assemble.ts(1,152줄)에 있다. 아래는 이 컴파일러를 떠받치는 세 가지 핵심 설계 패턴이다.

설계 패턴 ① 동적 템플릿(Dynamic Template) — 전략 + 레지스트리

모든 chartType 이름은 하나의 ChartTemplateDef에 매핑된다. 백엔드마다 레지스트리(vlTemplateDefs 등)가 있고 이름으로 조회한다. 30개가 넘는 차트가 전부 같은 인터페이스를 구현하되, 생명주기 훅(declareLayoutMode → normalizeEncodings → instantiate → postProcess)으로 개별 동작을 끼워 넣는 플러그인 아키텍처다.

// core/types.ts — 모든 차트 타입이 구현하는 계약
interface ChartTemplateDef {
  chart: string;                    // "Bar Chart" — chart_spec.chartType과 일치
  template: any;                    // 네이티브 스펙 골격 { mark:"bar", encoding:{} }
  channels: string[];               // 허용 인코딩 채널
  markCognitiveChannel: 'position'|'length'|'area'|'color';
                                    // 마크가 크기를 어떻게 표현하나 → 0기준선·stretch 클래스 결정
  declareLayoutMode?: (cs, table) => LayoutDeclaration;  // 어느 축이 밴드형?
  instantiate: (spec, ctx) => void;                      // 최종 스펙 조립
  properties?: ChartPropertyDef[];       // 조절 노브(예: cornerRadius)
  pivot?: PivotDef;                      // named-view 변환(패턴 ③)
}

// vegalite/templates/bar.ts — 패턴 전체가 ~30줄에 담긴다
export const barChartDef: ChartTemplateDef = {
  chart: "Bar Chart",
  template: { mark: "bar", encoding: {} },
  channels: ["x","y","color","group","opacity","column","row"],
  markCognitiveChannel: 'length',        // 막대는 "길이"로 크기 표현
  declareLayoutMode: (cs, table) => {
    const r = detectBandedAxisFromSemantics(cs, table, { preferAxis: 'x' });
    return { axisFlags: r ? { [r.axis]: { banded: true } } : { x: { banded: true } } };
  },
  instantiate: (spec, ctx) => {
    defaultBuildEncodings(spec, ctx.resolvedEncodings);
    if (ctx.chartProperties?.cornerRadius > 0)
      spec.mark = setMarkProp(spec.mark, 'cornerRadius', ctx.chartProperties.cornerRadius);
    adjustBarMarks(spec, ctx);
  },
  encodingActions: [makeSortAction()],
  pivot: makeCartesianPivot({ transpose: [['x','y']], permute: [['x','y','color']] }),
};

설계 패턴 ② 물리 기반 auto-layout

옵티마이저는 두 숫자에서 출발한다 — baseSize(차트가 지향하는 목표 크기, 기본 400×320)와 canvasSize(절대 넘으면 안 되는 상한, 기본 = baseSize × maxStretch, maxStretch 기본 1.5×). 데이터가 늘면 기하 형태별로 다른 물리 모델로 크기를 키운다.

데이터가 그래도 안 들어가면 overflow 필터가 항목을 버리고 ChartWarning 메타데이터를 붙인다 — 읽을 수 없는 차트를 그리느니 경고와 함께 잘라낸다. 이 "물리를 레이아웃 휴리스틱으로" 쓰는 발상은 "제한된 공간에 콘텐츠 맞추기"라는 온갖 문제에 전이 가능한 아이디어다(라인 차트의 banking-to-45° 종횡비 최적화도 포함).

설계 패턴 ③ Named Views = 군(group)의 궤도(orbit)

차트 변형(축 뒤집기, 계열↔색상 교환, facet, 형제 차트로 전환)을 매번 스펙 재작성으로 얻는 대신, Flint은 이를 4개 생성원(generator)이 만드는 궤도로 모델링한다. 원저작 배치 a0에서 시작해 아래 연산을 조합해 걷는다.

중복 제거는 안정자 몫(stabilizer quotient)을 코드로 구현한 것이다 — flip을 두 번 하면 항등(identity), facet 후 jitter가 Strip Plot로 접히는 등 같은 상태로 수렴하는 변형을 자동 병합한다. 호환성은 타입으로 강제된다(σ는 같은 프로파일만, τ는 슬롯을 바꾸므로 프로파일을 넘나들 수 있음). 라인 차트는 τ를 생략해 "세로 라인 차트" 같은 무의미한 변형을 아예 제안하지 않는다. 구현은 core/pivot.ts. 추상대수(궤도·생성원·안정자)를 실전 UI 상태 열거에 쓴, 보기 드문 사례다.

5디렉토리 구조 해부

클론 직후의 최상위 구조와, 코어의 내부다. HEAD 커밋은 8e8d1d2, 전체 2,587 파일에 TS/Py 실코드 약 86,600줄이다.

core/가 이 프로젝트의 지적 핵심이다(백엔드 독립 1·2단계). 파일 크기순으로 무엇이 있는지 보면 "이 컴파일러가 진짜로 무슨 일을 하는지"가 드러난다.

6학습 포인트

Flint이 학습 표본으로 훌륭한 이유는 컴파일러 아키텍처, 계층형 타입 시스템, 물리 휴리스틱, 군론 응용, 플러그인 패턴, MCP 서버 엔지니어링, 에이전트 프롬프트 설계, 크로스언어 포팅이 한 저장소에 모여 있기 때문이다. 관심사별로 짚어 보자.

① 비(非)-언어 도메인에 적용한 컴파일러/IL 설계

프론트엔드/옵티마이저/코드생성 분리, "중간 표현(IR)" 프레이밍, "하나의 입력 → 여러 타깃"은 교과서적 컴파일러 구조를 차트라는 비-프로그래밍 도메인에 적용한 것이다. core/는 타깃 독립, vegalite|echarts|chartjs/는 백엔드 코드 생성기. "PL이 아닌 대상을 위한 컴파일러를 어떻게 짜는가"를 배우기 딱 좋다.

② 파서 없는 DSL / 문법 설계

Flint의 "언어"는 JSON 모양(ChartAssemblyInput)이라 렉서/파서 대신 정규화 + 축약 확장(맨 문자열 → {field})과 zod 스키마(MCP 계층)를 문법의 검증 표면으로 쓴다. "DSL이 꼭 자체 파서를 가질 필요는 없다 — 임베디드/JSON DSL도 엄밀한 타이핑이 가능하다"는 교훈.

③ graceful degradation을 갖춘 3계층 타입 시스템

type-registry.ts·semantic-types.ts의 3계층 격자(Family → Category → Specific)는, 거친 라벨(Measure)만 줘도 "일반적이지만 올바른" 결과를 내고 구체 라벨(Price)을 주면 완전한 포맷팅을 푼다. 불완전한/LLM 입력을 견디도록 설계하는 아름다운 예다. (README의 "70+ 타입" = Family 6 + Category 17 + Specific 46 ≈ 69개.)

④ 레이아웃 휴리스틱으로서의 물리

decisions.ts + compute-layout.ts + design-stretch-model.md. 축 크기를 스프링(elastic budget)·가스 압력으로 모델링하는 건 "제한 공간에 콘텐츠 맞추기"라는 온갖 문제에 전이 가능한 발상이다(라인 차트 banking-to-45° 종횡비 최적화 포함).

⑤ 실전 소프트웨어 속의 군론

pivot.ts의 궤도·생성원·안정자 몫으로 UI 상태를 열거·중복제거하는 건 추상대수의 드문 실전 응용이다. "이론이 코드가 되는" 감을 잡기에 최고의 사례.

⑥ 대규모 전략 + 레지스트리 패턴 · MCP 서버 엔지니어링

30+ 템플릿이 같은 ChartTemplateDef 인터페이스를 생명주기 훅으로 구현한 플러그인 구조. 그리고 flint-mcp/는 라이브러리를 에이전트에게 MCP 도구(render_chart·compile_chart·validate_chart·list_chart_types·create_chart_view), 리소스(flint://chart-types·flint://agent-skill), 프롬프트(author_flint_chart)로 노출하는 법 — stdio/HTTP 두 트랜스포트, CSP-safe 인프로세스 래스터화까지 — 실전 교본이다.

⑦ 에이전트 지향 프롬프트 설계 · 크로스언어 포팅

agent-skills/flint-chart-author/SKILL.md(566줄)는 "LLM을 위한 지시문"의 마스터클래스 — 정확한 차트 타입 표, "변환/필드명을 지어내지 말라", 데이터 정합성 체크리스트. 순수 프롬프트 엔지니어링 자료로도 값지다. flint-py는 공유 픽스처(shared/test-data/) + 패리티 평가로 두 구현을 동기화하는 규율을 보여 준다.

7시스템 요구사항 · 설치

Flint은 특별한 하드웨어가 필요 없다 — 순수 계산이라 GPU도 무관하다. 라이브러리로 쓰든, 에이전트용 MCP 서버로 쓰든 설치는 간단하다.

# 1) 라이브러리로 쓰기
npm install flint-chart
npm install vega vega-lite vega-embed   # 브라우저에서 Vega-Lite 렌더 시
npm install echarts                     # ECharts 백엔드
npm install chart.js                    # Chart.js 백엔드

# 2) 에이전트용 MCP 서버(전역 설치 불필요)
npx -y flint-chart-mcp

MCP 클라이언트(VS Code .vscode/mcp.json 또는 일반 mcpServers) 설정은 이렇게 한다.

{
  "mcpServers": {
    "flint-chart": { "command": "npx", "args": ["-y", "flint-chart-mcp"] }
  }
}

# 기여/개발 (저장소 루트에서)
git clone https://github.com/microsoft/flint-chart && cd flint-chart
npm install        # workspaces: flint-js + flint-mcp + site
npm run typecheck  # tsc
npm run test       # Vitest (JS+MCP);  npm run test:py → uv run pytest
npm run build      # tsup가 두 npm 패키지 빌드
npm run site       # http://localhost:5274 갤러리+에디터

8직접 해볼 수 있는 실습 과제

import { assembleVegaLite, assembleECharts, assembleChartjs } from 'flint-chart';
const input = {
  data: { values: myData },
  semantic_types: { weight: 'Quantity', mpg: 'Quantity', origin: 'Country' },
  chart_spec: { chartType: 'Scatter Plot',
    encodings: { x: {field:'weight'}, y: {field:'mpg'}, color: {field:'origin'} } },
};
assembleVegaLite(input); assembleECharts(input); assembleChartjs(input);

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

저장소 & 배포
· GitHub: github.com/microsoft/flint-chart (MIT)
· npm 코어: npmjs.com/package/flint-chart · MCP: npmjs.com/package/flint-chart-mcp

프로젝트 사이트(문서 · 갤러리 · 라이브 에디터)
· 홈: microsoft.github.io/flint-chart
· 라이브 에디터: /#/editor · 갤러리: /#/gallery · MCP 가이드: /#/mcp

저장소 내 핵심 문서
· docs/architecture.md(3단계 + named-views 군론) · docs/overview.md(동기) · docs/design-semantics.md(시맨틱 3계층) · docs/design-stretch-model.md(물리 레이아웃 수식) · docs/api-reference.md · agent-skills/flint-chart-author/SKILL.md

제작
· Microsoft Research (microsoft.com/research) × 런민대 IDEAS Lab (ideas-lab.net) · 논문 "coming soon"