convoviz 0.2.12__py3-none-any.whl → 0.4.7__py3-none-any.whl

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

@@ -1,9 +1,22 @@
-"""Data analysis and visualization for convoviz."""
+"""Data analysis and visualization for convoviz.
 
-from convoviz.analysis.graphs import generate_week_barplot
-from convoviz.analysis.wordcloud import generate_wordcloud
+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}")

convoviz/analysis/graphs.py

@@ -8,6 +8,7 @@ Goals:
 
 from __future__ import annotations
 
+import logging
 from collections import defaultdict
 from collections.abc import Callable, Iterable
 from datetime import UTC, datetime
@@ -25,6 +26,8 @@ from convoviz.config import GraphConfig, get_default_config
 from convoviz.models import ConversationCollection
 from convoviz.utils import get_asset_path
 
+logger = logging.getLogger(__name__)
+
 WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
 
 
@@ -347,7 +350,9 @@ def generate_length_histogram(
         color="#cf222e",
     )
 
-    ax.set_title("Conversation length (user prompts)", fontproperties=font_prop, fontsize=14, pad=14)
+    ax.set_title(
+        "Conversation length (user prompts)", fontproperties=font_prop, fontsize=14, pad=14
+    )
     ax.set_xlabel("User prompts per conversation", fontproperties=font_prop)
     ax.set_ylabel("Conversations", fontproperties=font_prop)
     ax.set_xlim(left=0, right=cap)
@@ -619,7 +624,9 @@ def generate_summary_dashboard(
         locator = mdates.AutoDateLocator(minticks=4, maxticks=10)
         ax_ts.xaxis.set_major_locator(locator)
         ax_ts.xaxis.set_major_formatter(mdates.ConciseDateFormatter(locator))
-        ax_ts.set_title("Monthly activity (user prompts)", fontproperties=font_prop, fontsize=13, pad=10)
+        ax_ts.set_title(
+            "Monthly activity (user prompts)", fontproperties=font_prop, fontsize=13, pad=10
+        )
         ax_ts.set_ylabel("User prompts", fontproperties=font_prop)
         ax_ts.set_xlabel(f"Month ({_tz_label(cfg)})", fontproperties=font_prop)
         _apply_tick_font(ax_ts, font_prop)
@@ -738,14 +745,31 @@ def generate_summary_graphs(
     cfg = config or get_default_config().graph
 
     user_ts = collection.timestamps("user")
+    logger.info(f"Generating summary graphs to {output_dir}")
 
     tasks: list[tuple[str, str, Callable[[], Figure]]] = [
         ("Overview", "overview.png", lambda: generate_summary_dashboard(collection, cfg)),
-        ("Activity heatmap", "activity_heatmap.png", lambda: generate_activity_heatmap(collection, cfg)),
-        ("Daily activity", "daily_activity.png", lambda: generate_daily_activity_lineplot(collection, cfg)),
-        ("Monthly activity", "monthly_activity.png", lambda: generate_monthly_activity_barplot(collection, cfg)),
+        (
+            "Activity heatmap",
+            "activity_heatmap.png",
+            lambda: generate_activity_heatmap(collection, cfg),
+        ),
+        (
+            "Daily activity",
+            "daily_activity.png",
+            lambda: generate_daily_activity_lineplot(collection, cfg),
+        ),
+        (
+            "Monthly activity",
+            "monthly_activity.png",
+            lambda: generate_monthly_activity_barplot(collection, cfg),
+        ),
         ("Model usage", "model_usage.png", lambda: generate_model_piechart(collection, cfg)),
-        ("Conversation lengths", "conversation_lengths.png", lambda: generate_length_histogram(collection, cfg)),
+        (
+            "Conversation lengths",
+            "conversation_lengths.png",
+            lambda: generate_length_histogram(collection, cfg),
+        ),
         (
             "Conversation lifetimes",
             "conversation_lifetimes.png",

convoviz/analysis/wordcloud.py

@@ -1,5 +1,8 @@
 """Word cloud generation for conversation text."""
 
+import logging
+import os
+from concurrent.futures import ProcessPoolExecutor
 from functools import lru_cache
 from pathlib import Path
 
@@ -13,6 +16,8 @@ from wordcloud import WordCloud
 from convoviz.config import WordCloudConfig
 from convoviz.models import ConversationCollection
 
+logger = logging.getLogger(__name__)
+
 # Languages for stopwords
 STOPWORD_LANGUAGES = [
     "arabic",
@@ -110,6 +115,25 @@ def generate_wordcloud(text: str, config: WordCloudConfig) -> Image:
     return result
 
 
+def _generate_and_save_wordcloud(args: tuple[str, str, Path, WordCloudConfig]) -> bool:
+    """Worker function for parallel wordcloud generation.
+
+    Must be at module level for pickling by ProcessPoolExecutor.
+
+    Args:
+        args: Tuple of (text, filename, output_dir, config)
+
+    Returns:
+        True if wordcloud was generated, False if skipped (empty text)
+    """
+    text, filename, output_dir, config = args
+    if not text.strip():
+        return False
+    img = generate_wordcloud(text, config)
+    img.save(output_dir / filename, optimize=True)
+    return True
+
+
 def generate_wordclouds(
     collection: ConversationCollection,
     output_dir: Path,
@@ -119,6 +143,8 @@ def generate_wordclouds(
 ) -> None:
     """Generate word clouds for weekly, monthly, and yearly groupings.
 
