Args:
    filename: CSV file inside datasets/ (e.g. "train.csv").
    sample_rows: How many head rows to include in the preview.

Categorical features are one-hot encoded and numeric features are imputed +
scaled inside a single sklearn Pipeline, so it works on raw Kaggle CSVs.

Args:
    filename: CSV file inside datasets/.
    target: Column to predict.
    features: Columns to use as predictors. Defaults to all other columns.
    task: "classification", "regression", or "auto" (inferred from target).
    test_size: Fraction held out for evaluation.
    random_state: Reproducibility seed.

Provide the rows to score in ONE of two ways:
  * `records`: a list of row dicts, e.g.
    [{"Pclass": 3, "Sex": "male", "Age": 22, "Fare": 7.25, "Embarked": "S"}]
  * `filename`: a CSV inside datasets/ to score every row of (e.g. a Kaggle
    "test.csv").

The saved model is a full pipeline, so missing values and categoricals are
handled automatically; you only need to supply the feature columns used in
training. For classifiers, per-class probabilities and a confidence score
are included.

Args:
    model: Saved model name (see list_models), with or without ".joblib".
    records: Inline rows to score.
    filename: CSV in datasets/ to score instead of `records`.
    id_column: Optional identifier column to echo alongside each prediction
        (e.g. "PassengerId") — handy for building a submission file.
    save_csv: If true, also write the predictions to outputs/ as a CSV.
    top_n: Max number of prediction rows to include in the response.

Requires Kaggle authentication (KAGGLE_USERNAME / KAGGLE_KEY env vars or
~/.kaggle/kaggle.json). Example dataset slug: "yasserh/titanic-dataset".