FiD RAG Method

rankify.generator.rag_methods.fid_rag_method

BaseRAGModel

Bases: ABC

Base RAG Model for Retrieval-Augmented Generation (RAG).

This is an abstract base class for implementing LLM endpoints in rankify. It defines the interface for generating responses and optional embedding generation.

Methods:

Name	Description
generate	str, **kwargs) -> str: Abstract method to generate a response based on the given prompt.
embed	str, **kwargs) -> List[float]: Optional method to generate embeddings for the given text.

Notes

• This class serves as a blueprint for RAG models like OpenAIModel and HuggingFaceModel.
• The embed method is optional and can be implemented if needed.
• This class needs to be extended to include new LLM endpoints in Rankify.

Source code in rankify/generator/models/base_rag_model.py

class BaseRAGModel(ABC):
    """
    **Base RAG Model** for Retrieval-Augmented Generation (RAG).

    This is an abstract base class for implementing LLM endpoints in rankify. 
    It defines the interface for generating responses and optional embedding generation.

    Methods:
        generate(prompt: str, **kwargs) -> str:
            Abstract method to generate a response based on the given prompt.
        embed(text: str, **kwargs) -> List[float]:
            Optional method to generate embeddings for the given text.

    Notes:
        - This class serves as a blueprint for RAG models like `OpenAIModel` and `HuggingFaceModel`.
        - The `embed` method is optional and can be implemented if needed.
        - This class needs to be extended to include new LLM endpoints in Rankify.
    """

    @abstractmethod
    def generate(self, prompt: str, **kwargs) -> str:
        """Generate a response based on the given prompt."""
        pass

    def embed(self, text: str, **kwargs) -> List[float]:
        """Optional: Generate embeddings for the given text."""
        raise NotImplementedError("Embedding is not required for this implementation.")

generate(prompt, **kwargs) abstractmethod

Generate a response based on the given prompt.

Source code in rankify/generator/models/base_rag_model.py

@abstractmethod
def generate(self, prompt: str, **kwargs) -> str:
    """Generate a response based on the given prompt."""
    pass

embed(text, **kwargs)

Optional: Generate embeddings for the given text.

Source code in rankify/generator/models/base_rag_model.py

def embed(self, text: str, **kwargs) -> List[float]:
    """Optional: Generate embeddings for the given text."""
    raise NotImplementedError("Embedding is not required for this implementation.")

Document

Represents a document consisting of a question, answers, and contexts.

Attributes:

Name	Type	Description
question	Question	The question associated with the document.
answers	Answer	The answers to the question.
contexts	list[Context]	A list of related contexts.
reorder_contexts	list[Context] or None	A reordered list of contexts based on relevance.

Source code in rankify/dataset/dataset.py

