DeepFabric 4.10.1__py3-none-any.whl → 4.12.0__py3-none-any.whl

deepfabric/cli.py

@@ -2,11 +2,19 @@ import contextlib
 import json
 import math
 import os
+import platform
+import select
 import signal
 import sys
 
 from pathlib import Path
-from typing import Literal, NoReturn, cast
+from typing import TYPE_CHECKING, Literal, NoReturn, cast
+
+if TYPE_CHECKING:
+    from rich.tree import Tree as RichTree
+
+    from .topic_inspector import TopicInspectionResult
+    from .tui import DeepFabricTUI
 
 import click
 import yaml
@@ -137,7 +145,7 @@ class GenerateOptions(BaseModel):
     batch_size: int | None = None
     base_url: str | None = None
     include_system_message: bool | None = None
-    mode: Literal["tree", "graph"] = Field(default="tree")
+    mode: Literal["tree", "graph"] | None = Field(default=None)
     debug: bool = False
     topic_only: bool = False
     tui: Literal["rich", "simple"] = Field(default="rich")
@@ -330,7 +338,7 @@ def _load_and_prepare_generation_context(
     # Skip path validation for topic-only mode since we're not generating dataset samples
     if not skip_path_validation:
         validate_path_requirements(
-            mode=options.mode,
+            mode=config.topics.mode,
             depth=final_depth,
             degree=final_degree,
             num_samples=final_num_samples,
@@ -339,7 +347,7 @@ def _load_and_prepare_generation_context(
         )
 
         show_validation_success(
-            mode=options.mode,
+            mode=config.topics.mode,
             depth=final_depth,
             degree=final_degree,
             num_samples=final_num_samples,
@@ -419,6 +427,35 @@ def _trigger_cloud_upload(
     )
 
 
+def _prompt_with_timeout(
+    choices: list[str],
+    default: str,
+    timeout: int = 20,
+) -> str:
+    """Prompt for a choice with a visible countdown, auto-selecting default on timeout."""
+    if platform.system() == "Windows":
+        return click.prompt(
+            f"  Choose [{'/'.join(choices)}]",
+            type=click.Choice(choices),
+            default=default,
+        )
+    valid = set(choices)
+    for remaining in range(timeout, 0, -1):
+        sys.stdout.write(f"\r  Choose [{'/'.join(choices)}] (auto-{default} in {remaining:2d}s): ")
+        sys.stdout.flush()
+        ready, _, _ = select.select([sys.stdin], [], [], 1.0)
+        if ready:
+            line = sys.stdin.readline().strip()
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+            if line in valid:
+                return line
+            return default
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    return default
+
+
 def _run_generation(
     *,
     preparation: GenerationPreparation,
@@ -470,14 +507,10 @@ def _run_generation(
         tui.console.print("  [cyan]3)[/cyan] Abort")
         tui.console.print()
 
-        choice = click.prompt(
-            "Choose an option",
-            type=click.Choice(["1", "2", "3"]),
-            default="1",
-        )
+        choice = _prompt_with_timeout(["1", "2", "3"], default="1", timeout=20)
 
         if choice == "1":
-            # User wants to resume
+            # User wants to resume (or auto-selected after timeout)
             options.resume = True
         elif choice == "2":
             # Clear and start fresh
@@ -493,7 +526,7 @@ def _run_generation(
         if engine.load_checkpoint(retry_failed=options.retry_failed):
             samples_done = engine._flushed_samples_count
             failures_done = engine._flushed_failures_count
-            ids_processed = len(engine._processed_ids)
+            ids_processed = len(engine._completed)
             retry_msg = " (retrying failed samples)" if options.retry_failed else ""
 
             # Update TUI status panel with checkpoint progress
@@ -503,17 +536,18 @@ def _run_generation(
             if failures_done > 0:
                 tui.info(
                     f"Resuming from checkpoint: {samples_done} samples, "
-                    f"{failures_done} failed, {ids_processed} IDs processed{retry_msg}"
+                    f"{failures_done} failed, {ids_processed} UUIDs processed{retry_msg}"
                 )
             else:
                 tui.info(
                     f"Resuming from checkpoint: {samples_done} samples, "
-                    f"{ids_processed} IDs processed{retry_msg}"
+                    f"{ids_processed} UUIDs processed{retry_msg}"
                 )
         else:
             tui.info("No checkpoint found, starting fresh generation")
 
-    # Set up graceful Ctrl+C handling for checkpoint-based stop
+    # Set up graceful Ctrl+C handling
+    has_checkpoint = generation_params.get("checkpoint_interval") is not None
     interrupt_count = 0
 
     def handle_sigint(_signum, _frame):
@@ -522,7 +556,12 @@ def _run_generation(
 
         if interrupt_count == 1:
             engine.stop_requested = True
-            tui.warning("Stopping after current checkpoint... (Ctrl+C again to force quit)")
+            if has_checkpoint:
+                tui.warning("Stopping after current checkpoint... (Ctrl+C again to force quit)")
+            else:
+                tui.warning(
+                    "Stopping... partial results will be saved. (Ctrl+C again to force quit)"
+                )
             dataset_tui = get_dataset_tui()
             dataset_tui.log_event("⚠ Graceful stop requested")
             dataset_tui.status_stop_requested()
@@ -547,12 +586,22 @@ def _run_generation(
     finally:
         signal.signal(signal.SIGINT, original_handler)
 
-    # If gracefully stopped, don't save partial dataset or clean up checkpoints
+    output_config = preparation.config.get_output_config()
+    output_save_path = options.output_save_as or output_config["save_as"]
+
+    # If gracefully stopped, handle based on checkpoint availability
     if engine.stop_requested:
+        if has_checkpoint:
+            # Checkpoint on disk — user can resume later
+            return
+        # No checkpoint — save whatever was generated so far
+        if dataset and len(dataset) > 0:
+            tui.info(f"Saving {len(dataset)} samples generated before stop")
+            save_dataset(dataset, output_save_path, preparation.config, engine=engine)
+        else:
+            tui.warning("No samples were generated before stop")
         return
 
-    output_config = preparation.config.get_output_config()
-    output_save_path = options.output_save_as or output_config["save_as"]
     save_dataset(dataset, output_save_path, preparation.config, engine=engine)
 
     # Clean up checkpoint files after successful completion
@@ -612,8 +661,8 @@ def _run_generation(
 @click.option(
     "--mode",
     type=click.Choice(["tree", "graph"]),
-    default="tree",
-    help="Topic generation mode (default: tree)",
+    default=None,
+    help="Topic generation mode (default: graph)",
 )
 @click.option(
     "--debug",
@@ -651,8 +700,7 @@ def _run_generation(
     "--cloud-upload",
     type=click.Choice(["all", "dataset", "graph", "none"], case_sensitive=False),
     default=None,
-    help="Upload to DeepFabric Cloud (experimental): all, dataset, graph, or none. "
-    "Enables headless mode for CI. Requires DEEPFABRIC_API_KEY or prior auth.",
+    help="Upload to DeepFabric Cloud (experimental): all, dataset, graph, or none. ",
 )
 @click.option(
     "--checkpoint-interval",
@@ -783,7 +831,9 @@ def generate(  # noqa: PLR0913
 
         # Compute checkpoint directory once for consistent use throughout generation
         # Use config file for hash, fallback to output path for config-less runs
-        path_source = options.config_file or options.output_save_as or preparation.config.output.save_as
+        path_source = (
+            options.config_file or options.output_save_as or preparation.config.output.save_as
+        )
         checkpoint_dir = options.checkpoint_path or get_checkpoint_dir(path_source)
 
         # Auto-infer topics-load when resuming from checkpoint
@@ -1295,23 +1345,34 @@ def validate(config_file: str, check_api: bool) -> None:  # noqa: PLR0912
             f"estimated_paths={estimated_paths} ({degree}^{depth})"
         )
 
-        # Output summary with step size and checkpoint info
+        # Output summary with cycle-based generation info
         num_samples = config.output.num_samples
         batch_size = config.output.batch_size
-        # Calculate num_steps - handle 'auto' and percentage strings
-        if isinstance(num_samples, int):
-            num_steps = math.ceil(num_samples / batch_size)
-            output_info = f"Output: num_samples={num_samples}, batch_size={batch_size}, num_steps={num_steps}"
-        else:
-            # For 'auto' or percentage, we can't compute steps without topic count
-            output_info = f"Output: num_samples={num_samples}, batch_size={batch_size}"
 
-        # Add checkpoint info if enabled
+        # Show output configuration
+        output_info = f"Output: num_samples={num_samples}, concurrency={batch_size}"
         if config.output.checkpoint:
             checkpoint = config.output.checkpoint
             output_info += f", checkpoint_interval={checkpoint.interval}"
         tui.info(output_info)
 
+        # Calculate and display cycle-based generation info
+        if isinstance(num_samples, int):
+            cycles_needed = math.ceil(num_samples / estimated_paths)
+            final_cycle_size = num_samples - (cycles_needed - 1) * estimated_paths
+            is_partial = final_cycle_size < estimated_paths
+
+            tui.info(
+                f"  → Cycles needed: {cycles_needed} "
+                f"({num_samples} samples ÷ {estimated_paths} unique topics)"
+            )
+            if is_partial:
+                tui.info(f"  → Final cycle: {final_cycle_size} topics (partial)")
+        elif num_samples == "auto":
+            tui.info(f"  → Will generate 1 sample per unique topic ({estimated_paths} samples)")
+        else:
+            tui.info("  → Samples calculated at runtime based on topic count")
+
         if config.huggingface:
             hf_config = config.get_huggingface_config()
             tui.info(f"Hugging Face: repo={hf_config.get('repository', 'not set')}")
@@ -1893,7 +1954,8 @@ def checkpoint_status(config_file: str) -> None:
     # Check if checkpoint exists
     if not metadata_path.exists():
         tui.info(f"No checkpoint found at: {metadata_path}")
-        tui.info("\nTo enable checkpointing, run:")
+        tui.console.print()
+        tui.info("To enable checkpointing, run:")
         tui.info(f"  deepfabric generate {config_file} --checkpoint-interval 10")
         return
 
@@ -1994,5 +2056,534 @@ def checkpoint_status(config_file: str) -> None:
         )
 
 
+# Topic inspection command group
+@click.group()
+def topic() -> None:
+    """Topic management commands."""
+    pass
+
+
+@topic.command("inspect")
+@click.argument("file", type=click.Path(exists=True))
+@click.option(
+    "--level",
+    "-l",
+    type=int,
+    default=None,
+    help="Show topics at a specific depth level (0=root, 1=first children, etc.)",
+)
+@click.option(
+    "--expand",
+    "-e",
+    type=int,
+    default=None,
+    is_flag=False,
+    flag_value=-1,  # -1 means expand all levels
+    help="Show subtopics in tree format. Use alone for all levels, or specify depth (e.g., --expand 2)",
+)
+@click.option(
+    "--all",
+    "-a",
+    "show_all",
+    is_flag=True,
+    help="Show the entire tree structure with indentation",
+)
+@click.option(
+    "--format",
+    "-f",
+    "output_format",
+    type=click.Choice(["tree", "table", "json"]),
+    default="tree",
+    help="Output format (default: tree)",
+)
+@click.option(
+    "--uuid",
+    "-u",
+    "show_uuid",
+    is_flag=True,
+    help="Show UUID/topic_id for each leaf node",
+)
+def topic_inspect(
+    file: str,
+    level: int | None,
+    expand: int | None,
+    show_all: bool,
+    output_format: str,
+    show_uuid: bool,
+) -> None:
+    """Inspect a topic tree or graph file.
+
+    Displays metadata and structure of topic files generated by DeepFabric.
+    Supports both Tree (JSONL) and Graph (JSON) formats with auto-detection.
+
+    Examples:
+
+    \b
+        # Show file metadata and summary
+        deepfabric topic inspect topic_tree.jsonl
+
+    \b
+        # Show topics at depth level 2 (just topic names)
+        deepfabric topic inspect topic_tree.jsonl --level 2
+
+    \b
+        # Show level 2 topics and all subtopics (tree format)
+        deepfabric topic inspect topic_tree.jsonl --level 2 --expand
+
+    \b
+        # Show level 2 topics and 1 sublevel only (tree format)
+        deepfabric topic inspect topic_tree.jsonl --level 2 --expand 1
+
+    \b
+        # Show entire tree with indentation
+        deepfabric topic inspect topic_graph.json --all
+
+    \b
+        # Output as JSON for scripting
+        deepfabric topic inspect topic_tree.jsonl --format json
+
+    \b
+        # Show UUIDs for each leaf node
+        deepfabric topic inspect topic_tree.jsonl --all --uuid
+    """
+    from .topic_inspector import inspect_topic_file  # noqa: PLC0415
+
+    tui = get_tui()
+
+    try:
+        # Perform inspection
+        result = inspect_topic_file(file, level=level, expand_depth=expand, show_all=show_all)
+
+        # Handle JSON output format
+        if output_format == "json":
+            output = {
+                "format": result.format,
+                "source_file": result.source_file,
+                "total_paths": result.total_paths,
+                "max_depth": result.max_depth,
+                "metadata": result.metadata,
+            }
+            if result.paths_at_level is not None:
+                output["paths_at_level"] = result.paths_at_level
+            if result.expanded_paths is not None:
+                output["expanded_paths"] = result.expanded_paths
+            if result.all_paths is not None:
+                output["all_paths"] = result.all_paths
+            tui.console.print_json(json.dumps(output))
+            return
+
+        # Rich output (tree or table format)
+        _display_inspection_result(tui, result, output_format, level, expand, show_all, show_uuid)
+
+    except FileNotFoundError as e:
+        tui.error(str(e))
+        sys.exit(1)
+    except ValueError as e:
+        tui.error(f"Invalid file: {e}")
+        sys.exit(1)
+    except Exception as e:
+        tui.error(f"Error inspecting file: {e}")
+        sys.exit(1)
+
+
+def _display_inspection_result(
+    tui: "DeepFabricTUI",
+    result: "TopicInspectionResult",
+    output_format: str,
+    level: int | None,
+    expand: int | None,
+    show_all: bool,
+    show_uuid: bool = False,
+) -> None:
+    """Display inspection result using rich formatting."""
+    from rich.panel import Panel  # noqa: PLC0415
+    from rich.table import Table  # noqa: PLC0415
+
+    # Header with file info
+    format_label = "Graph (JSON)" if result.format == "graph" else "Tree (JSONL)"
+
+    tui.console.print()
+    tui.console.print("[bold cyan]Topic Inspector[/bold cyan]")
+    tui.console.print(f"[dim]{result.source_file}[/dim]")
+    tui.console.print()
+
+    # Statistics panel
+    stats_table = Table(show_header=False, box=None, padding=(0, 1))
+    stats_table.add_column(style="cyan", no_wrap=True)
+    stats_table.add_column(style="white")
+
+    stats_table.add_row("Format:", format_label)
+    stats_table.add_row("Total Paths:", str(result.total_paths))
+    stats_table.add_row("Max Depth:", str(result.max_depth))
+
+    if result.metadata.get("root_topic"):
+        root = result.metadata["root_topic"]
+        if len(root) > 60:  # noqa: PLR2004
+            root = root[:57] + "..."
+        stats_table.add_row("Root Topic:", root)
+
+    if result.metadata.get("total_nodes"):
+        stats_table.add_row("Total Nodes:", str(result.metadata["total_nodes"]))
+
+    if result.metadata.get("has_cycles") is not None:
+        has_cycles = "Yes" if result.metadata["has_cycles"] else "No"
+        stats_table.add_row("Has Cycles:", has_cycles)
+
+    if result.metadata.get("provider"):
+        stats_table.add_row("Provider:", result.metadata["provider"])
+
+    if result.metadata.get("model"):
+        stats_table.add_row("Model:", result.metadata["model"])
+
+    if result.metadata.get("created_at"):
+        stats_table.add_row("Created:", result.metadata["created_at"])
+
+    tui.console.print(Panel(stats_table, title="Statistics", border_style="dim"))
+
+    # Show level-specific topics (without expand) - simple list of topic names
+    if level is not None and expand is None and result.paths_at_level is not None:
+        tui.console.print()
+        tui.console.print(f"[cyan bold]Topics at Level {level}:[/cyan bold]")
+
+        if not result.paths_at_level:
+            tui.console.print(f"  [dim]No topics at level {level}[/dim]")
+        else:
+            # Display as simple list of topic names (with UUIDs)
+            for topic_path in result.paths_at_level:
+                topic_name = topic_path[0] if topic_path else ""
+                if show_uuid:
+                    # For graph format, use topic_to_uuid (node UUIDs)
+                    # For tree format, use path_to_uuid (leaf UUIDs only)
+                    uuid = ""
+                    if result.topic_to_uuid:
+                        uuid = result.topic_to_uuid.get(topic_name, "")
+                    if not uuid and result.path_to_uuid:
+                        uuid = result.path_to_uuid.get(tuple(topic_path), "")
+                    if uuid:
+                        tui.console.print(
+                            f"  • {topic_name} [dim](UUID: {uuid})[/dim]", highlight=False
+                        )
+                    else:
+                        tui.console.print(f"  • {topic_name}")
+                else:
+                    tui.console.print(f"  • {topic_name}")
+
+    # Show expanded subtree from level (with --expand)
+    if level is not None and expand is not None and result.expanded_paths is not None:
+        tui.console.print()
+        depth_info = "all sublevels" if expand == -1 else f"{expand} sublevel(s)"
+        tui.console.print(f"[cyan bold]Subtree from Level {level} ({depth_info}):[/cyan bold]")
+
+        if not result.expanded_paths:
+            tui.console.print(f"  [dim]No topics at or below level {level}[/dim]")
+        elif output_format == "table":
+            _display_paths_as_table(tui, result.expanded_paths)
+        else:
+            _display_paths_as_tree(
+                tui,
+                result.expanded_paths,
+                result.path_to_uuid if show_uuid else None,
+                result.topic_to_uuid if show_uuid else None,
+            )
+
+    # Show all paths with tree structure
+    if show_all and result.all_paths:
+        tui.console.print()
+        tui.console.print("[cyan bold]Full Tree Structure:[/cyan bold]")
+
+        if output_format == "table":
+            _display_paths_as_table(tui, result.all_paths)
+        else:
+            _display_paths_as_tree(
+                tui,
+                result.all_paths,
+                result.path_to_uuid if show_uuid else None,
+                result.topic_to_uuid if show_uuid else None,
+            )
+
+
+def _display_paths_as_table(tui: "DeepFabricTUI", paths: list[list[str]]) -> None:
+    """Display paths in a table format."""
+    from rich.table import Table  # noqa: PLC0415
+
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("#", style="dim")
+    table.add_column("Path", style="white")
+    table.add_column("Depth", style="green")
+
+    for i, path in enumerate(paths[:100], 1):
+        path_str = " > ".join(path)
+        if len(path_str) > 80:  # noqa: PLR2004
+            path_str = path_str[:77] + "..."
+        table.add_row(str(i), path_str, str(len(path)))
+
+    if len(paths) > 100:  # noqa: PLR2004
+        table.add_row("...", f"[dim]{len(paths) - 100} more paths[/dim]", "")
+
+    tui.console.print(table)
+
+
+def _display_paths_as_tree(
+    tui: "DeepFabricTUI",
+    paths: list[list[str]],
+    path_to_uuid: dict[tuple[str, ...], str] | None = None,
+    topic_to_uuid: dict[str, str] | None = None,
+) -> None:
+    """Display paths in an indented tree format."""
+    from rich.tree import Tree as RichTree  # noqa: PLC0415
+
+    if not paths:
+        return
+
+    # Build a tree structure from paths
+    # Group paths by their root topic
+    root_groups: dict[str, list[list[str]]] = {}
+    for path in paths:
+        if path:
+            root = path[0]
+            if root not in root_groups:
+                root_groups[root] = []
+            root_groups[root].append(path)
+
+    if len(root_groups) == 1:
+        # Single root - show directly
+        root_topic = paths[0][0]
+        # Show UUID for root if available (graph format)
+        root_label = f"[bold]{root_topic}[/bold]"
+        if topic_to_uuid and root_topic in topic_to_uuid:
+            root_label += f" [dim](UUID: {topic_to_uuid[root_topic]})[/dim]"
+        tree = RichTree(root_label)
+        _add_children_to_tree(
+            tree, paths, 1, path_to_uuid=path_to_uuid, topic_to_uuid=topic_to_uuid
+        )
+        tui.console.print(tree)
+    else:
+        # Multiple roots - show each as a separate tree
+        for root_topic, root_paths in list(root_groups.items())[:20]:
+            root_label = f"[bold]{root_topic}[/bold]"
+            if topic_to_uuid and root_topic in topic_to_uuid:
+                root_label += f" [dim](UUID: {topic_to_uuid[root_topic]})[/dim]"
+            tree = RichTree(root_label)
+            _add_children_to_tree(
+                tree, root_paths, 1, path_to_uuid=path_to_uuid, topic_to_uuid=topic_to_uuid
+            )
+            tui.console.print(tree)
+        if len(root_groups) > 20:  # noqa: PLR2004
+            tui.console.print(f"[dim]... and {len(root_groups) - 20} more topics[/dim]")
+
+
+def _add_children_to_tree(
+    parent: "RichTree",
+    paths: list[list[str]],
+    depth: int,
+    max_depth: int = 5,
+    path_to_uuid: dict[tuple[str, ...], str] | None = None,
+    topic_to_uuid: dict[str, str] | None = None,
+) -> None:
+    """Recursively add children to a rich tree (limited depth for display)."""
+    if depth > max_depth:
+        remaining = len([p for p in paths if len(p) > depth])
+        if remaining > 0:
+            parent.add(f"[dim]... {remaining} more levels[/dim]")
+        return
+
+    # Group paths by their element at current depth
+    children: dict[str, list[list[str]]] = {}
+    for path in paths:
+        if len(path) > depth:
+            child_topic = path[depth]
+            if child_topic not in children:
+                children[child_topic] = []
+            children[child_topic].append(path)
+
+    # Add children to tree
+    for child_topic, child_paths in list(children.items())[:20]:
+        # Check for UUID: first try topic_to_uuid (graph nodes), then path_to_uuid (leaves)
+        uuid = ""
+        if topic_to_uuid and child_topic in topic_to_uuid:
+            uuid = topic_to_uuid[child_topic]
+        elif path_to_uuid:
+            # Check if this child is a leaf (path ends at depth + 1)
+            is_leaf = any(len(p) == depth + 1 for p in child_paths)
+            if is_leaf:
+                leaf_path = next((p for p in child_paths if len(p) == depth + 1), None)
+                if leaf_path:
+                    uuid = path_to_uuid.get(tuple(leaf_path), "")
+
+        if uuid:
+            child_node = parent.add(f"{child_topic} [dim](UUID: {uuid})[/dim]")
+        else:
+            child_node = parent.add(child_topic)
+        _add_children_to_tree(
+            child_node, child_paths, depth + 1, max_depth, path_to_uuid, topic_to_uuid
+        )
+
+    if len(children) > 20:  # noqa: PLR2004
+        parent.add(f"[dim]... and {len(children) - 20} more siblings[/dim]")
+
+
+@topic.command("prune")
+@click.argument("file", type=click.Path(exists=True))
+@click.option(
+    "--level",
+    "-l",
+    type=int,
+    default=None,
+    help="Prune all nodes below this depth level (0=root, 1=children, etc.)",
+)
+@click.option(
+    "--uuid",
+    "-u",
+    type=str,
+    default=None,
+    help="Remove the node with this UUID and its entire subtree",
+)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(),
+    default=None,
+    help="Output file path (default: auto-generated from input filename)",
+)
+@click.option(
+    "--force",
+    "-f",
+    is_flag=True,
+    help="Overwrite the input file instead of creating a new one",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what would be removed without making changes",
+)
+def topic_prune(
+    file: str,
+    level: int | None,
+    uuid: str | None,
+    output: str | None,
+    force: bool,
+    dry_run: bool,
+) -> None:
+    """Prune a topic graph by removing nodes.
+
+    Supports two modes:
+
+    \b
+        # Remove all nodes below depth level 2
+        deepfabric topic prune topic_graph.json --level 2
+
+    \b
+        # Remove a specific node and its subtree by UUID
+        deepfabric topic prune topic_graph.json --uuid abc-123-def
+
+    \b
+        # Preview what would be removed (no file written)
+        deepfabric topic prune topic_graph.json --level 1 --dry-run
+
+    \b
+        # Overwrite the original file
+        deepfabric topic prune topic_graph.json --uuid abc-123 --force
+    """
+    from .graph_pruner import (  # noqa: PLC0415
+        load_graph_for_pruning,
+        prune_graph_at_level,
+        prune_graph_by_uuid,
+    )
+
+    tui = get_tui()
+
+    # Validate: exactly one mode must be specified
+    if level is None and uuid is None:
+        tui.error("Specify either --level or --uuid")
+        sys.exit(1)
+    if level is not None and uuid is not None:
+        tui.error("Cannot use --level and --uuid together")
+        sys.exit(1)
+
+    try:
+        if dry_run:
+            graph = load_graph_for_pruning(file)
+            total_nodes = len(graph.nodes)
+
+            tui.console.print()
+            tui.console.print("[bold]DRY RUN[/bold] — no changes will be made")
+            tui.console.print()
+
+            if level is not None:
+                # BFS to compute node depths
+                node_depths: dict[int, int] = {}
+                queue: list[tuple] = [(graph.root, 0)]
+                visited: set[int] = set()
+                while queue:
+                    current, d = queue.pop(0)
+                    if current.id in visited:
+                        continue
+                    visited.add(current.id)
+                    node_depths[current.id] = d
+                    for child in current.children:
+                        if child.id not in visited:
+                            queue.append((child, d + 1))
+
+                to_remove = {nid for nid, d in node_depths.items() if d > level}
+                tui.console.print(f"  Graph:         {total_nodes} unique nodes")
+                tui.console.print(f"  Would remove:  {len(to_remove)} nodes below level {level}")
+                tui.console.print(f"  Would keep:    {total_nodes - len(to_remove)} nodes")
+            else:
+                target = graph.find_node_by_uuid(uuid)
+                if target is None:
+                    tui.error(f"No node found with UUID: {uuid}")
+                    sys.exit(1)
+
+                # BFS to count subtree
+                subtree_count = 0
+                bfs_queue = [target]
+                visited_ids: set[int] = set()
+                while bfs_queue:
+                    current = bfs_queue.pop(0)
+                    if current.id in visited_ids:
+                        continue
+                    visited_ids.add(current.id)
+                    subtree_count += 1
+                    for child in current.children:
+                        if child.id not in visited_ids:
+                            bfs_queue.append(child)
+
+                tui.console.print(f"  Graph:         {total_nodes} unique nodes")
+                tui.console.print(
+                    f"  Target:        {target.topic}",
+                    highlight=False,
+                )
+                tui.console.print(f"  Would remove:  {subtree_count} nodes (including subtree)")
+                tui.console.print(f"  Would keep:    {total_nodes - subtree_count} nodes")
+            return
+
+        # Determine output path
+        output_path = file if force else output
+
+        if level is not None:
+            result = prune_graph_at_level(file, level, output_path)
+        else:
+            result = prune_graph_by_uuid(file, uuid, output_path)
+
+        tui.console.print()
+        tui.success("Graph pruned successfully")
+        tui.console.print(f"  Removed:   {result.removed_count} nodes")
+        tui.console.print(
+            f"  Remaining: {result.remaining_nodes} nodes, {result.remaining_paths} paths"
+        )
+        tui.console.print(f"  Saved to:  {result.output_path}")
+
+    except FileNotFoundError as e:
+        tui.error(str(e))
+        sys.exit(1)
+    except ValueError as e:
+        tui.error(str(e))
+        sys.exit(1)
+
+
+# Register the topic command group
+cli.add_command(topic)
+
+
 if __name__ == "__main__":
     cli()