ma-agents 3.4.8 → 3.5.0

package/.opencode/skills/ml-eda/scripts/class_weights_calculator.py

@@ -1,295 +0,0 @@
-#!/usr/bin/env python3
-"""
-class_weights_calculator.py — BMAD DL Lifecycle
-Computes class weights for imbalanced datasets to use in weighted loss functions.
-
-Supports:
-  - Image datasets (class-labeled subdirectory layout)
-  - CSV/TSV tabular datasets
-  - JSON annotation files (COCO or flat dict)
-
-Outputs ready-to-paste Python dict for PyTorch loss functions, plus a
-markdown summary. Works entirely with stdlib (no external deps).
-
-Usage:
-    python3 scripts/class_weights_calculator.py <data_path> [--label-col LABEL] [--output report.md]
-    python3 scripts/class_weights_calculator.py data/images/      # image dir
-    python3 scripts/class_weights_calculator.py data/labels.csv --label-col defective
-    python3 scripts/class_weights_calculator.py data/annotations.json
-
-Exit codes:
-    0 — success
-    2 — error
-"""
-
-from __future__ import annotations
-
-import argparse
-import csv
-import json
-import sys
-from collections import Counter
-from pathlib import Path
-
-IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".tif", ".webp"}
-
-
-def count_image_classes(data_dir: Path) -> dict[str, int]:
-    """Count images per class from class-labeled subdirectories."""
-    counts: dict[str, int] = {}
-    subdirs = [d for d in sorted(data_dir.iterdir()) if d.is_dir()]
-    if not subdirs:
-        raise ValueError(f"No subdirectories found in {data_dir}. "
-                         "Expected class-labeled subdirectory layout: data/class_name/img.jpg")
-    for cls_dir in subdirs:
-        images = [f for f in cls_dir.iterdir() if f.suffix.lower() in IMAGE_EXTENSIONS]
-        if images:
-            counts[cls_dir.name] = len(images)
-    return counts
-
-
-def count_csv_classes(path: Path, label_col: str | None) -> dict[str, int]:
-    """Count class frequencies from a CSV label column."""
-    with path.open(newline="", encoding="utf-8", errors="replace") as f:
-        reader = csv.DictReader(f)
-        rows = list(reader)
-    if not rows:
-        raise ValueError("CSV is empty")
-
-    columns = list(rows[0].keys())
-    if label_col and label_col in columns:
-        target = label_col
-    else:
-        target = next(
-            (c for c in columns if c.lower() in ("label", "class", "target", "y", "category")),
-            None,
-        )
-    if target is None:
-        raise ValueError(
-            f"No label column found. Use --label-col or name your column: "
-            f"label, class, target, y, category"
-        )
-    counter = Counter(row[target].strip() for row in rows if row.get(target, "").strip())
-    return dict(counter)
-
-
-def count_json_classes(path: Path) -> dict[str, int]:
-    """Count class frequencies from JSON annotations (COCO or flat dict)."""
-    data = json.loads(path.read_text(encoding="utf-8"))
-
-    # COCO format
-    if isinstance(data, dict) and "annotations" in data and "categories" in data:
-        categories = {c["id"]: c["name"] for c in data.get("categories", [])}
-        counter: Counter = Counter()
-        for ann in data.get("annotations", []):
-            cat_id = ann.get("category_id")
-            counter[categories.get(cat_id, f"id_{cat_id}")] += 1
-        return dict(counter)
-
-    # Flat dict: {"img.jpg": "class_name"}
-    if isinstance(data, dict):
-        return dict(Counter(str(v) for v in data.values()))
-
-    # List of dicts
-    if isinstance(data, list) and data and isinstance(data[0], dict):
-        label_key = next(
-            (k for k in data[0] if k.lower() in ("label", "class", "category", "target")),
-            None,
-        )
-        if label_key:
-            return dict(Counter(str(item.get(label_key, "unknown")) for item in data))
-
-    raise ValueError("Unrecognized JSON annotation format")
-
-
-def compute_weights(counts: dict[str, int]) -> dict[str, float]:
-    """
-    Compute balanced class weights: weight_i = n_samples / (n_classes * count_i).
-    This is sklearn's 'balanced' strategy, equivalent to:
-        sklearn.utils.class_weight.compute_class_weight('balanced', ...)
-    """
-    n_samples = sum(counts.values())
-    n_classes = len(counts)
-    return {
-        cls: round(n_samples / (n_classes * count), 6)
-        for cls, count in counts.items()
-    }
-
-
-def compute_inverse_freq_weights(counts: dict[str, int]) -> dict[str, float]:
-    """Normalized inverse frequency weights: weight_i = (1/count_i) / sum(1/count_j)."""
-    inv = {cls: 1.0 / count for cls, count in counts.items()}
-    total_inv = sum(inv.values())
-    return {cls: round(v / total_inv, 6) for cls, v in inv.items()}
-
-
-def generate_report(
-    counts: dict[str, int],
-    weights_balanced: dict[str, float],
-    weights_inv: dict[str, float],
-    data_path: Path,
-) -> str:
-    total = sum(counts.values())
-    n_classes = len(counts)
-    sorted_classes = sorted(counts, key=lambda c: -counts[c])
-
-    lines: list[str] = [
-        "# Class Weights Report",
-        f"*Dataset: `{data_path.name}` | {total:,} samples | {n_classes} classes*",
-        "",
-        "---",
-        "",
-        "## A. Class Distribution",
-        "",
-        "| Class | Count | % | Imbalance Ratio |",
-        "| :--- | ---: | ---: | ---: |",
-    ]
-    majority = counts[sorted_classes[0]]
-    for cls in sorted_classes:
-        pct = counts[cls] / total * 100
-        ratio = majority / counts[cls]
-        bar = "█" * int(pct / 5)
-        lines.append(f"| {cls} | {counts[cls]:,} | {pct:.1f}% {bar} | {ratio:.1f}:1 |")
-
-    max_ratio = majority / counts[sorted_classes[-1]]
-    if max_ratio > 10:
-        lines += ["", f"⚠ **Severe imbalance** detected: {max_ratio:.0f}:1 ratio. Weighted loss is strongly recommended."]
-    elif max_ratio > 3:
-        lines += ["", f"⚠ **Moderate imbalance** detected: {max_ratio:.0f}:1 ratio. Consider weighted loss."]
-    else:
-        lines += ["", f"✓ Dataset is relatively balanced ({max_ratio:.1f}:1 ratio)."]
-
-    # Balanced weights
-    sorted_by_cls = sorted(weights_balanced)
-    lines += [
-        "",
-        "---",
-        "",
-        "## B. Balanced Class Weights",
-        "",
-        "*Formula: `n_samples / (n_classes × class_count)` — equivalent to sklearn's `class_weight='balanced'`*",
-        "",
-        "| Class | Count | Weight |",
-        "| :--- | ---: | ---: |",
-    ]
-    for cls in sorted_by_cls:
-        lines.append(f"| {cls} | {counts[cls]:,} | {weights_balanced[cls]:.4f} |")
-
-    # Python code snippets
-    weight_list_balanced = [weights_balanced[c] for c in sorted(weights_balanced)]
-    lines += [
-        "",
-        "### PyTorch Usage",
-        "",
-        "```python",
-        "import torch",
-        "",
-        "# Option 1: As tensor for nn.CrossEntropyLoss",
-        f"class_names = {sorted_by_cls}",
-        f"weights = torch.tensor({[round(weights_balanced[c], 4) for c in sorted_by_cls]}, dtype=torch.float)",
-        "criterion = torch.nn.CrossEntropyLoss(weight=weights.to(device))",
-        "",
-        "# Option 2: As dict (for custom loss or WeightedRandomSampler)",
-        f"class_weight_dict = {dict(zip(sorted_by_cls, [weights_balanced[c] for c in sorted_by_cls]))}",
-        "```",
-        "",
-    ]
-
-    # Inverse freq weights
-    lines += [
-        "---",
-        "",
-        "## C. Inverse Frequency Weights (Normalized)",
-        "",
-        "*Alternative: normalized so weights sum to 1.0*",
-        "",
-        "| Class | Count | Weight |",
-        "| :--- | ---: | ---: |",
-    ]
-    for cls in sorted_by_cls:
-        lines.append(f"| {cls} | {counts[cls]:,} | {weights_inv[cls]:.4f} |")
-
-    lines += [
-        "",
-        "```python",
-        "# Inverse frequency weights tensor",
-        f"weights_inv = torch.tensor({[round(weights_inv[c], 4) for c in sorted_by_cls]}, dtype=torch.float)",
-        "```",
-        "",
-        "---",
-        "",
-        "## D. Recommendations",
-        "",
-    ]
-    if max_ratio > 10:
-        lines += [
-            "1. Use `CrossEntropyLoss(weight=...)` with balanced weights (Section B).",
-            "2. Consider `WeightedRandomSampler` to oversample minority classes in each batch.",
-            "3. Use per-class metrics (F1, precision, recall per class) — not just accuracy.",
-            "4. Consider Focal Loss for severe imbalance (set `gamma=2`).",
-        ]
-    elif max_ratio > 3:
-        lines += [
-            "1. Apply balanced class weights to your loss function (Section B).",
-            "2. Monitor per-class F1 during training.",
-            "3. Consider data augmentation on minority classes.",
-        ]
-    else:
-        lines += [
-            "1. Dataset is balanced — standard `CrossEntropyLoss` without weights is acceptable.",
-            "2. Monitor per-class metrics to catch any per-class degradation.",
-        ]
-
-    lines += [
-        "",
-        "---",
-        "*Generated by `class_weights_calculator.py` — BMAD DL Lifecycle*",
-    ]
-    return "\n".join(lines)
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Compute class weights for imbalanced datasets")
-    parser.add_argument("data_path", type=Path)
-    parser.add_argument("--label-col", type=str, default=None)
-    parser.add_argument("--output", type=Path, default=None)
-    args = parser.parse_args()
-
-    if not args.data_path.exists():
-        print(f"Error: Path not found: {args.data_path}", file=sys.stderr)
-        return 2
-
-    try:
-        if args.data_path.is_dir():
-            counts = count_image_classes(args.data_path)
-        elif args.data_path.suffix.lower() in (".csv", ".tsv"):
-            counts = count_csv_classes(args.data_path, args.label_col)
-        elif args.data_path.suffix.lower() == ".json":
-            counts = count_json_classes(args.data_path)
-        else:
-            print(f"Error: Unsupported format. Use image dir, CSV, or JSON.", file=sys.stderr)
-            return 2
-    except Exception as e:
-        print(f"Error: {e}", file=sys.stderr)
-        return 2
-
-    if not counts:
-        print("Error: No class data found.", file=sys.stderr)
-        return 2
-
-    weights_balanced = compute_weights(counts)
-    weights_inv = compute_inverse_freq_weights(counts)
-
-    report = generate_report(counts, weights_balanced, weights_inv, args.data_path)
-
-    output = args.output or args.data_path.parent / f"{args.data_path.stem}_class_weights.md"
-    output.write_text(report, encoding="utf-8")
-
-    print(f"✓ Class weight report: {output}")
-    print(f"  Classes: {list(counts.keys())}")
-    print(f"  Balanced weights: {weights_balanced}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/.opencode/skills/ml-eda/scripts/clustering_explorer.py

@@ -1,383 +0,0 @@
-#!/usr/bin/env python3
-"""
-clustering_explorer.py — BMAD DL Lifecycle
-(Inspired by K-Dense claude-scientific-skills/scikit-learn/clustering_analysis.py)
-
-Unsupervised cluster analysis for EDA on unlabeled or partially-labeled datasets.
-Useful during TSK-001 to discover natural groupings before annotation or labeling.
-
-Runs K-Means, Agglomerative, and DBSCAN; scores with Silhouette, Calinski-Harabasz,
-and Davies-Bouldin indices; optionally saves a PCA 2D scatter plot.
-
-Usage:
-    python3 scripts/clustering_explorer.py <data_csv> [--k N] [--find-k] [--output report.md] [--plot clusters.png]
-    python3 scripts/clustering_explorer.py data/features.csv --find-k --plot clusters.png
-
-Exit codes:
-    0 — success
-    2 — error
-"""
-
-from __future__ import annotations
-
-import argparse
-import csv
-import sys
-import warnings
-from dataclasses import dataclass, field
-from pathlib import Path
-
-warnings.filterwarnings("ignore")
-
-try:
-    import numpy as np
-    HAS_NUMPY = True
-except ImportError:
-    HAS_NUMPY = False
-
-try:
-    from sklearn.preprocessing import StandardScaler
-    from sklearn.decomposition import PCA
-    from sklearn.cluster import KMeans, DBSCAN, AgglomerativeClustering
-    from sklearn.metrics import silhouette_score, calinski_harabasz_score, davies_bouldin_score
-    from sklearn.impute import SimpleImputer
-    HAS_SKLEARN = True
-except ImportError:
-    HAS_SKLEARN = False
-
-try:
-    import matplotlib
-    matplotlib.use("Agg")
-    import matplotlib.pyplot as plt
-    import matplotlib.cm as cm
-    HAS_MPL = True
-except ImportError:
-    HAS_MPL = False
-
-
-# ── Data structures ────────────────────────────────────────────────────────────
-
-@dataclass
-class ClusterResult:
-    name: str
-    n_clusters: int
-    silhouette: float | None
-    calinski: float | None
-    davies: float | None
-    labels: "list | None" = None
-    n_noise: int = 0
-    notes: str = ""
-
-
-# ── Data loading ───────────────────────────────────────────────────────────────
-
-def load_numeric_csv(path: Path) -> tuple["np.ndarray", list[str]]:
-    """Load CSV, drop non-numeric and label columns, return (X, feature_names)."""
-    with path.open(newline="", encoding="utf-8", errors="replace") as f:
-        reader = csv.DictReader(f)
-        rows = list(reader)
-    if not rows:
-        raise ValueError("CSV is empty")
-
-    columns = list(rows[0].keys())
-    # Exclude likely label columns
-    label_cols = {c for c in columns if c.lower() in ("label", "class", "target", "y", "category")}
-
-    numeric_cols: list[str] = []
-    for col in columns:
-        if col in label_cols:
-            continue
-        try:
-            [float(row[col]) for row in rows if row.get(col, "").strip()]
-            numeric_cols.append(col)
-        except ValueError:
-            pass
-
-    if not numeric_cols:
-        raise ValueError("No numeric feature columns found")
-
-    X = np.array([
-        [float(row[c]) if row.get(c, "").strip() else float("nan") for c in numeric_cols]
-        for row in rows
-    ], dtype=float)
-    return X, numeric_cols
-
-
-def preprocess(X: "np.ndarray") -> "np.ndarray":
-    imputer = SimpleImputer(strategy="median")
-    scaler = StandardScaler()
-    return scaler.fit_transform(imputer.fit_transform(X))
-
-
-# ── Optimal K search ───────────────────────────────────────────────────────────
-
-def find_optimal_k(X: "np.ndarray", k_range: range) -> tuple[int, list[float], list[float]]:
-    inertias, silhouettes = [], []
-    for k in k_range:
-        km = KMeans(n_clusters=k, random_state=42, n_init=10)
-        labels = km.fit_predict(X)
-        inertias.append(km.inertia_)
-        silhouettes.append(silhouette_score(X, labels))
-    best_k = list(k_range)[int(np.argmax(silhouettes))]
-    return best_k, inertias, silhouettes
-
-
-# ── Clustering ─────────────────────────────────────────────────────────────────
-
-def run_clustering(X: "np.ndarray", n_clusters: int) -> list[ClusterResult]:
-    results: list[ClusterResult] = []
-
-    algorithms = {
-        "K-Means": KMeans(n_clusters=n_clusters, random_state=42, n_init=10),
-        "Agglomerative": AgglomerativeClustering(n_clusters=n_clusters, linkage="ward"),
-    }
-    for name, algo in algorithms.items():
-        labels = algo.fit_predict(X)
-        try:
-            sil = silhouette_score(X, labels)
-            cal = calinski_harabasz_score(X, labels)
-            dav = davies_bouldin_score(X, labels)
-        except Exception:
-            sil = cal = dav = None
-        results.append(ClusterResult(
-            name=name, n_clusters=n_clusters,
-            silhouette=sil, calinski=cal, davies=dav, labels=labels.tolist(),
-        ))
-
-    # DBSCAN (auto eps via 5th-NN heuristic)
-    try:
-        from sklearn.neighbors import NearestNeighbors
-        nn = NearestNeighbors(n_neighbors=5)
-        nn.fit(X)
-        distances, _ = nn.kneighbors(X)
-        eps = float(np.percentile(distances[:, -1], 90))
-    except Exception:
-        eps = 0.5
-
-    dbscan = DBSCAN(eps=eps, min_samples=5)
-    db_labels = dbscan.fit_predict(X)
-    unique_clusters = set(db_labels) - {-1}
-    n_noise = int((db_labels == -1).sum())
-
-    if len(unique_clusters) > 1:
-        mask = db_labels != -1
-        try:
-            sil = silhouette_score(X[mask], db_labels[mask])
-            cal = calinski_harabasz_score(X[mask], db_labels[mask])
-            dav = davies_bouldin_score(X[mask], db_labels[mask])
-        except Exception:
-            sil = cal = dav = None
-        results.append(ClusterResult(
-            name="DBSCAN", n_clusters=len(unique_clusters),
-            silhouette=sil, calinski=cal, davies=dav,
-            labels=db_labels.tolist(), n_noise=n_noise,
-        ))
-    else:
-        results.append(ClusterResult(
-            name="DBSCAN", n_clusters=len(unique_clusters),
-            silhouette=None, calinski=None, davies=None,
-            labels=db_labels.tolist(), n_noise=n_noise,
-            notes=f"Only {len(unique_clusters)} cluster(s) found — try adjusting eps",
-        ))
-    return results
-
-
-# ── Visualization ──────────────────────────────────────────────────────────────
-
-def save_cluster_plot(X: "np.ndarray", results: list[ClusterResult], output_path: Path) -> None:
-    pca = PCA(n_components=2)
-    X_2d = pca.fit_transform(X)
-    var = pca.explained_variance_ratio_
-
-    n_plots = len(results)
-    ncols = min(3, n_plots)
-    nrows = (n_plots + ncols - 1) // ncols
-
-    fig, axes = plt.subplots(nrows, ncols, figsize=(5 * ncols, 4 * nrows), squeeze=False)
-    axes = axes.flatten()
-
-    for idx, r in enumerate(results):
-        ax = axes[idx]
-        labels = np.array(r.labels)
-        unique = sorted(set(labels))
-        colors = cm.tab10(np.linspace(0, 1, max(len(unique), 1)))
-
-        for i, lbl in enumerate(unique):
-            mask = labels == lbl
-            color = "gray" if lbl == -1 else colors[i % len(colors)]
-            marker = "x" if lbl == -1 else "o"
-            label = "Noise" if lbl == -1 else f"C{lbl}"
-            ax.scatter(X_2d[mask, 0], X_2d[mask, 1], c=[color], marker=marker,
-                       alpha=0.6, s=20, label=label)
-
-        title = f"{r.name} (k={r.n_clusters})"
-        if r.silhouette is not None:
-            title += f"\nSil={r.silhouette:.3f}"
-        ax.set_title(title, fontsize=9)
-        ax.set_xlabel(f"PC1 ({var[0]:.1%})", fontsize=8)
-        ax.set_ylabel(f"PC2 ({var[1]:.1%})", fontsize=8)
-        ax.tick_params(labelsize=7)
-        if r.n_clusters <= 8:
-            ax.legend(fontsize=7, markerscale=1.2)
-
-    for idx in range(len(results), len(axes)):
-        axes[idx].axis("off")
-
-    plt.suptitle("Cluster Analysis — PCA Projection", fontsize=11, y=1.01)
-    plt.tight_layout()
-    plt.savefig(output_path, dpi=150, bbox_inches="tight")
-    plt.close()
-
-
-# ── Report generation ──────────────────────────────────────────────────────────
-
-def generate_report(
-    results: list[ClusterResult],
-    data_path: Path,
-    n_samples: int,
-    n_features: int,
-    k_range: range | None,
-    inertias: list[float] | None,
-    silhouettes_per_k: list[float] | None,
-    optimal_k: int | None,
-    plot_path: Path | None,
-) -> str:
-    lines: list[str] = [
-        "# Clustering Explorer Report",
-        f"*Dataset: `{data_path.name}` | {n_samples} samples | {n_features} features*",
-        "",
-        "---",
-        "",
-    ]
-
-    if k_range and optimal_k:
-        lines += [
-            "## A. Optimal K Analysis (K-Means Silhouette)",
-            "",
-            "| K | Inertia | Silhouette Score |",
-            "| ---: | ---: | ---: |",
-        ]
-        for k, inert, sil in zip(k_range, inertias or [], silhouettes_per_k or []):
-            marker = " ←" if k == optimal_k else ""
-            lines.append(f"| {k} | {inert:.1f} | {sil:.4f}{marker} |")
-        lines += ["", f"**Recommended K = {optimal_k}** (highest silhouette score)", "", "---", ""]
-
-    lines += [
-        "## B. Algorithm Comparison",
-        "",
-        "| Algorithm | Clusters | Silhouette ↑ | Calinski-Harabasz ↑ | Davies-Bouldin ↓ | Notes |",
-        "| :--- | ---: | ---: | ---: | ---: | :--- |",
-    ]
-    for r in results:
-        sil = f"{r.silhouette:.4f}" if r.silhouette is not None else "N/A"
-        cal = f"{r.calinski:.1f}" if r.calinski is not None else "N/A"
-        dav = f"{r.davies:.4f}" if r.davies is not None else "N/A"
-        noise = f" ({r.n_noise} noise pts)" if r.n_noise else ""
-        lines.append(f"| {r.name} | {r.n_clusters}{noise} | {sil} | {cal} | {dav} | {r.notes} |")
-
-    # Best algorithm by silhouette
-    scored = [r for r in results if r.silhouette is not None]
-    if scored:
-        best = max(scored, key=lambda r: r.silhouette)
-        lines += ["", f"**Best algorithm by silhouette: {best.name}** (score: {best.silhouette:.4f})", ""]
-
-    if plot_path:
-        lines += [
-            "---",
-            "",
-            "## C. Cluster Visualization",
-            "",
-            f"![Cluster scatter]({plot_path.name})",
-            "",
-            "*2D PCA projection. Colors indicate cluster assignments.*",
-            "",
-        ]
-
-    lines += [
-        "---",
-        "",
-        "## D. Interpretation Guide",
-        "",
-        "| Metric | Good Range | Meaning |",
-        "| :--- | :--- | :--- |",
-        "| Silhouette Score | 0.5 – 1.0 | Points are well-separated from other clusters |",
-        "| Calinski-Harabasz | Higher = better | Dense, well-separated clusters |",
-        "| Davies-Bouldin | 0.0 – 1.0 | Low = compact, well-separated clusters |",
-        "",
-        "**Next steps:**",
-        "1. Use the best cluster assignments as pseudo-labels for semi-supervised training.",
-        "2. Investigate outlier/noise points (DBSCAN noise) — these may be rare defects or data errors.",
-        "3. If clusters align with known classes, your feature space is discriminative — good sign for DL.",
-        "",
-        "---",
-        "*Generated by `clustering_explorer.py` — BMAD DL Lifecycle (TSK-001)*",
-    ]
-    return "\n".join(lines)
-
-
-# ── Main ───────────────────────────────────────────────────────────────────────
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Unsupervised clustering explorer for BMAD DL")
-    parser.add_argument("data_csv", type=Path)
-    parser.add_argument("--k", type=int, default=3, help="Number of clusters (default: 3)")
-    parser.add_argument("--find-k", action="store_true", help="Search for optimal K (2–10)")
-    parser.add_argument("--k-max", type=int, default=10)
-    parser.add_argument("--output", type=Path, default=None)
-    parser.add_argument("--plot", type=Path, default=None, help="Save cluster plot PNG")
-    args = parser.parse_args()
-
-    if not HAS_SKLEARN or not HAS_NUMPY:
-        print("Error: scikit-learn and numpy required. Run: pip install scikit-learn numpy",
-              file=sys.stderr)
-        return 2
-    if not args.data_csv.exists():
-        print(f"Error: File not found: {args.data_csv}", file=sys.stderr)
-        return 2
-
-    try:
-        X_raw, feature_names = load_numeric_csv(args.data_csv)
-    except Exception as e:
-        print(f"Error loading CSV: {e}", file=sys.stderr)
-        return 2
-
-    X = preprocess(X_raw)
-    n_samples, n_features = X.shape
-    print(f"Dataset: {n_samples} samples, {n_features} features")
-
-    # Find optimal K
-    k_range = inertias = silhouettes_k = optimal_k = None
-    n_clusters = args.k
-    if args.find_k:
-        k_max = min(args.k_max, n_samples - 1)
-        k_range = range(2, k_max + 1)
-        print(f"Searching optimal K in range 2–{k_max}...")
-        optimal_k, inertias, silhouettes_k = find_optimal_k(X, k_range)
-        n_clusters = optimal_k
-        print(f"Optimal K = {n_clusters}")
-
-    print(f"Running clustering with k={n_clusters}...")
-    results = run_clustering(X, n_clusters)
-
-    # Plot
-    plot_path: Path | None = None
-    if args.plot:
-        if HAS_MPL:
-            save_cluster_plot(X, results, args.plot)
-            plot_path = args.plot
-            print(f"✓ Cluster plot: {plot_path}")
-        else:
-            print("⚠ matplotlib not available — skipping plot")
-
-    report = generate_report(
-        results, args.data_csv, n_samples, n_features,
-        k_range, inertias, silhouettes_k, optimal_k, plot_path,
-    )
-    output = args.output or args.data_csv.parent / f"{args.data_csv.stem}_clustering_report.md"
-    output.write_text(report, encoding="utf-8")
-    print(f"✓ Report: {output}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())