optuna-nested-cv

Run resumable Optuna hyperparameter searches with nested cross-validation and SQLite persistence.

Updated Apr 20, 2026
One-click install
npx skills add https://github.com/thistleknot/skills --skill optuna-nested-cv
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: optuna-nested-cv
Source: https://github.com/thistleknot/skills/tree/main/optuna-nested-cv
Command: npx skills add https://github.com/thistleknot/skills --skill optuna-nested-cv

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It eliminates unreliable hyperparameter tuning by running a persistent Optuna search inside a nested cross-validation structure, producing an unbiased generalization estimate while preventing holdout leakage.

Core Features & Use Cases

  • Nested CV for unbiased evaluation: Uses an outer holdout fold for evaluation and an inner Optuna study to tune only on the outer training split.
  • Resumable SQLite-backed studies: Ensures trials are auditable and restartable via a stable study name and persistent storage.
  • Scalar objective + composite scoring: Supports single-scalar optimization (including composite objectives) to keep selection unambiguous.
  • Split discipline (tune vs holdout): Enforces explicit bank roles so the search never “peeks” at the evaluation data.
  • Sampler-policy contract: Keeps sampling regimes consistent between search and final training, so results transfer correctly.
  • Use in tuning expensive pipelines: Designed for costly evaluations where the search budget must be efficiently managed and results must generalize.

Quick Start

Use the optuna-nested-cv skill to run an Optuna TPE hyperparameter search over an inner loop for each outer CV fold, persisting trials to sqlite and reporting the mean outer-fold score as the unbiased estimate.

Frequently Asked Questions about optuna-nested-cv

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run resumable Optuna hyperparameter tuning with nested cross-validation?

Resumable Optuna hyperparameter tuning with nested cross-validation runs a TPE search inside an inner loop for each outer fold, persisting trials to SQLite to ensure the process is auditable and restartable.

Why does my hyperparameter optimization leak holdout data during model selection?

Hyperparameter optimization leaks holdout data when the tuning process evaluates on the same split used for final testing; nested cross-validation prevents this by enforcing strict tune versus holdout separation across outer folds.

Can I use a composite objective for TPE sampler searches in Optuna?

Yes, TPE sampler searches in Optuna support a single scalar objective, which can be a composite metric, ensuring the model selection process remains unambiguous during the hyperparameter optimization.

Does Optuna support SQLite-backed study persistence for expensive ML pipelines?

Optuna supports SQLite-backed study persistence for expensive ML pipelines by using a stable study name and persistent storage, allowing trials to be saved, audited, and restarted across search sessions.

What is the best way to get an unbiased generalization score from hyperparameter tuning?

The best way to get an unbiased generalization score from hyperparameter tuning is nested cross-validation, which evaluates the model on an outer holdout fold after tuning only on the inner training split.

How do I keep fold-safe preprocessing normalization during Optuna model selection?

Fold-safe preprocessing normalization during Optuna model selection requires applying normalization independently within each split, ensuring preprocessing parameters are fitted only on the inner training data to prevent data leakage.