+    Uses parallel processing to speed up generation on multi-core systems.
+
     Args:
         collection: Collection of conversations
         output_dir: Directory to save the word clouds
@@ -126,40 +152,53 @@ def generate_wordclouds(
         progress_bar: Whether to show progress bars
     """
     output_dir.mkdir(parents=True, exist_ok=True)
+    logger.info(f"Generating wordclouds to {output_dir}")
 
     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,
-    ):
+    # Pre-load/download NLTK stopwords in the main process to avoid race conditions in workers
+    load_nltk_stopwords()
+
+    # Build list of all tasks: (text, filename, output_dir, config)
+    tasks: list[tuple[str, str, Path, WordCloudConfig]] = []
+
+    for week, group in week_groups.items():
         text = group.plaintext("user", "assistant")
-        if text.strip():
-            img = generate_wordcloud(text, config)
-            # Format: 2024-W15.png (ISO week format)
-            img.save(output_dir / f"{week.strftime('%Y-W%W')}.png", optimize=True)
-
-    for month, group in tqdm(
-        month_groups.items(),
-        desc="Creating monthly wordclouds 🔡☁️",
-        disable=not progress_bar,
-    ):
+        # Format: 2024-W15.png (ISO week format)
+        filename = f"{week.strftime('%Y-W%W')}.png"
+        tasks.append((text, filename, output_dir, config))
+
+    for month, group in month_groups.items():
         text = group.plaintext("user", "assistant")
-        if text.strip():
-            img = generate_wordcloud(text, config)
-            # Format: 2024-03-March.png (consistent with folder naming)
-            img.save(output_dir / f"{month.strftime('%Y-%m-%B')}.png", optimize=True)
-
-    for year, group in tqdm(
-        year_groups.items(),
-        desc="Creating yearly wordclouds 🔡☁️",
-        disable=not progress_bar,
-    ):
+        # Format: 2024-03-March.png (consistent with folder naming)
+        filename = f"{month.strftime('%Y-%m-%B')}.png"
+        tasks.append((text, filename, output_dir, config))
+
+    for year, group in year_groups.items():
         text = group.plaintext("user", "assistant")
-        if text.strip():
-            img = generate_wordcloud(text, config)
-            # Format: 2024.png
-            img.save(output_dir / f"{year.strftime('%Y')}.png", optimize=True)
+        # Format: 2024.png
+        filename = f"{year.strftime('%Y')}.png"
+        tasks.append((text, filename, output_dir, config))
+
+    if not tasks:
+        return
+
+    # Determine worker count: use config if set, otherwise half CPU count (min 1)
+    max_workers = config.max_workers
+    if max_workers is None:
+        cpu_count = os.cpu_count() or 2
+        max_workers = max(1, cpu_count // 2)
+
+    # Use parallel processing for speedup on multi-core systems
+    logger.debug(f"Starting wordcloud generation with {max_workers} workers for {len(tasks)} tasks")
+    with ProcessPoolExecutor(max_workers=max_workers) as executor:
+        list(
+            tqdm(
+                executor.map(_generate_and_save_wordcloud, tasks),
+                total=len(tasks),
+                desc="Creating wordclouds 🔡☁️",
+                disable=not progress_bar,
+            )
+        )

convoviz/cli.py

@@ -1,14 +1,18 @@
 """Command-line interface for convoviz."""
 
+import logging
+from importlib.metadata import version as get_version
 from pathlib import Path
 
 import typer
 from rich.console import Console
+from rich.markup import escape
 
-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
+from convoviz.logging_config import setup_logging
 from convoviz.pipeline import run_pipeline
 from convoviz.utils import default_font_path
 
@@ -19,6 +23,13 @@ app = typer.Typer(
 console = Console()
 
 
+def _version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        console.print(f"convoviz {get_version('convoviz')}")
+        raise typer.Exit()
+
+
 @app.callback(invoke_without_command=True)
 def run(
     ctx: typer.Context,
@@ -38,6 +49,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",
@@ -50,8 +67,34 @@ def run(
         "-i/-I",
         help="Force interactive mode on or off.",
     ),
+    verbose: int = typer.Option(
+        0,
+        "--verbose",
+        "-v",
+        help="Increase verbosity. Use -vv for debug.",
+        count=True,
+    ),
+    log_file: Path | None = typer.Option(
+        None,
+        "--log-file",
+        help="Path to log file. Defaults to a temporary file.",
+    ),
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
 ) -> None:
     """Convert ChatGPT export data to markdown and generate visualizations."""
+    # Setup logging immediately
+    log_path = setup_logging(verbose, log_file)
+    logger = logging.getLogger("convoviz.cli")
+    console.print(f"[dim]Logging to: {log_path}[/dim]")
+    logger.debug(f"Logging initialized. Output: {log_path}")
+
     if ctx.invoked_subcommand is not None:
         return
 
@@ -63,6 +106,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
 
@@ -105,10 +150,13 @@ def run(
     try:
         run_pipeline(config)
     except (InvalidZipError, ConfigurationError) as e:
-        console.print(f"[bold red]Error:[/bold red] {e}")
+        logger.error(f"Known error: {e}")
+        console.print(f"[bold red]Error:[/bold red] {escape(str(e))}")
         raise typer.Exit(code=1) from None
     except Exception as e:
-        console.print(f"[bold red]Unexpected error:[/bold red] {e}")
+        logger.exception("Unexpected error occurred")
+        console.print(f"[bold red]Unexpected error:[/bold red] {escape(str(e))}")
+        console.print(f"[dim]See log file for details: {log_path}[/dim]")
         raise typer.Exit(code=1) from None
 
 

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."""
 
@@ -26,7 +38,7 @@ class AuthorHeaders(BaseModel):
 class MarkdownConfig(BaseModel):
     """Configuration for markdown output."""
 
-    latex_delimiters: Literal["default", "dollars"] = "default"
+    latex_delimiters: Literal["default", "dollars"] = "dollars"
     flavor: Literal["standard", "obsidian"] = "standard"
 
 
@@ -39,10 +51,13 @@ class YAMLConfig(BaseModel):
     create_time: bool = True
     update_time: bool = True
     model: bool = True
-    used_plugins: bool = True
+    used_plugins: bool = False
     message_count: bool = True
-    content_types: bool = True
-    custom_instructions: bool = True
+    content_types: bool = False
+    content_types: bool = False
+    custom_instructions: bool = False
+    is_starred: bool = False
+    voice: bool = False
 
 
 class ConversationConfig(BaseModel):
@@ -70,6 +85,7 @@ class WordCloudConfig(BaseModel):
     include_numbers: bool = False
     width: int = 600
     height: int = 600
+    max_workers: int | None = None  # None = use half CPU count
 
 
 class GraphConfig(BaseModel):
@@ -92,6 +108,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)