Metadata-Version: 2.4
Name: corter-ml
Version: 0.1.0
Summary: Autonomous ML Optimization Framework - No cloud required, no GPU farm needed
Home-page: https://github.com/pizenkov13-boop/Corter
Author: Corter Team
Author-email: support@corter.dev
Project-URL: Bug Reports, https://github.com/pizenkov13-boop/Corter/issues
Project-URL: Source, https://github.com/pizenkov13-boop/Corter
Project-URL: Documentation, https://github.com/pizenkov13-boop/Corter/blob/main/README.md
Keywords: machine-learning ml optimization hyperparameter-tuning explainable-ai xai automl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: joblib>=1.3.0
Requires-Dist: flask>=2.3.0
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: gunicorn>=21.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Provides-Extra: xai
Requires-Dist: shap>=0.42.0; extra == "xai"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

# ⚡ Corter

### Autonomous ML Optimization Framework

*Local hyperparameter search and explainability — no cloud required.*

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub Stars](https://img.shields.io/github/stars/pizenkov13-boop/Corter?style=social)](https://github.com/pizenkov13-boop/Corter)

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Contributing](#-contributing)

</div>

---

## 🎯 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)

```bash
pip install corter-ml
```

### From source

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

### Optional extras

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

---

## 🚀 Quick Start

### 1. Create configuration

```bash
corter init
```

Example `config.yaml`:

```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

```bash
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

```python
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

```bash
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

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

### HPO configuration

```yaml
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

```yaml
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

```bash
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

```bash
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](LICENSE).

---

## 🙏 Acknowledgments

- [scikit-learn](https://scikit-learn.org/) — models and metrics
- [SHAP](https://github.com/slundberg/shap) — optional explainability
- [Rich](https://github.com/Textualize/rich) — terminal UI
- [Flask](https://flask.palletsprojects.com/) — web dashboard

---

## 📞 Support

- [GitHub Issues](https://github.com/pizenkov13-boop/Corter/issues)
- [GitHub Discussions](https://github.com/pizenkov13-boop/Corter/discussions)

---

<div align="center">

**Made with ❤️ by the Corter Team**

[⬆ Back to Top](#-corter)

</div>
