@things-factory/ai-client-base 10.1.149 → 10.1.157

package/server/service/factory.ts

@@ -1,11 +1,10 @@
 /**
- * AI Provider 등록 + Client 생성.
+ * Provider registration and client construction.
  *
- * - 어댑터 패키지(또는 동일 패키지의 providers/) 가 모듈 로드 시 `registerAIProvider` 호출.
- * - 호출자는 `createAIClient({ provider: 'anthropic', ... })` 로 인스턴스 획득.
- * - things-factory env config 의 `aiClient` 키가 있으면 `getDefaultAIClient()` 가 자동 생성.
+ * Each adapter registers itself when its module loads. `createAIClient` builds a client from a provider, model and
+ * key; it is how this package's own door (aiClientFor) and the model list reach a provider. Code outside this package
+ * gets a client from aiClientFor, for a domain - there is no deployment-wide client.
  */
-import { config as envConfig } from '@things-factory/env'
 import type { AIClient, AIClientConfig, AIProviderFactory } from './types.js'
 
 const REGISTERED_PROVIDERS = new Map<string, AIProviderFactory>()
@@ -27,42 +26,3 @@ export function createAIClient(config: AIClientConfig): AIClient {
   }
   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

@@ -7,6 +7,11 @@ export * from './agentic-loop/index.js'
 export * from './assistant/index.js'
 export * from './analysis-contract.js'
 export * from './decision/index.js'
-/* 「이 배포에 AI 가 있나」 — 시도해서 알아내지 않고 먼저 읽는다(표준 A7-a). */
+/* 「이 사업장에 AI 가 있나」 — 시도해서 알아내지 않고 먼저 읽는다(표준 A7-a). */
 export * from './capability.js'
+/* AI agents per domain - the one door to a model, and its usage (design/ai/agent-settings.md). */
+export * from './agent/index.js'
+
+import { AiUsage } from './agent/ai-usage.js'
+export const entities = [AiUsage]
 export * from './testing/tool-call-context.js'

package/server/service/providers/anthropic.ts

@@ -58,6 +58,7 @@ export class AnthropicAIClient implements AIClient {
       ...(options.stopSequences && { stop_sequences: options.stopSequences }),
       messages: conversation
     } as any)
+    reportUsage(response, options, options.model ?? this.defaultModel)
 
     return extractResponseText(response)
   }
@@ -131,6 +132,7 @@ export class AnthropicAIClient implements AIClient {
       tools: sdkTools,
       ...(toolChoice && { tool_choice: toolChoice })
     } as any)
+    reportUsage(response, options, options.model ?? this.defaultModel)
 
     const text = extractResponseText(response) || undefined
     const toolCalls: AIToolCall[] = Array.isArray(response.content)
@@ -149,6 +151,21 @@ export class AnthropicAIClient implements AIClient {
       stopReason: normalizeAnthropicStopReason(response.stop_reason)
     }
   }
+
+  /** Every model Anthropic lists is a conversation model. */
+  async listModels(): Promise<string[]> {
+    const ids: string[] = []
+    for await (const model of this.sdk.models.list()) ids.push(model.id)
+    return ids.sort()
+  }
+}
+
+function reportUsage(response: any, options: AIChatOptions, requested: string): void {
+  options.onUsage?.({
+    model: response?.model ?? requested,
+    inputTokens: response?.usage?.input_tokens,
+    outputTokens: response?.usage?.output_tokens
+  })
 }
 
 // ── 변환 유틸 ─────────────────────────────────────────────────────────

package/server/service/providers/gemini.ts

@@ -34,17 +34,13 @@ export class GeminiAIClient implements AIClient {
   readonly id: string
   private sdk: GoogleGenerativeAI
   private defaultModel: string
+  private apiKey: string
+  private baseURL?: 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.apiKey = config.apiKey
+    this.baseURL = config.baseURL
+    this.sdk = new GoogleGenerativeAI(config.apiKey)
     this.defaultModel = config.model ?? DEFAULT_MODEL
     this.id = `gemini:${this.defaultModel}`
   }
