convoviz 0.2.14__tar.gz → 0.3.1__tar.gz

{convoviz-0.2.14 → convoviz-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convoviz
-Version: 0.2.14
+Version: 0.3.1
 Summary: Get analytics and visualizations on your ChatGPT data!
 Keywords: markdown,chatgpt,openai,visualization,analytics,json,export,data-analysis,obsidian
 Author: Mohamed Cheikh Sidiya
@@ -9,19 +9,18 @@ License-Expression: MIT
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
-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-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
@@ -49,23 +48,19 @@ See examples [here](demo).
 
 ### 2. Install the tool 🛠
 
-Try it without installing using uv ([astral-sh/uv](https://github.com/astral-sh/uv?tab=readme-ov-file#highlights)):
+With uv ([astral-sh/uv](https://github.com/astral-sh/uv?tab=readme-ov-file#highlights)):
 
 ```bash
-uvx convoviz
-```
-
-You can install it with uv (Recommended):
-
-```bash
-uv tool install convoviz
+uv tool install convoviz[viz]
 ```
 
 or pipx:
 ```bash
-pipx install convoviz
+pipx install convoviz[viz]
 ```
 
+The `[viz]` extra includes graphs and word clouds. If you only need markdown conversion, you can skip it for a faster install (`uv tool install convoviz`).
+
 ### 3. Run the tool 🏃‍♂️
 
 Simply run the command and follow the prompts:
@@ -82,9 +77,28 @@ You can provide arguments directly to skip the prompts:
 convoviz --input path/to/your/export.zip --output path/to/output/folder
 ```
 
-Notes:
+##### Selective Output Generation
+
+By default, Convoviz generates all outputs (Markdown files, graphs, and word clouds). You can select specific outputs using the `--outputs` flag:
+
+```bash
+# Generate only Markdown files (fastest)
+convoviz --input export.zip --outputs markdown
+
+# Generate Markdown and graphs (no word clouds)
+convoviz --input export.zip --outputs markdown --outputs graphs
+
+# Generate all outputs (default behavior)
+convoviz --input export.zip --outputs markdown --outputs graphs --outputs wordclouds
+```
+
+In interactive mode, you'll be prompted to select which outputs to generate.
+
+##### 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:
 
@@ -96,31 +110,13 @@ convoviz --help
 
 And that's it! After running the script, head over to the output folder to see your neatly formatted Markdown files and visualizations.
 
-The main outputs are:
-
-- **`Markdown/`**: one `.md` file per conversation
-- **`Graphs/`**: a small set of high-signal plots, including:
-  - `overview.png` (dashboard)
-  - `activity_heatmap.png` (weekday × hour)
-  - `daily_activity.png` / `monthly_activity.png`
-  - `model_usage.png`, `conversation_lengths.png`
-  - `weekday_pattern.png`, `hourly_pattern.png`, `conversation_lifetimes.png`
-- **`Word-Clouds/`**: weekly/monthly/yearly word clouds
-- **`custom_instructions.json`**: extracted custom instructions
-
 ![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!
-
-**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.
+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!
 
@@ -128,9 +124,6 @@ And if you've had a great experience, consider giving the project a star ⭐. It
 
 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.
 
-You can choose obsidian flavored md in the cli to get extra features like:
-- model reasoning (`reasoning_recap`, `thoughts`) rendered as collapsible `> [!NOTE]-` callouts instead of being hidden.
-
 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.
@@ -139,12 +132,12 @@ It should(?) also work as library, so you can import and use the models and func
 
 ### Offline / reproducible runs
 
-Convoviz uses NLTK stopwords for word clouds. If you’re offline and NLTK data isn’t already installed, pre-download it once:
+Word clouds use NLTK stopwords. If you're offline and NLTK data isn't installed yet, pre-download it:
 
 ```bash
-uv run python -c "import nltk; nltk.download('stopwords')"
+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.
+There's also a JavaScript bookmarklet flow under `js/` (experimental) for exporting additional conversation data outside the official ZIP export.

{convoviz-0.2.14 → convoviz-0.3.1}/README.md

@@ -23,23 +23,19 @@ See examples [here](demo).
 
 ### 2. Install the tool 🛠
 
-Try it without installing using uv ([astral-sh/uv](https://github.com/astral-sh/uv?tab=readme-ov-file#highlights)):
+With uv ([astral-sh/uv](https://github.com/astral-sh/uv?tab=readme-ov-file#highlights)):
 
 ```bash
-uvx convoviz
-```
-
-You can install it with uv (Recommended):
-
-```bash
-uv tool install convoviz
+uv tool install convoviz[viz]
 ```
 
 or pipx:
 ```bash
-pipx install convoviz
+pipx install convoviz[viz]
 ```
 
+The `[viz]` extra includes graphs and word clouds. If you only need markdown conversion, you can skip it for a faster install (`uv tool install convoviz`).
+
 ### 3. Run the tool 🏃‍♂️
 
 Simply run the command and follow the prompts:
@@ -56,9 +52,28 @@ You can provide arguments directly to skip the prompts:
 convoviz --input path/to/your/export.zip --output path/to/output/folder
 ```
 
-Notes:
+##### Selective Output Generation
+
+By default, Convoviz generates all outputs (Markdown files, graphs, and word clouds). You can select specific outputs using the `--outputs` flag:
+
+```bash
+# Generate only Markdown files (fastest)
+convoviz --input export.zip --outputs markdown
+
+# Generate Markdown and graphs (no word clouds)
+convoviz --input export.zip --outputs markdown --outputs graphs
+
+# Generate all outputs (default behavior)
+convoviz --input export.zip --outputs markdown --outputs graphs --outputs wordclouds
+```
+
+In interactive mode, you'll be prompted to select which outputs to generate.
+
+##### 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:
 
@@ -70,31 +85,13 @@ convoviz --help
 
 And that's it! After running the script, head over to the output folder to see your neatly formatted Markdown files and visualizations.
 
-The main outputs are:
-
-- **`Markdown/`**: one `.md` file per conversation
-- **`Graphs/`**: a small set of high-signal plots, including:
-  - `overview.png` (dashboard)
-  - `activity_heatmap.png` (weekday × hour)
-  - `daily_activity.png` / `monthly_activity.png`
-  - `model_usage.png`, `conversation_lengths.png`
-  - `weekday_pattern.png`, `hourly_pattern.png`, `conversation_lifetimes.png`
-- **`Word-Clouds/`**: weekly/monthly/yearly word clouds
-- **`custom_instructions.json`**: extracted custom instructions
-
 ![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!
-
-**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.
+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!
 
@@ -102,9 +99,6 @@ And if you've had a great experience, consider giving the project a star ⭐. It
 
 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.
 
-You can choose obsidian flavored md in the cli to get extra features like:
-- model reasoning (`reasoning_recap`, `thoughts`) rendered as collapsible `> [!NOTE]-` callouts instead of being hidden.
-
 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.
@@ -113,12 +107,12 @@ It should(?) also work as library, so you can import and use the models and func
 
 ### Offline / reproducible runs
 
-Convoviz uses NLTK stopwords for word clouds. If you’re offline and NLTK data isn’t already installed, pre-download it once:
+Word clouds use NLTK stopwords. If you're offline and NLTK data isn't installed yet, pre-download it:
 
 ```bash
-uv run python -c "import nltk; nltk.download('stopwords')"
+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.
+There's also a JavaScript bookmarklet flow under `js/` (experimental) for exporting additional conversation data outside the official ZIP export.

{convoviz-0.2.14 → convoviz-0.3.1}/convoviz/__init__.py

@@ -1,6 +1,6 @@
 """Convoviz - ChatGPT data visualization and export tool."""
 
-from convoviz import analysis, config, io, models, renderers, utils
+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
@@ -23,3 +23,12 @@ __all__ = [
     "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.1/convoviz/analysis/__init__.py

@@ -0,0 +1,22 @@
+"""Data analysis and visualization for convoviz.
+
+Requires the [viz] extra: pip 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}")

{convoviz-0.2.14 → convoviz-0.3.1}/convoviz/cli.py

@@ -5,7 +5,7 @@ from pathlib import Path
 import typer
 from rich.console import Console
 
-from convoviz.config import FolderOrganization, get_default_config
+from convoviz.config import FolderOrganization, OutputKind, get_default_config
 from convoviz.exceptions import ConfigurationError, InvalidZipError
 from convoviz.interactive import run_interactive_config
 from convoviz.io.loaders import find_latest_zip
@@ -38,6 +38,12 @@ def run(
         "-o",
         help="Path to the output directory.",
     ),
+    outputs: list[OutputKind] | None = typer.Option(
+        None,
+        "--outputs",
+        help="Output types to generate (repeatable). Options: markdown, graphs, wordclouds. "
+        "If not specified, all outputs are generated.",
+    ),
     flat: bool = typer.Option(
         False,
         "--flat",
@@ -63,6 +69,8 @@ def run(
         config.input_path = input_path
     if output_dir:
         config.output_folder = output_dir
+    if outputs:
+        config.outputs = set(outputs)
     if flat:
         config.folder_organization = FolderOrganization.FLAT
 

{convoviz-0.2.14 → convoviz-0.3.1}/convoviz/config.py

@@ -14,6 +14,18 @@ class FolderOrganization(str, Enum):
     DATE = "date"  # Nested by year/month (default)
 
 
+class OutputKind(str, Enum):
+    """Types of outputs that can be generated."""
+
+    MARKDOWN = "markdown"  # Conversation markdown files
+    GRAPHS = "graphs"  # Usage analytics graphs
+    WORDCLOUDS = "wordclouds"  # Word cloud visualizations
+
+
+# Default: generate all outputs
+ALL_OUTPUTS: frozenset[OutputKind] = frozenset(OutputKind)
+
+
 class AuthorHeaders(BaseModel):
     """Headers for different message authors in markdown output."""
 
@@ -93,6 +105,7 @@ class ConvovizConfig(BaseModel):
     input_path: Path | None = None
     output_folder: Path = Field(default_factory=lambda: Path.home() / "Documents" / "ChatGPT-Data")
     folder_organization: FolderOrganization = FolderOrganization.DATE
+    outputs: set[OutputKind] = Field(default_factory=lambda: set(ALL_OUTPUTS))
     message: MessageConfig = Field(default_factory=MessageConfig)
     conversation: ConversationConfig = Field(default_factory=ConversationConfig)
     wordcloud: WordCloudConfig = Field(default_factory=WordCloudConfig)

convoviz-0.3.1/convoviz/interactive.py

@@ -0,0 +1,255 @@
+"""Interactive configuration prompts using questionary."""
+
+from pathlib import Path
+from typing import Literal, Protocol, cast
+
+from questionary import Choice, Style, checkbox, select
+from questionary import path as qst_path
+from questionary import text as qst_text
+
+from convoviz.config import ConvovizConfig, OutputKind, get_default_config
+from convoviz.io.loaders import find_latest_zip, validate_zip
+from convoviz.utils import colormaps, default_font_path, font_names, font_path, validate_header
+
+CUSTOM_STYLE = Style(
+    [
+        ("qmark", "fg:#34eb9b bold"),
+        ("question", "bold fg:#e0e0e0"),
+        ("answer", "fg:#34ebeb bold"),
+        ("pointer", "fg:#e834eb bold"),
+        ("highlighted", "fg:#349ceb bold"),
+        ("selected", "fg:#34ebeb"),
+        ("separator", "fg:#eb3434"),
+        ("instruction", "fg:#eb9434"),
+        ("text", "fg:#b2eb34"),
+        ("disabled", "fg:#858585 italic"),
+    ]
+)
+
+
+class _QuestionaryPrompt[T](Protocol):
+    def ask(self) -> T | None: ...
+
+
+def _ask_or_cancel[T](prompt: _QuestionaryPrompt[T]) -> T:
+    """Ask a questionary prompt; treat Ctrl+C/Ctrl+D as cancelling the run.
+
+    questionary's `.ask()` returns `None` on cancellation (Ctrl+C / Ctrl+D). We
+    convert that to `KeyboardInterrupt` so callers can abort the whole
+    interactive session with a single Ctrl+C.
+    """
+
+    result = prompt.ask()
+    if result is None:
+        raise KeyboardInterrupt
+    return result
+
+
+def _validate_input_path(raw: str) -> bool | str:
+    path = Path(raw)
+    if not path.exists():
+        return "Path must exist"
+
+    if path.is_dir():
+        if (path / "conversations.json").exists():
+            return True
+        return "Directory must contain conversations.json"
+
+    if path.suffix.lower() == ".json":
+        return True
+
+    if path.suffix.lower() == ".zip":
+        return True if validate_zip(path) else "ZIP must contain conversations.json"
+
+    return "Input must be a .zip, a .json, or a directory containing conversations.json"
+
+
+def run_interactive_config(initial_config: ConvovizConfig | None = None) -> ConvovizConfig:
+    """Run interactive prompts to configure convoviz.
+
+    Args:
+        initial_config: Optional starting configuration (uses defaults if None)
+
+    Returns:
+        Updated configuration based on user input
+    """
+    config = initial_config or get_default_config()
+
+    # Set sensible defaults if not already set
+    if not config.input_path:
+        latest = find_latest_zip()
+        if latest:
+            config.input_path = latest
+
+    if not config.wordcloud.font_path:
+        config.wordcloud.font_path = default_font_path()
+
+    # Prompt for input path
+    input_default = str(config.input_path) if config.input_path else ""
+    input_result: str = _ask_or_cancel(
+        qst_path(
+            "Enter the path to the export ZIP, conversations JSON, or extracted directory:",
+            default=input_default,
+            validate=_validate_input_path,
+            style=CUSTOM_STYLE,
+        )
+    )
+
+    if input_result:
+        config.input_path = Path(input_result)
+
+    # Prompt for output folder
+    output_result: str = _ask_or_cancel(
+        qst_path(
+            "Enter the path to the output folder:",
+            default=str(config.output_folder),
+            style=CUSTOM_STYLE,
+        )
+    )
+
+    if output_result:
+        config.output_folder = Path(output_result)
+
+    # Prompt for outputs to generate
+    output_choices = [
+        Choice(title="Markdown conversations", value=OutputKind.MARKDOWN, checked=True),
+        Choice(title="Graphs (usage analytics)", value=OutputKind.GRAPHS, checked=True),
+        Choice(title="Word clouds", value=OutputKind.WORDCLOUDS, checked=True),
+    ]
+
+    selected_outputs: list[OutputKind] = _ask_or_cancel(
+        checkbox(
+            "Select outputs to generate:",
+            choices=output_choices,
+            style=CUSTOM_STYLE,
+        )
+    )
+
+    config.outputs = set(selected_outputs) if selected_outputs else set()
+
+    # Prompt for markdown settings (only if markdown output is selected)
+    if OutputKind.MARKDOWN in config.outputs:
+        # Prompt for author headers
+        headers = config.message.author_headers
+        for role in ["user", "assistant"]:
+            current = getattr(headers, role)
+            result: str = _ask_or_cancel(
+                qst_text(
+                    f"Enter the message header for '{role}':",
+                    default=current,
+                    validate=lambda t: validate_header(t)
+                    or "Must be a valid markdown header (e.g., # Title)",
+                    style=CUSTOM_STYLE,
+                )
+            )
+            if result:
+                setattr(headers, role, result)
+
+        # Prompt for markdown flavor
+        flavor_result = cast(
+            Literal["standard", "obsidian"],
+            _ask_or_cancel(
+                select(
+                    "Select the markdown flavor:",
+                    choices=["standard", "obsidian"],
+                    default=config.conversation.markdown.flavor,
+                    style=CUSTOM_STYLE,
+                )
+            ),
+        )
+
+        if flavor_result:
+            config.conversation.markdown.flavor = flavor_result
+
+        # Prompt for YAML headers
+        yaml_config = config.conversation.yaml
+        yaml_choices = [
+            Choice(title=field, checked=getattr(yaml_config, field))
+            for field in [
+                "title",
+                "tags",
+                "chat_link",
+                "create_time",
+                "update_time",
+                "model",
+                "used_plugins",
+                "message_count",
+                "content_types",
+                "custom_instructions",
+            ]
+        ]
+
+        selected: list[str] = _ask_or_cancel(
+            checkbox(
+                "Select YAML metadata headers to include:",
+                choices=yaml_choices,
+                style=CUSTOM_STYLE,
+            )
+        )
+
+        selected_set = set(selected)
+        for field_name in [
+            "title",
+            "tags",
+            "chat_link",
+            "create_time",
+            "update_time",
+            "model",
+            "used_plugins",
+            "message_count",
+            "content_types",
+            "custom_instructions",
+        ]:
+            setattr(yaml_config, field_name, field_name in selected_set)
+
+    # Prompt for wordcloud settings (only if wordclouds output is selected)
+    if OutputKind.WORDCLOUDS in config.outputs:
+        # Prompt for font
+        available_fonts = font_names()
+        if available_fonts:
+            current_font = (
+                config.wordcloud.font_path.stem
+                if config.wordcloud.font_path
+                else available_fonts[0]
+            )
+            font_result: str = _ask_or_cancel(
+                select(
+                    "Select the font for word clouds:",
+                    choices=available_fonts,
+                    default=current_font if current_font in available_fonts else available_fonts[0],
+                    style=CUSTOM_STYLE,
+                )
+            )
+
+            if font_result:
+                config.wordcloud.font_path = font_path(font_result)
+
+        # Prompt for colormap
+        available_colormaps = colormaps()
+        if available_colormaps:
+            colormap_result: str = _ask_or_cancel(
+                select(
+                    "Select the color theme for word clouds:",
+                    choices=available_colormaps,
+                    default=config.wordcloud.colormap
+                    if config.wordcloud.colormap in available_colormaps
+                    else available_colormaps[0],
+                    style=CUSTOM_STYLE,
+                )
+            )
+
+            if colormap_result:
+                config.wordcloud.colormap = colormap_result
+
+        # Prompt for custom stopwords
+        stopwords_result: str = _ask_or_cancel(
+            qst_text(
+                "Enter custom stopwords (comma-separated):",
+                default=config.wordcloud.custom_stopwords,
+                style=CUSTOM_STYLE,
+            )
+        )
+
+        config.wordcloud.custom_stopwords = stopwords_result
+
+    return config

{convoviz-0.2.14 → convoviz-0.3.1}/convoviz/pipeline.py

@@ -5,16 +5,14 @@ from shutil import rmtree
 
 from rich.console import Console
 
-from convoviz.analysis.graphs import generate_graphs
-from convoviz.analysis.wordcloud import generate_wordclouds
-from convoviz.config import ConvovizConfig
-from convoviz.exceptions import InvalidZipError
+from convoviz.config import ConvovizConfig, OutputKind
+from convoviz.exceptions import ConfigurationError, InvalidZipError
 from convoviz.io.loaders import (
     find_latest_bookmarklet_json,
     load_collection_from_json,
     load_collection_from_zip,
 )
-from convoviz.io.writers import save_collection, save_custom_instructions
+from convoviz.io.writers import save_collection
 
 console = Console()
 
@@ -80,10 +78,21 @@ def run_pipeline(config: ConvovizConfig) -> None:
     output_folder = config.output_folder
     output_folder.mkdir(parents=True, exist_ok=True)
 
-    # Clean only specific sub-directories we manage
-    managed_dirs = ["Markdown", "Graphs", "Word-Clouds"]
-    for d in managed_dirs:
-        sub_dir = output_folder / d
+    # Determine which outputs are selected
+    selected_outputs = config.outputs
+
+    # Build mapping of output kind -> directory name
+    output_dir_map: dict[OutputKind, str] = {
+        OutputKind.MARKDOWN: "Markdown",
+        OutputKind.GRAPHS: "Graphs",
+        OutputKind.WORDCLOUDS: "Word-Clouds",
+    }
+
+    # Clean only specific sub-directories we manage (only for selected outputs)
+    for output_kind, dir_name in output_dir_map.items():
+        if output_kind not in selected_outputs:
+            continue
+        sub_dir = output_folder / dir_name
         if sub_dir.exists():
             # Never follow symlinks; just unlink them.
             if sub_dir.is_symlink():
@@ -94,69 +103,69 @@ def run_pipeline(config: ConvovizConfig) -> None:
                 sub_dir.unlink()
         sub_dir.mkdir(exist_ok=True)
 
-    # Clean specific files we manage
-    managed_files = ["custom_instructions.json"]
-    for f in managed_files:
-        managed_file = output_folder / f
-        if managed_file.exists():
-            if managed_file.is_symlink() or managed_file.is_file():
-                managed_file.unlink()
-            elif managed_file.is_dir():
-                rmtree(managed_file)
-            else:
-                managed_file.unlink()
-
-    # Save markdown files
-    markdown_folder = output_folder / "Markdown"
-    save_collection(
-        collection,
-        markdown_folder,
-        config.conversation,
-        config.message.author_headers,
-        folder_organization=config.folder_organization,
-        progress_bar=True,
-    )
-    console.print(
-        f"\nDone [bold green]✅[/bold green] ! "
-        f"Check the output [bold blue]📄[/bold blue] here: {_safe_uri(markdown_folder)} 🔗\n"
-    )
-
-    # Generate graphs
-    graph_folder = output_folder / "Graphs"
-    graph_folder.mkdir(parents=True, exist_ok=True)
-    generate_graphs(
-        collection,
-        graph_folder,
-        config.graph,
-        progress_bar=True,
-    )
-    console.print(
-        f"\nDone [bold green]✅[/bold green] ! "
-        f"Check the output [bold blue]📈[/bold blue] here: {_safe_uri(graph_folder)} 🔗\n"
-    )
-
-    # Generate word clouds
-    wordcloud_folder = output_folder / "Word-Clouds"
-    wordcloud_folder.mkdir(parents=True, exist_ok=True)
-    generate_wordclouds(
-        collection,
-        wordcloud_folder,
-        config.wordcloud,
-        progress_bar=True,
-    )
-    console.print(
-        f"\nDone [bold green]✅[/bold green] ! "
-        f"Check the output [bold blue]🔡☁️[/bold blue] here: {_safe_uri(wordcloud_folder)} 🔗\n"
-    )
-
-    # Save custom instructions
-    console.print("Writing custom instructions [bold blue]📝[/bold blue] ...\n")
-    instructions_path = output_folder / "custom_instructions.json"
-    save_custom_instructions(collection, instructions_path)
-    console.print(
-        f"\nDone [bold green]✅[/bold green] ! "
-        f"Check the output [bold blue]📝[/bold blue] here: {_safe_uri(instructions_path)} 🔗\n"
-    )
+    # Save markdown files (if selected)
+    if OutputKind.MARKDOWN in selected_outputs:
+        markdown_folder = output_folder / "Markdown"
+        save_collection(
+            collection,
+            markdown_folder,
+            config.conversation,
+            config.message.author_headers,
+            folder_organization=config.folder_organization,
+            progress_bar=True,
+        )
+        console.print(
+            f"\nDone [bold green]✅[/bold green] ! "
+            f"Check the output [bold blue]📄[/bold blue] here: {_safe_uri(markdown_folder)} 🔗\n"
+        )
+
+    # Generate graphs (if selected)
+    if OutputKind.GRAPHS in selected_outputs:
+        # Lazy import to allow markdown-only usage without matplotlib
+        try:
+            from convoviz.analysis.graphs import generate_graphs
+        except ModuleNotFoundError as e:
+            raise ConfigurationError(
+                "Graph generation requires matplotlib. "
+                "Install with: pip install convoviz[viz]"
+            ) from e
+
+        graph_folder = output_folder / "Graphs"
+        graph_folder.mkdir(parents=True, exist_ok=True)
+        generate_graphs(
+            collection,
+            graph_folder,
+            config.graph,
+            progress_bar=True,
+        )
+        console.print(
+            f"\nDone [bold green]✅[/bold green] ! "
+            f"Check the output [bold blue]📈[/bold blue] here: {_safe_uri(graph_folder)} 🔗\n"
+        )
+
+    # Generate word clouds (if selected)
+    if OutputKind.WORDCLOUDS in selected_outputs:
+        # Lazy import to allow markdown-only usage without wordcloud/nltk
+        try:
+            from convoviz.analysis.wordcloud import generate_wordclouds
+        except ModuleNotFoundError as e:
+            raise ConfigurationError(
+                "Word cloud generation requires wordcloud and nltk. "
+                "Install with: pip install convoviz[viz]"
+            ) from e
+
+        wordcloud_folder = output_folder / "Word-Clouds"
+        wordcloud_folder.mkdir(parents=True, exist_ok=True)
+        generate_wordclouds(
+            collection,
+            wordcloud_folder,
+            config.wordcloud,
+            progress_bar=True,
+        )
+        console.print(
+            f"\nDone [bold green]✅[/bold green] ! "
+            f"Check the output [bold blue]🔡☁️[/bold blue] here: {_safe_uri(wordcloud_folder)} 🔗\n"
+        )
 
     console.print(
         "ALL DONE [bold green]🎉🎉🎉[/bold green] !\n\n"

{convoviz-0.2.14 → convoviz-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "convoviz"
-version = "0.2.14"
+version = "0.3.1"
 description = "Get analytics and visualizations on your ChatGPT data!"
 license = "MIT"
 keywords = [
@@ -18,16 +18,18 @@ authors = [
     { name = "Mohamed Cheikh Sidiya", email = "mohamedcheikhsidiya77@gmail.com" }
 ]
 dependencies = [
-    "matplotlib>=3.9.4",
-    "nltk>=3.9.2",
     "orjson>=3.11.5",
-    "pillow>=11.3.0",
     "pydantic>=2.12.5",
     "pydantic-settings>=2.7.0",
     "questionary>=2.1.1",
     "rich>=14.2.0",
     "tqdm>=4.67.1",
     "typer>=0.21.0",
+]
+
+[project.optional-dependencies]
+viz = [
+    "nltk>=3.9.2",
     "wordcloud>=1.9.5",
 ]
 
@@ -66,6 +68,9 @@ dev = [
     "ruff>=0.14.10",
     "ty>=0.0.11",
     "types-tqdm>=4.67.0.20250809",
+    # Viz extras for testing (wordcloud pulls in matplotlib + pillow)
+    "nltk>=3.9.2",
+    "wordcloud>=1.9.5",
 ]
 
 [tool.ruff]

convoviz-0.2.14/convoviz/analysis/__init__.py

@@ -1,9 +0,0 @@
-"""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.14/convoviz/interactive.py

@@ -1,232 +0,0 @@
-"""Interactive configuration prompts using questionary."""
-
-from pathlib import Path
-from typing import Literal, Protocol, cast
-
-from questionary import Choice, Style, checkbox, select
-from questionary import path as qst_path
-from questionary import text as qst_text
-
-from convoviz.config import ConvovizConfig, get_default_config
-from convoviz.io.loaders import find_latest_zip, validate_zip
-from convoviz.utils import colormaps, default_font_path, font_names, font_path, validate_header
-
-CUSTOM_STYLE = Style(
-    [
-        ("qmark", "fg:#34eb9b bold"),
-        ("question", "bold fg:#e0e0e0"),
-        ("answer", "fg:#34ebeb bold"),
-        ("pointer", "fg:#e834eb bold"),
-        ("highlighted", "fg:#349ceb bold"),
-        ("selected", "fg:#34ebeb"),
-        ("separator", "fg:#eb3434"),
-        ("instruction", "fg:#eb9434"),
-        ("text", "fg:#b2eb34"),
-        ("disabled", "fg:#858585 italic"),
-    ]
-)
-
-
-class _QuestionaryPrompt[T](Protocol):
-    def ask(self) -> T | None: ...
-
-
-def _ask_or_cancel[T](prompt: _QuestionaryPrompt[T]) -> T:
-    """Ask a questionary prompt; treat Ctrl+C/Ctrl+D as cancelling the run.
-
-    questionary's `.ask()` returns `None` on cancellation (Ctrl+C / Ctrl+D). We
-    convert that to `KeyboardInterrupt` so callers can abort the whole
-    interactive session with a single Ctrl+C.
-    """
-
-    result = prompt.ask()
-    if result is None:
-        raise KeyboardInterrupt
-    return result
-
-
-def _validate_input_path(raw: str) -> bool | str:
-    path = Path(raw)
-    if not path.exists():
-        return "Path must exist"
-
-    if path.is_dir():
-        if (path / "conversations.json").exists():
-            return True
-        return "Directory must contain conversations.json"
-
-    if path.suffix.lower() == ".json":
-        return True
-
-    if path.suffix.lower() == ".zip":
-        return True if validate_zip(path) else "ZIP must contain conversations.json"
-
-    return "Input must be a .zip, a .json, or a directory containing conversations.json"
-
-
-def run_interactive_config(initial_config: ConvovizConfig | None = None) -> ConvovizConfig:
-    """Run interactive prompts to configure convoviz.
-
-    Args:
-        initial_config: Optional starting configuration (uses defaults if None)
-
-    Returns:
-        Updated configuration based on user input
-    """
-    config = initial_config or get_default_config()
-
-    # Set sensible defaults if not already set
-    if not config.input_path:
-        latest = find_latest_zip()
-        if latest:
-            config.input_path = latest
-
-    if not config.wordcloud.font_path:
-        config.wordcloud.font_path = default_font_path()
-
-    # Prompt for input path
-    input_default = str(config.input_path) if config.input_path else ""
-    input_result: str = _ask_or_cancel(
-        qst_path(
-            "Enter the path to the export ZIP, conversations JSON, or extracted directory:",
-            default=input_default,
-            validate=_validate_input_path,
-            style=CUSTOM_STYLE,
-        )
-    )
-
-    if input_result:
-        config.input_path = Path(input_result)
-
-    # Prompt for output folder
-    output_result: str = _ask_or_cancel(
-        qst_path(
-            "Enter the path to the output folder:",
-            default=str(config.output_folder),
-            style=CUSTOM_STYLE,
-        )
-    )
-
-    if output_result:
-        config.output_folder = Path(output_result)
-
-    # Prompt for author headers
-    headers = config.message.author_headers
-    for role in ["user", "assistant"]:
-        current = getattr(headers, role)
-        result: str = _ask_or_cancel(
-            qst_text(
-                f"Enter the message header for '{role}':",
-                default=current,
-                validate=lambda t: validate_header(t)
-                or "Must be a valid markdown header (e.g., # Title)",
-                style=CUSTOM_STYLE,
-            )
-        )
-        if result:
-            setattr(headers, role, result)
-
-    # Prompt for markdown flavor
-    flavor_result = cast(
-        Literal["standard", "obsidian"],
-        _ask_or_cancel(
-            select(
-                "Select the markdown flavor:",
-                choices=["standard", "obsidian"],
-                default=config.conversation.markdown.flavor,
-                style=CUSTOM_STYLE,
-            )
-        ),
-    )
-
-    if flavor_result:
-        config.conversation.markdown.flavor = flavor_result
-
-    # Prompt for YAML headers
-    yaml_config = config.conversation.yaml
-    yaml_choices = [
-        Choice(title=field, checked=getattr(yaml_config, field))
-        for field in [
-            "title",
-            "tags",
-            "chat_link",
-            "create_time",
-            "update_time",
-            "model",
-            "used_plugins",
-            "message_count",
-            "content_types",
-            "custom_instructions",
-        ]
-    ]
-
-    selected: list[str] = _ask_or_cancel(
-        checkbox(
-            "Select YAML metadata headers to include:",
-            choices=yaml_choices,
-            style=CUSTOM_STYLE,
-        )
-    )
-
-    selected_set = set(selected)
-    for field_name in [
-        "title",
-        "tags",
-        "chat_link",
-        "create_time",
-        "update_time",
-        "model",
-        "used_plugins",
-        "message_count",
-        "content_types",
-        "custom_instructions",
-    ]:
-        setattr(yaml_config, field_name, field_name in selected_set)
-
-    # Prompt for font
-    available_fonts = font_names()
-    if available_fonts:
-        current_font = (
-            config.wordcloud.font_path.stem if config.wordcloud.font_path else available_fonts[0]
-        )
-        font_result: str = _ask_or_cancel(
-            select(
-                "Select the font for word clouds:",
-                choices=available_fonts,
-                default=current_font if current_font in available_fonts else available_fonts[0],
-                style=CUSTOM_STYLE,
-            )
-        )
-
-        if font_result:
-            config.wordcloud.font_path = font_path(font_result)
-
-    # Prompt for colormap
-    available_colormaps = colormaps()
-    if available_colormaps:
-        colormap_result: str = _ask_or_cancel(
-            select(
-                "Select the color theme for word clouds:",
-                choices=available_colormaps,
-                default=config.wordcloud.colormap
-                if config.wordcloud.colormap in available_colormaps
-                else available_colormaps[0],
-                style=CUSTOM_STYLE,
-            )
-        )
-
-        if colormap_result:
-            config.wordcloud.colormap = colormap_result
-
-    # Prompt for custom stopwords
-    stopwords_result: str = _ask_or_cancel(
-        qst_text(
-            "Enter custom stopwords (comma-separated):",
-            default=config.wordcloud.custom_stopwords,
-            style=CUSTOM_STYLE,
-        )
-    )
-
-    config.wordcloud.custom_stopwords = stopwords_result
-
-    return config