Speaker

class convokit.model.speaker.Speaker(owner=None, id: str = None, utts=None, convos=None, meta: Optional[Dict] = None, is_ai: Optional[bool] = None, ai_meta: Optional[Dict] = None)

Represents a single speaker in a dataset, which may be a human or an AI agent.

Parameters

  • id (str) – id of the speaker.

  • utts – dictionary of utterances by the speaker, where key is utterance id

  • convos – dictionary of conversations started by the speaker, where key is conversation id

  • meta (dict) – arbitrary dictionary of attributes associated with the speaker. "is_ai" / "ai_meta" entries (as in a dumped corpus) are moved out of meta into the corresponding attributes, unless those arguments are given.

  • is_ai – whether this speaker is known to be an AI agent (default False)

  • ai_meta –

    AI metadata of the speaker (see AI_FORMAT.md). Recognized keys:

    • "config": generation config for this speaker’s messages, used by generate() (see convokit.model.aiGeneration)

    • "role": the speaker’s role in the conversation, e.g. "participant" or "public assistant"

Variables

  • id – id of the speaker.

  • meta – A dictionary-like view object providing read-write access to speaker-level metadata.

  • is_ai – whether this speaker is known to be an AI agent

  • ai_meta – AI metadata of the speaker. Assigning a dict merges it into the existing ai_meta.

add_meta(key: str, value) → None

Adds a key-value pair to the metadata of the corpus object

Parameters

  • key – name of metadata attribute

  • value – value of metadata attribute

Returns

None

add_vector(vector_name: str)

Logs in the Corpus component object’s internal vectors list that the component object has a vector row associated with it in the vector matrix named vector_name.

Transformers that add vectors to the Corpus should use this to update the relevant component objects during the transform() step.

Parameters

vector_name – name of vector matrix

Returns

None

property ai_meta

The AI metadata of this speaker (a copy; assign to modify).

delete_vector(vector_name: str)

Delete a vector associated with this Corpus component object.

Parameters

vector_name –

Returns

None

generate(conversation=None, reply_to: Optional[str] = None, append: bool = False, client=None, config_manager=None, id: Optional[str] = None, timestamp: Optional[int] = None)

Generate an Utterance for this speaker with convokit.genai, using the prompt in ai_meta["config"] (see convokit.model.aiGeneration for the recognized config keys). Requires is_ai to be True.

Example:

speaker = corpus.get_speaker("bot")
utt = speaker.generate(conversation, append=True)
Parameters

  • conversation – if given, the conversation transcript (up to reply_to) is included in the prompt

  • reply_to – id of the utterance to reply to (defaults to the last utterance of conversation)

  • append – whether to add the generated utterance to conversation (and its Corpus)

  • client – a convokit.genai LLMClient to use instead of building one from the config

  • config_manager – GenAIConfigManager used to build the client (defaults to one reading ~/.convokit/config.yml)

  • id – id of the generated utterance (random if not given)

  • timestamp – timestamp of the generated utterance (defaults to after the conversation’s last message)

Returns

the generated Utterance (if append is True, the Utterance as stored in the Corpus)

Raises

ValueError – if the speaker is not an AI speaker, has no "prompt" in ai_meta["config"], or if append is True and no conversation is given

get_conversation(cid: str)

Get the Conversation with the specified Conversation id

Parameters

cid – The id of the Conversation

Returns

A Conversation object

get_conversation_ids(selector=<function Speaker.<lambda>>) → List[str]
Returns

a List of the ids of Conversations started by the speaker

get_conversations_dataframe(selector=<function Speaker.<lambda>>, exclude_meta: bool = False)

Get a DataFrame of the Conversations the Speaker has participated in, with fields and metadata attributes. Set an optional selector that filters for Conversations that should be included. Edits to the DataFrame do not change the corpus in any way.

Parameters

  • exclude_meta – whether to exclude metadata

  • selector – a (lambda) function that takes a Conversation and returns True or False (i.e. include / exclude). By default, the selector includes all Conversations in the Corpus.

Returns

a pandas DataFrame

get_utterance(ut_id: str)

Get the Utterance with the specified Utterance id

Parameters

ut_id – The id of the Utterance

Returns

An Utterance object

get_utterance_ids(selector=<function Speaker.<lambda>>) → List[str]
Returns

a List of the ids of Utterances made by the speaker

get_utterances_dataframe(selector=<function Speaker.<lambda>>, exclude_meta: bool = False)

Get a DataFrame of the Utterances made by the Speaker with fields and metadata attributes. Set an optional selector that filters for Utterances that should be included. Edits to the DataFrame do not change the corpus in any way.

Parameters

  • exclude_meta – whether to exclude metadata

  • selector – a (lambda) function that takes a Utterance and returns True or False (i.e. include / exclude). By default, the selector includes all Utterances in the Corpus.

Returns

a pandas DataFrame

get_vector(vector_name: str, as_dataframe: bool = False, columns: Optional[List[str]] = None)

Get the vector stored as vector_name for this object.

Parameters

  • vector_name – name of vector

  • as_dataframe – whether to return the vector as a dataframe (True) or in its raw array form (False). False by default.

  • columns – optional list of named columns of the vector to include. All columns returned otherwise. This parameter is only used if as_dataframe is set to True

Returns

a numpy / scipy array

property is_ai

Whether this speaker is known to be an AI agent.

iter_conversations(selector=<function Speaker.<lambda>>)
Returns

An iterator of the Conversations that the speaker has participated in

iter_utterances(selector=<function Speaker.<lambda>>)

Get utterances made by the Speaker, with an optional selector that selects for Utterances that should be included.

param selector

a (lambda) function that takes an Utterance and returns True or False (i.e. include / exclude). By default, the selector includes all Utterances in the Corpus.

Returns

An iterator of the Utterances made by the speaker

print_speaker_stats()

Helper function for printing the number of Utterances made and Conversations participated in by the Speaker.

Returns

None (prints output)

retrieve_meta(key: str)

Retrieves a value stored under the key of the metadata of corpus object

Parameters

key – name of metadata attribute

Returns

value