@things-factory/ai-client-base 10.0.0 → 10.0.3

package/server/service/utils/grounding.ts

@@ -0,0 +1,65 @@
+/**
+ * 접지 가드 — LLM 의 답이 **자기가 받은 근거 안에서** 말했는지 검사한다.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * LLM 이 가진 근거는 세 가지뿐이다: 시스템 프롬프트(현재 상태 요약), 사용자·이력 텍스트,
+ * 도구 결과(JSON). 답이 그 어디에도 없는 엔티티를 지목하면(존재하지 않는 노드·설비·주문
+ * 식별자) 그건 만들어 낸 것이다. 사용자는 그것을 검증할 수단이 없으므로 시스템이 표시해야 한다.
+ *
+ * ── 무엇을 하지 않는가 ──────────────────────────────────────────────────────
+ * 답을 고치거나 막지 않는다. 구조화된 경고만 낸다(비파괴) — 문장을 다시 쓰게 하는 판단은
+ * 호출부(대화면)의 정책이다. 또한 **문장으로 지어낸 상황**("지게차들이 바쁘게 움직인다")은
+ * 이 가드가 잡지 못한다. 그건 도구를 아예 부르지 않고 답한 경우이고, 별도 레버(도구 호출
+ * 강제)로 다뤄야 한다. 이 가드의 사정거리는 **식별자**다.
+ *
+ * ── 왜 식별자만 보는가 ──────────────────────────────────────────────────────
+ * 식별자는 근거집합과 문자 단위로 대조할 수 있는 유일한 요소다. 서술문의 사실성은 대조할
+ * 기준이 없다. 그래서 보수적으로 id 관례(하이픈 포함 소문자-영숫자)만 추출한다 —
+ * 한국어·하이픈 없는 일반어는 애초에 매칭하지 않는다.
+ */
+
+/** id 관례 — 소문자로 시작, 하이픈으로 이어진 소문자·숫자 토큰. `fk-1` `weld-station` `a-dc` 등. */
+const ID_TOKEN = /[a-z][a-z0-9]*(?:-[a-z0-9]+)+/g
+
+/** 문자열에서 id 후보 토큰을 뽑는다(중복 제거). */
+export function extractIdTokens(s: string): Set<string> {
+  const out = new Set<string>()
+  for (const m of (s ?? '').matchAll(ID_TOKEN)) out.add(m[0])
+  return out
+}
+
+/** 답이 언급한 id − 근거 코퍼스의 id = 미확인(환각 후보). 순서는 답에 나온 순서. */
+export function checkGrounding(reply: string, groundedCorpus: string): string[] {
+  const grounded = extractIdTokens(groundedCorpus)
+  const mentioned = extractIdTokens(reply)
+  return [...mentioned].filter(id => !grounded.has(id))
+}
+
+/**
+ * 소음 제거 — 미확인 토큰 중 **엔티티 참조로 보이는 것만** 남긴다.
+ *
+ * 왜 필요한가: id 관례는 영어 합성어와 구별되지 않는다(`read-only` `hand-off` `real-time`
+ * `zero-to-twin`). 영어로 답하는 대화면에서 그것들을 "근거 없는 식별자" 로 경고하면 경고가
+ * 소음이 되고, 소음이 되면 사용자는 **경고 자체를 무시**한다 — 가드가 있으나 없느니만 못해진다.
+ *
+ * 판정 기준(둘 중 하나):
+ *   ① 숫자를 포함한다 — `dock-3` `fk-12`. 일반 영어 합성어에는 숫자가 없다.
+ *   ② 근거에 있는 어떤 id 와 **첫 마디를 공유**한다 — 근거가 `dock-1` 을 담고 있는데 답이
+ *      `dock-7` 을 말하면 같은 계열의 없는 대상을 지목한 것이다.
+ *
+ * 놓치는 것: 숫자도 없고 근거에 같은 계열도 없는 순수 창작(`weld-station`). 그 경우까지
+ * 잡으려면 일반 영어 합성어를 함께 잡게 되므로, 이 가드는 **정확도를 택하고 재현율을 버린다**.
+ */
+export function filterEntityLike(tokens: string[], groundedCorpus: string): string[] {
+  const families = new Set<string>()
+  for (const id of extractIdTokens(groundedCorpus)) families.add(id.split('-')[0])
+  return tokens.filter(t => /[0-9]/.test(t) || families.has(t.split('-')[0]))
+}
+
+/**
+ * 접지 검사 + 소음 제거를 한 번에. 대화면에서 쓰는 기본 진입점.
+ * 반환이 비면 접지 정상(경고 없음).
+ */
+export function groundingWarnings(reply: string, groundedCorpus: string): string[] {
+  return filterEntityLike(checkGrounding(reply, groundedCorpus), groundedCorpus)
+}

