package com.superbiz.agent.service;

import com.superbiz.agent.dto.KnowledgeQuery;
import org.springframework.stereotype.Service;

import java.util.List;

/**
 * 检索前的 query 理解层（L0 出口）。
 *
 * <p>输入是 Agent 的原始检索句，输出 {@link KnowledgeQuery}，供后续 L1 过滤与 rerank 使用。</p>
 *
 * <h3>当前能力边界</h3>
 * <ul>
 *   <li>会做：关键词匹配、domain/entity/title hint、唯一 domain 时生成 categoryFilter</li>
 *   <li>不会做：真正的 query rewrite / 同义词扩展 / 多 query 改写
 *       （{@code rewrittenQuery} 目前等于 {@code originalQuery}）</li>
 *   <li>L0 命中文档正文不会直接当作 evidence；证据只来自 L1 向量召回</li>
 * </ul>
 */
@Service
public class KnowledgeQueryTransformer {

    private final KnowledgeIndexService knowledgeIndexService;

    public KnowledgeQueryTransformer(KnowledgeIndexService knowledgeIndexService) {
        this.knowledgeIndexService = knowledgeIndexService;
    }

    /**
     * 将原始 query 转为检索控制结构。
     *
     * <p>{@code categoryFilter} 仅在 L0 恰好命中一个 domain 时非空；
     * 多 domain 或零 domain 时为 null，避免错误收窄召回。</p>
     */
    public KnowledgeQuery transform(String rawQuery) {
        String normalized = rawQuery == null ? "" : rawQuery.trim();
        KnowledgeIndexService.L0Hint hint = knowledgeIndexService.analyzeQuery(normalized);
        return KnowledgeQuery.builder()
                .originalQuery(normalized)
                // 预留改写字段；当前未实现 rewrite，保持与 original 一致
                .rewrittenQuery(normalized)
                .domainHints(safeList(hint.domains()))
                .matchedKeywords(safeList(hint.matchedKeywords()))
                .entities(safeList(hint.entities()))
                // 只有唯一 domain 才作为向量 metadata 的 category 过滤条件
                .categoryFilter(hint.singleDomainOrNull())
                .l0Titles(safeList(hint.titles()))
                .l0MatchCount(hint.matches() == null ? 0 : hint.matches().size())
                .build();
    }

    private List<String> safeList(List<String> values) {
        return values == null ? List.of() : values;
    }
}