@@ -53,6 +49,7 @@ export class GeminiAIClient implements AIClient {
     const { systemPrompt, contents } = splitMessages(messages, options.systemPrompt)
     const model = this.buildModel(options, systemPrompt)
     const result = await model.generateContent({ contents } as any)
+    reportUsage(result, options, options.model ?? this.defaultModel)
     return result.response.text()
   }
 
@@ -72,8 +69,9 @@ export class GeminiAIClient implements AIClient {
       model: options.model ?? this.defaultModel,
       ...(systemPrompt && { systemInstruction: systemPrompt }),
       generationConfig
-    })
+    }, this.requestOptions)
     const result = await model.generateContent({ contents } as any)
+    reportUsage(result, options, options.model ?? this.defaultModel)
     const text = result.response.text()
     return parseJSONResponse<T>(text)
   }
@@ -102,7 +100,7 @@ export class GeminiAIClient implements AIClient {
       model: options.model ?? this.defaultModel,
       ...(systemInstruction && { systemInstruction }),
       generationConfig: baseGenerationConfig(options)
-    })
+    }, this.requestOptions)
   }
 
   async chatWithTools(
@@ -128,9 +126,10 @@ export class GeminiAIClient implements AIClient {
       generationConfig: baseGenerationConfig(options),
       tools: [{ functionDeclarations }] as any,
       ...(toolConfig && { toolConfig })
-    } as any)
+    } as any, this.requestOptions)
 
     const result = await model.generateContent({ contents } as any)
+    reportUsage(result, options, options.model ?? this.defaultModel)
     const response: any = result.response
 
     const candidate = response?.candidates?.[0]
@@ -176,6 +175,49 @@ export class GeminiAIClient implements AIClient {
       stopReason: normalizeGeminiStopReason(candidate?.finishReason, toolCalls.length > 0)
     }
   }
+
+  /**
+   * The SDK has no model list, so this reads the REST one. A conversation model is one that answers
+   * generateContent; embedding and other models are left out.
+   */
+  async listModels(): Promise<string[]> {
+    const base = (this.baseURL || 'https://generativelanguage.googleapis.com').replace(/\/+$/, '')
+    const ids: string[] = []
+    let pageToken = ''
+    do {
+      const url = `${base}/v1beta/models?pageSize=1000${pageToken ? `&pageToken=${encodeURIComponent(pageToken)}` : ''}`
+      const response = await fetch(url, { headers: { 'x-goog-api-key': this.apiKey } })
+      if (!response.ok) throw new ProviderListError(response.status, await response.text())
+      const page: any = await response.json()
+      for (const model of page.models ?? []) {
+        if ((model.supportedGenerationMethods ?? []).includes('generateContent')) {
+          ids.push(String(model.name).replace(/^models\//, ''))
+        }
+      }
+      pageToken = page.nextPageToken ?? ''
+    } while (pageToken)
+    return ids.sort()
+  }
+
+  private get requestOptions() {
+    return this.baseURL ? { baseUrl: this.baseURL } : undefined
+  }
+}
+
+/** A model list the provider refused, with the HTTP status the caller turns into a reason. */
+export class ProviderListError extends Error {
+  constructor(readonly status: number, body: string) {
+    super(`model list failed with ${status}: ${body.slice(0, 200)}`)
+  }
+}
+
+function reportUsage(result: any, options: AIChatOptions, requested: string): void {
+  const usage = result?.response?.usageMetadata
+  options.onUsage?.({
+    model: result?.response?.modelVersion ?? requested,
+    inputTokens: usage?.promptTokenCount,
+    outputTokens: usage?.candidatesTokenCount
+  })
 }
 
 // ── 변환 유틸 ─────────────────────────────────────────────────────────

package/server/service/providers/openai-models.test.ts

@@ -0,0 +1,30 @@
+/*
+ * What this guards: OpenAI's model list has no capability field, so the agent's model picker keeps the conversation
+ * models by name. The rule lives in one place and this fixes what it keeps.
+ */
+import { isOpenAIChatModel } from './openai'
+
+it('★ keeps the GPT and o-series conversation models', () => {
+  for (const id of ['gpt-4o', 'gpt-4o-mini', 'gpt-4.1', 'gpt-5', 'chatgpt-4o-latest', 'o1', 'o3-mini', 'o4-mini']) {
+    expect([id, isOpenAIChatModel(id)]).toEqual([id, true])
+  }
+})
+
+it('★ leaves out embedding, speech, image, realtime, search and instruct models', () => {
+  for (const id of [
+    'text-embedding-3-large',
+    'tts-1',
+    'whisper-1',
+    'dall-e-3',
+    'gpt-image-1',
+    'gpt-4o-audio-preview',
+    'gpt-4o-realtime-preview',
+    'gpt-4o-transcribe',
+    'gpt-4o-search-preview',
+    'gpt-3.5-turbo-instruct',
+    'omni-moderation-latest',
+    'davinci-002'
+  ]) {
+    expect([id, isOpenAIChatModel(id)]).toEqual([id, false])
+  }
+})

package/server/service/providers/openai.ts

@@ -4,8 +4,7 @@
  * 기본 모델: gpt-4o (구성에서 override 가능).
  * SDK: openai
  *
- * 비고: legacy `openai` config 키 (codelingua 의 사용처) 도 factory.ts 가 이 어댑터로 자동 매핑.
- *       organization 필드 지원.
+ * organization 필드 지원.
  */
 import OpenAI from 'openai'
 import type {
@@ -33,10 +32,8 @@ export class OpenAIAIClient implements AIClient {
   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,
+      apiKey: config.apiKey,
       ...(config.organization && { organization: config.organization }),
       ...(config.baseURL && { baseURL: config.baseURL })
     })
@@ -48,11 +45,13 @@ export class OpenAIAIClient implements AIClient {
     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,
+      /* `max_tokens` is refused by the gpt-5 and o-series models; every chat model takes this one. */
+      max_completion_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(options.temperature !== undefined && { temperature: options.temperature }),
       ...(options.stopSequences && { stop: options.stopSequences }),
       messages: sdkMessages as any
     })
