Summary of Conversation Dynamics (SCD)

SCD (Summary of Conversation Dynamics) is a ConvoKit Transformer that generates summaries of conversational dynamics from conversation transcripts, as introduced in the paper “How did we get here? Summarizing conversation dynamics”.

SCD extracts structured representations of conversation dynamics in two forms:

• Summary of Conversation Dynamics (SCD): A summary describing the overall dynamics in a conversation

• Sequence of Patterns (SoP): A structured sequence of interaction patterns extracted from the SCD, introduced in the paper “A Similarity Measure for Comparing Conversational Dynamics”

Note that SCD computation requires access to a LLM. We provide a unified interface for working with LLMs in the GenAI module. It is recommended to setup for GenAI models in the module beforehand to compute SCD.

Usage Examples

To see the use of SCD Transformer in action, check out:

• Simple example notebook showcasing basic SCD usage.

Module Reference

class convokit.convo_similarity.scd.SCD(model_provider: str, config, model: str = None, custom_scd_prompt: str = None, custom_sop_prompt: str = None, custom_prompt_dir: str = None, generate_scd: bool = True, generate_sop: bool = True, scd_metadata_name: str = 'machine_scd', sop_metadata_name: str = 'machine_sop', conversation_formatter: Optional[Callable[[convokit.model.conversation.Conversation], str]] = None, llm_kwargs: Optional[dict] = None)

A ConvoKit Transformer that generates Summary of Conversation Dynamics (SCD) and Sequence of Patterns (SoP) for conversations in a corpus through a LLM.

This transformer takes a corpus and generates SCD and/or SoP for selected conversations, storing the results as metadata on the conversations.

Prompt Templates: - SCD prompt: Uses {formatted_output} placeholder for the conversation transcript - SoP prompt: Uses {formatted_output} placeholder for the SCD summary

Parameters

• model_provider – The LLM provider to use (e.g., “gpt”, “gemini”)

• config – The GenAIConfigManager instance to use for LLM configuration

• model – Optional specific model name

• custom_scd_prompt – Custom text for the SCD prompt template. Should include {formatted_output} placeholder for the conversation transcript.

• custom_sop_prompt – Custom text for the SoP prompt template. Should include {formatted_output} placeholder for the SCD summary.

• custom_prompt_dir – Directory to save custom prompts

• generate_scd – Whether to generate SCD summaries (default: True)

• generate_sop – Whether to generate SoP patterns (default: True)

• scd_metadata_name – Name for the SCD metadata field (default: “machine_scd”)

• sop_metadata_name – Name for the SoP metadata field (default: “machine_sop”)

• conversation_formatter – Optional function to format conversations for processing. Should take a Conversation object and return a string. If None, uses default formatting.

• llm_kwargs – Additional keyword arguments to pass to the LLM client

load_custom_prompts_from_directory(prompt_dir: str)

Load custom prompts from a specified directory.

set_custom_scd_prompt(prompt_text: str, save_to_file: bool = True)

Set a custom SCD prompt template.

set_custom_sop_prompt(prompt_text: str, save_to_file: bool = True)

Set a custom SoP prompt template.

transform(corpus: convokit.model.corpus.Corpus, selector: Callable[[convokit.model.conversation.Conversation], bool] = <function SCD.<lambda>>) → convokit.model.corpus.Corpus

Transform the corpus by generating SCD and/or SoP for selected conversations.

Parameters

• corpus – The target corpus

• selector – A function that takes a Conversation object and returns True/False to determine which conversations to process. By default, processes all conversations.

Returns

The modified corpus with SCD/SoP metadata added to conversations