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

deepfabric/tui.py

@@ -1,8 +1,10 @@
 import contextlib
 import json
+import math
 import os
 import re
 
+from abc import abstractmethod
 from collections import deque
 from dataclasses import dataclass
 from time import monotonic
@@ -30,71 +32,6 @@ if TYPE_CHECKING:
     from .error_codes import ClassifiedError
 
 
-class TopicBuildingMixin:
-    """Mixin providing shared functionality for Tree and Graph building TUIs.
-
-    Provides common implementations for:
-    - _refresh_left(): Update events panel in left column
-    - on_error(): Handle error events from progress reporter
-    - on_step_start()/on_step_complete(): No-op handlers for step events
-    - update_status_panel(): Update status panel (requires _status_panel() in subclass)
-
-    Subclasses must have these attributes:
-    - tui: DeepFabricTUI instance
-    - live_display: Live | None
-    - live_layout: Layout | None
-    - events_log: deque
-    """
-
-    tui: "DeepFabricTUI"
-    live_display: "Live | None"
-    live_layout: "Layout | None"
-    events_log: "deque"
-
-    def stop_live(self) -> None:
-        """Stop the Live display if it's running."""
-        if self.live_display:
-            self.live_display.stop()
-            self.live_display = None
-
-    def _refresh_left(self) -> None:
-        """Update events panel in left column."""
-        if self.live_layout is not None:
-            try:
-                self.live_layout["main"]["left"]["events"].update(
-                    self.tui.build_events_panel(list(self.events_log))
-                )
-            except Exception:
-                return
-
-    def on_error(self, error: "ClassifiedError", metadata: dict[str, Any]) -> None:  # noqa: ARG002
-        """Handle error events - log to events panel."""
-        error_event = error.to_event()
-        self.events_log.append(f"X {error_event}")
-        self._refresh_left()
-
-    def on_step_start(self, step_name: str, metadata: dict[str, Any]) -> None:  # noqa: ARG002
-        """Handle step start - topic building doesn't need specific handling."""
-        pass
-
-    def on_step_complete(self, step_name: str, metadata: dict[str, Any]) -> None:  # noqa: ARG002
-        """Handle step complete - topic building doesn't need specific handling."""
-        pass
-
-    def update_status_panel(self) -> None:
-        """Update the status panel in the right column."""
-        if self.live_layout is None:
-            return
-        try:
-            self.live_layout["main"]["right"]["status"].update(self._status_panel())
-        except Exception:
-            return
-
-    def _status_panel(self) -> Panel:
-        """Create status panel - must be implemented by subclass."""
-        raise NotImplementedError
-
-
 # Constants
 STREAM_BUFFER_DISPLAY_THRESHOLD = 1000  # Show ellipsis if accumulated text exceeds this
 STREAM_TEXT_MAX_LENGTH = 8000  # Max characters to display in streaming text
@@ -111,23 +48,26 @@ TOPIC_PREVIEW_OFFSET = 13
 # Truncation limits for event log display
 EVENT_TOPIC_MAX_LENGTH = 20  # Max chars for topic names in events
 EVENT_ERROR_MAX_LENGTH = 80  # Max chars for error summaries in events
+ERROR_MESSAGE_MAX_LENGTH = 200  # Max chars for detailed error messages in simple mode
 
 
 @dataclass
 class TUISettings:
     mode: str = "rich"  # 'rich' or 'simple'
     syntax: bool = True  # enable syntax highlighting in preview
+    show_failures: bool = False  # show failure details in real-time
 
 
 _tui_settings = TUISettings()
 
 
-def configure_tui(mode: str) -> None:
+def configure_tui(mode: str, show_failures: bool = False) -> None:
     mode = (mode or "rich").lower().strip()
     if mode not in {"rich", "simple"}:
         mode = "rich"
     _tui_settings.mode = mode
     _tui_settings.syntax = mode == "rich"
+    _tui_settings.show_failures = show_failures
 
 
 def get_tui_settings() -> TUISettings:
@@ -290,44 +230,105 @@ class DeepFabricTUI:
         self.console.print(f"• {message}", style="blue")
 
 
-class TreeBuildingTUI(TopicBuildingMixin, StreamObserver):
-    """TUI for tree building operations with simplified progress and streaming."""
+class TopicGenerationTUI(StreamObserver):
+    """Abstract base for Tree and Graph building TUIs.
+
+    Provides shared initialization, layout setup, streaming, retry handling,
+    and event management. Subclasses customize via template methods.
+
+    Subclasses must implement:
+    - _get_title() -> str
+    - _get_subtitle(model_name) -> str
+    - _get_footer_description() -> str
+    - _topic_model_type() -> str  ('tree' or 'graph')
+    - _status_panel() -> Panel
+    """
 
     def __init__(self, tui: DeepFabricTUI):
         self.tui = tui
         self.console = tui.console
         self.progress = None
         self.overall_task = None
-        self.generated_paths = 0
         self.failed_attempts = 0
-        self.current_depth = 0
-        self.max_depth = 0
         self.stream_buffer = deque(maxlen=2000)
-        self.live_display = None
+        self.live_display: Live | None = None
         self.live_layout: Layout | None = None
         self.events_log = deque(maxlen=EVENT_LOG_MAX_LINES)
-        self.simple_mode = False
         self.current_topic_path: list[str] | None = None
         self.root_topic: str | None = None
