claude-turing 4.1.0 → 4.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "turing",
-  "version": "4.1.0",
-  "description": "Autonomous ML research harness — the autoresearch loop as a formal protocol. 66 commands, 2 specialized agents, collaboration (onboard + share + review), research communication (cite + present + changelog), experiment archaeology (trend + flashback + archive + annotate + search + template + replay), model surgery (prune + quantize + merge + surgery), feature & training intelligence, model debugging, pre-training intelligence, meta-intelligence, scaling & efficiency, model composition, deep analysis, experiment orchestration, literature + paper, model export, profiling, checkpoints, experiment intelligence, statistical rigor, tree-search, cost-performance, model cards, hypothesis database, novelty guard, anti-cheating, taste-leverage loop. Inspired by Karpathy's autoresearch and the scientific method itself.",
+  "version": "4.2.0",
+  "description": "Autonomous ML research harness — the autoresearch loop as a formal protocol. 69 commands, 2 specialized agents, what-if analysis (whatif + counterfactual + simulate), collaboration (onboard + share + review), research communication (cite + present + changelog), experiment archaeology (trend + flashback + archive + annotate + search + template + replay), model surgery (prune + quantize + merge + surgery), feature & training intelligence, model debugging, pre-training intelligence, meta-intelligence, scaling & efficiency, model composition, deep analysis, experiment orchestration, literature + paper, model export, profiling, checkpoints, experiment intelligence, statistical rigor, tree-search, cost-performance, model cards, hypothesis database, novelty guard, anti-cheating, taste-leverage loop. Inspired by Karpathy's autoresearch and the scientific method itself.",
   "author": {
     "name": "pragnition"
   },

package/README.md