class Document:
    """
    Represents a document consisting of a question, answers, and contexts.

    Attributes:
        question (Question): The question associated with the document.
        answers (Answer): The answers to the question.
        contexts (list[Context]): A list of related contexts.
        reorder_contexts (list[Context] or None): A reordered list of contexts based on relevance.
    """
    def __init__(self, question: Question, answers: Answer, contexts: list = None , id: int = None) -> None:
        """
        Initializes a Document instance.

        Args:
            question (Question): The question associated with the document.
            answers (Answer): The answers to the question.
            contexts (list[Context], optional): A list of contexts related to the question.

        Example:
            ```python
            q = Question("What is the capital of France?")
            a = Answer(["Paris"])
            c1 = Context(score=0.9, has_answer=True, id=1, title="Paris", text="The capital of France is Paris.")
            c2 = Context(score=0.5, has_answer=False, id=2, title="Berlin", text="Berlin is the capital of Germany.")
            d = Document(question=q, answers=a, contexts=[c1, c2])
            print(d)
            ```
        """
        self.question: Question = question
        self.answers: Answer = answers
        self.contexts: List[Context] = contexts
        self.reorder_contexts: List[Context] = None
        self.id = str(id) 

    @classmethod
    def from_dict(cls, data: dict,n_docs:int=100) -> 'Document':
        """
        Creates a Document instance from a dictionary.

        Args:
            data (dict): A dictionary containing the question, answers, and contexts.
            n_docs (int, optional): The number of contexts to include. Defaults to 100.

        Returns:
            Document: A new Document instance.

        Example:
            ```python
            data = {
                "question": "What is the capital of France?",
                "answers": ["Paris"],
                "ctxs": [
                    {"score": 0.9, "has_answer": True, "id": 1, "title": "Paris", "text": "The capital of France is Paris."},
                    {"score": 0.5, "has_answer": False, "id": 2, "title": "Berlin", "text": "Berlin is the capital of Germany."}
                ]
            }
            d = Document.from_dict(data)
            print(d.question)
            ```
        """
        question = Question(data["question"])
        if "answers" in data:
            answers = Answer(data["answers"])
        else:
            answers =Answer('')

        if "query_id" in data:
            id = data["query_id"]
        else:
            id = None
        contexts = [Context(**ctx) for ctx in data["ctxs"][:n_docs]]
        return cls(question, answers, contexts, id=id)

    def to_dict(self) -> Dict[str, Optional[object]]:
        """
        Converts the document into a dictionary representation.

        Returns:
            dict: A dictionary containing the question, answers, and contexts.
        """
        return {
            "question": self.question.question,
            "answers": self.answers.answers,
            "contexts": [ctx.to_dict() for ctx in self.contexts]
        }
    def to_dict_reoreder(self) -> Dict[str,Optional[object]]:
        return {
            "question" : self.question.question,
            "answers" : self.answers.answers,
            "contexts" : [ctx.to_dict() for ctx in self.reorder_contexts]
        }
    def __str__(self) -> str:
        """
        Returns a string representation of the Document instance.

        Returns:
            str: The formatted document information.

        Example:
            ```python
            d = Document(Question("What is the capital of France?"), Answer(["Paris"]))
            print(d)
            ```
        """
        contexts_str = "\n\n".join([str(ctx) for ctx in self.contexts])
        reorder_contexts_str= ''
        if self.reorder_contexts is not None:
            reorder_contexts_str = "\n\n".join([str(ctx) for ctx in self.reorder_contexts])
        return f"{self.question}\n\n{self.answers}\n\nContext: \n\n{contexts_str}\nReorder contexts: \n\n{reorder_contexts_str}"

__init__(question, answers, contexts=None, id=None)

Initializes a Document instance.

Parameters:

Name	Type	Description	Default
question	Question	The question associated with the document.	required
answers	Answer	The answers to the question.	required
contexts	list[Context]	A list of contexts related to the question.	None

Example

q = Question("What is the capital of France?")
a = Answer(["Paris"])
c1 = Context(score=0.9, has_answer=True, id=1, title="Paris", text="The capital of France is Paris.")
c2 = Context(score=0.5, has_answer=False, id=2, title="Berlin", text="Berlin is the capital of Germany.")
d = Document(question=q, answers=a, contexts=[c1, c2])
print(d)

Source code in rankify/dataset/dataset.py

def __init__(self, question: Question, answers: Answer, contexts: list = None , id: int = None) -> None:
    """
    Initializes a Document instance.

    Args:
        question (Question): The question associated with the document.
        answers (Answer): The answers to the question.
        contexts (list[Context], optional): A list of contexts related to the question.

    Example:
        ```python
        q = Question("What is the capital of France?")
        a = Answer(["Paris"])
        c1 = Context(score=0.9, has_answer=True, id=1, title="Paris", text="The capital of France is Paris.")
        c2 = Context(score=0.5, has_answer=False, id=2, title="Berlin", text="Berlin is the capital of Germany.")
        d = Document(question=q, answers=a, contexts=[c1, c2])
        print(d)
        ```
    """
    self.question: Question = question
    self.answers: Answer = answers
    self.contexts: List[Context] = contexts
    self.reorder_contexts: List[Context] = None
    self.id = str(id) 

from_dict(data, n_docs=100) classmethod

Creates a Document instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	A dictionary containing the question, answers, and contexts.	required
n_docs	int	The number of contexts to include. Defaults to 100.	100

Returns:

Name	Type	Description
Document	Document	A new Document instance.

Example

