diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 53b7324e..eec0b406 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -21,7 +21,7 @@ jobs: - name: rsync docs uses: burnett01/rsync-deployments@master with: - switches: -vzr + switches: -vzr --chown=":sauna" path: docs/build/ remote_path: ${{ secrets.DEPLOY_DOCS_PATH }} remote_host: ${{ secrets.DEPLOY_HOST }} diff --git a/.github/workflows/rsync-download-config.yml b/.github/workflows/rsync-download-config.yml index 6b018b39..7394a382 100644 --- a/.github/workflows/rsync-download-config.yml +++ b/.github/workflows/rsync-download-config.yml @@ -13,7 +13,7 @@ jobs: - name: rsync download config uses: burnett01/rsync-deployments@master with: - switches: -vzr + switches: -vzr --chown=":sauna" path: download_config.json remote_path: ${{ secrets.BASE_DIRECTORY_PATH }} remote_host: ${{ secrets.DEPLOY_HOST }} diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 43a78385..1d705ee4 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -20,7 +20,7 @@ jobs: - name: rsync homepage files uses: burnett01/rsync-deployments@master with: - switches: -vzr + switches: -vzr --chown=":sauna" path: website/docs/build/ remote_path: ${{ secrets.DEPLOY_WEBSITE_PATH }} remote_host: ${{ secrets.DEPLOY_HOST }} diff --git a/README.md b/README.md index f84bea51..62a3f411 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ [![license](https://img.shields.io/badge/license-MIT-green)](https://github.com/CornellNLP/ConvoKit/blob/master/LICENSE.md) [![Discord Community](https://img.shields.io/static/v1?logo=discord&style=flat&color=red&label=discord&message=community)](https://discord.gg/WMFqMWgz6P) -This toolkit contains tools to extract conversational features and analyze social phenomena in conversations, using a [single unified interface](https://convokit.cornell.edu/documentation/architecture.html) inspired by (and compatible with) scikit-learn. Several large [conversational datasets](https://github.com/CornellNLP/ConvoKit#datasets) are included together with scripts exemplifying the use of the toolkit on these datasets. The latest version is [4.1.0](https://github.com/CornellNLP/ConvoKit/releases/tag/v4.1.0) (released Mar. 10, 2026); follow the [project on GitHub](https://github.com/CornellNLP/ConvoKit) to keep track of updates. +This toolkit contains tools to extract conversational features and analyze social phenomena in conversations, using a [single unified interface](https://convokit.cornell.edu/documentation/architecture.html) inspired by (and compatible with) scikit-learn. Several large [conversational datasets](https://github.com/CornellNLP/ConvoKit#datasets) are included together with scripts exemplifying the use of the toolkit on these datasets. The latest version is [4.1.1](https://github.com/CornellNLP/ConvoKit/releases/tag/v4.1.1) (released May 1, 2026); follow the [project on GitHub](https://github.com/CornellNLP/ConvoKit) to keep track of updates. Join our [Discord community](https://discord.gg/WMFqMWgz6P) to stay informed, connect with fellow developers, and be part of an engaging space where we share progress, discuss features, and tackle issues together. diff --git a/convokit/genai/example/example.ipynb b/convokit/genai/example/example.ipynb index 6fa6fe79..ff038de5 100644 --- a/convokit/genai/example/example.ipynb +++ b/convokit/genai/example/example.ipynb @@ -22,17 +22,19 @@ }, { "cell_type": "code", - "execution_count": 23, + "execution_count": 1, "id": "be24454d", "metadata": {}, "outputs": [], "source": [ - "from convokit.genai.genai_config import GenAIConfigManager" + "from convokit.genai.genai_config import GenAIConfigManager\n", + "config = GenAIConfigManager()\n", + "from convokit.genai import get_llm_client" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 2, "id": "5666dc72", "metadata": {}, "outputs": [ @@ -45,7 +47,6 @@ } ], "source": [ - "config = GenAIConfigManager()\n", "config.set_api_key(\"gpt\", \"YOUR API KEY\")\n", "print(f\"Successfully set OpenAI API key in config.\")" ] @@ -62,13 +63,11 @@ }, { "cell_type": "code", - "execution_count": 25, + "execution_count": null, "id": "220c33fe", "metadata": {}, "outputs": [], "source": [ - "from convokit.genai import get_llm_client\n", - "\n", "MODEL_PROVIDER = \"gpt\"\n", "client = get_llm_client(MODEL_PROVIDER, config)" ] @@ -96,6 +95,95 @@ "print(\"Latency:\", response.latency)" ] }, + { + "cell_type": "markdown", + "id": "417c22b9", + "metadata": {}, + "source": [ + "# Setup ConvoKit GenAI with Google Gemini Through Gemini Developer API" + ] + }, + { + "cell_type": "markdown", + "id": "94aede45", + "metadata": {}, + "source": [ + "Checkout Google Gemini Developer API: https://ai.google.dev/gemini-api/docs/" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0a4c8e31", + "metadata": {}, + "outputs": [], + "source": [ + "MODEL_PROVIDER = \"gemini\"\n", + "MODEL = \"gemini-2.5-flash\"\n", + "config.set_api_key(\"gemini\", \"YOUR API KEY\")" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "88eef33f", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Text: ConvoKit is a powerful Python library designed for the **systematic analysis of conversational data**. It provides a unified framework to represent, transform, and analyze conversations, moving beyond simple text analysis to focus on the rich structure and dynamics inherent in human (and human-like) interactions.\n", + "\n", + "Here's a breakdown of what you can do with ConvoKit:\n", + "\n", + "1. **Represent Conversational Data:**\n", + " * **Standardized Structure:** ConvoKit allows you to load diverse conversational datasets (chat logs, forum posts, emails, transcripts, etc.) into a standardized `Corpus` object, which consists of `Utterance` and `Speaker` objects. This makes it easy to work with different datasets consistently.\n", + " * **Metadata Storage:** You can attach arbitrary metadata to conversations, utterances, and speakers (e.g., speaker demographics, conversation topics, timestamps, sentiment scores).\n", + "\n", + "2. **Preprocess and Enrich Conversational Data:**\n", + " * **Tokenization & Linguistic Features:** Integrate with spaCy to perform tokenization, part-of-speech tagging, named entity recognition, and dependency parsing on utterances.\n", + " * **Sentiment Analysis:** Apply pre-trained sentiment models to utterances to understand emotional tone.\n", + " * **Dialog Act Classification:** Use models to classify the communicative function of an utterance (e.g., question, statement, agreement, disagreement).\n", + " * **Speaker Attributes:** Extract features related to speakers, such as their average utterance length, lexical diversity, or frequency of certain dialog acts.\n", + "\n", + "3. **Analyze Conversational Dynamics and Structure:**\n", + " * **Turn-Taking Patterns:** Investigate how speakers take turns, who initiates conversations, and who responds.\n", + " * **Interaction Networks:** Build and analyze networks of who talks to whom, identifying central speakers or conversational hubs.\n", + " * **Topic Modeling:** Discover latent topics within conversations and track how topics shift over time or across different speakers.\n", + " * **Power and Dominance:** Analyze linguistic cues and interaction patterns that might indicate power dynamics or dominance within a conversation (e.g., interruption patterns, question-asking behavior).\n", + " * **Coherence and Cohesion:** Study how utterances relate to each other to form coherent conversations.\n", + "\n", + "4. **Extract Features for Machine Learning:**\n", + " * **Linguistic Features:** Extract features like word counts, TF-IDF, n-grams, lexical diversity, specific part-of-speech frequencies.\n", + " * **Social Features:** Features related to speaker roles, interaction frequency, or network centrality.\n", + " * **Structural Features:** Features related to turn-taking, utterance position in a conversation, or response time.\n", + " * These features can then be used to train models for tasks like speaker classification, conversation summarization, or predicting conversation outcomes.\n", + "\n", + "5. **Conduct Comparative Studies:**\n", + " * **Compare Groups:** Analyze differences in communication styles, sentiment, or interaction patterns between different groups of speakers (e.g., male vs. female, expert vs. novice, different customer segments).\n", + " * **Compare Contexts:** Study how conversations differ across various contexts (e.g., formal vs. informal, online vs. offline, different platforms).\n", + "\n", + "6. **Specific Use Cases:**\n", + "\n", + " * **Social Science Research:** Studying group dynamics, power structures, communication styles, and social phenomena in online communities, political debates, or interviews.\n", + " * **Customer Service Analytics:** Identifying common customer issues, evaluating agent performance, detecting customer frustration, and optimizing chatbot interactions.\n", + " * **Product Analytics:** Understanding how users interact with a product through chat, forums, or reviews; identifying pain points or feature requests.\n", + " * **Content Moderation:** Detecting toxic language, harassment, or hate speech by analyzing conversational context and patterns, not just isolated words.\n", + " * **Chatbot Development:** Analyzing user input to improve chatbot understanding, evaluating dialog flow, and benchmarking chatbot responses against human conversations.\n", + " * **Digital Humanities:** Analyzing historical texts, interviews, or literary dialogues to uncover linguistic and social insights.\n", + " * **Linguistic Research:** Investigating specific linguistic phenomena, such as politeness strategies, code-switching, or the use of discourse markers in natural conversation.\n", + "\n", + "In essence, ConvoKit empowers researchers and data scientists to move beyond simple text analysis and delve into the rich, structured world of conversations, enabling deeper insights into human communication.\n" + ] + } + ], + "source": [ + "client = get_llm_client(model=MODEL, provider=MODEL_PROVIDER, config_manager=config)\n", + "response = client.generate(\"What can you do with ConvoKit.\")\n", + "print(\"Text:\", response.text)" + ] + }, { "cell_type": "markdown", "id": "33b72969", @@ -114,13 +202,13 @@ "outputs": [], "source": [ "MODEL_PROVIDER = \"gemini\"\n", - "MODEL = \"gemini-2.0-flash-001\"\n", + "MODEL = \"gemini-2.5-flash\"\n", "config.set_google_cloud_config(\"YOUR PROJECT\", \"YOUR LOCATION\")" ] }, { "cell_type": "code", - "execution_count": 28, + "execution_count": null, "id": "32fad57a", "metadata": {}, "outputs": [ @@ -136,7 +224,7 @@ } ], "source": [ - "client = get_llm_client(MODEL_PROVIDER, config)\n", + "client = get_llm_client(model=MODEL, provider=MODEL_PROVIDER, config_manager=config, use_vertex_ai=True)\n", "response = client.generate(\"Tell me a fun fact about Cornell University.\")\n", "print(\"Text:\", response.text)" ] @@ -310,7 +398,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "convokit", "language": "python", "name": "python3" }, @@ -324,7 +412,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.5" + "version": "3.12.11" } }, "nbformat": 4, diff --git a/convokit/genai/gemini_client.py b/convokit/genai/gemini_client.py index 0a6ae42b..dd616acb 100644 --- a/convokit/genai/gemini_client.py +++ b/convokit/genai/gemini_client.py @@ -1,4 +1,3 @@ -import os from google import genai from google.genai.types import GenerateContentConfig, HttpOptions from .base import LLMClient, LLMResponse @@ -7,35 +6,48 @@ class GeminiClient(LLMClient): - """Client for interacting with Google Gemini models via Vertex AI. + """Client for interacting with Google Gemini models. - This client is configured to use Vertex AI and requires Google Cloud project and location - to be set. Configuration can be provided via the GenAI config system or environment variables. + This client uses the Gemini Developer API with an API key by default. If no API key + is configured, or if ``use_vertex_ai`` is set, it falls back to Vertex AI with Google + Cloud project and location configuration. - :param model: Name of the Gemini model to use (default: "gemini-2.0-flash-001") + :param model: Name of the Gemini model to use :param config_manager: GenAIConfigManager instance (optional, will create one if not provided) + :param use_vertex_ai: Force Vertex AI authentication instead of API key authentication """ def __init__( self, - model: str = "gemini-2.0-flash-001", + model: str, config_manager: GenAIConfigManager = None, + use_vertex_ai: bool = False, ): if config_manager is None: config_manager = GenAIConfigManager() self.config_manager = config_manager + self.model = model + + api_key = config_manager.get_api_key("gemini") + if api_key and not use_vertex_ai: + self.client = genai.Client(api_key=api_key) + else: + self.client = self._create_vertex_ai_client(config_manager) - # Get required Vertex AI configuration + @staticmethod + def _create_vertex_ai_client(config_manager: GenAIConfigManager): + """Create a Gemini client authenticated through Vertex AI.""" google_cloud_project = config_manager.get_google_cloud_project() google_cloud_location = config_manager.get_google_cloud_location() - # Validate required fields if not google_cloud_project: raise ValueError( - "Google Cloud project is required for Vertex AI. " - "Set it using config_manager.set_google_cloud_config(project, location) " - "or via GOOGLE_CLOUD_PROJECT environment variable." + "Gemini API key or Google Cloud project is required. " + "Set an API key using config_manager.set_api_key('gemini', 'your-key'), " + "or via GEMINI_API_KEY. For Vertex AI, set project and location using " + "config_manager.set_google_cloud_config(project, location) or via " + "GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION." ) if not google_cloud_location: @@ -45,13 +57,12 @@ def __init__( "or via GOOGLE_CLOUD_LOCATION environment variable." ) - # Set up Vertex AI environment - os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "true" - os.environ["GOOGLE_CLOUD_PROJECT"] = google_cloud_project - os.environ["GOOGLE_CLOUD_LOCATION"] = google_cloud_location - - self.client = genai.Client(http_options=HttpOptions(api_version="v1")) - self.model = model + return genai.Client( + vertexai=True, + project=google_cloud_project, + location=google_cloud_location, + http_options=HttpOptions(api_version="v1"), + ) def generate(self, prompt, temperature=0.0, times_retried=0) -> LLMResponse: """Generate text using the Gemini model. diff --git a/convokit/genai/gpt_client.py b/convokit/genai/gpt_client.py index 91ec8a45..03d82a9e 100644 --- a/convokit/genai/gpt_client.py +++ b/convokit/genai/gpt_client.py @@ -11,11 +11,11 @@ class GPTClient(LLMClient): Handles authentication, request formatting, and error retry logic. API key is managed through the GenAI config system. - :param model: Name of the GPT model to use (default: "gpt-4o-mini") + :param model: Name of the GPT model to use :param config_manager: GenAIConfigManager instance (optional, will create one if not provided) """ - def __init__(self, model: str = "gpt-4o-mini", config_manager: GenAIConfigManager = None): + def __init__(self, model: str, config_manager: GenAIConfigManager = None): if config_manager is None: config_manager = GenAIConfigManager() diff --git a/convokit/util.py b/convokit/util.py index 46e0f67b..365380a0 100644 --- a/convokit/util.py +++ b/convokit/util.py @@ -369,7 +369,7 @@ def _get_wikiconv_year_info(language: str, year: str = None) -> str: # base directory of wikicon corpuses wikiconv_base = "http://zissou.infosci.cornell.edu/convokit/datasets/wikiconv-corpus/" - data_dir = wikiconv_base + "corpus-zipped/" + data_dir = wikiconv_base + "corpus_zipped/" final_dir = ( data_dir + language + "/wikiconv-" + year + "/full.corpus.zip" if year is not None diff --git a/docs/source/conf.py b/docs/source/conf.py index 8639ff4f..9db0c116 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -56,7 +56,7 @@ # General information about the project. project = "convokit" -copyright = "2017-2025 The ConvoKit Developers" +copyright = "2017-2026 The ConvoKit Developers" author = "The ConvoKit Developers" # The version info for the project you're documenting, acts as replacement for @@ -66,7 +66,7 @@ # The short X.Y version. version = "4.1" # The full version, including alpha/beta/rc tags. -release = "4.1.0" +release = "4.1.1" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/genai.rst b/docs/source/genai.rst index 196edcf7..ac2a31e7 100644 --- a/docs/source/genai.rst +++ b/docs/source/genai.rst @@ -40,7 +40,7 @@ Supported Providers Currently supported LLM providers: * **OpenAI GPT**: Access to OpenAI GPT models through the OpenAI API. See `OpenAI API setup `_. -* **Google Gemini**: Access to Google Gemini models via Vertex AI. See `Vertex AI setup guide `_. +* **Google Gemini**: Access to Google Gemini models via the Gemini Developer API by default, or via Vertex AI. See `Gemini API key setup `_ and `Vertex AI setup guide `_. * **Local Models**: Template implementation for local LLM models (requires custom implementation) GPT Client @@ -79,7 +79,7 @@ Configuration The GenAIConfigManager handles API key storage and retrieval for different LLM providers. It supports: * **File-based storage**: Configuration is stored in `~/.convokit/config.yml` -* **Environment variables**: API keys can be set via environment variables (e.g., `GPT_API_KEY`) +* **Environment variables**: API keys can be set via environment variables (e.g., `GPT_API_KEY` or `GEMINI_API_KEY`) * **Secure storage**: API keys are stored locally and not exposed in code * **Provider-specific settings**: Support for different configuration requirements per provider (e.g., Google Cloud project settings for Gemini) @@ -94,7 +94,10 @@ The GenAIConfigManager handles API key storage and retrieval for different LLM p # Set OpenAI API key config.set_api_key("gpt", "your-openai-api-key") - # Set Google Cloud configuration for Gemini + # Set Gemini API key + config.set_api_key("gemini", "your-gemini-api-key") + + # Or set Google Cloud configuration for Gemini on Vertex AI config.set_google_cloud_config("your-project-id", "your-location") # Configuration is automatically saved and can be reused diff --git a/docs/source/index.rst b/docs/source/index.rst index 25467b06..bf3293bf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,7 +9,7 @@ Cornell Conversational Analysis Toolkit (ConvoKit) Documentation This toolkit contains tools to extract conversational features and analyze social phenomena in conversations, using a `single unified interface `_ inspired by (and compatible with) scikit-learn. Several large `conversational datasets `_ are included together with scripts exemplifying the use of the toolkit on these datasets. -More information can be found at our `website `_. The latest version is `4.1.0 `_ (released Mar. 10, 2026). +More information can be found at our `website `_. The latest version is `4.1.1 `_ (released May 1, 2026). Contents -------- diff --git a/docs/source/wikiconv.rst b/docs/source/wikiconv.rst index 5d1d5d13..442cf16f 100644 --- a/docs/source/wikiconv.rst +++ b/docs/source/wikiconv.rst @@ -88,22 +88,22 @@ Combining different years A common use case for the WikiConv corpora might be to combine corpora from different years for further analysis. This is straightforward with the Corpus's merge functionality, which we demonstrate below. >>> from convokit import Corpus, download ->>> wikiconv_2003 = Corpus(filename=download("wikiconv-2003")) ->>> wikiconv_2003.print_summary_stats() -Number of Speakers: 9168 -Number of Utterances: 140265 -Number of Conversations: 91787 ->>> wikiconv_2004 = Corpus(filename=download("wikiconv-2004")) ->>> wikiconv_2004.print_summary_stats() -Number of Speakers: 34235 -Number of Utterances: 613608 -Number of Conversations: 303494 ->>> merged_corpus = wikiconv_2003.merge(wikiconv_2004) +>>> wikiconv_russian_2004 = Corpus(filename=download("wikiconv-russian-2004")) +>>> wikiconv_russian_2004.print_summary_stats() +Number of Speakers: 338 +Number of Utterances: 3723 +Number of Conversations: 1844 +>>> wikiconv_russian_2005 = Corpus(filename=download("wikiconv-russian-2005")) +>>> wikiconv_russian_2005.print_summary_stats() +Number of Speakers: 1657 +Number of Utterances: 23719 +Number of Conversations: 10495 +>>> merged_corpus = Corpus.merge(wikiconv_russian_2004, wikiconv_russian_2005) WARNING: Multiple values found for Speaker([('name', 'TUF-KAT')]) for meta key: user_id. Taking the latest one found >>> merged_corpus.print_summary_stats() -Number of Speakers: 41509 -Number of Utterances: 753873 -Number of Conversations: 392883 +Number of Speakers: 1902 +Number of Utterances: 27442 +Number of Conversations: 12226 Notice that the number of Utterances in the merged corpus is simply the sum of those in the constituent corpora. This is to be expected since the Utterances from these two corpora are from different years and are therefore distinct and non-overlapping. diff --git a/setup.py b/setup.py index 497d1ac2..c38c90c9 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ author_email="cristian@cs.cornell.edu", url="https://github.com/CornellNLP/ConvoKit", description="ConvoKit", - version="4.1.0", + version="4.1.1", packages=[ "convokit", "convokit.bag_of_words", diff --git a/website/docs/source/conf.py b/website/docs/source/conf.py index a2ff886f..717b6bad 100644 --- a/website/docs/source/conf.py +++ b/website/docs/source/conf.py @@ -8,9 +8,9 @@ # -- Project information ----------------------------------------------------- project = "ConvoKit" -copyright = "2025, Cornell NLP" +copyright = "2026, Cornell NLP" author = "Cornell NLP" -release = "4.1.0" +release = "4.1.1" # -- General configuration --------------------------------------------------- extensions = [ diff --git a/website/docs/source/features.rst b/website/docs/source/features.rst index 43881993..84d900d5 100644 --- a/website/docs/source/features.rst +++ b/website/docs/source/features.rst @@ -1,5 +1,5 @@ -Features & APIs -=============== +Tools +===== ConvoKit provides a comprehensive set of analysis tools for extracting conversational features and studying social phenomena. @@ -16,512 +16,512 @@ ConvoKit provides a comprehensive set of analysis tools for extracting conversat
-TextParser ----------- +Bag-of-Words +------------ .. raw:: html -
+
-Dependency-parses each utterance in a corpus using SpaCy. This parsing step is a prerequisite for several other ConvoKit transformers. +Vectorizes corpus objects (utterances, speakers, or conversations) using bag-of-words representations. Compatible with any sklearn-style vectorizer including TF-IDF. Stores representations as ConvoKitMatrix objects for downstream use with classifiers. -* **API:** `TextParser `_ -* **Tags:** pre-processing, parsing, utterance, linguistic +* **Transformer:** `BoWTransformer `_ +* **Tags:** feature extraction, vectorization, speaker, utterance, conversation -**Example:** `Text Preprocessing `_ +**Example:** `Bag-of-Words classification `_ .. raw:: html
-TextToArcs +Classifier ---------- .. raw:: html -
+
-Converts dependency parse output into arc-based representations, where each sentence is expressed as a collection of dependency arc strings. Requires TextParser to be run first. +Trains and applies a classifier on corpus object metadata features. Uses an sklearn-compatible classifier and exposes evaluation utilities including cross-validation and train-test split scoring. -* **API:** `TextToArcs `_ -* **Tags:** pre-processing, structural, parsing, utterance, linguistic, pattern +* **Transformer:** `Classifier `_ +* **Tags:** classification, modeling, utterance, conversation, speaker, labeling + +**Example:** `Politeness `_ .. raw:: html
-TextCleaner ------------ +Column Normalized Tf-Idf +------------------------ .. raw:: html -
+
-Cleans utterance text by fixing unicode errors, lowercasing, removing line breaks, and replacing URLs, emails, phone numbers, and currency symbols with special tokens. Supports custom cleaning functions. +A modified Tf-Idf transformer that normalizes by columns (term-wise) rather than rows, producing more balanced term representations across a corpus. Often used as input to the Expected Conversational Context Framework. -* **API:** `TextCleaner `_ -* **Tags:** pre-processing, utterance, linguistic +* **Transformer:** `ColNormedTfidfTransformer `_ +* **Tags:** feature extraction, utterance, representation .. raw:: html
-TextProcessor (base class) --------------------------- +Community Embedder +------------------ .. raw:: html -
- -Abstract base class for text processing transformers in ConvoKit. Provides a shared interface for transformers that read and write utterance text fields, enabling pipeline composition of text processing steps. +
-* **API:** `Transformer (base class) `_ -* **Tags:** pre-processing, utterance, linguistic +Embeds community-level hypergraph statistics from HyperConvo into a low-dimensional space, enabling comparison and visualization of structural differences across communities or subreddits. -**Example:** `Text Preprocessing `_ +* **Transformer:** `CommunityEmbedder `_ +* **Research:** `Patterns of Participant Interactions `_ +* **Tags:** measurement, feature extraction, statistical, corpus, pattern .. raw:: html
-Bag-of-Words ------------- +Conversation Dynamics Similarity (ConDynS) +------------------------------------------- .. raw:: html -
- -Vectorizes corpus objects (utterances, speakers, or conversations) using bag-of-words representations. Compatible with any sklearn-style vectorizer including TF-IDF. Stores representations as ConvoKitMatrix objects for downstream use with classifiers. +
-* **API:** `BoWTransformer `_ -* **Tags:** feature extraction, vectorization, speaker, utterance, conversation +Measures the similarity between two conversations with respect to their conversational dynamics using SCD-based representations and sequence alignment. Enables topic-independent comparison of how conversations unfold. -**Example:** `Bag-of-Words classification `_ +* **Transformer:** `ConvoDynamicsSimilarity `_ +* **Research:** `A Similarity Measure for Comparing Conversational Dynamics `_ +* **Tags:** measurement, feature extraction, LLM, corpus, pattern, conversation-flow, context, comparison .. raw:: html
-Column Normalized Tf-Idf ------------------------- +Expected Conversational Context Framework +------------------------------------------ .. raw:: html -
+
-A modified Tf-Idf transformer that normalizes by columns (term-wise) rather than rows, producing more balanced term representations across a corpus. Often used as input to the Expected Conversational Context Framework. +Derives representations of utterances and terms based on their expected conversational context — the replies they tend to elicit or the utterances they tend to appear near. Supports both forward and backward context modeling. -* **API:** `ColNormedTfidfTransformer `_ -* **Tags:** feature extraction, utterance, representation +* **Transformer:** `ExpectedContextModel `_ +* **Research:** `Expected Context Framework `_ +* **Tags:** structural, modeling, utterance, exchange, linguistic, context + +**Examples:** + +* `Question types in British Parliament `_ +* `Switchboard Corpus `_ +* `Wikipedia discussions `_ .. raw:: html
-Hypergraph Conversation Representation ---------------------------------------- +Fighting Words +-------------- .. raw:: html -
+
-Extracts structural features of conversations through a hypergraph model, computing degree distribution statistics and motif counts for both full conversations and mid-threads. Forms the basis for ThreadEmbedder and CommunityEmbedder. +Identifies the n-gram features that most distinguish two groups of corpus objects, using Monroe et al.'s Dirichlet-multinomial method. Annotates objects with the top fighting words of each class. -* **API:** `HyperConvo `_ -* **Research:** `Patterns of Participant Interactions `_ -* **Tags:** structural, graph, conversation, pattern +* **Transformer:** `FightingWords `_ +* **Tags:** measurement, statistical, utterance, conversation, speaker, power, influence, social, pattern, comparison -**Example:** `Reddit hypergraph analysis `_ +**Examples:** `r/atheism vs r/Christianity `_ .. raw:: html
-Phrasing Motifs ---------------- +Forecaster +---------- .. raw:: html -
+
-Extracts arc-based phrasing patterns from dependency-parsed utterances by abstracting away content words, capturing common syntactic structures independently of topic. Used as input to the Prompt Types framework. +A framework for forecasting future conversation outcomes as they develop in real time. Wraps any ForecasterModel (e.g. CRAFT, BERT-based models) and feeds a chronological stream of context tuples to enable per-utterance prediction. -* **API:** `PhrasingMotifs `_ -* **Research:** `Asking Too Much? `_ -* **Tags:** feature extraction, utterance, linguistic, pragmatics +* **Transformer:** `Forecaster `_ +* **Research:** `Trouble on the Horizon `_ +* **Tags:** prediction, machine learning, neural, utterance, forecasting, LLM -**Example:** `Phrasing motifs in prompt type models `_ +**Example:** `CRAFT on CGA `_ .. raw:: html
-Politeness Strategies ---------------------- +Hypergraph Conversation Representation +--------------------------------------- .. raw:: html -
+
-Detects lexical and parse-based politeness and impoliteness strategies in utterances based on the Brown and Levinson politeness framework, producing binary feature vectors over a set of validated linguistic markers. +Extracts structural features of conversations through a hypergraph model, computing degree distribution statistics and motif counts for both full conversations and mid-threads. Forms the basis for ThreadEmbedder and CommunityEmbedder. -* **API:** `PolitenessStrategies `_ -* **Research:** `A Computational Approach to Politeness `_ -* **Tags:** measurement, statistical, conversation, linguistic, social, politeness, pragmatics +* **Transformer:** `HyperConvo `_ +* **Research:** `Patterns of Participant Interactions `_ +* **Tags:** structural, graph, conversation, pattern -**Example:** `Extracting politeness features and markers `_ +**Example:** `Reddit hypergraph analysis `_ .. raw:: html
-Prompt Types ------------- +Linguistic Coordination +----------------------- .. raw:: html -
- -Infers latent types of conversational prompts based on how they are phrased, using SVD-based embeddings of phrasing motifs relative to their response contexts. Assigns each utterance a prompt type and vector representation. +
-* **API:** `PromptTypes `_ -* **Research:** `Asking Too Much? `_ -* **Tags:** feature extraction, vectorization, utterance, context, pragmatics +Measures the propensity of a speaker to echo the function words used by another speaker in a conversation, serving as a proxy for linguistic coordination and relative power dynamics between individuals or groups. -**Examples:** +* **Transformer:** `Coordination `_ +* **Research:** `Echoes of Power `_ +* **Tags:** measurement, statistical, conversation, linguistic, power, influence -* `Prompt Type Wrapper `_ -* `Phrasing and rhetorical intent `_ +**Example:** `Power balance in U.S. Supreme Court `_ .. raw:: html
-Expected Conversational Context Framework ------------------------------------------- +Linguistic Diversity +-------------------- .. raw:: html -
- -Derives representations of utterances and terms based on their expected conversational context — the replies they tend to elicit or the utterances they tend to appear near. Supports both forward and backward context modeling. +
-* **API:** `ExpectedContextModel `_ -* **Research:** `Expected Context Framework `_ -* **Tags:** structural, modeling, utterance, exchange, linguistic, context +Computes the linguistic divergence between a speaker's language in each conversation and a reference language model trained on other conversations or speakers, measuring how a speaker's voice develops over time. -**Examples:** +* **Transformer:** `SpeakerConvoDiversity `_ +* **Research:** `Finding Your Voice `_ +* **Tags:** measurement, statistical, speaker, corpus, diversity, development -* `Question types in British Parliament `_ -* `Switchboard Corpus `_ -* `Wikipedia discussions `_ +**Example:** `Linguistic diversity on ChangeMyView `_ .. raw:: html
-Redirection and Utterance Likelihood -------------------------------------- +LLM Prompt Transformer +----------------------- .. raw:: html -
+
-Measures the extent to which an utterance redirects conversational flow away from its context, and computes utterance log-likelihoods given surrounding context using a language model. +Applies custom LLM prompts to corpus objects at any level — utterances, conversations, speakers, or the entire corpus — and stores responses as metadata. Supports multiple LLM providers including OpenAI GPT, Google Gemini, and local models. -* **API:** `Redirection and UtteranceLikelihood `_ -* **Research:** `Conversational Redirection in Therapy `_ -* **Tags:** structural, modeling, utterance, exchange, conversation-flow, detection, LLM, simulation +* **Transformer:** `LLMPromptTransformer `_ +* **Tags:** feature extraction, utterance, conversation, speaker, corpus, pragmatics -**Example:** `Redirection in Supreme Court `_ +**Example:** `GenAI module `_ .. raw:: html
-Pivotal Moment Measure ------------------------ +Pairer +------ .. raw:: html -
- -Identifies pivotal moments in a conversation where simulated alternative responses would most change the predicted outcome. Combines a simulator model and a forecaster model to score each conversational position. +
-* **API:** `PivotalMomentMeasure `_ -* **Tags:** prediction, modeling, conversation, turning-points, simulation +Annotates corpus objects with pairing information needed for paired prediction analyses. Controls for conversational context by pairing objects from the same conversation, enabling comparisons that isolate the variable of interest. -**Example:** `Pivotal moments in conversations gone awry `_ +* **Transformer:** `Pairer `_ +* **Tags:** pre-processing, prediction, statistical, utterance, conversation, speaker, representation, pattern .. raw:: html
-LLM Prompt Transformer ------------------------ +Paired Prediction +----------------- .. raw:: html -
+
-Applies custom LLM prompts to corpus objects at any level — utterances, conversations, speakers, or the entire corpus — and stores responses as metadata. Supports multiple LLM providers including OpenAI GPT, Google Gemini, and local models. +A quasi-experimental prediction method that controls for confounding priors by comparing matched pairs of corpus objects from the same conversation, enabling more rigorous causal inference. -* **API:** `LLMPromptTransformer `_ -* **Tags:** feature extraction, utterance, conversation, speaker, corpus, pragmatics +* **Transformer:** `PairedPrediction `_ +* **Research:** `Antisocial Behavior in Online Discussion Communities `_ +* **Tags:** prediction, classification, machine learning, corpus, detection -**Example:** `GenAI module `_ +**Example:** `Predicting conversation growth on Reddit `_ .. raw:: html
-Classifier ----------- +Phrasing Motifs +--------------- .. raw:: html -
+
-Trains and applies a classifier on corpus object metadata features. Uses an sklearn-compatible classifier and exposes evaluation utilities including cross-validation and train-test split scoring. +Extracts arc-based phrasing patterns from dependency-parsed utterances by abstracting away content words, capturing common syntactic structures independently of topic. Used as input to the Prompt Types framework. -* **API:** `Classifier `_ -* **Tags:** classification, modeling, utterance, conversation, speaker, labeling +* **Transformer:** `PhrasingMotifs `_ +* **Research:** `Asking Too Much? `_ +* **Tags:** feature extraction, utterance, linguistic, pragmatics -**Example:** `Politeness `_ +**Example:** `Phrasing motifs in prompt type models `_ .. raw:: html
-Vector Classifier ------------------ +Pivotal Moment Measure +----------------------- .. raw:: html -
+
-Trains and applies a classifier on corpus object vector representations (e.g. bag-of-words, TF-IDF). Inherits from Classifier. Requires a ConvoKitMatrix with the specified vector name to be present on the corpus. +Identifies pivotal moments in a conversation where simulated alternative responses would most change the predicted outcome. Combines a simulator model and a forecaster model to score each conversational position. -* **API:** `VectorClassifier `_ -* **Tags:** classification, modeling, vectorization, utterance, conversation, speaker, labeling +* **Transformer:** `PivotalMomentMeasure `_ +* **Tags:** prediction, modeling, conversation, turning-points, simulation -**Example:** `Bag-of-Words classification `_ +**Example:** `Pivotal moments in conversations gone awry `_ .. raw:: html
-Linguistic Coordination ------------------------ +Politeness Strategies +--------------------- .. raw:: html -
+
-Measures the propensity of a speaker to echo the function words used by another speaker in a conversation, serving as a proxy for linguistic coordination and relative power dynamics between individuals or groups. +Detects lexical and parse-based politeness and impoliteness strategies in utterances based on the Brown and Levinson politeness framework, producing binary feature vectors over a set of validated linguistic markers. -* **API:** `Coordination `_ -* **Research:** `Echoes of Power `_ -* **Tags:** measurement, statistical, conversation, linguistic, power, influence +* **Transformer:** `PolitenessStrategies `_ +* **Research:** `A Computational Approach to Politeness `_ +* **Tags:** measurement, statistical, conversation, linguistic, social, politeness, pragmatics -**Example:** `Power balance in U.S. Supreme Court `_ +**Example:** `Extracting politeness features and markers `_ .. raw:: html
-Fighting Words --------------- +Prompt Types +------------ .. raw:: html -
+
-Identifies the n-gram features that most distinguish two groups of corpus objects, using Monroe et al.'s Dirichlet-multinomial method. Annotates objects with the top fighting words of each class. +Infers latent types of conversational prompts based on how they are phrased, using SVD-based embeddings of phrasing motifs relative to their response contexts. Assigns each utterance a prompt type and vector representation. -* **API:** `FightingWords `_ -* **Tags:** measurement, statistical, utterance, conversation, speaker, power, influence, social, pattern, comparison +* **Transformer:** `PromptTypes `_ +* **Research:** `Asking Too Much? `_ +* **Tags:** feature extraction, vectorization, utterance, context, pragmatics -**Examples:** `r/atheism vs r/Christianity `_ +**Examples:** + +* `Prompt Type Wrapper `_ +* `Phrasing and rhetorical intent `_ .. raw:: html
-Forecaster ----------- +Ranker +------ .. raw:: html -
+
-A framework for forecasting future conversation outcomes as they develop in real time. Wraps any ForecasterModel (e.g. CRAFT, BERT-based models) and feeds a chronological stream of context tuples to enable per-utterance prediction. +Sorts and annotates corpus objects with rankings based on a user-defined scoring function. Supports ranking of utterances, speakers, or conversations by any derived or metadata feature. -* **API:** `Forecaster `_ -* **Research:** `Trouble on the Horizon `_ -* **Tags:** prediction, machine learning, neural, utterance, forecasting, LLM +* **Transformer:** `Ranker `_ +* **Tags:** sorting, statistical, utterance, conversation, speaker, representation -**Example:** `CRAFT on CGA `_ +**Example:** `Ranking users in r/Cornell by comment count `_ .. raw:: html
-Thread Embedder ---------------- +Redirection and Utterance Likelihood +------------------------------------- .. raw:: html -
+
-Embeds thread-level hypergraph statistics from HyperConvo into a low-dimensional space using SVD or other dimensionality reduction. Useful for visualizing and comparing thread structure across a corpus. +Measures the extent to which an utterance redirects conversational flow away from its context, and computes utterance log-likelihoods given surrounding context using a language model. -* **API:** `ThreadEmbedder `_ -* **Research:** `Patterns of Participant Interactions `_ -* **Tags:** measurement, feature extraction, statistical, corpus, pattern +* **Transformer:** `Redirection and UtteranceLikelihood `_ +* **Research:** `Conversational Redirection in Therapy `_ +* **Tags:** structural, modeling, utterance, exchange, conversation-flow, detection, LLM, simulation + +**Example:** `Redirection in Supreme Court `_ .. raw:: html
-Community Embedder ------------------- +Summary of Conversation Dynamics (SCD) +--------------------------------------- .. raw:: html -
+
-Embeds community-level hypergraph statistics from HyperConvo into a low-dimensional space, enabling comparison and visualization of structural differences across communities or subreddits. +Generates structured natural-language summaries of conversational dynamics using the LLM Prompt Transformer. Summaries describe how interactions unfold over time, capturing turn-by-turn shifts in tone, topic, and social dynamics. -* **API:** `CommunityEmbedder `_ -* **Research:** `Patterns of Participant Interactions `_ -* **Tags:** measurement, feature extraction, statistical, corpus, pattern +* **Transformer:** `SCD `_ +* **Research:** `How Did We Get Here? Summarizing Conversation Dynamics `_ +* **Tags:** measurement, feature extraction, LLM, corpus, pattern, conversation-flow, context + +**Example:** `SCD on conversations gone awry `_ .. raw:: html
-Pairer ------- +Talk-Time Sharing Dynamics +--------------------------- .. raw:: html -
+
-Annotates corpus objects with pairing information needed for paired prediction analyses. Controls for conversational context by pairing objects from the same conversation, enabling comparisons that isolate the variable of interest. +Analyzes how talk-time is distributed and evolves between speakers throughout a conversation, capturing both overall balance and moment-to-moment dynamics in participation patterns. -* **API:** `Pairer `_ -* **Tags:** pre-processing, prediction, statistical, utterance, conversation, speaker, representation, pattern +* **Transformer:** `TalkTimeSharingDynamics `_ +* **Tags:** measurement, feature extraction, statistical, corpus, pattern, conversation-flow, social, comparison + +**Example:** `Talk-time in CANDOR and Supreme Court `_ .. raw:: html
-Paired Prediction ------------------ +TextCleaner +----------- .. raw:: html -
- -A quasi-experimental prediction method that controls for confounding priors by comparing matched pairs of corpus objects from the same conversation, enabling more rigorous causal inference. +
-* **API:** `PairedPrediction `_ -* **Research:** `Antisocial Behavior in Online Discussion Communities `_ -* **Tags:** prediction, classification, machine learning, corpus, detection +Cleans utterance text by fixing unicode errors, lowercasing, removing line breaks, and replacing URLs, emails, phone numbers, and currency symbols with special tokens. Supports custom cleaning functions. -**Example:** `Predicting conversation growth on Reddit `_ +* **Transformer:** `TextCleaner `_ +* **Tags:** pre-processing, utterance, linguistic .. raw:: html
-Ranker ------- +TextParser +---------- .. raw:: html -
+
-Sorts and annotates corpus objects with rankings based on a user-defined scoring function. Supports ranking of utterances, speakers, or conversations by any derived or metadata feature. +Dependency-parses each utterance in a corpus using SpaCy. This parsing step is a prerequisite for several other ConvoKit transformers. -* **API:** `Ranker `_ -* **Tags:** sorting, statistical, utterance, conversation, speaker, representation +* **Transformer:** `TextParser `_ +* **Tags:** pre-processing, parsing, utterance, linguistic -**Example:** `Ranking users in r/Cornell by comment count `_ +**Example:** `Text Preprocessing `_ .. raw:: html
-Linguistic Diversity --------------------- +TextProcessor (base class) +-------------------------- .. raw:: html -
+
-Computes the linguistic divergence between a speaker's language in each conversation and a reference language model trained on other conversations or speakers, measuring how a speaker's voice develops over time. +Abstract base class for text processing transformers in ConvoKit. Provides a shared interface for transformers that read and write utterance text fields, enabling pipeline composition of text processing steps. -* **API:** `SpeakerConvoDiversity `_ -* **Research:** `Finding Your Voice `_ -* **Tags:** measurement, statistical, speaker, corpus, diversity, development +* **Transformer:** `Transformer (base class) `_ +* **Tags:** pre-processing, utterance, linguistic -**Example:** `Linguistic diversity on ChangeMyView `_ +**Example:** `Text Preprocessing `_ .. raw:: html
-Summary of Conversation Dynamics (SCD) ---------------------------------------- +TextToArcs +---------- .. raw:: html -
- -Generates structured natural-language summaries of conversational dynamics using the LLM Prompt Transformer. Summaries describe how interactions unfold over time, capturing turn-by-turn shifts in tone, topic, and social dynamics. +
-* **API:** `SCD `_ -* **Research:** `How Did We Get Here? Summarizing Conversation Dynamics `_ -* **Tags:** measurement, feature extraction, LLM, corpus, pattern, conversation-flow, context +Converts dependency parse output into arc-based representations, where each sentence is expressed as a collection of dependency arc strings. Requires TextParser to be run first. -**Example:** `SCD on conversations gone awry `_ +* **Transformer:** `TextToArcs `_ +* **Tags:** pre-processing, structural, parsing, utterance, linguistic, pattern .. raw:: html
-Conversation Dynamics Similarity (ConDynS) -------------------------------------------- +Thread Embedder +--------------- .. raw:: html -
+
-Measures the similarity between two conversations with respect to their conversational dynamics using SCD-based representations and sequence alignment. Enables topic-independent comparison of how conversations unfold. +Embeds thread-level hypergraph statistics from HyperConvo into a low-dimensional space using SVD or other dimensionality reduction. Useful for visualizing and comparing thread structure across a corpus. -* **API:** `ConvoDynamicsSimilarity `_ -* **Research:** `A Similarity Measure for Comparing Conversational Dynamics `_ -* **Tags:** measurement, feature extraction, LLM, corpus, pattern, conversation-flow, context, comparison +* **Transformer:** `ThreadEmbedder `_ +* **Research:** `Patterns of Participant Interactions `_ +* **Tags:** measurement, feature extraction, statistical, corpus, pattern .. raw:: html
-Talk-Time Sharing Dynamics ---------------------------- +Vector Classifier +----------------- .. raw:: html -
+
-Analyzes how talk-time is distributed and evolves between speakers throughout a conversation, capturing both overall balance and moment-to-moment dynamics in participation patterns. +Trains and applies a classifier on corpus object vector representations (e.g. bag-of-words, TF-IDF). Inherits from Classifier. Requires a ConvoKitMatrix with the specified vector name to be present on the corpus. -* **API:** `TalkTimeSharingDynamics `_ -* **Tags:** measurement, feature extraction, statistical, corpus, pattern, conversation-flow, social, comparison +* **Transformer:** `VectorClassifier `_ +* **Tags:** classification, modeling, vectorization, utterance, conversation, speaker, labeling -**Example:** `Talk-time in CANDOR and Supreme Court `_ +**Example:** `Bag-of-Words classification `_ .. raw:: html diff --git a/website/docs/source/index.rst b/website/docs/source/index.rst index 2cd4c7f8..d2314462 100644 --- a/website/docs/source/index.rst +++ b/website/docs/source/index.rst @@ -17,7 +17,7 @@ ConvoKit: Conversational Analysis Toolkit :target: https://github.com/CornellNLP/ConvoKit/blob/master/LICENSE.md :alt: License -This toolkit contains tools to extract conversational features and analyze social phenomena in conversations, using a `single unified interface `_ inspired by (and compatible with) scikit-learn. Several large conversational datasets are included together with scripts exemplifying the use of the toolkit on these datasets. The latest version is `4.1.0 `_ (released Mar. 10, 2026); follow the project on GitHub to keep track of updates. +This toolkit contains tools to extract conversational features and analyze social phenomena in conversations, using a `single unified interface `_ inspired by (and compatible with) scikit-learn. Several large conversational datasets are included together with scripts exemplifying the use of the toolkit on these datasets. The latest version is `4.1.1 `_ (released May 1, 2026); follow the project on GitHub to keep track of updates. Quick Links ----------- @@ -63,7 +63,7 @@ For an overview, watch our SIGDIAL talk introducing the toolkit: About installation datasets - features + Tools contributors Community & Support