data-advisor 0.1.0__py3-none-any.whl

data_advisor/__init__.py

@@ -0,0 +1,38 @@
+"""
+data_advisor - Production-grade diagnostic advisor and code generator for data science examinations.
+"""
+
+from data_advisor.advisor import DataAdvisor, data_advisor
+from data_advisor.codegen import CodeGenerator
+from data_advisor.rules import Recommendation, RuleEngine
+from data_advisor.scanner import DataScanner, load_dataset
+from data_advisor.search import (
+    CodeSearchEngine,
+    get_file,
+    list_files,
+    read_file,
+    run_file,
+    search,
+    view_file,
+)
+from data_advisor.visualizer import VisualizationAdvisor
+
+__version__ = "0.1.0"
+__all__ = [
+    "data_advisor",
+    "DataAdvisor",
+    "DataScanner",
+    "RuleEngine",
+    "CodeGenerator",
+    "VisualizationAdvisor",
+    "Recommendation",
+    "CodeSearchEngine",
+    "search",
+    "get_file",
+    "read_file",
+    "view_file",
+    "run_file",
+    "list_files",
+    "load_dataset",
+    "__version__",
+]

data_advisor/__main__.py

@@ -0,0 +1,9 @@
+"""
+__main__.py - Entry point when running data_advisor as a module: python -m data_advisor
+"""
+
+import sys
+from data_advisor.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

data_advisor/advisor.py

