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

package/server/service/providers/index.ts

@@ -0,0 +1,8 @@
+// Auto-register providers on module load
+import './anthropic.js'
+import './gemini.js'
+import './openai.js'
+
+export { AnthropicAIClient } from './anthropic.js'
+export { GeminiAIClient } from './gemini.js'
+export { OpenAIAIClient } from './openai.js'

package/server/service/providers/openai.ts

@@ -0,0 +1,284 @@
+/**
+ * OpenAI AI Client adapter.
+ *
+ * 기본 모델: gpt-4o (구성에서 override 가능).
+ * SDK: openai
+ *
+ * 비고: legacy `openai` config 키 (codelingua 의 사용처) 도 factory.ts 가 이 어댑터로 자동 매핑.
+ *       organization 필드 지원.
+ */
+import OpenAI from 'openai'
+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 = 'gpt-4o'
+const DEFAULT_MAX_TOKENS = 4096
+
+export class OpenAIAIClient implements AIClient {
+  readonly id: string
+  private sdk: OpenAI
+  private defaultModel: string
+
+  constructor(config: AIClientConfig) {
+    // OpenAI SDK 는 apiKey 없을 시 OPENAI_API_KEY 환경변수 자동 인식.
+    const apiKey = config.apiKey ?? process.env.OPENAI_API_KEY
+    this.sdk = new OpenAI({
+      apiKey,
+      ...(config.organization && { organization: config.organization }),
+      ...(config.baseURL && { baseURL: config.baseURL })
+    })
+    this.defaultModel = config.model ?? DEFAULT_MODEL
+    this.id = `openai:${this.defaultModel}`
+  }
+
+  async chat(messages: AIMessage[], options: AIChatOptions = {}): Promise<string> {
+    const sdkMessages = buildSDKMessages(messages, options.systemPrompt)
+    const response = await this.sdk.chat.completions.create({
+      model: options.model ?? this.defaultModel,
+      max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      ...(options.temperature !== undefined && { temperature: options.temperature }),
+      ...(options.stopSequences && { stop: options.stopSequences }),
+      messages: sdkMessages as any
+    })
+    return response.choices[0]?.message?.content ?? ''
+  }
+
+  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 sdkMessages = buildSDKMessages(messages, enforcedSystem)
+    const response = await this.sdk.chat.completions.create({
+      model: options.model ?? this.defaultModel,
+      max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      ...(options.temperature !== undefined && { temperature: options.temperature }),
+      response_format: { type: 'json_object' },
+      messages: sdkMessages as any
+    })
+    const text = response.choices[0]?.message?.content ?? '{}'
+    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 sdkMessages = buildSDKMessages(messages, options.systemPrompt)
+
+    const sdkTools = tools.map(t => ({
+      type: 'function' as const,
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters
+      }
+    }))
+
+    const toolChoice = buildOpenAIToolChoice(options)
+
+    const response = await this.sdk.chat.completions.create({
+      model: options.model ?? this.defaultModel,
+      max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      ...(options.temperature !== undefined && { temperature: options.temperature }),
+      ...(options.stopSequences && { stop: options.stopSequences }),
+      messages: sdkMessages as any,
+      tools: sdkTools,
+      ...(toolChoice !== undefined && { tool_choice: toolChoice as any }),
+      ...(options.allowParallelToolCalls === false && { parallel_tool_calls: false })
+    })
+
+    const choice = response.choices?.[0]
+    const message = choice?.message
+    const text = message?.content || undefined
+
+    const toolCalls: AIToolCall[] = (message?.tool_calls || []).map((tc: any) => {
+      const fn = tc.function
+      let args: Record<string, any> = {}
+      try {
+        args = fn?.arguments ? JSON.parse(fn.arguments) : {}
+      } catch {
+        args = {}
+      }
+      return {
+        id: typeof tc.id === 'string' && tc.id ? tc.id : `call_${Math.random().toString(36).slice(2, 12)}`,
+        name: fn?.name ?? '',
+        arguments: args
+      }
+    })
+
+    return {
+      text,
+      toolCalls,
+      stopReason: normalizeOpenAIStopReason(choice?.finish_reason)
+    }
+  }
+}
+
+// ── 변환 유틸 ─────────────────────────────────────────────────────────
+
+function buildSDKMessages(messages: AIMessage[], externalSystem?: string): any[] {
+  const out: any[] = []
+
+  const systemFromMessages = messages
+    .filter(m => m.role === 'system')
+    .map(extractTextContent)
+    .filter(Boolean)
+    .join('\n\n')
+  const combinedSystem = [externalSystem, systemFromMessages].filter(Boolean).join('\n\n')
+  if (combinedSystem) {
+    out.push({ role: 'system', content: combinedSystem })
+  }
+
+  for (const msg of messages) {
+    if (msg.role === 'system') continue
+    const sdkMsgs = toSDKMessages(msg)
+    out.push(...sdkMsgs)
+  }
+
+  return out
+}
+
+/**
+ * 한 AIMessage 가 다중 tool_result 를 가지면 OpenAI 측에서 여러 role:'tool' 메시지로
+ * 분리해야 함 (OpenAI 는 메시지당 tool_call_id 하나만 매핑). 따라서 array 를 반환.
+ */
+function toSDKMessages(msg: AIMessage): any[] {
+  if (typeof msg.content === 'string') {
+    return [{ role: msg.role, content: msg.content }]
+  }
+
+  const parts = msg.content
+  const toolUseParts = parts.filter(p => p.type === 'tool_use') as any[]
+  const toolResultParts = parts.filter(p => p.type === 'tool_result') as any[]
+  const otherParts = parts.filter(p => p.type !== 'tool_use' && p.type !== 'tool_result')
+
+  // tool_result 가 있으면 각각을 role='tool' 메시지로 분리 (OpenAI 요구사항).
+  if (toolResultParts.length > 0) {
+    return toolResultParts.map((r: any) => ({
+      role: 'tool',
+      tool_call_id: r.toolUseId,
+      content: r.content
+    }))
+  }
+
+  // assistant 측 tool_use 가 있으면 message.tool_calls 로
+  const out: any = { role: msg.role }
+  if (otherParts.length > 0) {
+    out.content = otherParts.map(toSDKContentPart)
+  } else {
+    out.content = null
+  }
+  if (toolUseParts.length > 0) {
+    out.tool_calls = toolUseParts.map(p => ({
+      id: p.id,
+      type: 'function',
+      function: { name: p.name, arguments: JSON.stringify(p.arguments) }
+    }))
+  }
+  return [out]
+}
+
+function toSDKContentPart(part: AIContentPart): any {
+  if (part.type === 'text') {
+    return { type: 'text', text: part.text }
+  }
+  if (part.type === 'tool_use' || part.type === 'tool_result') {
+    // 처리는 toSDKMessage 가 함 — 도달하면 버그.
+    return { type: 'text', text: '' }
+  }
+  // image
+  if (part.source.kind === 'url') {
+    return { type: 'image_url', image_url: { url: part.source.url } }
+  }
+  const b64 = Buffer.isBuffer(part.source.data)
+    ? part.source.data.toString('base64')
+    : Buffer.from(part.source.data).toString('base64')
+  return {
+    type: 'image_url',
+    image_url: { url: `data:${part.source.mediaType};base64,${b64}` }
+  }
+}
+
+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 buildOpenAIToolChoice(options: AIToolChatOptions): any {
+  const choice = options.toolChoice ?? 'auto'
+  if (choice === 'none') return 'none'
+  if (choice === 'required') {
+    if (options.forceTool) {
+      return { type: 'function', function: { name: options.forceTool } }
+    }
+    return 'required'
+  }
+  return 'auto'
+}
+
+function normalizeOpenAIStopReason(raw: any): AIToolChatResult['stopReason'] {
+  switch (raw) {
+    case 'tool_calls':
+      return 'tool_use'
+    case 'function_call':
+      return 'tool_use'
+    case 'stop':
+      return 'end_turn'
+    case 'length':
+      return 'max_tokens'
+    case 'content_filter':
+      return 'stop_sequence'
+    default:
+      return raw ?? 'end_turn'
+  }
+}
+
+// Auto-register at module load
+registerAIProvider('openai', config => new OpenAIAIClient(config))

