@things-factory/ai-client-base 10.0.0-beta.64

package/server/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @things-factory/ai-client-base — Provider-agnostic AI client abstraction.
+ *
+ * 사용 예:
+ * ```ts
+ * import { createAIClient } from '@things-factory/ai-client-base'
+ *
+ * const client = createAIClient({
+ *   provider: 'anthropic',
+ *   model: 'claude-sonnet-4-6',
+ *   apiKey: process.env.ANTHROPIC_API_KEY
+ * })
+ *
+ * const text = await client.chat([{ role: 'user', content: 'Hello' }])
+ * const json = await client.generateJSON<MyShape>('Return {"x": 1, "y": 2} as JSON')
+ * const desc = await client.vision(imageBuffer, 'What is in this image?')
+ * ```
+ */
+export * from './service/index.js'

package/server/service/factory.ts

@@ -0,0 +1,68 @@
+/**
+ * AI Provider 등록 + Client 생성.
+ *
+ * - 어댑터 패키지(또는 동일 패키지의 providers/) 가 모듈 로드 시 `registerAIProvider` 호출.
+ * - 호출자는 `createAIClient({ provider: 'anthropic', ... })` 로 인스턴스 획득.
+ * - things-factory env config 의 `aiClient` 키가 있으면 `getDefaultAIClient()` 가 자동 생성.
+ */
+import { config as envConfig } from '@things-factory/env'
+import type { AIClient, AIClientConfig, AIProviderFactory } from './types.js'
+
+const REGISTERED_PROVIDERS = new Map<string, AIProviderFactory>()
+
+export function registerAIProvider(name: string, factory: AIProviderFactory): void {
+  REGISTERED_PROVIDERS.set(name, factory)
+}
+
+export function listRegisteredProviders(): string[] {
+  return Array.from(REGISTERED_PROVIDERS.keys())
+}
+
+export function createAIClient(config: AIClientConfig): AIClient {
+  const factory = REGISTERED_PROVIDERS.get(config.provider)
+  if (!factory) {
+    throw new Error(
+      `Unknown AI provider "${config.provider}". Registered: ${listRegisteredProviders().join(', ') || '(none)'}`
+    )
+  }
+  return factory(config)
+}
+
+let _defaultClient: AIClient | undefined
+
+/**
+ * 기본 client.
+ *  1) `setDefaultAIClient()` 로 명시 설정된 게 있으면 그것
+ *  2) env config 의 `aiClient` 키가 있으면 거기서 생성
+ *  3) 없으면 undefined (호출자는 nullable 처리)
+ *
+ * 다른 모듈 (예: codelingua) 의 `openai` 키와는 의도적으로 분리. 두 키는 서로 모르고 동작.
+ *
+ * 잘못된 config (provider 누락, 등록되지 않은 provider) 는 console.warn 후 undefined.
+ */
+export function getDefaultAIClient(): AIClient | undefined {
+  if (_defaultClient) return _defaultClient
+  const cfg = envConfig.get('aiClient', null) as AIClientConfig | null
+  if (!cfg) return undefined
+  if (!cfg.provider) {
+    console.warn(
+      '[ai-client-base] config.aiClient is set but missing required "provider" field. ' +
+        'See @things-factory/ai-client-base/config/config.development.js for examples.'
+    )
+    return undefined
+  }
+  try {
+    _defaultClient = createAIClient(cfg)
+  } catch (e) {
+    console.warn(
+      `[ai-client-base] Failed to create default AI client: ${(e as Error).message}. ` +
+        `Registered providers: ${listRegisteredProviders().join(', ') || '(none)'}`
+    )
+    return undefined
+  }
+  return _defaultClient
+}
+
+export function setDefaultAIClient(client: AIClient | undefined): void {
+  _defaultClient = client
+}

package/server/service/index.ts

@@ -0,0 +1,4 @@
+export * from './types.js'
+export * from './factory.js'
+export * from './providers/index.js'
+export * from './utils/index.js'

