convoviz 0.2.4__py3-none-any.whl → 0.2.6__py3-none-any.whl

convoviz/config.py

@@ -19,7 +19,7 @@ class MarkdownConfig(BaseModel):
     """Configuration for markdown output."""
 
     latex_delimiters: Literal["default", "dollars"] = "default"
-    flavor: Literal["obsidian", "standard"] = "obsidian"
+    flavor: Literal["obsidian", "standard"] = "standard"
 
 
 class YAMLConfig(BaseModel):
@@ -74,6 +74,8 @@ class GraphConfig(BaseModel):
     figsize: tuple[int, int] = (10, 6)
     dpi: int = 300
     timezone: Literal["utc", "local"] = "local"
+    generate_monthly_breakdowns: bool = False
+    generate_yearly_breakdowns: bool = False
 
 
 class ConvovizConfig(BaseModel):

convoviz/interactive.py

@@ -1,6 +1,7 @@
 """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
@@ -25,6 +26,23 @@ CUSTOM_STYLE = Style(
     ]
 )
 
+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)
@@ -67,22 +85,26 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
 
     # Prompt for input path
     input_default = str(config.input_path) if config.input_path else ""
-    input_result = qst_path(
-        "Enter the path to the export ZIP, conversations JSON, or extracted directory:",
-        default=input_default,
-        validate=_validate_input_path,
-        style=CUSTOM_STYLE,
-    ).ask()
+    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 = qst_path(
-        "Enter the path to the output folder:",
-        default=str(config.output_folder),
-        style=CUSTOM_STYLE,
-    ).ask()
+    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)
@@ -91,34 +113,46 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
     headers = config.message.author_headers
     for role in ["system", "user", "assistant", "tool"]:
         current = getattr(headers, role)
-        result = 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,
-        ).ask()
+        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 LaTeX delimiters
-    latex_result = select(
-        "Select the LaTeX math delimiters:",
-        choices=["default", "dollars"],
-        default=config.conversation.markdown.latex_delimiters,
-        style=CUSTOM_STYLE,
-    ).ask()
+    latex_result = cast(
+        Literal["default", "dollars"],
+        _ask_or_cancel(
+            select(
+                "Select the LaTeX math delimiters:",
+                choices=["default", "dollars"],
+                default=config.conversation.markdown.latex_delimiters,
+                style=CUSTOM_STYLE,
+            )
+        ),
+    )
 
     if latex_result:
         config.conversation.markdown.latex_delimiters = latex_result
 
     # Prompt for markdown flavor
-    flavor_result = select(
-        "Select the markdown flavor:",
-        choices=["obsidian", "standard"],
-        default=config.conversation.markdown.flavor,
-        style=CUSTOM_STYLE,
-    ).ask()
+    flavor_result = cast(
+        Literal["obsidian", "standard"],
+        _ask_or_cancel(
+            select(
+                "Select the markdown flavor:",
+                choices=["obsidian", "standard"],
+                default=config.conversation.markdown.flavor,
+                style=CUSTOM_STYLE,
+            )
+        ),
+    )
 
     if flavor_result:
         config.conversation.markdown.flavor = flavor_result
@@ -141,27 +175,28 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
         ]
     ]
 
-    selected = checkbox(
-        "Select YAML metadata headers to include:",
-        choices=yaml_choices,
-        style=CUSTOM_STYLE,
-    ).ask()
-
-    if selected is not None:
-        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)
+    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()
@@ -169,12 +204,14 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
         current_font = (
             config.wordcloud.font_path.stem if config.wordcloud.font_path else available_fonts[0]
         )
-        font_result = 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,
-        ).ask()
+        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)
@@ -182,26 +219,29 @@ def run_interactive_config(initial_config: ConvovizConfig | None = None) -> Conv
     # Prompt for colormap
     available_colormaps = colormaps()
     if available_colormaps:
-        colormap_result = 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,
-        ).ask()
+        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 = qst_text(
-        "Enter custom stopwords (comma-separated):",
-        default=config.wordcloud.custom_stopwords,
-        style=CUSTOM_STYLE,
-    ).ask()
-
-    if stopwords_result is not None:
-        config.wordcloud.custom_stopwords = stopwords_result
+    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/models/conversation.py

@@ -36,22 +36,29 @@ class Conversation(BaseModel):
 
     @property
     def all_message_nodes(self) -> list[Node]:
-        """Get all nodes that have messages (including all branches)."""
+        """Get all nodes that have messages (including hidden/internal ones)."""
         return [node for node in self.node_mapping.values() if node.has_message]
 
-    def nodes_by_author(self, *authors: AuthorRole) -> list[Node]:
+    @property
+    def visible_message_nodes(self) -> list[Node]:
+        """Get all nodes that have *visible* (non-hidden) messages."""
+        return [
+            node
+            for node in self.node_mapping.values()
+            if node.has_message and node.message is not None and not node.message.is_hidden
+        ]
+
+    def nodes_by_author(self, *authors: AuthorRole, include_hidden: bool = False) -> list[Node]:
         """Get nodes with messages from specified authors.
 
         Args:
             *authors: Author roles to filter by. Defaults to ("user",) if empty.
