package com.zioinfo.hrm.common.ai;

/**
 * 텍스트 생성 공용 인터페이스 (AI provider 추상화). [GUARDiA-HRM]
 *
 * <p>온프레미스 Ollama({@link OllamaTextClient})와 외부 Claude({@link ClaudeTextClient})를 동일 계약으로
 * 다루기 위한 얇은 추상화. 구현체는 어떤 사유로든(비활성/실패/타임아웃/키미설정) 실패 시
 * {@link GenResult#degraded()}=true · {@link GenResult#text()}=null 을 반환하고, 호출자가 폴백을 책임진다.
 *
 * <p>provider 선택/폴백 라우팅은 {@code ai.service.AiTextRouter} 가 담당한다(이 인터페이스를 구현).
 *
 * <p><b>레퍼런스</b>: guardia-ocr {@code com.zioinfo.ocr.common.ai.TextAiClient} 미러(패키지·ISSUER 치환).
 */
public interface TextAiClient {

    /**
     * 프롬프트로 텍스트를 생성한다. 실패 시 {@code degraded=true·text=null}(예외를 던지지 않음).
     *
     * @param prompt 한국어 지시문(컨텍스트 포함)
     * @return 생성 결과(텍스트 또는 degraded 폴백 신호)
     */
    GenResult generate(String prompt);

    /** 생성 결과: 텍스트(폴백 시 null) + degraded(폴백 여부). */
    record GenResult(String text, boolean degraded) {
    }
}
