rg.Suggestion

Class for interacting with Argilla Suggestions of records. Suggestions are typically created by a model prediction, unlike a Response which is typically created by a user in the UI or consumed from a data source as a label.

Usage Examples

Adding records with suggestions

Suggestions can be added to a record directly or via a dictionary structure. The following examples demonstrate how to add suggestions to a record object and how to access suggestions from a record object:

Add a response from a dictionary where key is the question name and value is the response:

dataset.records.log(
    [
        {
            "text": "Hello World, how are you?",
            "label": "negative", # this will be used as a suggestion
        },
    ]
)

If your data contains scores for suggestions you can add them as well via the mapping parameter. The following example demonstrates how to add a suggestion with a score to a record object:

dataset.records.log(
    [
        {
            "prompt": "Hello World, how are you?",
            "label": "negative",  # this will be used as a suggestion
            "score": 0.9,  # this will be used as the suggestion score
            "model": "model_name",  # this will be used as the suggestion agent
        },
    ],
    mapping={
        "score": "label.suggestion.score",
        "model": "label.suggestion.agent",
    },  # `label` is the question name in the dataset settings
)

Or, instantiate the Record and related Suggestions objects directly, like this:

dataset.records.log(
    [
        rg.Record(
            fields={"text": "Hello World, how are you?"},
            suggestions=[rg.Suggestion("negative", "label", score=0.9, agent="model_name")],
        )
    ]
)

Iterating over records with suggestions

Just like responses, suggestions can be accessed from a Record via their question name as an attribute of the record. So if a question is named label, the suggestion can be accessed as record.label. The following example demonstrates how to access suggestions from a record object:

for record in dataset.records(with_suggestions=True):
    print(record.suggestions.label)

---

Class Reference

rg.Suggestion

Bases: Resource

Class for interacting with Argilla Suggestions. Suggestions are typically model predictions for records. Suggestions are rendered in the user interfaces as 'hints' or 'suggestions' for the user to review and accept or reject.

Attributes:

Name	Type	Description
value	str	The value of the suggestion.add()
question_name	str	The name of the question that the suggestion is for.
type	str	The type of suggestion, either 'model' or 'human'.
score	float	The score of the suggestion. For example, the probability of the model prediction.
agent	str	The agent that created the suggestion. For example, the model name.
question_id	UUID	The ID of the question that the suggestion is for.

Source code in src/argilla_sdk/suggestions.py

class Suggestion(Resource):
    """Class for interacting with Argilla Suggestions. Suggestions are typically model predictions for records.
    Suggestions are rendered in the user interfaces as 'hints' or 'suggestions' for the user to review and accept or reject.

    Attributes:
        value (str): The value of the suggestion.add()
        question_name (str): The name of the question that the suggestion is for.
        type (str): The type of suggestion, either 'model' or 'human'.
        score (float): The score of the suggestion. For example, the probability of the model prediction.
        agent (str): The agent that created the suggestion. For example, the model name.
        question_id (UUID): The ID of the question that the suggestion is for.

    """

    _model: SuggestionModel

    def __init__(
        self,
        question_name: str,
        value: Any,
        score: Union[float, List[float], None] = None,
        agent: Optional[str] = None,
        type: Optional[Literal["model", "human"]] = None,
        id: Optional[UUID] = None,
        question_id: Optional[UUID] = None,
        _record: Optional["Record"] = None,
    ) -> None:
        super().__init__()

        if question_name is None:
            raise ValueError("question_name is required")
        if value is None:
            raise ValueError("value is required")

        self.record = _record
        self._model = SuggestionModel(
            id=id,
            question_name=question_name,
            question_id=question_id,
            value=value,
            type=type,
            score=score,
            agent=agent,
        )

    ##############################
    # Properties
    ##############################

    @property
    def value(self) -> Any:
        """The value of the suggestion."""
        return self._model.value

    @property
    def question_name(self) -> Optional[str]:
        """The name of the question that the suggestion is for."""
        return self._model.question_name

    @question_name.setter
    def question_name(self, value: str) -> None:
        self._model.question_name = value

    @property
    def question_id(self) -> Optional[UUID]:
        """The ID of the question that the suggestion is for."""
        return self._model.question_id

    @question_id.setter
    def question_id(self, value: UUID) -> None:
        self._model.question_id = value

    @property
    def type(self) -> Optional[Literal["model", "human"]]:
        """The type of suggestion, either 'model' or 'human'."""
        return self._model.type

    @property
    def score(self) -> Optional[Union[float, List[float]]]:
        """The score of the suggestion."""
        return self._model.score

    @score.setter
    def score(self, value: float) -> None:
        self._model.score = value

    @property
    def agent(self) -> Optional[str]:
        """The agent that created the suggestion."""
        return self._model.agent

    @agent.setter
    def agent(self, value: str) -> None:
        self._model.agent = value

    @classmethod
    def from_model(cls, model: SuggestionModel, dataset: "Dataset") -> "Suggestion":
        question = dataset.settings.question_by_id(model.question_id)
        model.question_name = question.name
        model.value = cls.__from_model_value(model.value, question)

        return cls(**model.model_dump())

    def api_model(self) -> SuggestionModel:
        if self.record is None or self.record.dataset is None:
            return self._model

        question = self.record.dataset.settings.question_by_name(self.question_name)
        return SuggestionModel(
            value=self.__to_model_value(self.value, question),
            question_name=self.question_name,
            question_id=self.question_id or question.id,
            type=self._model.type,
            score=self._model.score,
            agent=self._model.agent,
            id=self._model.id,
        )

    @classmethod
    def __to_model_value(cls, value: Any, question: "QuestionType") -> Any:
        if isinstance(question, RankingQuestion):
            return cls.__ranking_to_model_value(value)
        return value

    @classmethod
    def __from_model_value(cls, value: Any, question: "QuestionType") -> Any:
        if isinstance(question, RankingQuestion):
            return cls.__ranking_from_model_value(value)
        return value

    @classmethod
    def __ranking_from_model_value(cls, value: List[Dict[str, Any]]) -> List[str]:
        return [v["value"] for v in value]

    @classmethod
    def __ranking_to_model_value(cls, value: List[str]) -> List[Dict[str, str]]:
        return [{"value": str(v)} for v in value]

agent: Optional[str] property writable

The agent that created the suggestion.

question_id: Optional[UUID] property writable

The ID of the question that the suggestion is for.

question_name: Optional[str] property writable

The name of the question that the suggestion is for.

score: Optional[Union[float, List[float]]] property writable

The score of the suggestion.

type: Optional[Literal['model', 'human']] property

The type of suggestion, either 'model' or 'human'.

value: Any property

The value of the suggestion.