data = {
    "question": "What is the capital of France?",
    "answers": ["Paris"],
    "ctxs": [
        {"score": 0.9, "has_answer": True, "id": 1, "title": "Paris", "text": "The capital of France is Paris."},
        {"score": 0.5, "has_answer": False, "id": 2, "title": "Berlin", "text": "Berlin is the capital of Germany."}
    ]
}
d = Document.from_dict(data)
print(d.question)

Source code in rankify/dataset/dataset.py

@classmethod
def from_dict(cls, data: dict,n_docs:int=100) -> 'Document':
    """
    Creates a Document instance from a dictionary.

    Args:
        data (dict): A dictionary containing the question, answers, and contexts.
        n_docs (int, optional): The number of contexts to include. Defaults to 100.

    Returns:
        Document: A new Document instance.

    Example:
        ```python
        data = {
            "question": "What is the capital of France?",
            "answers": ["Paris"],
            "ctxs": [
                {"score": 0.9, "has_answer": True, "id": 1, "title": "Paris", "text": "The capital of France is Paris."},
                {"score": 0.5, "has_answer": False, "id": 2, "title": "Berlin", "text": "Berlin is the capital of Germany."}
            ]
        }
        d = Document.from_dict(data)
        print(d.question)
        ```
    """
    question = Question(data["question"])
    if "answers" in data:
        answers = Answer(data["answers"])
    else:
        answers =Answer('')

    if "query_id" in data:
        id = data["query_id"]
    else:
        id = None
    contexts = [Context(**ctx) for ctx in data["ctxs"][:n_docs]]
    return cls(question, answers, contexts, id=id)

to_dict()

Converts the document into a dictionary representation.

Returns:

Name	Type	Description
dict	Dict[str, Optional[object]]	A dictionary containing the question, answers, and contexts.

Source code in rankify/dataset/dataset.py

def to_dict(self) -> Dict[str, Optional[object]]:
    """
    Converts the document into a dictionary representation.

    Returns:
        dict: A dictionary containing the question, answers, and contexts.
    """
    return {
        "question": self.question.question,
        "answers": self.answers.answers,
        "contexts": [ctx.to_dict() for ctx in self.contexts]
    }

__str__()

Returns a string representation of the Document instance.

Returns:

Name	Type	Description
str	str	The formatted document information.

Example

d = Document(Question("What is the capital of France?"), Answer(["Paris"]))
print(d)

Source code in rankify/dataset/dataset.py

def __str__(self) -> str:
    """
    Returns a string representation of the Document instance.

    Returns:
        str: The formatted document information.

    Example:
        ```python
        d = Document(Question("What is the capital of France?"), Answer(["Paris"]))
        print(d)
        ```
    """
    contexts_str = "\n\n".join([str(ctx) for ctx in self.contexts])
    reorder_contexts_str= ''
    if self.reorder_contexts is not None:
        reorder_contexts_str = "\n\n".join([str(ctx) for ctx in self.reorder_contexts])
    return f"{self.question}\n\n{self.answers}\n\nContext: \n\n{contexts_str}\nReorder contexts: \n\n{reorder_contexts_str}"

BaseRAGMethod

Bases: ABC

Base RAG Method for Retrieval-Augmented Generation (RAG) techniques.

This abstract base class defines the blueprint for implementing RAG methods in Rankify. Each RAG method (e.g., zero-shot, chain-of-thought, Fusion-in-Decoder) should inherit from this class and implement the logic for answering questions using a provided RAG model.

Attributes:

Name	Type	Description
model	BaseRAGModel	The RAG model instance used for generation.

Methods:

Name	Description
answer_questions	List[Document], custom_prompt=None, **kwargs) -> List[str]: Abstract method to answer questions based on a list of documents and optional custom prompt.

Notes

• Extend this class to implement new RAG techniques or strategies.
• The answer_questions method must be implemented by all subclasses.
• This class enables modularity and extensibility for different retrieval-augmented generation approaches.

Source code in rankify/generator/rag_methods/base_rag_method.py

