domain

type BatchReranker ¶ added in v1.0.0

type BatchReranker interface {
	Reranker
	// RerankBatch принимает несколько query и один набор чанков.
	// Возвращает список результатов той же длины, что и queries.
	// Каждый результат — переранжированная версия chunks для соответствующего query.
	RerankBatch(ctx context.Context, queries []string, chunks []RetrievedChunk) ([][]RetrievedChunk, error)
}

BatchReranker — опциональное расширение Reranker для batch-режима.

@sk-task reranker-cross-encoder#T1.1: BatchReranker interface (AC-008) Позволяет переранжировать один набор чанков по нескольким query одновременно. Pipeline проверяет реализацию через type assertion в multi-query режиме.

type Chunk ¶

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

Chunk представляет фрагмент документа, полученный в результате чанкинга.

@ds-task T1.2: Добавить поле Metadata в Chunk (DEC-005)

func (c Chunk) Validate() error

type Chunker ¶

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

Chunker определяет интерфейс для разбиения документа на чанки.

type Closer ¶ added in v1.0.0

type Closer interface {
	// Close освобождает ресурсы компонента.
	// После вызова Close компонент не должен использоваться.
	Close() error
}

Closer — опциональная capability для освобождения ресурсов (HTTP-клиенты, соединения). VectorStore/Embedder/LLMProvider могут реализовать этот интерфейс, если они создают собственные ресурсы, требующие явного закрытия.

type CollectionManager ¶

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)
}

CollectionManager — опциональная capability VectorStore для управления жизненным циклом коллекции. Реализации, поддерживающие управление коллекциями, должны реализовывать этот интерфейс дополнительно (без ломки существующего контракта VectorStore).

@ds-task T1.1: Добавить интерфейс CollectionManager в domain (AC-006, DEC-001)

type CostSnapshot ¶ added in v1.0.0

type CostSnapshot struct {
	// PromptTokens — общее количество prompt токенов.
	PromptTokens int64
	// CompletionTokens — общее количество completion токенов.
	CompletionTokens int64
	// TotalTokens — общее количество токенов (prompt + completion).
	TotalTokens int64
	// TotalCost — общая стоимость всех вызовов в USD.
	TotalCost float64
	// CallsCount — количество успешных LLM-вызовов.
	CallsCount int64
}

@sk-task cost-tracking: CostSnapshot для снапшота статистики (AC-003, RQ-003, RQ-007) CostSnapshot — атомарный срез накопленной статистики cost tracker'а.

func Diff(prev, curr CostSnapshot) CostSnapshot

type Document ¶

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

Document представляет документ для индексации в RAG-системе.

func (d Document) Validate() error

type DocumentStore ¶

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

DocumentStore — опциональная capability VectorStore для удаления документа целиком по ParentID.

type Embedder ¶

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

	// Health проверяет доступность embedder'а.
	// Возвращает nil если компонент работает, error с описанием проблемы если нет.
	Health(ctx context.Context) error
}

@sk-task health-check-interface#T1.1: Добавлен Health(ctx) в Embedder (AC-002, RQ-001) Embedder определяет интерфейс для преобразования текста в векторное представление.

type Embedding ¶

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

Embedding представляет векторное представление текста.

type Handler ¶ added in v1.0.0

type Handler func(ctx context.Context, data StageData) (StageData, error)

Handler — обработчик стадии pipeline. Получает контекст и StageData, возвращает (возможно модифицированные) данные и ошибку.

@sk-task middleware-chain#T1.1: Handler type (AC-001, AC-004)

type HookStage ¶

type HookStage string

HookStage описывает стадию выполнения pipeline, которую можно наблюдать через Hooks.

const (
	// HookStageChunking — разбиение документа на чанки (только при наличии Chunker).
	HookStageChunking HookStage = "chunking"
	// HookStageEmbed — генерация embedding для текста.
	HookStageEmbed HookStage = "embed"
	// HookStageSearch — поиск в VectorStore.
	HookStageSearch HookStage = "search"
	// HookStageGenerate — генерация ответа LLM.
	HookStageGenerate HookStage = "generate"
	// HookStageRateLimit — ожидание rate limiter'а (token bucket).
	// @sk-task rate-limiting-llm#T0.1: HookStageRateLimit (AC-001, RQ-007)
	HookStageRateLimit HookStage = "rate_limit"
)

