semantic_router.text.Conversation#

class semantic_router.text.Conversation(*, messages: List[Message] = None, topics: List[Tuple[int, str]] = [], splitter: ConsecutiveSimSplitter | CumulativeSimSplitter | None = None)#

Bases: BaseModel

__init__(**data: Any) → None#

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Methods

__init__(**data)

Create a new model by parsing and validating input data from keyword arguments.

add_new_messages(new_messages)

Adds new messages to the conversation.

append_new_topics(new_topics, start)

Appends new topics to the list of topics with unique IDs.

configure_splitter(encoder[, threshold, ...])

Configures the splitter for the conversation based on the specified method.

construct([_fields_set])

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data.

copy(*[, include, exclude, update, deep])

Duplicate a model, optionally choose which fields to include, exclude and change.

determine_topic_start_index(new_topics, ...)

Determines the starting index for new topics based on existing topics and the last message.

dict(*[, include, exclude, by_alias, ...])

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

from_orm(obj)

get_last_message_and_topic_id()

Retrieves the last message and its corresponding topic ID from the list of topics.

json(*[, include, exclude, by_alias, ...])

Generate a JSON representation of the model, include and exclude arguments as per dict().

parse_file(path, *[, content_type, ...])

parse_obj(obj)

parse_raw(b, *[, content_type, encoding, ...])

remove_topics()

schema([by_alias, ref_template])

schema_json(*[, by_alias, ref_template])

split_by_topic([force])

Splits the messages into topics based on their semantic similarity.

update_forward_refs(**localns)

Try to update ForwardRefs on fields based on this Model, globalns and localns.

validate(value)

Attributes

messages

topics

splitter

add_new_messages(new_messages: List[Message])#

Adds new messages to the conversation.

Parameters:

messages (List[Message]) – The new messages to be added to the conversation.

append_new_topics(new_topics, start) → None#

Appends new topics to the list of topics with unique IDs.

This method takes a list of new topics generated by the splitter and appends them to the existing list of topics, ensuring each topic is assigned a unique ID starting from the specified starting index.

Parameters:

  • new_topics (List[DocumentSplit]) – The list of new topics generated by the splitter.

  • start (int) – The starting index for new topics.

configure_splitter(encoder: BaseEncoder, threshold: float = 0.5, split_method: Literal['consecutive_similarity', 'cumulative_similarity'] = 'consecutive_similarity')#

Configures the splitter for the conversation based on the specified method.

This method sets the splitter attribute of the Conversation class to an instance of the appropriate splitter class, based on the split_method parameter. It uses the provided encoder and similarity threshold to initialize the splitter.

Parameters:

  • encoder (BaseEncoder) – The encoder to be used by the splitter for encoding messages.

  • threshold (float) – The similarity threshold to be used by the splitter. Defaults to 0.5.

  • split_method (Literal["consecutive_similarity", "cumulative_similarity"]) – The method to be used for splitting the conversation into topics. Can be one of “consecutive_similarity” or “cumulative_similarity”. Defaults to “consecutive_similarity”.

Raises:

ValueError – If an invalid split method is provided.

classmethod construct(_fields_set: SetStr | None = None, **values: Any) → Model#

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: DictStrAny | None = None, deep: bool = False) → Model#

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:

  • include – fields to include in new model

  • exclude – fields to exclude from new model, as with values this takes precedence over include

  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data

  • deep – set to True to make a deep copy of the model

Returns:

new model instance

determine_topic_start_index(new_topics, last_topic_id, last_message)#

Determines the starting index for new topics based on existing topics and the last message.

Parameters:

  • new_topics (List[DocumentSplit]) – The list of new topics generated by the splitter.

  • last_topic_id (int, optional) – The topic ID of the last message from the previous splitting.

  • last_message (str, optional) – The last message from the previous splitting.

Returns:

The starting index for new topics.

Return type:

int

dict(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, by_alias: bool = False, skip_defaults: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → DictStrAny#

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

get_last_message_and_topic_id()#

Retrieves the last message and its corresponding topic ID from the list of topics.

This method scans the list of topics, if any, and returns the topic ID and message of the last entry. If there are no topics, it returns None for both the topic ID and message.

The last message from a previous spiltting is useful because it can be passed to the splitter along with new messages, and if the first new message is assigned the same topic as the last message, then we know that the new message should continue with the same topic ID as the last message.

Returns:

A tuple containing the topic ID (int) and message (str) of the last topic, or (None, None) if there are no topics.

Return type:

tuple[int | None, str | None]

json(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, by_alias: bool = False, skip_defaults: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = None, models_as_dict: bool = True, **dumps_kwargs: Any) → str#

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

split_by_topic(force: bool = False) → Tuple[List[Tuple[int, str]], List[DocumentSplit]]#

Splits the messages into topics based on their semantic similarity.

This method processes unclustered messages, splits them into topics using the configured splitter, and appends the new topics to the existing list of topics with unique IDs. It ensures that messages belonging to the same topic are grouped together, even if they were not processed in the same batch.

Raises:

ValueError – If the splitter is not configured before calling this method.

Returns:

A tuple containing the updated list of topics and the list of new topics generated in this call.

Return type:

tuple[List[tuple[int, str]], List[DocumentSplit]]

classmethod update_forward_refs(**localns: Any) → None#

Try to update ForwardRefs on fields based on this Model, globalns and localns.