package/server/service/types.ts

@@ -0,0 +1,197 @@
+/**
+ * Provider-agnostic AI client types.
+ *
+ * 공통 인터페이스만 정의 — 실제 호출은 provider 별 어댑터에서.
+ */
+
+export type AIRole = 'system' | 'user' | 'assistant'
+
+export interface AITextPart {
+  type: 'text'
+  text: string
+}
+
+export type AIImageMediaType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp'
+
+export interface AIImagePart {
+  type: 'image'
+  source:
+    | { kind: 'base64'; data: Buffer | Uint8Array; mediaType: AIImageMediaType }
+    | { kind: 'url'; url: string }
+}
+
+/**
+ * Assistant 가 tool 을 호출하라고 한 시점의 content part.
+ * 다음 턴에서 같은 id 로 tool_result 를 매핑한다.
+ */
+export interface AIToolUsePart {
+  type: 'tool_use'
+  /** provider-stable id — Anthropic tool_use.id / OpenAI tool_call.id / Gemini 의 자체 매핑 */
+  id: string
+  /** tool 이름 */
+  name: string
+  /** 호출 인자 (JSON object) */
+  arguments: Record<string, any>
+  /**
+   * provider-specific opaque metadata that must be echoed back when this tool_use
+   * is referenced in subsequent turns.
+   *
+   * Gemini: `thoughtSignature` — 안 보내면 400 에러.
+   * Anthropic: 없음.
+   * OpenAI: 없음.
+   *
+   * 호출자(assistant loop)는 AIToolCall.providerMeta 를 그대로 복사해 넣는다.
+   */
+  providerMeta?: Record<string, any>
+}
+
+/**
+ * 도구 실행 결과를 LLM 에 회신하는 user 측 content part.
+ *
+ * Anthropic: { type: 'tool_result', tool_use_id, content } — user role 에 들어감.
+ * OpenAI: tool role 메시지로 전송.
+ * Gemini: functionResponse part — user role 에 들어감.
+ */
+export interface AIToolResultPart {
+  type: 'tool_result'
+  /** 매핑되는 AIToolUsePart.id */
+  toolUseId: string
+  /** 도구 실행 결과 (text 또는 JSON-serializable) */
+  content: string
+  /** 실행 중 에러 발생 표시 (LLM 이 retry/대안 판단) */
+  isError?: boolean
+}
+
+export type AIContentPart = AITextPart | AIImagePart | AIToolUsePart | AIToolResultPart
+
+export interface AIMessage {
+  role: AIRole
+  content: string | AIContentPart[]
+}
+
+export interface AIChatOptions {
+  /** 모델 override (없으면 client 기본값) */
+  model?: string
+  maxTokens?: number
+  temperature?: number
+  /**
+   * system prompt — messages 의 system 메시지와 합쳐서 전달.
+   * Anthropic 의 system 파라미터 / OpenAI 의 system 메시지로 매핑.
+   */
+  systemPrompt?: string
+  stopSequences?: string[]
+}
+
+export interface AIJSONOptions extends AIChatOptions {
+  /** JSON Schema (옵션). 어댑터가 지원하면 structured output 강제 */
+  schema?: object
+}
+
+export interface AIVisionOptions extends AIChatOptions {}
+
+// ── Tool calling ──────────────────────────────────────────────────
+
+/**
+ * Provider-agnostic 도구 정의.
+ * Anthropic input_schema / OpenAI parameters / Gemini parameters 로 어댑터에서 정규화.
+ */
+export interface AITool {
+  name: string
+  description: string
+  /** JSON Schema (object 권장). enum / required / properties 등 표준 키 사용. */
+  parameters: Record<string, any>
+}
+
+/**
+ * LLM 이 호출하라고 지시한 도구 1 건.
+ * id 는 multi-turn 흐름에서 tool_result 매핑에 사용 — 어댑터가 항상 채워야 한다.
+ */
+export interface AIToolCall {
+  id: string
+  name: string
+  arguments: Record<string, any>
+  /**
+   * provider-specific opaque metadata to round-trip on subsequent turns.
+   * Gemini 는 `thoughtSignature` 를 여기에 담는다 — 다음 턴에 functionCall.thoughtSignature
+   * 로 복원되어야 400 에러 회피.
+   */
+  providerMeta?: Record<string, any>
+}
+
+export interface AIToolChatOptions extends AIChatOptions {
+  /**
+   * tool 선택 모드:
+   *  - 'auto': LLM 자율 (tool 호출 또는 텍스트 응답)
+   *  - 'required': 반드시 하나 이상 tool 호출
+   *  - 'none': tool 무시, 텍스트만
+   */
+  toolChoice?: 'auto' | 'required' | 'none'
+  /** 'required' 와 함께 특정 tool 강제. provider 별 지원 다름. */
+  forceTool?: string
+  /**
+   * 병렬 tool 호출 허용 여부 (default true).
+   * false 시 LLM 이 한 번에 하나의 tool 만 호출.
+   */
+  allowParallelToolCalls?: boolean
+}
+
+export interface AIToolChatResult {
+  /** 사용자에게 보여줄 텍스트 (tool 호출과 함께 동봉될 수도 있음) */
+  text?: string
+  /** LLM 이 호출하라고 지시한 도구들 (병렬 가능) */
+  toolCalls: AIToolCall[]
+  /**
+   * 정규화된 stop reason:
+   *   'tool_use' — tool 호출 발생
+   *   'end_turn' — 텍스트 응답 종료
+   *   'max_tokens' — 토큰 한도
+   *   'stop_sequence' — stop sequence 도달
+   *   기타 — provider 원본 그대로
+   */
+  stopReason: 'tool_use' | 'end_turn' | 'max_tokens' | 'stop_sequence' | string
+}
+
+// ── Client ────────────────────────────────────────────────────────
+
+export interface AIClient {
+  /** 'anthropic:claude-sonnet-4-6' 등 사람이 읽을 식별자 */
+  readonly id: string
+
+  /** 텍스트 chat completion */
+  chat(messages: AIMessage[], options?: AIChatOptions): Promise<string>
+
+  /** JSON 출력 강제. 파싱된 객체 반환. */
+  generateJSON<T = unknown>(prompt: string | AIMessage[], options?: AIJSONOptions): Promise<T>
+
+  /** 이미지 입력 — 텍스트 응답. 어댑터가 vision 모델을 지원해야 함. */
+  vision?(
+    image: Buffer | Uint8Array | { url: string },
+    prompt: string,
+    options?: AIVisionOptions
+  ): Promise<string>
+
+  /**
+   * Tool calling — LLM 이 자유 텍스트 대신 정의된 도구를 schema-검증된 인자로 호출.
+   * 각 도구의 parameters 가 enum/required 강제 → invalid type / 누락 필드 봉쇄.
+   * 어댑터별로 Anthropic tool_use / OpenAI tools / Gemini functionCalls 로 매핑.
+   */
+  chatWithTools?(
+    messages: AIMessage[],
+    tools: AITool[],
+    options?: AIToolChatOptions
+  ): Promise<AIToolChatResult>
+}
+
+export interface AIClientConfig {
+  /** 등록된 provider 이름 (예: 'anthropic', 'openai', 'gemini') */
+  provider: string
+  /** 기본 모델 ID */
+  model?: string
+  apiKey?: string
+  /** OpenAI organization (provider:'openai' 전용) */
+  organization?: string
+  baseURL?: string
+  [k: string]: any
+}
+
+export type AIProviderFactory = (config: AIClientConfig) => AIClient

