convoviz 0.3.2__tar.gz

convoviz-0.3.2/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: convoviz
+Version: 0.3.2
+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: Mohamed Cheikh Sidiya <mohamedcheikhsidiya77@gmail.com>
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: orjson>=3.11.5
+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: nltk>=3.9.2 ; extra == 'viz'
+Requires-Dist: wordcloud>=1.9.5 ; extra == 'viz'
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/mohamed-chs/chatgpt-history-export-to-md
+Provides-Extra: viz
+Description-Content-Type: text/markdown
+
+# Convoviz 📊: Visualize your entire ChatGPT data
+
+Convert your ChatGPT history into well-formatted Markdown files. Visualize your data with word clouds 🔡☁️ and usage graphs 📈.
+
+![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.
+- **Inline Images**: Media attachments rendered directly in Markdown.
+- **Data Visualizations**: Word clouds, graphs, and more.
+
+See examples [here](demo).
+
+## How to Use 📖
+
+### 1. Export Your ChatGPT Data 🗂
+
+- Sign in at [chatgpt.com](https://chatgpt.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 🛠
+
+First, install [uv](https://github.com/astral-sh/uv) (if you don't have it):
+
+MacOS / Linux:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then install convoviz:
+
+```bash
+uv tool install "convoviz[viz]"
+```
+
+The `[viz]` extra includes graphs and word clouds. Skip it for a faster markdown-only install.
+
+### 3. Run the tool 🏃‍♂️
+
+Simply run the command and follow the prompts:
+
+```bash
+convoviz
+```
+
+#### Command Line Arguments
+
+You can provide arguments directly to skip the prompts:
+
+```bash
+convoviz --input path/to/your/export.zip --output path/to/output/folder
+```
+
+##### Selective Output
+
+By default, all outputs are generated. Use `--outputs` to pick specific ones:
+
+```bash
+convoviz --input export.zip --outputs markdown --outputs graphs
+```
+
+Options: `markdown`, `graphs`, `wordclouds`. In interactive mode, you'll be prompted.
+
+##### Other Notes
+
+- `--zip` / `-z` is kept as an alias for `--input` for convenience.
+- You can force non-interactive mode with `--no-interactive`.
+- Use `--flat` to put all Markdown files in a single folder instead of organizing by date.
+
+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 neatly formatted Markdown files and visualizations.
+
+![wordcloud example](demo/wordcloud-example.png)
+
+## 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! (see [issues](https://github.com/mohamed-chs/chatgpt-history-export-to-md/issues))
+
+And if you've had a great experience, consider giving the project a star ⭐. It keeps me motivated and helps others discover it!
+
+## Notes
+
+This is just a small thing I coded to help me see my convos in beautiful markdown. It was originally built with [Obsidian](https://obsidian.md/) (my go-to note-taking app) in mind, but the default output is standard Markdown.
+
+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 should(?) also work as library, so you can import and use the models and functions. I need to add more documentation for that tho. Feel free to reach out if you need help.
+
+### Offline / reproducible runs
+
+Word clouds use NLTK stopwords. If you're offline and NLTK data isn't installed yet, pre-download it:
+
+```bash
+python -c "import nltk; nltk.download('stopwords')"
+```
+
+### Bookmarklet
+
+There's also a JavaScript bookmarklet flow under `js/` (experimental) for exporting additional conversation data outside the official ZIP export.

convoviz-0.3.2/README.md

@@ -0,0 +1,120 @@
+# Convoviz 📊: Visualize your entire ChatGPT data
+
+Convert your ChatGPT history into well-formatted Markdown files. Visualize your data with word clouds 🔡☁️ and usage graphs 📈.
+
+![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.
+- **Inline Images**: Media attachments rendered directly in Markdown.
+- **Data Visualizations**: Word clouds, graphs, and more.
+
+See examples [here](demo).
+
+## How to Use 📖
+
+### 1. Export Your ChatGPT Data 🗂
+
+- Sign in at [chatgpt.com](https://chatgpt.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 🛠
+
+First, install [uv](https://github.com/astral-sh/uv) (if you don't have it):
+
+MacOS / Linux:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then install convoviz:
+
+```bash
+uv tool install "convoviz[viz]"
+```
+
+The `[viz]` extra includes graphs and word clouds. Skip it for a faster markdown-only install.
+
+### 3. Run the tool 🏃‍♂️
+
+Simply run the command and follow the prompts:
+
+```bash
+convoviz
+```
+
+#### Command Line Arguments
+
+You can provide arguments directly to skip the prompts:
+
+```bash
+convoviz --input path/to/your/export.zip --output path/to/output/folder
+```
+
+##### Selective Output
+
+By default, all outputs are generated. Use `--outputs` to pick specific ones:
+
+```bash
+convoviz --input export.zip --outputs markdown --outputs graphs
+```
+
+Options: `markdown`, `graphs`, `wordclouds`. In interactive mode, you'll be prompted.
+
+##### Other Notes
+
+- `--zip` / `-z` is kept as an alias for `--input` for convenience.
+- You can force non-interactive mode with `--no-interactive`.
+- Use `--flat` to put all Markdown files in a single folder instead of organizing by date.
+
+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 neatly formatted Markdown files and visualizations.
+
+![wordcloud example](demo/wordcloud-example.png)
+
+## 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! (see [issues](https://github.com/mohamed-chs/chatgpt-history-export-to-md/issues))
+
+And if you've had a great experience, consider giving the project a star ⭐. It keeps me motivated and helps others discover it!
+
+## Notes
+
+This is just a small thing I coded to help me see my convos in beautiful markdown. It was originally built with [Obsidian](https://obsidian.md/) (my go-to note-taking app) in mind, but the default output is standard Markdown.
+
+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 should(?) also work as library, so you can import and use the models and functions. I need to add more documentation for that tho. Feel free to reach out if you need help.
+
+### Offline / reproducible runs
+
+Word clouds use NLTK stopwords. If you're offline and NLTK data isn't installed yet, pre-download it:
+
+```bash
+python -c "import nltk; nltk.download('stopwords')"
+```
+
+### Bookmarklet
+
+There's also a JavaScript bookmarklet flow under `js/` (experimental) for exporting additional conversation data outside the official ZIP export.

convoviz-0.3.2/convoviz/__init__.py

@@ -0,0 +1,34 @@
+"""Convoviz - ChatGPT data visualization and export tool."""
+
+from convoviz import 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",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import for optional submodules like analysis."""
+    if name == "analysis":
+        from convoviz import analysis
+
+        return analysis
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

convoviz-0.3.2/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.3.2/convoviz/analysis/__init__.py

@@ -0,0 +1,22 @@
+"""Data analysis and visualization for convoviz.
+
+Requires the [viz] extra: uv tool install "convoviz[viz]"
+"""
+
+__all__ = [
+    "generate_week_barplot",
+    "generate_wordcloud",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import for visualization functions requiring optional dependencies."""
+    if name == "generate_week_barplot":
+        from convoviz.analysis.graphs import generate_week_barplot
+
+        return generate_week_barplot
+    if name == "generate_wordcloud":
+        from convoviz.analysis.wordcloud import generate_wordcloud
+
+        return generate_wordcloud
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")