Train models from one declarative spec.
The high-level entry point of the library:
train takes a single spec dict describing the model, the data, the pipeline, and the evaluation, builds the corresponding Workflow, and returns it fitted. PRESETS provides ready-made pipeline step lists.Functions
train(spec: Union[Dict[str, Any], str]) -> 'Workflow'
Train a model from one declarative spec.
This is the high-level entry point. The whole run is described by a single dict (or a path to a JSON file containing it). Every component is written the same way, as {"name": ..., "params": {...}}, so a spec can be stored, diffed, sent over the wire, and replayed.
To work with imported classes and configured instances instead, use Workflow directly. It takes the same pipeline as a list of objects.
Parameters
spec
dict or str
The experiment spec, or a path to a
.json file containing it. Keys: model (required) What to train, as {"name": "RandomForestClassifier", "params": {"n_estimators": 100}}. "params" may be omitted for defaults; hyperparameters outside it are rejected. data (required) What to train on. {"source": "sales.csv", "target": "label"} for a file (csv, arff, parquet, json, excel, auto-detected) or a builtin dataset name, {"X": X_array, "y": y_array} for in-memory arrays, or a bare source such as "iris". target, features (optional) Companions for a bare data source: the target column name (or array) and a column subset to keep. pipeline (optional) Ordered steps applied before the model. Each step is a component spec; imputation, scaling, encoding, feature generation, extraction, selection, and resampling are all steps. A preset name ("minimal", "fast", "standard", "full", "imbalanced") expands to a predefined list. evaluation (optional) How to score the run. {"cv": 10} for k-fold, or {"test_size": 0.2, "stratify": True} for a holdout split, plus "metrics": a list of metric function names from tuiml.evaluation.metrics (default "auto"). Omitted entirely: a stratified 80/20 holdout with auto metrics. random_seed (optional) Seed for splits, folds, and any component that accepts one. Falls back to the global seed, then 42.
Returns
Workflow
The fitted pipeline. It behaves like a model:
metrics_ holds the evaluation scores, and predict(X), score(X, y), save(path), serve(port=...) are all available on it.
Raises
ValueError
If required keys are missing, an unknown key is present, or a component spec carries loose hyperparameter keys.
python
>>> import tuiml
>>> model = tuiml.train({
... "model": {"name": "RandomForestClassifier",
... "params": {"n_estimators": 100}},
... "data": {"source": "sales.csv", "target": "label"},
... "pipeline": [
... {"name": "SimpleImputer", "params": {"strategy": "mean"}},
... {"name": "StandardScaler"},
... {"name": "SelectKBestSelector", "params": {"k": 10}},
... ],
... "evaluation": {"cv": 10, "metrics": ["accuracy_score"]},
... "random_seed": 42,
... })
>>> model.metrics_ # doctest: +SKIP
{'cv_accuracy_score_mean': 0.94, 'cv_accuracy_score_std': 0.02}The same spec from a JSON file:
python
>>> model = tuiml.train("experiment.json") # doctest: +SKIPIn-memory arrays:
python
>>> model = tuiml.train({
... "model": {"name": "NaiveBayesClassifier"},
... "data": {"X": X, "y": y},
... }) # doctest: +SKIP