AI 캐릭터 대화 엔진 설계: 3단계 파이프라인과 실시간 스트리밍

// backend/src/ai-pipeline/ai-pipeline.service.ts (요약)
async runStream(
  context: PipelineContext,
  onItem: (item: GeneratedItem) => void,
): Promise<PipelineResult> {
  // 1단계: 기억 검색·로어 선택, 입력 안전 심사는 promise 로 띄워만 둔다
  const genContext = await this.buildGenerationContext(context);

  // 2단계: 응답 생성 (스트리밍). 입력 판정이 개입을 요구하면 safetyAbort 로 끊는다
  const result = await this.executeWithRetry(
    genContext.context,
    emit,
    safetyAbort.signal,
  );

  // 3단계: 호감도 평가 + 메타데이터 정리
  return this.evaluateAndFinalize(context, genContext, result);
}

// backend/src/ai-pipeline/ai-pipeline.service.ts: buildGenerationContext 내부
targetCharacterName = context.characters[0].name;
targetCharacterId = nameToId.get(targetCharacterName) ?? null;

// backend/src/ai-pipeline/ai-pipeline.service.ts: buildGenerationContext 내부
const inputSafetyPromise = this.contentSafetyEvaluation
  .evaluateInput(safetyParams)
  .catch((err: unknown) => {
    this.logger.error(`Input safety evaluation threw: ${String(err)}`);
    return {
      decision: 'APPROVE',
      reason: 'Safety evaluation failed',
    } as SafetyEvalResult;
  })
  .then(withNormalizedCategory);

// backend/src/ai-pipeline/services/prompt-builder.ts (발췌)
private static readonly BLOCK_RENDERERS = {
  // ① 서비스 골격
  'director/mode': (b) => b.renderDirectorMode(),
  'safety/content-rating': (b) => b.renderContentRating(),
  // ② 캐릭터 정체성
  'character/profiles': (b) => b.renderCharacterProfiles(),
  // ③ 관계와 상태
  'affinity/level-guide': (b) => renderAffinityLevelGuide(b.sections),
  // ⑥ 참고 데이터와 그 한계
  'memory/recalled': (b) => b.renderMemories(),
  // ⑦ 대화 기록
  'chat/history': (b) => b.renderRecentHistory(),
  // ⑧ 최종 지시
  'output/format': (b) => b.renderOutputFormat(),
  // ...
};

// packages/shared/src/affinity-config.ts (발췌)
export const AFFINITY_LEVEL_GUIDES: Record<number, string> = {
  [1]: '거리를 두되 차갑지는 않다. 상대가 말을 걸면 짧게 답하고, 호기심이 생기면 조심스럽게 티를 낸다. 먼저 나서지 않지만 대화를 이어가려는 기색은 있다.',
  [2]: '경계를 낮추고 자연스럽게 대화한다. 가벼운 농담을 섞고, 서투른 모습을 숨기지 않으며, 상대의 일상에 소소한 관심을 보인다.',
  // ...
};

{
  "items": [
    {"type": "narration", "text": "묘한 침묵이 흘렀다."},
    {"type": "dialogue", "character": "한시우", "text": "(시선을 피하며) ...뭐야, 왜 조용해."}
  ],
  "currentLocation": "학교 옥상",
  "characterStates": {
    "한시우": {"mood": "불안", "thinking": "뭔가 이상한데..."}
  },
  "emotionCode": "shy",
  "sceneCode": "school"
}

// backend/src/ai-pipeline/utils/streaming-json-extractor.ts (요약)
export class StreamingJsonExtractor<T = unknown> {
  private buffer = '';
  private depth = 0;
  private itemStart = -1;
  private inString = false;   // 문자열 내부 중괄호 무시
  private escaped = false;    // 이스케이프 시퀀스 처리
  private arrayFound = false;
  private cursor = 0;         // 이미 처리한 위치: 재스캔 방지

  feed(chunk: string): T[] {
    this.buffer += chunk;
    const items: T[] = [];

    // "items": [ 패턴을 찾아 배열 시작 위치 확정
    if (!this.arrayFound) {
      const pattern = new RegExp(
        `"${this.escapeRegex(this.arrayKey)}"\\s*:\\s*\\[`,
      );
      const match = this.buffer.match(pattern);
      if (!match) return [];
      this.arrayFound = true;
      this.cursor = this.buffer.indexOf(match[0]) + match[0].length;
    }

    for (let i = this.cursor; i < this.buffer.length; i++) {
      const ch = this.buffer[i];
      if (this.escaped) { this.escaped = false; continue; }
      if (ch === '\\' && this.inString) { this.escaped = true; continue; }
      if (ch === '"') { this.inString = !this.inString; continue; }
      if (this.inString) continue;

      if (ch === '{') {
        if (this.depth === 0) this.itemStart = i;
        this.depth++;
      } else if (ch === '}') {
        this.depth--;
        if (this.depth === 0 && this.itemStart !== -1) {
          // 완전한 객체 하나 완성 → JSON.parse 후 반환 (깨진 객체는 건너뛴다)
          try {
            items.push(JSON.parse(this.buffer.slice(this.itemStart, i + 1)) as T);
          } catch {}
          this.itemStart = -1;
        }
      }
    }
    this.cursor = this.buffer.length;
    return items;
  }
}