type Hooks ¶

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

Hooks — опциональный интерфейс наблюдаемости для pipeline стадий.

Hooks вызываются синхронно: обработчики ДОЛЖНЫ быть лёгкими и быстрыми. При nil hooks pipeline работает как обычно (no-op).

StageStart возвращает context.Context, который может содержать span или другие инструментационные данные, пробрасываемые в StageEnd.

@sk-task arch-quality-pass#T1.2: StageStart returns context.Context (AC-001)

type HybridConfig ¶

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
}

HybridConfig задаёт параметры гибридного поиска (BM25 + semantic).

func DefaultHybridConfig() HybridConfig

func (c HybridConfig) Validate() error

type HybridSearcher ¶

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

HybridSearcher определяет capability для хранилищ, поддерживающих гибридный поиск (BM25 + semantic).

type HybridSearcherWithFilters ¶

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)
}

HybridSearcherWithFilters расширяет HybridSearcher фильтрами для гибридного поиска.

type IndexBatchError ¶

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

IndexBatchError представляет ошибку индексации конкретного документа.

@ds-task T1.1: Добавить тип IndexBatchError для идентификации failed документов (AC-003)

type IndexBatchResult ¶

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

IndexBatchResult содержит результат batch-индексации документов.

@ds-task T1.1: Добавить тип IndexBatchResult для возврата результатов batch-индексации (AC-003, AC-004)

type InlineCitation ¶

type InlineCitation struct {
	Number int
	Chunk  RetrievedChunk
}

InlineCitation задаёт детерминированный маппинг номера цитаты (используется как `[n]`) на конкретный retrieval-источник (чанк + score).

Нумерация начинается с 1 и соответствует порядку источников в prompt.

type LLMProvider ¶

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

	// Health проверяет доступность LLM провайдера.
	// Возвращает nil если компонент работает, error с описанием проблемы если нет.
	Health(ctx context.Context) error
}

@sk-task health-check-interface#T1.1: Добавлен Health(ctx) в LLMProvider (AC-003, RQ-001) LLMProvider определяет интерфейс для генерации текста через LLM.

type LogField ¶

type LogField struct {
	Key   string
	Value any
}

LogField — структурированное поле лог-события.

type LogLevel ¶

type LogLevel string

LogLevel — уровень логирования.

const (
	LogLevelDebug LogLevel = "debug"
	LogLevelInfo  LogLevel = "info"
	LogLevelWarn  LogLevel = "warn"
	LogLevelError LogLevel = "error"
)

type Logger ¶

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

Logger — минимальный интерфейс структурированного логирования.

Реализация должна быть thread-safe. Любые ошибки/паники логгера не должны ломать основной поток библиотеки: вызывайте логгер через SafeLog.

func NoopLogger() Logger

type Message ¶ added in v1.0.0

type Message struct {
	// Role — отправитель: "user" или "assistant".
	Role string

	// Content — текст сообщения.
	Content string
}

Message представляет одно сообщение в истории диалога.

type MetadataFilter ¶

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

MetadataFilter задаёт условие точного совпадения по полям метаданных документа при поиске. Пустой Fields (nil или len==0) означает «без фильтра» — поведение идентично поиску без фильтра. Все условия применяются как AND: все пары ключ-значение из Fields должны совпасть.

@ds-task T1.1: Добавить тип MetadataFilter в domain (RQ-001, DEC-001)

type Middleware ¶ added in v1.0.0

type Middleware func(next Handler) Handler

Middleware — функциональный тип для обёртки Handler. Каждая middleware получает следующий Handler и должна вызвать его для продолжения цепочки. Может модифицировать StageData до/после next.

@sk-task middleware-chain#T1.1: Middleware type (AC-001, AC-004)

type ModelPricing ¶ added in v1.0.0

type ModelPricing struct {
	// InputCostPer1K — стоимость за 1K input (prompt) токенов в USD.
	InputCostPer1K float64
	// OutputCostPer1K — стоимость за 1K output (completion) токенов в USD.
	OutputCostPer1K float64
}

@sk-task cost-tracking: ModelPricing для расчёта стоимости (AC-002, RQ-002) ModelPricing задаёт цены за 1K токенов для модели.