+        self.max_depth = 0
+        self.current_depth = 0
+        self._is_simple = get_tui_settings().mode == "simple"
+        self.simple_progress: Progress | None = None
+        self.simple_task = None
+
+    # ---- Template methods for subclass customization ----
+
+    @abstractmethod
+    def _get_title(self) -> str:
+        """Return header title for this TUI."""
+        ...
+
+    @abstractmethod
+    def _get_subtitle(self, model_name: str) -> str:
+        """Return header subtitle for this TUI."""
+        ...
+
+    @abstractmethod
+    def _get_footer_description(self) -> str:
+        """Return footer progress description."""
+        ...
+
+    @abstractmethod
+    def _topic_model_type(self) -> str:
+        """Return 'tree' or 'graph' for context panel."""
+        ...
+
+    @abstractmethod
+    def _status_panel(self) -> Panel:
+        """Create status panel - must be implemented by subclass."""
+        ...
+
+    @abstractmethod
+    def _get_simple_total(self, depth: int, degree: int) -> int:
+        """Return the total for the simple mode progress bar."""
+        ...
+
+    # ---- Lifecycle ----
 
     def start_building(self, model_name: str, depth: int, degree: int, root_topic: str) -> None:
-        """Start the tree building process."""
+        """Start the building process. Handles both simple and rich modes."""
         self.max_depth = depth
         self.root_topic = root_topic
 
-        # If simple/headless mode, print static header and return without Live
-        if get_tui_settings().mode == "simple":
-            header_panel = self.tui.create_header(
-                "DeepFabric Tree Generation",
-                f"Building hierarchical topic structure with {model_name}",
-            )
-            self.console.print(header_panel)
-            self.console.print(f"Configuration: depth={depth}, degree={degree}")
+        header_panel = self.tui.create_header(
+            self._get_title(),
+            self._get_subtitle(model_name),
+        )
+
+        # Simple/headless mode: print config summary, optional progress bar, no Live
+        if self._is_simple:
+            self.console.print("\n[bold cyan]Topic Generation[/bold cyan]")
+            self.tui.info(f"Model: {model_name}")
+            self.tui.info(f"Topic configuration: depth={depth}, degree={degree}")
             self.console.print()
-            self.simple_mode = True
+            total = self._get_simple_total(depth, degree)
+            if self.console.is_terminal:
+                self.simple_progress = Progress(
+                    SpinnerColumn(),
+                    TextColumn("[progress.description]{task.description}"),
+                    BarColumn(),
+                    MofNCompleteColumn(table_column=Column(justify="right")),
+                    TimeElapsedColumn(),
+                    console=self.console,
+                )
+                self.simple_task = self.simple_progress.add_task(
+                    self._get_footer_description(), total=total
+                )
+                self.simple_progress.start()
             return
 
