convoviz 0.3.8__tar.gz → 0.4.0__tar.gz

{convoviz-0.3.8 → convoviz-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convoviz
-Version: 0.3.8
+Version: 0.4.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
@@ -19,7 +19,7 @@ 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
+Project-URL: Repository, https://github.com/mohamed-chs/convoviz
 Provides-Extra: viz
 Description-Content-Type: text/markdown
 
@@ -45,29 +45,23 @@ See examples [here](demo).
 
 ### 2. Install the tool 🛠
 
-First, install [uv](https://github.com/astral-sh/uv) (if you don't have it):
+One command to install everything:
 
-MacOS / Linux:
+**Linux / macOS:**
 
 ```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.sh | bash
 ```
 
-Windows:
+**Windows (PowerShell):**
 
 ```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+irm https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.ps1 | iex
 ```
 
-Then install convoviz:
+This installs [uv](https://github.com/astral-sh/uv) (if needed) and convoviz with graphs and word clouds.
 
-```bash
-uv tool install "convoviz[viz]"
-```
-
-The `[viz]` extra includes graphs and word clouds. Skip it for a faster markdown-only install.
-
-### Alternative: pip
+#### Alternative: pip
 
 ```bash
 python3 -m venv .venv
@@ -106,6 +100,8 @@ Options: `markdown`, `graphs`, `wordclouds`. In interactive mode, you'll be prom
 - `--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.
+- Use `--verbose` or `-v` for detailed logging (use `-vv` for debug logs).
+- Use `--log-file` to specify a custom log file (logs default to a temporary file if not specified).
 
 For more options, run:
 
@@ -123,7 +119,7 @@ And that's it! After running the script, head over to the output folder to see y
 
 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))
+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/convoviz/issues))
 
 And if you've had a great experience, consider giving the project a star ⭐. It keeps me motivated and helps others discover it!
 

{convoviz-0.3.8 → convoviz-0.4.0}/README.md

@@ -20,29 +20,23 @@ See examples [here](demo).
 
 ### 2. Install the tool 🛠
 
-First, install [uv](https://github.com/astral-sh/uv) (if you don't have it):
+One command to install everything:
 
-MacOS / Linux:
+**Linux / macOS:**
 
 ```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.sh | bash
 ```
 
-Windows:
+**Windows (PowerShell):**
 
 ```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+irm https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.ps1 | iex
 ```
 
-Then install convoviz:
+This installs [uv](https://github.com/astral-sh/uv) (if needed) and convoviz with graphs and word clouds.
 
-```bash
-uv tool install "convoviz[viz]"
-```
-
-The `[viz]` extra includes graphs and word clouds. Skip it for a faster markdown-only install.
-
-### Alternative: pip
+#### Alternative: pip
 
 ```bash
 python3 -m venv .venv
@@ -81,6 +75,8 @@ Options: `markdown`, `graphs`, `wordclouds`. In interactive mode, you'll be prom
 - `--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.
+- Use `--verbose` or `-v` for detailed logging (use `-vv` for debug logs).
+- Use `--log-file` to specify a custom log file (logs default to a temporary file if not specified).
 
 For more options, run:
 
@@ -98,7 +94,7 @@ And that's it! After running the script, head over to the output folder to see y
 
 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))
+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/convoviz/issues))
 
 And if you've had a great experience, consider giving the project a star ⭐. It keeps me motivated and helps others discover it!
 

{convoviz-0.3.8 → convoviz-0.4.0}/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"]
 
 
@@ -742,6 +745,7 @@ 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)),

{convoviz-0.3.8 → convoviz-0.4.0}/convoviz/analysis/wordcloud.py

@@ -1,5 +1,6 @@
 """Word cloud generation for conversation text."""
 
+import logging
 import os
 from concurrent.futures import ProcessPoolExecutor
 from functools import lru_cache
@@ -15,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",
@@ -149,6 +152,7 @@ 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()
@@ -188,6 +192,7 @@ def generate_wordclouds(
         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(

{convoviz-0.3.8 → convoviz-0.4.0}/convoviz/cli.py

@@ -1,5 +1,6 @@
 """Command-line interface for convoviz."""
 
+import logging
 from pathlib import Path
 
 import typer
@@ -10,6 +11,7 @@ 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
 
@@ -57,8 +59,26 @@ 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.",
+    ),
 ) -> 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
 