type PIIDetector ¶ added in v1.0.0

type PIIDetector interface {
	// Detect возвращает текст с заменёнными PII-вхождениями.
	// Если PII не обнаружено, возвращает исходный текст без изменений.
	Detect(text string) string
}

@sk-task pii-guardrails#T1.1: PIIDetector interface (RQ-004, AC-005)

PIIDetector определяет интерфейс для обнаружения и цензурирования персональных данных (PII) в тексте.

type ParentDocumentStore ¶ added in v1.0.0

type ParentDocumentStore interface {
	// UpsertParent сохраняет или обновляет родительский документ с его embedding'ом.
	UpsertParent(ctx context.Context, doc Document, embedding []float64) error

	// GetParentDocument загружает родительский документ по его ID.
	// Возвращает (nil, nil) если документ не найден.
	GetParentDocument(ctx context.Context, parentID string) (*Document, error)

	// DeleteParent удаляет родительский документ по ID.
	// Idempotent: повторный вызов для несуществующего ID возвращает nil.
	DeleteParent(ctx context.Context, parentID string) error
}

@sk-task hierarchical-indices#T1.1: ParentDocumentStore optional capability (AC-001, DEC-001, DEC-002, DM-002) ParentDocumentStore — опциональная capability интерфейса VectorStore для хранения и загрузки родительских документов (parent-сущностей) отдельно от чанков.

Parent-документ сохраняется при индексации и загружается при retrieval, чтобы предоставить LLM полный контекст исходного документа.

Реализации, поддерживающие родительские документы, должны реализовать этот интерфейс дополнительно (без ломки существующего контракта VectorStore).

type ParentIDFilter ¶

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

ParentIDFilter задаёт фильтрацию retrieval по ParentID (например, в пределах одного документа).

type Query ¶

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

Query представляет пользовательский запрос для поиска.

func (q Query) Validate() error

type QueryDecomposer ¶ added in v1.0.0

type QueryDecomposer interface {
	// Decompose разбивает запрос на независимые под-вопросы.
	// Возвращает nil или пустой срез, если декомпозиция не требуется.
	// Ошибка не фатальна — pipeline логирует и использует исходный запрос.
	Decompose(ctx context.Context, query string) ([]string, error)
}

@sk-task sub-query-decomposition#T1.1: QueryDecomposer interface (AC-001, AC-006) QueryDecomposer — опциональный компонент для разбиения запроса на под-вопросы.

Реализации могут быть LLM-based (через LLMProvider) или rule-based. Возвращает список под-вопросов для параллельного retrieval. Пустой или nil результат означает «декомпозиция не нужна» — pipeline выполняет single-query.

type QueryHistory ¶ added in v1.0.0

type QueryHistory struct {
	Entries []Message
}

QueryHistory содержит историю предыдущих сообщений диалога для multi-turn контекста.

Caller управляет жизненным циклом и размером истории. Pipeline не хранит, не обрезает и не персистирует QueryHistory.

type QueryRewriter ¶ added in v1.0.0

type QueryRewriter interface {
	// Rewrite переписывает запрос с учётом истории диалога.
	// Возвращает одну или несколько переформулировок.
	// При пустом результате (nil или len==0) pipeline использует исходный запрос.
	// Ошибка не фатальна — pipeline логирует и использует исходный запрос.
	Rewrite(ctx context.Context, query string, history QueryHistory) ([]RewrittenQuery, error)
}

@sk-task query-rewriting#T1.1: QueryRewriter interface (AC-001) QueryRewriter — опциональный компонент для переписывания запроса перед retrieval.

Реализации могут быть LLM-based (через LLMProvider), rule-based или гибридными. Поддерживает два режима: 1:1 (одна переформулировка) и 1:N (несколько переформулировок).

type Reranker ¶

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

Reranker — опциональная capability для переранжирования результатов retrieval. Принимает исходный вопрос и список чанков, возвращает переупорядоченный список. Типичные реализации: cross-encoder, Cohere Rerank, LLM-based scoring.

type RetrievalResult ¶

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

RetrievalResult содержит результаты поиска по запросу.

type RetrievedChunk ¶

type RetrievedChunk struct {
	Chunk         Chunk
	Score         float64
	ParentContent string
}

@sk-task hierarchical-indices#T1.2: ParentContent field on RetrievedChunk (AC-001, DM-001)

