convoviz 0.1.7__tar.gz → 0.2.0__tar.gz

{convoviz-0.1.7 → convoviz-0.2.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 Mohamed Cheikh Sidiya
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2023 Mohamed Cheikh Sidiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{convoviz-0.1.7 → convoviz-0.2.0}/PKG-INFO

@@ -1,26 +1,46 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: convoviz
-Version: 0.1.7
-Summary: Get analytics and visualizations on your ChatGPT data !
-Home-page: https://github.com/mohamed-chs/chatgpt-history-export-to-md
-License: MIT
-Keywords: markdown,advanced-data-analysis,json,zip,openai,chatgpt,bookmarklet,obsidian-md,code-interpreter
+Version: 0.2.0
+Summary: Get analytics and visualizations on your ChatGPT data!
+Keywords: markdown,chatgpt,openai,visualization,analytics,json,export,data-analysis,obsidian
 Author: Mohamed Cheikh Sidiya
-Author-email: mohamedcheikhsidiya77@gmail.com
-Requires-Python: >=3.9,<4.0
+Author-email: Mohamed Cheikh Sidiya <mohamedcheikhsidiya77@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2023 Mohamed Cheikh Sidiya
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: matplotlib (>=3.8.1,<4.0.0)
-Requires-Dist: nltk (>=3.8.1,<4.0.0)
-Requires-Dist: orjson (>=3.9.10,<4.0.0)
-Requires-Dist: pydantic (>=2.4.2,<3.0.0)
-Requires-Dist: questionary (>=2.0.1,<3.0.0)
-Requires-Dist: tqdm (>=4.66.1,<5.0.0)
-Requires-Dist: wordcloud (>=1.9.2,<2.0.0)
+Requires-Dist: matplotlib>=3.9.4
+Requires-Dist: nltk>=3.9.2
+Requires-Dist: orjson>=3.11.5
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.7.0
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=14.2.0
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: typer>=0.21.0
+Requires-Dist: wordcloud>=1.9.5
+Requires-Python: >=3.12
 Project-URL: Repository, https://github.com/mohamed-chs/chatgpt-history-export-to-md
 Description-Content-Type: text/markdown
 
@@ -51,41 +71,49 @@ See examples [here](demo).
 
 ### 2. Install the tool 🛠
 
-Open a terminal or command prompt and run:
+You can install the tool using `pip` (or `uv`):
 
 ```bash
 pip install convoviz
+# or
+uv pip install convoviz
 ```
 
-to install the package.
-
 ### 3. Run the Script 🏃‍♂️
 
-With the package installed, run the following command in your terminal:
+You have two options: **Interactive Mode** or **Command Line Arguments**.
+
+#### Interactive Mode
+
+Simply run the command and follow the prompts:
 
 ```bash
-python -m convoviz
+convoviz
 ```
 
-Next, follow the instructions displayed and choose your desired options, the script will handle the rest.
+#### Command Line Arguments
 
-### 4. Check the Output 🎉
+You can provide arguments directly to skip the prompts:
 
-And that's it! After running the script, head over to the output folder to see your nice word clouds, graphs, and neatly formatted Markdown files. Enjoy !
+```bash
+convoviz --zip path/to/your/export.zip --output path/to/output/folder
+```
 
-**Tweet Your Discoveries**:
+For more options, run:
 
-[![Tweet](https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Fgithub.com%2Fyourusername%2Fyourrepository)](https://twitter.com/intent/tweet?text=So%2C%20this%20is%20what%20my%20entire%20ChatGPT%20history%20looks%20like%20...%0D%0A%0D%0Ahttp%3A%2F%2Fbit.ly%2F3ZuHCCK)
+```bash
+convoviz --help
+```
 
-### How to add new conversations ➕
+### 4. Check the Output 🎉
 
-See [How to use the JS script](js/how_to_use.md) for instructions on how to download new conversations.
+And that's it! After running the script, head over to the output folder to see your nice word clouds, graphs, and neatly formatted Markdown files. Enjoy !
 
 ## Share Your Feedback! 💌
 
 I hope you find this tool useful. I'm continuously looking to improve on this, but I need your help for that.
 
-Whether you're a tech wizard or you're new to all this (especially if you're new to all this), I'd love to hear about your journey with the tool. Found a quirk? Have a suggestion? Or just want to send some good vibes? I'm all ears!
+Whether you're a tech wizard or you're new to all this, I'd love to hear about your journey with the tool. Found a quirk? Have a suggestion? Or just want to send some good vibes? I'm all ears!
 
 **Here's how you can share your thoughts:**
 
@@ -99,17 +127,8 @@ Thank you for being awesome! 🌟
 
 ## Notes
 
-This project requires Python 3.8.7 or higher if on Windows. See [known issue](https://github.com/prompt-toolkit/python-prompt-toolkit/issues/1023#issue-534396318)
+This project requires Python 3.9 or higher.
 
 This is just a small thing I coded to help me see my convos in beautiful markdown, in [Obsidian](https://obsidian.md/) (my go-to note-taking app).
 
-I wasn't a fan of the clunky, and sometimes paid, browser extensions.
-
-It was also a great opportunity to learn more about Python and type annotations. I had mypy, pyright, and ruff all on strict mode, 'twas fun.
-
-It also works as package, so you can **import** it in your own projects, and use the models and functions as you wish. I need to add more documentation for that tho. Feel free to reach out if you need help.
-
-I'm working on automating it to add new conversations and updating old ones. Had some luck with a JavaScript bookmarklet, still ironing it out tho. Shouldn't take long.
-
-> for an older version with zero dependencies, see https://github.com/mohamed-chs/chatgpt-history-export-to-md/tree/fe13a701fe8653c9f946b1e12979ce3bfe7104b8.
-
+It also works as package, so you can **import** it in your own projects, and use the models and functions as you wish.

{convoviz-0.1.7 → convoviz-0.2.0}/README.md

@@ -1,88 +1,88 @@
-# Convoviz 📊: Visualize your entire ChatGPT data !
-
-Convert your ChatGPT history into well-formatted Markdown files. Additionally, visualize your data with word clouds 🔡☁️, view your prompt history graphs 📈, and access all your custom instructions 🤖 in a single location.
-
-![GitHub last commit](https://img.shields.io/github/last-commit/mohamed-chs/chatgpt-history-export-to-md)
-![GitHub issues](https://img.shields.io/github/issues/mohamed-chs/chatgpt-history-export-to-md)
-
-## Features
-
-- **YAML Headers**: Optional and included by default.
-- **Track message versions**: prompt/response edits included.
-- **Code Interpreter**: Environment code blocks and execution results.
-- **Data Visualizations**: Word clouds, graphs, and more.
-- **Custom Instructions**: All your custom instructions in one JSON file.
-
-See examples [here](demo).
-
-## How to Use 📖
-
-### 1. Export Your ChatGPT Data 🗂
-
-- Sign in at [chat.openai.com](https://chat.openai.com).
-- Navigate: Profile Name (bottom left) -> **Settings** -> **Data controls** -> **Export** -> **Confirm export**.
-- Await email from OpenAI and download the `.zip` file.
-
-### 2. Install the tool 🛠
-
-Open a terminal or command prompt and run:
-
-```bash
-pip install convoviz
-```
-
-to install the package.
-
-### 3. Run the Script 🏃‍♂️
-
-With the package installed, run the following command in your terminal:
-
-```bash
-python -m convoviz
-```
-
-Next, follow the instructions displayed and choose your desired options, the script will handle the rest.
-
-### 4. Check the Output 🎉
-
-And that's it! After running the script, head over to the output folder to see your nice word clouds, graphs, and neatly formatted Markdown files. Enjoy !
-
-**Tweet Your Discoveries**:
-
-[![Tweet](https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Fgithub.com%2Fyourusername%2Fyourrepository)](https://twitter.com/intent/tweet?text=So%2C%20this%20is%20what%20my%20entire%20ChatGPT%20history%20looks%20like%20...%0D%0A%0D%0Ahttp%3A%2F%2Fbit.ly%2F3ZuHCCK)
-
-### How to add new conversations ➕
-
-See [How to use the JS script](js/how_to_use.md) for instructions on how to download new conversations.
-
-## Share Your Feedback! 💌
-
-I hope you find this tool useful. I'm continuously looking to improve on this, but I need your help for that.
-
-Whether you're a tech wizard or you're new to all this (especially if you're new to all this), I'd love to hear about your journey with the tool. Found a quirk? Have a suggestion? Or just want to send some good vibes? I'm all ears!
-
-**Here's how you can share your thoughts:**
-
-1. **GitHub Issues**: For more specific feedback or if you've stumbled upon a bug, please open an [issue](https://github.com/mohamed-chs/chatgpt-history-export-to-md/issues). This helps me track and address them effectively.
-
-2. **GitHub Discussions**: If you just want to share your general experience, have a suggestion, or maybe a cool idea for a new feature, jump into the [discussions](https://github.com/mohamed-chs/chatgpt-history-export-to-md/discussions) page. It's a more casual space where we can chat.
-
-And if you've had a great experience, consider giving the project a star ⭐. It keeps me motivated and helps others discover it!
-
-Thank you for being awesome! 🌟
-
-## Notes
-
-This project requires Python 3.8.7 or higher if on Windows. See [known issue](https://github.com/prompt-toolkit/python-prompt-toolkit/issues/1023#issue-534396318)
-
-This is just a small thing I coded to help me see my convos in beautiful markdown, in [Obsidian](https://obsidian.md/) (my go-to note-taking app).
-
-I wasn't a fan of the clunky, and sometimes paid, browser extensions.
-
-It was also a great opportunity to learn more about Python and type annotations. I had mypy, pyright, and ruff all on strict mode, 'twas fun.
-
-It also works as package, so you can **import** it in your own projects, and use the models and functions as you wish. I need to add more documentation for that tho. Feel free to reach out if you need help.
-
-I'm working on automating it to add new conversations and updating old ones. Had some luck with a JavaScript bookmarklet, still ironing it out tho. Shouldn't take long.
-
-> for an older version with zero dependencies, see https://github.com/mohamed-chs/chatgpt-history-export-to-md/tree/fe13a701fe8653c9f946b1e12979ce3bfe7104b8.
+# Convoviz 📊: Visualize your entire ChatGPT data !
+
+Convert your ChatGPT history into well-formatted Markdown files. Additionally, visualize your data with word clouds 🔡☁️, view your prompt history graphs 📈, and access all your custom instructions 🤖 in a single location.
+
+![GitHub last commit](https://img.shields.io/github/last-commit/mohamed-chs/chatgpt-history-export-to-md)
+![GitHub issues](https://img.shields.io/github/issues/mohamed-chs/chatgpt-history-export-to-md)
+
+## Features
+
+- **YAML Headers**: Optional and included by default.
+- **Track message versions**: prompt/response edits included.
+- **Code Interpreter**: Environment code blocks and execution results.
+- **Data Visualizations**: Word clouds, graphs, and more.
+- **Custom Instructions**: All your custom instructions in one JSON file.
+
+See examples [here](demo).
+
+## How to Use 📖
+
+### 1. Export Your ChatGPT Data 🗂
+
+- Sign in at [chat.openai.com](https://chat.openai.com).
+- Navigate: Profile Name (bottom left) -> **Settings** -> **Data controls** -> **Export** -> **Confirm export**.
+- Await email from OpenAI and download the `.zip` file.
+
+### 2. Install the tool 🛠
+
+You can install the tool using `pip` (or `uv`):
+
+```bash
+pip install convoviz
+# or
+uv pip install convoviz
+```
+
+### 3. Run the Script 🏃‍♂️
+
+You have two options: **Interactive Mode** or **Command Line Arguments**.
+
+#### Interactive Mode
+
+Simply run the command and follow the prompts:
+
+```bash
+convoviz
+```
+
+#### Command Line Arguments
+
+You can provide arguments directly to skip the prompts:
+
+```bash
+convoviz --zip path/to/your/export.zip --output path/to/output/folder
+```
+
+For more options, run:
+
+```bash
+convoviz --help
+```
+
+### 4. Check the Output 🎉
+
+And that's it! After running the script, head over to the output folder to see your nice word clouds, graphs, and neatly formatted Markdown files. Enjoy !
+
+## Share Your Feedback! 💌
+
+I hope you find this tool useful. I'm continuously looking to improve on this, but I need your help for that.
+
+Whether you're a tech wizard or you're new to all this, I'd love to hear about your journey with the tool. Found a quirk? Have a suggestion? Or just want to send some good vibes? I'm all ears!
+
+**Here's how you can share your thoughts:**
+
+1. **GitHub Issues**: For more specific feedback or if you've stumbled upon a bug, please open an [issue](https://github.com/mohamed-chs/chatgpt-history-export-to-md/issues). This helps me track and address them effectively.
+
+2. **GitHub Discussions**: If you just want to share your general experience, have a suggestion, or maybe a cool idea for a new feature, jump into the [discussions](https://github.com/mohamed-chs/chatgpt-history-export-to-md/discussions) page. It's a more casual space where we can chat.
+
+And if you've had a great experience, consider giving the project a star ⭐. It keeps me motivated and helps others discover it!
+
+Thank you for being awesome! 🌟
+
+## Notes
+
+This project requires Python 3.9 or higher.
+
+This is just a small thing I coded to help me see my convos in beautiful markdown, in [Obsidian](https://obsidian.md/) (my go-to note-taking app).
+
+It also works as package, so you can **import** it in your own projects, and use the models and functions as you wish.

convoviz-0.2.0/convoviz/__init__.py

@@ -0,0 +1,25 @@
+"""Convoviz - ChatGPT data visualization and export tool."""
+
+from convoviz import analysis, config, io, models, renderers, utils
+from convoviz.config import ConvovizConfig, get_default_config
+from convoviz.models import Conversation, ConversationCollection, Message, Node
+from convoviz.pipeline import run_pipeline
+
+__all__ = [
+    # Submodules
+    "analysis",
+    "config",
+    "io",
+    "models",
+    "renderers",
+    "utils",
+    # Main classes
+    "Conversation",
+    "ConversationCollection",
+    "ConvovizConfig",
+    "Message",
+    "Node",
+    # Functions
+    "get_default_config",
+    "run_pipeline",
+]

convoviz-0.2.0/convoviz/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running convoviz as a module: python -m convoviz"""
+
+from convoviz.cli import main_entry
+
+if __name__ == "__main__":
+    main_entry()

convoviz-0.2.0/convoviz/analysis/__init__.py

@@ -0,0 +1,9 @@
+"""Data analysis and visualization for convoviz."""
+
+from convoviz.analysis.graphs import generate_week_barplot
+from convoviz.analysis.wordcloud import generate_wordcloud
+
+__all__ = [
+    "generate_week_barplot",
+    "generate_wordcloud",
+]

convoviz-0.2.0/convoviz/analysis/graphs.py

@@ -0,0 +1,98 @@
+"""Graph generation for conversation analytics."""
+
+from collections import defaultdict
+from datetime import UTC, datetime
+from pathlib import Path
+
+from matplotlib.figure import Figure
+from tqdm import tqdm
+
+from convoviz.config import GraphConfig
+from convoviz.models import ConversationCollection
+
+WEEKDAYS = [
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+    "Sunday",
+]
+
+
+def generate_week_barplot(
+    timestamps: list[float],
+    title: str,
+    _config: GraphConfig | None = None,
+) -> Figure:
+    """Create a bar graph showing message distribution across weekdays.
+
+    Args:
+        timestamps: List of Unix timestamps
+        title: Title for the graph
+        config: Optional graph configuration (for future extensions)
+
+    Returns:
+        Matplotlib Figure object
+    """
+    dates = [datetime.fromtimestamp(ts, UTC) for ts in timestamps]
+
+    weekday_counts: defaultdict[str, int] = defaultdict(int)
+    for date in dates:
+        weekday_counts[WEEKDAYS[date.weekday()]] += 1
+
+    x = WEEKDAYS
+    y = [weekday_counts[day] for day in WEEKDAYS]
+
+    fig = Figure(dpi=300)
+    ax = fig.add_subplot()
+
+    ax.bar(x, y)
+    ax.set_xlabel("Weekday")
+    ax.set_ylabel("Prompt Count")
+    ax.set_title(title)
+    ax.set_xticks(range(len(x)))
+    ax.set_xticklabels(x, rotation=45)
+    fig.tight_layout()
+
+    return fig
+
+
+def generate_week_barplots(
+    collection: ConversationCollection,
+    output_dir: Path,
+    config: GraphConfig | None = None,
+    *,
+    progress_bar: bool = False,
+) -> None:
+    """Generate weekly bar plots for monthly and yearly groupings.
+
+    Args:
+        collection: Collection of conversations
+        output_dir: Directory to save the graphs
+        config: Optional graph configuration
+        progress_bar: Whether to show progress bars
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    month_groups = collection.group_by_month()
+    year_groups = collection.group_by_year()
+
+    for month, group in tqdm(
+        month_groups.items(),
+        desc="Creating monthly weekwise graphs 📈",
+        disable=not progress_bar,
+    ):
+        title = month.strftime("%B '%y")
+        fig = generate_week_barplot(group.timestamps("user"), title, config)
+        fig.savefig(output_dir / f"{month.strftime('%Y %B')}.png")
+
+    for year, group in tqdm(
+        year_groups.items(),
+        desc="Creating yearly weekwise graphs 📈",
+        disable=not progress_bar,
+    ):
+        title = year.strftime("%Y")
+        fig = generate_week_barplot(group.timestamps("user"), title, config)
+        fig.savefig(output_dir / f"{year.strftime('%Y')}.png")

convoviz-0.2.0/convoviz/analysis/wordcloud.py

@@ -0,0 +1,142 @@
+"""Word cloud generation for conversation text."""
+
+from functools import lru_cache
+from pathlib import Path
+
+from nltk import download as nltk_download
+from nltk.corpus import stopwords as nltk_stopwords
+from nltk.data import find as nltk_find
+from PIL.Image import Image
+from tqdm import tqdm
+from wordcloud import WordCloud
+
+from convoviz.config import WordCloudConfig
+from convoviz.models import ConversationCollection
+
+# Languages for stopwords
+STOPWORD_LANGUAGES = [
+    "arabic",
+    "english",
+    "french",
+    "german",
+    "spanish",
+    "portuguese",
+]
+
+
+@lru_cache(maxsize=1)
+def load_nltk_stopwords() -> frozenset[str]:
+    """Load and cache NLTK stopwords.
+
+    Downloads stopwords if not already present.
+
+    Returns:
+        Frozen set of stopwords from multiple languages
+    """
+    try:
+        nltk_find("corpora/stopwords")
+    except LookupError:
+        nltk_download("stopwords", quiet=True)
+
+    words: set[str] = set()
+    for lang in STOPWORD_LANGUAGES:
+        words.update(nltk_stopwords.words(fileids=lang))
+
+    return frozenset(words)
+
+
+def parse_custom_stopwords(stopwords_str: str) -> set[str]:
+    """Parse a comma-separated string of custom stopwords.
+
+    Args:
+        stopwords_str: Comma-separated stopwords
+
+    Returns:
+        Set of lowercase, stripped stopwords
+    """
+    if not stopwords_str:
+        return set()
+
+    return {word.strip().lower() for word in stopwords_str.split(",") if word.strip()}
+
+
+def generate_wordcloud(text: str, config: WordCloudConfig) -> Image:
+    """Generate a word cloud from text.
+
+    Args:
+        text: The text to create a word cloud from
+        config: Word cloud configuration
+
+    Returns:
+        PIL Image of the word cloud
+    """
+    # Combine NLTK and custom stopwords
+    stopwords = set(load_nltk_stopwords())
+    stopwords.update(parse_custom_stopwords(config.custom_stopwords))
+
+    wc = WordCloud(
+        font_path=str(config.font_path) if config.font_path else None,
+        width=config.width,
+        height=config.height,
+        stopwords=stopwords,
+        background_color=config.background_color,
+        mode=config.mode,
+        colormap=config.colormap,
+        include_numbers=config.include_numbers,
+    )
+
+    wc.generate(text)
+    result: Image = wc.to_image()
+    return result
+
+
+def generate_wordclouds(
+    collection: ConversationCollection,
+    output_dir: Path,
+    config: WordCloudConfig,
+    *,
+    progress_bar: bool = False,
+) -> None:
+    """Generate word clouds for weekly, monthly, and yearly groupings.
+
+    Args:
+        collection: Collection of conversations
+        output_dir: Directory to save the word clouds
+        config: Word cloud configuration
+        progress_bar: Whether to show progress bars
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    week_groups = collection.group_by_week()
+    month_groups = collection.group_by_month()
+    year_groups = collection.group_by_year()
+
+    for week, group in tqdm(
+        week_groups.items(),
+        desc="Creating weekly wordclouds 🔡☁️",
+        disable=not progress_bar,
+    ):
+        text = group.plaintext("user", "assistant")
+        if text.strip():
+            img = generate_wordcloud(text, config)
+            img.save(output_dir / f"{week.strftime('%Y week %W')}.png", optimize=True)
+
+    for month, group in tqdm(
+        month_groups.items(),
+        desc="Creating monthly wordclouds 🔡☁️",
+        disable=not progress_bar,
+    ):
+        text = group.plaintext("user", "assistant")
+        if text.strip():
+            img = generate_wordcloud(text, config)
+            img.save(output_dir / f"{month.strftime('%Y %B')}.png", optimize=True)
+
+    for year, group in tqdm(
+        year_groups.items(),
+        desc="Creating yearly wordclouds 🔡☁️",
+        disable=not progress_bar,
+    ):
+        text = group.plaintext("user", "assistant")
+        if text.strip():
+            img = generate_wordcloud(text, config)
+            img.save(output_dir / f"{year.strftime('%Y')}.png", optimize=True)