@things-factory/board-ai 10.0.0-beta.108

package/server/service/assistant-llm-smoke.test.ts

@@ -0,0 +1,296 @@
+/**
+ * 실제 LLM 통합 스모크 테스트 (gated).
+ *
+ * 단위 / 통합 / 호스트 dispatcher 테스트 (3-layer 자동화) 가 mock 으로 잡지 못하는
+ * 한 가지: **실제 LLM 이 우리 tool catalog 를 보고 사용자 의도에 맞는 tool 을
+ * 선택하는가**. mock 으로는 tool 선택 결정을 시뮬레이션할 수 없다.
+ *
+ * 정책:
+ *   - **Default 비활성** — RUN_LLM_SMOKE=1 환경변수 + provider API key 필요.
+ *     `yarn test` 매 실행마다 돌리면 비용 누적 + 시간 소요 + 외부 의존성.
+ *   - 릴리즈 게이트 / nightly cron 에서만 실행 권장 (수동: `yarn test:llm-smoke`)
+ *   - 검증은 **느슨한** 매칭 — LLM 응답은 비결정적이라 tool 이름 집합에 포함되는지만
+ *     확인. 정확한 인자값은 검증하지 않는다.
+ *   - 실패 시 toolUsages 콘솔 출력해서 어떤 tool 을 골랐는지 디버그 가능.
+ *
+ * Provider 자동 선택 우선순위:
+ *   1. LLM_SMOKE_PROVIDER 명시 (anthropic | gemini | openai)
+ *   2. 환경 키 보유 순서: ANTHROPIC_API_KEY → GEMINI_API_KEY → OPENAI_API_KEY
+ */
+import {
+  createAIClient,
+  listRegisteredProviders,
+  type AIClient
+} from '@things-factory/ai-client-base'
+import { DefaultBoardAIAssistant } from './assistant'
+import type { ChatOptions } from './types'
+
+// providers 자동 등록 — import 만으로 registerAIProvider 발동
+import '@things-factory/ai-client-base'
+
+const RUN_FLAG = process.env.RUN_LLM_SMOKE === '1'
+
+interface ProviderResolution {
+  provider: 'anthropic' | 'gemini' | 'openai'
+  apiKey: string
+}
+
+function resolveProvider(): ProviderResolution | null {
+  const explicit = process.env.LLM_SMOKE_PROVIDER as 'anthropic' | 'gemini' | 'openai' | undefined
+  const candidates: Array<{ provider: 'anthropic' | 'gemini' | 'openai'; envKey: string }> = [
+    { provider: 'anthropic', envKey: 'ANTHROPIC_API_KEY' },
+    { provider: 'gemini', envKey: 'GEMINI_API_KEY' },
+    { provider: 'openai', envKey: 'OPENAI_API_KEY' }
+  ]
+  if (explicit) {
+    const match = candidates.find(c => c.provider === explicit)
+    if (match && process.env[match.envKey]) {
+      return { provider: match.provider, apiKey: process.env[match.envKey]! }
+    }
+    return null
+  }
+  for (const c of candidates) {
+    if (process.env[c.envKey]) {
+      return { provider: c.provider, apiKey: process.env[c.envKey]! }
+    }
+  }
+  return null
+}
+
+const resolved = RUN_FLAG ? resolveProvider() : null
+const ENABLED = !!resolved
+const describeIf = ENABLED ? describe : describe.skip
+
+const COMMON_OPTIONS: ChatOptions = {
+  knownTypes: ['rect', 'circle', 'text', 'gauge-circle'],
+  // 토큰 절약 + 빠른 응답
+  maxTokens: 1024,
+  temperature: 0.1
+}
+
+function makeClient(): AIClient {
+  // import 만으로는 jest 모듈 캐시 / hoisting 이슈로 registry 가 비어있을 수 있어
+  // 호출 시점에 등록 확인.
+  if (listRegisteredProviders().length === 0) {
+    // 강제 재로딩
+    require('@things-factory/ai-client-base')
+  }
+  return createAIClient({
+    provider: resolved!.provider,
+    apiKey: resolved!.apiKey
+  })
+}
+
+const TIMEOUT_MS = 90_000 // 다중 turn agentic loop 고려, 90초
+
+const dumpUsages = (usages: any) => {
+  if (usages) console.log('  toolUsages:', JSON.stringify(usages.map((u: any) => ({ name: u.name, kind: u.kind })), null, 2))
+}
+
+describeIf('LLM 스모크 — 실제 모델 tool 선택 검증', () => {
+  let client: AIClient
+  beforeAll(() => {
+    client = makeClient()
+    // eslint-disable-next-line no-console
+    console.log(`[llm-smoke] provider=${resolved!.provider} client.id=${client.id}`)
+  })
+
+  test(
+    '"안녕" → text-only (tool 호출 없음)',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat([{ role: 'user', content: '안녕' }], undefined, COMMON_OPTIONS)
+      expect(r.reply).toBeTruthy()
+      expect(r.patch).toBeUndefined()
+      expect(r.toolUsages ?? []).toHaveLength(0)
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"rect 하나 추가" → addComponent 호출',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: 'rect 하나 추가해줘' }],
+        { width: 1000, height: 600, components: [] } as any,
+        COMMON_OPTIONS
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      expect(names).toContain('addComponent')
+      expect(r.patch).toBeDefined()
+      expect(r.patch!.ops.some(op => op.op === 'add')).toBe(true)
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"선택한 컴포넌트 빨간색" + selectedRefids → modifyComponentByRefid',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: '선택한 컴포넌트를 빨간색으로 바꿔줘' }],
+        {
+          width: 1000,
+          height: 600,
+          components: [{ refid: 35, type: 'rect', left: 10, top: 20, fillStyle: '#fff' }]
+        } as any,
+        { ...COMMON_OPTIONS, selectedRefids: [35] }
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      // 받아들일 수 있는 경로: 직접 modify 또는 먼저 read 후 modify
+      expect(names).toContain('modifyComponentByRefid')
+      expect(r.patch?.ops.some(op => op.op === 'modify')).toBe(true)
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"왼쪽으로 정렬" + 다중 selection → alignComponents',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: '선택한 것들을 왼쪽으로 정렬해줘' }],
+        {
+          width: 1000,
+          height: 600,
+          components: [
+            { refid: 1, type: 'rect', left: 10, top: 0, width: 100, height: 50 },
+            { refid: 2, type: 'rect', left: 80, top: 100, width: 100, height: 50 }
+          ]
+        } as any,
+        { ...COMMON_OPTIONS, selectedRefids: [1, 2] }
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      expect(names).toContain('alignComponents')
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"보드 배경 어둡게" → modifyBoard',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: '보드 배경을 어둡게 해줘' }],
+        { width: 1000, height: 600, fillStyle: '#ffffff', components: [] } as any,
+        COMMON_OPTIONS
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      // modifyBoard 또는 atmosphere primer + modifyBoard 둘 다 OK
+      expect(names).toContain('modifyBoard')
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"심해 분위기로" → getAtmosphereGuide + modifyBoard 패턴',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: '이 보드를 심해 분위기로 만들어줘' }],
+        { width: 1000, height: 600, components: [] } as any,
+        COMMON_OPTIONS
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      // 핵심: AI 가 atmosphere primer 를 활용 (LLM 이 atmosphere 모르더라도 우리
+      // primer 가이드를 호출해야 일관된 결과 — 시스템 프롬프트의 의도)
+      expect(names).toContain('modifyBoard')
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"view 모드로" → setSceneMode action (ephemeral)',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: 'view 모드로 바꿔줘' }],
+        { width: 1000, height: 600, components: [] } as any,
+        COMMON_OPTIONS
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      expect(names).toContain('setSceneMode')
+      // ephemeral — patch 없음, actions 에 들어감
+      expect(r.actions?.some(a => a.action === 'setSceneMode')).toBe(true)
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"보드 전체 보이게" → fitToView action',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: '보드 전체가 보이게 화면 맞춰줘' }],
+        { width: 2000, height: 1200, components: [{ refid: 1, type: 'rect' }] } as any,
+        COMMON_OPTIONS
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      expect(names).toContain('fitToView')
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"선택한 거 화면 가운데" + selection → centerToComponent',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: '선택한 컴포넌트를 화면 가운데로 보여줘' }],
+        { width: 1000, height: 600, components: [{ refid: 7, type: 'rect' }] } as any,
+        { ...COMMON_OPTIONS, selectedRefids: [7] }
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      expect(names).toContain('centerToComponent')
+    },
+    TIMEOUT_MS
+  )
+
+  test(
+    '"refid 1 삭제" → removeComponentByRefid',
+    async () => {
+      const a = new DefaultBoardAIAssistant(client)
+      const r = await a.chat(
+        [{ role: 'user', content: 'refid 1번 컴포넌트 삭제해줘' }],
+        {
+          width: 1000,
+          height: 600,
+          components: [
+            { refid: 1, type: 'rect' },
+            { refid: 2, type: 'circle' }
+          ]
+        } as any,
+        COMMON_OPTIONS
+      )
+      const names = (r.toolUsages ?? []).map((u: any) => u.name)
+      dumpUsages(r.toolUsages)
+      expect(names).toContain('removeComponentByRefid')
+      expect(r.patch?.ops.some(op => op.op === 'remove')).toBe(true)
+    },
+    TIMEOUT_MS
+  )
+})
+
+// ── Skip 안내 — 사용법 노출 ───────────────────────────────────────
+if (!ENABLED) {
+  describe('LLM 스모크 — 비활성 안내', () => {
+    test('실행 방법', () => {
+      // 의도적 no-op — 사용법을 콘솔로만 노출. 비활성 상태에서도 jest 가 1 test 통과로 보고.
+      // eslint-disable-next-line no-console
+      console.log(
+        '[llm-smoke] 비활성. 실행: RUN_LLM_SMOKE=1 ANTHROPIC_API_KEY=sk-... yarn test:llm-smoke ' +
+          '(또는 GEMINI_API_KEY / OPENAI_API_KEY 중 하나).'
+      )
+      expect(true).toBe(true)
+    })
+  })
+}