package com.zioinfo.kintex.ai;

/**
 * 텍스트 생성 provider 추상화 (F100 AI 플랫폼 라우터).
 *
 * <p>온프레미스 Ollama({@link OllamaTextClient})와 외부 Claude({@link ClaudeTextClient})를 동일 계약으로 다룬다.
 * 구현체는 어떤 사유로든(비활성/실패/타임아웃/키·URL 미설정) 실패 시 {@link GenResult#degraded()}=true·
 * {@link GenResult#text()}=null 을 반환하고 <b>예외를 던지지 않는다</b>. 폴백은 호출자({@link AiTextRouter})가 책임진다.
 *
 * <p>provider 선택/폴백 라우팅은 {@link AiTextRouter} 가 담당한다.
 */
public interface TextAiClient {

    /** 프롬프트로 텍스트를 생성한다. 실패 시 {@code degraded=true·text=null}(예외 미투척). */
    GenResult generate(String prompt);

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

        public static GenResult fail() {
            return new GenResult(null, true);
        }

        public static GenResult ok(String text) {
            return new GenResult(text, false);
        }

        public boolean usable() {
            return !degraded && text != null && !text.isBlank();
        }
    }
}
