DeepFabric 4.8.3__py3-none-any.whl → 4.10.0__py3-none-any.whl

deepfabric/cli.py

@@ -1,7 +1,11 @@
 import contextlib
+import json
+import math
 import os
+import signal
 import sys
 
+from pathlib import Path
 from typing import Literal, NoReturn, cast
 
 import click
@@ -13,6 +17,11 @@ from pydantic import ValidationError as PydanticValidationError
 from .auth import auth as auth_group
 from .config import DeepFabricConfig
 from .config_manager import apply_cli_overrides, get_final_parameters, load_config
+from .constants import (
+    CHECKPOINT_FAILURES_SUFFIX,
+    CHECKPOINT_METADATA_SUFFIX,
+    CHECKPOINT_SAMPLES_SUFFIX,
+)
 from .dataset_manager import create_dataset, save_dataset
 from .exceptions import ConfigurationError
 from .generator import DataSetGenerator
@@ -21,9 +30,15 @@ from .llm import VerificationStatus, verify_provider_api_key
 from .metrics import set_trace_debug, trace
 from .topic_manager import load_or_build_topic_model, save_topic_model
 from .topic_model import TopicModel
-from .tui import configure_tui, get_tui
+from .tui import configure_tui, get_dataset_tui, get_tui
 from .update_checker import check_for_updates
-from .utils import get_bool_env
+from .utils import (
+    check_dir_writable,
+    check_path_writable,
+    get_bool_env,
+    get_checkpoint_dir,
+    parse_num_samples,
+)
 from .validation import show_validation_success, validate_path_requirements
 
 OverrideValue = str | int | float | bool | None
@@ -45,6 +60,35 @@ def handle_error(ctx: click.Context, error: Exception) -> NoReturn:
     sys.exit(1)
 
 
