---

🎯 What is Corter?

Corter runs hyperparameter search on tabular CSV data, fits a scikit-learn model with the best settings, and reports feature importance and short text insights. Everything runs on your machine via the CLI, Python API, or optional Flask web dashboard.

Why Corter?

• CLI workflow — corter init, corter run, corter web
• YAML configuration — task, model, HPO, and XAI settings in one file
• Terminal UI — live progress with Rich during optimization
• Web dashboard — monitor runs at http://localhost:5000 when using --web or corter web
• Explainability — permutation importance; optional SHAP when corter-ml[xai] is installed

---

✨ Features

Hyperparameter optimization

• Random search over a YAML-defined search space
• SciPy global (scipy_de) and local (scipy_local) strategies
• Parallel trials via joblib
• Early stopping when scores stop improving

Models (scikit-learn)

Supported model.name values:

Name	Aliases
random_forest	rf
gradient_boosting	gbm
logistic_regression	logreg, logistic
ridge
svc	svm

Numeric feature columns are used automatically; specify target_column in config.

Explainability

• Permutation importance (always)
• SHAP values when shap is installed (pip install corter-ml[xai])
• Drift checks and generated insight strings

Interfaces

• CLI — corter init, run, web, version
• Python — Corter.from_yaml(...) and core.run("data.csv")
• Web UI — Flask app in web_ui.py; corter_web.py pushes live updates during a run

---

📦 Installation

From PyPI (when published)

pip install corter-ml

From source

git clone https://github.com/pizenkov13-boop/Corter.git
cd Corter
pip install -e .

Optional extras

pip install corter-ml[xai]    # SHAP support
pip install corter-ml[dev]    # pytest, black, mypy

---

🚀 Quick Start

1. Create configuration

corter init

Example config.yaml:

task: classification
target_column: target

model:
  name: random_forest
  params:
    n_estimators: 100

hpo:
  strategy: random          # random | scipy_de | scipy_local
  n_trials: 24
  parallel_trials: 4
  enable_early_stop: true
  cv_folds: 5
  scoring: accuracy
  search_space:
    n_estimators:
      low: 50
      high: 200
      type: int

xai:
  use_shap: true
  top_k_features: 10

tui:
  show_live: true
  refresh_hz: 4

2. Run optimization

corter run data.csv
corter run data.csv --web          # optimization + dashboard
corter run data.csv -c other.yaml

Results are written to results.json by default.

3. Python API

from corter import Corter

core = Corter.from_yaml("config.yaml")
result = core.run("data.csv")

print(result["best_cv_score"])
print(result["best_params"])
print(result["insights"])

4. Web dashboard only

corter web
# open http://127.0.0.1:5000

During corter run data.csv --web, the dashboard receives live updates from the optimizer.

---

📖 Documentation

Task configuration

task: auto                  # auto | classification | regression
target_column: target       # default: last column

HPO configuration

hpo:
  strategy: random          # random | scipy_de | scipy_local
  n_trials: 50
  parallel_trials: 4
  enable_early_stop: true
  patience: 5
  min_delta: 0.001
  cv_folds: 5
  scoring: accuracy         # or f1_weighted, neg_mean_squared_error, etc.
  search_space: { ... }

XAI configuration

xai:
  use_shap: true            # requires corter-ml[xai]
  shap_sample_size: 100
  top_k_features: 10
  permutation_repeats: 8
  drift_threshold: 0.15

CLI reference

corter init [-o config.yaml]
corter run <data.csv> [-c config.yaml] [--web] [--output results.json]
corter web [--host 127.0.0.1] [--port 5000]
corter version

Direct module usage

python corter.py data.csv -c config.yaml
python corter_web.py config.yaml data.csv   # optimization with web updates
gunicorn web_ui:app                         # production-style web only (see Procfile)

---

🏗️ Architecture

┌──────────────────────────────────────────────┐
│                   Corter                     │
├──────────────────────────────────────────────┤
│  CLI (corter_pkg)  │  corter.py  │  web_ui  │
├────────────────────┴─────────────┴──────────┤
│  HyperparameterAutopilot  →  fit best model │
│  SemanticDiagnostics      →  insights       │
│  CorterDashboard (Rich TUI)                 │
└──────────────────────────────────────────────┘

---

🤝 Contributing

1. Fork and clone the repository
2. pip install -e ".[dev]"
3. Make changes and run formatters/tests as appropriate
4. Open a pull request

---

📄 License

MIT — see LICENSE.

---

🙏 Acknowledgments

• scikit-learn — models and metrics
• SHAP — optional explainability
• Rich — terminal UI
• Flask — web dashboard

---

📞 Support

• GitHub Issues
• GitHub Discussions

---