@@ -114,10 +134,13 @@ def run(
     try:
         run_pipeline(config)
     except (InvalidZipError, ConfigurationError) as 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:
+        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-0.3.8 → convoviz-0.4.0}/convoviz/interactive.py

@@ -1,5 +1,6 @@
 """Interactive configuration prompts using questionary."""
 
+import logging
 from pathlib import Path
 from typing import Literal, Protocol, cast
 
@@ -26,6 +27,8 @@ CUSTOM_STYLE = Style(
     ]
 )
 
+logger = logging.getLogger(__name__)
+
 
 class _QuestionaryPrompt[T](Protocol):
     def ask(self) -> T | None: ...
@@ -74,6 +77,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
         Updated configuration based on user input
     """
     config = initial_config or get_default_config()
+    logger.info("Starting interactive configuration")
 
     # Set sensible defaults if not already set
     if not config.input_path:
@@ -97,6 +101,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
 
     if input_result:
         config.input_path = Path(input_result)
+    logger.debug(f"User selected input: {config.input_path}")
 
     # Prompt for output folder
     output_result: str = _ask_or_cancel(
@@ -109,6 +114,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
 
     if output_result:
         config.output_folder = Path(output_result)
+    logger.debug(f"User selected output: {config.output_folder}")
 
     # Prompt for outputs to generate
     output_choices = [
@@ -126,6 +132,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
     )
 
     config.outputs = set(selected_outputs) if selected_outputs else set()
+    logger.debug(f"User selected outputs: {config.outputs}")
 
     # Prompt for markdown settings (only if markdown output is selected)
     if OutputKind.MARKDOWN in config.outputs:
@@ -144,6 +151,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
             )
             if result:
                 setattr(headers, role, result)
+        logger.debug(f"User selected headers: {headers}")
 
         # Prompt for markdown flavor
         flavor_result = cast(
@@ -160,6 +168,7 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
 
         if flavor_result:
             config.conversation.markdown.flavor = flavor_result
+        logger.debug(f"User selected flavor: {config.conversation.markdown.flavor}")
 
         # Prompt for YAML headers
         yaml_config = config.conversation.yaml

{convoviz-0.3.8 → convoviz-0.4.0}/convoviz/io/assets.py

@@ -1,8 +1,11 @@
 "Asset management functions."
 
+import logging
 import shutil
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 
 def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
     """Find the actual file for a given asset ID in the source directory.
@@ -26,6 +29,7 @@ def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
     # 1. Try exact match
     exact_path = (source_dir / asset_id).resolve()
     if exact_path.exists() and exact_path.is_file() and exact_path.is_relative_to(source_dir):
+        logger.debug(f"Resolved asset (exact): {asset_id} -> {exact_path}")
         return exact_path
 
     # 2. Try prefix match in root
@@ -37,6 +41,7 @@ def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
             if p.is_file() and p.resolve().is_relative_to(source_dir)
         ]
         if files:
+            logger.debug(f"Resolved asset (prefix root): {asset_id} -> {files[0]}")
             return files[0]
     except Exception:
         pass
@@ -53,6 +58,7 @@ def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
                 if p.is_file() and p.resolve().is_relative_to(dalle_dir)
             ]
             if files:
+                logger.debug(f"Resolved asset (dalle): {asset_id} -> {files[0]}")
                 return files[0]
         except Exception:
             pass
@@ -69,6 +75,7 @@ def resolve_asset_path(source_dir: Path, asset_id: str) -> Path | None:
                     if p.is_file() and p.resolve().is_relative_to(user_dir)
                 ]
                 if files:
+                    logger.debug(f"Resolved asset (user dir): {asset_id} -> {files[0]}")
                     return files[0]
     except Exception:
         pass
@@ -92,7 +99,11 @@ def copy_asset(source_path: Path, dest_dir: Path) -> str:
     dest_path = assets_dir / source_path.name
 
     if not dest_path.exists():
-        shutil.copy2(source_path, dest_path)
+        try:
+            shutil.copy2(source_path, dest_path)
+            logger.debug(f"Copied asset: {source_path.name}")
+        except Exception as e:
+            logger.warning(f"Failed to copy asset {source_path}: {e}")
 
     # Return forward-slash path for Markdown compatibility even on Windows
     return f"assets/{source_path.name}"