package/server/service/utils/index.ts

@@ -0,0 +1 @@
+export * from './parse-json.js'

package/server/service/utils/parse-json.ts

@@ -0,0 +1,100 @@
+/**
+ * Robust JSON parsing for LLM responses.
+ *
+ * LLM 응답은 다음 같은 변형이 흔하다:
+ *  - 마크다운 코드펜스로 감싸짐 (```json ... ```)
+ *  - 앞뒤 자연어 코멘트 ("Sure, here is: { ... }")
+ *  - 끝에 trailing 문자 (Gemini 의 알려진 케이스: 닫는 } 가 한 번 더)
+ *  - smart quote 등의 사소한 변형
+ *
+ * 이 helper 는:
+ *   1) 코드펜스를 제거
+ *   2) 첫 balanced JSON object/array 만 잘라냄 (brace counting + 문자열 인지)
+ *   3) 그래도 실패하면 raw 출력 포함한 명확한 에러
+ */
+
+export function parseJSONResponse<T = unknown>(text: string): T {
+  if (typeof text !== 'string') {
+    throw new Error(`AI response is not a string (got ${typeof text})`)
+  }
+
+  const stripped = stripCodeFences(text).trim()
+
+  // 1) 직접 시도
+  try {
+    return JSON.parse(stripped) as T
+  } catch {
+    /* fallthrough */
+  }
+
+  // 2) 첫 balanced JSON 추출 시도
+  const extracted = extractFirstBalanced(stripped)
+  if (extracted) {
+    try {
+      return JSON.parse(extracted) as T
+    } catch (e) {
+      throw new Error(
+        `AI response is not valid JSON (after extraction): ${(e as Error).message}\n----- raw -----\n${text}`
+      )
+    }
+  }
+
+  throw new Error(`AI response is not valid JSON: no balanced JSON found.\n----- raw -----\n${text}`)
+}
+
+function stripCodeFences(text: string): string {
+  return text
+    .replace(/^\s*```(?:json|JSON)?\s*\n?/i, '')
+    .replace(/\n?\s*```\s*$/i, '')
+}
+
+/**
+ * 첫 balanced { ... } 또는 [ ... ] 추출.
+ * 문자열 내의 brace 는 무시. escape 처리.
+ */
+export function extractFirstBalanced(text: string): string | null {
+  const startIdx = findFirstBraceOrBracket(text)
+  if (startIdx < 0) return null
+
+  const opener = text[startIdx]
+  const closer = opener === '{' ? '}' : ']'
+  let depth = 0
+  let inString = false
+  let escape = false
+
+  for (let i = startIdx; i < text.length; i++) {
+    const ch = text[i]
+    if (escape) {
+      escape = false
+      continue
+    }
+    if (inString) {
+      if (ch === '\\') {
+        escape = true
+      } else if (ch === '"') {
+        inString = false
+      }
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      continue
+    }
+    if (ch === opener) depth++
+    else if (ch === closer) {
+      depth--
+      if (depth === 0) {
+        return text.substring(startIdx, i + 1)
+      }
+    }
+  }
+  return null
+}
+
+function findFirstBraceOrBracket(text: string): number {
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (ch === '{' || ch === '[') return i
+  }
+  return -1
+}

package/things-factory.config.js

@@ -0,0 +1 @@
+export default {}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig-base.json",
+  "compilerOptions": {
+    "outDir": "./dist-server",
+    "baseUrl": "./"
+  },
+  "include": ["./server/**/*"],
+  "exclude": ["**/*.spec.ts", "**/*.test.ts"]
+}