feat: UUID-based cycle generation with bug fixes and UX improvements (#595)

* feat: UUID-based cycle generation with improved TUI and checkpoint v4

Refactor dataset generation to use UUID-based tracking with cycle-based
topic assignment, fixing an issue where topic cycling exited early
without generating the expected number of samples. Adds simple/headless
TUI mode with progress bars, dynamic Cycle/Step labels, and section
headings for topic and dataset generation phases. Bumps checkpoint
format to v4 for (uuid, cycle) tuple tracking. Includes prompt timeout
for checkpoint resume, improved failure counting after checkpoint clear,
and updated docs and tests.

* fix: TUI improvements and minor cleanups

Add section headings for Topic Generation and Dataset Generation in
simple TUI mode. Fix floating bullet on checkpoint status empty line.
Clarify cloud upload prompt to specify graph and dataset. Remove
redundant help text from --cloud-upload option. Sync uv.lock with
version bump and transformers 5.0.0.

* fix: restore full topic path context in cycle-based generation

Cycle-based generation was only passing the leaf topic text to
build_prompt(), losing the hierarchical path context that step-based
generation preserves. Now uses topic_model.get_path_by_id() to recover
the full root-to-leaf path before building prompts. Also documents
this requirement in CLAUDE.md to prevent future regressions.

* fix: remove duplicate stop_requested initialization in generator

* fix: replace missing _refresh_left call in DatasetGenerationTUI

on_llm_retry() called _refresh_left() which only exists on
TopicGenerationTUI. Replace with inline events panel update
matching the pattern used by log_event() in the same class.
Add unit test to prevent regression.

* fix: remove duplicate generation_stopped event handler in dataset_manager

The second elif handler for "generation_stopped" was unreachable dead
code (duplicate condition). It also lacked simple_progress cleanup
that the first handler correctly includes.

* fix: add Windows fallback for _prompt_with_timeout

select.select on sys.stdin raises OSError on Windows. Fall back to
click.prompt (blocking, no countdown) when platform is Windows.

* fix: exclude root node from graph get_unique_topics

The root node contains the generation seed prompt, not a topic for
sample generation. Its UUID was being included in cycle-based
generation, causing samples to be generated from the raw prompt text.

* fix: target retry logic to specific failed (uuid, cycle) tuples

Previously, when a UUID failed on one cycle, all (uuid, cycle) tuples
were removed from the completed set — including cycles that succeeded.
This caused unnecessary re-generation of already-completed work.

Now failure records include the cycle number, and retry logic removes
only the specific (uuid, cycle) that failed. Includes a legacy
fallback for checkpoint files created before this change.

* chore: remove internal PLAN files and warn on checkpoint interval adjustment

Remove PLAN-generation-refactor.md and PLAN-remaining-work.md which
are internal working documents that should not ship with the codebase.

Add logger.warning when checkpoint_interval is silently bumped to
match concurrency/batch_size, so users understand the adjustment.

* fix: use config mode for topic file loading, warn on extension mismatch

Previously, a .json file extension would override the config mode and
force graph loading, even when mode was set to 'tree'. Now config mode
always takes precedence. A TUI warning is shown when the file extension
does not match the configured mode, guiding users to fix either the
extension or the --mode flag.

* fix: save partial results on Ctrl+C when checkpointing is not enabled

Previously, Ctrl+C without checkpointing showed a misleading
"Stopping after current checkpoint" message and discarded all
generated samples. Now the message is context-aware, and partial
results are saved to the output file when no checkpoint is configured.

* fix: address PR feedback - simplify input handling and add accounting fields

- Remove redundant empty-string check in _prompt_with_timeout (both
  branches returned default)
- Add unaccounted field to cycle-based generation_complete event for
  parity with step-based generation accounting

Author: scp7

CLAUDE.md

@@ -59,6 +59,9 @@ The engine includes robust JSON parsing with regex extraction and retry logic fo
 - Failed samples tracked separately from successful ones
 - Comprehensive error reporting in final summary
 
+### Topic Path Context in Generation
+Dataset generation must always pass the **full hierarchical path** (root -> ... -> leaf) to `build_prompt()`, not just the leaf topic text. This applies to all generation modes (step-based and cycle-based). The full path provides essential context for the LLM to generate domain-specific samples. When modifying generation logic, verify that `subtopics_list` receives the complete path from `TopicModel.get_path_by_id()` or `TopicPath.path`, never just the leaf text in isolation.
+
 ### System Message Control
 The `sys_msg` parameter controls whether system messages are included in the final dataset format - this affects training data structure.
 

deepfabric/cli.py

@@ -2,6 +2,8 @@
 import json
 import math
 import os
+import platform
+import select
 import signal
 import sys
 
@@ -419,6 +421,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 +501,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 +520,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 +530,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 +550,10 @@ def handle_sigint(_signum, _frame):
 
         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 +578,22 @@ def handle_sigint(_signum, _frame):
     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
@@ -652,7 +693,6 @@ def handle_sigint(_signum, _frame):
     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.",
 )
 @click.option(
     "--checkpoint-interval",
@@ -783,7 +823,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 +1337,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 +1946,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
 

deepfabric/cloud_upload.py

@@ -778,7 +778,7 @@ def handle_cloud_upload(  # noqa: PLR0911
 
         # Build prompt based on what's available
         if has_dataset and has_graph:
-            prompt_text = "  Upload to DeepFabric Cloud?"
+            prompt_text = "  Upload graph and dataset to DeepFabric Cloud?"
             hint = "[dim](Y=both, n=skip, c=choose)[/dim]"
         elif has_dataset:
             prompt_text = "  Upload dataset to DeepFabric Cloud?"

deepfabric/config.py

@@ -630,9 +630,7 @@ def get_generation_params(self, **overrides) -> dict:
             # Note: checkpoint_path can be None, meaning "auto-resolve" at runtime
             "checkpoint_interval": self.output.checkpoint.interval if self.output.checkpoint else None,
             "checkpoint_path": self.output.checkpoint.path if self.output.checkpoint else None,
-            "checkpoint_retry_failed": (
-                self.output.checkpoint.retry_failed if self.output.checkpoint else False
-            ),
+            "checkpoint_retry_failed": self.output.checkpoint.retry_failed if self.output.checkpoint else False,
         }
 
         # Tool config

deepfabric/constants.py

@@ -93,7 +93,7 @@
 CHECKPOINT_METADATA_SUFFIX = ".checkpoint.json"
 CHECKPOINT_SAMPLES_SUFFIX = ".checkpoint.jsonl"
 CHECKPOINT_FAILURES_SUFFIX = ".checkpoint.failures.jsonl"
-CHECKPOINT_VERSION = 3  # Increment when checkpoint format changes
+CHECKPOINT_VERSION = 4  # v4: (uuid, cycle) tuple tracking for cycle-based generation
 
 # Stream simulation defaults
 STREAM_SIM_CHUNK_SIZE = 8  # characters per chunk