package/server/service/utils/index.ts

@@ -1 +1,3 @@
 export * from './parse-json.js'
+export * from './grounding.js'
+export * from './transient.js'

package/server/service/utils/transient.test.ts

@@ -0,0 +1,92 @@
+/*
+ * 일시 장애 재시도 검증 — **잠깐 죽은 것에 한 번은 다시 시도한다.**
+ *
+ * 실제 사고: Gemini 503 이 왔을 때 재시도 없이 대화가 끝났다. 반대로 요청·자격 오류(400·401)를
+ * 재시도하면 원인이 늦게 드러나므로 즉시 던져야 한다 — 그 경계를 여기서 고정한다.
+ */
+import { isTransientAIError, retryTransient } from './transient'
+
+const err = (message: string, extra: any = {}) => Object.assign(new Error(message), extra)
+
+describe('isTransientAIError', () => {
+  it('429·5xx 는 일시로 본다', () => {
+    expect(isTransientAIError(err('too many requests', { status: 429 }))).toBe(true)
+    expect(isTransientAIError(err('unavailable', { status: 503 }))).toBe(true)
+    expect(isTransientAIError(err('bad gateway', { status: 502 }))).toBe(true)
+  })
+
+  it('SDK 가 코드를 본문에만 담아도 찾아낸다 — 실제 Gemini 오류 모양', () => {
+    expect(
+      isTransientAIError(err('Error fetching from undefined: [503 Service Unavailable] The service is currently unavailable.'))
+    ).toBe(true)
+  })
+
+  it('요청·자격 문제는 일시가 아니다 — 다시 해도 같고, 원인을 늦게 드러내면 안 된다', () => {
+    expect(isTransientAIError(err('invalid api key', { status: 401 }))).toBe(false)
+    expect(isTransientAIError(err('bad request', { status: 400 }))).toBe(false)
+    expect(isTransientAIError(err('not found', { status: 404 }))).toBe(false)
+  })
+
+  it('네트워크 계열은 일시로 본다', () => {
+    expect(isTransientAIError(err('socket hang up'))).toBe(true)
+    expect(isTransientAIError(err('fetch failed'))).toBe(true)
+  })
+
+  it('과부하 표현은 코드가 없어도 일시로 본다', () => {
+    expect(isTransientAIError(err('The model is overloaded. Please try again later.'))).toBe(true)
+  })
+
+  it('사용자 취소는 재시도 대상이 아니다 — 사용자가 멈춘 것이다', () => {
+    expect(isTransientAIError(Object.assign(new Error('aborted'), { name: 'AbortError' }))).toBe(false)
+  })
+})
+
+describe('retryTransient', () => {
+  const nosleep = async () => {}
+
+  it('일시 장애면 다시 시도해 성공한다', async () => {
+    let n = 0
+    const r = await retryTransient(
+      async () => {
+        n++
+        if (n < 3) throw err('unavailable', { status: 503 })
+        return 'ok'
+      },
+      { attempts: 3, sleep: nosleep }
+    )
+    expect(r).toBe('ok')
+    expect(n).toBe(3)
+  })
+
+  it('일시가 아니면 즉시 던진다 — 조용히 몇 번 더 시도하지 않는다', async () => {
+    let n = 0
+    await expect(
+      retryTransient(
+        async () => {
+          n++
+          throw err('invalid api key', { status: 401 })
+        },
+        { attempts: 3, sleep: nosleep }
+      )
+    ).rejects.toThrow(/invalid api key/)
+    expect(n).toBe(1)
+  })
+
+  it('시도 횟수를 다 쓰면 마지막 오류를 던진다', async () => {
+    await expect(
+      retryTransient(async () => { throw err('unavailable', { status: 503 }) }, { attempts: 2, sleep: nosleep })
+    ).rejects.toThrow(/unavailable/)
+  })
+
+  it('대기는 시도마다 2배로 늘린다 — 같은 순간에 몰아 때리지 않는다', async () => {
+    const delays: number[] = []
+    await expect(
+      retryTransient(async () => { throw err('unavailable', { status: 503 }) }, {
+        attempts: 3,
+        baseDelayMs: 100,
+        sleep: async (ms: number) => { delays.push(ms) }
+      })
+    ).rejects.toThrow()
+    expect(delays).toEqual([100, 200])
+  })
+})

package/server/service/utils/transient.ts