{convoviz-0.3.8 → convoviz-0.4.0}/convoviz/io/loaders.py

@@ -1,5 +1,6 @@
 """Loading functions for conversations and collections."""
 
+import logging
 from pathlib import Path, PurePosixPath
 from zipfile import ZipFile
 
@@ -8,6 +9,8 @@ from orjson import loads
 from convoviz.exceptions import InvalidZipError
 from convoviz.models import Conversation, ConversationCollection
 
+logger = logging.getLogger(__name__)
+
 
 def _is_safe_zip_member_name(name: str) -> bool:
     """Return True if a ZIP entry name is safe to extract.
@@ -46,6 +49,7 @@ def extract_archive(filepath: Path) -> Path:
     """
     folder = filepath.with_suffix("")
     folder.mkdir(parents=True, exist_ok=True)
+    logger.info(f"Extracting archive: {filepath} to {folder}")
 
     with ZipFile(filepath) as zf:
         for member in zf.infolist():
@@ -115,6 +119,7 @@ def load_collection_from_json(filepath: Path | str) -> ConversationCollection:
         Loaded ConversationCollection object
     """
     filepath = Path(filepath)
+    logger.debug(f"Loading collection from JSON: {filepath}")
     with filepath.open(encoding="utf-8") as f:
         data = loads(f.read())
 

{convoviz-0.3.8 → convoviz-0.4.0}/convoviz/io/writers.py

@@ -1,5 +1,6 @@
 """Writing functions for conversations and collections."""
 
+import logging
 from os import utime as os_utime
 from pathlib import Path
 from urllib.parse import quote
@@ -13,6 +14,8 @@ from convoviz.models import Conversation, ConversationCollection
 from convoviz.renderers import render_conversation
 from convoviz.utils import sanitize
 
+logger = logging.getLogger(__name__)
+
 # Month names for folder naming
 _MONTH_NAMES = [
     "January",
@@ -102,6 +105,7 @@ def save_conversation(
     markdown = render_conversation(conversation, config, headers, asset_resolver=asset_resolver)
     with final_path.open("w", encoding="utf-8") as f:
         f.write(markdown)
+    logger.debug(f"Saved conversation: {final_path}")
 
     # Set modification time
     timestamp = conversation.update_time.timestamp()
@@ -135,6 +139,7 @@ def _generate_year_index(year_dir: Path, year: str) -> None:
 
     index_path = year_dir / "_index.md"
     index_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    logger.debug(f"Generated year index: {index_path}")
 
 
 def _generate_month_index(month_dir: Path, year: str, month: str) -> None:
@@ -162,6 +167,7 @@ def _generate_month_index(month_dir: Path, year: str, month: str) -> None:
 
     index_path = month_dir / "_index.md"
     index_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    logger.debug(f"Generated month index: {index_path}")
 
 
 def save_collection(

convoviz-0.4.0/convoviz/logging_config.py

@@ -0,0 +1,69 @@
+"""Logging configuration for convoviz."""
+
+import logging
+import tempfile
+from pathlib import Path
+
+from rich.logging import RichHandler
+
+
+def setup_logging(
+    verbosity: int = 0,
+    log_file: Path | None = None,
+) -> Path:
+    """Set up logging configuration.
+
+    Args:
+        verbosity: Level of verbosity (0=WARNING, 1=INFO, 2=DEBUG)
+        log_file: Path to log file. If None, a temporary file is created.
+
+    Returns:
+        Path to the log file used.
+    """
+    # clear existing handlers
+    root_logger = logging.getLogger()
+    root_logger.handlers.clear()
+
+    # Determine log level for console
+    if verbosity >= 2:
+        console_level = logging.DEBUG
+    elif verbosity >= 1:
+        console_level = logging.INFO
+    else:
+        console_level = logging.WARNING
+
+    # Console handler (Rich)
+    console_handler = RichHandler(
+        rich_tracebacks=True,
+        markup=True,
+        show_time=False,
+        show_path=False,
+    )
+    console_handler.setLevel(console_level)
+
+    # File handler
+    if log_file is None:
+        # Create temp file if not specified
+        with tempfile.NamedTemporaryFile(prefix="convoviz_", suffix=".log", delete=False) as tf:
+            log_file = Path(tf.name)
+
+    # Ensure parent dir exists
+    if not log_file.parent.exists():
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    file_handler = logging.FileHandler(log_file, encoding="utf-8")
+    file_handler.setLevel(logging.DEBUG)  # Always log DEBUG to file
+    file_formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    file_handler.setFormatter(file_formatter)
+
+    # Configure root logger
+    # We set root level to DEBUG so that the handlers can filter as they please
+    root_logger.setLevel(logging.DEBUG)
+    root_logger.addHandler(console_handler)
+    root_logger.addHandler(file_handler)
+
+    # Reduce noise from explicit libraries if necessary
+    logging.getLogger("matplotlib").setLevel(logging.WARNING)
+    logging.getLogger("PIL").setLevel(logging.WARNING)
+
+    return log_file

{convoviz-0.3.8 → convoviz-0.4.0}/convoviz/pipeline.py

@@ -1,5 +1,6 @@
 """Main processing pipeline for convoviz."""
 
+import logging
 from pathlib import Path
 from shutil import rmtree
 
@@ -15,6 +16,7 @@ from convoviz.io.loaders import (
 from convoviz.io.writers import save_collection
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def _safe_uri(path: Path) -> str:
@@ -46,6 +48,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
     if not input_path.exists():
         raise InvalidZipError(str(input_path), reason="File does not exist")
 
+    logger.info(f"Starting pipeline with input: {input_path}")
     console.print(f"Loading data from {input_path} [bold yellow]📂[/bold yellow] ...\n")
 
     # Load collection based on input type
@@ -62,6 +65,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
     else:
         # Assume zip
         collection = load_collection_from_zip(input_path)
+    logger.info(f"Loaded collection with {len(collection.conversations)} conversations")
 
     # Try to merge bookmarklet data if available
     bookmarklet_json = find_latest_bookmarklet_json()
@@ -70,6 +74,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
         try:
             bookmarklet_collection = load_collection_from_json(bookmarklet_json)
             collection.update(bookmarklet_collection)
+            logger.info("Merged bookmarklet data")
         except Exception as e:
             console.print(
                 f"[bold yellow]Warning:[/bold yellow] Failed to load bookmarklet data: {e}"
@@ -114,6 +119,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
             folder_organization=config.folder_organization,
             progress_bar=True,
         )
+        logger.info("Markdown generation complete")
         console.print(
             f"\nDone [bold green]✅[/bold green] ! "
             f"Check the output [bold blue]📄[/bold blue] here: {_safe_uri(markdown_folder)} 🔗\n"
@@ -138,6 +144,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
             config.graph,
             progress_bar=True,
         )
+        logger.info("Graph generation complete")
         console.print(
             f"\nDone [bold green]✅[/bold green] ! "
             f"Check the output [bold blue]📈[/bold blue] here: {_safe_uri(graph_folder)} 🔗\n"
@@ -162,6 +169,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
             config.wordcloud,
             progress_bar=True,
         )
+        logger.info("Wordcloud generation complete")
         console.print(
             f"\nDone [bold green]✅[/bold green] ! "
             f"Check the output [bold blue]🔡☁️[/bold blue] here: {_safe_uri(wordcloud_folder)} 🔗\n"
@@ -172,5 +180,5 @@ def run_pipeline(config: ConvovizConfig) -> None:
         f"Explore the full gallery [bold yellow]🖼️[/bold yellow] at: {_safe_uri(output_folder)} 🔗\n\n"
         "I hope you enjoy the outcome 🤞.\n\n"
         "If you appreciate it, kindly give the project a star 🌟 on GitHub:\n\n"
-        "➡️ https://github.com/mohamed-chs/chatgpt-history-export-to-md 🔗\n\n"
+        "➡️ https://github.com/mohamed-chs/convoviz 🔗\n\n"
     )

{convoviz-0.3.8 → convoviz-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "convoviz"
-version = "0.3.8"
+version = "0.4.0"
 description = "Get analytics and visualizations on your ChatGPT data!"
 license = "MIT"
 keywords = [
@@ -34,7 +34,7 @@ viz = [
 ]
 
 [project.urls]
-Repository = "https://github.com/mohamed-chs/chatgpt-history-export-to-md"
+Repository = "https://github.com/mohamed-chs/convoviz"
 
 [build-system]
 requires = ["uv_build"]