// backend/src/ai-pipeline/services/response-generation.service.ts: generateStream 내부
const extractor = new StreamingJsonExtractor<Record<string, unknown>>('items');

const handleTextDelta = (textDelta: string) => {
  fullText += textDelta;
  const newItems = extractor.feed(textDelta);
  const normalized = ResponseGenerationService.normalizeItems(
    newItems,
    context.targetCharacterName,
  );
  // 완성된 항목마다 즉시 콜백 호출
  for (const item of normalized) {
    onItem(item);
    sentItemCount++;
  }
};

// backend/src/ai-pipeline/ai-pipeline.service.ts: executeWithRetry 내부
if (err.sentItemCount > 0) {
  this.logger.warn(
    `Generation failed after ${err.sentItemCount} items sent: cannot retry`,
  );
  throw err;
}

// backend/src/ai-pipeline/services/response-generation.service.ts: generateStream 내부
const req = {
  task: LlmTask.RESPONSE_GENERATION,
  modelId: context.llmModelId,
  maxTokens: 4096,
  system: systemSegments,
  userMessage: context.userMessage,
  responseFormat: 'json' as const,
  operation: 'generate-response',
};

// backend/src/common/ai-client/ai-client.service.ts
async resolveModel(req: AiTextRequest): Promise<ResolvedLlmModel> {
  const chosen = await this.registry.resolveUserChoice(req.modelId);
  if (chosen && chosen.modality === 'TEXT') return chosen;
  return this.registry.resolveForTask(req.task);
}

// packages/shared/src/sse-events.ts (발췌)
export const SSE_EVENTS = {
  NARRATION: 'narration',
  DIALOGUE: 'dialogue',
  SCENE_TRANSITION: 'scene_transition',
  AFFINITY_DELTA: 'intimacy_delta',
  LOCATION_CHANGE: 'location_change',
  CONVERSATION_PAUSE: 'conversation_pause',
  DIALOGUE_CUT: 'dialogue_cut',
  DONE: 'done',
  ERROR: 'error',
  // ... 기기 간 동기화, 세션 공유 이벤트
} as const;

// backend/src/chat/chat.controller.ts: sendMessage 내부 (요약)
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
return this.chatTurn.run(
  { sessionId, userId, content, mentionedCharacter, forceAdvanceEvent, clientId },
  res,
);

// backend/src/chat/turn-sse.ts
export function sseFrame(event: string, data: unknown): string {
  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
}

// backend/src/chat/turn-failure.ts
export function classifyTurnFailure(
  error: unknown,
  flushedItemCount: number,
): TurnFailureKind {
  // 제공사 하드 차단은 아무것도 저장되지 않은 턴 실패다. 흘러간 항목 수와 무관하게 환불한다
  if (error instanceof ProviderBlockedError) {
    return 'complete_failure';
  }
  if (error instanceof RetryableGenerationError && error.sentItemCount > 0) {
    return 'generation_partial';
  }
  if (flushedItemCount > 0) {
    return 'response_save_failed';
  }
  return 'complete_failure';
}

// backend/src/chat/chat-turn.service.ts
private async issueRefundOnce(
  state: TurnState,
): Promise<{ gemRefunded: boolean; error?: unknown }> {
  // 테스트 턴, 혹은 아직 차감이 일어나기 전 실패는 환불할 것이 없다
  if (
    !state.wallet?.gemTransactionId ||
    state.refundIssued ||
    state.isTestSession
  ) {
    return { gemRefunded: false };
  }
  state.refundIssued = true;
  try {
    await this.gemsService.refundSpend(state.wallet.gemTransactionId);
    return { gemRefunded: true };
  } catch (error) {
    return { gemRefunded: false, error };
  }
}

// frontend/src/lib/sse.ts: sendMessageSSE 내부
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop() || '';

let currentEvent = 'message';
for (const line of lines) {
  if (line.startsWith('event: ')) {
    currentEvent = line.slice(7).trim();
  } else if (line.startsWith('data: ')) {
    try {
      onEvent(currentEvent, JSON.parse(line.slice(6)));
    } catch {
      // 형식이 잘못된 데이터 건너뜀
    }
  }
}