package com.lingyue.ai.service;

import com.lingyue.ai.dto.ner.*;

import java.util.List;
import java.util.concurrent.CompletableFuture;

/**
 * NER（命名实体识别）服务接口
 *
 * @author lingyue
 * @since 2026-01-19
 */
public interface NerService {

    /**
     * 从文本中提取实体（同步）
     *
     * @param request NER 请求
     * @return NER 响应（包含实体和关系）
     */
    NerResponse extractEntities(NerRequest request);

    /**
     * 从文本中提取实体（异步）
     *
     * @param request NER 请求
     * @return 异步结果
     */
    CompletableFuture<NerResponse> extractEntitiesAsync(NerRequest request);

    /**
     * 从已提取的实体中抽取关系
     *
     * @param request 关系抽取请求
     * @return 关系抽取响应
     */
    RelationResponse extractRelations(RelationRequest request);

    /**
     * 对已解析的文档执行 NER 并保存结果到图数据库
     *
     * @param documentId 文档ID
     * @param userId     用户ID
     * @return NER 响应
     */
    NerResponse extractAndSaveForDocument(String documentId, String userId);

    /**
     * 对已解析的文档执行 NER 并保存结果到图数据库（异步）
     *
     * @param documentId 文档ID
     * @param userId     用户ID
     * @return 异步结果
     */
    CompletableFuture<NerResponse> extractAndSaveForDocumentAsync(String documentId, String userId);

    /**
     * 批量提取实体
     *
     * @param texts 文本列表
     * @return 每个文本的实体列表
     */
    List<List<EntityInfo>> batchExtractEntities(List<String> texts);
}
