Workflow and operations API

Load, validate, split, fit, and score an experiment.

Per-row pure-premium rate under the multiplicative tariff on X.

Equivalent to RiskGLM.predict(X) when tariff has not been recalibrated. Numeric inputs must be finite and categorical levels must have been seen when the tariff was extracted. The linear predictor is summed before exponentiation. Invalid factors and unrepresentable rates raise ValueError; a zero recalibrated base produces zero rates.

Fit an exportable log-link GLM to a fitted positive-objective GBM.

The student is a RiskGLM that inherits the teacher's objective as its family (tweedie, poisson, or gamma) and, for tweedie, the teacher's tweedie_variance_power; it fits with the RiskGLM default alpha=0.001. The fit frame teaches the student; the separate validation frame supplies only held-out fidelity metrics. Both use the teacher's exposure column as sample weight, and both frames must yield positive, finite exposure and teacher predictions. A pipeline result contains copied, already-fitted upstream preprocessing (bins and group mappings are not relearned) and exposes the metrics in distillation_metrics_.

Callers must supply disjoint observations for fitting and validation. The object-identity guard only rejects reuse of the same frame object; distinct frames (including copies) do not prove row independence. The CLI uses the run's stored training and test positions.

Write a multiplicative-tariff xlsx from a fitted RiskGLM or pipeline.

Three sheets per PRD section 3: base_rate / factors / mappings. By default recalibrate=True and an (X, y, exposure_col) triple is expected; the base is shifted so the tariff reproduces the observed portfolio total claim amount. Pass recalibrate=False for the structural tariff (intercept + reference levels only).

y must be a finite, non-negative one-dimensional vector of aggregate claim amounts with one value per row of X. Library callers choose this calibration frame explicitly; keep evaluation observations separate. The CLI recalibrates only on the run's stored training positions.

Base and factors must be representable as finite floats (strictly positive except for a zero-total recalibrated base). User text is written as literal Excel strings; numeric and boolean level labels retain their types.

Decompose a fitted RiskGLM into a multiplicative tariff structure.

The returned base_rate is structural (intercept + ref levels only); pass the returned dict through recalibrate_for_total (or call export_tariff with the (X, y, exposure_col, recalibrate=True) quadruple) to shift the base so the tariff reproduces an observed portfolio total.

Coefficients must be finite; the structural base and categorical factors must be representable as positive, finite floats. Numeric coefficients remain in log space; workbook export additionally requires representable per-unit factors.

Shift the tariff base so it reproduces an observed portfolio total.

predicted_total is the sum of model-predicted pure premium times exposure; observed_total is the sum of observed aggregate claim amount. Returns the new base rate. A zero observed total returns zero; otherwise an unrepresentable adjusted base raises ValueError.

Return standalone Plotly HTML with the same context warning as the table.

Return all model metrics, warning once for mixed evaluation contexts.

Dataset fingerprints, target/exposure columns, and holdout membership must match for direct comparisons. Holdout order does not matter. Mixed contexts remain available for descriptive comparison; the warning names affected runs.

Return the model card for run as markdown.

Calibration tables are truncated to their first 12 rows -- a preview, not the full table; write full tables separately when all segments are needed.

Log run to mlflow and return the mlflow run_id (string).

run_name defaults to the experiment config name. Records: * Top-level params: config name, split, test_size, random_state, n_rows / n_train / n_test (prefixed experiment.*). * Per-model: <model>.kind + one <model>.params.<k> per param, plus one <model>.<metric> metric per metric (NaN and infinite metrics are skipped -- mlflow rejects non-finite values since 3.x). * Artifacts: every path in artifacts (file or directory). A missing path raises FileNotFoundError. Files upload flat under artifact_path (default "artifacts"); a directory's contents upload nested under <artifact_path>/<dir_name> so the directory name is preserved in the artifact tree.

Run an optuna study per named model; return a TuneResult whose run refits every selected model on outer training data and scores outer test.

calibration_penalty scales |1 - op_ratio_test| to be commensurate with deviance_test -- tune it to your portfolio's deviance magnitude (a unitless ratio penalty is invisible against a six-figure Tweedie deviance; raise the penalty until calibration loss shows up in the trial ordering).

Explicit n_trials and calibration_penalty values override config.tuning; omitted values use YAML, then 20 and 1.0. return_estimators=True also populates TuneResult.estimators with {name: fitted_estimator} from the final run_experiment.