Merge pull request #598 from scp7/feature/topic-inspect

feat: add topic inspect and prune commands
change: change default topic generation mode from tree to graph

Author: scp7

deepfabric/cli.py

@@ -8,6 +8,7 @@
 
 from .constants import (
     DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_TOKENS,
     DEFAULT_MODEL,
     DEFAULT_PROVIDER,
     DEFAULT_SAMPLE_RETRIES,
@@ -86,7 +87,7 @@ class TopicsConfig(BaseModel):
         ..., min_length=1, description="The initial prompt to start topic generation"
     )
     mode: Literal["tree", "graph"] = Field(
-        default="tree", description="Topic generation mode: tree or graph"
+        default="graph", description="Topic generation mode: tree or graph"
     )
     system_prompt: str = Field(
         default="", description="System prompt for topic exploration and generation"
@@ -109,6 +110,11 @@ class TopicsConfig(BaseModel):
         le=20,
         description="Maximum concurrent LLM calls during graph expansion (helps avoid rate limits)",
     )
+    max_tokens: int = Field(
+        default=DEFAULT_MAX_TOKENS,
+        ge=1,
+        description="Maximum tokens for topic generation LLM calls",
+    )
     save_as: str | None = Field(default=None, description="Where to save the generated topics")
     prompt_style: Literal["default", "isolated", "anchored"] = Field(
         default="default",
@@ -589,6 +595,7 @@ def get_topics_params(self, **overrides) -> dict:
             "depth": self.topics.depth,
             "degree": self.topics.degree,
             "max_concurrent": self.topics.max_concurrent,
+            "max_tokens": self.topics.max_tokens,
             "prompt_style": self.topics.prompt_style,
         }
 

deepfabric/config.py

