Mythosia.AI.Rag.Abstractions 6.3.0

Mythosia.AI.Rag.Abstractions

v6.3.0: Adds IRagRetriever and RagRetrievalRequest for custom request-based retrieval. Use Mythosia.AI.Rag 8.1.0 for the corresponding builder and pipeline APIs; IRetrievalStrategy remains supported. See the release notes.

Package Summary

Core interfaces and models for the Mythosia.AI RAG ecosystem.
This package defines the contracts that all RAG components implement — you only need this directly if you're building a custom implementation.

Interfaces

Models

Per-Query Overrides via Clone()

RagPipelineOptions, RagQueryOptions, RagFilter, RagRetrievalDerivation, and RagFinalSelectionOptions all expose a Clone() method. Use Clone() to override a single field on top of RagPipelineOptions.DefaultQuery without losing the other configured fields (notably StoreFilter and ProgressAsync):

var options = pipeline.Options.DefaultQuery.Clone();
options.FinalFilter.TopK = 10;
await pipeline.QueryAsync(query, options);

Constructing new RagQueryOptions { FinalFilter = ... } from scratch silently drops every other field, including any tenant/permission scope on StoreFilter and any progress callback on ProgressAsync. Clone() makes the "inherit defaults, override one field" pattern safe.

Custom Implementation Example

Custom implementations must preserve the association between each document, chunk and vector. A splitter returns non-null chunks with nonblank IDs unique across the target store; include the document ID and chunk index, and copy inherited metadata when access filters depend on it. Indexing rejects blank or duplicate chunk IDs within a document before embedding or persistence and does not invent replacement IDs.

An embedding batch returns exactly one vector per input, in input order, with the provider's positive Dimensions and finite values in every coordinate. RAG indexing validates each batch and copies its vectors before asking for another batch. Provider-owned buffers may therefore be reused by a later sequential call; they must remain stable while the caller is reading the current response. A validation failure preserves that document's previous index when it occurs before persistence. See the indexing validation guide for exception types and storage boundaries.

Single query embeddings follow the same dimension and finite-value contract. Built-in vector, hybrid and legacy retrieval adapters validate and copy a completed query vector before invoking retrieval progress callbacks or the store. This keeps a later sequential call from changing an earlier query through a reused provider buffer. Providers must still keep returned data stable while it is being read or copied; custom IRagRetriever implementations own their preparation and validation. Keyword-only retrieval does not inspect or call the embedding provider. See query embedding validation.

public class MyEmbeddingProvider : IEmbeddingProvider
{
    public int Dimensions => 768;

    public Task<float[]> GetEmbeddingAsync(string text, CancellationToken ct = default)
    {
        // Your embedding logic here
    }

    public Task<IReadOnlyList<float[]>> GetEmbeddingsAsync(
        IEnumerable<string> texts, CancellationToken ct = default)
    {
        // Batch embedding logic here
    }
}

Then register via the builder:

.WithRag(rag => rag.UseEmbedding(new MyEmbeddingProvider()))

Custom retrieval without mandatory embeddings

An external search index should not need a dense query embedding merely to connect to RAG. Implement IRagRetriever and register it with RagBuilder.UseRetriever(...). Preparation belongs to the retriever; the rest of the pipeline can still apply reranking and assemble context. Respect the request filter, top-K and cancellation, and return the content and metadata needed downstream. See the custom retriever guide. Existing IRetrievalStrategy implementations remain supported through an embedding adapter. This changes query retrieval, not the document-ingestion contract.