domain

type Chunk struct {
	ID        string
	Content   string
	ParentID  string
	Embedding []float64
	Position  int
	// Metadata хранит произвольные метаданные чанка, унаследованные от родительского документа.
	// nil означает отсутствие метаданных и не влияет на результат Validate.
	Metadata map[string]string
}

type Chunker interface {
	// Chunk разбивает документ на фрагменты для индексации.
	Chunk(ctx context.Context, doc Document) ([]Chunk, error)
}

type CollectionManager interface {
	// CreateCollection создаёт коллекцию в хранилище.
	// Idempotent: повторный вызов при уже существующей коллекции возвращает nil.
	CreateCollection(ctx context.Context) error

	// DeleteCollection удаляет коллекцию из хранилища.
	// Idempotent: возвращает nil если коллекция не существует (404).
	DeleteCollection(ctx context.Context) error

	// CollectionExists проверяет существование коллекции.
	// Возвращает (true, nil) если коллекция существует, (false, nil) если нет,
	// (false, error) при сетевой или серверной ошибке.
	CollectionExists(ctx context.Context) (bool, error)
}

type Document struct {
	ID        string
	Content   string
	Metadata  map[string]string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type DocumentStore interface {
	VectorStore
	// DeleteByParentID удаляет все чанки с указанным ParentID.
	DeleteByParentID(ctx context.Context, parentID string) error
}

type Embedder interface {
	// Embed преобразует текст в embedding-вектор фиксированной размерности.
	Embed(ctx context.Context, text string) ([]float64, error)
}

type Embedding struct {
	Vector    []float64
	Dimension int
	Model     string
}

type HookStage string

type Hooks interface {
	StageStart(ctx context.Context, ev StageStartEvent)
	StageEnd(ctx context.Context, ev StageEndEvent)
}

type HybridConfig struct {
	// SemanticWeight вес семантического скора (0.0 - 1.0).
	// BM25Weight вычисляется как 1.0 - SemanticWeight.
	// При значении 0.0 используется только BM25, при 1.0 — только семантический.
	// Default: 0.7
	SemanticWeight float64

	// UseRRF если true, используется Reciprocal Rank Fusion вместо weighted score.
	// При UseRRF=true поле SemanticWeight игнорируется.
	// Default: true
	UseRRF bool

	// RRFK константа для RRF-формулы: score = 1/(k + rank).
	// Default: 60
	RRFK int

	// BMFinalK количество результатов, возвращаемых после fusion.
	// Должно быть <= topK.
	// Default: равно topK (0 означает "использовать topK")
	BMFinalK int
}

type HybridSearcher interface {
	// SearchHybrid выполняет гибридный поиск: семантический + BM25.
	// Возвращает объединённые результаты с скором от fusion-стратегии.
	SearchHybrid(ctx context.Context, query string, embedding []float64, topK int, config HybridConfig) (RetrievalResult, error)
}

type HybridSearcherWithFilters interface {
	HybridSearcher

	// SearchHybridWithParentIDFilter выполняет гибридный поиск с фильтрацией по ParentID.
	SearchHybridWithParentIDFilter(ctx context.Context, query string, embedding []float64, topK int, config HybridConfig, filter ParentIDFilter) (RetrievalResult, error)

	// SearchHybridWithMetadataFilter выполняет гибридный поиск с фильтрацией по метаданным.
	SearchHybridWithMetadataFilter(ctx context.Context, query string, embedding []float64, topK int, config HybridConfig, filter MetadataFilter) (RetrievalResult, error)
}

type IndexBatchError struct {
	// DocumentID — идентификатор документа, который не удалось проиндексировать.
	DocumentID string
	// Error — оригинальная ошибка (embed, chunking или upsert).
	Error error
}

type IndexBatchResult struct {
	// Successful — документы, успешно проиндексированные (все чанки сохранены).
	Successful []Document
	// Errors — ошибки по документам (partial failure).
	Errors []IndexBatchError
	// ProcessedCount — общее количество обработанных документов (успешных + с ошибками).
	ProcessedCount int
}

type InlineCitation struct {
	Number int
	Chunk  RetrievedChunk
}

type LLMProvider interface {
	// Generate генерирует ответ на основе system и user сообщений.
	Generate(ctx context.Context, systemPrompt, userMessage string) (string, error)
}

type LogField struct {
	Key   string
	Value any
}

type LogLevel string

type Logger interface {
	Log(ctx context.Context, level LogLevel, msg string, fields ...LogField)
}

type MetadataFilter struct {
	// Fields — карта имён полей метаданных и их ожидаемых строковых значений.
	Fields map[string]string
}

type ParentIDFilter struct {
	// ParentIDs — список допустимых parent_id. Пустой список означает “без фильтра”.
	ParentIDs []string
}

type Query struct {
	Text   string
	TopK   int
	Filter map[string]string
}

type Reranker interface {
	Rerank(ctx context.Context, query string, chunks []RetrievedChunk) ([]RetrievedChunk, error)
}

type RetrievalResult struct {
	Chunks     []RetrievedChunk
	QueryText  string
	TotalFound int
}

type RetrievedChunk struct {
	Chunk Chunk
	Score float64
}

type StageEndEvent struct {
	Operation string
	Stage     HookStage
	Duration  time.Duration
	Err       error
}

type StageStartEvent struct {
	Operation string
	Stage     HookStage
}

type StreamingLLMProvider interface {
	LLMProvider

	// GenerateStream генерирует ответ токен за токеном через канал.
	// Возвращает канал для чтения текстовых чанков; канал закрывается при завершении или ошибке.
	GenerateStream(ctx context.Context, systemPrompt, userMessage string) (<-chan string, error)
}

type VectorStore interface {
	// Upsert сохраняет или обновляет чанк в хранилище.
	Upsert(ctx context.Context, chunk Chunk) error

	// Delete удаляет чанк по ID из хранилища.
	Delete(ctx context.Context, id string) error

	// Search выполняет поиск похожих чанков по embedding-вектору.
	// Возвращает результат с релевантными чанками, отсортированными по score (по убыванию).
	Search(ctx context.Context, embedding []float64, topK int) (RetrievalResult, error)
}

type VectorStoreWithFilters interface {
	VectorStore

	// SearchWithFilter выполняет поиск похожих чанков по embedding-вектору с дополнительным фильтром.
	SearchWithFilter(ctx context.Context, embedding []float64, topK int, filter ParentIDFilter) (RetrievalResult, error)

	// SearchWithMetadataFilter выполняет поиск похожих чанков с фильтрацией по полям метаданных.
	// Пустой filter.Fields (nil или len==0) эквивалентно вызову Search без фильтра.
	SearchWithMetadataFilter(ctx context.Context, embedding []float64, topK int, filter MetadataFilter) (RetrievalResult, error)
}