package core

import "context"

// ---- 检索管线组件契约（设计 4.12：查询 → Embedding → 混合检索(向量+全文) → Rerank → TopK → 注入）----
// 契约先行：实现按档位组合（嵌入式档=分块+FTS5+进程内向量扫描；PG 档可换
// tsvector/pgvector）；管线编排见 backend internal/rag。

// Chunk 是分块结果（Chunker 输出；Index 为文档内序号）。
type Chunk struct {
	Text  string `json:"text"`
	Index int    `json:"index"`
}

// Chunker 把解析文档切分为检索块（策略由实现决定；空实现=整文档单块）。
type Chunker interface {
	Chunk(doc ParsedDocument) []Chunk
}

// EmbeddingProvider 文本批量 → 向量（OpenAI 兼容 /embeddings 或插件提供）。
type EmbeddingProvider interface {
	Embed(ctx context.Context, texts []string) ([][]float32, error)
}

// VectorIndex 向量存取；实现负责租户过滤（owner 本人 + 共享）。
type VectorIndex interface {
	Upsert(ctx context.Context, owner, docID, ref ID, vec []float32) error
	DeleteByRef(ctx context.Context, owner ID, ref ID) error
	// Search 按余弦相似度降序返回命中。
	Search(ctx context.Context, owner ID, vec []float32, topK int, filter RetrievalQuery) ([]RetrievalHit, error)
}

// Reranker 对候选重排序；未配置时管线跳过（排序退化为混合分）。
type Reranker interface {
	Rerank(ctx context.Context, query string, docs []KnowledgeDoc, topK int) ([]KnowledgeDoc, error)
}

// Retriever 统一检索入口：实现决定全文/向量/混合与是否 rerank。
type Retriever interface {
	Retrieve(ctx context.Context, owner ID, q RetrievalQuery) ([]RetrievalHit, error)
}

// DocumentIndexer 检索索引写入（分块 + 全文 + 可选向量）；upload/工件产物统一走此入口。
type DocumentIndexer interface {
	IndexDocument(owner ID, projectID ID, source, title, ref, plainText string) error
}