class BaseRAGMethod(ABC):
    """
    **Base RAG Method** for Retrieval-Augmented Generation (RAG) techniques.

    This abstract base class defines the blueprint for implementing RAG methods in Rankify.
    Each RAG method (e.g., zero-shot, chain-of-thought, Fusion-in-Decoder) should inherit from this class
    and implement the logic for answering questions using a provided RAG model.

    Attributes:
        model (BaseRAGModel): The RAG model instance used for generation.

    Methods:
        answer_questions(documents: List[Document], custom_prompt=None, **kwargs) -> List[str]:
            Abstract method to answer questions based on a list of documents and optional custom prompt.

    Notes:
        - Extend this class to implement new RAG techniques or strategies.
        - The `answer_questions` method must be implemented by all subclasses.
        - This class enables modularity and extensibility for different retrieval-augmented generation approaches.
    """
    def __init__(self, model: BaseRAGModel, **kwargs):
        """
        Initialize the BaseRAGMethod.

        Args:
            model (BaseRAGModel): The RAG model instance used for generation.
            **kwargs: Additional configuration parameters for the RAG method.
        """
        self.model = model

    @abstractmethod
    def answer_questions(self, documents: List[Document], custom_prompt=None, **kwargs) -> List[str]:
        """
        Abstract method to answer questions based on a list of documents.

        Args:
            documents (List[Document]): List of Document objects containing questions and contexts.
            custom_prompt (str, optional): Custom prompt to override default prompt generation.
            **kwargs: Additional parameters for the answering logic.

        Returns:
            List[str]: List of generated answers, one per document.

        Notes:
            - Must be implemented by subclasses to define the RAG technique's answering logic.
            - Enables flexible integration of different prompting or generation strategies.
        """
        pass

__init__(model, **kwargs)

Initialize the BaseRAGMethod.

Parameters:

Name	Type	Description	Default
model	BaseRAGModel	The RAG model instance used for generation.	required
**kwargs		Additional configuration parameters for the RAG method.	{}

Source code in rankify/generator/rag_methods/base_rag_method.py

def __init__(self, model: BaseRAGModel, **kwargs):
    """
    Initialize the BaseRAGMethod.

    Args:
        model (BaseRAGModel): The RAG model instance used for generation.
        **kwargs: Additional configuration parameters for the RAG method.
    """
    self.model = model

answer_questions(documents, custom_prompt=None, **kwargs) abstractmethod

Abstract method to answer questions based on a list of documents.

Parameters:

Name	Type	Description	Default
documents	List[Document]	List of Document objects containing questions and contexts.	required
custom_prompt	str	Custom prompt to override default prompt generation.	None
**kwargs		Additional parameters for the answering logic.	{}

Returns:

Type	Description
List[str]	List[str]: List of generated answers, one per document.

Notes

• Must be implemented by subclasses to define the RAG technique's answering logic.
• Enables flexible integration of different prompting or generation strategies.

Source code in rankify/generator/rag_methods/base_rag_method.py

@abstractmethod
def answer_questions(self, documents: List[Document], custom_prompt=None, **kwargs) -> List[str]:
    """
    Abstract method to answer questions based on a list of documents.

    Args:
        documents (List[Document]): List of Document objects containing questions and contexts.
        custom_prompt (str, optional): Custom prompt to override default prompt generation.
        **kwargs: Additional parameters for the answering logic.

    Returns:
        List[str]: List of generated answers, one per document.

    Notes:
        - Must be implemented by subclasses to define the RAG technique's answering logic.
        - Enables flexible integration of different prompting or generation strategies.
    """
    pass

FiDRAGMethod

Bases: BaseRAGMethod

FiD RAG Method for Open-Domain Question Answering.

This class implements a retrieval-augmented generation (RAG) method using the Fusion-in-Decoder (FiD) approach. The FiD model aggregates information from multiple retrieved passages to generate context-aware answers.

References

• Izacard & Grave Leveraging Passage Retrieval with Generative Models for Open-Domain QA
  Paper

Attributes:

Name	Type	Description
model	BaseRAGModel	The underlying FiD model used for text generation.

Methods:

Name	Description
answer_questions	List[Document], **kwargs) -> List[str]: Generates answers for a list of documents using the FiD model.