+            include_hidden: Whether to include hidden/internal messages.
         """
         if not authors:
             authors = ("user",)
-        return [
-            node
-            for node in self.all_message_nodes
-            if node.message and node.message.author.role in authors
-        ]
+        nodes = self.all_message_nodes if include_hidden else self.visible_message_nodes
+        return [node for node in nodes if node.message and node.message.author.role in authors]
 
     @property
     def leaf_count(self) -> int:
@@ -65,9 +72,13 @@ class Conversation(BaseModel):
 
     @property
     def content_types(self) -> list[str]:
-        """Get all unique content types in the conversation."""
+        """Get all unique content types in the conversation (excluding hidden messages)."""
         return list(
-            {node.message.content.content_type for node in self.all_message_nodes if node.message}
+            {
+                node.message.content.content_type
+                for node in self.visible_message_nodes
+                if node.message
+            }
         )
 
     def message_count(self, *authors: AuthorRole) -> int:

convoviz/renderers/markdown.py

@@ -8,6 +8,24 @@ from convoviz.exceptions import MessageContentError
 from convoviz.models import Conversation, Node
 from convoviz.renderers.yaml import render_yaml_header
 
+# Length for shortened node IDs in markdown output (similar to Git short hashes)
+SHORT_ID_LENGTH = 8
+
+
+def shorten_id(node_id: str) -> str:
+    """Shorten a node ID for display in markdown.
+
+    Takes the first 8 characters of the ID, which is typically the first
+    segment of a UUID and provides sufficient uniqueness within a conversation.
+
+    Args:
+        node_id: The full node ID (often a UUID)
+
+    Returns:
+        Shortened ID string
+    """
+    return node_id[:SHORT_ID_LENGTH]
+
 
 def close_code_blocks(text: str) -> str:
     """Ensure all code blocks in the text are properly closed.
@@ -81,7 +99,7 @@ def render_message_header(role: str, headers: AuthorHeaders) -> str:
     return header_map.get(role, f"### {role.title()}")
 
 
-def render_node_header(node: Node, headers: AuthorHeaders, flavor: str = "obsidian") -> str:
+def render_node_header(node: Node, headers: AuthorHeaders, flavor: str = "standard") -> str:
     """Render the header section of a node.
 
     Includes the node ID, parent link, and message author header.
@@ -105,15 +123,15 @@ def render_node_header(node: Node, headers: AuthorHeaders, flavor: str = "obsidi
 
     # Add parent link if parent has a message
     if node.parent_node and node.parent_node.message:
-        parts.append(f"[⬆️](#^{node.parent_node.id})")
+        parts.append(f"[⬆️](#^{shorten_id(node.parent_node.id)})")
 
     author_header = render_message_header(node.message.author.role, headers)
-    parts.append(f"{author_header} ^{node.id}")
+    parts.append(f"{author_header} ^{shorten_id(node.id)}")
 
     return "\n".join(parts) + "\n"
 
 
-def render_node_footer(node: Node, flavor: str = "obsidian") -> str:
+def render_node_footer(node: Node, flavor: str = "standard") -> str:
     """Render the footer section of a node with child links.
 
     Args:
@@ -127,9 +145,11 @@ def render_node_footer(node: Node, flavor: str = "obsidian") -> str:
         return ""
 
     if len(node.children_nodes) == 1:
-        return f"\n[⬇️](#^{node.children_nodes[0].id})\n"
+        return f"\n[⬇️](#^{shorten_id(node.children_nodes[0].id)})\n"
 
-    links = " | ".join(f"[{i + 1} ⬇️](#^{child.id})" for i, child in enumerate(node.children_nodes))
+    links = " | ".join(
+        f"[{i + 1} ⬇️](#^{shorten_id(child.id)})" for i, child in enumerate(node.children_nodes)
+    )
     return f"\n{links}\n"
 
 
@@ -138,7 +158,7 @@ def render_node(
     headers: AuthorHeaders,
     use_dollar_latex: bool = False,
     asset_resolver: Callable[[str], str | None] | None = None,
-    flavor: str = "obsidian",
+    flavor: str = "standard",
 ) -> str:
     """Render a complete node as markdown.
 

{convoviz-0.2.4.dist-info → convoviz-0.2.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convoviz
-Version: 0.2.4
+Version: 0.2.6
 Summary: Get analytics and visualizations on your ChatGPT data!
 Keywords: markdown,chatgpt,openai,visualization,analytics,json,export,data-analysis,obsidian
 Author: Mohamed Cheikh Sidiya
@@ -101,7 +101,19 @@ 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 !
+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
 
 ## Share Your Feedback! 💌
 
@@ -119,7 +131,7 @@ And if you've had a great experience, consider giving the project a star ⭐. It
 
 ## Notes
 
-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).
+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 (and you can choose an Obsidian-flavored mode in the interactive config if you want block IDs / navigation links).
 
 I wasn't a fan of the clunky, and sometimes paid, browser extensions.
 

{convoviz-0.2.4.dist-info → convoviz-0.2.6.dist-info}/RECORD

@@ -1,7 +1,7 @@
 convoviz/__init__.py,sha256=bQLCHO2U9EyMTGqNgsYiCtBQKTKNj4iIM3-TwIkrnRY,612
 convoviz/__main__.py,sha256=1qiGW13_SgL7wJi8iioIN-AAHGkNGnEl5q_RcPUrI0s,143
 convoviz/analysis/__init__.py,sha256=FxgH5JJpyypiLJpMQn_HlM51jnb8lQdP63_C_W3Dlx4,241
-convoviz/analysis/graphs.py,sha256=3CV4yhFwfUYb5-CXtq4D-r_vf0jn5cxDXwaPu1P8M8g,14928
+convoviz/analysis/graphs.py,sha256=gt056UkgGcy9vCkupQmW_HjOLy-W6j4Ekxr315BXPgA,29457
 convoviz/analysis/wordcloud.py,sha256=ZnbA_-rcXHwXIny_xbudfJDQbIuPT7urNFfHcx6QWxQ,4673
 convoviz/assets/colormaps.txt,sha256=59TSGz428AxY14AEvymAH2IJ2RT9Mlp7Sy0N12NEdXQ,108
 convoviz/assets/fonts/AmaticSC-Regular.ttf,sha256=83clh7a3urnTLud0_yZofuIb6BdyC2LMI9jhE6G2LvU,142696
@@ -37,25 +37,25 @@ convoviz/assets/fonts/YsabeauSC-Thin.ttf,sha256=hZGOZNTRrxbiUPE2VDeLbtnaRwkMOBaV
 convoviz/assets/fonts/Zeyada-Regular.ttf,sha256=fKhkrp9VHt_3Aw8JfkfkPeC2j3CilLWuPUudzBeawPQ,57468
 convoviz/assets/stopwords.txt,sha256=7_ywpxsKYOj3U5CZTh9lP4GqbbkZLMabSOjKAXFk6Wc,539
 convoviz/cli.py,sha256=8HNn-6kmDN8ECb0BspvjeGa_636SQPDffpM0yINgNII,3463
-convoviz/config.py,sha256=EbkMl5DNcExJiUSVB8Yg1cftpduMp45-Qabg6DBFoKQ,2724
+convoviz/config.py,sha256=UUynLSD22e5_fdm2zXx_bjRNOPRov_UjMBIY8u-76vg,2815
 convoviz/exceptions.py,sha256=bQpIKls48uOQpagEJAxpXf5LF7QoagRRfbD0MjWC7Ak,1476
-convoviz/interactive.py,sha256=hnla88hUqRjN-YV6zcauohMwxgQwbV3Y0UMT-FfXEMw,6350
+convoviz/interactive.py,sha256=VXtKgYo9tZGtsoj7zThdnbTrbjSNP5MzAZbdOs3icW4,7424
 convoviz/io/__init__.py,sha256=y70TYypJ36_kaEA04E2wa1EDaKQVjprKItoKR6MMs4M,471
 convoviz/io/assets.py,sha256=BykidWJG6OQAgbVfUByQ3RLTrldzpZ_NeM7HV3a5Tig,2333
 convoviz/io/loaders.py,sha256=RuGiGzpyNcgwTxOM-m2ehhyh2mP1-k1YamK8-VynR3g,5713
 convoviz/io/writers.py,sha256=KaLr0f2F2Pw5XOoQKMA75IeQYXUTT4WbS-HAqRxsp3c,3494
 convoviz/models/__init__.py,sha256=6gAfrk6KJT2QxdvX_v15mUdfIqEw1xKxwQlKSfyA5eI,532
 convoviz/models/collection.py,sha256=L658yKMNC6IZrfxYxZBe-oO9COP_bzVfRznnNon7tfU,4467
-convoviz/models/conversation.py,sha256=5Xw1po0N92AdgpnbwFd6Ukb_io34OzSfDGeYDwyuPDk,5123
+convoviz/models/conversation.py,sha256=ssx1Z6LM9kJIx3OucQW8JVoAc8zCdxj1iOLtie2B3ak,5678
 convoviz/models/message.py,sha256=mVnaUG6hypz92Oz3OgFAK1uuTgH3ZOJAWsFiCpLYneY,5459
 convoviz/models/node.py,sha256=1vBAtKVscYsUBDnKAOyLxuZaK9KoVF1dFXiKXRHxUnY,1946
 convoviz/pipeline.py,sha256=Mwg3Xqazk5PrsIHxhVajtWbfq4PgFlIGVHWq8BsW0U0,5750
 convoviz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 convoviz/renderers/__init__.py,sha256=IQgwD9NqtUgbS9zwyPBNZbBIZcFrbZ9C7WMAV-X3Xdg,261
-convoviz/renderers/markdown.py,sha256=kBeHqDH8yEiVN0N03dUUSJ-JbmdRmdoiC863NI83gXo,7211
+convoviz/renderers/markdown.py,sha256=mpDt-xrjsPX_wt9URCDk2wicesaVv_VTWWxTHCMKiLM,7765
 convoviz/renderers/yaml.py,sha256=XG1s4VhDdx-TiqekTkgED87RZ1lVQ7IwrbA-sZHrs7k,4056
 convoviz/utils.py,sha256=IQEKYHhWOnYxlr4GwAHoquG0BXTlVRkORL80oUSaIeQ,3417
-convoviz-0.2.4.dist-info/WHEEL,sha256=eycQt0QpYmJMLKpE3X9iDk8R04v2ZF0x82ogq-zP6bQ,79
-convoviz-0.2.4.dist-info/entry_points.txt,sha256=HYsmsw5vt36yYHB05uVU48AK2WLkcwshly7m7KKuZMY,54
-convoviz-0.2.4.dist-info/METADATA,sha256=DuwAsh5Sei0B-5Q-cMCzcXH0bUO9ZyzvbAfoV8Ury2M,5309
-convoviz-0.2.4.dist-info/RECORD,,
+convoviz-0.2.6.dist-info/WHEEL,sha256=eycQt0QpYmJMLKpE3X9iDk8R04v2ZF0x82ogq-zP6bQ,79
+convoviz-0.2.6.dist-info/entry_points.txt,sha256=HYsmsw5vt36yYHB05uVU48AK2WLkcwshly7m7KKuZMY,54
+convoviz-0.2.6.dist-info/METADATA,sha256=8bNTXriUg1k45-hM3NlxNrk01HM1Hu8xZPLhtk8uYgI,5994
+convoviz-0.2.6.dist-info/RECORD,,