package/server/service/providers/anthropic.ts

@@ -0,0 +1,252 @@
+/**
+ * Anthropic (Claude) AI Client adapter.
+ *
+ * 기본 모델: claude-sonnet-4-6 (구성에서 override 가능).
+ * SDK: @anthropic-ai/sdk
+ */
+import Anthropic from '@anthropic-ai/sdk'
+import type {
+  AIChatOptions,
+  AIClient,
+  AIClientConfig,
+  AIContentPart,
+  AIJSONOptions,
+  AIMessage,
+  AITool,
+  AIToolCall,
+  AIToolChatOptions,
+  AIToolChatResult,
+  AIVisionOptions
+} from '../types.js'
+import { registerAIProvider } from '../factory.js'
+import { parseJSONResponse } from '../utils/parse-json.js'
+
+const DEFAULT_MODEL = 'claude-sonnet-4-6'
+const DEFAULT_MAX_TOKENS = 4096
+
+export class AnthropicAIClient implements AIClient {
+  readonly id: string
+  private sdk: Anthropic
+  private defaultModel: string
+
+  constructor(config: AIClientConfig) {
+    this.sdk = new Anthropic({
+      apiKey: config.apiKey,
+      ...(config.baseURL && { baseURL: config.baseURL })
+    })
+    this.defaultModel = config.model ?? DEFAULT_MODEL
+    this.id = `anthropic:${this.defaultModel}`
+  }
+
+  async chat(messages: AIMessage[], options: AIChatOptions = {}): Promise<string> {
+    const systemFromMessages = messages
+      .filter(m => m.role === 'system')
+      .map(extractTextContent)
+      .filter(Boolean)
+      .join('\n\n')
+    const system = [options.systemPrompt, systemFromMessages].filter(Boolean).join('\n\n')
+
+    const conversation = messages
+      .filter(m => m.role !== 'system')
+      .map(toAnthropicMessage)
+
+    const response = await this.sdk.messages.create({
+      model: options.model ?? this.defaultModel,
+      max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      ...(options.temperature !== undefined && { temperature: options.temperature }),
+      ...(system && { system }),
+      ...(options.stopSequences && { stop_sequences: options.stopSequences }),
+      messages: conversation
+    } as any)
+
+    return extractResponseText(response)
+  }
+
+  async generateJSON<T = unknown>(
+    prompt: string | AIMessage[],
+    options: AIJSONOptions = {}
+  ): Promise<T> {
+    const messages: AIMessage[] =
+      typeof prompt === 'string' ? [{ role: 'user', content: prompt }] : prompt
+
+    const schemaHint = options.schema
+      ? `\n\nResponse MUST conform to this JSON schema:\n${JSON.stringify(options.schema)}`
+      : ''
+    const enforcedSystem =
+      (options.systemPrompt ? options.systemPrompt + '\n\n' : '') +
+      'Return only valid JSON. No markdown code fences, no commentary.' +
+      schemaHint
+
+    const text = await this.chat(messages, { ...options, systemPrompt: enforcedSystem })
+    return parseJSONResponse<T>(text)
+  }
+
+  async vision(
+    image: Buffer | Uint8Array | { url: string },
+    prompt: string,
+    options: AIVisionOptions = {}
+  ): Promise<string> {
+    const imagePart: AIContentPart =
+      typeof image === 'object' && 'url' in image
+        ? { type: 'image', source: { kind: 'url', url: image.url } }
+        : {
+            type: 'image',
+            source: { kind: 'base64', data: image as Buffer | Uint8Array, mediaType: 'image/png' }
+          }
+
+    return this.chat(
+      [{ role: 'user', content: [imagePart, { type: 'text', text: prompt }] }],
+      options
+    )
+  }
+
+  async chatWithTools(
+    messages: AIMessage[],
+    tools: AITool[],
+    options: AIToolChatOptions = {}
+  ): Promise<AIToolChatResult> {
+    const systemFromMessages = messages
+      .filter(m => m.role === 'system')
+      .map(extractTextContent)
+      .filter(Boolean)
+      .join('\n\n')
+    const system = [options.systemPrompt, systemFromMessages].filter(Boolean).join('\n\n')
+    const conversation = messages.filter(m => m.role !== 'system').map(toAnthropicMessage)
+
+    const sdkTools = tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.parameters as any
+    }))
+
+    const toolChoice = buildAnthropicToolChoice(options)
+
+    const response = await this.sdk.messages.create({
+      model: options.model ?? this.defaultModel,
+      max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      ...(options.temperature !== undefined && { temperature: options.temperature }),
+      ...(system && { system }),
+      ...(options.stopSequences && { stop_sequences: options.stopSequences }),
+      messages: conversation,
+      tools: sdkTools,
+      ...(toolChoice && { tool_choice: toolChoice })
+    } as any)
+
+    const text = extractResponseText(response) || undefined
+    const toolCalls: AIToolCall[] = Array.isArray(response.content)
+      ? response.content
+          .filter((b: any) => b && b.type === 'tool_use')
+          .map((b: any) => ({
+            id: typeof b.id === 'string' && b.id ? b.id : `call_${Math.random().toString(36).slice(2, 12)}`,
+            name: b.name,
+            arguments: (b.input && typeof b.input === 'object' ? b.input : {}) as Record<string, any>
+          }))
+      : []
+
+    return {
+      text,
+      toolCalls,
+      stopReason: normalizeAnthropicStopReason(response.stop_reason)
+    }
+  }
+}
+
+// ── 변환 유틸 ─────────────────────────────────────────────────────────
+
+function extractTextContent(msg: AIMessage): string {
+  if (typeof msg.content === 'string') return msg.content
+  return msg.content
+    .filter(p => p.type === 'text')
+    .map(p => (p as { type: 'text'; text: string }).text)
+    .join('\n')
+}
+
+function toAnthropicMessage(msg: AIMessage): any {
+  if (typeof msg.content === 'string') {
+    return { role: msg.role, content: msg.content }
+  }
+  return {
+    role: msg.role,
+    content: msg.content.map(toAnthropicContentBlock)
+  }
+}
+
+function toAnthropicContentBlock(part: AIContentPart): any {
+  if (part.type === 'text') {
+    return { type: 'text', text: part.text }
+  }
+  if (part.type === 'tool_use') {
+    return { type: 'tool_use', id: part.id, name: part.name, input: part.arguments }
+  }
+  if (part.type === 'tool_result') {
+    return {
+      type: 'tool_result',
+      tool_use_id: part.toolUseId,
+      content: part.content,
+      ...(part.isError && { is_error: true })
+    }
+  }
+  // image
+  if (part.source.kind === 'url') {
+    return { type: 'image', source: { type: 'url', url: part.source.url } }
+  }
+  const data = Buffer.isBuffer(part.source.data)
+    ? part.source.data.toString('base64')
+    : Buffer.from(part.source.data).toString('base64')
+  return {
+    type: 'image',
+    source: { type: 'base64', media_type: part.source.mediaType, data }
+  }
+}
+
+function extractResponseText(response: any): string {
+  if (!response || !Array.isArray(response.content)) return ''
+  return response.content
+    .filter((b: any) => b && b.type === 'text')
+    .map((b: any) => b.text || '')
+    .join('')
+}
+
+function buildAnthropicToolChoice(options: AIToolChatOptions): any | undefined {
+  const choice = options.toolChoice ?? 'auto'
+  const disableParallel = options.allowParallelToolCalls === false
+  if (choice === 'none') {
+    return { type: 'none' }
+  }
+  if (choice === 'required') {
+    if (options.forceTool) {
+      return {
+        type: 'tool',
+        name: options.forceTool,
+        ...(disableParallel && { disable_parallel_tool_use: true })
+      }
+    }
+    return {
+      type: 'any',
+      ...(disableParallel && { disable_parallel_tool_use: true })
+    }
+  }
+  // 'auto'
+  return {
+    type: 'auto',
+    ...(disableParallel && { disable_parallel_tool_use: true })
+  }
+}
+
+function normalizeAnthropicStopReason(raw: any): AIToolChatResult['stopReason'] {
+  switch (raw) {
+    case 'tool_use':
+      return 'tool_use'
+    case 'end_turn':
+      return 'end_turn'
+    case 'max_tokens':
+      return 'max_tokens'
+    case 'stop_sequence':
+      return 'stop_sequence'
+    default:
+      return raw ?? 'end_turn'
+  }
+}
+
+// Auto-register at module load
+registerAIProvider('anthropic', config => new AnthropicAIClient(config))