+def _get_checkpoint_topics_path(
+    checkpoint_dir: str,
+    output_save_as: str,
+) -> str | None:
+    """
+    Read checkpoint metadata to get the topics path used in the original run.
+
+    Args:
+        checkpoint_dir: Directory containing checkpoint files
+        output_save_as: Output file path (used to derive checkpoint file names)
+
+    Returns:
+        Topics file path from checkpoint metadata, or None if not available
+    """
+    checkpoint_path = Path(checkpoint_dir)
+    output_stem = Path(output_save_as).stem
+    metadata_path = checkpoint_path / f"{output_stem}{CHECKPOINT_METADATA_SUFFIX}"
+
+    if not metadata_path.exists():
+        return None
+
+    try:
+        with open(metadata_path, encoding="utf-8") as f:
+            metadata = json.load(f)
+        return metadata.get("topics_file") or metadata.get("topics_save_as")
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
 @click.group()
 @click.version_option()
 @click.option(
@@ -89,7 +133,7 @@ class GenerateOptions(BaseModel):
     temperature: float | None = None
     degree: int | None = None
     depth: int | None = None
-    num_samples: int | None = None
+    num_samples: int | str | None = None
     batch_size: int | None = None
     base_url: str | None = None
     include_system_message: bool | None = None
@@ -101,16 +145,19 @@ class GenerateOptions(BaseModel):
     # Modular conversation configuration
     conversation_type: Literal["basic", "cot"] | None = None
     reasoning_style: Literal["freetext", "agent", "structured", "hybrid"] | None = None
-    agent_mode: Literal["single_turn", "multi_turn"] | None = None
-
-    # Multi-turn configuration
-    min_turns: int | None = None
-    max_turns: int | None = None
-    min_tool_calls: int | None = None
+    agent_mode: Literal["single_turn", "multi_turn"] | None = (
+        None  # Deprecated, kept for backward compat
+    )
 
     # Cloud upload (experimental)
     cloud_upload: Literal["all", "dataset", "graph", "none"] | None = None
 
+    # Checkpointing options
+    checkpoint_interval: int | None = None
+    checkpoint_path: str | None = None
+    resume: bool = False
+    retry_failed: bool = False
+
     @model_validator(mode="after")
     def validate_mode_constraints(self) -> "GenerateOptions":
         if self.topic_only and self.topics_load:
@@ -126,7 +173,7 @@ class GenerationPreparation(BaseModel):
     config: DeepFabricConfig
     topics_overrides: OverrideMap = Field(default_factory=dict)
     generation_overrides: OverrideMap = Field(default_factory=dict)
-    num_samples: int
+    num_samples: int | str  # Can be int, "auto", or percentage like "50%"
     batch_size: int
     depth: int
     degree: int
@@ -134,7 +181,8 @@ class GenerationPreparation(BaseModel):
 
     @model_validator(mode="after")
     def validate_positive_dimensions(self) -> "GenerationPreparation":
-        if self.num_samples <= 0:
+        # Skip num_samples validation for dynamic values (auto or percentage)
+        if isinstance(self.num_samples, int) and self.num_samples <= 0:
             raise ValueError("num_samples must be greater than zero")
         if self.batch_size <= 0:
             raise ValueError("batch_size must be greater than zero")
@@ -222,6 +270,8 @@ def _validate_api_keys(
 
 def _load_and_prepare_generation_context(
     options: GenerateOptions,
+    *,
+    skip_path_validation: bool = False,
 ) -> GenerationPreparation:
     """Load configuration, compute overrides, and validate derived parameters."""
     tui = get_tui()
@@ -277,23 +327,25 @@ def _load_and_prepare_generation_context(
 
     loading_existing = bool(options.topics_load)
 
-    validate_path_requirements(
-        mode=options.mode,
-        depth=final_depth,
-        degree=final_degree,
-        num_steps=final_num_samples,
-        batch_size=final_batch_size,
-        loading_existing=loading_existing,
-    )
+    # 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,
+            depth=final_depth,
+            degree=final_degree,
+            num_samples=final_num_samples,
+            batch_size=final_batch_size,
+            loading_existing=loading_existing,
+        )
 
-    show_validation_success(
-        mode=options.mode,
-        depth=final_depth,
-        degree=final_degree,
-        num_steps=final_num_samples,
-        batch_size=final_batch_size,
-        loading_existing=loading_existing,
-    )
+        show_validation_success(
+            mode=options.mode,
+            depth=final_depth,
+            degree=final_degree,
+            num_samples=final_num_samples,
+            batch_size=final_batch_size,
+            loading_existing=loading_existing,
+        )
 
     try:
         return GenerationPreparation(
@@ -372,29 +424,145 @@ def _run_generation(
     preparation: GenerationPreparation,
     topic_model: TopicModel,
     options: GenerateOptions,
+    checkpoint_dir: str,
 ) -> None:
     """Create the dataset using the prepared configuration and topic model."""
+    tui = get_tui()
 
-    generation_params = preparation.config.get_generation_params(**preparation.generation_overrides)
-    engine = DataSetGenerator(**generation_params)
+    # Apply CLI checkpoint overrides
+    checkpoint_overrides = {}
+    if options.checkpoint_interval is not None:
+        checkpoint_overrides["checkpoint_interval"] = options.checkpoint_interval
+    if options.checkpoint_path is not None:
+        checkpoint_overrides["checkpoint_path"] = options.checkpoint_path
+    if options.retry_failed:
+        checkpoint_overrides["checkpoint_retry_failed"] = options.retry_failed
+
+    generation_params = preparation.config.get_generation_params(
+        **preparation.generation_overrides, **checkpoint_overrides
+    )
 
-    dataset = create_dataset(
-        engine=engine,
-        topic_model=topic_model,
-        config=preparation.config,
-        num_samples=preparation.num_samples,
-        batch_size=preparation.batch_size,
-        include_system_message=options.include_system_message,
-        provider=options.provider,
-        model=options.model,
-        generation_overrides=preparation.generation_overrides,
-        debug=options.debug,
+    # Use provided checkpoint_dir if not explicitly set via CLI
+    if generation_params.get("checkpoint_path") is None:
+        generation_params["checkpoint_path"] = checkpoint_dir
+
+    # Resolve and pass topics_file for checkpoint metadata
+    # Prioritize: loaded file > save path > config > default
+    # Store absolute path for reliable resume from any working directory
+    topics_mode = preparation.config.topics.mode
+    default_topics_path = "topic_graph.json" if topics_mode == "graph" else "topic_tree.jsonl"
+    resolved_topics_path = (
+        options.topics_load
+        or options.topics_save_as
+        or preparation.config.topics.save_as
+        or default_topics_path
     )
+    generation_params["topics_file"] = str(Path(resolved_topics_path).resolve())
+
+    engine = DataSetGenerator(**generation_params)
+
+    # Check for existing checkpoint when not resuming
+    if not options.resume and engine.has_checkpoint():
+        tui.warning("Existing checkpoint found for this configuration")
+        tui.console.print()
+        tui.console.print("  [cyan]1)[/cyan] Resume from checkpoint")
+        tui.console.print("  [cyan]2)[/cyan] Clear checkpoint and start fresh")
+        tui.console.print("  [cyan]3)[/cyan] Abort")
+        tui.console.print()
+
+        choice = click.prompt(
+            "Choose an option",
+            type=click.Choice(["1", "2", "3"]),
+            default="1",
+        )
+
+        if choice == "1":
+            # User wants to resume
+            options.resume = True
+        elif choice == "2":
+            # Clear and start fresh
+            engine.clear_checkpoint()
+            tui.info("Checkpoint cleared, starting fresh generation")
+        else:
+            # Abort
+            tui.info("Aborted")
+            sys.exit(0)
+
+    # Handle resume from checkpoint
+    if options.resume:
+        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)
+            retry_msg = " (retrying failed samples)" if options.retry_failed else ""
+
+            # Update TUI status panel with checkpoint progress
+            get_dataset_tui().set_checkpoint_resume_status(samples_done, failures_done)
+
+            # Log resume info including failures
+            if failures_done > 0:
+                tui.info(
+                    f"Resuming from checkpoint: {samples_done} samples, "
+                    f"{failures_done} failed, {ids_processed} IDs processed{retry_msg}"
+                )
+            else:
+                tui.info(
+                    f"Resuming from checkpoint: {samples_done} samples, "
+                    f"{ids_processed} IDs processed{retry_msg}"
+                )
+        else:
+            tui.info("No checkpoint found, starting fresh generation")
+
+    # Set up graceful Ctrl+C handling for checkpoint-based stop
+    interrupt_count = 0
+
+    def handle_sigint(_signum, _frame):
+        nonlocal interrupt_count
+        interrupt_count += 1
+
+        if interrupt_count == 1:
+            engine.stop_requested = True
+            tui.warning("Stopping after current checkpoint... (Ctrl+C again to force quit)")
+            dataset_tui = get_dataset_tui()
+            dataset_tui.log_event("⚠ Graceful stop requested")
+            dataset_tui.status_stop_requested()
+        else:
+            tui.error("Force quit!")
+            sys.exit(1)
+
+    original_handler = signal.signal(signal.SIGINT, handle_sigint)
+    try:
+        dataset = create_dataset(
+            engine=engine,
+            topic_model=topic_model,
+            config=preparation.config,
+            num_samples=preparation.num_samples,
+            batch_size=preparation.batch_size,
+            include_system_message=options.include_system_message,
+            provider=options.provider,
+            model=options.model,
+            generation_overrides=preparation.generation_overrides,
+            debug=options.debug,
+        )
+    finally:
+        signal.signal(signal.SIGINT, original_handler)
+
+    # If gracefully stopped, don't save partial dataset or clean up checkpoints
+    if engine.stop_requested:
+        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
+    if generation_params.get("checkpoint_interval") is not None:
+        try:
+            engine.clear_checkpoint()
+            tui.info("Checkpoint files cleaned up after successful generation")
+        except OSError as e:
+            tui.warning(f"Failed to clean up checkpoint files: {e}")
+
     trace(
         "dataset_generated",
         {"samples": len(dataset)},
@@ -429,7 +597,11 @@ def _run_generation(
 @click.option("--temperature", type=float, help="Temperature setting")
 @click.option("--degree", type=int, help="Degree (branching factor)")
 @click.option("--depth", type=int, help="Depth setting")
-@click.option("--num-samples", type=int, help="Number of samples to generate")
+@click.option(
+    "--num-samples",
+    type=str,
+    help="Number of samples: integer, 'auto' (all topics), or percentage like '50%'",
+)
 @click.option("--batch-size", type=int, help="Batch size")
 @click.option("--base-url", help="Base URL for LLM provider API endpoint")
 @click.option(
@@ -473,29 +645,34 @@ def _run_generation(
 @click.option(
     "--agent-mode",
     type=click.Choice(["single_turn", "multi_turn"]),
-    help="Agent mode: single_turn (one-shot tool use), multi_turn (extended conversations). Requires tools.",
+    help="[Deprecated] Agent mode is now implicit when tools are configured. 'multi_turn' is no longer supported.",
 )
 @click.option(
-    "--min-turns",
-    type=int,
-    help="Minimum conversation turns for multi_turn agent mode",
+    "--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.",
 )
 @click.option(
-    "--max-turns",
+    "--checkpoint-interval",
     type=int,
-    help="Maximum conversation turns for multi_turn agent mode",
+    help="Save checkpoint every N samples. Enables resumable generation.",
 )
 @click.option(
-    "--min-tool-calls",
-    type=int,
-    help="Minimum tool calls before allowing conversation conclusion",
+    "--checkpoint-path",
+    type=click.Path(),
+    help="Override checkpoint directory (default: XDG data dir)",
 )
 @click.option(
-    "--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.",
+    "--resume",
+    is_flag=True,
+    help="Resume from existing checkpoint if available",
+)
+@click.option(
+    "--retry-failed",
+    is_flag=True,
+    help="When resuming, retry previously failed samples",
 )
 def generate(  # noqa: PLR0913
     config_file: str | None,
@@ -511,7 +688,7 @@ def generate(  # noqa: PLR0913
     temperature: float | None = None,
     degree: int | None = None,
     depth: int | None = None,
-    num_samples: int | None = None,
+    num_samples: str | None = None,
     batch_size: int | None = None,
     base_url: str | None = None,
     include_system_message: bool | None = None,
@@ -521,13 +698,28 @@ def generate(  # noqa: PLR0913
     conversation_type: Literal["basic", "cot"] | None = None,
     reasoning_style: Literal["freetext", "agent"] | None = None,
     agent_mode: Literal["single_turn", "multi_turn"] | None = None,
-    min_turns: int | None = None,
-    max_turns: int | None = None,
-    min_tool_calls: int | None = None,
     cloud_upload: Literal["all", "dataset", "graph", "none"] | None = None,
     tui: Literal["rich", "simple"] = "rich",
+    checkpoint_interval: int | None = None,
+    checkpoint_path: str | None = None,
+    resume: bool = False,
+    retry_failed: bool = False,
 ) -> None:
     """Generate training data from a YAML configuration file or CLI parameters."""
+    # Handle deprecated --agent-mode flag
+    if agent_mode == "multi_turn":
+        click.echo(
+            "Error: --agent-mode multi_turn is deprecated and no longer supported. "
+            "Omit --agent-mode and the default supported agent mode will be used.",
+            err=True,
+        )
+        sys.exit(1)
+    elif agent_mode == "single_turn":
+        click.echo(
+            "Note: --agent-mode single_turn is deprecated. "
+            "Single-turn agent mode is now implicit when tools are configured."
+        )
+
     set_trace_debug(debug)
     trace(
         "cli_generate",
@@ -540,6 +732,9 @@ def generate(  # noqa: PLR0913
     )
 
     try:
+        # Parse num_samples from CLI string (could be int, "auto", or "50%")
+        parsed_num_samples = parse_num_samples(num_samples)
+
         options = GenerateOptions(
             config_file=config_file,
             output_system_prompt=output_system_prompt,
@@ -554,7 +749,7 @@ def generate(  # noqa: PLR0913
             temperature=temperature,
             degree=degree,
             depth=depth,
-            num_samples=num_samples,
+            num_samples=parsed_num_samples,
             batch_size=batch_size,
             base_url=base_url,
             include_system_message=include_system_message,
@@ -564,13 +759,14 @@ def generate(  # noqa: PLR0913
             conversation_type=conversation_type,
             reasoning_style=reasoning_style,
             agent_mode=agent_mode,
-            min_turns=min_turns,
-            max_turns=max_turns,
-            min_tool_calls=min_tool_calls,
             cloud_upload=cloud_upload,
             tui=tui,
+            checkpoint_interval=checkpoint_interval,
+            checkpoint_path=checkpoint_path,
+            resume=resume,
+            retry_failed=retry_failed,
         )
-    except PydanticValidationError as error:
+    except (PydanticValidationError, ValueError) as error:
         handle_error(click.get_current_context(), ConfigurationError(str(error)))
         return
 
@@ -583,7 +779,27 @@ def generate(  # noqa: PLR0913
         tui.info("Initializing DeepFabric...")  # type: ignore
         print()
 
-        preparation = _load_and_prepare_generation_context(options)
+        preparation = _load_and_prepare_generation_context(options, skip_path_validation=topic_only)
+
+        # 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
+        checkpoint_dir = options.checkpoint_path or get_checkpoint_dir(path_source)
+
+        # Auto-infer topics-load when resuming from checkpoint
+        if options.resume and not options.topics_load:
+            output_path = options.output_save_as or preparation.config.output.save_as
+
+            inferred_topics_path = _get_checkpoint_topics_path(checkpoint_dir, output_path)
+            if inferred_topics_path:
+                if Path(inferred_topics_path).exists():
+                    tui.info(f"Resume: auto-loading topics from {inferred_topics_path}")
+                    options.topics_load = inferred_topics_path
+                else:
+                    tui.warning(
+                        f"Checkpoint references topics at {inferred_topics_path} but file not found. "
+                        "Topic graph will be regenerated."
+                    )
 
         topic_model = _initialize_topic_model(
             preparation=preparation,
@@ -603,6 +819,7 @@ def generate(  # noqa: PLR0913
             preparation=preparation,
             topic_model=topic_model,
             options=options,
+            checkpoint_dir=checkpoint_dir,
         )
 
     except ConfigurationError as e:
@@ -1024,7 +1241,12 @@ def visualize(graph_file: str, output: str) -> None:
 
 @cli.command()
 @click.argument("config_file", type=click.Path(exists=True))
-def validate(config_file: str) -> None:  # noqa: PLR0912
+@click.option(
+    "--check-api/--no-check-api",
+    default=True,
+    help="Validate API keys by making test calls (default: enabled)",
+)
+def validate(config_file: str, check_api: bool) -> None:  # noqa: PLR0912
     """Validate a DeepFabric configuration file."""
     try:
         # Try to load the configuration
@@ -1053,24 +1275,43 @@ def validate(config_file: str) -> None:  # noqa: PLR0912
             for error in errors:
                 tui.console.print(f"  - {error}", style="red")
             sys.exit(1)
-        else:
-            tui.success("Configuration is valid")
 
         if warnings:
-            tui.console.print("\nWarnings:", style="yellow bold")
+            tui.console.print("Warnings:", style="yellow bold")
             for warning in warnings:
                 tui.warning(warning)
+            tui.console.print()
 
         # Print configuration summary
-        tui.console.print("\nConfiguration Summary:", style="cyan bold")
-        tui.info(
-            f"Topics: mode={config.topics.mode}, depth={config.topics.depth}, degree={config.topics.degree}"
-        )
+        tui.console.print("Configuration Summary:", style="cyan bold")
 
+        # Topics summary with estimated paths
+        depth = config.topics.depth
+        degree = config.topics.degree
+        # Estimated paths = degree^depth (each level branches by degree)
+        estimated_paths = degree**depth
         tui.info(
-            f"Output: num_samples={config.output.num_samples}, batch_size={config.output.batch_size}"
+            f"Topics: mode={config.topics.mode}, depth={depth}, degree={degree}, "
+            f"estimated_paths={estimated_paths} ({degree}^{depth})"
         )
 
+        # Output summary with step size and checkpoint 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
+        if config.output.checkpoint:
+            checkpoint = config.output.checkpoint
+            output_info += f", checkpoint_interval={checkpoint.interval}"
+        tui.info(output_info)
+
         if config.huggingface:
             hf_config = config.get_huggingface_config()
             tui.info(f"Hugging Face: repo={hf_config.get('repository', 'not set')}")
@@ -1079,6 +1320,58 @@ def validate(config_file: str) -> None:  # noqa: PLR0912
             kaggle_config = config.get_kaggle_config()
             tui.info(f"Kaggle: handle={kaggle_config.get('handle', 'not set')}")
 
+        # Check path writability
+        tui.console.print("\nPath Writability:", style="cyan bold")
+        path_errors = []
+
+        # Check topics.save_as if configured
+        if config.topics.save_as:
+            is_writable, error_msg = check_path_writable(config.topics.save_as, "topics.save_as")
+            if is_writable:
+                tui.success(f"topics.save_as: {config.topics.save_as}")
+            else:
+                path_errors.append(error_msg)
+                tui.error(f"topics.save_as: {error_msg}")
+
+        # Check output.save_as
+        if config.output.save_as:
+            is_writable, error_msg = check_path_writable(config.output.save_as, "output.save_as")
+            if is_writable:
+                tui.success(f"output.save_as: {config.output.save_as}")
+            else:
+                path_errors.append(error_msg)
+                tui.error(f"output.save_as: {error_msg}")
+
+        # Check checkpoint directory if enabled
+        if config.output.checkpoint:
+            checkpoint_path = config.output.checkpoint.path or get_checkpoint_dir(config_file)
+            is_writable, error_msg = check_dir_writable(checkpoint_path, "checkpoint directory")
+            if is_writable:
+                tui.success(f"checkpoint directory: {checkpoint_path}")
+            else:
+                path_errors.append(error_msg)
+                tui.error(f"checkpoint directory: {error_msg}")
+
+        if path_errors:
+            tui.console.print()
+            tui.error("Some paths are not writable. Fix permissions or choose different paths.")
+            sys.exit(1)
+
+        # Validate API keys if requested
+        if check_api:
+            tui.console.print("\nAPI Keys:", style="cyan bold")
+            try:
+                _validate_api_keys(config)
+            except ConfigurationError as e:
+                tui.error(str(e))
+                sys.exit(1)
+        else:
+            tui.console.print("\nSkipping API key validation (use --check-api to enable)")
+
+        # Final success message
+        tui.console.print()
+        tui.success("Configuration is valid")
+
     except FileNotFoundError:
         handle_error(
             click.get_current_context(),
@@ -1563,5 +1856,143 @@ def import_tools(
         sys.exit(1)
 
 
+@cli.command("checkpoint-status")
+@click.argument("config_file", type=click.Path(exists=True))
+def checkpoint_status(config_file: str) -> None:
+    """Show checkpoint status for a generation config.
+
+    Displays the current state of any checkpoint files associated with
+    the given configuration file, including progress, failures, and
+    resume instructions.
+    """
+    tui = get_tui()
+
+    try:
+        config = DeepFabricConfig.from_yaml(config_file)
+    except Exception as e:
+        tui.error(f"Failed to load config: {e}")
+        sys.exit(1)
+
+    # Get checkpoint configuration
+    checkpoint_config = config.get_checkpoint_config()
+    output_config = config.get_output_config()
+    checkpoint_dir = checkpoint_config.get("path") or get_checkpoint_dir(config_file)
+    save_as = output_config.get("save_as")
+
+    if not save_as:
+        tui.error("Config does not specify output.save_as - cannot determine checkpoint paths")
+        sys.exit(1)
+
+    # Derive checkpoint paths
+    output_stem = Path(save_as).stem
+    checkpoint_dir_path = Path(checkpoint_dir)
+    metadata_path = checkpoint_dir_path / f"{output_stem}{CHECKPOINT_METADATA_SUFFIX}"
+    samples_path = checkpoint_dir_path / f"{output_stem}{CHECKPOINT_SAMPLES_SUFFIX}"
+    failures_path = checkpoint_dir_path / f"{output_stem}{CHECKPOINT_FAILURES_SUFFIX}"
+
+    # 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.info(f"  deepfabric generate {config_file} --checkpoint-interval 10")
+        return
+
+    # Load and display checkpoint metadata
+    try:
+        with open(metadata_path) as f:
+            metadata = json.load(f)
+    except Exception as e:
+        tui.error(f"Failed to read checkpoint metadata: {e}")
+        sys.exit(1)
+
+    # Count samples in checkpoint file
+    checkpoint_sample_count = 0
+    if samples_path.exists():
+        with open(samples_path) as f:
+            checkpoint_sample_count = sum(1 for line in f if line.strip())
+
+    # Count failures
+    checkpoint_failures = 0
+    failure_details = []
+    if failures_path.exists():
+        with open(failures_path) as f:
+            for raw_line in f:
+                stripped = raw_line.strip()
+                if stripped:
+                    checkpoint_failures += 1
+                    try:
+                        failure = json.loads(stripped)
+                        failure_details.append(failure)
+                    except json.JSONDecodeError:
+                        pass
+
+    # Get target samples from config
+    # num_samples is the total target, not per-batch. It can be int, "auto", or percentage like "50%"
+    target_samples = output_config.get("num_samples", 0)
+    # "auto" or percentage strings can't be resolved without topic model
+    total_target = 0 if isinstance(target_samples, str) else (target_samples or 0)
+
+    # Display status
+    tui.console.print()
+    tui.console.print(f"[bold]Checkpoint Status:[/bold] {metadata_path}")
+    tui.console.print()
+
+    # Progress
+    progress_pct = (checkpoint_sample_count / total_target * 100) if total_target > 0 else 0
+    tui.console.print(
+        f"  [cyan]Progress:[/cyan]     {checkpoint_sample_count}/{total_target} samples ({progress_pct:.1f}%)"
+    )
+    tui.console.print(f"  [cyan]Failed:[/cyan]       {checkpoint_failures} samples")
+
+    # Paths processed
+    processed_ids = metadata.get("processed_ids", [])
+    tui.console.print(f"  [cyan]Paths done:[/cyan]   {len(processed_ids)}")
+
+    # Config info
+    tui.console.print()
+    tui.console.print(f"  [dim]Provider:[/dim]      {metadata.get('provider', 'unknown')}")
+    tui.console.print(f"  [dim]Model:[/dim]         {metadata.get('model_name', 'unknown')}")
+    tui.console.print(f"  [dim]Conv type:[/dim]     {metadata.get('conversation_type', 'unknown')}")
+    if metadata.get("reasoning_style"):
+        tui.console.print(f"  [dim]Reasoning:[/dim]     {metadata.get('reasoning_style')}")
+    tui.console.print(f"  [dim]Last saved:[/dim]    {metadata.get('created_at', 'unknown')}")
+
+    # Show topics file path if available
+    topics_path = metadata.get("topics_file") or metadata.get("topics_save_as")
+    if topics_path:
+        topics_exists = Path(topics_path).exists()
+        status = "[green]exists[/green]" if topics_exists else "[red]missing[/red]"
+        tui.console.print(f"  [dim]Topics file:[/dim]  {topics_path} ({status})")
+
+    # Show failed topics if any
+    max_failures_to_show = 5
+    max_error_length = 60
+    if failure_details:
+        tui.console.print()
+        tui.console.print("[yellow]Failed Topics:[/yellow]")
+        for failure in failure_details[:max_failures_to_show]:
+            error_msg = failure.get("error", "Unknown error")
+            # Truncate long error messages
+            if len(error_msg) > max_error_length:
+                error_msg = error_msg[: max_error_length - 3] + "..."
+            tui.console.print(f"  - {error_msg}")
+        if len(failure_details) > max_failures_to_show:
+            remaining = len(failure_details) - max_failures_to_show
+            tui.console.print(f"  ... and {remaining} more failures")
+
+    # Resume instructions
+    tui.console.print()
+    checkpoint_interval_arg = metadata.get("checkpoint_interval", 10)
+    tui.console.print("[green]Resume with:[/green]")
+    tui.console.print(
+        f"  deepfabric generate {config_file} --checkpoint-interval {checkpoint_interval_arg} --resume"
+    )
+    if metadata.get("total_failures", 0) > 0:
+        tui.console.print("[green]Retry failed:[/green]")
+        tui.console.print(
+            f"  deepfabric generate {config_file} --checkpoint-interval {checkpoint_interval_arg} --resume --retry-failed"
+        )
+
+
 if __name__ == "__main__":
     cli()