Interface IRetriever<T>

Namespace

AiDotNet.Interfaces

Assembly

AiDotNet.dll

Defines the contract for retrieving relevant documents based on a query.

public interface IRetriever<T>

Type Parameters

T

The numeric data type used for relevance scoring.

Remarks

A retriever finds the most relevant documents for a given query using various retrieval strategies such as dense vector search, sparse keyword matching, or hybrid approaches. Implementations can range from simple vector similarity to complex multi-stage retrieval pipelines.

For Beginners: A retriever is like a smart search engine for your documents.

Think of it like different ways to find information:

• Dense retrieval: Understands meaning (finds "automobile" when you search "car")
• Sparse retrieval: Matches keywords (finds exact words you typed)
• Hybrid retrieval: Combines both approaches for best results

When you ask a question, the retriever finds the documents most likely to contain the answer, even if they don't use the exact same words you used.

Properties

DefaultTopK

Gets the default number of documents to retrieve.

int DefaultTopK { get; }

Property Value

int

Remarks

For Beginners: This is how many documents the retriever returns by default.

For example, if DefaultTopK = 5, the retriever will return the 5 most relevant documents unless you specifically ask for a different number.

Methods

Retrieve(string)

Retrieves relevant documents for a given query string using the default TopK value.

IEnumerable<Document<T>> Retrieve(string query)

Parameters

query string

The query text.

Returns

IEnumerable<Document<T>>

A collection of relevant documents ordered by relevance (most relevant first).

Remarks

This method finds documents relevant to the query using the retriever's configured strategy. Documents are returned in descending order of relevance, with the most relevant documents first. The number of results returned equals DefaultTopK.

For Beginners: This searches for documents matching your question.

For example:

• Query: "How do I reset my password?"
• Returns: Top 5 (or DefaultTopK) documents about password reset procedures

The results are sorted so the best match comes first, second-best second, and so on.

Retrieve(string, int)

Retrieves relevant documents with a custom number of results.

IEnumerable<Document<T>> Retrieve(string query, int topK)

Parameters

query string

The query text.

topK int

The number of documents to retrieve.

Returns

IEnumerable<Document<T>>

A collection of relevant documents ordered by relevance (most relevant first).

Remarks

This overload allows specifying a custom number of results to retrieve, overriding the DefaultTopK value. This is useful when different use cases require different numbers of results.

For Beginners: This lets you specify exactly how many results you want.

For example:

• Retrieve("password reset", topK: 3) → Returns 3 documents
• Retrieve("password reset", topK: 10) → Returns 10 documents

Use fewer results (3-5) when you need quick answers. Use more results (10-20) when you want comprehensive information.

Retrieve(string, int, Dictionary<string, object>)

Retrieves relevant documents with metadata filtering.

IEnumerable<Document<T>> Retrieve(string query, int topK, Dictionary<string, object> metadataFilters)

Parameters

query string

The query text.

topK int

The number of documents to retrieve.

metadataFilters Dictionary<string, object>

Metadata filters to apply before retrieval.

Returns

IEnumerable<Document<T>>

A collection of filtered, relevant documents ordered by relevance.

Remarks

This method combines retrieval with metadata filtering, enabling queries that constrain results based on document properties. For example, retrieving only documents from a specific time period, author, or category.

For Beginners: This searches for documents but only looks in a specific subset.

For example:

• Query: "machine learning"
• Filters: { "year": 2024, "category": "research" }
• Returns: Top K papers about machine learning from 2024 in the research category

Think of it like searching in a specific section of a library rather than the whole building.