ds-agent-cli 0.1.0

package/src/cli.py

@@ -0,0 +1,2886 @@
+"""
+Command Line Interface for Data Science Copilot
+"""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
+from rich.live import Live
+from rich import print as rprint
+from pathlib import Path
+import json
+import sys
+import os
+import io
+import contextlib
+import importlib.util
+from typing import Optional
+
+# Add src to path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__)))
+
+app = typer.Typer(
+    name="ds-agent",
+    help="AI-powered data science CLI for profiling, modeling, forecasting, and chat workflows.",
+    add_completion=False,
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    epilog=(
+        "Quick start: run [bold]ds-agent quickstart[/bold]\n"
+        "Examples: [bold]ds-agent analyze data.csv --target price[/bold] | "
+        "[bold]ds-agent chat data.csv[/bold]"
+    )
+)
+
+sessions_app = typer.Typer(help="Manage saved chat/analysis sessions")
+app.add_typer(sessions_app, name="sessions")
+
+console = Console()
+
+
+def _print_cli_home():
+    """Render a first-run friendly home screen for users running the CLI without arguments."""
+    banner = r"""[bold cyan]
+  ____  ____         _    ____ _____ _   _ _____
+ |  _ \/ ___|       / \  / ___| ____| \ | |_   _|
+ | | | \___ \      / _ \| |  _|  _| |  \| | | |
+ | |_| |___) |    / ___ \ |_| | |___| |\  | | |
+ |____/|____/    /_/   \_\____|_____|_| \_| |_|
+[/bold cyan]"""
+    console.print(banner)
+    console.print("[dim]The open data science agent CLI[/dim]\n")
+
+    table = Table(show_header=False, box=None, pad_edge=False)
+    table.add_column("Command", style="bold white", width=52, no_wrap=True)
+    table.add_column("What it does", style="white")
+
+    table.add_row("ds-agent quickstart", "Show examples for all major workflows")
+    table.add_row("ds-agent analyze <file>", "Run end-to-end automated analysis")
+    table.add_row("ds-agent chat [file]", "Start interactive session with memory")
+    table.add_row("ds-agent report <file>", "Generate full HTML profiling report")
+    table.add_row("ds-agent train <file> --target <col>", "Train baseline ML models")
+    table.add_row("ds-agent tune <file> --target <col>", "Hyperparameter optimization")
+    table.add_row("ds-agent plot <file>", "Generate charts and visualizations")
+    table.add_row("ds-agent forecast <file> --time <col> --target <col>", "Time-series forecasting")
+    table.add_row("ds-agent sessions list", "List and manage saved sessions")
+    table.add_row("ds-agent --help", "Full command reference")
+
+    console.print(table)
+    console.print("\n[dim]Tip: run [bold]ds-agent quickstart[/bold] for copy-paste commands.[/dim]")
+
+
+@app.callback(invoke_without_command=True)
+def root_callback(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-v", help="Show CLI version and exit.")
+):
+    """Root CLI callback for startup UX and global flags."""
+    if version:
+        try:
+            from ds_agent import __version__
+        except Exception:
+            __version__ = "0.1.0"
+        console.print(f"ds-agent v{__version__}")
+        raise typer.Exit(0)
+
+    if ctx.invoked_subcommand is None:
+        _print_cli_home()
+        raise typer.Exit(0)
+
+
+@app.command()
+def quickstart():
+    """Show beginner-friendly command guide with copy-paste examples."""
+    guide = Table(title="⚡ Quickstart Guide")
+    guide.add_column("Workflow", style="cyan", width=24, no_wrap=True)
+    guide.add_column("Command", style="white", no_wrap=True)
+
+    guide.add_row("Analyze", "ds-agent analyze data.csv --target price --task \"predict price\"")
+    guide.add_row("Chat", "ds-agent chat data.csv")
+    guide.add_row("Profile Report", "ds-agent report data.csv --engine ydata --output ./outputs/reports")
+    guide.add_row("Model Training", "ds-agent train data.csv --target label --task-type classification")
+    guide.add_row("Hyperparameter Tuning", "ds-agent tune data.csv --target label --model xgboost --trials 50")
+    guide.add_row("Visualizations", "ds-agent plot data.csv --type heatmap")
+    guide.add_row("Compare Datasets", "ds-agent compare train.csv test.csv --label1 train --label2 test")
+    guide.add_row("Forecast", "ds-agent forecast sales.csv --time date --target revenue --horizon 30")
+    guide.add_row("NLP", "ds-agent nlp reviews.csv --text review --task sentiment")
+    guide.add_row("Session Management", "ds-agent sessions list | ds-agent sessions resume <session_id>")
+
+    console.print()
+    console.print(guide)
+    console.print("\n[dim]Use [bold]ds-agent <command> --help[/bold] for detailed options and examples.[/dim]")
+
+
+def _load_module_from_src(module_name: str, relative_path: str):
+    """Load a module directly from src to avoid triggering package-wide __init__ side effects."""
+    module_path = Path(__file__).resolve().parent / relative_path
+    spec = importlib.util.spec_from_file_location(module_name, str(module_path))
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Unable to load module at {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+@app.command()
+def analyze(
+    file_path: str = typer.Argument(..., help="Path to dataset file (CSV or Parquet)"),
+    task: str = typer.Option(
+        "Complete data science workflow: profile, clean, engineer features, and train models",
+        "--task", "-t",
+        help="Description of the analysis task"
+    ),
+    target: str = typer.Option(None, "--target", "-y", help="Target column name for prediction"),
+    output: str = typer.Option("./outputs", "--output", "-o", help="Output directory"),
+    no_cache: bool = typer.Option(False, "--no-cache", help="Disable caching"),
+    reasoning: str = typer.Option("medium", "--reasoning", "-r", help="Reasoning effort (low/medium/high)")
+):
+    """
+    Analyze a dataset and perform complete data science workflow.
+    
+    Example:
+        python cli.py analyze data.csv --target Survived --task "Predict survival"
+    """
+    console.print(Panel.fit(
+        "🤖 Data Science Copilot - AI-Powered Analysis",
+        style="bold blue"
+    ))
+    
+    # Validate file exists
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+    
+    # Initialize copilot
+    try:
+        from ds_agent.orchestrator import DataScienceCopilot
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task_init = progress.add_task("Initializing Data Science Copilot...", total=None)
+            copilot = DataScienceCopilot(reasoning_effort=reasoning)
+            progress.update(task_init, completed=True)
+    
+    except Exception as e:
+        console.print(f"[red]✗ Error initializing copilot: {e}[/red]")
+        console.print("[yellow]Make sure GROQ_API_KEY is set in .env file[/yellow]")
+        raise typer.Exit(1)
+    
+    # Run analysis
+    console.print(f"\n📊 [bold]Dataset:[/bold] {file_path}")
+    console.print(f"🎯 [bold]Task:[/bold] {task}")
+    if target:
+        console.print(f"🎲 [bold]Target:[/bold] {target}")
+    console.print()
+    
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task_analyze = progress.add_task("Running analysis workflow...", total=None)
+            
+            result = copilot.analyze(
+                file_path=file_path,
+                task_description=task,
+                target_col=target,
+                use_cache=not no_cache
+            )
+            
+            progress.update(task_analyze, completed=True)
+    
+    except Exception as e:
+        console.print(f"\n[red]✗ Analysis failed: {e}[/red]")
+        raise typer.Exit(1)
+    
+    # Display results
+    if result["status"] == "success":
+        console.print("\n[green]✓ Analysis Complete![/green]\n")
+        
+        # Summary
+        console.print(Panel(
+            result["summary"],
+            title="📋 Analysis Summary",
+            border_style="green"
+        ))
+        
+        # Workflow history
+        console.print("\n[bold]🔧 Tools Executed:[/bold]")
+        for step in result["workflow_history"]:
+            tool_name = step["tool"]
+            success = step["result"].get("success", False)
+            icon = "✓" if success else "✗"
+            color = "green" if success else "red"
+            console.print(f"  [{color}]{icon}[/{color}] {tool_name}")
+        
+        # Stats
+        stats_table = Table(title="📊 Execution Statistics", show_header=False)
+        stats_table.add_column("Metric", style="cyan")
+        stats_table.add_column("Value", style="white")
+        
+        stats_table.add_row("Iterations", str(result["iterations"]))
+        stats_table.add_row("API Calls", str(result["api_calls"]))
+        stats_table.add_row("Execution Time", f"{result['execution_time']}s")
+        
+        console.print()
+        console.print(stats_table)
+        
+        # Save full report
+        report_path = Path(output) / "reports" / f"analysis_{Path(file_path).stem}.json"
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(report_path, "w") as f:
+            json.dump(result, f, indent=2)
+        
+        console.print(f"\n💾 Full report saved to: [cyan]{report_path}[/cyan]")
+    
+    elif result["status"] == "error":
+        console.print(f"\n[red]✗ Error: {result['error']}[/red]")
+        raise typer.Exit(1)
+    
+    else:
+        console.print(f"\n[yellow]⚠ Analysis incomplete: {result.get('message')}[/yellow]")
+
+
+@app.command()
+def profile(
+    file_path: str = typer.Argument(..., help="Path to dataset file")
+):
+    """
+    Quick profile of a dataset (basic statistics and quality checks).
+    
+    Example:
+        python cli.py profile data.csv
+    """
+    from ds_agent.tools.data_profiling import profile_dataset, detect_data_quality_issues
+    
+    console.print(f"\n📊 [bold]Profiling:[/bold] {file_path}\n")
+    
+    # Profile
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}")) as progress:
+        task1 = progress.add_task("Analyzing dataset...", total=None)
+        profile = profile_dataset(file_path)
+        progress.update(task1, completed=True)
+    
+    # Display basic info
+    info_table = Table(title="Dataset Information", show_header=False)
+    info_table.add_column("Property", style="cyan")
+    info_table.add_column("Value", style="white")
+    
+    info_table.add_row("Rows", str(profile["shape"]["rows"]))
+    info_table.add_row("Columns", str(profile["shape"]["columns"]))
+    info_table.add_row("Memory", f"{profile['memory_usage']['total_mb']} MB")
+    info_table.add_row("Null %", f"{profile['overall_stats']['null_percentage']}%")
+    info_table.add_row("Duplicates", str(profile['overall_stats']['duplicate_rows']))
+    
+    console.print()
+    console.print(info_table)
+    
+    # Column types
+    console.print("\n[bold]Column Types:[/bold]")
+    console.print(f"  Numeric: {len(profile['column_types']['numeric'])}")
+    console.print(f"  Categorical: {len(profile['column_types']['categorical'])}")
+    console.print(f"  Datetime: {len(profile['column_types']['datetime'])}")
+    
+    # Detect issues
+    console.print("\n[bold]Quality Check:[/bold]")
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}")) as progress:
+        task2 = progress.add_task("Detecting quality issues...", total=None)
+        issues = detect_data_quality_issues(file_path)
+        progress.update(task2, completed=True)
+    
+    console.print(f"  🔴 Critical: {issues['summary']['critical_count']}")
+    console.print(f"  🟡 Warnings: {issues['summary']['warning_count']}")
+    console.print(f"  🔵 Info: {issues['summary']['info_count']}")
+
+
+@app.command()
+def eda(
+    file_path: str = typer.Argument(..., help="Path to dataset file (CSV or Parquet)"),
+    target: str = typer.Option(None, "--target", "-y", help="Target column name for supervised EDA"),
+    output: str = typer.Option("./outputs/eda/", "--output", "-o", help="Output directory for EDA artifacts"),
+    full: bool = typer.Option(False, "--full", help="Run deeper EDA analysis")
+):
+    """
+    Run exploratory data analysis with quality checks and optional root-cause insights.
+
+    Example:
+        ds-agent eda sales.csv
+        ds-agent eda sales.csv --target revenue --full
+    """
+    from ds_agent.tools.advanced_analysis import perform_eda_analysis
+    from ds_agent.tools.data_profiling import detect_data_quality_issues
+    from ds_agent.tools.advanced_insights import analyze_root_cause
+
+    console.print(Panel.fit(
+        "📈 Exploratory Data Analysis",
+        style="bold blue"
+    ))
+
+    # Validate file exists
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    output_dir = Path(output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_html = f"{str(output_dir).rstrip('/')}/eda.html"
+
+    console.print(f"\n📊 [bold]Dataset:[/bold] {file_path}")
+    if target:
+        console.print(f"🎯 [bold]Target:[/bold] {target}")
+    console.print(f"🧪 [bold]Depth:[/bold] {'Full' if full else 'Standard'}")
+    console.print()
+
+    try:
+        # Step 1: Perform EDA analysis
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task_eda = progress.add_task("Running comprehensive EDA...", total=None)
+            eda_result = perform_eda_analysis(
+                file_path,
+                target_col=target,
+                output_html=output_html
+            )
+            progress.update(task_eda, completed=True)
+
+        # Step 2: Detect quality issues
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task_quality = progress.add_task("Detecting data quality issues...", total=None)
+            quality_result = detect_data_quality_issues(file_path)
+            progress.update(task_quality, completed=True)
+
+        # Step 3: Root cause analysis (only when target is provided)
+        root_cause_result = None
+        if target:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console
+            ) as progress:
+                task_root = progress.add_task("Analyzing root-cause factors...", total=None)
+                if full:
+                    root_cause_result = analyze_root_cause(
+                        file_path,
+                        target_col=target,
+                        threshold_drop=0.10
+                    )
+                else:
+                    root_cause_result = analyze_root_cause(file_path, target_col=target)
+                progress.update(task_root, completed=True)
+
+    except Exception as e:
+        console.print(f"\n[red]✗ EDA failed: {e}[/red]")
+        raise typer.Exit(1)
+
+    # Prepare summary fields
+    dataset_shape = eda_result.get("dataset_shape", {})
+    column_types = eda_result.get("column_types", {})
+
+    ranked_issues = (
+        quality_result.get("critical", [])
+        + quality_result.get("warning", [])
+        + quality_result.get("info", [])
+    )
+    top_issues = ranked_issues[:3]
+
+    top_issue_lines = []
+    for issue in top_issues:
+        msg = issue.get("message", "Issue detected")
+        top_issue_lines.append(f"- {msg}")
+    if not top_issue_lines:
+        top_issue_lines.append("- No major quality issues detected")
+
+    top_corr_lines = []
+    if target and isinstance(root_cause_result, dict):
+        corr_map = root_cause_result.get("correlations", {})
+        if isinstance(corr_map, dict) and corr_map:
+            top_corrs = sorted(corr_map.items(), key=lambda x: abs(x[1]), reverse=True)[:3]
+            for feature, corr in top_corrs:
+                top_corr_lines.append(f"- {feature}: {corr:.3f}")
+    if target and not top_corr_lines:
+        top_corr_lines.append("- No strong target correlations detected")
+
+    # Step 4: Rich summary table
+    summary_table = Table(title="📊 EDA Summary", show_header=False)
+    summary_table.add_column("Metric", style="cyan", width=28)
+    summary_table.add_column("Value", style="white")
+
+    summary_table.add_row("Rows", str(dataset_shape.get("rows", "-")))
+    summary_table.add_row("Columns", str(dataset_shape.get("columns", "-")))
+    summary_table.add_row("Numeric Columns", str(column_types.get("numeric", "-")))
+    summary_table.add_row("Categorical Columns", str(column_types.get("categorical", "-")))
+    summary_table.add_row("Top 3 Quality Issues", "\n".join(top_issue_lines))
+    if target:
+        summary_table.add_row("Top 3 Correlations with Target", "\n".join(top_corr_lines))
+
+    console.print()
+    console.print(summary_table)
+
+    # Step 5: Report path
+    console.print(f"\n💾 HTML report saved to: [cyan]{output_html}[/cyan]")
+
+    quality_summary = quality_result.get("summary", {})
+    final_lines = [
+        f"Rows: {dataset_shape.get('rows', '-')}",
+        f"Columns: {dataset_shape.get('columns', '-')}",
+        f"Issues found: {quality_summary.get('total_issues', 0)}",
+        f"Mode: {'Full' if full else 'Standard'}"
+    ]
+    if target:
+        final_lines.append(f"Target analyzed: {target}")
+
+    console.print(Panel(
+        "\n".join(final_lines),
+        title="✅ EDA Complete",
+        border_style="green"
+    ))
+
+
+@app.command()
+def report(
+    file_path: str = typer.Argument(..., help="Path to dataset file (CSV or Parquet)"),
+    engine: str = typer.Option("ydata", "--engine", help="Report engine: ydata or sweetviz"),
+    target: str = typer.Option(None, "--target", "-y", help="Optional target column for supervised analysis"),
+    compare: str = typer.Option(None, "--compare", help="Optional second dataset path for Sweetviz comparison"),
+    output: str = typer.Option("./outputs/reports/", "--output", "-o", help="Output directory for HTML reports"),
+    minimal: bool = typer.Option(False, "--minimal", help="Use minimal mode for large files")
+):
+    """
+    Generate a full HTML profiling report using ydata-profiling or Sweetviz.
+
+    Example:
+        ds-agent report sales.csv
+        ds-agent report sales.csv --engine sweetviz --target revenue
+        ds-agent report sales.csv --compare test.csv --engine sweetviz
+    """
+    eda_reports_module = _load_module_from_src("ds_agent_cli_eda_reports", "tools/eda_reports.py")
+    generate_ydata_profiling_report = eda_reports_module.generate_ydata_profiling_report
+    generate_sweetviz_report = eda_reports_module.generate_sweetviz_report
+    import webbrowser
+
+    console.print(Panel.fit(
+        "📄 HTML Profiling Report",
+        style="bold blue"
+    ))
+
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    engine_normalized = engine.strip().lower()
+    if engine_normalized not in {"ydata", "sweetviz"}:
+        console.print("[red]✗ Error: --engine must be either 'ydata' or 'sweetviz'[/red]")
+        raise typer.Exit(1)
+
+    if compare and not Path(compare).exists():
+        console.print(f"[red]✗ Error: Compare file not found: {compare}[/red]")
+        raise typer.Exit(1)
+
+    output_dir = Path(output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    report_filename = "ydata_profile.html" if engine_normalized == "ydata" else "sweetviz_report.html"
+    output_path = str(output_dir / report_filename)
+    report_title = f"{Path(file_path).stem} - Profiling Report"
+
+    console.print(f"\n📊 [bold]Dataset:[/bold] {file_path}")
+    console.print(f"⚙️ [bold]Engine:[/bold] {engine_normalized}")
+    if target:
+        console.print(f"🎯 [bold]Target:[/bold] {target}")
+    if compare:
+        console.print(f"🔁 [bold]Compare:[/bold] {compare}")
+    console.print("⏳ [yellow]Generating report may take 1-2 minutes...[/yellow]\n")
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task_report = progress.add_task("Generating HTML report...", total=None)
+
+            if engine_normalized == "ydata":
+                result = generate_ydata_profiling_report(
+                    file_path,
+                    output_path,
+                    minimal,
+                    report_title
+                )
+            else:
+                result = generate_sweetviz_report(
+                    file_path,
+                    target,
+                    compare,
+                    output_path
+                )
+
+            progress.update(task_report, completed=True)
+
+    except Exception as e:
+        console.print(f"[red]✗ Report generation failed: {e}[/red]")
+        raise typer.Exit(1)
+
+    if not result.get("success", False):
+        console.print(f"[red]✗ Report generation failed: {result.get('error', 'Unknown error')}[/red]")
+        raise typer.Exit(1)
+
+    report_path = result.get("report_path", output_path)
+
+    console.print(Panel(
+        f"✅ Report generated successfully!\n\nPath: {report_path}",
+        title="Report Ready",
+        border_style="green"
+    ))
+
+    try:
+        webbrowser.open(str(Path(report_path).resolve().as_uri()))
+    except Exception:
+        pass
+
+
+@app.command()
+def compare(
+    file1: str = typer.Argument(..., help="First dataset path (CSV or Parquet)"),
+    file2: str = typer.Argument(..., help="Second dataset path (CSV or Parquet)"),
+    label1: str = typer.Option("Dataset A", "--label1", help="Display label for first dataset"),
+    label2: str = typer.Option("Dataset B", "--label2", help="Display label for second dataset"),
+    output: str = typer.Option("./outputs/compare/", "--output", "-o", help="Output directory for comparison reports")
+):
+    """
+    Compare two datasets side-by-side for schema and distribution differences.
+
+    Example:
+        ds-agent compare train.csv test.csv
+        ds-agent compare raw.csv cleaned.csv --label1 "Before" --label2 "After"
+    """
+    import math
+    from datetime import datetime
+    import polars as pl
+    from ds_agent.utils.polars_helpers import load_dataframe
+    eda_reports_module = _load_module_from_src("ds_agent_cli_eda_reports_compare", "tools/eda_reports.py")
+    generate_sweetviz_report = eda_reports_module.generate_sweetviz_report
+
+    if not Path(file1).exists():
+        console.print(f"[red]✗ Error: File not found: {file1}[/red]")
+        raise typer.Exit(1)
+    if not Path(file2).exists():
+        console.print(f"[red]✗ Error: File not found: {file2}[/red]")
+        raise typer.Exit(1)
+
+    output_dir = Path(output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    console.print(Panel.fit(
+        f"🔍 Dataset Compare\n{label1} vs {label2}",
+        style="bold blue"
+    ))
+
+    def _fmt_num(value, digits: int = 4) -> str:
+        if value is None:
+            return "-"
+        try:
+            value = float(value)
+        except Exception:
+            return "-"
+        if math.isnan(value) or math.isinf(value):
+            return "-"
+        return f"{value:.{digits}f}"
+
+    def _col_stats(df: pl.DataFrame, col_name: str) -> dict:
+        series = df[col_name]
+        row_count = len(df)
+        null_count = series.null_count()
+        null_pct = (null_count / row_count * 100.0) if row_count > 0 else 0.0
+
+        is_numeric = series.dtype in pl.NUMERIC_DTYPES
+        mean_val = series.mean() if is_numeric else None
+        median_val = series.median() if is_numeric else None
+        std_val = series.std() if is_numeric else None
+
+        return {
+            "dtype": str(series.dtype),
+            "is_numeric": is_numeric,
+            "mean": float(mean_val) if mean_val is not None else None,
+            "median": float(median_val) if median_val is not None else None,
+            "std": float(std_val) if std_val is not None else None,
+            "null_pct": round(null_pct, 2),
+            "unique": int(series.n_unique())
+        }
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console
+    ) as progress:
+        task = progress.add_task("Loading datasets with Polars...", total=None)
+        try:
+            df_a = load_dataframe(file1)
+            df_b = load_dataframe(file2)
+        except Exception as e:
+            console.print(f"[red]✗ Failed to load datasets: {e}[/red]")
+            raise typer.Exit(1)
+        progress.update(task, completed=True)
+
+    cols_a = set(df_a.columns)
+    cols_b = set(df_b.columns)
+
+    shared_cols = sorted(cols_a.intersection(cols_b))
+    only_a = sorted(cols_a - cols_b)
+    only_b = sorted(cols_b - cols_a)
+
+    comparison_rows = []
+    numeric_shift_rows = []
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console
+    ) as progress:
+        task = progress.add_task("Computing side-by-side comparison...", total=None)
+        for col in shared_cols:
+            stats_a = _col_stats(df_a, col)
+            stats_b = _col_stats(df_b, col)
+
+            mean_diff = None
+            std_diff = None
+            if stats_a["is_numeric"] and stats_b["is_numeric"]:
+                if stats_a["mean"] is not None and stats_b["mean"] is not None:
+                    mean_diff = stats_a["mean"] - stats_b["mean"]
+                if stats_a["std"] is not None and stats_b["std"] is not None:
+                    std_diff = stats_a["std"] - stats_b["std"]
+
+            comparison_rows.append({
+                "column": col,
+                "a": stats_a,
+                "b": stats_b,
+                "mean_diff": mean_diff,
+                "std_diff": std_diff
+            })
+
+            if mean_diff is not None or std_diff is not None:
+                numeric_shift_rows.append({
+                    "column": col,
+                    "mean_diff": mean_diff,
+                    "std_diff": std_diff
+                })
+        progress.update(task, completed=True)
+
+    stats_panel = Panel(
+        "\n".join([
+            f"Shared columns: {len(shared_cols)}",
+            f"Columns only in {label1}: {len(only_a)}",
+            f"Columns only in {label2}: {len(only_b)}",
+            f"Rows in {label1}: {len(df_a)}",
+            f"Rows in {label2}: {len(df_b)}"
+        ]),
+        title="Overall Stats",
+        border_style="cyan"
+    )
+    console.print()
+    console.print(stats_panel)
+
+    comparison_table = Table(title=f"📋 Shared Column Comparison ({label1} vs {label2})")
+    comparison_table.add_column("Column", style="bold")
+    comparison_table.add_column(f"Type ({label1})", style="cyan")
+    comparison_table.add_column(f"Type ({label2})", style="cyan")
+    comparison_table.add_column(f"Mean ({label1})", justify="right")
+    comparison_table.add_column(f"Mean ({label2})", justify="right")
+    comparison_table.add_column(f"Median ({label1})", justify="right")
+    comparison_table.add_column(f"Median ({label2})", justify="right")
+    comparison_table.add_column(f"Null % ({label1})", justify="right")
+    comparison_table.add_column(f"Null % ({label2})", justify="right")
+    comparison_table.add_column(f"Unique ({label1})", justify="right")
+    comparison_table.add_column(f"Unique ({label2})", justify="right")
+    comparison_table.add_column("Mean Diff", justify="right")
+    comparison_table.add_column("Std Diff", justify="right")
+
+    for row in comparison_rows:
+        a_stats = row["a"]
+        b_stats = row["b"]
+        comparison_table.add_row(
+            row["column"],
+            a_stats["dtype"],
+            b_stats["dtype"],
+            _fmt_num(a_stats["mean"]),
+            _fmt_num(b_stats["mean"]),
+            _fmt_num(a_stats["median"]),
+            _fmt_num(b_stats["median"]),
+            _fmt_num(a_stats["null_pct"], 2),
+            _fmt_num(b_stats["null_pct"], 2),
+            str(a_stats["unique"]),
+            str(b_stats["unique"]),
+            _fmt_num(row["mean_diff"]),
+            _fmt_num(row["std_diff"])
+        )
+
+    console.print()
+    console.print(comparison_table)
+
+    if only_a or only_b:
+        missing_table = Table(title="🚨 Columns Not Shared", border_style="red")
+        missing_table.add_column("Column", style="red")
+        missing_table.add_column("Present In", style="red")
+        missing_table.add_column("Missing In", style="red")
+
+        for col in only_a:
+            missing_table.add_row(col, label1, label2, style="red")
+        for col in only_b:
+            missing_table.add_row(col, label2, label1, style="red")
+
+        console.print()
+        console.print(missing_table)
+
+    if numeric_shift_rows:
+        shift_table = Table(title="📈 Numeric Distribution Shift")
+        shift_table.add_column("Column", style="bold")
+        shift_table.add_column("Mean Diff", justify="right", style="yellow")
+        shift_table.add_column("Std Diff", justify="right", style="yellow")
+
+        for item in numeric_shift_rows:
+            shift_table.add_row(
+                item["column"],
+                _fmt_num(item["mean_diff"]),
+                _fmt_num(item["std_diff"])
+            )
+
+        console.print()
+        console.print(shift_table)
+
+    report_data = {
+        "generated_at": datetime.utcnow().isoformat() + "Z",
+        "dataset_a": {
+            "label": label1,
+            "path": file1,
+            "rows": len(df_a),
+            "columns": len(df_a.columns)
+        },
+        "dataset_b": {
+            "label": label2,
+            "path": file2,
+            "rows": len(df_b),
+            "columns": len(df_b.columns)
+        },
+        "summary": {
+            "shared_columns_count": len(shared_cols),
+            "columns_only_in_a_count": len(only_a),
+            "columns_only_in_b_count": len(only_b),
+            "rows_a": len(df_a),
+            "rows_b": len(df_b)
+        },
+        "columns_only_in_a": only_a,
+        "columns_only_in_b": only_b,
+        "shared_columns": comparison_rows,
+        "numeric_distribution_shift": numeric_shift_rows
+    }
+
+    report_path = output_dir / f"compare_{Path(file1).stem}_vs_{Path(file2).stem}.json"
+    with open(report_path, "w") as f:
+        json.dump(report_data, f, indent=2)
+
+    console.print(f"\n💾 Comparison JSON report saved to: [cyan]{report_path}[/cyan]")
+
+    if output:
+        sweetviz_path = output_dir / "sweetviz_compare_report.html"
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task = progress.add_task("Generating Sweetviz compare report...", total=None)
+            sweetviz_result = generate_sweetviz_report(
+                file_path=file1,
+                target_col=None,
+                compare_file_path=file2,
+                output_path=str(sweetviz_path),
+                title=f"{label1} vs {label2} - Sweetviz Comparison"
+            )
+            progress.update(task, completed=True)
+
+        if sweetviz_result.get("success", False):
+            console.print(f"🌐 Sweetviz compare report saved to: [cyan]{sweetviz_result.get('report_path', sweetviz_path)}[/cyan]")
+        else:
+            console.print(f"[yellow]⚠ Sweetviz compare report generation skipped: {sweetviz_result.get('error', 'Unknown error')}[/yellow]")
+
+
+@app.command()
+def bi(
+    file_path: str = typer.Argument(..., help="Path to dataset file (CSV or Parquet)"),
+    customer_col: str = typer.Option(None, "--customer", "-c", help="Customer ID column name"),
+    date_col: str = typer.Option(None, "--date", "-d", help="Date column name"),
+    value_col: str = typer.Option(None, "--value", "-v", help="Revenue/value column name"),
+    target_col: str = typer.Option(None, "--target", "-y", help="Optional target column for churn analysis"),
+    analysis: str = typer.Option("all", "--analysis", help="Analysis type: all, cohort, rfm, kpi, churn"),
+    output: str = typer.Option("./outputs/bi/", "--output", "-o", help="Output directory for BI results")
+):
+    """
+    Run business intelligence analytics on a dataset.
+
+    Example:
+        ds-agent bi transactions.csv --customer customer_id --date order_date --value amount
+        ds-agent bi customers.csv --customer id --date signup_date --analysis cohort
+    """
+    from datetime import datetime
+    import math
+    import pandas as pd
+    from ds_agent.utils.polars_helpers import load_dataframe
+    import ds_agent.tools.business_intelligence as bi_tools
+
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    analysis = analysis.strip().lower()
+    valid_analyses = {"all", "cohort", "rfm", "kpi", "churn"}
+    if analysis not in valid_analyses:
+        console.print("[red]✗ Error: --analysis must be one of all, cohort, rfm, kpi, churn[/red]")
+        raise typer.Exit(1)
+
+    output_dir = Path(output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console
+    ) as progress:
+        task = progress.add_task("Loading dataset...", total=None)
+        try:
+            df = load_dataframe(file_path)
+        except Exception as e:
+            console.print(f"[red]✗ Failed to load dataset: {e}[/red]")
+            raise typer.Exit(1)
+        progress.update(task, completed=True)
+
+    def _format_metric(value) -> str:
+        if value is None:
+            return "-"
+        if isinstance(value, bool):
+            return "Yes" if value else "No"
+        if isinstance(value, int):
+            return f"{value:,}"
+        if isinstance(value, float):
+            if math.isnan(value) or math.isinf(value):
+                return "-"
+            if abs(value) >= 1000:
+                return f"{value:,.2f}"
+            return f"{value:.4f}"
+        return str(value)
+
+    def _trend_arrow(trend_value) -> str:
+        if trend_value is None:
+            return "→"
+        if isinstance(trend_value, str):
+            text = trend_value.strip().lower()
+            if any(token in text for token in ["up", "increase", "growing", "higher", "+"]):
+                return "↑"
+            if any(token in text for token in ["down", "decrease", "decline", "lower", "-"]):
+                return "↓"
+            return "→"
+        try:
+            numeric = float(trend_value)
+        except Exception:
+            return "→"
+        if numeric > 0:
+            return "↑"
+        if numeric < 0:
+            return "↓"
+        return "→"
+
+    validation_errors = []
+    required_columns = set()
+
+    def _require_option(value: Optional[str], option_name: str, analysis_name: str):
+        if not value:
+            validation_errors.append(f"{option_name} is required for '{analysis_name}' analysis")
+        else:
+            required_columns.add(value)
+
+    if analysis in {"kpi", "all"}:
+        _require_option(date_col, "--date/-d", "kpi")
+        _require_option(value_col, "--value/-v", "kpi")
+
+    if analysis in {"cohort", "all"}:
+        _require_option(customer_col, "--customer/-c", "cohort")
+        _require_option(date_col, "--date/-d", "cohort")
+
+    if analysis in {"rfm", "all"}:
+        _require_option(customer_col, "--customer/-c", "rfm")
+        _require_option(date_col, "--date/-d", "rfm")
+        _require_option(value_col, "--value/-v", "rfm")
+
+    if analysis in {"churn", "all"}:
+        _require_option(target_col, "--target/-y", "churn")
+
+    if validation_errors:
+        for err in validation_errors:
+            console.print(f"[red]✗ {err}[/red]")
+        raise typer.Exit(1)
+
+    missing_cols = [col for col in sorted(required_columns) if col not in df.columns]
+    if missing_cols:
+        console.print(f"[red]✗ Required columns not found in dataset: {', '.join(missing_cols)}[/red]")
+        raise typer.Exit(1)
+
+    console.print(Panel.fit(
+        f"💼 Business Intelligence Analytics\nAnalysis: {analysis}",
+        style="bold blue"
+    ))
+
+    results = {
+        "meta": {
+            "file_path": file_path,
+            "analysis": analysis,
+            "rows": len(df),
+            "columns": len(df.columns),
+            "output_dir": str(output_dir),
+            "generated_at": datetime.utcnow().isoformat() + "Z"
+        },
+        "kpi": None,
+        "cohort": None,
+        "rfm": None,
+        "churn": None
+    }
+    actionable_insights = []
+
+    if analysis in {"kpi", "all"}:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task = progress.add_task("Calculating KPI analytics...", total=None)
+
+            calculate_kpis = getattr(bi_tools, "calculate_kpis", None)
+            if callable(calculate_kpis):
+                try:
+                    kpi_result = calculate_kpis(
+                        data=df,
+                        customer_id_column=customer_col,
+                        date_column=date_col,
+                        value_column=value_col
+                    )
+                except TypeError:
+                    try:
+                        kpi_result = calculate_kpis(df, customer_col, date_col, value_col)
+                    except Exception as e:
+                        console.print(f"[yellow]⚠ calculate_kpis failed, using fallback KPI computation: {e}[/yellow]")
+                        kpi_result = None
+            else:
+                kpi_result = None
+
+            if kpi_result is None:
+                base_kpis = {
+                    "Total Rows": len(df),
+                    "Total Revenue": float(df[value_col].sum()) if value_col else None,
+                    "Average Value": float(df[value_col].mean()) if value_col else None,
+                    "Unique Customers": int(df[customer_col].n_unique()) if customer_col else None,
+                }
+
+                trend_pct = None
+                if date_col and value_col:
+                    try:
+                        trend_df = df.select([date_col, value_col]).to_pandas()
+                        trend_df[date_col] = pd.to_datetime(trend_df[date_col], errors="coerce")
+                        trend_df[value_col] = pd.to_numeric(trend_df[value_col], errors="coerce")
+                        trend_df = trend_df.dropna(subset=[date_col, value_col]).sort_values(date_col)
+                        if len(trend_df) >= 6:
+                            mid = len(trend_df) // 2
+                            first_avg = trend_df.iloc[:mid][value_col].mean()
+                            second_avg = trend_df.iloc[mid:][value_col].mean()
+                            if first_avg and not pd.isna(first_avg):
+                                trend_pct = float(((second_avg - first_avg) / abs(first_avg)) * 100.0)
+                    except Exception:
+                        trend_pct = None
+
+                kpi_result = {
+                    "kpis": [{"name": k, "value": v, "trend": trend_pct if k in {"Total Revenue", "Average Value"} else None} for k, v in base_kpis.items() if v is not None],
+                    "fallback": True
+                }
+
+            progress.update(task, completed=True)
+
+        kpi_table = Table(title="📊 KPI Summary")
+        kpi_table.add_column("KPI", style="cyan")
+        kpi_table.add_column("Value", style="white", justify="right")
+        kpi_table.add_column("Trend", style="white", justify="center")
+
+        kpi_items = []
+        if isinstance(kpi_result, dict) and isinstance(kpi_result.get("kpis"), list):
+            for item in kpi_result.get("kpis", []):
+                if isinstance(item, dict):
+                    kpi_items.append({
+                        "name": str(item.get("name", "KPI")),
+                        "value": item.get("value"),
+                        "trend": item.get("trend")
+                    })
+
+        if not kpi_items and isinstance(kpi_result, dict):
+            for key, val in kpi_result.items():
+                if isinstance(val, (str, int, float, bool)):
+                    kpi_items.append({"name": str(key), "value": val, "trend": None})
+
+        for item in kpi_items:
+            arrow = _trend_arrow(item.get("trend"))
+            arrow_style = "green" if arrow == "↑" else ("red" if arrow == "↓" else "yellow")
+            kpi_table.add_row(
+                item["name"],
+                _format_metric(item.get("value")),
+                f"[{arrow_style}]{arrow}[/{arrow_style}]"
+            )
+
+        console.print()
+        console.print(kpi_table)
+        results["kpi"] = kpi_result
+
+        revenue_item = next((item for item in kpi_items if "revenue" in item["name"].lower()), None)
+        if revenue_item:
+            arrow = _trend_arrow(revenue_item.get("trend"))
+            if arrow == "↓":
+                actionable_insights.append("Revenue momentum is declining; review recent pricing, acquisition channels, or discount strategy.")
+            elif arrow == "↑":
+                actionable_insights.append("Revenue momentum is improving; scale the channels or offers driving the uplift.")
+
+    if analysis in {"cohort", "all"}:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task = progress.add_task("Running cohort retention analysis...", total=None)
+            cohort_result = bi_tools.perform_cohort_analysis(
+                data=df,
+                customer_id_column=customer_col,
+                date_column=date_col,
+                value_column=value_col,
+                cohort_period="monthly",
+                metric="retention"
+            )
+            progress.update(task, completed=True)
+
+        cohort_matrix = cohort_result.get("cohort_matrix", {})
+        period_keys = sorted(cohort_matrix.keys(), key=lambda x: int(x) if str(x).isdigit() else str(x))
+        cohort_labels = sorted({str(label) for inner in cohort_matrix.values() if isinstance(inner, dict) for label in inner.keys()})
+
+        retention_table = Table(title="👥 Cohort Retention Matrix")
+        retention_table.add_column("Cohort", style="bold")
+        for key in period_keys:
+            retention_table.add_column(f"P{key}", justify="right")
+
+        for cohort_label in cohort_labels:
+            row_values = [cohort_label]
+            for key in period_keys:
+                val = None
+                inner = cohort_matrix.get(key, {})
+                if isinstance(inner, dict):
+                    val = inner.get(cohort_label)
+
+                if val is None:
+                    cell = "-"
+                else:
+                    try:
+                        rate = float(val)
+                    except Exception:
+                        cell = str(val)
+                    else:
+                        pct = rate * 100.0
+                        if pct >= 70:
+                            cell = f"[green]{pct:.1f}%[/green]"
+                        elif pct >= 40:
+                            cell = f"[yellow]{pct:.1f}%[/yellow]"
+                        else:
+                            cell = f"[red]{pct:.1f}%[/red]"
+
+                row_values.append(cell)
+
+            retention_table.add_row(*row_values)
+
+        console.print()
+        console.print(retention_table)
+        results["cohort"] = cohort_result
+
+        for insight in cohort_result.get("insights", [])[:2]:
+            actionable_insights.append(str(insight))
+
+    if analysis in {"rfm", "all"}:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task = progress.add_task("Running RFM segmentation...", total=None)
+
+            rfm_fn = getattr(bi_tools, "rfm_segmentation", None)
+            if callable(rfm_fn):
+                try:
+                    rfm_result = rfm_fn(
+                        data=df,
+                        customer_id_column=customer_col,
+                        date_column=date_col,
+                        value_column=value_col
+                    )
+                except TypeError:
+                    rfm_result = rfm_fn(df, customer_col, date_col, value_col)
+            else:
+                rfm_result = bi_tools.perform_rfm_analysis(
+                    data=df,
+                    customer_id_column=customer_col,
+                    date_column=date_col,
+                    value_column=value_col
+                )
+
+            progress.update(task, completed=True)
+
+        segment_summary = rfm_result.get("segment_summary", {}) if isinstance(rfm_result, dict) else {}
+        rfm_table = Table(title="🎯 Customer Segments (RFM)")
+        rfm_table.add_column("Segment", style="cyan")
+        rfm_table.add_column("Customers", justify="right")
+        rfm_table.add_column("Share", justify="right")
+        rfm_table.add_column("Avg Monetary", justify="right")
+
+        if isinstance(segment_summary, dict) and segment_summary:
+            sorted_segments = sorted(segment_summary.items(), key=lambda x: x[1].get("count", 0), reverse=True)
+            for segment, stats in sorted_segments:
+                rfm_table.add_row(
+                    str(segment),
+                    _format_metric(stats.get("count")),
+                    f"{float(stats.get('percentage', 0.0)):.1f}%",
+                    _format_metric(stats.get("avg_monetary"))
+                )
+            top_segment = sorted_segments[0][0]
+            actionable_insights.append(f"Your largest segment is '{top_segment}'; tailor campaigns specifically for this group to improve conversion.")
+        else:
+            rfm_table.add_row("-", "-", "-", "-")
+
+        console.print()
+        console.print(rfm_table)
+        results["rfm"] = rfm_result
+
+    if analysis in {"churn", "all"} and target_col:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task = progress.add_task("Running churn analysis...", total=None)
+
+            churn_fn = getattr(bi_tools, "churn_prediction", None)
+            if callable(churn_fn):
+                try:
+                    churn_result = churn_fn(data=df, target_column=target_col)
+                except TypeError:
+                    try:
+                        churn_result = churn_fn(df, target_col)
+                    except Exception as e:
+                        churn_result = {"error": str(e)}
+            else:
+                target_series = df[target_col].drop_nulls()
+                unique_vals = set([str(v).strip().lower() for v in target_series.unique().to_list()])
+                positive_tokens = {"1", "true", "yes", "y", "churn", "churned"}
+                churn_rate = None
+
+                try:
+                    if unique_vals.issubset({"0", "1", "true", "false", "yes", "no", "y", "n", "churn", "churned", "active"}):
+                        mapped = target_series.cast(str).str.to_lowercase()
+                        positives = mapped.is_in(list(positive_tokens)).sum()
+                        churn_rate = float(positives / len(mapped)) if len(mapped) else None
+                    else:
+                        numeric_target = pd.to_numeric(target_series.to_list(), errors="coerce")
+                        numeric_target = pd.Series(numeric_target).dropna()
+                        if len(numeric_target) and numeric_target.nunique() <= 2:
+                            churn_rate = float(numeric_target.mean())
+                except Exception:
+                    churn_rate = None
+
+                churn_result = {
+                    "status": "fallback",
+                    "message": "churn_prediction function not found; returning churn baseline summary.",
+                    "target_column": target_col,
+                    "rows_evaluated": int(len(target_series)),
+                    "churn_rate": churn_rate,
+                    "unique_target_values": sorted(list(unique_vals))
+                }
+
+            progress.update(task, completed=True)
+
+        churn_table = Table(title="📉 Churn Analysis")
+        churn_table.add_column("Metric", style="cyan")
+        churn_table.add_column("Value", justify="right")
+
+        if isinstance(churn_result, dict):
+            churn_table.add_row("Target Column", str(churn_result.get("target_column", target_col)))
+            if churn_result.get("churn_rate") is not None:
+                churn_rate_pct = float(churn_result.get("churn_rate")) * 100.0
+                churn_table.add_row("Estimated Churn Rate", f"{churn_rate_pct:.2f}%")
+                if churn_rate_pct >= 30:
+                    actionable_insights.append("Estimated churn is high; prioritize retention campaigns for at-risk customers this cycle.")
+                elif churn_rate_pct >= 15:
+                    actionable_insights.append("Estimated churn is moderate; test proactive customer success outreach on vulnerable segments.")
+                else:
+                    actionable_insights.append("Estimated churn is low; maintain retention programs and monitor leading indicators weekly.")
+            for key in ["status", "message", "rows_evaluated"]:
+                if key in churn_result:
+                    churn_table.add_row(key.replace("_", " ").title(), _format_metric(churn_result.get(key)))
+
+        console.print()
+        console.print(churn_table)
+        results["churn"] = churn_result
+
+    timestamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+    for key in ["kpi", "cohort", "rfm", "churn"]:
+        if results.get(key) is not None:
+            partial_path = output_dir / f"{key}_results_{timestamp}.json"
+            with open(partial_path, "w") as f:
+                json.dump(results[key], f, indent=2, default=str)
+
+    summary_path = output_dir / f"bi_results_{timestamp}.json"
+    with open(summary_path, "w") as f:
+        json.dump(results, f, indent=2, default=str)
+
+    console.print(f"\n💾 BI results saved to: [cyan]{output_dir}[/cyan]")
+    console.print(f"📄 Combined summary: [cyan]{summary_path}[/cyan]")
+
+    deduped_insights = []
+    for insight in actionable_insights:
+        clean = str(insight).strip()
+        if clean and clean not in deduped_insights:
+            deduped_insights.append(clean)
+
+    while len(deduped_insights) < 3:
+        fallback_pool = [
+            "Monitor weekly KPI trends and quickly investigate any sudden drops.",
+            "Segment customers by lifecycle stage and personalize messaging for each segment.",
+            "Use cohort retention patterns to prioritize onboarding improvements in the first customer period."
+        ]
+        for candidate in fallback_pool:
+            if candidate not in deduped_insights:
+                deduped_insights.append(candidate)
+            if len(deduped_insights) >= 3:
+                break
+
+    top3 = deduped_insights[:3]
+    insights_text = "\n".join([f"{idx}. {insight}" for idx, insight in enumerate(top3, start=1)])
+    console.print()
+    console.print(Panel(
+        insights_text,
+        title="💡 Top 3 Business Insights",
+        border_style="green"
+    ))
+
+
+@app.command()
+def chat(
+    file_path: Optional[str] = typer.Argument(None, help="Optional dataset path to auto-load at startup"),
+    session_id: str = typer.Option(None, "--session", "-s", help="Resume a specific session ID"),
+    model: str = typer.Option("llama-3.3-70b-versatile", "--model", help="LLM model to use")
+):
+    """
+    Launch an interactive chat session for follow-up questions on datasets.
+
+    Example:
+        ds-agent chat sales.csv
+        ds-agent chat --session abc123
+    """
+    from datetime import datetime
+    from rich.prompt import Prompt
+    from rich.markdown import Markdown
+    from ds_agent.session_store import SessionStore
+    from ds_agent.session_memory import SessionMemory
+    from ds_agent.tools.data_profiling import profile_dataset
+
+    console.print(Panel.fit(
+        "DS-Agent Chat — type 'help' for commands, 'exit' to quit",
+        title="💬 Chat",
+        border_style="blue"
+    ))
+
+    store = SessionStore()
+    save_session_fn = getattr(store, "save_session", None) or getattr(store, "save", None)
+    load_session_fn = getattr(store, "load_session", None) or getattr(store, "load", None)
+
+    if session_id:
+        session_memory = load_session_fn(session_id) if callable(load_session_fn) else None
+        if session_memory is None:
+            console.print(f"[yellow]⚠ Session '{session_id}' not found. Creating a new one.[/yellow]")
+            session_memory = SessionMemory(session_id=session_id)
+    else:
+        session_memory = SessionMemory()
+
+    current_dataset = file_path or session_memory.last_dataset
+    last_analysis_result = None
+
+    def _print_dataset_summary(profile: dict, path: str):
+        shape = profile.get("shape", {})
+        col_types = profile.get("column_types", {})
+        overall = profile.get("overall_stats", {})
+
+        summary_table = Table(title=f"📊 Dataset Summary: {Path(path).name}", show_header=False)
+        summary_table.add_column("Metric", style="cyan", width=26)
+        summary_table.add_column("Value", style="white")
+
+        summary_table.add_row("File", str(path))
+        summary_table.add_row("Rows", str(shape.get("rows", "-")))
+        summary_table.add_row("Columns", str(shape.get("columns", "-")))
+        summary_table.add_row("Numeric Columns", str(len(col_types.get("numeric", []))))
+        summary_table.add_row("Categorical Columns", str(len(col_types.get("categorical", []))))
+        summary_table.add_row("Datetime Columns", str(len(col_types.get("datetime", []))))
+        summary_table.add_row("Null %", f"{overall.get('null_percentage', 0)}%")
+        summary_table.add_row("Duplicate Rows", str(overall.get("duplicate_rows", 0)))
+
+        console.print()
+        console.print(summary_table)
+
+    def _load_and_profile_dataset(path: str) -> bool:
+        nonlocal current_dataset
+        if not Path(path).exists():
+            console.print(f"[red]✗ File not found: {path}[/red]")
+            return False
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task = progress.add_task(f"Profiling dataset: {path}", total=None)
+            try:
+                profile = profile_dataset(path)
+            except Exception as e:
+                console.print(f"[red]✗ Failed to profile dataset: {e}[/red]")
+                return False
+            progress.update(task, completed=True)
+
+        current_dataset = path
+        session_memory.update(last_dataset=path)
+        session_memory.add_workflow_step(
+            "profile_dataset",
+            {
+                "success": True,
+                "arguments": {"file_path": path},
+                "result": {
+                    "output_path": path,
+                    "shape": profile.get("shape", {})
+                }
+            }
+        )
+        _print_dataset_summary(profile, path)
+        return True
+
+    if current_dataset:
+        _load_and_profile_dataset(current_dataset)
+
+    try:
+        os.environ["GROQ_MODEL"] = model
+        from ds_agent.orchestrator import DataScienceCopilot
+
+        copilot = DataScienceCopilot(
+            provider="groq",
+            session_id=session_memory.session_id,
+            use_session_memory=False
+        )
+    except Exception as e:
+        console.print(f"[red]✗ Failed to initialize orchestrator: {e}[/red]")
+        if callable(save_session_fn):
+            save_session_fn(session_memory)
+        raise typer.Exit(1)
+
+    help_panel = Panel(
+        "\n".join([
+            "help               Show commands",
+            "history            Show workflow history",
+            "summary            Re-print current dataset summary",
+            "load <file>        Load/switch dataset",
+            "clear              Clear current session history",
+            "export             Export current session/results",
+            "exit or quit       Save session and exit",
+        ]),
+        title="Available Commands",
+        border_style="cyan"
+    )
+
+    while True:
+        user_message = Prompt.ask(f"[bold cyan][{session_memory.session_id}][/bold cyan] > ").strip()
+        if not user_message:
+            continue
+
+        lowered = user_message.lower().strip()
+
+        if lowered in {"exit", "quit"}:
+            if callable(save_session_fn):
+                save_session_fn(session_memory)
+            console.print("[green]✓ Session saved. Goodbye![/green]")
+            break
+
+        if lowered == "help":
+            console.print(help_panel)
+            continue
+
+        if lowered == "history":
+            history = session_memory.workflow_history
+            if not history:
+                console.print("[yellow]No workflow history yet.[/yellow]")
+                continue
+
+            history_table = Table(title="🧭 Workflow History")
+            history_table.add_column("Time", style="cyan")
+            history_table.add_column("Tool", style="white")
+            history_table.add_column("Status", style="white")
+
+            for step in history[-20:]:
+                ts = str(step.get("timestamp", ""))
+                ts_short = ts.split("T")[-1][:8] if "T" in ts else ts[:8]
+                tool = str(step.get("tool", "-"))
+                result = step.get("result", {})
+                success = False
+                if isinstance(result, dict):
+                    success = bool(result.get("success", False))
+                status = "[green]✓[/green]" if success else "[red]✗[/red]"
+                history_table.add_row(ts_short, tool, status)
+
+            console.print()
+            console.print(history_table)
+            continue
+
+        if lowered == "summary":
+            if not current_dataset:
+                console.print("[yellow]No dataset is loaded. Use 'load <file>'.[/yellow]")
+                continue
+            _load_and_profile_dataset(current_dataset)
+            continue
+
+        if lowered == "clear":
+            # Keep currently loaded dataset but clear conversational/workflow memory.
+            last_dataset = current_dataset
+            session_memory.clear()
+            if last_dataset:
+                session_memory.update(last_dataset=last_dataset)
+            console.print("[green]✓ Session history cleared.[/green]")
+            continue
+
+        if lowered == "export":
+            export_dir = Path("./outputs/chat/")
+            export_dir.mkdir(parents=True, exist_ok=True)
+            ts = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+            export_path = export_dir / f"chat_session_{session_memory.session_id}_{ts}.json"
+
+            export_payload = {
+                "session": session_memory.to_dict(),
+                "last_result": last_analysis_result,
+                "current_dataset": current_dataset,
+                "exported_at": datetime.utcnow().isoformat() + "Z"
+            }
+
+            with open(export_path, "w") as f:
+                json.dump(export_payload, f, indent=2, default=str)
+
+            console.print(f"[green]✓ Exported session to:[/green] [cyan]{export_path}[/cyan]")
+            continue
+
+        if lowered.startswith("load "):
+            load_path = user_message[5:].strip().strip('"').strip("'")
+            if not load_path:
+                console.print("[yellow]Usage: load <file_path>[/yellow]")
+                continue
+            _load_and_profile_dataset(load_path)
+            continue
+
+        resolver = getattr(session_memory, "resolve_context", None) or getattr(session_memory, "resolve_ambiguity", None)
+        resolved_context = resolver(user_message) if callable(resolver) else {}
+
+        effective_dataset = resolved_context.get("file_path") or current_dataset or session_memory.last_dataset
+        effective_target = resolved_context.get("target_col") or session_memory.last_target_col
+
+        if not effective_dataset:
+            console.print("[yellow]No dataset loaded. Use 'load <file>' or pass file_path at startup.[/yellow]")
+            continue
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task = progress.add_task("Thinking...", total=None)
+            try:
+                analysis_result = copilot.analyze(
+                    file_path=effective_dataset,
+                    task_description=user_message,
+                    target_col=effective_target,
+                    use_cache=True,
+                    stream=False,
+                    max_iterations=20
+                )
+            except Exception as e:
+                progress.update(task, completed=True)
+                console.print(f"[red]✗ Chat analysis failed: {e}[/red]")
+                continue
+            progress.update(task, completed=True)
+
+        last_analysis_result = analysis_result
+        session_memory.update(last_dataset=effective_dataset)
+        if effective_target:
+            session_memory.update(last_target_col=effective_target)
+
+        workflow_steps = analysis_result.get("workflow_history", []) if isinstance(analysis_result, dict) else []
+        for step in workflow_steps:
+            if not isinstance(step, dict):
+                continue
+            tool_name = step.get("tool", "unknown_tool")
+            tool_result = step.get("result", {}) if isinstance(step.get("result", {}), dict) else {"raw_result": step.get("result")}
+            session_memory.add_workflow_step(
+                tool_name,
+                {
+                    "success": tool_result.get("success", True),
+                    "arguments": {
+                        "file_path": effective_dataset,
+                        "target_col": effective_target
+                    },
+                    "result": tool_result
+                }
+            )
+
+        response_text = ""
+        if isinstance(analysis_result, dict):
+            response_text = analysis_result.get("summary") or analysis_result.get("message") or "Analysis complete."
+        else:
+            response_text = str(analysis_result)
+
+        session_memory.add_conversation(user_message, response_text)
+        console.print()
+        console.print(Markdown(response_text))
+
+
+@app.command()
+def plot(
+    file_path: str = typer.Argument(..., help="Path to dataset file (CSV or Parquet)"),
+    query: Optional[str] = typer.Argument(None, help="Optional plot request like 'correlation heatmap' or 'revenue by region'"),
+    chart_type: str = typer.Option("auto", "--type", "-t", help="Chart type: auto, bar, line, histogram, scatter, heatmap, box, distribution"),
+    x: str = typer.Option(None, "--x", help="X-axis column name"),
+    y: str = typer.Option(None, "--y", help="Y-axis column name"),
+    target: str = typer.Option(None, "--target", help="Target/color-by column name"),
+    output: str = typer.Option("./outputs/plots/", "--output", "-o", help="Output directory for generated plots")
+):
+    """
+    Generate visualization charts from a dataset.
+
+    Example:
+        ds-agent plot sales.csv "top products bar chart" --y revenue
+        ds-agent plot sales.csv --type heatmap
+        ds-agent plot sales.csv --type histogram --x revenue
+    """
+    from ds_agent.tools.visualization_engine import generate_all_plots
+    from ds_agent.tools.plotly_visualizations import (
+        generate_interactive_correlation_heatmap,
+        generate_interactive_histogram,
+        generate_interactive_scatter,
+        generate_interactive_box_plots,
+        generate_interactive_time_series,
+    )
+    from ds_agent.utils.polars_helpers import load_dataframe, get_numeric_columns
+
+    console.print(Panel.fit(
+        "📉 Plot Generator",
+        style="bold blue"
+    ))
+
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    valid_types = {"auto", "bar", "line", "histogram", "scatter", "heatmap", "box", "distribution"}
+    chart_type = chart_type.strip().lower()
+    if chart_type not in valid_types:
+        console.print(f"[red]✗ Error: Invalid chart type '{chart_type}'.[/red]")
+        raise typer.Exit(1)
+
+    output_dir = Path(output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Load once for safe column inference when user does not pass x/y.
+    try:
+        df = load_dataframe(file_path)
+        numeric_cols = get_numeric_columns(df)
+        all_cols = list(df.columns)
+    except Exception as e:
+        console.print(f"[red]✗ Could not load dataset for plotting: {e}[/red]")
+        raise typer.Exit(1)
+
+    if x is None and all_cols:
+        x = all_cols[0]
+    if y is None and numeric_cols:
+        y = numeric_cols[0] if x not in numeric_cols else (numeric_cols[1] if len(numeric_cols) > 1 else numeric_cols[0])
+
+    query_text = (query or "").lower()
+
+    selected_mode = "all"
+    if "correlation" in query_text or "heatmap" in query_text:
+        selected_mode = "heatmap"
+    elif "distribution" in query_text or "histogram" in query_text:
+        selected_mode = "histogram"
+    elif "scatter" in query_text:
+        selected_mode = "scatter"
+    elif "box" in query_text:
+        selected_mode = "box"
+    elif "time" in query_text or "trend" in query_text:
+        selected_mode = "time_series"
+    elif chart_type != "auto":
+        if chart_type == "heatmap":
+            selected_mode = "heatmap"
+        elif chart_type in {"histogram", "distribution"}:
+            selected_mode = "histogram"
+        elif chart_type == "scatter":
+            selected_mode = "scatter"
+        elif chart_type == "box":
+            selected_mode = "box"
+        elif chart_type == "line":
+            selected_mode = "time_series"
+        else:
+            selected_mode = "all"
+
+    console.print(f"\n📊 [bold]Dataset:[/bold] {file_path}")
+    if query:
+        console.print(f"📝 [bold]Query:[/bold] {query}")
+    console.print(f"🎯 [bold]Mode:[/bold] {selected_mode}")
+
+    plot_paths = []
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task_plot = progress.add_task("Generating visualizations...", total=None)
+
+            if selected_mode == "heatmap":
+                result = generate_interactive_correlation_heatmap(
+                    file_path,
+                    output_path=str(output_dir / "correlation_heatmap.html")
+                )
+                if result.get("status") == "success":
+                    plot_paths.append(result.get("output_path"))
+                else:
+                    raise ValueError(result.get("message", "Failed to generate heatmap"))
+
+            elif selected_mode == "histogram":
+                hist_col = x if x in all_cols else (y if y in all_cols else (numeric_cols[0] if numeric_cols else None))
+                if not hist_col:
+                    raise ValueError("No suitable numeric column found for histogram")
+                result = generate_interactive_histogram(
+                    file_path,
+                    column=hist_col,
+                    color_col=target,
+                    output_path=str(output_dir / "histogram.html")
+                )
+                if result.get("status") == "success":
+                    plot_paths.append(result.get("output_path"))
+                else:
+                    raise ValueError(result.get("message", "Failed to generate histogram"))
+
+            elif selected_mode == "scatter":
+                if not x or not y:
+                    raise ValueError("Scatter plot requires x and y columns (inferred values unavailable)")
+                result = generate_interactive_scatter(
+                    file_path,
+                    x_col=x,
+                    y_col=y,
+                    color_col=target,
+                    output_path=str(output_dir / "scatter.html")
+                )
+                if result.get("status") == "success":
+                    plot_paths.append(result.get("output_path"))
+                else:
+                    raise ValueError(result.get("message", "Failed to generate scatter plot"))
+
+            elif selected_mode == "box":
+                result = generate_interactive_box_plots(
+                    file_path,
+                    columns=[col for col in [x, y] if col],
+                    group_by=target,
+                    output_path=str(output_dir / "box_plots.html")
+                )
+                if result.get("status") == "success":
+                    plot_paths.append(result.get("output_path"))
+                else:
+                    raise ValueError(result.get("message", "Failed to generate box plot"))
+
+            elif selected_mode == "time_series":
+                if not x:
+                    raise ValueError("Time series requires --x as time column")
+                value_cols = [col for col in [y, target] if col and col != x]
+                if not value_cols:
+                    value_cols = [col for col in numeric_cols if col != x][:1]
+                if not value_cols:
+                    raise ValueError("Time series requires at least one numeric value column")
+                result = generate_interactive_time_series(
+                    file_path,
+                    time_col=x,
+                    value_cols=value_cols,
+                    output_path=str(output_dir / "time_series.html")
+                )
+                if result.get("status") == "success":
+                    plot_paths.append(result.get("output_path"))
+                else:
+                    raise ValueError(result.get("message", "Failed to generate time series"))
+
+            else:
+                result = generate_all_plots(
+                    file_path,
+                    target_col=target,
+                    output_dir=str(output_dir)
+                )
+                plot_paths.extend(result.get("plots_generated", []))
+
+            progress.update(task_plot, completed=True)
+
+    except Exception as e:
+        console.print(f"\n[red]✗ Plot generation failed: {e}[/red]")
+        raise typer.Exit(1)
+
+    plot_paths = [p for p in plot_paths if p]
+    if not plot_paths:
+        console.print("[yellow]⚠ No plots were generated.[/yellow]")
+        raise typer.Exit(1)
+
+    console.print("\n[green]✓ Plots generated:[/green]")
+    for path in plot_paths:
+        console.print(f"  - [cyan]{path}[/cyan]")
+
+    summary = Table(title="📊 Plot Summary")
+    summary.add_column("#", style="cyan", width=4)
+    summary.add_column("Plot File", style="white")
+    summary.add_column("Path", style="green")
+
+    if len(plot_paths) > 1:
+        with Live(summary, console=console, refresh_per_second=8):
+            for idx, path in enumerate(plot_paths, start=1):
+                summary.add_row(str(idx), Path(path).name, path)
+    else:
+        summary.add_row("1", Path(plot_paths[0]).name, plot_paths[0])
+
+    console.print()
+    console.print(summary)
+
+
+@app.command()
+def forecast(
+    file_path: str = typer.Argument(..., help="Path to time series dataset file (CSV or Parquet)"),
+    time_col: str = typer.Option(None, "--time", "-t", help="Time column name (required)"),
+    target_col: str = typer.Option(None, "--target", "-y", help="Target column to forecast (required)"),
+    horizon: int = typer.Option(30, "--horizon", "-h", help="Forecast horizon (periods ahead)"),
+    method: str = typer.Option("prophet", "--method", "-m", help="Forecasting method: prophet, arima, exponential_smoothing"),
+    output: str = typer.Option("./outputs/forecast/", "--output", "-o", help="Output directory for forecast files")
+):
+    """
+    Forecast a time series target column.
+
+    Example:
+        ds-agent forecast sales.csv --time date --target revenue --horizon 90
+        ds-agent forecast stock.csv --time Date --target Close --method arima
+    """
+    from ds_agent.tools.time_series import forecast_time_series
+    import csv
+
+    # detect_seasonality is requested by name; fallback keeps compatibility with current tools module.
+    try:
+        from ds_agent.tools.time_series import detect_seasonality
+    except ImportError:
+        from ds_agent.tools.time_series import detect_seasonality_trends as detect_seasonality
+
+    console.print(Panel.fit(
+        "⏳ Time Series Forecast",
+        style="bold blue"
+    ))
+
+    # Step 1: Validation
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    if not time_col:
+        console.print("[red]✗ Error: --time (-t) is required[/red]")
+        raise typer.Exit(1)
+
+    if not target_col:
+        console.print("[red]✗ Error: --target (-y) is required[/red]")
+        raise typer.Exit(1)
+
+    if horizon <= 0:
+        console.print("[red]✗ Error: --horizon must be a positive integer[/red]")
+        raise typer.Exit(1)
+
+    method_normalized = method.strip().lower()
+    valid_methods = {"prophet", "arima", "exponential_smoothing"}
+    if method_normalized not in valid_methods:
+        console.print("[red]✗ Error: --method must be one of prophet, arima, exponential_smoothing[/red]")
+        raise typer.Exit(1)
+
+    output_dir = Path(output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_csv = output_dir / f"forecast_{Path(file_path).stem}_{target_col}_{method_normalized}.csv"
+
+    console.print(f"\n📊 [bold]Dataset:[/bold] {file_path}")
+    console.print(f"🕒 [bold]Time Column:[/bold] {time_col}")
+    console.print(f"🎯 [bold]Target Column:[/bold] {target_col}")
+    console.print(f"📈 [bold]Method:[/bold] {method_normalized}")
+    console.print(f"🔭 [bold]Horizon:[/bold] {horizon}")
+
+    # Step 2: Seasonality detection
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task_seasonality = progress.add_task("Detecting seasonality...", total=None)
+            seasonality_result = detect_seasonality(file_path, time_col, target_col)
+            progress.update(task_seasonality, completed=True)
+    except Exception as e:
+        seasonality_result = {"status": "error", "message": str(e)}
+
+    if seasonality_result.get("status") == "success":
+        detected_period = seasonality_result.get("detected_period", "unknown")
+        interpretation = seasonality_result.get("interpretation", {})
+        seasonality_label = interpretation.get("seasonality", "unknown")
+        console.print(
+            f"[green]✓ Seasonality detected:[/green] {seasonality_label} (period={detected_period})"
+        )
+    else:
+        console.print(
+            f"[yellow]⚠ Seasonality detection unavailable:[/yellow] {seasonality_result.get('message', 'Unknown issue')}"
+        )
+
+    # Step 3: Forecast generation
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task_forecast = progress.add_task("Generating forecast...", total=None)
+            forecast_result = forecast_time_series(
+                file_path=file_path,
+                time_col=time_col,
+                target_col=target_col,
+                forecast_horizon=horizon,
+                method=method_normalized,
+                output_path=str(output_csv)
+            )
+            progress.update(task_forecast, completed=True)
+    except Exception as e:
+        console.print(f"[red]✗ Forecast failed: {e}[/red]")
+        raise typer.Exit(1)
+
+    if forecast_result.get("status") != "success":
+        console.print(f"[red]✗ Forecast failed: {forecast_result.get('message', 'Unknown error')}[/red]")
+        raise typer.Exit(1)
+
+    forecast_rows = forecast_result.get("forecast", [])
+    if not isinstance(forecast_rows, list) or not forecast_rows:
+        console.print("[yellow]⚠ Forecast completed but returned no rows.[/yellow]")
+        raise typer.Exit(1)
+
+    # Normalize row fields for display and CSV export.
+    normalized_rows = []
+    for row in forecast_rows:
+        date_val = row.get("date") or row.get("ds") or row.get("time")
+        actual_val = row.get("actual") or row.get("y")
+        predicted_val = row.get("predicted") or row.get("yhat") or row.get("value")
+        lower_val = row.get("lower_bound") or row.get("yhat_lower") or row.get("lower_ci")
+        upper_val = row.get("upper_bound") or row.get("yhat_upper") or row.get("upper_ci")
+
+        normalized_rows.append({
+            "date": date_val,
+            "actual": actual_val,
+            "predicted": predicted_val,
+            "lower_bound": lower_val,
+            "upper_bound": upper_val,
+        })
+
+    # Step 4: Forecast results table
+    table = Table(title="📊 Forecast Results")
+    table.add_column("Date", style="cyan")
+    table.add_column("Actual", justify="right")
+    table.add_column("Predicted", justify="right", style="green")
+    table.add_column("Lower Bound", justify="right")
+    table.add_column("Upper Bound", justify="right")
+
+    for row in normalized_rows:
+        actual_display = "-" if row["actual"] is None else f"{float(row['actual']):.4f}"
+        predicted_display = "-" if row["predicted"] is None else f"{float(row['predicted']):.4f}"
+        lower_display = "-" if row["lower_bound"] is None else f"{float(row['lower_bound']):.4f}"
+        upper_display = "-" if row["upper_bound"] is None else f"{float(row['upper_bound']):.4f}"
+
+        table.add_row(
+            str(row["date"]),
+            actual_display,
+            predicted_display,
+            lower_display,
+            upper_display,
+        )
+
+    console.print()
+    console.print(table)
+
+    # Step 5: Save normalized forecast CSV in output directory.
+    with open(output_csv, "w", newline="") as csv_file:
+        writer = csv.DictWriter(
+            csv_file,
+            fieldnames=["date", "actual", "predicted", "lower_bound", "upper_bound"]
+        )
+        writer.writeheader()
+        writer.writerows(normalized_rows)
+
+    console.print(f"\n💾 Forecast CSV saved to: [cyan]{output_csv}[/cyan]")
+
+    # Step 6: Print model accuracy metrics if available.
+    metrics = {}
+    for metric_key in ["mae", "rmse", "mape"]:
+        if metric_key in forecast_result:
+            metrics[metric_key] = forecast_result.get(metric_key)
+
+    nested_metrics = forecast_result.get("metrics")
+    if isinstance(nested_metrics, dict):
+        for metric_key in ["mae", "rmse", "mape"]:
+            if metric_key in nested_metrics:
+                metrics[metric_key] = nested_metrics.get(metric_key)
+
+    if metrics:
+        metrics_table = Table(title="📏 Forecast Accuracy")
+        metrics_table.add_column("Metric", style="cyan")
+        metrics_table.add_column("Value", style="white", justify="right")
+
+        if metrics.get("mae") is not None:
+            metrics_table.add_row("MAE", f"{float(metrics['mae']):.4f}")
+        if metrics.get("rmse") is not None:
+            metrics_table.add_row("RMSE", f"{float(metrics['rmse']):.4f}")
+        if metrics.get("mape") is not None:
+            metrics_table.add_row("MAPE", f"{float(metrics['mape']):.2f}%")
+
+        console.print()
+        console.print(metrics_table)
+    else:
+        console.print("[yellow]ℹ Accuracy metrics (MAE/RMSE/MAPE) were not returned by this model run.[/yellow]")
+
+
+@app.command()
+def nlp(
+    file_path: str = typer.Argument(..., help="Path to dataset file (CSV or Parquet)"),
+    text_col: str = typer.Option(None, "--text", "-t", help="Text column name (required)"),
+    task: str = typer.Option("all", "--task", help="NLP task: all, topics, sentiment, entities, classify"),
+    n_topics: int = typer.Option(5, "--n-topics", help="Number of topics for topic modeling"),
+    output: str = typer.Option("./outputs/nlp/", "--output", "-o", help="Output directory for NLP artifacts")
+):
+    """
+    Run NLP analysis tasks such as sentiment, topics, and entity extraction.
+
+    Example:
+        ds-agent nlp reviews.csv --text review_text --task sentiment
+        ds-agent nlp news.csv --text content --task topics --n-topics 8
+        ds-agent nlp articles.csv --text body
+    """
+    from ds_agent.utils.polars_helpers import load_dataframe
+    from ds_agent.tools.nlp_text_analytics import (
+        analyze_sentiment_advanced as sentiment_analysis,
+        perform_topic_modeling,
+        perform_named_entity_recognition as extract_entities,
+    )
+
+    console.print(Panel.fit(
+        "📝 NLP Text Analytics",
+        style="bold blue"
+    ))
+
+    # Step 1: Validate file and text column.
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    if not text_col:
+        console.print("[red]✗ Error: --text (-t) is required[/red]")
+        raise typer.Exit(1)
+
+    valid_tasks = {"all", "topics", "sentiment", "entities", "classify"}
+    task = task.strip().lower()
+    if task not in valid_tasks:
+        console.print("[red]✗ Error: --task must be one of all, topics, sentiment, entities, classify[/red]")
+        raise typer.Exit(1)
+
+    if n_topics <= 0:
+        console.print("[red]✗ Error: --n-topics must be a positive integer[/red]")
+        raise typer.Exit(1)
+
+    try:
+        df = load_dataframe(file_path)
+    except Exception as e:
+        console.print(f"[red]✗ Error loading dataset: {e}[/red]")
+        raise typer.Exit(1)
+
+    if text_col not in df.columns:
+        console.print(f"[red]✗ Error: Text column '{text_col}' not found in dataset[/red]")
+        raise typer.Exit(1)
+
+    output_dir = Path(output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Step 2: Preview first 5 rows of text column.
+    preview_table = Table(title="🔎 Text Preview (first 5 rows)")
+    preview_table.add_column("Row", style="cyan", width=6)
+    preview_table.add_column(text_col, style="white")
+
+    preview_values = df[text_col].head(5).to_list()
+    for idx, value in enumerate(preview_values, start=1):
+        text_value = "" if value is None else str(value)
+        text_value = text_value.replace("\n", " ").strip()
+        if len(text_value) > 140:
+            text_value = text_value[:137] + "..."
+        preview_table.add_row(str(idx), text_value)
+
+    console.print()
+    console.print(preview_table)
+
+    sentiment_result = None
+    topics_result = None
+    entities_result = None
+    saved_files = []
+
+    # Step 3A: Sentiment analysis
+    if task in {"all", "sentiment"}:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            sentiment_task = progress.add_task("Running sentiment analysis...", total=None)
+            sentiment_result = sentiment_analysis(df, text_col)
+            progress.update(sentiment_task, completed=True)
+
+        sentiment_dist = sentiment_result.get("statistics", {}).get("sentiment_distribution")
+        if not sentiment_dist:
+            sentiments = sentiment_result.get("sentiments", [])
+            labels = [str(item.get("label", "NEUTRAL")).upper() for item in sentiments]
+            total = len(labels)
+            sentiment_dist = {
+                "POSITIVE": sum(1 for label in labels if "POS" in label),
+                "NEGATIVE": sum(1 for label in labels if "NEG" in label),
+                "NEUTRAL": sum(1 for label in labels if "NEU" in label),
+            } if total > 0 else {"POSITIVE": 0, "NEGATIVE": 0, "NEUTRAL": 0}
+
+        total_count = sum(sentiment_dist.values()) if isinstance(sentiment_dist, dict) else 0
+
+        sentiment_table = Table(title="😊 Sentiment Distribution")
+        sentiment_table.add_column("Label", style="cyan")
+        sentiment_table.add_column("Count", style="white", justify="right")
+        sentiment_table.add_column("Percentage", style="green", justify="right")
+
+        for label in ["POSITIVE", "NEGATIVE", "NEUTRAL"]:
+            count = int(sentiment_dist.get(label, 0)) if isinstance(sentiment_dist, dict) else 0
+            pct = (count / total_count * 100) if total_count > 0 else 0.0
+            sentiment_table.add_row(label, str(count), f"{pct:.2f}%")
+
+        console.print()
+        console.print(sentiment_table)
+
+        sentiment_path = output_dir / "sentiment_results.json"
+        with open(sentiment_path, "w") as f:
+            json.dump(sentiment_result, f, indent=2, default=str)
+        saved_files.append(str(sentiment_path))
+
+    # Step 3B: Topic modeling
+    if task in {"all", "topics"}:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            topics_task = progress.add_task("Running topic modeling...", total=None)
+            topics_result = perform_topic_modeling(
+                data=df,
+                text_column=text_col,
+                n_topics=n_topics
+            )
+            progress.update(topics_task, completed=True)
+
+        topics_table = Table(title="🧠 Topic Modeling Results")
+        topics_table.add_column("Topic", style="cyan", width=8)
+        topics_table.add_column("Top 5 Keywords", style="white")
+
+        for topic in topics_result.get("topics", []):
+            topic_id = topic.get("topic_id", "-")
+            words = topic.get("words", [])[:5]
+            topics_table.add_row(str(topic_id), ", ".join(words) if words else "-")
+
+        console.print()
+        console.print(topics_table)
+
+        topics_path = output_dir / "topics_results.json"
+        with open(topics_path, "w") as f:
+            json.dump(topics_result, f, indent=2, default=str)
+        saved_files.append(str(topics_path))
+
+    # Step 3C: Entity extraction
+    if task in {"all", "entities"}:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            entities_task = progress.add_task("Extracting entities...", total=None)
+            entities_result = extract_entities(df, text_col)
+            progress.update(entities_task, completed=True)
+
+        entities_table = Table(title="🏷️ Top Entities by Type")
+        entities_table.add_column("Entity Type", style="cyan")
+        entities_table.add_column("Top 10 Entities", style="white")
+
+        by_type = entities_result.get("by_type", {}) if isinstance(entities_result, dict) else {}
+        for entity_type, details in by_type.items():
+            top_items = details.get("top_entities") if isinstance(details, dict) else None
+            if isinstance(top_items, list) and top_items:
+                top_10 = [
+                    f"{item.get('text', '')} ({item.get('count', 0)})"
+                    for item in top_items[:10]
+                ]
+            else:
+                examples = details.get("examples", []) if isinstance(details, dict) else []
+                top_10 = [str(ex) for ex in examples[:10]]
+
+            entities_table.add_row(entity_type, ", ".join(top_10) if top_10 else "-")
+
+        console.print()
+        console.print(entities_table)
+
+        entities_path = output_dir / "entities_results.json"
+        with open(entities_path, "w") as f:
+            json.dump(entities_result, f, indent=2, default=str)
+        saved_files.append(str(entities_path))
+
+    # Step 4: Save classify placeholder when classify-only requested.
+    if task == "classify":
+        classify_result = {
+            "status": "not_implemented",
+            "message": "Classify task is reserved but no classification routine is currently wired in nlp_text_analytics."
+        }
+        classify_path = output_dir / "classify_results.json"
+        with open(classify_path, "w") as f:
+            json.dump(classify_result, f, indent=2)
+        saved_files.append(str(classify_path))
+        console.print("[yellow]ℹ Classify task placeholder saved (feature not implemented in tools module).[/yellow]")
+
+    # Step 5: Final summary panel
+    summary_lines = [
+        f"Task: {task}",
+        f"Dataset: {file_path}",
+        f"Text column: {text_col}",
+        f"Rows processed: {len(df)}",
+        "Saved files:"
+    ]
+    summary_lines.extend([f"- {path}" for path in saved_files])
+
+    console.print(Panel(
+        "\n".join(summary_lines),
+        title="✅ NLP Analysis Complete",
+        border_style="green"
+    ))
+
+
+@app.command()
+def pipeline(
+    file_path: str = typer.Argument(..., help="Path to dataset file (CSV or Parquet)"),
+    target_col: str = typer.Option(None, "--target", "-y", help="Target column name (required)"),
+    level: str = typer.Option("basic", "--level", "-l", help="Feature engineering level: basic, intermediate, advanced"),
+    task_type: str = typer.Option("auto", "--task-type", help="Task type: auto, classification, regression"),
+    output: str = typer.Option("./outputs/data/pipeline_output.csv", "--output", "-o", help="Output file path")
+):
+    """
+    Run the full automated ML pipeline.
+
+    Example:
+        ds-agent pipeline titanic.csv --target Survived
+        ds-agent pipeline sales.csv --target revenue --level advanced --task-type regression
+    """
+    from ds_agent.tools.auto_pipeline import auto_ml_pipeline
+
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    if not target_col:
+        console.print("[red]✗ Error: --target (-y) is required[/red]")
+        raise typer.Exit(1)
+
+    level = level.strip().lower()
+    valid_levels = {"basic", "intermediate", "advanced"}
+    if level not in valid_levels:
+        console.print("[red]✗ Error: --level must be one of basic, intermediate, advanced[/red]")
+        raise typer.Exit(1)
+
+    task_type = task_type.strip().lower()
+    valid_task_types = {"auto", "classification", "regression"}
+    if task_type not in valid_task_types:
+        console.print("[red]✗ Error: --task-type must be one of auto, classification, regression[/red]")
+        raise typer.Exit(1)
+
+    output_path = str(Path(output))
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+
+    overview_lines = [
+        "1. Type detection",
+        "2. Cleaning",
+        "3. Outliers",
+        "4. Encoding",
+        "5. Feature engineering",
+        "6. Feature selection",
+        "",
+        f"Dataset: {file_path}",
+        f"Target: {target_col}",
+        f"Feature engineering level: {level}",
+        f"Task type: {task_type}",
+    ]
+
+    # Step 1: Pipeline Overview
+    console.print(Panel(
+        "\n".join(overview_lines),
+        title="🔄 Pipeline Overview",
+        border_style="blue"
+    ))
+
+    stage_to_progress = {
+        "Stage 1": 1,
+        "Stage 2": 2,
+        "Stage 3": 3,
+        "Stage 5": 4,
+        "Stage 6": 5,
+        "Stage 7": 6,
+    }
+
+    class _PipelineStream(io.TextIOBase):
+        def __init__(self, progress, task_id):
+            self.progress = progress
+            self.task_id = task_id
+            self.buffer = ""
+            self.max_completed = 0
+
+        def write(self, text):
+            self.buffer += text
+            while "\n" in self.buffer:
+                line, self.buffer = self.buffer.split("\n", 1)
+                line = line.strip()
+                for key, step in stage_to_progress.items():
+                    if key in line and step > self.max_completed:
+                        self.max_completed = step
+                        self.progress.update(self.task_id, completed=step)
+                        break
+            return len(text)
+
+        def flush(self):
+            return None
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            pipeline_task = progress.add_task("Running automated pipeline...", total=6)
+            stream = _PipelineStream(progress, pipeline_task)
+
+            with contextlib.redirect_stdout(stream):
+                result = auto_ml_pipeline(
+                    file_path,
+                    target_col,
+                    task_type,
+                    output_path,
+                    level,
+                )
+
+            progress.update(pipeline_task, completed=6)
+
+    except Exception as e:
+        console.print(f"[red]✗ Pipeline failed: {e}[/red]")
+        raise typer.Exit(1)
+
+    original_shape = result.get("original_shape", {})
+    final_shape = result.get("final_shape", {})
+    original_cols = int(original_shape.get("columns", 0))
+    final_cols = int(final_shape.get("columns", 0))
+    features_added = max(final_cols - original_cols, 0)
+    features_removed = max(original_cols - final_cols, 0)
+    transformations_applied = result.get("transformations_applied", [])
+
+    # Step 4: Comparison table
+    comparison_table = Table(title="📊 Pipeline Comparison", show_header=False)
+    comparison_table.add_column("Metric", style="cyan", width=28)
+    comparison_table.add_column("Value", style="white")
+
+    comparison_table.add_row(
+        "Original Shape",
+        f"{original_shape.get('rows', '-')} rows × {original_shape.get('columns', '-')} cols"
+    )
+    comparison_table.add_row(
+        "Final Shape",
+        f"{final_shape.get('rows', '-')} rows × {final_shape.get('columns', '-')} cols"
+    )
+    comparison_table.add_row("Features Added", str(features_added))
+    comparison_table.add_row("Features Removed", str(features_removed))
+    comparison_table.add_row(
+        "Transformations Applied",
+        str(len(transformations_applied))
+    )
+
+    transformation_names = [t.get("stage", "Unknown") for t in transformations_applied]
+    comparison_table.add_row(
+        "Transformation Stages",
+        ", ".join(transformation_names) if transformation_names else "-"
+    )
+
+    console.print()
+    console.print(comparison_table)
+
+    # Step 5: Top selected features
+    selected_features = result.get("selected_features", [])
+    feature_importance = result.get("feature_importance", {})
+
+    if selected_features:
+        feature_table = Table(title="🏆 Top Selected Features")
+        feature_table.add_column("Rank", style="cyan", width=6)
+        feature_table.add_column("Feature", style="white")
+        feature_table.add_column("Importance", style="green", justify="right")
+
+        if isinstance(feature_importance, dict) and feature_importance:
+            ranked = []
+            for feature in selected_features:
+                score = feature_importance.get(feature)
+                if score is None:
+                    score = feature_importance.get(str(feature))
+                ranked.append((feature, score))
+
+            ranked.sort(key=lambda x: float(x[1]) if x[1] is not None else float("-inf"), reverse=True)
+            top_features = ranked[:10]
+        else:
+            top_features = [(feature, None) for feature in selected_features[:10]]
+
+        for idx, (feature, score) in enumerate(top_features, start=1):
+            score_text = "-" if score is None else f"{float(score):.6f}"
+            feature_table.add_row(str(idx), str(feature), score_text)
+
+        console.print()
+        console.print(feature_table)
+
+    # Step 6: Output file path
+    output_file = result.get("output_path", output_path)
+    console.print(f"\n💾 Pipeline output saved to: [cyan]{output_file}[/cyan]")
+
+
+@app.command()
+def tune(
+    file_path: str = typer.Argument(..., help="Path to pre-processed dataset (CSV or Parquet)"),
+    target_col: str = typer.Option(None, "--target", "-y", help="Target column name (required)"),
+    model_type: str = typer.Option("xgboost", "--model", "-m", help="Model to tune: random_forest, xgboost, lightgbm"),
+    trials: int = typer.Option(30, "--trials", "-n", help="Number of Optuna trials"),
+    task_type: str = typer.Option("auto", "--task-type", help="Task type: auto, classification, regression"),
+    output: str = typer.Option("./outputs/models/", "--output", "-o", help="Output directory or model file path")
+):
+    """
+    Run Bayesian hyperparameter optimization with Optuna.
+
+    Example:
+        ds-agent tune cleaned.csv --target Survived --model xgboost --trials 50
+    """
+    from ds_agent.tools.advanced_training import hyperparameter_tuning
+    from ds_agent.utils.polars_helpers import load_dataframe
+    import ds_agent.tools.advanced_training as advanced_training_module
+    import numpy as np
+    from sklearn.model_selection import cross_val_score, StratifiedKFold, KFold
+    from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor
+    from xgboost import XGBClassifier, XGBRegressor
+
+    if not Path(file_path).exists():
+        console.print(f"[red]✗ Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    if not target_col:
+        console.print("[red]✗ Error: --target (-y) is required[/red]")
+        raise typer.Exit(1)
+
+    model_type = model_type.strip().lower()
+    valid_models = {"random_forest", "xgboost", "lightgbm"}
+    if model_type not in valid_models:
+        console.print("[red]✗ Error: --model must be one of random_forest, xgboost, lightgbm[/red]")
+        raise typer.Exit(1)
+
+    task_type = task_type.strip().lower()
+    valid_task_types = {"auto", "classification", "regression"}
+    if task_type not in valid_task_types:
+        console.print("[red]✗ Error: --task-type must be one of auto, classification, regression[/red]")
+        raise typer.Exit(1)
+
+    if trials <= 0:
+        console.print("[red]✗ Error: --trials (-n) must be a positive integer[/red]")
+        raise typer.Exit(1)
+
+    try:
+        df_for_estimate = load_dataframe(file_path)
+        dataset_rows = len(df_for_estimate)
+    except Exception:
+        dataset_rows = 0
+
+    base_estimated_seconds = int(trials * 10)
+    size_factor = max(1.0, (dataset_rows / 50000.0)) if dataset_rows > 0 else 1.0
+    estimated_seconds = int(base_estimated_seconds * size_factor)
+
+    # Resolve output path: directory or file path.
+    output_path_obj = Path(output)
+    if output_path_obj.suffix.lower() in {".pkl", ".joblib"}:
+        model_output_path = output_path_obj
+        model_output_path.parent.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path_obj.mkdir(parents=True, exist_ok=True)
+        model_output_path = output_path_obj / f"tuned_{model_type}_{Path(file_path).stem}.pkl"
+
+    # Step 1: Upfront warning panel
+    console.print(Panel(
+        f"⚠️  Hyperparameter tuning is compute-intensive.\n"
+        f"Estimated time: {base_estimated_seconds} seconds. Press Ctrl+C to stop early.\n"
+        f"Dataset-size adjusted estimate: {estimated_seconds} seconds.",
+        title="Tuning Warning",
+        border_style="yellow"
+    ))
+
+    baseline_score = None
+
+    def _compute_baseline_score() -> Optional[float]:
+        try:
+            df = load_dataframe(file_path).to_pandas()
+            if target_col not in df.columns:
+                return None
+
+            X = df.drop(columns=[target_col])
+            y = df[target_col]
+            X = X.select_dtypes(include=[np.number]).fillna(0)
+            if X.shape[1] == 0:
+                return None
+
+            inferred_task = task_type
+            if inferred_task == "auto":
+                inferred_task = "classification" if y.nunique() < 20 else "regression"
+
+            if model_type == "random_forest":
+                model = RandomForestClassifier(random_state=42) if inferred_task == "classification" else RandomForestRegressor(random_state=42)
+            elif model_type == "xgboost":
+                model = XGBClassifier(random_state=42, use_label_encoder=False, eval_metric="logloss") if inferred_task == "classification" else XGBRegressor(random_state=42)
+            elif model_type == "lightgbm":
+                from lightgbm import LGBMClassifier, LGBMRegressor
+                model = LGBMClassifier(random_state=42, verbosity=-1) if inferred_task == "classification" else LGBMRegressor(random_state=42, verbosity=-1)
+            else:
+                return None
+
+            if inferred_task == "classification":
+                cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
+                scores = cross_val_score(model, X, y, cv=cv, scoring="accuracy", n_jobs=-1)
+            else:
+                cv = KFold(n_splits=5, shuffle=True, random_state=42)
+                scores = cross_val_score(model, X, y, cv=cv, scoring="neg_root_mean_squared_error", n_jobs=-1)
+
+            return float(scores.mean())
+        except Exception:
+            return None
+
+    baseline_score = _compute_baseline_score()
+
+    trial_counter = {"count": 0}
+    optuna_module = advanced_training_module.optuna
+    original_optimize = optuna_module.study.study.Study.optimize
+
+    def _patched_optimize(self, func, *args, **kwargs):
+        def _trial_callback(study, trial):
+            trial_counter["count"] += 1
+            progress.update(
+                progress_task,
+                completed=min(trial_counter["count"], trials),
+                description=f"Running Optuna trials ({trial_counter['count']} of {trials})..."
+            )
+
+        callbacks = list(kwargs.get("callbacks") or [])
+        callbacks.append(_trial_callback)
+        kwargs["callbacks"] = callbacks
+        kwargs["show_progress_bar"] = False
+        return original_optimize(self, func, *args, **kwargs)
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TextColumn("[progress.percentage]{task.completed:.0f}/{task.total:.0f}"),
+            console=console
+        ) as progress:
+            progress_task = progress.add_task("Running Optuna trials (0 of 0)...", total=trials)
+
+            optuna_module.study.study.Study.optimize = _patched_optimize
+            tuning_result = hyperparameter_tuning(
+                file_path,
+                target_col,
+                model_type,
+                task_type,
+                trials,
+                output_path=str(model_output_path)
+            )
+
+            progress.update(
+                progress_task,
+                completed=trials,
+                description=f"Running Optuna trials ({trial_counter['count']} of {trials})..."
+            )
+    except KeyboardInterrupt:
+        console.print("[yellow]⚠ Tuning stopped by user (Ctrl+C).[/yellow]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]✗ Hyperparameter tuning failed: {e}[/red]")
+        raise typer.Exit(1)
+    finally:
+        optuna_module.study.study.Study.optimize = original_optimize
+
+    if tuning_result.get("status") != "success":
+        console.print(f"[red]✗ Hyperparameter tuning failed: {tuning_result.get('message', 'Unknown error')}[/red]")
+        raise typer.Exit(1)
+
+    best_params = tuning_result.get("best_params", {})
+    best_score = tuning_result.get("best_cv_score")
+
+    improvement_pct = None
+    if baseline_score is not None and best_score is not None and baseline_score != 0:
+        improvement_pct = ((float(best_score) - float(baseline_score)) / abs(float(baseline_score))) * 100.0
+
+    # Step 4: Results table
+    summary_table = Table(title="🎯 Tuning Results", show_header=False)
+    summary_table.add_column("Metric", style="cyan", width=28)
+    summary_table.add_column("Value", style="white")
+
+    summary_table.add_row("Best Parameters", json.dumps(best_params, indent=2) if best_params else "-")
+    summary_table.add_row("Best Score", "-" if best_score is None else f"{float(best_score):.6f}")
+    summary_table.add_row("Baseline Score", "-" if baseline_score is None else f"{float(baseline_score):.6f}")
+    summary_table.add_row(
+        "Improvement Percentage",
+        "-" if improvement_pct is None else f"{improvement_pct:+.2f}%"
+    )
+
+    console.print()
+    console.print(summary_table)
+
+    # Step 5: Saved model path
+    saved_model_path = tuning_result.get("model_path") or str(model_output_path)
+    console.print(f"\n💾 Tuned model saved to: [cyan]{saved_model_path}[/cyan]")
+
+
+@app.command()
+def clean(
+    file_path: str = typer.Argument(..., help="Path to dataset file"),
+    output: str = typer.Option(None, "--output", "-o", help="Output file path"),
+    strategy: str = typer.Option("auto", "--strategy", "-s", help="Cleaning strategy (auto/median/mean/mode/drop)")
+):
+    """
+    Clean dataset (handle missing values and outliers).
+    
+    Example:
+        python cli.py clean data.csv --output cleaned_data.csv
+    """
+    from ds_agent.tools.data_cleaning import clean_missing_values
+    from ds_agent.tools.data_profiling import profile_dataset
+    
+    if output is None:
+        output = f"./outputs/data/cleaned_{Path(file_path).name}"
+    
+    console.print(f"\n🧹 [bold]Cleaning:[/bold] {file_path}\n")
+    
+    # Get columns with missing values
+    profile = profile_dataset(file_path)
+    cols_with_nulls = {
+        col: "auto"
+        for col, info in profile["columns"].items()
+        if info["null_count"] > 0
+    }
+    
+    if not cols_with_nulls:
+        console.print("[green]✓ No missing values found - dataset is clean![/green]")
+        return
+    
+    console.print(f"Found {len(cols_with_nulls)} columns with missing values")
+    
+    # Clean
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}")) as progress:
+        task = progress.add_task("Cleaning dataset...", total=None)
+        result = clean_missing_values(file_path, cols_with_nulls, output)
+        progress.update(task, completed=True)
+    
+    console.print(f"\n[green]✓ Cleaned dataset saved to: {output}[/green]")
+    console.print(f"  Rows: {result['original_rows']} → {result['final_rows']}")
+
+
+@app.command()
+def train(
+    file_path: str = typer.Argument(..., help="Path to prepared dataset"),
+    target: str = typer.Argument(..., help="Target column name"),
+    task_type: str = typer.Option("auto", "--task-type", help="Task type (classification/regression/auto)")
+):
+    """
+    Train baseline models on prepared dataset.
+    
+    Example:
+        python cli.py train cleaned_data.csv Survived --task-type classification
+    """
+    from ds_agent.tools.model_training import train_baseline_models
+    
+    console.print(f"\n🤖 [bold]Training Models[/bold]\n")
+    console.print(f"📊 Dataset: {file_path}")
+    console.print(f"🎯 Target: {target}\n")
+    
+    # Train
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}")) as progress:
+        task = progress.add_task("Training baseline models...", total=None)
+        result = train_baseline_models(file_path, target, task_type)
+        progress.update(task, completed=True)
+    
+    if "error" in result:
+        console.print(f"[red]✗ Error: {result['message']}[/red]")
+        raise typer.Exit(1)
+    
+    # Display results
+    console.print(f"\n[green]✓ Training Complete![/green]\n")
+    console.print(f"Task Type: {result['task_type']}")
+    console.print(f"Features: {result['n_features']}")
+    console.print(f"Samples: {result['n_samples']}\n")
+    
+    # Model comparison table
+    table = Table(title="Model Performance")
+    table.add_column("Model", style="cyan")
+    
+    # Add metric columns based on task type
+    if result["task_type"] == "classification":
+        table.add_column("Accuracy", justify="right")
+        table.add_column("F1 Score", justify="right")
+    else:
+        table.add_column("R² Score", justify="right")
+        table.add_column("RMSE", justify="right")
+    
+    for model_name, model_result in result["models"].items():
+        if "test_metrics" in model_result:
+            metrics = model_result["test_metrics"]
+            if result["task_type"] == "classification":
+                table.add_row(
+                    model_name,
+                    f"{metrics['accuracy']:.4f}",
+                    f"{metrics['f1']:.4f}"
+                )
+            else:
+                table.add_row(
+                    model_name,
+                    f"{metrics['r2']:.4f}",
+                    f"{metrics['rmse']:.4f}"
+                )
+    
+    console.print(table)
+    
+    # Best model
+    console.print(f"\n🏆 [bold]Best Model:[/bold] {result['best_model']['name']}")
+    console.print(f"   Score: {result['best_model']['score']:.4f}")
+    console.print(f"   Path: {result['best_model']['model_path']}")
+
+
+@app.command()
+def cache_stats():
+    """Show cache statistics."""
+    from ds_agent.orchestrator import DataScienceCopilot
+
+    copilot = DataScienceCopilot()
+    stats = copilot.get_cache_stats()
+    
+    table = Table(title="Cache Statistics")
+    table.add_column("Metric", style="cyan")
+    table.add_column("Value", style="white")
+    
+    table.add_row("Total Entries", str(stats["total_entries"]))
+    table.add_row("Valid Entries", str(stats["valid_entries"]))
+    table.add_row("Expired Entries", str(stats["expired_entries"]))
+    table.add_row("Size", f"{stats['size_mb']} MB")
+    
+    console.print()
+    console.print(table)
+
+
+@app.command()
+def clear_cache():
+    """Clear all cached results."""
+    from ds_agent.orchestrator import DataScienceCopilot
+
+    copilot = DataScienceCopilot()
+    copilot.clear_cache()
+    console.print("[green]✓ Cache cleared successfully[/green]")
+
+
+@sessions_app.command("list")
+def sessions_list():
+    """List saved sessions."""
+    from ds_agent.session_store import SessionStore
+
+    store = SessionStore()
+    list_fn = getattr(store, "list_sessions", None)
+    load_fn = getattr(store, "load_session", None) or getattr(store, "load", None)
+
+    if not callable(list_fn):
+        console.print("[red]✗ Session store does not provide list_sessions().[/red]")
+        raise typer.Exit(1)
+
+    sessions = list_fn(limit=10000)
+    if not sessions:
+        console.print("[yellow]No saved sessions found.[/yellow]")
+        return
+
+    table = Table(title="Saved Sessions")
+    table.add_column("session_id", style="cyan")
+    table.add_column("created_at", style="white")
+    table.add_column("last_active", style="white")
+    table.add_column("last_dataset", style="magenta")
+    table.add_column("steps_completed", justify="right", style="green")
+
+    for item in sessions:
+        sid = item.get("session_id", "-")
+        created_at = item.get("created_at", "-")
+        last_active = item.get("last_active", "-")
+
+        last_dataset = "-"
+        steps_completed = 0
+
+        if callable(load_fn):
+            try:
+                session_obj = load_fn(sid)
+                if session_obj is not None:
+                    last_dataset = getattr(session_obj, "last_dataset", None) or "-"
+                    workflow_history = getattr(session_obj, "workflow_history", []) or []
+                    steps_completed = len(workflow_history)
+            except Exception:
+                pass
+
+        table.add_row(
+            str(sid),
+            str(created_at),
+            str(last_active),
+            str(last_dataset),
+            str(steps_completed)
+        )
+
+    console.print()
+    console.print(table)
+
+
+@sessions_app.command("resume")
+def sessions_resume(
+    session_id: str = typer.Argument(..., help="Session ID to resume")
+):
+    """Load a saved session and print its context."""
+    from ds_agent.session_store import SessionStore
+
+    store = SessionStore()
+    load_fn = getattr(store, "load_session", None) or getattr(store, "load", None)
+
+    if not callable(load_fn):
+        console.print("[red]✗ Session store does not provide load_session().[/red]")
+        raise typer.Exit(1)
+
+    session = load_fn(session_id)
+    if session is None:
+        console.print(f"[red]✗ Session not found: {session_id}[/red]")
+        raise typer.Exit(1)
+
+    context_text = ""
+    get_context_summary = getattr(session, "get_context_summary", None)
+    if callable(get_context_summary):
+        context_text = get_context_summary()
+
+    if not context_text:
+        context_lines = [
+            f"Session ID: {getattr(session, 'session_id', session_id)}",
+            f"Created: {getattr(session, 'created_at', '-')}",
+            f"Last Active: {getattr(session, 'last_active', '-')}",
+            f"Last Dataset: {getattr(session, 'last_dataset', '-')}",
+            f"Last Target: {getattr(session, 'last_target_col', '-')}",
+            f"Last Model: {getattr(session, 'last_model', '-')}",
+            f"Steps Completed: {len(getattr(session, 'workflow_history', []) or [])}",
+        ]
+        context_text = "\n".join(context_lines)
+
+    console.print(Panel(
+        context_text,
+        title=f"Session Context: {session_id}",
+        border_style="green"
+    ))
+
+
+@sessions_app.command("delete")
+def sessions_delete(
+    session_id: str = typer.Argument(..., help="Session ID to delete")
+):
+    """Delete one saved session from SQLite."""
+    from ds_agent.session_store import SessionStore
+
+    store = SessionStore()
+    delete_fn = getattr(store, "delete_session", None) or getattr(store, "delete", None)
+
+    if not callable(delete_fn):
+        console.print("[red]✗ Session store does not provide delete_session().[/red]")
+        raise typer.Exit(1)
+
+    deleted = bool(delete_fn(session_id))
+    if deleted:
+        console.print(f"[green]✓ Deleted session: {session_id}[/green]")
+    else:
+        console.print(f"[yellow]Session not found: {session_id}[/yellow]")
+
+
+@sessions_app.command("clear")
+def sessions_clear():
+    """Delete all saved sessions."""
+    from ds_agent.session_store import SessionStore
+
+    store = SessionStore()
+    list_fn = getattr(store, "list_sessions", None)
+    delete_fn = getattr(store, "delete_session", None) or getattr(store, "delete", None)
+
+    if not callable(list_fn):
+        console.print("[red]✗ Session store does not provide list_sessions().[/red]")
+        raise typer.Exit(1)
+    if not callable(delete_fn):
+        console.print("[red]✗ Session store does not provide delete_session().[/red]")
+        raise typer.Exit(1)
+
+    sessions = list_fn(limit=10000)
+    if not sessions:
+        console.print("[yellow]No sessions to clear.[/yellow]")
+        return
+
+    deleted_count = 0
+    for item in sessions:
+        sid = item.get("session_id")
+        if sid and delete_fn(sid):
+            deleted_count += 1
+
+    console.print(f"[green]✓ Cleared {deleted_count} session(s).[/green]")
+
+
+def main():
+    """Console entry point for ds-agent."""
+    app()
+
+
+if __name__ == "__main__":
+    main()