connectai/src/retrieval/intentClarification.ts

/**
 * Intent Clarification — 모호한 질의에서 *추측 답변 대신 질문 던지기* 지시.
 *
 * 사용자 피드백: "ASTRA 는 질문을 받으면 즉시 답변을 생성하려 함. 하지만 '날카로운'
 * 파악을 위해서는 질문 뒤의 '실행 목적' 을 먼저 정의해야". 예: "배포해줘" → 환경
 * (dev/prod) / 태그 묻기. "그 부분 고쳐줘" → 어느 파일/모듈인지 묻기.
 *
 * 현재 ASTRA: 모호 감지 메커니즘 없음. CoVe(v2.2.184) 가 *답변 작성 시* 출처 매핑
 * 검증하지만, *질문 자체가 모호한 경우* 는 다루지 않음. 이 모듈이 그 갭.
 *
 * 설계:
 *   - 휴리스틱 차원(환경/대상/범위/포맷/마감) 별로 *trigger 키워드 + 명시 키워드* 정의
 *   - trigger 가 있는데 명시가 없으면 missing
 *   - missing 차원이 strictness 임계 이상이면 ambiguous → 시스템 프롬프트에 질문 지시
 *
 * 위험: false positive → 사용자가 "그냥 답해" 짜증. strictness 로 조절.
 */

export type IntentStrictness = 'low' | 'medium' | 'high';

interface AmbiguityDimensionDef {
    key: string;
    label: string;             // 한국어 표시명
    /** 이 차원이 *문제 되는 지* 판정하는 trigger 단어들 (있으면 의심 시작). */
    triggers: string[];
    /** 차원이 *명시* 됐다고 보는 단어들 (있으면 ambiguity 해소). */
    specifiers: string[];
    /** missing 일 때 사용자에게 권장 질문 예시. */
    suggestedQuestion: string;
}

const DIMENSIONS: AmbiguityDimensionDef[] = [
    {
        key: 'environment',
        label: '환경 (dev/prod/staging)',
        triggers: ['배포', '롤백', 'deploy', 'rollback', 'release', '릴리스', '릴리즈', '띄워', '재시작', 'restart'],
        specifiers: ['dev', 'prod', 'staging', 'local', '로컬', '개발', '운영', '프로덕션', '스테이징', '본번', '본 번', '본번에', '운영에'],
        suggestedQuestion: '어느 환경에 작업할지 (dev/prod/staging) 명시해 주실 수 있나요?',
    },
    {
        key: 'target',
        label: '대상 (파일/모듈/멤버)',
        triggers: ['고쳐', '고처', '수정', '바꿔', '추가', '제거', '리팩토', '리팩터', '리팩터링', '리팩토링', '개선', '정리', '리뷰', '검토해'],
        specifiers: ['.ts', '.tsx', '.js', '.py', '.md', '.json', '.go', '.rs', '파일', '함수', '클래스', '모듈', '@', 'src/', 'lib/', 'features/', '폴더'],
        suggestedQuestion: '어느 파일/모듈/함수를 대상으로 할지 명시해 주실 수 있나요?',
    },
    {
        key: 'scope',
        label: '범위 (전체/부분)',
        triggers: ['리팩토', '리팩터', '리팩터링', '리팩토링', '정리해', '개선', '최적화', '튜닝', '청소', '정비'],
        specifiers: ['전체', '전부', '모두', '일부', '특정', '하나만', '이것만', '여기만', '단', '단지'],
        suggestedQuestion: '범위가 전체인지 특정 부분인지 알려 주실 수 있나요?',
    },
    {
        key: 'format',
        label: '출력 포맷',
        triggers: ['요약', '보고서', '리포트', '정리', '문서', '카드', '발표', '슬라이드', '프레젠테이션'],
        specifiers: ['표', '리스트', 'json', 'markdown', '마크다운', '단락', 'bullet', '글머리표', '한장', '한 장', '슬라이드', 'pdf', '문장으로', '항목별', '단계별'],
        suggestedQuestion: '어떤 형식 (표/리스트/단락 등) 으로 받고 싶은지 알려 주실 수 있나요?',
    },
    {
        key: 'deadline',
        label: '마감/긴급도',
        triggers: ['언제까지', '마감', '빨리', '급함', '오늘 안에', '내일까지'],
        specifiers: ['오늘', '내일', '이번 주', '다음 주', '월', '일', '시', '분'],
        suggestedQuestion: '마감일이나 긴급도를 알려 주실 수 있나요?',
    },
];