@@ -37,7 +37,7 @@ def load_config(  # noqa: PLR0913
     topics_save_as: str | None = None,
     output_save_as: str | None = None,
     include_system_message: bool | None = None,
-    mode: str = "tree",
+    mode: str | None = None,
     # Modular conversation configuration
     conversation_type: str | None = None,
     reasoning_style: str | None = None,
@@ -83,6 +83,8 @@ def load_config(  # noqa: PLR0913
         except Exception as e:
             raise ConfigurationError(f"Error loading config file: {str(e)}") from e
         else:
+            if mode is not None:
+                config.topics.mode = mode
             return config
 
     # No config file provided - create minimal configuration from CLI args
@@ -92,6 +94,9 @@ def load_config(  # noqa: PLR0913
     tui = get_tui()
     tui.info("No config file provided - using CLI parameters")
 
+    # Default to graph mode when no config file and no explicit mode
+    mode = mode or "graph"
+
     # Create minimal config dict with new structure
     default_prompt = generation_system_prompt or "You are a helpful AI assistant."
 

deepfabric/config_manager.py

@@ -70,6 +70,11 @@ class GraphConfig(BaseModel):
         le=20,
         description="Maximum concurrent LLM calls during graph expansion (helps avoid rate limits)",
     )
+    max_tokens: int = Field(
+        default=DEFAULT_MAX_TOKENS,
+        ge=1,
+        description="Maximum tokens for topic generation LLM calls",
+    )
     base_url: str | None = Field(
         default=None,
         description="Base URL for API endpoint (e.g., custom OpenAI-compatible servers)",
@@ -156,6 +161,7 @@ def __init__(self, **kwargs):
         self.degree = self.config.degree
         self.depth = self.config.depth
         self.max_concurrent = self.config.max_concurrent
+        self.max_tokens = self.config.max_tokens
         self.prompt_style = self.config.prompt_style
 
         # Initialize LLM client
@@ -211,6 +217,139 @@ def add_edge(self, parent_id: int, child_id: int) -> None:
             if parent_node not in child_node.parents:
                 child_node.parents.append(parent_node)
 
+    def find_node_by_uuid(self, uuid: str) -> Node | None:
+        """Find a node by its UUID.
+
+        Args:
+            uuid: The UUID string to search for.
+
+        Returns:
+            The Node if found, None otherwise.
+        """
+        for node in self.nodes.values():
+            if node.metadata.get("uuid") == uuid:
+                return node
+        return None
+
+    def remove_node(self, node_id: int) -> None:
+        """Remove a single node from the graph, cleaning up bidirectional references.
+
+        Does not remove children — use remove_subtree() for cascading removal.
+
+        Args:
+            node_id: The ID of the node to remove.
+
+        Raises:
+            ValueError: If node_id is the root node or does not exist.
+        """
+        if node_id == self.root.id:
+            raise ValueError("Cannot remove the root node")  # noqa: TRY003
+        node = self.nodes.get(node_id)
+        if node is None:
+            raise ValueError(f"Node {node_id} not found in graph")  # noqa: TRY003
+
+        for parent in node.parents:
+            if node in parent.children:
+                parent.children.remove(node)
+
+        for child in node.children:
+            if node in child.parents:
+                child.parents.remove(node)
+
+        del self.nodes[node_id]
+
+    def remove_subtree(self, node_id: int) -> list[int]:
+        """Remove a node and all its descendants from the graph.
+
+        Args:
+            node_id: The ID of the node to remove (along with all descendants).
+
+        Returns:
+            List of removed node IDs.
+
+        Raises:
+            ValueError: If node_id is the root node or does not exist.
+        """
+        if node_id == self.root.id:
+            raise ValueError("Cannot remove the root node")  # noqa: TRY003
+        node = self.nodes.get(node_id)
+        if node is None:
+            raise ValueError(f"Node {node_id} not found in graph")  # noqa: TRY003
+
+        # BFS to collect all descendant node IDs
+        to_remove: list[int] = []
+        queue = [node]
+        visited: set[int] = set()
+        while queue:
+            current = queue.pop(0)
+            if current.id in visited:
+                continue
+            visited.add(current.id)
+            to_remove.append(current.id)
+            for child in current.children:
+                if child.id not in visited:
+                    queue.append(child)
+
+        # Remove in reverse order (leaves first)
+        for nid in reversed(to_remove):
+            self.remove_node(nid)
+
+        return to_remove
+
+    def prune_at_level(self, max_depth: int) -> list[int]:
+        """Remove all nodes below the given depth level.
+
+        Nodes at exactly max_depth become leaf nodes. Root is depth 0.
+
+        Args:
+            max_depth: Maximum depth to keep (inclusive).
+                       0 = keep only root, 1 = root and its children, etc.
+
+        Returns:
+            List of removed node IDs.
+
+        Raises:
+            ValueError: If max_depth is negative.
+        """
+        if max_depth < 0:
+            raise ValueError("max_depth must be non-negative")  # noqa: TRY003
+
+        # BFS from root to compute node depths
+        node_depths: dict[int, int] = {}
+        queue: list[tuple[Node, int]] = [(self.root, 0)]
+        visited: set[int] = set()
+        while queue:
+            current, depth = queue.pop(0)
+            if current.id in visited:
+                continue
+            visited.add(current.id)
+            node_depths[current.id] = depth
+            for child in current.children:
+                if child.id not in visited:
+                    queue.append((child, depth + 1))
+
+        to_remove_set = {nid for nid, d in node_depths.items() if d > max_depth}
+
+        # Sever children links from boundary nodes
+        for nid, d in node_depths.items():
+            if d == max_depth:
+                self.nodes[nid].children = [
+                    c for c in self.nodes[nid].children if c.id not in to_remove_set
+                ]
+
+        # Remove deeper nodes
+        for nid in to_remove_set:
+            node = self.nodes[nid]
+            for parent in node.parents:
+                if node in parent.children:
+                    parent.children.remove(node)
+            for child in node.children:
+                if node in child.parents:
+                    child.parents.remove(node)
+            del self.nodes[nid]
+
+        return list(to_remove_set)
+
     def to_pydantic(self) -> GraphModel:
         """Converts the runtime graph to its Pydantic model representation."""
         return GraphModel(
@@ -237,6 +376,13 @@ def save(self, save_path: str) -> None:
         with open(save_path, "w") as f:
             f.write(self.to_json())
 
+        # Save failed generations if any
+        if self.failed_generations:
+            failed_path = save_path.replace(".json", "_failed.jsonl")
+            with open(failed_path, "w") as f:
+                for failed in self.failed_generations:
+                    f.write(json.dumps({"failed_generation": failed}) + "\n")
+
     @classmethod
     def from_json(cls, json_path: str, params: dict) -> "Graph":
         """Load a topic graph from a JSON file."""
@@ -268,6 +414,36 @@ def from_json(cls, json_path: str, params: dict) -> "Graph":
         graph._next_node_id = max(graph.nodes.keys()) + 1
         return graph
 
+    @classmethod
+    def load(cls, json_path: str) -> "Graph":
+        """Load a graph from JSON without initializing LLM client.
+
+        Intended for inspection and manipulation operations that don't
+        require LLM generation capabilities. Restores provider, model,
+        and temperature from the file metadata so saves preserve them.
+        """
+        params = {
+            "topic_prompt": "loaded",
+            "model_name": "placeholder/model",
+            "degree": 3,
+            "depth": 2,
+            "temperature": 0.7,
+        }
+        graph = cls.from_json(json_path, params)
+
+        # Restore original metadata so save() preserves provenance
+        with open(json_path) as f:
+            raw = json.load(f)
+        file_meta = raw.get("metadata") or {}
+        if file_meta.get("provider"):
+            graph.provider = file_meta["provider"]
+        if file_meta.get("model"):
+            graph.model_name = file_meta["model"]
+        if file_meta.get("temperature") is not None:
+            graph.temperature = file_meta["temperature"]
+
+        return graph
+
     def visualize(self, save_path: str) -> None:
         """Visualize the graph and save it to a file."""
         try:
@@ -454,7 +630,7 @@ async def _generate_subtopics_with_retry(
                     prompt=prompt,
                     schema=GraphSubtopics,
                     max_retries=1,  # Don't retry inside - we handle it here
-                    max_tokens=DEFAULT_MAX_TOKENS,
+                    max_tokens=self.max_tokens,
                     temperature=self.temperature,
                 )