+    reportUsage(response, options, options.model ?? this.defaultModel)
     return response.choices[0]?.message?.content ?? ''
   }
 
@@ -74,11 +73,13 @@ export class OpenAIAIClient implements AIClient {
     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,
+      /* `max_tokens` is refused by the gpt-5 and o-series models; every chat model takes this one. */
+      max_completion_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(options.temperature !== undefined && { temperature: options.temperature }),
       response_format: { type: 'json_object' },
       messages: sdkMessages as any
     })
+    reportUsage(response, options, options.model ?? this.defaultModel)
     const text = response.choices[0]?.message?.content ?? '{}'
     return parseJSONResponse<T>(text)
   }
@@ -122,7 +123,8 @@ export class OpenAIAIClient implements AIClient {
 
     const response = await this.sdk.chat.completions.create({
       model: options.model ?? this.defaultModel,
-      max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      /* `max_tokens` is refused by the gpt-5 and o-series models; every chat model takes this one. */
+      max_completion_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(options.temperature !== undefined && { temperature: options.temperature }),
       ...(options.stopSequences && { stop: options.stopSequences }),
       messages: sdkMessages as any,
@@ -130,6 +132,7 @@ export class OpenAIAIClient implements AIClient {
       ...(toolChoice !== undefined && { tool_choice: toolChoice as any }),
       ...(options.allowParallelToolCalls === false && { parallel_tool_calls: false })
     })
+    reportUsage(response, options, options.model ?? this.defaultModel)
 
     const choice = response.choices?.[0]
     const message = choice?.message
@@ -156,6 +159,29 @@ export class OpenAIAIClient implements AIClient {
       stopReason: normalizeOpenAIStopReason(choice?.finish_reason)
     }
   }
+
+  async listModels(): Promise<string[]> {
+    const ids: string[] = []
+    for await (const model of this.sdk.models.list()) ids.push(model.id)
+    return ids.filter(isOpenAIChatModel).sort()
+  }
+}
+
+/**
+ * OpenAI's model list has no capability field, so the conversation models are told apart by name: the GPT and
+ * o-series families, without their audio, realtime, speech, image, search and instruct variants. One rule, kept by a test.
+ */
+export function isOpenAIChatModel(id: string): boolean {
+  if (!/^(gpt-|chatgpt-|o\d)/.test(id)) return false
+  return !/(audio|realtime|tts|transcribe|image|search|instruct|embedding|moderation)/.test(id)
+}
+
+function reportUsage(response: any, options: AIChatOptions, requested: string): void {
+  options.onUsage?.({
+    model: response?.model ?? requested,
+    inputTokens: response?.usage?.prompt_tokens,
+    outputTokens: response?.usage?.completion_tokens
+  })
 }
 
 // ── 변환 유틸 ─────────────────────────────────────────────────────────