@@ -377,6 +377,9 @@ The index (`hypotheses.yaml`) is the lightweight queue. The detail files (`hypot
 | `/turing:onboard [--audience]` | Project onboarding — walkthrough for new collaborators |
 | `/turing:share <exp-ids...>` | Experiment packaging — portable archive with manifest |
 | `/turing:review [--venue]` | Peer review simulation — weaknesses, fix commands, score |
+| `/turing:whatif "<question>"` | What-if analysis — answer hypotheticals from existing experiment data |
+| `/turing:counterfactual <exp-id>` | Counterfactual explanations — minimum input change to flip a prediction |
+| `/turing:simulate [--configs]` | Experiment outcome prediction — pre-filter configs, save budget |
 
 And for fully hands-off operation:
 
@@ -561,11 +564,11 @@ Each project gets independent config, data, experiments, models, and agent memor
 
 ## Architecture of Turing Itself
 
-66 commands, 2 agents, 10 config files, 85 template scripts, model registry, artifact contract, cost-performance frontier, model cards, tree-search exploration, statistical rigor, experiment intelligence, performance profiling, smart checkpoints, production model export, literature integration, paper section drafting, experiment orchestration (queue + retry + fork), deep analysis (diff + watch + regress), model composition (ensemble + stitch + warm), scaling & efficiency (scale + budget + distill), meta-intelligence (transfer + audit), pre-training intelligence (sanity + baseline + leak), model debugging (xray + sensitivity + calibrate), feature & training intelligence (feature + curriculum), model surgery (prune + quantize + merge + surgery), experiment archaeology (trend + flashback + archive + annotate + search + template + replay), research communication (cite + present + changelog), collaboration (onboard + share + review), 16 ADRs. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full codemap.
+69 commands, 2 agents, 10 config files, 88 template scripts, model registry, artifact contract, cost-performance frontier, model cards, tree-search exploration, statistical rigor, experiment intelligence, performance profiling, smart checkpoints, production model export, literature integration, paper section drafting, experiment orchestration (queue + retry + fork), deep analysis (diff + watch + regress), model composition (ensemble + stitch + warm), scaling & efficiency (scale + budget + distill), meta-intelligence (transfer + audit), pre-training intelligence (sanity + baseline + leak), model debugging (xray + sensitivity + calibrate), feature & training intelligence (feature + curriculum), model surgery (prune + quantize + merge + surgery), experiment archaeology (trend + flashback + archive + annotate + search + template + replay), research communication (cite + present + changelog), collaboration (onboard + share + review), what-if analysis (whatif + counterfactual + simulate), 16 ADRs. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full codemap.
 
 ```
 turing/
-├── commands/              62 skill files (core + taste-leverage + reporting + exploration + statistical rigor + experiment intelligence + performance + deployment + research workflow + orchestration + deep analysis + model composition + scaling & efficiency + meta-intelligence + pre-training intelligence + model debugging + feature & training intelligence + model surgery + experiment archaeology + research communication)
+├── commands/              65 skill files (core + taste-leverage + reporting + exploration + statistical rigor + experiment intelligence + performance + deployment + research workflow + orchestration + deep analysis + model composition + scaling & efficiency + meta-intelligence + pre-training intelligence + model debugging + feature & training intelligence + model surgery + experiment archaeology + research communication + what-if analysis)
 ├── agents/                2 agents (researcher: read/write, evaluator: read-only)
 ├── config/                8 files (lifecycle, taxonomy, archetypes, novelty aliases)
 ├── templates/             Scaffolded into user projects by /turing:init

package/commands/counterfactual.md

@@ -0,0 +1,27 @@
+---
+name: counterfactual
+description: Input-level counterfactual explanations — find the smallest input change to flip a prediction.
+disable-model-invocation: true
+argument-hint: "<exp-id> --sample <index> [--target <class>]"
+allowed-tools: Read, Bash(*), Grep, Glob
+---
+
+What would need to change to flip this prediction? Minimum-change counterfactual for individual predictions.
+
+## Steps
+1. `source .venv/bin/activate`
+2. `python scripts/counterfactual_explanation.py $ARGUMENTS`
+3. **Saved:** `experiments/counterfactuals/`
+
+## Methods
+- **Greedy perturbation:** change one feature at a time, find minimum flip
+- **Prototype-based:** find nearest training sample from target class
+- Both methods run and the best (smallest distance) is selected
+
+## Examples
+```
+/turing:counterfactual exp-042 --sample 1247
+/turing:counterfactual exp-042 --sample 1247 --target 0
+/turing:counterfactual exp-042 --batch-misclassified
+/turing:counterfactual exp-042 --sample 500 --json
+```

package/commands/simulate.md

@@ -0,0 +1,28 @@
+---
+name: simulate
+description: Experiment outcome prediction — predict which configs will beat the current best before running them.
+disable-model-invocation: true
+argument-hint: "[--configs configs.yaml] [--top-k 5] [--threshold 0.001]"
+allowed-tools: Read, Bash(*), Grep, Glob
+---
+
+Predict outcomes before spending compute. Ranks proposed configs and recommends which to run vs skip.
+
+## Steps
+1. `source .venv/bin/activate`
+2. `python scripts/experiment_simulator.py $ARGUMENTS`
+3. **Saved:** `experiments/simulations/`
+
+## How it works
+- Builds a surrogate model from experiment history (weighted k-NN)
+- Predicts metric for each proposed config
+- Applies novelty penalty for configs far from training distribution
+- Ranks and filters: only recommend configs predicted to improve
+
+## Examples
+```
+/turing:simulate --configs sweep_configs.yaml
+/turing:simulate --configs candidates.yaml --top-k 3
+/turing:simulate --configs proposals.yaml --threshold 0.005
+/turing:simulate --configs sweep.yaml --json
+```

package/commands/turing.md

@@ -75,6 +75,9 @@ You are the Turing ML research router. Detect the user's intent and route to the
 | "search", "find experiment", "query experiments", "which experiments" | `/turing:search` | Query |
 | "template", "recipe", "save config", "reusable config", "starting point" | `/turing:template` | Manage |
 | "replay", "re-run", "revisit", "retry old", "would it work now" | `/turing:replay` | Validate |
+| "what if", "what-if", "hypothetical", "estimate impact", "would it help" | `/turing:whatif` | Analyze |
+| "counterfactual", "flip prediction", "why this prediction", "minimum change", "explanation" | `/turing:counterfactual` | Explain |
+| "simulate", "predict outcome", "pre-filter", "which configs will work", "forecast" | `/turing:simulate` | Predict |
 
 ## Sub-commands
 
@@ -146,6 +149,9 @@ You are the Turing ML research router. Detect the user's intent and route to the
 | `/turing:onboard [--audience]` | Project onboarding: full walkthrough for new collaborators | (inline) |
 | `/turing:share <exp-ids...>` | Experiment packaging: portable archive with manifest and README | (inline) |
 | `/turing:review [--venue]` | Peer review simulation: weaknesses, questions, fix commands, score | (inline) |
+| `/turing:whatif "<question>"` | What-if analysis: route hypotheticals to existing estimators (scaling, ablation, sensitivity, ensemble, pruning) | (inline) |
+| `/turing:counterfactual <exp-id> --sample <index>` | Input-level counterfactual explanations: minimum input change to flip a prediction | (inline) |
+| `/turing:simulate [--configs] [--top-k]` | Experiment outcome prediction: pre-filter configs using surrogate model, save budget | (inline) |
 
 ## Proactive Detection
 

package/commands/whatif.md

@@ -0,0 +1,31 @@
+---
+name: whatif
+description: What-if analysis — answer hypotheticals from existing experiment data without running new experiments.
+disable-model-invocation: true
+argument-hint: "\"<question>\" [--json]"
+allowed-tools: Read, Bash(*), Grep, Glob
+---
+
+Answer "what if?" questions using existing experiment data. Routes to the right estimator automatically.
+
+## Steps
+1. `source .venv/bin/activate`
+2. `python scripts/whatif_engine.py $ARGUMENTS`
+3. **Saved:** `experiments/whatif/`
+
+## Supported question types
+- **Data scaling:** "what if I had 2x more data" → scaling law extrapolation
+- **Ablation:** "what if I removed class 3" → ablation study data
+- **Pipeline stitch:** "what if I combined exp-031 with exp-042" → stitch estimation
+- **Hyperparameters:** "what if learning_rate was 0.01" → sensitivity interpolation
+- **Ensemble:** "what if I ensembled the top models" → correlation analysis
+- **Pruning:** "what if I pruned to 50% sparsity" → pruning sweep interpolation
+- **Budget:** "what if I spent my budget on X vs Y" → budget allocation
+
+## Examples
+```
+/turing:whatif "what if I had 2x more data"
+/turing:whatif "what if I removed class 3"
+/turing:whatif "what if I combined exp-031 with exp-042"
+/turing:whatif "what if learning_rate was 0.01" --json
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-turing",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "type": "module",
   "description": "Autonomous ML research harness for Claude Code. The autoresearch loop as a formal protocol — iteratively trains, evaluates, and improves ML models with structured experiment tracking, convergence detection, immutable evaluation infrastructure, and safety guardrails.",
   "bin": {

package/src/install.js

@@ -36,6 +36,7 @@ const SUB_COMMANDS = [
   "trend", "flashback", "archive", "annotate", "search", "template", "replay",
   "cite", "present", "changelog",
   "onboard", "share", "review",
+  "whatif", "counterfactual", "simulate",
 ];
 
 export async function install(opts = {}) {

package/src/verify.js

@@ -80,6 +80,9 @@ const EXPECTED_COMMANDS = [
   "onboard/SKILL.md",
   "share/SKILL.md",
   "review/SKILL.md",
+  "whatif/SKILL.md",
+  "counterfactual/SKILL.md",
+  "simulate/SKILL.md",
 ];
 
 const EXPECTED_AGENTS = ["ml-researcher.md", "ml-evaluator.md"];

package/templates/scripts/counterfactual_explanation.py

@@ -0,0 +1,485 @@
+#!/usr/bin/env python3
+"""Input-level counterfactual explanations for the autoresearch pipeline.
+
+For a given prediction, finds the smallest input change that would flip
+the outcome. "This sample was classified as X — what's the minimum change
+to make it Y?" Useful for debugging predictions and regulatory explanations.
+
+Usage:
+    python scripts/counterfactual_explanation.py exp-042 --sample 1247
+    python scripts/counterfactual_explanation.py exp-042 --sample 1247 --target 0
+    python scripts/counterfactual_explanation.py exp-042 --batch-misclassified
+    python scripts/counterfactual_explanation.py --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+import yaml
+
+from scripts.turing_io import load_config, load_experiments
+
+DEFAULT_LOG_PATH = "experiments/log.jsonl"
+DEFAULT_MAX_ITERATIONS = 100
+DEFAULT_DISTANCE_METRIC = "normalized_l2"
+
+
+# --- Feature Perturbation ---
+
+
+def greedy_perturbation(
+    sample: dict[str, float],
+    predict_fn,
+    target_class: int | str,
+    feature_names: list[str],
+    feature_ranges: dict[str, tuple[float, float]],
+    max_iterations: int = DEFAULT_MAX_ITERATIONS,
+    categorical_features: list[str] | None = None,
+) -> dict:
+    """Find counterfactual by greedily changing one feature at a time.
+
+    Args:
+        sample: Original sample as {feature_name: value}.
+        predict_fn: Function(sample_dict) -> (predicted_class, confidence).
+        target_class: Desired target class.
+        feature_names: Ordered list of feature names.
+        feature_ranges: {feature: (min, max)} from training data.
+        max_iterations: Maximum perturbation attempts.
+        categorical_features: Features that are categorical (discrete changes).
+
+    Returns:
+        Counterfactual result dict.
+    """
+    if categorical_features is None:
+        categorical_features = []
+
+    current = dict(sample)
+    original_pred, original_conf = predict_fn(sample)
+
+    if str(original_pred) == str(target_class):
+        return {
+            "status": "already_target",
+            "message": f"Sample is already predicted as {target_class}",
+        }
+
+    best_cf = None
+    best_distance = float("inf")
+    changes = []
+
+    for iteration in range(max_iterations):
+        improved = False
+
+        for feat in feature_names:
+            if feat in categorical_features:
+                candidates = _categorical_candidates(feat, current[feat], feature_ranges.get(feat))
+            else:
+                candidates = _numeric_candidates(
+                    current[feat],
+                    feature_ranges.get(feat, (0, 1)),
+                    n_steps=5,
+                )
+
+            for candidate_val in candidates:
+                trial = dict(current)
+                trial[feat] = candidate_val
+                pred, conf = predict_fn(trial)
+
+                if str(pred) == str(target_class):
+                    dist = _compute_distance(sample, trial, feature_ranges)
+                    if dist < best_distance:
+                        best_distance = dist
+                        best_cf = dict(trial)
+                        changes = _compute_changes(sample, trial, feature_names)
+                        improved = True
+
+        if best_cf is not None and not improved:
+            break
+
+    if best_cf is None:
+        return {
+            "status": "not_found",
+            "message": f"Could not find counterfactual within {max_iterations} iterations",
+            "original_prediction": original_pred,
+            "original_confidence": float(original_conf),
+        }
+
+    cf_pred, cf_conf = predict_fn(best_cf)
+
+    return {
+        "status": "found",
+        "original_prediction": original_pred,
+        "original_confidence": float(original_conf),
+        "counterfactual_prediction": cf_pred,
+        "counterfactual_confidence": float(cf_conf),
+        "distance": round(float(best_distance), 4),
+        "n_changes": len(changes),
+        "changes": changes,
+        "counterfactual_sample": best_cf,
+    }
+
+
+def _numeric_candidates(current: float, value_range: tuple[float, float], n_steps: int = 5) -> list[float]:
+    """Generate candidate values for a numeric feature."""
+    low, high = value_range
+    step = (high - low) / max(n_steps, 1)
+    candidates = []
+    for i in range(n_steps + 1):
+        val = low + i * step
+        if val != current:
+            candidates.append(val)
+    return candidates
+
+
+def _categorical_candidates(
+    feature: str,
+    current_value,
+    value_range: tuple | list | None,
+) -> list:
+    """Generate candidate values for a categorical feature."""
+    if value_range is None:
+        return []
+    if isinstance(value_range, (tuple, list)):
+        return [v for v in value_range if v != current_value]
+    return []
+
+
+def _compute_distance(
+    original: dict[str, float],
+    counterfactual: dict[str, float],
+    feature_ranges: dict[str, tuple[float, float]],
+) -> float:
+    """Compute normalized L2 distance between original and counterfactual."""
+    total = 0.0
+    for feat in original:
+        orig_val = original[feat]
+        cf_val = counterfactual.get(feat, orig_val)
+        feat_range = feature_ranges.get(feat, (0, 1))
+
+        if isinstance(orig_val, str) or (isinstance(feat_range, (tuple, list)) and len(feat_range) > 2):
+            # Categorical: 1 if changed, 0 if same
+            total += 0.0 if orig_val == cf_val else 1.0
+        else:
+            low, high = feat_range[0], feat_range[1]
+            span = high - low if high != low else 1
+            normalized_diff = (cf_val - orig_val) / span
+            total += normalized_diff ** 2
+    return float(np.sqrt(total))
+
+
+def _compute_changes(
+    original: dict[str, float],
+    counterfactual: dict[str, float],
+    feature_names: list[str],
+) -> list[dict]:
+    """Compute the list of changed features."""
+    changes = []
+    for feat in feature_names:
+        orig = original.get(feat)
+        cf = counterfactual.get(feat)
+        if orig != cf:
+            change = {
+                "feature": feat,
+                "original": orig,
+                "counterfactual": cf,
+            }
+            if isinstance(orig, (int, float)) and isinstance(cf, (int, float)):
+                change["delta"] = round(cf - orig, 6)
+            else:
+                change["delta"] = "category_change"
+            changes.append(change)
+    return changes
+
+
+# --- Prototype-Based Search ---
+
+
+def prototype_counterfactual(
+    sample: dict[str, float],
+    training_data: list[dict[str, float]],
+    training_labels: list,
+    target_class: int | str,
+    feature_names: list[str],
+    feature_ranges: dict[str, tuple[float, float]],
+) -> dict:
+    """Find the nearest training sample from the target class.
+
+    Args:
+        sample: Original sample.
+        training_data: List of training samples as dicts.
+        training_labels: Corresponding labels.
+        target_class: Desired target class.
+        feature_names: Feature names.
+        feature_ranges: {feature: (min, max)}.
+
+    Returns:
+        Nearest prototype counterfactual result.
+    """
+    target_indices = [i for i, label in enumerate(training_labels) if str(label) == str(target_class)]
+
+    if not target_indices:
+        return {
+            "status": "not_found",
+            "message": f"No training samples found for class {target_class}",
+        }
+
+    best_dist = float("inf")
+    best_idx = -1
+
+    for idx in target_indices:
+        dist = _compute_distance(sample, training_data[idx], feature_ranges)
+        if dist < best_dist:
+            best_dist = dist
+            best_idx = idx
+
+    if best_idx < 0:
+        return {"status": "not_found", "message": "No valid prototype found"}
+
+    prototype = training_data[best_idx]
+    changes = _compute_changes(sample, prototype, feature_names)
+
+    return {
+        "status": "found",
+        "method": "prototype",
+        "prototype_index": best_idx,
+        "distance": round(float(best_dist), 4),
+        "n_changes": len(changes),
+        "changes": changes,
+        "counterfactual_sample": prototype,
+    }
+
+
+# --- Full Pipeline ---
+
+
+def counterfactual_analysis(
+    exp_id: str,
+    sample_index: int | None = None,
+    sample_data: dict[str, float] | None = None,
+    target_class: int | str | None = None,
+    predict_fn=None,
+    training_data: list[dict] | None = None,
+    training_labels: list | None = None,
+    feature_names: list[str] | None = None,
+    feature_ranges: dict[str, tuple[float, float]] | None = None,
+    categorical_features: list[str] | None = None,
+    batch_misclassified: bool = False,
+    config_path: str = "config.yaml",
+    log_path: str = DEFAULT_LOG_PATH,
+) -> dict:
+    """Run counterfactual analysis.
+
+    Args:
+        exp_id: Experiment ID to analyze.
+        sample_index: Index of the sample to explain.
+        sample_data: Direct sample data (alternative to index).
+        target_class: Desired counterfactual class.
+        predict_fn: Prediction function (sample_dict) -> (class, confidence).
+        training_data: Training data for prototype search.
+        training_labels: Training labels for prototype search.
+        feature_names: Feature names.
+        feature_ranges: Feature value ranges.
+        categorical_features: Categorical feature names.
+        batch_misclassified: If True, generate for all misclassified samples.
+        config_path: Path to config.yaml.
+        log_path: Path to experiment log.
+
+    Returns:
+        Counterfactual analysis report.
+    """
+    config = load_config(config_path)
+
+    if sample_data is None and sample_index is None and not batch_misclassified:
+        return {"error": "Provide --sample <index> or --batch-misclassified"}
+
+    if predict_fn is None:
+        return {
+            "error": "No prediction function available. "
+                     "Load the model from the experiment first.",
+            "suggestion": f"Run `/turing:counterfactual {exp_id} --sample <index>` "
+                          "from the experiment directory with train.py available.",
+        }
+
+    if feature_names is None:
+        return {"error": "Feature names not available. Provide feature_names."}
+
+    if feature_ranges is None:
+        feature_ranges = {}
+
+    results = []
+
+    if batch_misclassified and training_data and training_labels:
+        for i, (data, label) in enumerate(zip(training_data, training_labels)):
+            pred, conf = predict_fn(data)
+            if str(pred) != str(label):
+                cf = greedy_perturbation(
+                    data, predict_fn, label, feature_names,
+                    feature_ranges, categorical_features=categorical_features,
+                )
+                cf["sample_index"] = i
+                cf["true_label"] = label
+                results.append(cf)
+    elif sample_data is not None:
+        if target_class is None:
+            pred, _ = predict_fn(sample_data)
+            # Flip to opposite for binary
+            target_class = 0 if pred == 1 else 1
+
+        # Try greedy perturbation
+        cf_greedy = greedy_perturbation(
+            sample_data, predict_fn, target_class, feature_names,
+            feature_ranges, categorical_features=categorical_features,
+        )
+
+        # Try prototype-based if training data available
+        cf_proto = None
+        if training_data and training_labels:
+            cf_proto = prototype_counterfactual(
+                sample_data, training_data, training_labels,
+                target_class, feature_names, feature_ranges,
+            )
+
+        results = {
+            "greedy": cf_greedy,
+            "prototype": cf_proto,
+            "best": _select_best([cf_greedy, cf_proto]),
+        }
+
+    return {
+        "experiment_id": exp_id,
+        "sample_index": sample_index,
+        "target_class": target_class,
+        "results": results,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def _select_best(candidates: list[dict | None]) -> dict | None:
+    """Select the counterfactual with smallest distance."""
+    valid = [c for c in candidates if c and c.get("status") == "found"]
+    if not valid:
+        return None
+    return min(valid, key=lambda c: c.get("distance", float("inf")))
+
+
+# --- Report Formatting ---
+
+
+def save_counterfactual_report(report: dict, output_dir: str = "experiments/counterfactuals") -> Path:
+    """Save counterfactual report to YAML."""
+    out_path = Path(output_dir)
+    out_path.mkdir(parents=True, exist_ok=True)
+    exp_id = report.get("experiment_id", "unknown")
+    sample = report.get("sample_index", "batch")
+    filepath = out_path / f"{exp_id}-cf-{sample}.yaml"
+    with open(filepath, "w") as f:
+        yaml.dump(report, f, default_flow_style=False, sort_keys=False)
+    return filepath
+
+
+def format_counterfactual_report(report: dict) -> str:
+    """Format counterfactual report as readable markdown."""
+    if "error" in report:
+        return f"ERROR: {report['error']}"
+
+    lines = ["# Counterfactual Explanation", ""]
+    lines.append(f"**Experiment:** {report.get('experiment_id', 'N/A')}")
+    lines.append(f"**Sample:** {report.get('sample_index', 'N/A')}")
+    lines.append(f"**Target class:** {report.get('target_class', 'N/A')}")
+    lines.append("")
+
+    results = report.get("results", {})
+
+    if isinstance(results, dict):
+        best = results.get("best")
+        if best and best.get("status") == "found":
+            lines.append(f"**Method:** {best.get('method', 'greedy')}")
+            lines.append(f"**Distance:** {best.get('distance', 'N/A')}")
+            lines.append(f"**Changes needed:** {best.get('n_changes', 0)}")
+            lines.append("")
+
+            changes = best.get("changes", [])
+            if changes:
+                lines.append("| Feature | Original | Counterfactual | Change |")
+                lines.append("|---------|----------|----------------|--------|")
+                for c in changes:
+                    delta = c.get("delta", "")
+                    if isinstance(delta, (int, float)):
+                        delta_str = f"{delta:+.4f}" if isinstance(delta, float) else f"{delta:+d}"
+                    else:
+                        delta_str = str(delta)
+                    lines.append(
+                        f"| {c['feature']} | {c['original']} | {c['counterfactual']} | {delta_str} |"
+                    )
+        else:
+            lines.append("No counterfactual found within search budget.")
+
+        # Show method comparison
+        greedy = results.get("greedy", {})
+        proto = results.get("prototype", {})
+        if greedy.get("status") == "found" or (proto and proto.get("status") == "found"):
+            lines.append("")
+            lines.append("**Method comparison:**")
+            if greedy.get("status") == "found":
+                lines.append(f"- Greedy: distance={greedy.get('distance')}, changes={greedy.get('n_changes')}")
+            if proto and proto.get("status") == "found":
+                lines.append(f"- Prototype: distance={proto.get('distance')}, changes={proto.get('n_changes')}")
+
+    elif isinstance(results, list):
+        lines.append(f"**Batch results:** {len(results)} misclassified samples analyzed")
+        found = sum(1 for r in results if r.get("status") == "found")
+        lines.append(f"**Counterfactuals found:** {found}/{len(results)}")
+
+    lines.append("")
+    lines.append(f"*Generated: {report.get('generated_at', 'N/A')}*")
+    return "\n".join(lines)
+
+
+# --- CLI ---
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Counterfactual explanations — find minimum input changes to flip predictions"
+    )
+    parser.add_argument("exp_id", nargs="?", help="Experiment ID")
+    parser.add_argument("--sample", type=int, help="Sample index to explain")
+    parser.add_argument("--target", help="Target class for counterfactual")
+    parser.add_argument("--batch-misclassified", action="store_true",
+                        help="Generate counterfactuals for all misclassified samples")
+    parser.add_argument("--config", default="config.yaml", help="Path to config.yaml")
+    parser.add_argument("--log", default=DEFAULT_LOG_PATH, help="Path to experiment log")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+
+    args = parser.parse_args()
+
+    if not args.exp_id:
+        parser.error("Please provide an experiment ID")
+
+    report = counterfactual_analysis(
+        exp_id=args.exp_id,
+        sample_index=args.sample,
+        target_class=args.target,
+        batch_misclassified=args.batch_misclassified,
+        config_path=args.config,
+        log_path=args.log,
+    )
+
+    if args.json:
+        print(json.dumps(report, indent=2, default=str))
+    else:
+        print(format_counterfactual_report(report))
+
+    if "error" not in report:
+        saved = save_counterfactual_report(report)
+        if not args.json:
+            print(f"\nSaved: {saved}")
+
+
+if __name__ == "__main__":
+    main()