convoviz 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

convoviz/cli.py

@@ -5,7 +5,7 @@ from pathlib import Path
 import typer
 from rich.console import Console
 
-from convoviz.config import get_default_config
+from convoviz.config import FolderOrganization, 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.",
     ),
+    flat: bool = typer.Option(
+        False,
+        "--flat",
+        "-f",
+        help="Put all markdown files in a single folder (disables date organization).",
+    ),
     interactive: bool | None = typer.Option(
         None,
         "--interactive/--no-interactive",
@@ -57,6 +63,8 @@ def run(
         config.input_path = input_path
     if output_dir:
         config.output_folder = output_dir
+    if flat:
+        config.folder_organization = FolderOrganization.FLAT
 
     # Determine mode: interactive if explicitly requested or no input provided
     use_interactive = interactive if interactive is not None else (input_path is None)

convoviz/config.py

@@ -1,11 +1,19 @@
 """Configuration models using Pydantic v2."""
 
+from enum import Enum
 from pathlib import Path
 from typing import Literal
 
 from pydantic import BaseModel, Field
 
 
+class FolderOrganization(str, Enum):
+    """How to organize markdown output files in folders."""
+
+    FLAT = "flat"  # All files in one directory (default)
+    DATE = "date"  # Nested by year/month/week
+
+
 class AuthorHeaders(BaseModel):
     """Headers for different message authors in markdown output."""
 
@@ -74,6 +82,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):
@@ -81,6 +91,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
     message: MessageConfig = Field(default_factory=MessageConfig)
     conversation: ConversationConfig = Field(default_factory=ConversationConfig)
     wordcloud: WordCloudConfig = Field(default_factory=WordCloudConfig)

convoviz/io/writers.py

@@ -6,12 +6,59 @@ from pathlib import Path
 from orjson import OPT_INDENT_2, dumps
 from tqdm import tqdm
 
-from convoviz.config import AuthorHeaders, ConversationConfig
+from convoviz.config import AuthorHeaders, ConversationConfig, FolderOrganization
 from convoviz.io.assets import copy_asset, resolve_asset_path
 from convoviz.models import Conversation, ConversationCollection
 from convoviz.renderers import render_conversation
 from convoviz.utils import sanitize
 
+# Month names for folder naming
+_MONTH_NAMES = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+]
+
+
+def get_date_folder_path(conversation: Conversation) -> Path:
+    """Get the date-based folder path for a conversation.
+
+    Creates a nested structure: year/month/week
+    Example: 2024/03-March/Week-02/
+
+    Args:
+        conversation: The conversation to get the path for
+
+    Returns:
+        Relative path for the date-based folder structure
+    """
+    create_time = conversation.create_time
+
+    # Year folder: "2024"
+    year = str(create_time.year)
+
+    # Month folder: "03-March"
+    month_num = create_time.month
+    month_name = _MONTH_NAMES[month_num - 1]
+    month = f"{month_num:02d}-{month_name}"
+
+    # Week folder: "Week-01" through "Week-05" (week of the month)
+    # Calculate which week of the month this date falls into
+    day = create_time.day
+    week_of_month = (day - 1) // 7 + 1
+    week = f"Week-{week_of_month:02d}"
+
+    return Path(year) / month / week
+
 
 def save_conversation(
     conversation: Conversation,
@@ -74,6 +121,7 @@ def save_collection(
     config: ConversationConfig,
     headers: AuthorHeaders,
     *,
+    folder_organization: FolderOrganization = FolderOrganization.FLAT,
     progress_bar: bool = False,
 ) -> None:
     """Save all conversations in a collection to markdown files.
@@ -83,6 +131,7 @@ def save_collection(
         directory: Target directory
         config: Conversation rendering configuration
         headers: Author header configuration
+        folder_organization: How to organize files in folders (flat or by date)
         progress_bar: Whether to show a progress bar
     """
     directory.mkdir(parents=True, exist_ok=True)
@@ -92,7 +141,14 @@ def save_collection(
         desc="Writing Markdown 📄 files",
         disable=not progress_bar,
     ):
-        filepath = directory / f"{sanitize(conv.title)}.md"
+        # Determine target directory based on organization setting
+        if folder_organization == FolderOrganization.DATE:
+            target_dir = directory / get_date_folder_path(conv)
+            target_dir.mkdir(parents=True, exist_ok=True)
+        else:
+            target_dir = directory
+
+        filepath = target_dir / f"{sanitize(conv.title)}.md"
         save_conversation(conv, filepath, config, headers, source_path=collection.source_path)
 
 

convoviz/pipeline.py

@@ -113,6 +113,7 @@ def run_pipeline(config: ConvovizConfig) -> None:
         markdown_folder,
         config.conversation,
         config.message.author_headers,
+        folder_organization=config.folder_organization,
         progress_bar=True,
     )
     console.print(

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.
@@ -105,10 +123,10 @@ def render_node_header(node: Node, headers: AuthorHeaders, flavor: str = "standa
 
     # 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"
 
@@ -127,9 +145,11 @@ def render_node_footer(node: Node, flavor: str = "standard") -> 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"
 
 

{convoviz-0.2.5.dist-info → convoviz-0.2.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convoviz
-Version: 0.2.5
+Version: 0.2.7
 Summary: Get analytics and visualizations on your ChatGPT data!
 Keywords: markdown,chatgpt,openai,visualization,analytics,json,export,data-analysis,obsidian
 Author: Mohamed Cheikh Sidiya
@@ -84,11 +84,6 @@ You can provide arguments directly to skip the prompts:
 convoviz --input path/to/your/export.zip --output path/to/output/folder
 ```
 
-Inputs can be any of:
-- A ChatGPT export ZIP (downloaded from OpenAI)
-- An extracted export directory containing `conversations.json`
-- A `conversations.json` file directly
-
 Notes:
 - `--zip` / `-z` is kept as an alias for `--input` for convenience.
 - You can force non-interactive mode with `--no-interactive`.
@@ -101,7 +96,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 +126,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.5.dist-info → convoviz-0.2.7.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
@@ -36,26 +36,26 @@ convoviz/assets/fonts/YsabeauSC-Regular.ttf,sha256=G4lkq34KKqZOaoomtxFz_KlwVmxg5
 convoviz/assets/fonts/YsabeauSC-Thin.ttf,sha256=hZGOZNTRrxbiUPE2VDeLbtnaRwkMOBaVQbq7Fwx-34c,116932
 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=vjedCcpQ_t-mR6cZ4GJJuyRPDeY95XCIiMXufVIlm9M,2724
+convoviz/cli.py,sha256=TPboT0maH_b_EjiT9cWbUSyMFz4ozoqf1_R-4AzY31g,3730
+convoviz/config.py,sha256=5fklWzwr0aNyeEJG0NAggLhT0xI0kwgxhjyh9_zUvwM,3112
 convoviz/exceptions.py,sha256=bQpIKls48uOQpagEJAxpXf5LF7QoagRRfbD0MjWC7Ak,1476
 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/io/writers.py,sha256=UW-JF5uq91NV62qpFVqgWTYSzzOAkLv67zDpulz2iBc,5072
 convoviz/models/__init__.py,sha256=6gAfrk6KJT2QxdvX_v15mUdfIqEw1xKxwQlKSfyA5eI,532
 convoviz/models/collection.py,sha256=L658yKMNC6IZrfxYxZBe-oO9COP_bzVfRznnNon7tfU,4467
 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/pipeline.py,sha256=IKfyy3iaNDTqox2YvwB3tnPqvL5iM0i_kMoa854glvY,5806
 convoviz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 convoviz/renderers/__init__.py,sha256=IQgwD9NqtUgbS9zwyPBNZbBIZcFrbZ9C7WMAV-X3Xdg,261
-convoviz/renderers/markdown.py,sha256=HDvTYpTJUI87o8QjS5ZfMS1FLRS4zPNBvCDyWzEpi9o,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.5.dist-info/WHEEL,sha256=eycQt0QpYmJMLKpE3X9iDk8R04v2ZF0x82ogq-zP6bQ,79
-convoviz-0.2.5.dist-info/entry_points.txt,sha256=HYsmsw5vt36yYHB05uVU48AK2WLkcwshly7m7KKuZMY,54
-convoviz-0.2.5.dist-info/METADATA,sha256=nh8J1XdXD9CdGO3REyBLZTdan-LdCP92tofpY7w4Wt0,5309
-convoviz-0.2.5.dist-info/RECORD,,
+convoviz-0.2.7.dist-info/WHEEL,sha256=eycQt0QpYmJMLKpE3X9iDk8R04v2ZF0x82ogq-zP6bQ,79
+convoviz-0.2.7.dist-info/entry_points.txt,sha256=HYsmsw5vt36yYHB05uVU48AK2WLkcwshly7m7KKuZMY,54
+convoviz-0.2.7.dist-info/METADATA,sha256=B3v-e0XrLNCEos-nS6_Ynw3-KGPxDMpvbrFgSEFYyHw,5820
+convoviz-0.2.7.dist-info/RECORD,,