Coverage for haystack/components/retrievers/types/protocol.py: 100%

1# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai> 

2# 

3# SPDX-License-Identifier: Apache-2.0 

4 

5from typing import Any, Protocol 

6 

7 

8class TextRetriever(Protocol): 

9 """ 

10 This protocol defines the minimal interface that all keyword-based BM25 Retrievers must implement. 

11 

12 Retrievers are components that process a query and, based on that query, return relevant documents from a document 

13 store or other data source. They return a dictionary with a list of Document objects. 

14 """ 

15 

16 def run(self, query: str, filters: dict[str, Any] | None = None, top_k: int | None = None) -> dict[str, Any]: 

17 """ 

18 Retrieve documents that are relevant to the query. 

19 

20 Implementing classes may accept additional optional parameters in their run method. 

21 

22 :param query: The input query string. 

23 :param filters: A dictionary of filters to apply when retrieving documents. 

24 :param top_k: The maximum number of documents to return. 

25 

26 :returns: 

27 A dictionary containing: 

28 `documents`: List of retrieved documents sorted by relevance score. 

29 """ 

30 ... 

31 

32 

33class EmbeddingRetriever(Protocol): 

34 """ 

35 This protocol defines the minimal interface that all embedding-based Retrievers must implement. 

36 

37 Retrievers are components that process a query and, based on that query, return relevant documents from a document 

38 store or other data source. They return a dictionary with a list of Document objects. 

39 """ 

40 

41 def run( 

42 self, query_embedding: list[float], filters: dict[str, Any] | None = None, top_k: int | None = None 

43 ) -> dict[str, Any]: 

44 """ 

45 Retrieve documents that are relevant to the query. 

46 

47 Implementing classes may accept additional optional parameters in their run method. 

48 

49 :param query_embedding: The input query embedding. 

50 :param filters: A dictionary of filters to apply when retrieving documents. 

51 :param top_k: The maximum number of documents to return. 

52 :returns: 

53 A dictionary containing: 

54 `documents`: List of retrieved documents sorted by relevance score. 

55 """ 

56 ...