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

package/server/service/ai/types.ts

@@ -0,0 +1,619 @@
+/**
+ * BoardImportAI — board-import 의 **도메인 AI 인터페이스**.
+ *
+ * Provider 추상화 (chat/JSON/vision) 는 `@things-factory/ai-client-base` 의 `AIClient` 가 담당.
+ * 이 모듈은 board-import 의 도메인 메서드 (컨벤션 추론, Few-shot 분류, 도면 이미지 파싱,
+ * 자연어 → ImportRule) 만 정의하고, 기본 구현은 base AIClient 위에 LLM 프롬프트로 만든다.
+ *
+ * 사용 예:
+ * ```ts
+ * import { createAIClient } from '@things-factory/ai-client-base'
+ * import { setAIClient, DefaultBoardImportAI } from '@things-factory/board-import'
+ *
+ * const base = createAIClient({ provider: 'anthropic', apiKey: '...' })
+ * setAIClient(new DefaultBoardImportAI(base))
+ * ```
+ *
+ * Phase 1-2 결정적 파이프라인은 AI 미사용. 위 등록은 Phase 3+ 메서드 활성화용.
+ */
+import {
+  getDefaultAIClient,
+  parseJSONResponse,
+  type AIClient as BaseAIClient
+} from '@things-factory/ai-client-base'
+import type { ComponentCategory, ImportRule } from '../types/registry'
+import type { UniversalEntity } from '../types/index'
+
+export interface BoardImportAI {
+  /** 식별자 — 보통 base.id 와 동일 (provider:model) */
+  readonly id: string
+
+  /**
+   * 미매칭 entity 묶음을 보고 컨벤션 규칙을 추론.
+   * 예: "STK_001, STK_002 가 stocker 인 것 같습니다" → 정규식 규칙 제안
+   */
+  inferConventions?(
+    entities: UniversalEntity[],
+    options?: ConventionInferenceOptions
+  ): Promise<RuleSuggestion[]>
+
+  /**
+   * 사용자가 일부 entity 를 라벨링했을 때, 나머지 미라벨 entity 의 카테고리·type 을 추론.
+   * Few-shot 분류.
+   */
+  classifyEntities?(
+    labeled: LabeledEntity[],
+    unlabeled: UniversalEntity[],
+    options?: ClassificationOptions
+  ): Promise<EntityClassification[]>
+
+  /**
+   * 도면 이미지(PNG/JPG/PDF 페이지) 에서 객체를 검출하여 UniversalEntity 로 변환.
+   *
+   * 1-pass structured response 를 권장 — view type 자동 분류 + entity 추출을 단일 vision
+   * 호출로 처리해 토큰 비용을 절반으로 줄인다. 응답 형태:
+   *   - **`ImageAnalysis`** 객체: `{ viewType, confidence, entities, reasoning? }`
+   *   - 또는 **`UniversalEntity[]`** 직접 (구버전 호환).
+   * ImageAdapter 는 양쪽을 모두 정규화 처리.
+   *
+   * Phase 3 (이미지 어댑터) 에서 사용.
+   */
+  parseFromImage?(
+    image: Buffer | Uint8Array,
+    options?: ImageParseOptions
+  ): Promise<ImageAnalysis | UniversalEntity[]>
+
+  /**
+   * 자연어 매핑 정의 ("STK는 stocker, BUF는 buffer") → ImportRule[] 로 변환.
+   */
+  parseNaturalLanguageMapping?(
+    text: string,
+    availableTypes: string[]
+  ): Promise<ImportRule[]>
+}
+
+// ── 옵션 / 결과 타입 ────────────────────────────────────────────────
+
+export interface ConventionInferenceOptions {
+  /** 알려진 도메인 type 후보 (LLM 이 이 안에서 고르도록) */
+  knownTypes?: string[]
+  /** 카테고리 후보 */
+  categories?: ComponentCategory[]
+  /** 최대 제안 개수 */
+  maxSuggestions?: number
+}
+
+export interface RuleSuggestion {
+  /** 자동 생성된 ImportRule 후보 */
+  rule: ImportRule
+  /** 0..1 신뢰도 */
+  confidence: number
+  /** 추론 근거 */
+  reasoning?: string
+}
+
+export interface ClassificationOptions {
+  knownTypes?: string[]
+  categories?: ComponentCategory[]
+}
+
+export interface LabeledEntity {
+  entity: UniversalEntity
+  type: string
+  category?: ComponentCategory
+}
+
+export interface EntityClassification {
+  entityUid: string
+  type: string
+  category: ComponentCategory
+  confidence: number
+}
+
+export interface ImageParseOptions {
+  /** 자연어 컨텍스트. 예: "factory floor plan with AGV paths" */
+  context?: string
+  categories?: ComponentCategory[]
+  /**
+   * 사용자 자유서술 hint — 도면 설명 / 강조 / 카테고리 가이드 등.
+   * 1-pass VLM 프롬프트에 합류해 view type 분류 + entity 추출 양쪽에 영향.
+   */
+  userPrompt?: string
+  /** 이미지 dimension — 픽셀 좌표계 명시용 (top-down 모드에서). */
+  imageWidth?: number
+  imageHeight?: number
+  /**
+   * View type 강제. 미지정 시 VLM 이 자동 분류.
+   * - 'top-down': 픽셀 좌표 그대로
+   * - 'perspective-3d' / 'photo': floor plan 좌표 추정 (0..1000 단위)
+   */
+  viewType?: 'top-down' | 'perspective-3d' | 'photo'
+}
+
+/**
+ * 1-pass VLM 응답의 구조화된 결과 — **다중 시안 (variants)** 포함.
+ *
+ * 같은 도면을 AI 가 3 가지 다른 관점으로 해석. 사용자가 review 에서 선택.
+ *
+ * 시안 축 (프롬프트가 제시) 예시:
+ *   - 장비(equipment) 중심 / 운송(transport) 중심 / 영역(region) 중심
+ *   - 보수적(conservative) / 균형(balanced) / 공격적(aggressive)
+ *
+ * 각 시안은 독립적인 entities + subjectName/subjectDescription + importStrategy.
+ * viewType / confidence / reasoning 은 시안 무관 공통 (도면 자체의 특성).
+ */
+export interface ImageAnalysis {
+  /** 자동 분류된 view type — 시안 무관 공통. */
+  viewType: 'top-down' | 'perspective-3d' | 'photo'
+  /** 분류 신뢰도 (0..1). LLM 자기보고. */
+  confidence: number
+  /** 분류 근거 한 줄 (왜 이 viewType 인가). */
+  reasoning?: string
+  /** 시안 풀세트. 보통 3 개 — variants[0] 가 default. */
+  variants: ImageAnalysisVariant[]
+}
+
+/**
+ * 한 시안의 풀데이터 — entities + 정체성 + 의도.
+ * 각 시안은 같은 도면이지만 다른 해석.
+ */
+export interface ImageAnalysisVariant {
+  /** URL 친화적 short id. */
+  id: string
+  /** 사용자에게 보여줄 한글 라벨. 예: "장비 중심" */
+  label: string
+  /** 짧은 한 줄 설명 — 이 시안의 강조점. */
+  description?: string
+  /** 추출된 entity 목록. 좌표 의미는 ImageAnalysis.viewType 에 따름. */
+  entities: UniversalEntity[]
+  /**
+   * 보드 정체성 — 도면이 무엇을 나타내는가의 짧은 제목 (≤30자). 보드 name 자동 추천 기반.
+   * 처리 과정이 아니라 **컨텐츠 정체성** 만.
+   */
+  subjectName?: string
+  /**
+   * 보드 정체성 — 도면이 나타내는 시설/배치/구성 1-2 문장. 보드 description 자동 추천 기반.
+   * 처리 과정 X (importStrategy 와 분리).
+   */
+  subjectDescription?: string
+  /**
+   * AI 의 의도 narrative — "왜 이 시안에서 이렇게 해석했나". 3-5 문장.
+   * **transient — wizard review 카드 전시용. 영속 description 에는 사용 X.**
+   */
+  importStrategy?: string
+}
+
+// ── 기본 구현 — base AIClient 위에 LLM 프롬프트로 ────────────────────
+
+interface SingleVariantResult {
+  viewType: 'top-down' | 'perspective-3d' | 'photo'
+  confidence: number
+  reasoning?: string
+  variant: ImageAnalysisVariant
+}
+
+export class DefaultBoardImportAI implements BoardImportAI {
+  readonly id: string
+
+  private static readonly VARIANT_AXES = [
+    {
+      id: 'equipment-focus',
+      label: '장비 중심',
+      instruction: '장비/설비(machine/stocker/facility) 식별 우선. 이동체/경로는 보조.'
+    },
+    {
+      id: 'transport-focus',
+      label: '운송 중심',
+      instruction: '차량/경로(AGV/forklift/conveyor) 식별 우선. 정적 장비는 영역으로 묶음.'
+    },
+    {
+      id: 'region-focus',
+      label: '구역 중심',
+      instruction: '영역/구획(zone/wall/structure) 식별 우선. 개별 장비는 generic placeholder.'
+    }
+  ] as const
+
+  constructor(private base: BaseAIClient) {
+    this.id = base.id
+  }
+
+  async inferConventions(
+    entities: UniversalEntity[],
+    options: ConventionInferenceOptions = {}
+  ): Promise<RuleSuggestion[]> {
+    const sample = entities.slice(0, 100).map(e => ({
+      uid: e.uid,
+      name: e.attribs.name,
+      layer: e.attribs.layer,
+      kind: e.kind,
+      shape: e.attribs.shape
+    }))
+    const knownTypes = options.knownTypes ?? []
+    const categories = options.categories ?? []
+    const maxSuggestions = options.maxSuggestions ?? 5
+
+    const prompt = `You analyze CAD/IFC drawing entities and infer naming/layer conventions for an import pipeline.
+
+Unmatched entities (sample):
+${JSON.stringify(sample, null, 2)}
+
+Available component types: ${knownTypes.length ? knownTypes.join(', ') : '(any)'}
+Available categories: ${categories.length ? categories.join(', ') : '(any)'}
+
+Suggest up to ${maxSuggestions} convention rules. For each, return:
+- rule.componentType: chosen type
+- rule.category: one of available categories (or 'unknown')
+- rule.match.cad.blockNamePattern: regex pattern source string (e.g. "^STK_")
+- rule.match.cad.layer: optional regex source string
+- rule.build.idStrategy: 'fromAttribute' or 'auto'
+- confidence: 0..1
+- reasoning: short explanation`
+
+    const raw = await this.base.generateJSON<any[]>(prompt, { systemPrompt: SYSTEM_HINT })
+    return Array.isArray(raw) ? raw.map(r => ({ ...r, rule: hydrateRuleRegexes(r.rule) })) : []
+  }
+
+  async classifyEntities(
+    labeled: LabeledEntity[],
+    unlabeled: UniversalEntity[],
+    options: ClassificationOptions = {}
+  ): Promise<EntityClassification[]> {
+    const examples = labeled.map(l => ({
+      name: l.entity.attribs.name,
+      layer: l.entity.attribs.layer,
+      kind: l.entity.kind,
+      type: l.type,
+      category: l.category
+    }))
+    const targets = unlabeled.map(e => ({
+      uid: e.uid,
+      name: e.attribs.name,
+      layer: e.attribs.layer,
+      kind: e.kind
+    }))
+
+    const prompt = `Few-shot entity classification.
+
+Labeled examples:
+${JSON.stringify(examples, null, 2)}
+
+Available types: ${(options.knownTypes ?? []).join(', ') || '(any)'}
+Available categories: ${(options.categories ?? []).join(', ') || '(any)'}
+
+Classify these unlabeled entities. Return JSON array of:
+- entityUid
+- type
+- category
+- confidence: 0..1
+
+Targets:
+${JSON.stringify(targets, null, 2)}`
+
+    const raw = await this.base.generateJSON<EntityClassification[]>(prompt, { systemPrompt: SYSTEM_HINT })
+    return Array.isArray(raw) ? raw : []
+  }
+
+  async parseFromImage(
+    image: Buffer | Uint8Array,
+    options: ImageParseOptions = {}
+  ): Promise<ImageAnalysis> {
+    if (!this.base.vision) {
+      throw new Error(`AI client (${this.base.id}) does not support vision input`)
+    }
+
+    const results = await Promise.allSettled(
+      DefaultBoardImportAI.VARIANT_AXES.map(axis => this._callOneVariant(image, axis, options))
+    )
+
+    const succeeded = results
+      .filter((r): r is PromiseFulfilledResult<SingleVariantResult> => r.status === 'fulfilled')
+      .map(r => r.value)
+
+    if (succeeded.length === 0) {
+      const errors = (results as PromiseRejectedResult[]).map(r => r.reason?.message ?? String(r.reason))
+      throw new Error(`All variant calls failed: ${errors.join('; ')}`)
+    }
+
+    const forcedVT = options.viewType
+    const viewType = forcedVT ?? consensusViewType(succeeded.map(r => r.viewType))
+    const confidence = succeeded.reduce((s, r) => s + r.confidence, 0) / succeeded.length
+    const reasoning = succeeded.find(r => r.reasoning)?.reasoning
+
+    return { viewType, confidence, reasoning, variants: succeeded.map(r => r.variant) }
+  }
+
+  private async _callOneVariant(
+    image: Buffer | Uint8Array,
+    axis: { id: string; label: string; instruction: string },
+    options: ImageParseOptions
+  ): Promise<SingleVariantResult> {
+    const w = options.imageWidth
+    const h = options.imageHeight
+    const userHint = options.userPrompt?.trim()
+    const forcedViewType = options.viewType
+
+    const dimsLine =
+      Number.isFinite(w) && Number.isFinite(h)
+        ? `\nImage dimensions: ${w} x ${h} pixels.`
+        : ''
+
+    const viewTypeInstruction = forcedViewType
+      ? `\nThe view type is GIVEN: "${forcedViewType}". Do not classify; use it as-is.`
+      : `\nFirst, classify the view type:
+  - "top-down": orthographic floor plan / 2D engineering drawing seen from directly above
+  - "perspective-3d": 3D rendering / isometric / bird's-eye view with visible depth
+  - "photo": photograph of a physical space`
+
+    const coordRule = `\nCoordinate convention by viewType:
+  - "top-down": INTEGER PIXEL coordinates (origin top-left, x →, y ↓)${
+    Number.isFinite(w) && Number.isFinite(h) ? ` in [0, ${w}] x [0, ${h}]` : ''
+  }. Each entity ≥ 16x16 pixels.
+  - "perspective-3d" / "photo": INFER the FLOOR PLAN layout (where each object would be on a flat floor seen from above, NOT screen positions). Use arbitrary plan units in [0, 1000] x [0, 1000]. Object size in plan units (e.g. 50x80 for a stocker).
+NEVER use normalized 0..1 coordinates.`
+
+    const prompt = `Analyze this drawing image and provide ONE interpretation with focus axis: "${axis.id}".
+Focus: ${axis.instruction}${
+      userHint ? '\n\nUser hints (highest priority): ' + userHint : ''
+    }${options.context ? '\nContext: ' + options.context : ''}${
+      options.categories ? '\nPossible categories: ' + options.categories.join(', ') : ''
+    }${dimsLine}${viewTypeInstruction}${coordRule}
+
+Return STRICT JSON (no markdown, no commentary) with this shape:
+{
+  "viewType": "top-down" | "perspective-3d" | "photo",
+  "confidence": 0..1,
+  "reasoning": "brief one-sentence explanation of view type classification",
+  "variant": {
+    "id": "${axis.id}",
+    "label": "한글 라벨 (예: ${axis.label})",
+    "description": "한 줄 — 이 시안의 강조점",
+    "subjectName": "≤30 char short title — what the depicted facility is",
+    "subjectDescription": "1-2 sentences in Korean — what is depicted (NOT how you analyzed)",
+    "importStrategy": "3-5 sentence narrative explaining YOUR INTENT for this variant",
+    "entities": [
+      {
+        "uid": "string",
+        "kind": "shape" | "path" | "text",
+        "position": { "x": number, "y": number },
+        "size": { "width": number, "height": number },
+        "bbox": { "min": {"x": number, "y": number}, "max": {"x": number, "y": number} },
+        "attribs": {
+          "name": "string?",
+          "semanticType": "string?",
+          "text": "string?",
+          "layer": "string?",
+          "categoryHint": "container | vehicle | path | region | equipment | io | marker | structure"
+        }
+      }
+    ]
+  }
+}
+
+categoryHint should be one of the listed categories; omit only if highly uncertain.
+Provide 10-30 distinct entities clearly identifiable under the "${axis.id}" axis.
+
+attribs.name — IMPORTANT for component identity / data binding:
+  - If you see a TEXT LABEL on/near the entity in the drawing (e.g. "STK_001", "AGV-3", "CV1"), use that EXACTLY as the name.
+  - DO NOT invent labels not in the drawing — leave attribs.name empty if uncertain.
+  - Keep alphanumeric + hyphens / underscores. No spaces. ≤24 chars. UNIQUE within the variant.
+
+subjectName + subjectDescription — describe WHAT the board depicts (its identity), NOT what you did.
+  These become the board's persistent name + description if the user picks this variant.
+
+importStrategy — Korean 3-5 sentences: what this variant emphasizes, how you decided categories, areas of uncertainty.
+Used in the wizard review card only; transient — separate from board description.`
+
+    const raw = await this.base.vision!(image as Buffer, prompt, { maxTokens: 4096 })
+    return parseSingleVariantResponse(raw, axis.id, axis.label, forcedViewType)
+  }
+
+  async parseNaturalLanguageMapping(
+    text: string,
+    availableTypes: string[]
+  ): Promise<ImportRule[]> {
+    const prompt = `Convert the following user description into ImportRule[] entries for the board-import pipeline.
+
+Description: "${text}"
+Available component types: ${availableTypes.join(', ')}
+
+Return JSON array of:
+- componentType
+- category (one of: container, vehicle, path, region, equipment, io, marker, structure, unknown)
+- match.cad.blockNamePattern: regex source string (e.g. "^STK_")
+- match.cad.layer: optional regex source string
+- build.idStrategy: 'fromAttribute' or 'auto'`
+
+    const raw = await this.base.generateJSON<any[]>(prompt, { systemPrompt: SYSTEM_HINT })
+    return Array.isArray(raw) ? raw.map(hydrateRuleRegexes) : []
+  }
+}
+
+// ── 유틸 ─────────────────────────────────────────────────────────────
+
+const SYSTEM_HINT =
+  'You are a CAD/IFC drawing analysis assistant. Output strict JSON only — no commentary, no markdown.'
+
+const VIEW_TYPES = ['top-down', 'perspective-3d', 'photo'] as const
+
+function parseSingleVariantResponse(
+  rawText: string,
+  axisId: string,
+  axisLabel: string,
+  forcedViewType?: 'top-down' | 'perspective-3d' | 'photo'
+): SingleVariantResult {
+  const parsed = parseJSONResponse<any>(rawText)
+  const trimmed = (s: any) => (typeof s === 'string' && s.trim() ? s.trim() : undefined)
+
+  const rawVT = parsed?.viewType
+  const viewType: 'top-down' | 'perspective-3d' | 'photo' =
+    forcedViewType ??
+    ((VIEW_TYPES as readonly string[]).includes(rawVT)
+      ? (rawVT as 'top-down' | 'perspective-3d' | 'photo')
+      : 'top-down')
+  const confidence =
+    typeof parsed?.confidence === 'number' && parsed.confidence >= 0 && parsed.confidence <= 1
+      ? parsed.confidence
+      : 0.5
+
+  const v = parsed?.variant ?? {}
+  const variant: ImageAnalysisVariant = {
+    id: typeof v.id === 'string' && v.id ? v.id : axisId,
+    label: typeof v.label === 'string' && v.label ? v.label : axisLabel,
+    description: trimmed(v.description),
+    entities: Array.isArray(v.entities) ? v.entities : [],
+    subjectName: trimmed(v.subjectName),
+    subjectDescription: trimmed(v.subjectDescription),
+    importStrategy: trimmed(v.importStrategy)
+  }
+
+  return { viewType, confidence, reasoning: trimmed(parsed?.reasoning), variant }
+}
+
+function consensusViewType(
+  viewTypes: Array<'top-down' | 'perspective-3d' | 'photo'>
+): 'top-down' | 'perspective-3d' | 'photo' {
+  const counts = new Map<string, number>()
+  for (const vt of viewTypes) counts.set(vt, (counts.get(vt) ?? 0) + 1)
+  let best: 'top-down' | 'perspective-3d' | 'photo' = 'top-down'
+  let max = 0
+  for (const [vt, count] of counts) {
+    if (count > max) {
+      max = count
+      best = vt as 'top-down' | 'perspective-3d' | 'photo'
+    }
+  }
+  return best
+}
+
+/**
+ * VLM 의 JSON 응답을 ImageAnalysis 형태로 정규화 — 다중 시안 (variants) 지원.
+ *
+ * 허용 입력 형태:
+ *  - `{ viewType, confidence, reasoning?, variants: [...] }` — **최신 권장** (multi-variant)
+ *  - `{ viewType, ..., entities }` — 구버전 single-variant (자동으로 variants:[default] 으로 감쌈)
+ *  - `[ entity, ... ]` — 가장 구버전 (entities 만)
+ *
+ * 결손 / 비정상 viewType 은 'top-down' fallback. forcedViewType 이 주어지면 그 값 강제.
+ */
+export function normalizeImageAnalysisResponse(
+  rawText: string,
+  forcedViewType?: 'top-down' | 'perspective-3d' | 'photo'
+): ImageAnalysis {
+  const parsed = parseJSONResponse<any>(rawText)
+  const trimmed = (s: any) => (typeof s === 'string' && s.trim() ? s.trim() : undefined)
+
+  if (Array.isArray(parsed)) {
+    return {
+      viewType: forcedViewType ?? 'top-down',
+      confidence: 0.5,
+      variants: [{ id: 'default', label: 'default', entities: parsed }]
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return {
+      viewType: forcedViewType ?? 'top-down',
+      confidence: 0,
+      variants: [{ id: 'default', label: 'default', entities: [] }]
+    }
+  }
+  const rawVT = parsed.viewType
+  const viewType =
+    forcedViewType ??
+    ((VIEW_TYPES as readonly string[]).includes(rawVT) ? rawVT : 'top-down')
+  const confidence =
+    typeof parsed.confidence === 'number' && parsed.confidence >= 0 && parsed.confidence <= 1
+      ? parsed.confidence
+      : 0.5
+
+  // variants 배열 정규화 — 최신 권장 형태
+  let variants: ImageAnalysisVariant[]
+  if (Array.isArray(parsed.variants) && parsed.variants.length > 0) {
+    variants = parsed.variants.map((v: any, i: number) => ({
+      id: typeof v?.id === 'string' && v.id ? v.id : `variant-${i + 1}`,
+      label: typeof v?.label === 'string' && v.label ? v.label : `Variant ${i + 1}`,
+      description: trimmed(v?.description),
+      entities: Array.isArray(v?.entities) ? v.entities : [],
+      subjectName: trimmed(v?.subjectName),
+      subjectDescription: trimmed(v?.subjectDescription),
+      importStrategy: trimmed(v?.importStrategy)
+    }))
+  } else {
+    // 구버전 호환 — top-level entities + subjectName 등을 단일 variant 로 감쌈
+    variants = [
+      {
+        id: 'default',
+        label: 'default',
+        entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+        subjectName: trimmed(parsed.subjectName),
+        subjectDescription: trimmed(parsed.subjectDescription),
+        importStrategy: trimmed(parsed.importStrategy)
+      }
+    ]
+  }
+
+  return {
+    viewType,
+    confidence,
+    reasoning: trimmed(parsed.reasoning),
+    variants
+  }
+}
+
+/**
+ * LLM 응답의 regex pattern 문자열 → 실제 RegExp.
+ * 보통 "^STK_" 같은 source string 으로 응답.
+ */
+function hydrateRuleRegexes<T extends { match?: any }>(rule: T): T {
+  if (!rule || !rule.match) return rule
+  const cad = rule.match.cad
+  if (cad) {
+    const newCad = { ...cad }
+    if (typeof newCad.blockNamePattern === 'string') {
+      try {
+        newCad.blockNamePattern = new RegExp(newCad.blockNamePattern)
+      } catch {
+        // invalid regex — 패턴 무시
+        delete newCad.blockNamePattern
+      }
+    }
+    if (typeof newCad.layer === 'string') {
+      const m = newCad.layer.match(/^\/(.+)\/([a-z]*)$/)
+      if (m) {
+        try { newCad.layer = new RegExp(m[1], m[2]) } catch { /* keep as string */ }
+      }
+    }
+    rule.match = { ...rule.match, cad: newCad }
+  }
+  return rule
+}
+
+// ── Provider 등록 ──────────────────────────────────────────────────
+
+let currentClient: BoardImportAI | undefined
+let defaultBackedClient: BoardImportAI | undefined
+let defaultBackedFor: BaseAIClient | undefined
+
+export function setAIClient(client: BoardImportAI | undefined): void {
+  currentClient = client
+}
+
+/**
+ * 등록된 BoardImportAI 가 있으면 그걸 반환.
+ * 없으면 ai-client-base 의 default AIClient (config.aiClient) 를 `DefaultBoardImportAI` 로
+ * 감싸서 반환 — board-ai 와 동일한 1회 설정만으로 image import 도 동작하게 한다.
+ *
+ * default base 가 바뀌면 (테스트 등) 캐시를 무효화하고 다시 감싼다.
+ */
+export function getAIClient(): BoardImportAI | undefined {
+  if (currentClient) return currentClient
+  const base = getDefaultAIClient()
+  if (!base) return undefined
+  if (defaultBackedFor !== base) {
+    defaultBackedFor = base
+    defaultBackedClient = new DefaultBoardImportAI(base)
+  }
+  return defaultBackedClient
+}
+
+/** Deprecated alias — 기존 코드 호환용. 새로 작성 시 BoardImportAI 사용. */
+export type AIClient = BoardImportAI