package/server/service/types.ts

@@ -80,6 +80,18 @@ export interface AIChatOptions {
    */
   systemPrompt?: string
   stopSequences?: string[]
+  /**
+   * Told what one provider call used, right after it returns. The metering boundary (aiClientFor) sets this per
+   * call so the usage row knows whose call it was; adapters call it once for every request they send.
+   */
+  onUsage?: (usage: AIProviderUsage) => void
+}
+
+/** What one provider request used, as the provider reported it. A count the provider did not report stays undefined. */
+export interface AIProviderUsage {
+  model: string
+  inputTokens?: number
+  outputTokens?: number
 }
 
 export interface AIJSONOptions extends AIChatOptions {
@@ -180,14 +192,18 @@ export interface AIClient {
     tools: AITool[],
     options?: AIToolChatOptions
   ): Promise<AIToolChatResult>
+
+  /** The ids of the conversation models this key may call, sorted. Reading it also proves the key is accepted. */
+  listModels(): Promise<string[]>
 }
 
 export interface AIClientConfig {
   /** 등록된 provider 이름 (예: 'anthropic', 'openai', 'gemini') */
   provider: string
-  /** 기본 모델 ID */
+  /** The model every call uses unless a call names another. */
   model?: string
-  apiKey?: string
+  /** Required - a provider is never reached with a key from the process environment. */
+  apiKey: string
   /** OpenAI organization (provider:'openai' 전용) */
   organization?: string
   baseURL?: string

package/translations/en.json

@@ -0,0 +1,13 @@
+{
+  "error.ai-not-configured": "AI is not set up for this domain.",
+  "error.ai-agent-not-available": "The AI agent you picked is not available here.",
+  "error.ai-agent-provider-unknown": "\"{provider}\" is not a provider an agent can use.",
+  "error.ai-agent-key-required": "Enter the API key of \"{agent}\".",
+  "error.ai-agent-name-required": "Every agent needs a name.",
+  "error.ai-agent-model-required": "Pick the model of \"{agent}\".",
+  "error.ai-agent-model-not-offered": "The provider does not offer \"{model}\" to this key.",
+  "error.ai-agent-name-taken": "There is already an agent named \"{name}\".",
+  "error.ai-agent-not-in-domain": "That agent does not belong to this domain.",
+  "error.ai-provider-key-rejected": "The provider did not accept this API key.",
+  "error.ai-provider-unreachable": "The provider could not be reached."
+}

package/translations/es.json

@@ -0,0 +1,13 @@
+{
+  "error.ai-not-configured": "La IA no está configurada para este dominio.",
+  "error.ai-agent-not-available": "El agente de IA elegido no está disponible aquí.",
+  "error.ai-agent-provider-unknown": "\"{provider}\" no es un proveedor que un agente pueda usar.",
+  "error.ai-agent-key-required": "Introduzca la clave de API de \"{agent}\".",
+  "error.ai-agent-name-required": "Cada agente necesita un nombre.",
+  "error.ai-agent-model-required": "Elija el modelo de \"{agent}\".",
+  "error.ai-agent-model-not-offered": "El proveedor no ofrece \"{model}\" a esta clave.",
+  "error.ai-agent-name-taken": "Ya existe un agente llamado \"{name}\".",
+  "error.ai-agent-not-in-domain": "Ese agente no pertenece a este dominio.",
+  "error.ai-provider-key-rejected": "El proveedor no aceptó esta clave de API.",
+  "error.ai-provider-unreachable": "No se pudo contactar con el proveedor."
+}

package/translations/ja.json

@@ -0,0 +1,13 @@
+{
+  "error.ai-not-configured": "この事業所には AI が設定されていません。",
+  "error.ai-agent-not-available": "選んだ AI エージェントはこの事業所では使えません。",
+  "error.ai-agent-provider-unknown": "「{provider}」はエージェントが使える提供元ではありません。",
+  "error.ai-agent-key-required": "「{agent}」の API キーを入力してください。",
+  "error.ai-agent-name-required": "エージェントごとに名前が必要です。",
+  "error.ai-agent-model-required": "「{agent}」のモデルを選んでください。",
+  "error.ai-agent-model-not-offered": "提供元はこのキーに「{model}」を提供していません。",
+  "error.ai-agent-name-taken": "「{name}」という名前のエージェントがすでにあります。",
+  "error.ai-agent-not-in-domain": "そのエージェントはこの事業所のものではありません。",
+  "error.ai-provider-key-rejected": "提供元がこの API キーを受け付けませんでした。",
+  "error.ai-provider-unreachable": "提供元に接続できませんでした。"
+}

package/translations/ko.json

@@ -0,0 +1,13 @@
+{
+  "error.ai-not-configured": "이 사업장에는 AI 가 설정되어 있지 않습니다.",
+  "error.ai-agent-not-available": "고른 AI 에이전트를 이 사업장에서 쓸 수 없습니다.",
+  "error.ai-agent-provider-unknown": "\"{provider}\" 은(는) 에이전트가 쓸 수 있는 제공처가 아닙니다.",
+  "error.ai-agent-key-required": "\"{agent}\" 의 API 키를 넣어 주세요.",
+  "error.ai-agent-name-required": "에이전트마다 이름이 있어야 합니다.",
+  "error.ai-agent-model-required": "\"{agent}\" 의 모델을 골라 주세요.",
+  "error.ai-agent-model-not-offered": "제공처가 이 키에 \"{model}\" 모델을 제공하지 않습니다.",
+  "error.ai-agent-name-taken": "\"{name}\" 이라는 에이전트가 이미 있습니다.",
+  "error.ai-agent-not-in-domain": "그 에이전트는 이 사업장의 것이 아닙니다.",
+  "error.ai-provider-key-rejected": "제공처가 이 API 키를 받지 않았습니다.",
+  "error.ai-provider-unreachable": "제공처에 닿지 않았습니다."
+}

package/translations/ms.json

@@ -0,0 +1,13 @@
+{
+  "error.ai-not-configured": "AI belum disediakan untuk domain ini.",
+  "error.ai-agent-not-available": "Ejen AI yang dipilih tidak tersedia di sini.",
+  "error.ai-agent-provider-unknown": "\"{provider}\" bukan penyedia yang boleh digunakan oleh ejen.",
+  "error.ai-agent-key-required": "Masukkan kunci API untuk \"{agent}\".",
+  "error.ai-agent-name-required": "Setiap ejen memerlukan nama.",
+  "error.ai-agent-model-required": "Pilih model untuk \"{agent}\".",
+  "error.ai-agent-model-not-offered": "Penyedia tidak menawarkan \"{model}\" kepada kunci ini.",
+  "error.ai-agent-name-taken": "Sudah ada ejen bernama \"{name}\".",
+  "error.ai-agent-not-in-domain": "Ejen itu bukan milik domain ini.",
+  "error.ai-provider-key-rejected": "Penyedia tidak menerima kunci API ini.",
+  "error.ai-provider-unreachable": "Penyedia tidak dapat dihubungi."
+}

package/translations/zh.json

@@ -0,0 +1,13 @@
+{
+  "error.ai-not-configured": "此站点尚未设置 AI。",
+  "error.ai-agent-not-available": "所选的 AI 代理在此站点不可用。",
+  "error.ai-agent-provider-unknown": "“{provider}”不是代理可用的提供商。",
+  "error.ai-agent-key-required": "请输入“{agent}”的 API 密钥。",
+  "error.ai-agent-name-required": "每个代理都需要名称。",
+  "error.ai-agent-model-required": "请选择“{agent}”的模型。",
+  "error.ai-agent-model-not-offered": "提供商未向此密钥提供“{model}”。",
+  "error.ai-agent-name-taken": "已存在名为“{name}”的代理。",
+  "error.ai-agent-not-in-domain": "该代理不属于此站点。",
+  "error.ai-provider-key-rejected": "提供商未接受此 API 密钥。",
+  "error.ai-provider-unreachable": "无法连接到提供商。"
+}