RetrievedChunk представляет чанк с оценкой релевантности в результате поиска. ParentContent содержит полный текст родительского документа (пустая строка, если parent недоступен: store не поддерживает или ParentContextEnabled=false).

type RewrittenQuery ¶ added in v1.0.0

type RewrittenQuery struct {
	// Query — переписанный текст запроса.
	Query string

	// Weight — вес при fusion (0 — эквивалентно 1.0).
	// Зарезервировано для weighted fusion в будущем.
	Weight float64
}

RewrittenQuery представляет результат переформулировки запроса.

type StageData ¶ added in v1.0.0

type StageData struct {
	Stage     HookStage
	Operation string
	Query     string
	Document  Document
	Embedding []float64
	Chunks    []RetrievedChunk
	Answer    string
}

StageData — единая структура данных, передаваемая через middleware-цепочку. Поля заполняются в зависимости от стадии (Stage):

• chunking: Document
• embed: Query (текст для эмбеддинга)
• search: Query, Embedding, Chunks (результат)
• generate: Query, Chunks, Answer (результат)

@sk-task middleware-chain#T1.1: StageData struct (AC-001, AC-003, AC-004)

type StageEndEvent ¶

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

StageEndEvent — событие завершения стадии pipeline.

type StageStartEvent ¶

type StageStartEvent struct {
	Operation string
	Stage     HookStage
}

StageStartEvent — событие начала стадии pipeline.

type StreamingLLMProvider ¶

type StreamingLLMProvider interface {
	LLMProvider

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

StreamingLLMProvider — опциональная capability интерфейса LLMProvider.

Реализации, которые поддерживают streaming, должны реализовать этот интерфейс дополнительно (без ломки существующего контракта LLMProvider).

@ds-task T1.1: Добавить StreamingLLMProvider интерфейс (DEC-001, AC-004)

type TokenUsage ¶ added in v1.0.0

type TokenUsage struct {
	// PromptTokens — количество токенов во входном сообщении (system + user).
	PromptTokens int64
	// CompletionTokens — количество токенов в сгенерированном ответе.
	CompletionTokens int64
	// TotalTokens — общее количество токенов (может не совпадать с суммой,
	// если API возвращает только суммарное значение).
	TotalTokens int64
}

@sk-task cost-tracking: TokenUsage для cost tracking (AC-001, RQ-001) TokenUsage содержит количество токенов, использованных в одном LLM-вызове.

type ToolCall ¶ added in v1.0.0

type ToolCall struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

@sk-task arch-issues#T1.1: ToolCall для tool calling (AC-003, AC-004) ToolCall представляет вызов инструмента от LLM.

type ToolCallingLLMProvider ¶ added in v1.0.0

type ToolCallingLLMProvider interface {
	LLMProvider

	// GenerateWithTools генерирует ответ с возможностью вызова инструментов.
	// Возвращает текст ответа и список вызовов инструментов (если LLM решила их вызвать).
	GenerateWithTools(ctx context.Context, systemPrompt, userMessage string, tools []ToolDefinition) (string, []ToolCall, error)
}

@sk-task arch-issues#T4.1: ToolCallingLLMProvider — optional capability для LLMProvider (AC-003) ToolCallingLLMProvider — опциональная capability интерфейса LLMProvider.

Реализации, поддерживающие tool calling (function calling), должны реализовать этот интерфейс дополнительно (без ломки существующего контракта LLMProvider).

type ToolDefinition ¶ added in v1.0.0

type ToolDefinition struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
}

@sk-task arch-issues#T1.1: ToolDefinition для tool calling (AC-003, AC-004) ToolDefinition описывает инструмент для LLM tool calling.

type ToolResult ¶ added in v1.0.0

type ToolResult struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	Result string `json:"result"`
}

@sk-task arch-issues#T1.1: ToolResult для tool calling (AC-003, AC-004) ToolResult представляет результат выполнения инструмента.

type TransactionalDocumentStore ¶ added in v0.2.0

type TransactionalDocumentStore interface {
	// BeginTx открывает новую транзакцию.
	// Возвращает ошибку, если транзакция не может быть начата.
	BeginTx(ctx context.Context) (TransactionalTx, error)
}