-        # Create simple progress display with indeterminate progress
+        # Rich mode: build full two-pane layout with footer
         self.progress = Progress(
             SpinnerColumn(),
             TextColumn(
@@ -338,17 +339,13 @@ class TreeBuildingTUI(TopicBuildingMixin, StreamObserver):
             TimeElapsedColumn(),
             console=self.console,
         )
-        # Two-pane layout: left header + progress + events; right status + preview
+
         layout = Layout(name="root")
         layout.split(Layout(name="main"), Layout(name="footer", size=3))
         left = Layout(name="left", ratio=3)
         right = Layout(name="right", ratio=2)
         right.minimum_size = STREAM_PANEL_WIDTH
 
-        header_panel = self.tui.create_header(
-            "DeepFabric Tree Generation",
-            f"Building hierarchical topic structure with {model_name}",
-        )
         stats = {"Model": model_name, "Depth": f"{depth}", "Degree": f"{degree}"}
         stats_table = self.tui.create_stats_table(stats)
         params_panel = Panel(stats_table, title="Generation Parameters", border_style="dim")
@@ -363,7 +360,7 @@ class TreeBuildingTUI(TopicBuildingMixin, StreamObserver):
         left["params"].update(params_panel)
         left["context"].update(self._context_panel())
         left["events"].update(self.tui.build_events_panel(list(self.events_log)))
-        # Right column: status + preview (preview fills remaining space)
+
         right.split(
             Layout(name="status", size=8),
             Layout(name="preview"),
@@ -372,59 +369,109 @@ class TreeBuildingTUI(TopicBuildingMixin, StreamObserver):
         right["status"].update(self._status_panel())
         right["preview"].update(self.tui.build_stream_panel("Waiting for generation..."))
 
-        # Start Live display with layout
         self.live_layout = layout
-        # Footer progress
+        footer_desc = self._get_footer_description()
         self.footer_progress = self.tui.create_footer(layout, title="Run Status")
-        self.footer_task = self.footer_progress.add_task("Building topic tree", total=depth)
+        self.footer_task = self.footer_progress.add_task(footer_desc, total=depth)
 
         self.live_display = Live(layout, console=self.console, refresh_per_second=15, screen=True)
         self.live_display.start()
-        self.overall_task = self.progress.add_task(f"Building topic tree (depth 1/{depth})")
-
-    def start_depth_level(self, depth: int) -> None:
-        """Update progress for new depth level."""
-        self.current_depth = depth
-        if self.progress and self.overall_task is not None:
-            self.progress.update(
-                self.overall_task,
-                description=f"Building topic tree (depth {depth}/{self.max_depth})",
-            )
-        self.events_log.append(f"→ Depth {depth}/{self.max_depth} started")
-        self._refresh_left()
-        # Advance footer on each depth start (only after first)
-        self.update_status_panel()
+        self.overall_task = self.progress.add_task(f"{footer_desc} (depth 1/{depth})")
 
-    def start_subtree_generation(self, node_path: list[str], _num_subtopics: int) -> None:
-        """Log subtree generation without updating progress to avoid flicker."""
-        self.current_topic_path = node_path
-        self._refresh_context()
-        pass
+    def stop_live(self) -> None:
+        """Stop the Live display if it's running."""
+        if self.live_display:
+            self.live_display.stop()
+            self.live_display = None
 
-    def complete_subtree_generation(self, success: bool, generated_count: int) -> None:
-        """Track completion without updating progress bar."""
-        if success:
-            self.generated_paths += generated_count
+    def advance_simple_progress(self, advance: int = 1, description: str = "") -> None:
+        """Advance the simple mode progress bar."""
+        if self.simple_progress is not None and self.simple_task is not None:
+            with contextlib.suppress(Exception):
+                if description:
+                    self.simple_progress.update(
+                        self.simple_task, advance=advance, description=description
+                    )
+                else:
+                    self.simple_progress.update(self.simple_task, advance=advance)
+
+    def stop_simple_progress(self) -> None:
+        """Stop the simple mode progress bar."""
+        if self.simple_progress is not None:
+            self.simple_progress.stop()
+            self.simple_progress = None
+
+    def _simple_print(self, message: str) -> None:
+        """Print a message in simple mode, routing through the progress bar if active."""
+        if self.simple_progress is not None:
+            self.simple_progress.console.print(message)
         else:
-            self.failed_attempts += 1
-        # Log succinct outcome
-        status = "ok" if success else "fail"
-        self.events_log.append(f"✓ Subtree {status} (+{generated_count} paths)")
-        self._refresh_left()
-        self.update_status_panel()
-        # Advance footer on completed depth
-        with contextlib.suppress(Exception):
-            self.footer_progress.update(self.footer_task, advance=1)
+            self.console.print(message)
 
-    def add_failure(self) -> None:
-        """Record a generation failure."""
-        self.failed_attempts += 1
-        self.events_log.append("✗ Generation failed")
+    # ---- Panel refresh helpers ----
+
+    def _refresh_left(self) -> None:
+        """Update events panel in left column."""
+        if self.live_layout is not None:
+            try:
+                self.live_layout["main"]["left"]["events"].update(
+                    self.tui.build_events_panel(list(self.events_log))
+                )
+            except Exception:
+                return
+
+    def update_status_panel(self) -> None:
+        """Update the status panel in the right column."""
+        if self.live_layout is None:
+            return
+        try:
+            self.live_layout["main"]["right"]["status"].update(self._status_panel())
+        except Exception:
+            return
+
+    def _context_panel(self) -> Panel:
+        return self.tui.build_context_panel(
+            root_topic=self.root_topic,
+            topic_model_type=self._topic_model_type(),
+            path=self.current_topic_path,
+        )
+
+    def _refresh_context(self) -> None:
+        if self.live_layout is not None:
+            try:
+                self.live_layout["main"]["left"]["context"].update(self._context_panel())
+            except Exception:
+                return
+
+    # ---- StreamObserver event handlers ----
+
+    def on_error(self, error: "ClassifiedError", metadata: dict[str, Any]) -> None:  # noqa: ARG002
+        """Handle error events - log to events panel."""
+        error_event = error.to_event()
+        self.events_log.append(f"X {error_event}")
         self._refresh_left()
-        self.update_status_panel()
+
+        # In simple mode with --show-failures, print detailed error immediately
+        if self._is_simple and get_tui_settings().show_failures:
+            self.tui.console.print(f"[red]✗ FAILURE:[/red] {error_event}")
+            if error.message and error.message != error_event:
+                msg = (
+                    error.message[:ERROR_MESSAGE_MAX_LENGTH] + "..."
+                    if len(error.message) > ERROR_MESSAGE_MAX_LENGTH
+                    else error.message
+                )
+                self.tui.console.print(f"  [dim]{msg}[/dim]")
+
+    def on_step_start(self, step_name: str, metadata: dict[str, Any]) -> None:  # noqa: ARG002
+        """Handle step start - topic building doesn't need specific handling."""
+        pass
+
+    def on_step_complete(self, step_name: str, metadata: dict[str, Any]) -> None:  # noqa: ARG002
+        """Handle step complete - topic building doesn't need specific handling."""
+        pass
 
     def on_stream_chunk(self, _source: str, chunk: str, _metadata: dict[str, Any]) -> None:
-        """Handle streaming text from tree generation."""
+        """Handle streaming text from topic generation."""
         self.stream_buffer.append(chunk)
         if self.live_display and self.live_layout is not None:
             accumulated_text = "".join(self.stream_buffer)
@@ -469,7 +516,7 @@ class TreeBuildingTUI(TopicBuildingMixin, StreamObserver):
         error_summary: str,
         metadata: dict[str, Any],
     ) -> None:
-        """Handle retry events from the progress reporter by logging a concise message."""
+        """Handle retry events by logging a concise message."""
         _ = metadata  # Unused for now
         try:
             self.events_log.append(
@@ -480,33 +527,103 @@ class TreeBuildingTUI(TopicBuildingMixin, StreamObserver):
             # Swallow errors to avoid breaking progress reporting
             return
 
-    def _context_panel(self) -> Panel:
-        return self.tui.build_context_panel(
-            root_topic=self.root_topic,
-            topic_model_type="tree",
-            path=self.current_topic_path,
-        )
+    def on_llm_retry(
+        self,
+        provider: str,
+        attempt: int,
+        wait: float,
+        error_summary: str,
+        metadata: dict[str, Any],
+    ) -> None:
+        """Handle LLM API retry events (rate limits, transient errors)."""
+        _ = metadata
+        try:
+            short_msg = f"↻ {provider} retry (attempt {attempt}), backoff {wait:.1f}s"
+            self.events_log.append(short_msg)
+            self._refresh_left()
 
-    def _refresh_context(self) -> None:
-        if self.live_layout is not None:
-            try:
-                self.live_layout["main"]["left"]["context"].update(self._context_panel())
-            except Exception:
-                return
+            if self._is_simple:
+                self._simple_print(f"    [yellow]{short_msg}: {error_summary}[/yellow]")
+        except Exception:
+            return
+
+
+class TreeBuildingTUI(TopicGenerationTUI):
+    """TUI for tree building operations."""
+
+    def __init__(self, tui: DeepFabricTUI):
+        super().__init__(tui)
+        self.generated_paths = 0
+
+    def _get_title(self) -> str:
+        return "DeepFabric Tree Generation"
+
+    def _get_subtitle(self, model_name: str) -> str:
+        return f"Building hierarchical topic structure with {model_name}"
+
+    def _get_footer_description(self) -> str:
+        return "Building topic tree"
+
+    def _topic_model_type(self) -> str:
+        return "tree"
+
+    def _get_simple_total(self, depth: int, degree: int) -> int:
+        if degree <= 1:
+            return depth
+        return (degree**depth - 1) // (degree - 1)
+
+    def start_depth_level(self, depth: int) -> None:
+        """Update progress for new depth level."""
+        self.current_depth = depth
+        if self.progress and self.overall_task is not None:
+            self.progress.update(
+                self.overall_task,
+                description=f"Building topic tree (depth {depth}/{self.max_depth})",
+            )
+        self.events_log.append(f"→ Depth {depth}/{self.max_depth} started")
+        self._refresh_left()
+        self.update_status_panel()
+
+    def start_subtree_generation(self, node_path: list[str], _num_subtopics: int) -> None:
+        """Log subtree generation without updating progress to avoid flicker."""
+        self.current_topic_path = node_path
+        self._refresh_context()
+
+    def complete_subtree_generation(self, success: bool, generated_count: int) -> None:
+        """Track completion without updating progress bar."""
+        if success:
+            self.generated_paths += generated_count
+        else:
+            self.failed_attempts += 1
+        # Log succinct outcome
+        status = "ok" if success else "fail"
+        self.events_log.append(f"✓ Subtree {status} (+{generated_count} paths)")
+        self._refresh_left()
+        self.update_status_panel()
+        # Advance footer on completed depth
+        with contextlib.suppress(Exception):
+            self.footer_progress.update(self.footer_task, advance=1)
+
+    def add_failure(self) -> None:
+        """Record a generation failure."""
+        self.failed_attempts += 1
+        self.advance_simple_progress()
+        self.events_log.append("✗ Generation failed")
+        self._refresh_left()
+        self.update_status_panel()
 
     def finish_building(self, total_paths: int, failed_generations: int) -> None:
         """Finish the tree building process."""
         if self.live_display:
             self.live_display.stop()
+        self.stop_simple_progress()
 
         # Final summary
         self.console.print()
         if failed_generations > 0:
-            self.tui.warning(f"Tree building complete with {failed_generations} failures")
+            self.tui.warning(f"Created {total_paths} unique topics ({failed_generations} failed)")
         else:
-            self.tui.success("Tree building completed successfully")
-
-        self.tui.info(f"Generated {total_paths} total paths")
+            self.tui.success(f"Created {total_paths} unique topics")
         self.events_log.append("✓ Tree building completed")
         self.update_status_panel()
 
@@ -522,101 +639,37 @@ class TreeBuildingTUI(TopicBuildingMixin, StreamObserver):
         return Panel(table, title="Status", border_style="dim", padding=(0, 1))
 
 
-class GraphBuildingTUI(TopicBuildingMixin, StreamObserver):
-    """TUI for graph building operations with simplified progress and streaming."""
+class GraphBuildingTUI(TopicGenerationTUI):
+    """TUI for graph building operations."""
 
     def __init__(self, tui: DeepFabricTUI):
-        self.tui = tui
-        self.console = tui.console
-        self.progress = None
-        self.overall_task = None
+        super().__init__(tui)
         self.nodes_count = 1  # Start with root
         self.edges_count = 0
-        self.failed_attempts = 0
-        self.stream_buffer = deque(maxlen=2000)
-        self.live_display = None
-        self.live_layout: Layout | None = None
-        self.events_log = deque(maxlen=EVENT_LOG_MAX_LINES)
-        self.simple_mode = False
-        self.current_topic_path: list[str] | None = None
-        self.root_topic: str | None = None
 
-    def start_building(self, model_name: str, depth: int, degree: int, root_topic: str) -> None:
-        """Start the graph building process."""
-        self.max_depth = depth
-        self.current_depth = 0
-        self.root_topic = root_topic
-        # If simple/headless mode, print static header and return
-        if get_tui_settings().mode == "simple":
-            header = self.tui.create_header(
-                "DeepFabric Graph Generation",
-                f"Building interconnected topic structure with {model_name}",
-            )
-            self.console.print(header)
-            self.console.print(f"Configuration: depth={depth}, degree={degree}")
-            self.console.print()
-            self.simple_mode = True
-            return
+    def _get_title(self) -> str:
+        return "DeepFabric Graph Generation"
 
-        # Create simple progress display
-        self.progress = Progress(
-            SpinnerColumn(),
-            TextColumn(
-                "[bold blue]{task.description}",
-                table_column=Column(ratio=1, overflow="ellipsis"),
-            ),
-            BarColumn(bar_width=None),
-            MofNCompleteColumn(),
-            TimeElapsedColumn(),
-            console=self.console,
-        )
-        # Two-pane layout: left header + events; right status + preview with footer at bottom
-        layout = Layout(name="root")
-        layout.split(Layout(name="main"), Layout(name="footer", size=3))
-        left = Layout(name="left", ratio=3)
-        right = Layout(name="right", ratio=2)
-        right.minimum_size = STREAM_PANEL_WIDTH
+    def _get_subtitle(self, model_name: str) -> str:
+        return f"Building interconnected topic structure with {model_name}"
 
-        header_panel = self.tui.create_header(
-            "DeepFabric Graph Generation",
-            f"Building interconnected topic structure with {model_name}",
-        )
-        stats = {"Model": model_name, "Depth": f"{depth}", "Degree": f"{degree}"}
-        stats_table = self.tui.create_stats_table(stats)
-        params_panel = Panel(stats_table, title="Generation Parameters", border_style="dim")
-
-        left.split(
-            Layout(name="header", size=4),
-            Layout(name="params", size=5),
-            Layout(name="context", size=5),
-            Layout(name="events"),
-        )
-        left["header"].update(header_panel)
-        left["params"].update(params_panel)
-        left["context"].update(self._context_panel())
-        left["events"].update(self.tui.build_events_panel(list(self.events_log)))
-        # Right column: status + preview (preview fills remaining space)
-        right.split(
-            Layout(name="status", size=8),
-            Layout(name="preview"),
-        )
-        layout["main"].split_row(left, right)
-        right["status"].update(self._status_panel())
-        right["preview"].update(self.tui.build_stream_panel("Waiting for generation..."))
+    def _get_footer_description(self) -> str:
+        return "Building topic graph"
 
-        # Footer progress
-        self.footer_progress = self.tui.create_footer(layout, title="Run Status")
-        self.footer_task = self.footer_progress.add_task("Building topic graph", total=depth)
+    def _topic_model_type(self) -> str:
+        return "graph"
 
-        self.live_layout = layout
-        self.live_display = Live(layout, console=self.console, refresh_per_second=15, screen=True)
-        self.live_display.start()
-        self.overall_task = self.progress.add_task("  Building topic graph", total=depth)
+    def _get_simple_total(self, depth: int, degree: int) -> int:  # noqa: ARG002
+        return depth
 
     def start_depth_level(self, depth: int, leaf_count: int) -> None:
         """Update for new depth level."""
-        if self.simple_mode:
-            self.console.print(f"  Depth {depth}: expanding {leaf_count} nodes...")
+        if self._is_simple:
+            desc = f"Depth {depth}/{self.max_depth} ({leaf_count} nodes)"
+            if self.simple_progress is not None:
+                self.advance_simple_progress(advance=0, description=desc)
+            else:
+                self.console.print(f"  Depth {depth}: expanding {leaf_count} nodes...")
         elif self.progress and self.overall_task is not None:
             self.progress.update(
                 self.overall_task,
@@ -637,10 +690,13 @@ class GraphBuildingTUI(TopicBuildingMixin, StreamObserver):
 
     def complete_depth_level(self, depth: int) -> None:
         """Complete a depth level."""
-        if self.simple_mode:
-            self.console.print(
-                f"    Depth {depth} complete (nodes: {self.nodes_count}, edges: {self.edges_count})"
-            )
+        if self._is_simple:
+            if self.simple_progress is not None:
+                self.advance_simple_progress()
+            else:
+                self.console.print(
+                    f"  Depth {depth} complete (nodes: {self.nodes_count}, edges: {self.edges_count})"
+                )
         elif self.progress and self.overall_task is not None:
             self.progress.advance(self.overall_task, 1)
         self.events_log.append(f"✓ Depth {depth} complete")
@@ -653,12 +709,12 @@ class GraphBuildingTUI(TopicBuildingMixin, StreamObserver):
     def add_failure(self, node_topic: str) -> None:
         """Record a generation failure."""
         self.failed_attempts += 1
-        if self.simple_mode:
+        if self._is_simple:
             if len(node_topic) > EVENT_ERROR_MAX_LENGTH:
                 topic_display = node_topic[:EVENT_ERROR_MAX_LENGTH] + "..."
             else:
                 topic_display = node_topic
-            self.console.print(f"    [red]✗ Node expansion failed: {topic_display}[/red]")
+            self._simple_print(f"    [red]✗ Node expansion failed: {topic_display}[/red]")
         self.events_log.append("✗ Node expansion failed")
         self._refresh_left()
 
@@ -692,9 +748,9 @@ class GraphBuildingTUI(TopicBuildingMixin, StreamObserver):
             else:
                 error_display = error_summary
 
-            # In simple mode, print directly to console
-            if self.simple_mode:
-                self.console.print(
+            # In simple mode, print through progress-aware helper
+            if self._is_simple:
+                self._simple_print(
                     f"    [yellow]↻ Retry {attempt}/{max_attempts} '{topic_display}': {error_display}[/yellow]"
                 )
 
@@ -706,100 +762,35 @@ class GraphBuildingTUI(TopicBuildingMixin, StreamObserver):
             # Best-effort, swallow errors to avoid breaking progress reporting
             return
 
-    def on_retry(
-        self,
-        sample_idx: int,
-        attempt: int,
-        max_attempts: int,
-        error_summary: str,
-        metadata: dict[str, Any],
-    ) -> None:
-        """Handle retry events from the progress reporter.
-
-        Provides a minimal implementation so GraphBuildingTUI is not abstract;
-        logs a concise retry message to the events panel.
-        """
-        _ = metadata  # Unused for now
-        try:
-            self.events_log.append(
-                f"↻ Retry sample {sample_idx} attempt {attempt}/{max_attempts}: {error_summary}"
-            )
-            self._refresh_left()
-        except Exception:
-            # Best-effort, swallow errors to avoid breaking progress reporting
-            return
-
-    def on_stream_chunk(self, _source: str, chunk: str, _metadata: dict[str, Any]) -> None:
-        """Handle streaming text from graph generation."""
-        self.stream_buffer.append(chunk)
-        if self.live_display and self.live_layout is not None:
-            accumulated_text = "".join(self.stream_buffer)
-            if len(accumulated_text) > STREAM_TEXT_MAX_LENGTH:
-                accumulated_text = "..." + accumulated_text[-STREAM_TEXT_MAX_LENGTH:]
-            display_text = accumulated_text.replace("\r", "")
-            display_text = re.sub(r"[^\S\n]+", " ", display_text)
-
-            # Compute dynamic preview lines based on terminal height
-            # Use TOPIC_PREVIEW_OFFSET for tree/graph TUIs (simpler layout)
-            terminal_height = self.console.size.height
-            target_lines = max(MIN_PREVIEW_LINES, terminal_height - TOPIC_PREVIEW_OFFSET)
-            lines = display_text.splitlines()
-
-            # Handle low-newline content (like JSON) to fill panel properly
-            if len(lines) >= int(target_lines / 2):
-                # Plenty of newlines: take the last N lines
-                visible_lines = lines[-target_lines:]
-            else:
-                # Low-newline content: take a character tail and then split
-                approx_right_cols = max(40, int(self.console.size.width * 0.42))
-                char_tail = max(800, approx_right_cols * max(8, target_lines - 2))
-                tail = display_text[-char_tail:]
-                visible_lines = tail.splitlines()[-target_lines:]
-
-            visible = "\n".join(visible_lines)
-
-            # Update the streaming panel
-            try:
-                container = self.live_layout["main"]["right"]["preview"]
-            except Exception:
-                container = self.live_layout["main"]["right"]
-            container.update(self.tui.build_stream_panel(visible))
-
-    def _context_panel(self) -> Panel:
-        return self.tui.build_context_panel(
-            root_topic=self.root_topic,
-            topic_model_type="graph",
-            path=self.current_topic_path,
-        )
-
-    def _refresh_context(self) -> None:
-        if self.live_layout is not None:
-            try:
-                self.live_layout["main"]["left"]["context"].update(self._context_panel())
-            except Exception:
-                return
-
     def finish_building(self, failed_generations: int) -> None:
         """Finish the graph building process."""
         if self.live_display:
             self.live_display.stop()
+        self.stop_simple_progress()
 
-        # Show final stats
         self.console.print()
-        stats_table = self.tui.create_stats_table(
-            {
-                "Total Nodes": self.nodes_count,
-                "Total Edges": self.edges_count,
-                "Failed Attempts": self.failed_attempts,
-            }
-        )
-        self.console.print(Panel(stats_table, title="Final Statistics", border_style="dim"))
-
-        # Final summary
-        if failed_generations > 0:
-            self.tui.warning(f"Graph building complete with {failed_generations} failures")
+        if self._is_simple:
+            # One-liner summary for simple/headless mode
+            if failed_generations > 0:
+                self.tui.warning(
+                    f"Created {self.nodes_count} unique topics ({failed_generations} failed)"
+                )
+            else:
+                self.tui.success(f"Created {self.nodes_count} unique topics")
         else:
-            self.tui.success("Graph building completed successfully")
+            # Rich mode: show detailed stats panel
+            stats_table = self.tui.create_stats_table(
+                {
+                    "Total Nodes": self.nodes_count,
+                    "Total Edges": self.edges_count,
+                    "Failed Attempts": self.failed_attempts,
+                }
+            )
+            self.console.print(Panel(stats_table, title="Final Statistics", border_style="dim"))
+            if failed_generations > 0:
+                self.tui.warning(f"Graph building complete with {failed_generations} failures")
+            else:
+                self.tui.success("Graph building completed successfully")
         self.events_log.append("✓ Graph building completed")
         self.update_status_panel()
 
@@ -808,7 +799,7 @@ class GraphBuildingTUI(TopicBuildingMixin, StreamObserver):
         table = Table(show_header=False, box=None, padding=(0, 1))
         table.add_column(style="cyan", no_wrap=True)
         table.add_column(style="white")
-        table.add_row("Depth:", f"{self.current_depth}/{getattr(self, 'max_depth', 0)}")
+        table.add_row("Depth:", f"{self.current_depth}/{self.max_depth}")
         table.add_row("Nodes:", str(self.nodes_count))
         table.add_row("Edges:", str(self.edges_count))
         if self.failed_attempts:
@@ -853,6 +844,9 @@ class DatasetGenerationTUI(StreamObserver):
         self.last_checkpoint_samples = 0
         self._resumed_from_checkpoint = False  # Set by set_checkpoint_resume_status()
         self._stop_requested = False  # Set when graceful stop requested via Ctrl+C
+        self._is_cycle_based = False  # Set by init_status; controls "Cycle" vs "Step" labels
+        self._is_simple = get_tui_settings().mode != "rich"
+        self.simple_progress: Progress | None = None  # Set by dataset_manager for simple mode
         # Retry tracking for simple mode
         self.step_retries: list[dict] = []  # Retries in current step
 
@@ -872,26 +866,69 @@ class DatasetGenerationTUI(StreamObserver):
         return self.progress
 
     def build_generation_panels(
-        self, model_name: str, num_steps: int, batch_size: int
+        self,
+        model_name: str,
+        num_steps: int,
+        batch_size: int,
+        total_samples: int | None = None,
+        is_cycle_based: bool = False,
+        unique_topics: int = 0,
+        final_cycle_size: int = 0,
+        checkpoint_interval: int = 0,
     ) -> tuple[Panel, Panel]:
-        """Return header and parameters panels for layout use (no direct printing)."""
+        """Return header and parameters panels for layout use (no direct printing).
+
+        Args:
+            model_name: Name of the LLM model being used.
+            num_steps: Number of steps (step-based) or cycles (cycle-based).
+            batch_size: Batch size (step-based) or concurrency (cycle-based).
+            total_samples: Explicit total samples count. If None, calculated as num_steps * batch_size.
+            is_cycle_based: If True, display "Cycles" and "Concurrency" instead of "Steps" and "Batch Size".
+            unique_topics: Number of unique topics (cycle-based).
+            final_cycle_size: Size of the final cycle (cycle-based).
+            checkpoint_interval: Checkpoint interval in samples.
+        """
         header = self.tui.create_header(
             "DeepFabric Dataset Generation",
             f"Creating synthetic traces with {model_name}",
         )
-        stats = {
-            "Model": model_name,
-            "Steps": num_steps,
-            "Batch Size": batch_size,
-            "Total Samples": num_steps * batch_size,
-        }
-        stats_table = self.tui.create_stats_table(stats)
-        params_panel = Panel(stats_table, title="Generation Parameters", border_style="dim")
 
-        # Seed events log
-        self.events_log.append(
-            f"Start • steps={num_steps} batch={batch_size} total={num_steps * batch_size}"
+        display_total = total_samples if total_samples is not None else num_steps * batch_size
+
+        lines = [f"[cyan]Model:[/] {model_name}"]
+
+        if is_cycle_based:
+            lines.append(
+                f"[cyan]Number samples:[/] {display_total}, [cyan]Concurrency:[/] {batch_size}"
+            )
+            cycles_line = (
+                f"[cyan]Cycles needed:[/] {num_steps} "
+                f"({display_total} samples ÷ {unique_topics} unique topics)"
+            )
+            if final_cycle_size and unique_topics and final_cycle_size < unique_topics:
+                cycles_line += f", final cycle: {final_cycle_size} topics (partial)"
+            lines.append(cycles_line)
+            log_msg = f"Start • cycles={num_steps} concurrency={batch_size} total={display_total}"
+        else:
+            lines.append(
+                f"[cyan]Number samples:[/] {display_total}, [cyan]Batch size:[/] {batch_size}"
+            )
+            log_msg = f"Start • steps={num_steps} batch={batch_size} total={display_total}"
+
+        if checkpoint_interval and checkpoint_interval > 0:
+            total_cp = math.ceil(display_total / checkpoint_interval)
+            lines.append(
+                f"[cyan]Checkpoint:[/] every {checkpoint_interval} samples "
+                f"({total_cp} total checkpoints)"
+            )
+
+        params_panel = Panel(
+            Text.from_markup("\n".join(lines)),
+            title="Generation Parameters",
+            border_style="dim",
         )
+
+        self.events_log.append(log_msg)
         return header, params_panel
 
     def on_stream_chunk(self, _source: str, chunk: str, _metadata: dict[str, Any]) -> None:
@@ -1016,8 +1053,17 @@ class DatasetGenerationTUI(StreamObserver):
         self.stream_buffer.clear()
 
     # Deprecated printer retained for backward compatibility
-    def show_generation_header(self, model_name: str, num_steps: int, batch_size: int) -> None:
-        header, params_panel = self.build_generation_panels(model_name, num_steps, batch_size)
+    def show_generation_header(
+        self,
+        model_name: str,
+        num_steps: int,
+        batch_size: int,
+        total_samples: int | None = None,
+        is_cycle_based: bool = False,
+    ) -> None:
+        header, params_panel = self.build_generation_panels(
+            model_name, num_steps, batch_size, total_samples, is_cycle_based
+        )
         self.console.print(header)
         self.console.print(params_panel)
         self.console.print()
@@ -1039,11 +1085,16 @@ class DatasetGenerationTUI(StreamObserver):
 
     # --- Status Panel helpers ---
     def init_status(
-        self, total_steps: int, total_samples: int, checkpoint_enabled: bool = False
+        self,
+        total_steps: int,
+        total_samples: int,
+        checkpoint_enabled: bool = False,
+        is_cycle_based: bool = False,
     ) -> None:
         self.status_total_steps = total_steps
         self.status_total_samples = total_samples
         self.status_current_step = 0
+        self._is_cycle_based = is_cycle_based
         # Preserve samples_done and failed_total if resuming from checkpoint
         if not getattr(self, "_resumed_from_checkpoint", False):
             self.status_samples_done = 0
@@ -1103,21 +1154,29 @@ class DatasetGenerationTUI(StreamObserver):
         table = Table(show_header=False, box=None, padding=(0, 1))
         table.add_column(style="cyan", no_wrap=True)
         table.add_column(style="white")
-        table.add_row("Step:", f"{self.status_current_step}/{self.status_total_steps}")
+        label = "Cycle:" if self._is_cycle_based else "Step:"
+        last_label = "Last Cycle:" if self._is_cycle_based else "Last Step:"
+        table.add_row(label, f"{self.status_current_step}/{self.status_total_steps}")
         if self.status_last_step_duration > 0:
-            table.add_row("Last Step:", f"{self.status_last_step_duration:0.1f}s")
+            table.add_row(last_label, f"{self.status_last_step_duration:0.1f}s")
         table.add_row("Generated:", f"{self.status_samples_done}/{self.status_total_samples}")
         if self.status_failed_total:
             table.add_row("Failed:", str(self.status_failed_total))
         if self.checkpoint_enabled:
             if self.checkpoint_count > 0:
                 table.add_row(
-                    "Checkpoints:", f"{self.checkpoint_count} ({self.last_checkpoint_samples} samples)"
+                    "Checkpoints:",
+                    f"{self.checkpoint_count} ({self.last_checkpoint_samples} samples)",
                 )
             else:
                 table.add_row("Checkpoints:", "0 (enabled)")
         if self._stop_requested:
-            table.add_row("[yellow]Stopping:[/yellow]", "[yellow]at next checkpoint[/yellow]")
+            if self.checkpoint_enabled:
+                table.add_row("[yellow]Stopping:[/yellow]", "[yellow]at next checkpoint[/yellow]")
+            else:
+                table.add_row(
+                    "[yellow]Stopping:[/yellow]", "[yellow]saving partial results[/yellow]"
+                )
         return Panel(table, title="Status", border_style="dim", padding=(0, 1))
 
     def update_status_panel(self) -> None:
@@ -1231,6 +1290,18 @@ class DatasetGenerationTUI(StreamObserver):
         # Log to events panel with error indicator
         self.log_event(f"X {error_event}")
 
+        # In simple mode with --show-failures, print detailed error immediately
+        if self._is_simple and get_tui_settings().show_failures:
+            self.tui.console.print(f"[red]✗ FAILURE:[/red] {error_event}")
+            if error.message and error.message != error_event:
+                # Show truncated full message if different from event
+                msg = (
+                    error.message[:ERROR_MESSAGE_MAX_LENGTH] + "..."
+                    if len(error.message) > ERROR_MESSAGE_MAX_LENGTH
+                    else error.message
+                )
+                self.tui.console.print(f"  [dim]{msg}[/dim]")
+
     def on_retry(
         self,
         sample_idx: int,
@@ -1256,7 +1327,7 @@ class DatasetGenerationTUI(StreamObserver):
         """
         _ = metadata  # Unused for now
 
-        if get_tui_settings().mode != "rich":
+        if self._is_simple:
             # Simple mode: track for summary at step completion
             self.step_retries.append(
                 {
@@ -1288,6 +1359,34 @@ class DatasetGenerationTUI(StreamObserver):
             return f"{total_retries} retry for sample {list(samples_with_retries)[0]}"
         return f"{total_retries} retries across {len(samples_with_retries)} samples"
 
+    def on_llm_retry(
+        self,
+        provider: str,
+        attempt: int,
+        wait: float,
+        error_summary: str,
+        metadata: dict[str, Any],
+    ) -> None:
+        """Handle LLM API retry events (rate limits, transient errors)."""
+        _ = metadata
+        try:
+            short_msg = f"↻ {provider} retry (attempt {attempt}), backoff {wait:.1f}s"
+            self.events_log.append(short_msg)
+            if self.live_layout is not None:
+                self.live_layout["main"]["left"]["events"].update(
+                    self.tui.build_events_panel(list(self.events_log))
+                )
+
+            if self._is_simple:
+                if self.simple_progress is not None:
+                    self.simple_progress.console.print(
+                        f"    [yellow]{short_msg}: {error_summary}[/yellow]"
+                    )
+                else:
+                    self.console.print(f"    [yellow]{short_msg}: {error_summary}[/yellow]")
+        except Exception:
+            return
+
 
 # Global TUI instances
 _tui_instance = None