package/server/service/providers/gemini.ts

@@ -0,0 +1,353 @@
+/**
+ * Google Gemini AI Client adapter.
+ *
+ * 기본 모델: gemini-3-pro (구성에서 override 가능).
+ * SDK: @google/generative-ai
+ *
+ * 비고: Antigravity (Google 의 agentic IDE) 가 기본 백엔드로 사용하는 모델군.
+ *       이 어댑터는 Gemini API 직접 호출 — Antigravity IDE 와는 별개.
+ */
+import { GoogleGenerativeAI } from '@google/generative-ai'
+import type {
+  AIChatOptions,
+  AIClient,
+  AIClientConfig,
+  AIContentPart,
+  AIJSONOptions,
+  AIMessage,
+  AITool,
+  AIToolCall,
+  AIToolChatOptions,
+  AIToolChatResult,
+  AIVisionOptions
+} from '../types.js'
+import { registerAIProvider } from '../factory.js'
+import { parseJSONResponse } from '../utils/parse-json.js'
+
+// `gemini-3-pro` 는 2026-03-09 종료됨. 후속 권장 모델로 변경.
+// 사용자가 자기 환경에서 활용 가능한 정확한 ID 는 ListModels 로 확인:
+//   curl "https://generativelanguage.googleapis.com/v1beta/models?key=$KEY"
+const DEFAULT_MODEL = 'gemini-3-flash-preview'
+const DEFAULT_MAX_TOKENS = 8192
+
+export class GeminiAIClient implements AIClient {
+  readonly id: string
+  private sdk: GoogleGenerativeAI
+  private defaultModel: string
+
+  constructor(config: AIClientConfig) {
+    // Gemini SDK 는 환경변수 자동 인식이 없으므로 어댑터에서 명시적으로 fallback.
+    // 우선순위: config.apiKey → GOOGLE_API_KEY → GEMINI_API_KEY → GOOGLE_GENERATIVE_AI_API_KEY
+    const apiKey =
+      config.apiKey ??
+      process.env.GOOGLE_API_KEY ??
+      process.env.GEMINI_API_KEY ??
+      process.env.GOOGLE_GENERATIVE_AI_API_KEY ??
+      ''
+    this.sdk = new GoogleGenerativeAI(apiKey)
+    this.defaultModel = config.model ?? DEFAULT_MODEL
+    this.id = `gemini:${this.defaultModel}`
+  }
+
+  async chat(messages: AIMessage[], options: AIChatOptions = {}): Promise<string> {
+    const { systemPrompt, contents } = splitMessages(messages, options.systemPrompt)
+    const model = this.buildModel(options, systemPrompt)
+    const result = await model.generateContent({ contents } as any)
+    return result.response.text()
+  }
+
+  async generateJSON<T = unknown>(
+    prompt: string | AIMessage[],
+    options: AIJSONOptions = {}
+  ): Promise<T> {
+    const messages: AIMessage[] =
+      typeof prompt === 'string' ? [{ role: 'user', content: prompt }] : prompt
+    const { systemPrompt, contents } = splitMessages(messages, options.systemPrompt)
+
+    const generationConfig: any = baseGenerationConfig(options)
+    generationConfig.responseMimeType = 'application/json'
+    if (options.schema) generationConfig.responseSchema = options.schema
+
+    const model = this.sdk.getGenerativeModel({
+      model: options.model ?? this.defaultModel,
+      ...(systemPrompt && { systemInstruction: systemPrompt }),
+      generationConfig
+    })
+    const result = await model.generateContent({ contents } as any)
+    const text = result.response.text()
+    return parseJSONResponse<T>(text)
+  }
+
+  async vision(
+    image: Buffer | Uint8Array | { url: string },
+    prompt: string,
+    options: AIVisionOptions = {}
+  ): Promise<string> {
+    const imagePart: AIContentPart =
+      typeof image === 'object' && 'url' in image
+        ? { type: 'image', source: { kind: 'url', url: image.url } }
+        : {
+            type: 'image',
+            source: { kind: 'base64', data: image as Buffer | Uint8Array, mediaType: 'image/png' }
+          }
+
+    return this.chat(
+      [{ role: 'user', content: [imagePart, { type: 'text', text: prompt }] }],
+      options
+    )
+  }
+
+  private buildModel(options: AIChatOptions, systemInstruction?: string) {
+    return this.sdk.getGenerativeModel({
+      model: options.model ?? this.defaultModel,
+      ...(systemInstruction && { systemInstruction }),
+      generationConfig: baseGenerationConfig(options)
+    })
+  }
+
+  async chatWithTools(
+    messages: AIMessage[],
+    tools: AITool[],
+    options: AIToolChatOptions = {}
+  ): Promise<AIToolChatResult> {
+    const { systemPrompt, contents } = splitMessages(messages, options.systemPrompt)
+
+    // Gemini 는 OpenAPI 3.0 subset — JSON Schema 의 일부 키를 거부함.
+    // 'additionalProperties' / '$schema' / '$defs' 등을 제거.
+    const functionDeclarations = tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      parameters: sanitizeForGeminiSchema(t.parameters)
+    }))
+
+    const toolConfig = buildGeminiToolConfig(options)
+
+    const model = this.sdk.getGenerativeModel({
+      model: options.model ?? this.defaultModel,
+      ...(systemPrompt && { systemInstruction: systemPrompt }),
+      generationConfig: baseGenerationConfig(options),
+      tools: [{ functionDeclarations }] as any,
+      ...(toolConfig && { toolConfig })
+    } as any)
+
+    const result = await model.generateContent({ contents } as any)
+    const response: any = result.response
+
+    const candidate = response?.candidates?.[0]
+    const parts = candidate?.content?.parts ?? []
+
+    // Gemini 는 한 응답에서 (a) thinking part (p.thought === true) 와
+    // (b) 본문 text part 를 함께 emit 할 수 있다. thought 는 사용자에게 노출하면
+    // "구조화 답변 + 산문 답변" 형태의 중복으로 보이므로 제거.
+    const textParts = parts
+      .filter((p: any) => typeof p?.text === 'string' && p?.thought !== true)
+      .map((p: any) => p.text)
+    const text = textParts.join('') || undefined
+
+    // Gemini 는 functionCall 에 자체 id 가 없음 — 어댑터가 turn 내부에서 부여.
+    // id 포맷 'g:<name>:<seq>' — assistant 가 tool_result 를 만들 때 이 id 를 그대로
+    // 넘기면 toGeminiPart 가 name 을 추출해 functionResponse.name 에 채운다.
+    //
+    // thoughtSignature: Gemini 2.5/3 부터 thinking 모델이 functionCall 에 서명을 붙임.
+    // 다음 turn 에 그대로 echo 해야 400 에러 안 남 (cite: ai.google.dev/.../thought-signatures).
+    let geminiCallSeq = 0
+    const ts = Date.now()
+    const toolCalls: AIToolCall[] = parts
+      .filter((p: any) => p?.functionCall && typeof p.functionCall.name === 'string')
+      .map((p: any) => {
+        // SDK 가 camelCase 또는 snake_case 둘 중 하나로 emit — 둘 다 받음.
+        const sig: string | undefined = p.thoughtSignature ?? p.thought_signature
+        return {
+          id: `g:${p.functionCall.name}:${ts}_${geminiCallSeq++}`,
+          name: p.functionCall.name,
+          arguments:
+            p.functionCall.args && typeof p.functionCall.args === 'object'
+              ? (p.functionCall.args as Record<string, any>)
+              : {},
+          ...(typeof sig === 'string' && sig.length > 0 && {
+            providerMeta: { thoughtSignature: sig }
+          })
+        }
+      })
+
+    return {
+      text,
+      toolCalls,
+      stopReason: normalizeGeminiStopReason(candidate?.finishReason, toolCalls.length > 0)
+    }
+  }
+}
+
+// ── 변환 유틸 ─────────────────────────────────────────────────────────
+
+function baseGenerationConfig(options: AIChatOptions): any {
+  return {
+    maxOutputTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.stopSequences && { stopSequences: options.stopSequences })
+  }
+}
+
+function splitMessages(
+  messages: AIMessage[],
+  externalSystem?: string
+): { systemPrompt: string; contents: any[] } {
+  const systemMessages = messages
+    .filter(m => m.role === 'system')
+    .map(extractTextContent)
+    .filter(Boolean)
+  const conversation = messages.filter(m => m.role !== 'system')
+  const systemPrompt = [externalSystem, ...systemMessages].filter(Boolean).join('\n\n')
+  return { systemPrompt, contents: conversation.map(toGeminiContent) }
+}
+
+function extractTextContent(msg: AIMessage): string {
+  if (typeof msg.content === 'string') return msg.content
+  return msg.content
+    .filter(p => p.type === 'text')
+    .map(p => (p as { type: 'text'; text: string }).text)
+    .join('\n')
+}
+
+function toGeminiContent(msg: AIMessage): any {
+  // Our 'assistant' role → Gemini's 'model' role
+  const role = msg.role === 'assistant' ? 'model' : msg.role
+  const parts =
+    typeof msg.content === 'string'
+      ? [{ text: msg.content }]
+      : msg.content.map(toGeminiPart)
+  return { role, parts }
+}
+
+function toGeminiPart(part: AIContentPart): any {
+  if (part.type === 'text') {
+    return { text: part.text }
+  }
+  if (part.type === 'tool_use') {
+    // Gemini: assistant 가 호출 의도 표현. functionCall.name + args 만 가짐 (id 없음).
+    // thoughtSignature 는 thinking 모델 사용 시 필수 — providerMeta 에서 복원해 echo.
+    const sig = part.providerMeta?.thoughtSignature
+    return {
+      functionCall: { name: part.name, args: part.arguments },
+      ...(typeof sig === 'string' && sig.length > 0 && { thoughtSignature: sig })
+    }
+  }
+  if (part.type === 'tool_result') {
+    // Gemini: user role 에 functionResponse part 로 회신. 이름은 호출했던 tool name 과
+    // 같아야 함 — assistant.ts 의 loop 에서 part 생성 시 함께 전달.
+    let parsed: any = part.content
+    try {
+      parsed = JSON.parse(part.content)
+    } catch {
+      parsed = { result: part.content }
+    }
+    return {
+      functionResponse: {
+        // name 은 원래 호출했던 tool name. toolUseId 에 임베드되어 있지 않으므로
+        // assistant 가 메시지 생성 시 별도 채워줘야 함 — 여기서는 placeholder.
+        // 실제 사용 시 toolUseId 를 'tool_<name>_<seq>' 형태로 만들어 name 추출.
+        name: extractGeminiNameFromId(part.toolUseId),
+        response: parsed
+      }
+    }
+  }
+  // image
+  if (part.source.kind === 'url') {
+    // Gemini SDK 는 inlineData(base64) 만 지원. URL 은 호출 전에 fetch 필요.
+    throw new Error(
+      'Gemini adapter: image URL is not supported directly. Fetch the URL and pass as Buffer.'
+    )
+  }
+  const data = Buffer.isBuffer(part.source.data)
+    ? part.source.data.toString('base64')
+    : Buffer.from(part.source.data).toString('base64')
+  return {
+    inlineData: { data, mimeType: part.source.mediaType }
+  }
+}
+
+/**
+ * Gemini 의 functionCall 에는 자체 id 가 없어서 chatWithTools 가 'gemini_<ts>_<seq>'
+ * 형태의 가짜 id 를 만든다. 그런데 functionResponse 에는 name 이 필수 — assistant 의
+ * tool 실행기는 이 id 와 name 을 별도 매핑해야 한다. assistant 가 tool_result part 를
+ * 만들 때 toolUseId 에 'name:<actualName>;id:<originalId>' 같은 인코딩을 할 수 있지만
+ * 그건 invasive — 대신 toolUseId 가 'g:<name>:<id>' 형태면 name 을 직접 추출.
+ *
+ * 현재는 fallback: id 가 'g:' 로 시작하면 두 번째 segment 를 name 으로,
+ * 아니면 그대로 사용 (Gemini 가 받지 않으면 에러 — assistant 가 책임지고 인코딩).
+ */
+function extractGeminiNameFromId(id: string): string {
+  if (id.startsWith('g:')) {
+    const parts = id.split(':')
+    return parts[1] || id
+  }
+  return id
+}
+
+/**
+ * JSON Schema → Gemini OpenAPI 3.0 subset 변환.
+ * Gemini API 가 거부하는 키들 (deep) 제거.
+ * 보존: type / properties / items / required / enum / description / format / nullable
+ */
+const GEMINI_REJECTED_KEYS = new Set([
+  'additionalProperties',
+  '$schema',
+  '$defs',
+  '$ref',
+  '$id',
+  'definitions',
+  'patternProperties',
+  'dependencies'
+])
+
+function sanitizeForGeminiSchema(schema: any): any {
+  if (schema === null || schema === undefined) return schema
+  if (Array.isArray(schema)) return schema.map(sanitizeForGeminiSchema)
+  if (typeof schema !== 'object') return schema
+  const out: any = {}
+  for (const [k, v] of Object.entries(schema)) {
+    if (GEMINI_REJECTED_KEYS.has(k)) continue
+    out[k] = sanitizeForGeminiSchema(v)
+  }
+  return out
+}
+
+function buildGeminiToolConfig(options: AIToolChatOptions): any | undefined {
+  const choice = options.toolChoice ?? 'auto'
+  if (choice === 'none') {
+    return { functionCallingConfig: { mode: 'NONE' } }
+  }
+  if (choice === 'required') {
+    return {
+      functionCallingConfig: {
+        mode: 'ANY',
+        ...(options.forceTool && { allowedFunctionNames: [options.forceTool] })
+      }
+    }
+  }
+  return { functionCallingConfig: { mode: 'AUTO' } }
+}
+
+function normalizeGeminiStopReason(
+  raw: any,
+  hasToolCalls: boolean
+): AIToolChatResult['stopReason'] {
+  // Gemini 는 function call 발생 시 finishReason 을 'STOP' 으로 마킹할 수 있어
+  // toolCalls 존재 여부로 우선 판정.
+  if (hasToolCalls) return 'tool_use'
+  switch (raw) {
+    case 'STOP':
+      return 'end_turn'
+    case 'MAX_TOKENS':
+      return 'max_tokens'
+    case 'SAFETY':
+    case 'RECITATION':
+    case 'OTHER':
+      return 'stop_sequence'
+    default:
+      return raw ?? 'end_turn'
+  }
+}
+
+// Auto-register at module load
+registerAIProvider('gemini', config => new GeminiAIClient(config))