TransactionalDocumentStore — опциональная capability VectorStore, поддерживающая транзакционные операции для атомарного UpdateDocument.

Реализации, поддерживающие транзакции (например, pgvector через *sql.Tx), реализуют этот интерфейс дополнительно к DocumentStore. Pipeline при наличии capability использует транзакционный путь; иначе — best-effort path с возвратом ErrUpdateNotAtomic при сбое после успешного delete.

@sk-task api-consistency-pass#T1.1: новый optional capability для atomic UpdateDocument (RQ-005, AC-008)

type TransactionalTx ¶ added in v0.2.0

type TransactionalTx interface {
	// DeleteByParentID удаляет все чанки с указанным ParentID в транзакции.
	DeleteByParentID(ctx context.Context, parentID string) error
	// Upsert сохраняет или обновляет чанк в транзакции.
	Upsert(ctx context.Context, chunk Chunk) error
	// Commit фиксирует все изменения, сделанные в транзакции.
	Commit() error
	// Rollback откатывает все изменения, сделанные в транзакции.
	Rollback() error
}

TransactionalTx — транзакция в транзакционном vector store.

Контракт:

• DeleteByParentID и Upsert работают в контексте открытой транзакции; изменения видимы только после Commit.
• При ошибке любого метода (или явном Rollback) все изменения откатываются.
• Методы НЕ ДОЛЖНЫ вызываться после Commit/Rollback — поведение зависит от реализации.

@sk-task api-consistency-pass#T1.1: интерфейс для атомарного UpdateDocument (RQ-005, AC-008)

type UsageAwareLLMProvider ¶ added in v1.0.0

type UsageAwareLLMProvider interface {
	LLMProvider

	// GenerateWithUsage генерирует ответ и возвращает token usage.
	GenerateWithUsage(ctx context.Context, systemPrompt, userMessage string) (string, TokenUsage, error)

	// ModelName возвращает имя модели (например, "gpt-4o", "claude-3-haiku-20240307").
	ModelName() string
}

@sk-task cost-tracking: UsageAwareLLMProvider — optional capability для LLMProvider (AC-001, RQ-001) UsageAwareLLMProvider — опциональная capability интерфейса LLMProvider.

Реализации, которые могут возвращать token usage из API-ответа, должны реализовать этот интерфейс дополнительно (без ломки существующего контракта LLMProvider).

@sk-task cost-tracking: GenerateWithUsage возвращает token usage (AC-001, RQ-001)

type UsageAwareStreamingLLMProvider ¶ added in v1.0.0

type UsageAwareStreamingLLMProvider interface {
	StreamingLLMProvider

	// StreamUsage возвращает token usage последнего streaming-вызова.
	// Должен вызываться после полного чтения канала GenerateStream.
	// Возвращает (TokenUsage{}, false) если usage недоступен.
	StreamUsage() (TokenUsage, bool)
}

@sk-task cost-tracking: UsageAwareStreamingLLMProvider — optional capability для streaming (AC-005, RQ-006, T3.4) UsageAwareStreamingLLMProvider — опциональная capability интерфейса StreamingLLMProvider.

Реализации, которые поддерживают streaming и могут возвращать token usage из финального chunk SSE-потока, должны реализовать этот интерфейс дополнительно (без ломки существующего контракта StreamingLLMProvider).

StreamUsage ДОЛЖЕН вызываться только после полного потребления канала из GenerateStream. Возвращает TokenUsage и true, если usage доступен.

type VectorStore ¶

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)

	// Health проверяет доступность хранилища.
	// Возвращает nil если компонент работает, error с описанием проблемы если нет.
	Health(ctx context.Context) error
}

@sk-task health-check-interface#T1.1: Добавлен Health(ctx) в VectorStore (AC-001, RQ-001) VectorStore определяет интерфейс для работы с векторным хранилищем. Реализации должны поддерживать операции upsert, delete и поиска по embedding-вектору.

type VectorStoreWithFilters ¶

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)
}

VectorStoreWithFilters — опциональная capability интерфейса VectorStore.

Реализации, которые поддерживают фильтры, должны реализовать этот интерфейс дополнительно (без ломки существующего контракта VectorStore).

@ds-task T1.3: Расширить VectorStoreWithFilters методом SearchWithMetadataFilter (RQ-002, DEC-001)