@@ -0,0 +1,436 @@
+"""
+advisor.py - The primary DataAdvisor interface class.
+
+Orchestrates scanning, rule evaluation, interactive terminal reporting,
+and automated script generation.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import pandas as pd
+
+from data_advisor.codegen import CodeGenerator
+from data_advisor.rules import Recommendation, RuleEngine
+from data_advisor.scanner import DataScanner, load_dataset
+
+
+class DataAdvisor:
+    """
+    High-level facade for autonomous dataset inspection, diagnostics,
+    statistical hypothesis testing, and code generation.
+
+    Parameters
+    ----------
+    data : Union[str, Path, pd.DataFrame]
+        A pandas DataFrame or path to a dataset file (CSV, TSV, Excel, Parquet).
+    target : Optional[str], default=None
+        Name of the target / dependent variable column. If None, DataAdvisor
+        attempts auto-detection based on common naming patterns.
+    id_cols : Optional[List[str]], default=None
+        Optional list of explicit identifier columns to exclude from modeling.
+
+    Examples
+    --------
+    >>> from data_advisor import DataAdvisor
+    >>> advisor = DataAdvisor("customer_churn.csv", target="churn")
+    >>> results = advisor.scan()
+    >>> advisor.report()
+    >>> advisor.generate_script("run_analysis.py")
+    """
+
+    def __init__(
+        self,
+        data: Union[str, Path, pd.DataFrame],
+        target: Optional[str] = None,
+        id_cols: Optional[List[str]] = None,
+    ) -> None:
+        self.data_source_str = str(data) if isinstance(data, (str, Path)) else "dataset.csv"
+        self.df: pd.DataFrame = load_dataset(data)
+        self.target: Optional[str] = target
+        self.id_cols: List[str] = list(id_cols or [])
+
+        # Internal components
+        self._scanner = DataScanner(self.df, target=self.target, id_cols=self.id_cols)
+        self._scan_cache: Optional[Dict[str, Any]] = None
+        self._recommendations_cache: Optional[List[Recommendation]] = None
+
+    # -------------------------------------------------------------------------
+    # 1. Scan Method
+    # -------------------------------------------------------------------------
+    def scan(self) -> Dict[str, Any]:
+        """
+        Execute profiling and statistical audits.
+
+        Returns
+        -------
+        Dict[str, Any]
+            A comprehensive dictionary containing metrics for overview,
+            missing values, data types, distributions, categoricals,
+            target analysis, hypothesis tests, and recommendations.
+        """
+        if self._scan_cache is None:
+            results = self._scanner.scan()
+            rule_engine = RuleEngine(results)
+            recs = rule_engine.generate_all_recommendations()
+
+            # Attach recommendations into scan dictionary
+            results["recommendations"] = [r.to_dict() for r in recs]
+            self._scan_cache = results
+            self._recommendations_cache = recs
+
+        return self._scan_cache
+
+    # -------------------------------------------------------------------------
+    # 2. Recommendations & Step Access
+    # -------------------------------------------------------------------------
+    def get_recommendations(self) -> List[Dict[str, Any]]:
+        """Return the prioritized list of diagnostic recommendations."""
+        scan_res = self.scan()
+        return scan_res.get("recommendations", [])
+
+    def get_code_block(self, step: str) -> str:
+        """
+        Retrieve executable code for a specific analysis stage:
+        'cleaning', 'transformations', 'encoding', 'hypothesis_tests', or 'modeling'.
+        """
+        scan_res = self.scan()
+        generator = CodeGenerator(scan_res, data_source_str=self.data_source_str)
+
+        step_map = {
+            "cleaning": generator.generate_cleaning_code,
+            "transformations": generator.generate_transformations_code,
+            "encoding": generator.generate_encoding_code,
+            "hypothesis_tests": generator.generate_hypothesis_testing_code,
+            "tests": generator.generate_hypothesis_testing_code,
+            "modeling": generator.generate_modeling_code,
+        }
+
+        func = step_map.get(step.lower())
+        if not func:
+            valid_keys = list(step_map.keys())
+            raise ValueError(f"Invalid step '{step}'. Choose from: {valid_keys}")
+
+        return func()
+
+    # -------------------------------------------------------------------------
+    # 3. Code Generation
+    # -------------------------------------------------------------------------
+    def generate_script(self, filename: Optional[Union[str, Path]] = None) -> str:
+        """
+        Produce a complete, self-contained, executable Python script tailored
+        to the audited dataset.
+
+        Parameters
+        ----------
+        filename : Optional[Union[str, Path]], default=None
+            If provided, saves the generated script to this file path.
+
+        Returns
+        -------
+        str
+            The complete Python script string.
+        """
+        scan_res = self.scan()
+        generator = CodeGenerator(scan_res, data_source_str=self.data_source_str)
+        script_code = generator.generate_full_script()
+
+        if filename:
+            file_path = Path(filename)
+            file_path.write_text(script_code, encoding="utf-8")
+            print(f"\n[+] Production script successfully exported to: {file_path.resolve()}\n")
+
+        return script_code
+
+    # -------------------------------------------------------------------------
+    # 4. Local Code Search
+    # -------------------------------------------------------------------------
+    @staticmethod
+    def search(
+        key: str,
+        folder: Optional[Union[str, Path, List[Union[str, Path]]]] = None,
+        max_results: int = 3,
+        print_output: bool = True,
+    ) -> str:
+        """
+        Search local code files and code banks for matching snippets and implementations.
+
+        Parameters
+        ----------
+        key : str
+            Search keyword, e.g. 'wokwi', 'linear regression', 'dht22', 'coap server'.
+        folder : Optional[Union[str, Path, List[Union[str, Path]]]], default=None
+            Folder path to search. If None, auto-discovers 'code_bank', 'snippets',
+            'examples', or current directory.
+        max_results : int, default=3
+            Maximum number of matching code files to return.
+        print_output : bool, default=True
+            Whether to print formatted code to the console.
+
+        Returns
+        -------
+        str
+            The formatted code text response.
+        """
+        from data_advisor.search import search as search_fn
+        return search_fn(key=key, folder=folder, max_results=max_results, print_output=print_output)
+
+    @staticmethod
+    def get_file(
+        query: Union[str, int],
+        folder: Optional[Union[str, Path, List[Union[str, Path]]]] = None,
+        print_output: bool = True,
+        line_numbers: bool = False,
+    ) -> str:
+        """
+        Retrieve and display the COMPLETE raw file content by question number, filename, or keyword.
+        """
+        from data_advisor.search import get_file as get_file_fn
+        return get_file_fn(query=query, folder=folder, print_output=print_output, line_numbers=line_numbers)
+
+    @staticmethod
+    def read_file(
+        query: Union[str, int],
+        folder: Optional[Union[str, Path, List[Union[str, Path]]]] = None,
+    ) -> str:
+        """Return the COMPLETE raw file content as a string without printing."""
+        from data_advisor.search import read_file as read_file_fn
+        return read_file_fn(query=query, folder=folder)
+
+    @staticmethod
+    def view_file(
+        query: Union[str, int],
+        folder: Optional[Union[str, Path, List[Union[str, Path]]]] = None,
+        line_numbers: bool = False,
+    ) -> str:
+        """Display the complete file in the console with metadata header."""
+        from data_advisor.search import view_file as view_file_fn
+        return view_file_fn(query=query, folder=folder, line_numbers=line_numbers)
+
+    @staticmethod
+    def run_file(
+        query: Union[str, int],
+        folder: Optional[Union[str, Path, List[Union[str, Path]]]] = None,
+        args: Optional[List[str]] = None,
+        timeout: Optional[int] = None,
+    ) -> int:
+        """Execute a Python file directly by question number or filename."""
+        from data_advisor.search import run_file as run_file_fn
+        return run_file_fn(query=query, folder=folder, args=args, timeout=timeout)
+
+    @staticmethod
+    def list_files(
+        folder: Optional[Union[str, Path, List[Union[str, Path]]]] = None,
+        print_output: bool = True,
+    ) -> List[Path]:
+        """List all indexed code snippets with a 1-line summary."""
+        from data_advisor.search import list_files as list_files_fn
+        return list_files_fn(folder=folder, print_output=print_output)
+
+    # -------------------------------------------------------------------------
+    # 5. CLI / Terminal Reporting Engine
+    # -------------------------------------------------------------------------
+    def report(self) -> None:
+        """
+        Print an executive, structured diagnostic report directly to the terminal
+        with rich visual formatting and actionable guidance.
+        """
+        data = self.scan()
+        overview = data["overview"]
+        missing = data["missing_values"]
+        dtypes = data["data_types"]
+        distributions = data["distributions"]
+        categoricals = data["categoricals"]
+        target = data["target"]
+        hypothesis_tests = data["hypothesis_tests"]
+        recommendations = data["recommendations"]
+
+        divider = "=" * 80
+        thin_div = "-" * 80
+
+        print("\n" + divider)
+        print("  DATA ADVISOR - EXAM & PRODUCTION DATASET DIAGNOSTIC REPORT")
+        print(divider)
+
+        # ---------------- Section 1: Overview ----------------
+        print("\n[+] SECTION 1: DATASET ARCHITECTURE & HEALTH")
+        print(thin_div)
+        print(f"  * Dimensions       : {overview['n_rows']} rows x {overview['n_cols']} columns")
+        print(f"  * Memory Footprint : {overview['memory_mb']} MB")
+        dup_flag = "[WARNING]" if overview["duplicate_rows"] > 0 else "[OK]"
+        print(f"  * Duplicated Rows  : {overview['duplicate_rows']} ({overview['duplicate_pct']}%)  --> {dup_flag}")
+
+        dtypes_str = ", ".join([f"{k}: {v}" for k, v in overview["dtypes_summary"].items()])
+        print(f"  * Dtypes Breakdown : {dtypes_str}")
+
+        # ---------------- Section 2: Missing Values & Anomalies ----------------
+        print("\n[+] SECTION 2: DATA INTEGRITY & TYPE MISMATCH AUDIT")
+        print(thin_div)
+
+        null_cols = [(c, info) for c, info in missing.items() if info["null_count"] > 0]
+        if null_cols:
+            print(f"  {'Column':<25} | {'Null Count':<10} | {'Null %':<8} | {'Strategy'}")
+            print(f"  {'-'*25}-|-{'-'*10}-|-{'-'*8}-|-{'-'*28}")
+            for col, info in null_cols:
+                pct = info["null_pct"]
+                strat = "Drop Column" if pct >= 60 else ("Median/Mean" if info["is_numeric"] else "Mode/Missing")
+                print(f"  {col:<25} | {info['null_count']:<10} | {pct:<7.1f}% | {strat}")
+        else:
+            print("  * Zero missing values detected across all columns. [OK]")
+
+        if dtypes.get("potential_dates"):
+            print(f"  * Potential Date Strings Flagged : {dtypes['potential_dates']}")
+        if dtypes.get("potential_ids"):
+            print(f"  * Unique Identifiers / IDs Flagged: {dtypes['potential_ids']}")
+        if dtypes.get("constant_columns"):
+            print(f"  * Zero-Variance Constant Columns : {dtypes['constant_columns']} [CRITICAL - Drop]")
+        if dtypes.get("low_card_numerics"):
+            low_cards = [f"{item['column']} ({item['unique_count']} vals)" for item in dtypes["low_card_numerics"]]
+            print(f"  * Discrete Categorical Numerics  : {low_cards}")
+
+        # ---------------- Section 3: Distributions & Outliers ----------------
+        if distributions:
+            print("\n[+] SECTION 3: NUMERIC DISTRIBUTIONS & OUTLIER ANOMALIES")
+            print(thin_div)
+            print(f"  {'Column':<20} | {'Skewness':<8} | {'Kurtosis':<8} | {'IQR Outliers':<15} | {'Z>3 Outliers':<12} | {'Transform'}")
+            print(f"  {'-'*20}-|-{'-'*8}-|-{'-'*8}-|-{'-'*15}-|-{'-'*12}-|-{'-'*12}")
+            for col, dist in list(distributions.items())[:10]:
+                skew = dist["skewness"]
+                kurt = dist["kurtosis"]
+                iqr_out = f"{dist['iqr_outliers']} ({dist['iqr_outlier_pct']}%)"
+                z_out = f"{dist['z_outliers']} ({dist['z_outlier_pct']}%)"
+
+                trans = "None"
+                if skew > 1.2:
+                    trans = "log1p" if dist.get("is_non_negative", True) else "Yeo-Johnson"
+                elif skew < -1.2:
+                    trans = "Yeo-Johnson"
+                elif dist["iqr_outlier_pct"] > 5.0:
+                    trans = "IQR Clip"
+
+                print(f"  {col:<20} | {skew:<8.2f} | {kurt:<8.2f} | {iqr_out:<15} | {z_out:<12} | {trans}")
+
+        # ---------------- Section 4: Categorical Processing ----------------
+        if categoricals:
+            print("\n[+] SECTION 4: CATEGORICAL ENCODING STRATEGY")
+            print(thin_div)
+            print(f"  {'Column':<22} | {'Levels':<7} | {'Top Category':<18} | {'Recommended Encoding'}")
+            print(f"  {'-'*22}-|-{'-'*7}-|-{'-'*18}-|-{'-'*25}")
+            for col, cat in list(categoricals.items())[:10]:
+                card = cat["cardinality"]
+                top_v = f"{cat['top_value']} ({cat['top_value_pct']}%)"
+                rec_enc = "Binary (0/1)" if card == 2 else ("One-Hot (drop_first)" if card <= 10 else "Frequency / Target")
+                print(f"  {col:<22} | {card:<7} | {top_v:<18} | {rec_enc}")
+
+        # ---------------- Section 5: Hypothesis Testing ----------------
+        if hypothesis_tests:
+            print("\n[+] SECTION 5: STATISTICAL HYPOTHESIS TESTING RESULTS")
+            print(thin_div)
+            for idx, test in enumerate(hypothesis_tests[:6], 1):
+                f1, f2 = test["feature_1"], test["feature_2"]
+                sig = "[SIGNIFICANT]" if test["is_significant"] else "[NOT SIGNIFICANT]"
+                p_str = f"{test['p_value']:.2e}" if test["p_value"] < 0.001 else f"{test['p_value']:.4f}"
+                print(f"  ({idx}) {test['test_type']} : {f1} vs {f2}  --> {sig}")
+                print(f"      Statistic: {test['statistic']} | p-value: {p_str}")
+                print(f"      Interpretation: {test['conclusion']}")
+
+        # ---------------- Section 6: Target & Modeling Strategy ----------------
+        if target:
+            print("\n[+] SECTION 6: TARGET VARIABLE & MODEL SELECTION")
+            print(thin_div)
+            t_col = target["target_column"]
+            p_type = target["problem_type"]
+            print(f"  * Target Column  : '{t_col}'")
+            print(f"  * Problem Type   : {p_type.upper()}")
+
+            if p_type == "classification":
+                imb_flag = "[CRITICAL IMBALANCE]" if target.get("is_imbalanced") else "[BALANCED]"
+                print(f"  * Classes        : {target['n_classes']} levels")
+                print(f"  * Class Balance  : Ratio 1:{target.get('imbalance_ratio', 1.0):.1f} (Minority: {target.get('minority_percentage', 50)}%) --> {imb_flag}")
+                print("  * Models Baseline: LogisticRegression(class_weight='balanced') -> RandomForestClassifier")
+                print("  * Primary Metrics: F1-Score (macro/weighted), PR-AUC, Confusion Matrix")
+            else:
+                print(f"  * Target Range   : [{target['min']} to {target['max']}] (Mean: {target['mean']}, Std: {target['std']})")
+                print("  * Models Baseline: LinearRegression -> Ridge(alpha=1.0) -> RandomForestRegressor")
+                print("  * Primary Metrics: RMSE, MAE, R² Score")
+
+        # ---------------- Section 7: Prioritized Action Plan ----------------
+        print("\n[+] SECTION 7: PRIORITIZED ACTION PLAN")
+        print(thin_div)
+        for idx, rec in enumerate(recommendations[:8], 1):
+            badge = f"[{rec.get('severity')}]"
+            col_target = f" on '{rec.get('column')}'" if rec.get('column') else ""
+            print(f"  {idx}. {badge:<14} {rec.get('action')}{col_target}")
+            print(f"     Why: {rec.get('rationale')}")
+
+        print(divider + "\n")
+
+
+def data_advisor(
+    data: Union[str, Path, pd.DataFrame],
+    target: Optional[str] = None,
+    output_script: Optional[Union[str, Path]] = None,
+    id_cols: Optional[List[str]] = None,
+    print_report: bool = True,
+    print_code: bool = True,
+    return_script: bool = False,
+) -> Union[DataAdvisor, str]:
+    """
+    Given a CSV file (or DataFrame), diagnoses what all analysis should be done
+    and immediately outputs the complete executable Python code to do that analysis.
+
+    Parameters
+    ----------
+    data : Union[str, Path, pd.DataFrame]
+        A CSV file path (e.g. "dataset.csv") or an existing pandas DataFrame.
+    target : Optional[str], default=None
+        Target/dependent variable column name (if known). If None, auto-detected.
+    output_script : Optional[Union[str, Path]], default=None
+        Optional file path to save the generated Python script (e.g. "solution.py").
+    id_cols : Optional[List[str]], default=None
+        Optional list of identifier columns to exclude from modeling.
+    print_report : bool, default=True
+        Whether to print the structured diagnostic report (what all analysis to do).
+    print_code : bool, default=True
+        Whether to print the complete executable Python code to do that analysis.
+    return_script : bool, default=False
+        If True, returns the generated script string. Otherwise returns the DataAdvisor instance.
+
+    Returns
+    -------
+    Union[DataAdvisor, str]
+        The DataAdvisor instance (or the script string if return_script=True).
+
+    Examples
+    --------
+    >>> from data_advisor import data_advisor
+    >>> data_advisor("exam_dataset.csv")
+    >>> data_advisor("exam_dataset.csv", target="churn", output_script="solution.py")
+    """
+    advisor = DataAdvisor(data=data, target=target, id_cols=id_cols)
+
+    # 1. Output what all analysis should be done (Diagnostic Report)
+    if print_report:
+        advisor.report()
+
+    # 2. Generate the complete executable code to do that analysis
+    script_code = advisor.generate_script(filename=output_script)
+
+    # 3. Print the code to the console
+    if print_code:
+        divider = "=" * 80
+        print("\n" + divider)
+        print("  DATA ADVISOR - EXECUTABLE PYTHON CODE FOR ALL RECOMMENDED ANALYSES")
+        print("  Copy-paste and run this complete pipeline in your Jupyter Notebook or script:")
+        print(divider + "\n")
+        print(script_code)
+        print("\n" + divider + "\n")
+
+    if return_script:
+        return script_code
+
+    return advisor
+

data_advisor/cli.py

@@ -0,0 +1,160 @@
+"""
+cli.py - Command-line interface for DataAdvisor.
+Allows instant dataset audits, script generation, and local code search directly from the terminal.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from data_advisor.advisor import DataAdvisor
+from data_advisor.search import search
+
+
+def parse_args(args: Optional[List[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="data-advisor",
+        description="DataAdvisor: Automated dataset auditor, exam-ready code generator, and local code snippet search.",
+    )
+    parser.add_argument(
+        "dataset",
+        type=str,
+        nargs="?",
+        default=None,
+        help="Path to dataset file (CSV, TSV, Excel, Parquet). Optional if using --search.",
+    )
+    parser.add_argument(
+        "-s", "--search",
+        type=str,
+        default=None,
+        help="Search query to find code from local code files (e.g. 'wokwi', 'linear regression').",
+    )
+    parser.add_argument(
+        "-g", "--get",
+        type=str,
+        default=None,
+        help="Retrieve and display the COMPLETE raw file content by question or name (e.g. 'q1', 24, 'question_01.py').",
+    )
+    parser.add_argument(
+        "-r", "--run",
+        type=str,
+        default=None,
+        help="Execute a script directly from the code bank by question or name (e.g. 'q24', '14').",
+    )
+    parser.add_argument(
+        "-l", "--list",
+        action="store_true",
+        help="List all indexed code files in the code bank.",
+    )
+    parser.add_argument(
+        "-n", "--line-numbers",
+        action="store_true",
+        help="Show line numbers when viewing files with --get.",
+    )
+    parser.add_argument(
+        "--folder",
+        type=str,
+        default=None,
+        help="Custom folder to search code files within (default: ./code_bank or ./snippets).",
+    )
+    parser.add_argument(
+        "-t", "--target",
+        type=str,
+        default=None,
+        help="Target / response variable column name.",
+    )
+    parser.add_argument(
+        "--id-cols",
+        type=str,
+        nargs="*",
+        default=None,
+        help="Column names representing IDs/keys to exclude from modeling.",
+    )
+    parser.add_argument(
+        "-c", "--code",
+        action="store_true",
+        help="Print the complete executable Python code pipeline to the console.",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        type=str,
+        default=None,
+        help="Output file path to save the generated Python script.",
+    )
+    parser.add_argument(
+        "--no-report",
+        action="store_true",
+        help="Do not print terminal diagnostic report.",
+    )
+    return parser.parse_args(args)
+
+
+def main(args: Optional[List[str]] = None) -> int:
+    parsed = parse_args(args)
+
+    # 1. Handle code bank retrieval / execution modes
+    if parsed.get is not None:
+        from data_advisor.search import get_file
+        get_file(query=parsed.get, folder=parsed.folder, print_output=True, line_numbers=parsed.line_numbers)
+        return 0
+
+    if parsed.run is not None:
+        from data_advisor.search import run_file
+        return run_file(query=parsed.run, folder=parsed.folder)
+
+    if parsed.list:
+        from data_advisor.search import list_files
+        list_files(folder=parsed.folder, print_output=True)
+        return 0
+
+    if parsed.search is not None:
+        search(key=parsed.search, folder=parsed.folder, print_output=True)
+        return 0
+
+    # 2. Handle dataset auditing mode
+    if not parsed.dataset:
+        print("[!] Error: Please provide a dataset file path, or use '--get <q>', '--search <key>', or '--run <q>'.")
+        print("    Example: data-advisor --get q1             # Display complete Question 1 code")
+        print("    Example: data-advisor --run q24            # Run Question 24 directly")
+        print("    Example: data-advisor --search 'linear regression'")
+        print("    Example: data-advisor dataset.csv --target churn")
+        print("    Example: data-advisor dataset.csv --target churn")
+        print("    Example: data-advisor dataset.csv --code")
+        print("    Example: data-advisor --search 'linear regression'")
+        return 1
+
+    dataset_path = Path(parsed.dataset)
+    if not dataset_path.exists():
+        print(f"[!] Error: File not found: {dataset_path}", file=sys.stderr)
+        return 1
+
+    try:
+        from data_advisor.advisor import data_advisor
+
+        # When --code is specified, print_code is True; otherwise, if output is specified, save it.
+        data_advisor(
+            data=dataset_path,
+            target=parsed.target,
+            output_script=parsed.output,
+            id_cols=parsed.id_cols,
+            print_report=not parsed.no_report,
+            print_code=parsed.code,
+        )
+
+        if not parsed.output and not parsed.code:
+            print("[*] To view the complete executable Python code, run with `--code` / `-c`.")
+            print("[*] To export to a Python file, run with `--output run_analysis.py` / `-o run_analysis.py`.")
+
+        return 0
+    except Exception as exc:
+        print(f"[!] Execution failed: {exc}", file=sys.stderr)
+        import traceback
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())