See Also

• FiDModel: Class for FiDModel, containing the FiD specific logic.

Example

from rankify.dataset.dataset import Document, Question, Answer, Context
from rankify.generator.generator import Generator

# Define question and answer
question = Question("What is the capital of France?")
answers = Answer([""])
contexts = [
    Context(id=1, title="France", text="The capital of France is Paris.", score=0.9),
    Context(id=2, title="Germany", text="Berlin is the capital of Germany.", score=0.5)
]

# Construct document
doc = Document(question=question, answers=answers, contexts=contexts)

# Initialize Generator (e.g., Meta Llama)
generator = Generator(method="fid", model_name='nq_reader_base', backend="fid")

# Generate answer
generated_answers = generator.generate([doc])
print(generated_answers)  # Output: ["Paris"]

Notes

• This class was created to keep the unified interface of RAG methods.
• Since FiD is a specific RAG technique that relies on the full transformer architecture, the logic is included in the model, see

Source code in rankify/generator/rag_methods/fid_rag_method.py

class FiDRAGMethod(BaseRAGMethod):
    """
    **FiD RAG Method** for Open-Domain Question Answering.

    This class implements a retrieval-augmented generation (RAG) method using the 
    Fusion-in-Decoder (FiD) approach. The FiD model aggregates information from 
    multiple retrieved passages to generate context-aware answers.

    References:
        - **Izacard & Grave** *Leveraging Passage Retrieval with Generative Models for Open-Domain QA*  
          [Paper](https://arxiv.org/abs/2007.01282)

    Attributes:
        model (BaseRAGModel): The underlying FiD model used for text generation.

    Methods:
        answer_questions(documents: List[Document], **kwargs) -> List[str]:
            Generates answers for a list of documents using the FiD model.

    See Also:
        - `FiDModel`: Class for FiDModel, containing the FiD specific logic.

    Example:
        ```python
        from rankify.dataset.dataset import Document, Question, Answer, Context
        from rankify.generator.generator import Generator

        # Define question and answer
        question = Question("What is the capital of France?")
        answers = Answer([""])
        contexts = [
            Context(id=1, title="France", text="The capital of France is Paris.", score=0.9),
            Context(id=2, title="Germany", text="Berlin is the capital of Germany.", score=0.5)
        ]

        # Construct document
        doc = Document(question=question, answers=answers, contexts=contexts)

        # Initialize Generator (e.g., Meta Llama)
        generator = Generator(method="fid", model_name='nq_reader_base', backend="fid")

        # Generate answer
        generated_answers = generator.generate([doc])
        print(generated_answers)  # Output: ["Paris"]
        ```

    Notes:
        - This class was created to keep the unified interface of RAG methods.
        - Since FiD is a specific RAG technique that relies on the full transformer architecture,
          the logic is included in the model, see 

    """
    def __init__(self, model: BaseRAGModel, **kwargs):
        super().__init__(model=model)

    def answer_questions(self, documents: List[Document], custom_prompt=None, **kwargs) -> List[str]:
        """
        Answer questions for a list of documents using the FiDModel.

        Args:
            documents (List[Document]): A list of Document objects containing questions and contexts.

        Returns:
            Lists[str]: An answer based on the given documents and question.
        """

        # Generate the answer using the model
        answer = self.model.generate(documents, **kwargs)

        return answer

answer_questions(documents, custom_prompt=None, **kwargs)

Answer questions for a list of documents using the FiDModel.

Parameters:

Name	Type	Description	Default
documents	List[Document]	A list of Document objects containing questions and contexts.	required

Returns:

Type	Description
List[str]	Lists[str]: An answer based on the given documents and question.

Source code in rankify/generator/rag_methods/fid_rag_method.py

def answer_questions(self, documents: List[Document], custom_prompt=None, **kwargs) -> List[str]:
    """
    Answer questions for a list of documents using the FiDModel.

    Args:
        documents (List[Document]): A list of Document objects containing questions and contexts.

    Returns:
        Lists[str]: An answer based on the given documents and question.
    """

    # Generate the answer using the model
    answer = self.model.generate(documents, **kwargs)

    return answer