Mythosia.AI.Rag.Abstractions 6.5.0

Mythosia.AI.Rag.Abstractions

v6.5.0: Retains IRagDiagnosticsStore as an obsolete compatibility bridge to Mythosia.VectorDb.IVectorStoreDiagnostics in VectorDb Abstractions 4.2.0. Existing custom diagnostic stores can use the bridge; new stores should implement the vector-layer contract. 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

Diagnostics compatibility

Store inspection belongs to Mythosia.VectorDb.IVectorStoreDiagnostics. RAG analysis belongs to Mythosia.AI.Rag: RagDiagnostics and RagDiagnosticSession use the optional vector-layer capability for chunk lookup, all-record scoring and health checks. Implementing IVectorStore alone does not require diagnostics.

The obsolete IRagDiagnosticsStore keeps its original namespace, assembly and two method declarations (ListAllRecordsAsync, ScoredListAsync), inherits IVectorStoreDiagnostics, and supplies default interface bridges to those legacy methods. This supports existing custom implementations, including explicit implementations of the old members, when used with the updated contracts. New custom stores should implement IVectorStoreDiagnostics directly and can omit a RAG abstractions reference if they otherwise use only vector contracts.

A public class method takes precedence over a default interface bridge. If a legacy store also exposes public methods with those names, a direct call through IVectorStoreDiagnostics can select the public methods. RAG 8.3.0 uses an internal adapter that calls the original IRagDiagnosticsStore slots, preserving explicit legacy behavior in chunk lookup, scoring and health checks.

The bridge does not make InMemory 4.3.0 implement the old interface. Migrate old InMemory assignments, casts and is/as checks to IVectorStoreDiagnostics, then rebuild affected consumers. Upgrade RAG to 8.3.0 together with InMemory 4.3.0; older RAG packages paired with the new InMemory package are unsupported. This is not a guarantee that every previously compiled consumer remains compatible.

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

If a provider needs neighbouring chunks or retrieval-specific input formatting, implement IRetrievalEmbeddingProvider in addition to its inherited generic methods. The pipeline supplies a complete document regardless of EmbeddingBatchSize, then calls the query method for dense retrieval and diagnostics. Existing providers keep their flat batches and generic query calls.

IRetrievalEmbeddingProvider embeddings = retrievalEmbeddingProvider;
var document = new EmbeddingDocument("policy", new[]
{
    "Returns are accepted within fourteen days.",
    "Keep the original receipt."
}, title: "Refund policy");
IReadOnlyList<float[]> chunks = await embeddings.GetDocumentEmbeddingsAsync(
    document, cancellationToken);
float[] query = await embeddings.GetQueryEmbeddingAsync(
    "What is the refund period?", cancellationToken);

Return one finite vector of exactly Dimensions per original chunk in order. Do not mutate the document or returned vectors while the caller copies them. Contextual providers must preserve the complete group; independent providers may manage HTTP batches or bounded concurrency internally. RAG captures the title from RagDocument.Metadata["title"], copies validated results, and preserves source text when a provider adds retrieval formatting to HTTP input. Invalid responses or cancellation before persistence preserve the previous document; store or callback behavior determines atomicity after persistence starts. Reindex when the model, dimensions or retrieval formatting changes. See the provider contract and built-in implementations.

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.