export interface AmbiguityResult {
    ambiguous: boolean;
    missingDimensions: { key: string; label: string; suggestedQuestion: string }[];
    triggerCount: number;
    promptLength: number;
}

function hasAnyKeyword(text: string, keywords: string[]): boolean {
    const lower = text.toLowerCase();
    return keywords.some((k) => lower.includes(k.toLowerCase()));
}

/**
 * 모호 감지. strictness 에 따라 threshold 변동:
 *   - low: 2개 이상 missing → ambiguous
 *   - medium: 1개 이상 missing → ambiguous (기본)
 *   - high: 1개 이상 missing OR 프롬프트 짧음 (<20 chars) → ambiguous
 */
export function detectAmbiguity(prompt: string, strictness: IntentStrictness = 'medium'): AmbiguityResult {
    const result: AmbiguityResult = {
        ambiguous: false,
        missingDimensions: [],
        triggerCount: 0,
        promptLength: (prompt || '').length,
    };
    if (!prompt || !prompt.trim()) return result;

    for (const dim of DIMENSIONS) {
        const hasTrigger = hasAnyKeyword(prompt, dim.triggers);
        if (!hasTrigger) continue;
        result.triggerCount++;
        const hasSpecifier = hasAnyKeyword(prompt, dim.specifiers);
        if (!hasSpecifier) {
            result.missingDimensions.push({
                key: dim.key,
                label: dim.label,
                suggestedQuestion: dim.suggestedQuestion,
            });
        }
    }

    const missingCount = result.missingDimensions.length;
    if (strictness === 'low') result.ambiguous = missingCount >= 2;
    else if (strictness === 'medium') result.ambiguous = missingCount >= 1;
    else result.ambiguous = missingCount >= 1 || (result.promptLength < 20 && result.triggerCount > 0);

    return result;
}

/**
 * 시스템 프롬프트용 [INTENT CLARIFICATION GUIDANCE] 블록.
 * ambiguous=false 면 빈 문자열 반환.
 */
export function buildIntentClarificationBlock(result: AmbiguityResult): string {
    if (!result.ambiguous || result.missingDimensions.length === 0) return '';

    const lines: string[] = [];
    lines.push('[INTENT CLARIFICATION GUIDANCE]');
    lines.push('사용자 질의에서 다음 의도 차원이 *명시되지 않음* — 추측 답변보다 *짧은 역질문* 우선:');
    lines.push('');
    for (const d of result.missingDimensions) {
        lines.push(`- **${d.label}** — 예: "${d.suggestedQuestion}"`);
    }
    lines.push('');
    lines.push('[지침]');
    lines.push('1. 모호 차원이 답변의 *방향* 을 좌우하는 경우, 1~2개 핵심 질문을 *먼저* 던질 것 (전체 답변 미리 만들지 말 것).');
    lines.push('2. 사용자가 이미 "추정해도 OK", "그냥 진행", "알아서" 같은 표현을 했으면 합리적 가정 + *가정 명시* 후 진행.');
    lines.push('3. 모호 차원이 답변과 *무관* 한 정보성/탐색성 질의면 그대로 답변 OK.');
    lines.push('4. 질문 던질 때 사용자가 다시 입력하기 쉽도록 *선택지 2~3개* 또는 *기대 형식* 같이 명시.');
    lines.push('[/INTENT CLARIFICATION GUIDANCE]');
    return lines.join('\n');
}