autodatamining 0.1.0__tar.gz

autodatamining-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1

autodatamining-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,25 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install -e ".[dev,visualization]"
+      - run: python -m compileall -q src tests
+      - run: python -m ruff check src tests examples
+      - run: python -m pytest -q --cov=autodatamining --cov-report=term-missing
+      - run: python -m build
+      - run: python -m twine check dist/*

autodatamining-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+- Initial modular library for classification, regression, clustering, and anomaly detection.
+- Added registry, mixed tabular preprocessing, evaluation, reports, explainability, and persistence.
+- Alpha API; package has not been published.

autodatamining-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+1. Create a virtual environment and install `python -m pip install -e ".[dev,visualization]"`.
+2. Keep task-specific code modular and preserve train/test separation and fold-local preprocessing.
+3. Add or update tests for behavior and edge cases.
+4. Run `python -m compileall -q src tests`, `python -m ruff check src tests examples`, `python -m pytest -q`, `python -m build`, and `python -m twine check dist/*`.
+5. Update README/docs and CHANGELOG when public behavior changes.
+
+Please check third-party dependency licenses and preserve attribution. Do not include user datasets, credentials, or generated model artifacts in pull requests. The current API is alpha and may change before a stable release.

autodatamining-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AutoDataMining contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

autodatamining-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE CHANGELOG.md CONTRIBUTING.md build.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include .github/workflows *.yml

autodatamining-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: autodatamining
+Version: 0.1.0
+Summary: A consistent, transparent scikit-learn based data mining workflow.
+Author: AutoDataMining contributors
+License-Expression: MIT
+Keywords: machine-learning,data-mining,automl,scikit-learn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.4
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.5; extra == "visualization"
+Provides-Extra: explainability
+Requires-Dist: shap>=0.42; extra == "explainability"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=4; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# AutoDataMining
+
+**AutoDataMining** is a Python library for running consistent, inspectable data mining experiments with scikit-learn. It brings preprocessing, model comparison, evaluation, simple explanations, reports, and model persistence behind one API. It integrates existing estimators; it does not introduce new machine learning algorithms.
+
+> **Status: alpha (0.1.0).** The public API may change. Benchmark results depend on the dataset, split, metric, and estimator settings, and are not a guarantee of future performance. Review results before using a model in a consequential setting.
+
+## Installation
+
+```bash
+python -m pip install autodatamining
+```
+
+For plots and optional SHAP explanations:
+
+```bash
+python -m pip install "autodatamining[visualization,explainability]"
+```
+
+## Quick start: classification
+
+```python
+import pandas as pd
+from autodatamining import AutoDataMining
+
+data = pd.read_csv("dataset.csv")
+results = AutoDataMining(
+    task="classification",
+    target="label",
+    test_size=0.2,
+    cv=5,
+    random_state=42,
+    scoring="f1_weighted",
+    models=["logistic_regression", "random_forest"],
+).fit(data)
+
+print(results.leaderboard)
+print(results.best_model)
+print(results.metrics)  # holdout metrics, plus CV score and fit time
+results.plot()
+results.report("classification-report.html")
+results.save("best-model.joblib")
+```
+
+`leaderboard.cv_score` is calculated only on training folds. Other task metrics such as `accuracy`, `f1_weighted`, and `roc_auc` are holdout test values. The holdout is not used for selection when valid cross-validation scores exist.
+
+## Other tasks
+
+### Regression
+
+```python
+results = AutoDataMining(
+    task="regression", target="price", cv=5, random_state=42,
+    models=["ridge", "random_forest", "hist_gradient_boosting"],
+).fit(data)
+print(results.leaderboard[["model", "cv_score", "mae", "rmse", "r2", "status"]])
+```
+
+### Clustering
+
+```python
+results = AutoDataMining(
+    task="clustering", models=["kmeans", "dbscan", "agglomerative"], random_state=42,
+).fit(features)
+print(results.leaderboard)
+print(results.labels)  # labels from the selected model
+```
+
+The selected clustering model is ranked by silhouette score when that score is defined. Silhouette, Davies–Bouldin, and Calinski–Harabasz are internal measures, not accuracy against known classes. DBSCAN noise points have label `-1`.
+
+### Anomaly detection
+
+```python
+results = AutoDataMining(
+    task="anomaly", models=["isolation_forest", "lof"], random_state=42,
+).fit(features)
+print(results.leaderboard)  # anomaly_rate and anomaly_count
+print(results.labels)  # -1 is an anomaly; +1 is an inlier
+```
+
+Without ground-truth labels, anomaly rate describes how many rows were flagged; it cannot rank model quality. If labels are available, pass their column as `target` and encode anomalies as `1`/`True` and normal rows as `0`/`False`. The runner excludes that target from the features, selects using stratified training-fold F1, and reports holdout precision, recall, F1, and AUC where defined. In labeled mode, `results.labels` contains selected-model holdout predictions; without labels, it contains fit-set detections.
+
+## Algorithms and metrics
+
+| Task | Built-in estimators | Default comparison score |
+| --- | --- | --- |
+| Classification | Logistic Regression, Decision Tree, Random Forest, Extra Trees, Gradient Boosting, HistGradientBoosting, KNN, Gaussian Naive Bayes, SVM | Accuracy (training CV) |
+| Regression | Linear Regression, Ridge, Lasso, Decision Tree, Random Forest, Extra Trees, Gradient Boosting, HistGradientBoosting, KNN, SVR | R² (training CV) |
+| Clustering | K-Means, MiniBatch K-Means, DBSCAN, Agglomerative, Gaussian Mixture | Silhouette |
+| Anomaly | Isolation Forest, Local Outlier Factor, One-Class SVM | Labeled F1 when labels are supplied; otherwise no quality ranking |
+
+Classification holdout metrics include accuracy, balanced accuracy, weighted precision/recall/F1, and ROC-AUC / PR-AUC when the estimator and test labels support them. Regression reports MAE, MSE, RMSE, and R². Clustering reports silhouette, Davies–Bouldin, and Calinski–Harabasz when defined. Individual estimator failures are recorded in the leaderboard; successful models remain usable.
+
+## Automatic task detection and data profile
+
+`task="auto"` requires a target column. Text-like targets are treated as classification; small-cardinality integer targets are treated as classification; other numeric targets are treated as regression. Ambiguous low-cardinality numeric targets emit a warning. Pass `task` explicitly when the heuristic is not appropriate. Auto mode never silently launches clustering.
+
+```python
+from autodatamining import AutoDataMining
+
+profile = AutoDataMining.profile(data, target="label")
+print(profile["potential_issues"])
+```
+
+The profile includes row and column counts, per-column type, missing count and cardinality, duplicate rows, and a target distribution. It does not diagnose leakage or establish that a metric is suitable for a research question.
+
+## Advanced usage
+
+### Custom estimators
+
+```python
+from sklearn.linear_model import SGDClassifier
+from autodatamining import AutoDataMining, EstimatorRegistry
+
+registry = EstimatorRegistry()
+registry.register("fast_sgd", SGDClassifier, tasks="classification",
+                  params={"max_iter": 2000, "tol": 1e-3})
+results = AutoDataMining(
+    task="classification", target="label", registry=registry,
+    models=["fast_sgd"], cv=3,
+).fit(data)
+```
+
+Use unique names and register only estimators compatible with the declared task. Estimators are cloned before fitting. Model-specific parameters can be supplied with `model_params={"fast_sgd": {"alpha": 0.001}}`.
+
+The module-level `register_estimator(name, estimator, tasks, params=None)` adds an estimator to the shared default registry for later runs.
+
+### Feature selection and dimensionality reduction
+
+```python
+from autodatamining import select_features, reduce_dimensions
+
+selected, selector = select_features(numeric_features, y, method="mutual_information",
+                                     task="classification", k=5)
+embedding, pca = reduce_dimensions(numeric_features, method="pca", n_components=2)
+```
+
+These convenience helpers fit directly to the data passed to them. For scientific evaluation, put selection or reduction inside a cross-validation `Pipeline` so each fold learns its transform from training data only.
+
+### Explainability
+
+```python
+importance = results.explain(method="auto")
+```
+
+Auto mode uses native tree importance or absolute coefficient magnitude where available, then falls back to holdout permutation importance for supervised tasks. `method="shap"` requires the optional extra. Importance describes model behavior and is not causal evidence. Unsupervised feature importance is not inferred.
+
+### Plots, reports, and CSV
+
+```python
+results.plot(kind="leaderboard")
+results.plot(kind="confusion_matrix")  # classification
+results.plot(kind="roc_curve")          # binary classification
+results.plot(kind="precision_recall_curve")  # binary classification
+results.plot(kind="residuals")          # regression
+results.plot(kind="clusters")           # clustering
+print(results.classification_report())
+results.to_csv("leaderboard.csv")
+results.report("experiment.html")
+```
+
+Plots need `autodatamining[visualization]`. HTML reports include experiment metadata, metrics, leaderboard, and evaluation limitations; dataset rows are not included.
+
+### Save and load
+
+```python
+from autodatamining import load_model
+
+results.save("model.joblib")
+model = load_model("model.joblib")
+predictions = model.predict(new_data)
+```
+
+Prediction validates feature names and permits incoming DataFrame columns in a different order. Missing or unexpected columns raise an error. A joblib/pickle artifact can execute code when loaded: only load files from a trusted source. Artifacts record the scikit-learn version; cross-version compatibility is not guaranteed.
+
+## Evaluation notes
+
+- Supervised evaluation uses a train/test split and cross-validation on the training partition. Preprocessing is in the estimator pipeline and is fitted independently inside each fold.
+- Classification uses stratification where class counts allow. Very small classes can prevent stratification or CV; the runner warns and reports what it could evaluate.
+- CV score selects the supervised model when available. Holdout metrics are reported separately and should not be used repeatedly to tune the experiment.
+- Clustering and unlabeled anomaly detection do not have ground-truth accuracy. Internal scores and anomaly rates have narrower meanings.
+- Compare models using a metric tied to the intended use, and assess class imbalance, data leakage, temporal or grouped splits, calibration, latency, and deployment data drift separately.
+- A top score in one experiment is not necessarily the best model for all datasets or real-world use.
+
+## Troubleshooting
+
+- **`task='auto' requires a target column`**: pass a target or explicitly choose clustering/anomaly.
+- **A requested estimator failed**: inspect its `status` and `error` in `results.leaderboard`; try fewer parameters or another model.
+- **Feature columns do not match**: supply the same feature names as training; DataFrame column order may differ.
+- **A score is missing/NaN**: some metrics need multiple target classes or at least two non-noise clusters.
+- **Plotting or SHAP import error**: install the corresponding optional extra.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev,visualization]"
+python -m compileall -q src tests
+python -m ruff check src tests examples
+python -m pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md). Contributions should include tests for changed behavior and preserve the distinction between training CV and holdout evaluation.
+
+## PyPI release checklist
+
+1. Review source, dependency licenses, project ownership, name availability, and version.
+2. Run the test suite and build checks above.
+3. Inspect wheel and source distribution contents.
+4. Upload to TestPyPI and install into a clean virtual environment.
+5. Publish to PyPI using an API token held outside the source tree or trusted publishing.
+6. Verify the published install and create a version tag.
+
+The project has not been published by this repository setup. Name availability and legal attribution must be checked again at release time. No credentials belong in the repository.
+
+## License
+
+MIT; see [LICENSE](LICENSE). Review ownership and attribution before the first release.

autodatamining-0.1.0/README.md

@@ -0,0 +1,218 @@
+# AutoDataMining
+
+**AutoDataMining** is a Python library for running consistent, inspectable data mining experiments with scikit-learn. It brings preprocessing, model comparison, evaluation, simple explanations, reports, and model persistence behind one API. It integrates existing estimators; it does not introduce new machine learning algorithms.
+
+> **Status: alpha (0.1.0).** The public API may change. Benchmark results depend on the dataset, split, metric, and estimator settings, and are not a guarantee of future performance. Review results before using a model in a consequential setting.
+
+## Installation
+
+```bash
+python -m pip install autodatamining
+```
+
+For plots and optional SHAP explanations:
+
+```bash
+python -m pip install "autodatamining[visualization,explainability]"
+```
+
+## Quick start: classification
+
+```python
+import pandas as pd
+from autodatamining import AutoDataMining
+
+data = pd.read_csv("dataset.csv")
+results = AutoDataMining(
+    task="classification",
+    target="label",
+    test_size=0.2,
+    cv=5,
+    random_state=42,
+    scoring="f1_weighted",
+    models=["logistic_regression", "random_forest"],
+).fit(data)
+
+print(results.leaderboard)
+print(results.best_model)
+print(results.metrics)  # holdout metrics, plus CV score and fit time
+results.plot()
+results.report("classification-report.html")
+results.save("best-model.joblib")
+```
+
+`leaderboard.cv_score` is calculated only on training folds. Other task metrics such as `accuracy`, `f1_weighted`, and `roc_auc` are holdout test values. The holdout is not used for selection when valid cross-validation scores exist.
+
+## Other tasks
+
+### Regression
+
+```python
+results = AutoDataMining(
+    task="regression", target="price", cv=5, random_state=42,
+    models=["ridge", "random_forest", "hist_gradient_boosting"],
+).fit(data)
+print(results.leaderboard[["model", "cv_score", "mae", "rmse", "r2", "status"]])
+```
+
+### Clustering
+
+```python
+results = AutoDataMining(
+    task="clustering", models=["kmeans", "dbscan", "agglomerative"], random_state=42,
+).fit(features)
+print(results.leaderboard)
+print(results.labels)  # labels from the selected model
+```
+
+The selected clustering model is ranked by silhouette score when that score is defined. Silhouette, Davies–Bouldin, and Calinski–Harabasz are internal measures, not accuracy against known classes. DBSCAN noise points have label `-1`.
+
+### Anomaly detection
+
+```python
+results = AutoDataMining(
+    task="anomaly", models=["isolation_forest", "lof"], random_state=42,
+).fit(features)
+print(results.leaderboard)  # anomaly_rate and anomaly_count
+print(results.labels)  # -1 is an anomaly; +1 is an inlier
+```
+
+Without ground-truth labels, anomaly rate describes how many rows were flagged; it cannot rank model quality. If labels are available, pass their column as `target` and encode anomalies as `1`/`True` and normal rows as `0`/`False`. The runner excludes that target from the features, selects using stratified training-fold F1, and reports holdout precision, recall, F1, and AUC where defined. In labeled mode, `results.labels` contains selected-model holdout predictions; without labels, it contains fit-set detections.
+
+## Algorithms and metrics
+
+| Task | Built-in estimators | Default comparison score |
+| --- | --- | --- |
+| Classification | Logistic Regression, Decision Tree, Random Forest, Extra Trees, Gradient Boosting, HistGradientBoosting, KNN, Gaussian Naive Bayes, SVM | Accuracy (training CV) |
+| Regression | Linear Regression, Ridge, Lasso, Decision Tree, Random Forest, Extra Trees, Gradient Boosting, HistGradientBoosting, KNN, SVR | R² (training CV) |
+| Clustering | K-Means, MiniBatch K-Means, DBSCAN, Agglomerative, Gaussian Mixture | Silhouette |
+| Anomaly | Isolation Forest, Local Outlier Factor, One-Class SVM | Labeled F1 when labels are supplied; otherwise no quality ranking |
+
+Classification holdout metrics include accuracy, balanced accuracy, weighted precision/recall/F1, and ROC-AUC / PR-AUC when the estimator and test labels support them. Regression reports MAE, MSE, RMSE, and R². Clustering reports silhouette, Davies–Bouldin, and Calinski–Harabasz when defined. Individual estimator failures are recorded in the leaderboard; successful models remain usable.
+
+## Automatic task detection and data profile
+
+`task="auto"` requires a target column. Text-like targets are treated as classification; small-cardinality integer targets are treated as classification; other numeric targets are treated as regression. Ambiguous low-cardinality numeric targets emit a warning. Pass `task` explicitly when the heuristic is not appropriate. Auto mode never silently launches clustering.
+
+```python
+from autodatamining import AutoDataMining
+
+profile = AutoDataMining.profile(data, target="label")
+print(profile["potential_issues"])
+```
+
+The profile includes row and column counts, per-column type, missing count and cardinality, duplicate rows, and a target distribution. It does not diagnose leakage or establish that a metric is suitable for a research question.
+
+## Advanced usage
+
+### Custom estimators
+
+```python
+from sklearn.linear_model import SGDClassifier
+from autodatamining import AutoDataMining, EstimatorRegistry
+
+registry = EstimatorRegistry()
+registry.register("fast_sgd", SGDClassifier, tasks="classification",
+                  params={"max_iter": 2000, "tol": 1e-3})
+results = AutoDataMining(
+    task="classification", target="label", registry=registry,
+    models=["fast_sgd"], cv=3,
+).fit(data)
+```
+
+Use unique names and register only estimators compatible with the declared task. Estimators are cloned before fitting. Model-specific parameters can be supplied with `model_params={"fast_sgd": {"alpha": 0.001}}`.
+
+The module-level `register_estimator(name, estimator, tasks, params=None)` adds an estimator to the shared default registry for later runs.
+
+### Feature selection and dimensionality reduction
+
+```python
+from autodatamining import select_features, reduce_dimensions
+
+selected, selector = select_features(numeric_features, y, method="mutual_information",
+                                     task="classification", k=5)
+embedding, pca = reduce_dimensions(numeric_features, method="pca", n_components=2)
+```
+
+These convenience helpers fit directly to the data passed to them. For scientific evaluation, put selection or reduction inside a cross-validation `Pipeline` so each fold learns its transform from training data only.
+
+### Explainability
+
+```python
+importance = results.explain(method="auto")
+```
+
+Auto mode uses native tree importance or absolute coefficient magnitude where available, then falls back to holdout permutation importance for supervised tasks. `method="shap"` requires the optional extra. Importance describes model behavior and is not causal evidence. Unsupervised feature importance is not inferred.
+
+### Plots, reports, and CSV
+
+```python
+results.plot(kind="leaderboard")
+results.plot(kind="confusion_matrix")  # classification
+results.plot(kind="roc_curve")          # binary classification
+results.plot(kind="precision_recall_curve")  # binary classification
+results.plot(kind="residuals")          # regression
+results.plot(kind="clusters")           # clustering
+print(results.classification_report())
+results.to_csv("leaderboard.csv")
+results.report("experiment.html")
+```
+
+Plots need `autodatamining[visualization]`. HTML reports include experiment metadata, metrics, leaderboard, and evaluation limitations; dataset rows are not included.
+
+### Save and load
+
+```python
+from autodatamining import load_model
+
+results.save("model.joblib")
+model = load_model("model.joblib")
+predictions = model.predict(new_data)
+```
+
+Prediction validates feature names and permits incoming DataFrame columns in a different order. Missing or unexpected columns raise an error. A joblib/pickle artifact can execute code when loaded: only load files from a trusted source. Artifacts record the scikit-learn version; cross-version compatibility is not guaranteed.
+
+## Evaluation notes
+
+- Supervised evaluation uses a train/test split and cross-validation on the training partition. Preprocessing is in the estimator pipeline and is fitted independently inside each fold.
+- Classification uses stratification where class counts allow. Very small classes can prevent stratification or CV; the runner warns and reports what it could evaluate.
+- CV score selects the supervised model when available. Holdout metrics are reported separately and should not be used repeatedly to tune the experiment.
+- Clustering and unlabeled anomaly detection do not have ground-truth accuracy. Internal scores and anomaly rates have narrower meanings.
+- Compare models using a metric tied to the intended use, and assess class imbalance, data leakage, temporal or grouped splits, calibration, latency, and deployment data drift separately.
+- A top score in one experiment is not necessarily the best model for all datasets or real-world use.
+
+## Troubleshooting
+
+- **`task='auto' requires a target column`**: pass a target or explicitly choose clustering/anomaly.
+- **A requested estimator failed**: inspect its `status` and `error` in `results.leaderboard`; try fewer parameters or another model.
+- **Feature columns do not match**: supply the same feature names as training; DataFrame column order may differ.
+- **A score is missing/NaN**: some metrics need multiple target classes or at least two non-noise clusters.
+- **Plotting or SHAP import error**: install the corresponding optional extra.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev,visualization]"
+python -m compileall -q src tests
+python -m ruff check src tests examples
+python -m pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md). Contributions should include tests for changed behavior and preserve the distinction between training CV and holdout evaluation.
+
+## PyPI release checklist
+
+1. Review source, dependency licenses, project ownership, name availability, and version.
+2. Run the test suite and build checks above.
+3. Inspect wheel and source distribution contents.
+4. Upload to TestPyPI and install into a clean virtual environment.
+5. Publish to PyPI using an API token held outside the source tree or trusted publishing.
+6. Verify the published install and create a version tag.
+
+The project has not been published by this repository setup. Name availability and legal attribution must be checked again at release time. No credentials belong in the repository.
+
+## License
+
+MIT; see [LICENSE](LICENSE). Review ownership and attribution before the first release.