@@ -0,0 +1,92 @@
+/*
+ * 일시 장애 분류와 재시도 — **모델 서비스는 가끔 잠깐 죽는다.**
+ *
+ * 실제로 났다: Gemini 가 503(Service Unavailable)을 돌려주자 대화가 그 자리에서 끝나고, 사용자에게는
+ * SDK 원문("Error fetching from undefined: [503 …]")이 그대로 보였다. 두 가지가 잘못이다 —
+ * ① 잠깐 죽은 것에 한 번도 다시 시도하지 않았고, ② 사용자에게 우리 말이 아닌 남의 말을 보여줬다.
+ *
+ * 여기서는 ①의 판정과 대기만 담당한다(순수). 무엇을 보여줄지는 표면의 몫이다.
+ *
+ * ── 무엇을 일시로 보는가 ────────────────────────────────────────────────────
+ * 다시 시도하면 될 수 있는 것만: 429(과부하·쿼터 초과 순간), 5xx(서비스 불가·게이트웨이),
+ * 그리고 네트워크 계열(연결 끊김·타임아웃). **400·401·403·404 는 다시 해도 같다** — 요청이나
+ * 자격이 잘못된 것이므로 즉시 알려야 한다(조용히 몇 번 더 시도하면 원인이 늦게 드러난다).
+ */
+
+/** 상태 코드를 여러 프로바이더 SDK 의 오류 모양에서 최대한 끌어낸다. */
+function statusOf(e: any): number | undefined {
+  const candidates = [e?.status, e?.statusCode, e?.response?.status, e?.cause?.status]
+  for (const c of candidates) {
+    const n = typeof c === 'string' ? Number(c) : c
+    if (typeof n === 'number' && Number.isFinite(n)) return n
+  }
+  /* SDK 가 코드를 본문에만 넣는 경우(예: "[503 Service Unavailable]") 메시지에서 찾는다. */
+  const m = /\[(\d{3})\s/.exec(String(e?.message ?? ''))
+  return m ? Number(m[1]) : undefined
+}
+
+/** 네트워크 계열 오류 표식 — 코드가 없어도 다시 시도할 값이 있는 것들. */
+const NETWORK_MARKERS = [
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ETIMEDOUT',
+  'EAI_AGAIN',
+  'ENOTFOUND',
+  'socket hang up',
+  'fetch failed',
+  'network error',
+  'terminated'
+]
+
+/** 프로바이더가 과부하를 코드 없이 알리는 표현들. */
+const OVERLOAD_MARKERS = ['overloaded', 'rate limit', 'try again', 'temporarily unavailable', 'service unavailable']
+
+/** 다시 시도할 가치가 있는 오류인가. 취소(abort)는 재시도 대상이 아니다 — 사용자가 멈춘 것이다. */
+export function isTransientAIError(e: any): boolean {
+  if (!e) return false
+  if (e?.name === 'AbortError') return false
+  const status = statusOf(e)
+  if (status === 429) return true
+  if (status && status >= 500 && status < 600) return true
+  if (status && status >= 400 && status < 500) return false // 요청·자격 문제는 다시 해도 같다
+  const message = String(e?.message ?? '').toLowerCase()
+  return [...NETWORK_MARKERS, ...OVERLOAD_MARKERS].some(marker => message.includes(marker.toLowerCase()))
+}
+
+export interface RetryOptions {
+  /** 총 시도 횟수(첫 시도 포함). 기본 3. */
+  attempts?: number
+  /** 첫 대기(ms). 시도마다 2배로 늘린다. 기본 500. */
+  baseDelayMs?: number
+  /** 대기 구현 — 테스트가 즉시 진행하기 위한 이음매. */
+  sleep?: (ms: number) => Promise<void>
+  /** 재시도 직전 통지(로그·관측). */
+  onRetry?: (info: { attempt: number; delayMs: number; error: any }) => void
+}
+
+const defaultSleep = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms))
+
+/**
+ * 일시 장애면 지수 백오프로 다시 시도한다. 일시가 아니면 **즉시 그대로 던진다**(감추지 않는다).
+ *
+ * 대기 시간을 길게 두지 않는다 — 사용자가 화면 앞에서 기다리는 호출이다. 몇 초 안에 안 되면
+ * 실패를 알리고 사용자가 다시 묻게 하는 것이 낫다.
+ */
+export async function retryTransient<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
+  const attempts = Math.max(1, options.attempts ?? 3)
+  const base = Math.max(0, options.baseDelayMs ?? 500)
+  const sleep = options.sleep ?? defaultSleep
+  let lastError: any
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await fn()
+    } catch (e) {
+      lastError = e
+      if (attempt >= attempts || !isTransientAIError(e)) throw e
+      const delayMs = base * 2 ** (attempt - 1)
+      options.onRetry?.({ attempt, delayMs, error: e })
+      await sleep(delayMs)
+    }
+  }
+  throw lastError
+}