kerasnip: A Bridge Between ‘keras’ and ‘tidymodels’

Madrid R Group | February 2026

kerasnip v0.1.0.900

Docs: davidrsch.github.io/kerasnip · Repo: github.com/davidrsch/kerasnip

Open with energy. Ask: “Who loves tidymodels?” then “Who has fought with Keras architectures?”

Say: - Keras and tidymodels are like oil and water, kerasnip is the emulsifier. - Today: solving the architectural tuning problem.

Today

• Why tuning Keras inside tidymodels is hard
• What kerasnip generates and why it matters
• Sequential workflow: structural tuning with num_{block}
• Functional workflow: branch/merge graphs with inp_spec()

Keep this slide to 20 seconds. It is orientation, not content.

Say: - We will go from problem to working code quickly. - First half: sequential API. Second half: functional graphs. - There is a debug helper at the end that is worth knowing about.

The Landscape & The Gap

Keras (via keras3)

• Deep Learning
• Tensor-centric & imperative
• Backend agnostic (TF, JAX, Torch)
• Arbitrary graphs of layers

tidymodels

• Machine Learning
• Dataframe-centric & declarative
• Unified interface (fit, predict)
• Standardized tuning

The gap: tune_grid() handles learning rate easily, but tuning model structure: depth, width, branches; is awkward. parsnip expects a fixed set of named arguments; Keras models are arbitrary graphs.

Analogy: Keras = architect’s blank sheet; tidymodels = government form with fixed fields. kerasnip makes the forms fit the drawings.

Say: - You can already tune learning rate with keras3 + tidymodels. The friction is topology, which live in Keras code, not in named spec arguments. - kerasnip does not replace keras3. It generates new parsnip spec functions that use the existing keras engine. - One sentence on why not other packages: reticulate is too low-level, luz/brulee are Torch-only, parsnip::mlp() is too fixed for architecture search.

Transition: Let us see how kerasnip solves this, one diagram.

Mental Model

flowchart LR
  classDef step fill:#f5f7fa,stroke:#5c6b7a,color:#1b3a57,stroke-width:2px;
  classDef tune fill:#BF281B,stroke:#BF281B,color:#ffffff,stroke-width:2px;

  A["Blocks<br/>(plain R functions)"] --> B["Spec function<br/>create_keras_*_spec()"]
  B --> C["Workflow<br/>recipe() + workflow()"]
  C --> D["Tuning<br/>tune_grid()"]
  A -. "args → tunables<br/>num_{block} repeats" .-> B

  class A,B,C step;
  class D tune;

One rule: if you want to tune it, make it a function argument.

Spend about 60 seconds here. This diagram is the whole talk in one image.

Say: - You write plain R functions called blocks. Each block returns Keras layers. - create_keras_*spec() reads those functions and generates a new parsnip model. - From that point on it is standard tidymodels: recipe, workflow, tune_grid. - The dotted arrow is the key insight: block arguments automatically become tunable spec arguments, prefixed by block name. dense_block(units=128) becomes body_units. And num{block} controls how many times a block repeats, that is depth as a hyperparameter.

If someone gets lost: blocks → spec → workflow → tuning. Everything else is detail.

Transition: Let us build one. Sequential API first, predicting diamond prices.

Sequential Blocks

input_block <- function(model, input_shape) {
  keras_model_sequential(input_shape = input_shape)
}

dense_block <- function(model, units = 128, dropout = 0.0) {
  model |>
    layer_dense(units = units, activation = "relu") |>
    layer_dropout(rate = dropout)
}

output_block <- function(model) {
  model |> layer_dense(units = 1)
}

Say: - These are plain R functions. Nothing from kerasnip here yet. - The function signature is everything: units and dropout become tunable because they are arguments with defaults. - dense_block is the repeatable one, num_body will control how many times it stacks. - input and output blocks have no tunable args by design: input shape is fixed by the data, output is fixed by the task.

Point at the code while saying: “body_units comes from units here, body_dropout from dropout. The prefix body comes from the block name we will assign in the list on the next slide.”

Transition: Now pass these to create_keras_sequential_spec and we get a parsnip model.

Generate Spec + Structural Tuning

Register the spec

create_keras_sequential_spec(
  model_name = "diamond_mlp",
  layer_blocks = list(
    input  = input_block,
    body   = dense_block,  # repeatable
    output = output_block
  ),
  mode = "regression"
)

This creates diamond_mlp(), a standard parsnip model function.

Treat topology as a hyperparameter

spec <- diamond_mlp(
  num_body     = tune(),  # depth: 1, 2, 3…
  body_units   = tune(),  # width: 32, 64, 128…
  body_dropout = tune(),
  fit_epochs   = 20
) |>
  set_engine("keras")

num_body and body_units are auto-generated from the block name and its arguments.

Say: - Left: one call, one new parsnip model. That is all kerasnip does structurally. - Right: now depth is tune() just like any other hyperparameter. This is what was not possible before. - Point at num_body: this controls how many times dense_block stacks. Put tune() here and you are searching architecture space. - Point at body_units: the body_ prefix comes from naming the block “body” in the list on the left.

Transition: Now drop it into a standard workflow.

Diamonds Workflow

library(tidymodels)
library(kerasnip)
data(diamonds, package = "ggplot2")

diamonds_split <- initial_split(diamonds, strata = price)
diamonds_train <- training(diamonds_split)

diamonds_rec <- recipe(price ~ ., data = diamonds_train) |>
  step_dummy(all_nominal_predictors()) |>
  step_zv(all_predictors()) |>
  step_normalize(all_numeric_predictors())

wf <- workflow() |> add_recipe(diamonds_rec) |> add_model(spec)

params <- extract_parameter_set_dials(wf) |>
  update(
    num_body     = dials::num_terms(c(1, 4)),
    body_units   = dials::hidden_units(c(32, 256)),
    body_dropout = dials::dropout(c(0, 0.4))
  )

grid  <- grid_latin_hypercube(params, size = 20)
folds <- vfold_cv(diamonds_train, v = 5, strata = price)
res   <- tune_grid(wf, resamples = folds, grid = grid)

Say: - This is identical to any other tidymodels workflow. That is the point. - Recipe must output numeric matrices: step_dummy + step_normalize are required for Keras. - extract_parameter_set_dials discovers tunables automatically, you just update the ranges. - Practical tip: start with size = 8 when testing a new architecture. Scale up once you know it builds correctly.

Transition: Let us look at what came out.

Results (Diamonds): CV — Table

num_body	body_units	body_dropout	mean	std_err
2	62	0.060	767.101	57.202
2	35	0.180	775.932	45.765
2	49	0.030	782.881	51.891
2	98	0.121	783.726	54.377
1	127	0.276	842.246	45.535

Keep this slide to 30 seconds then move to the plot.

Say: - These are cross-validation estimates. We select on CV, never on the test set. - Look for a stable region: good mean RMSE and small std_err. That is the architecture to carry forward. - Pick the simplest within 1 std_err of the best, not necessarily the top row.

Results (Diamonds): CV — Plot

Say: - If lines flatten as num_body increases, going deeper is not buying anything, pick the shallower model. - Each facet is a dropout value: look for a panel where the spread between width options is small. That is a robust region.

Transition: One-time test confirmation.

Results (Diamonds): Test — Table

.metric	.estimate
rmse	736.1172
mae	349.0455
rsq	0.9660

Say: - Test is for reporting only. The architecture was chosen with CV, this is just confirmation. - If test is much worse than CV, suspect data leakage or an unstable architecture.

Results (Diamonds): Test — Plot

Say: - Points near the diagonal are good predictions. Systematic deviation below at high prices means the model underestimates expensive diamonds, expected, as those are rare in training data.

Transition: Before moving to functional, one slide on a tool that saves a lot of debugging pain.

Debugging: compile_keras_grid()

prep_rec <- prep(diamonds_rec, training = diamonds_train)
juiced <- juice(prep_rec)
x <- juiced |> select(-price)
y <- juiced$price
modified_grid <- tibble(
    num_body = c(3, 6),
    body_units = c(-10, 128),
    body_dropout = c(0.2, 0.2)
)

dbg <- compile_keras_grid(spec, modified_grid, x, y)
dbg

# A tibble: 2 × 5
  num_body body_units body_dropout compiled_model                          
     <dbl>      <dbl>        <dbl> <list>                                  
1        3        -10          0.2 <NULL>                                  
2        6        128          0.2 <keras.src.models.sequential.Sequential>
# ℹ 1 more variable: error <chr>

Say: - Before running tune_grid on 20 configurations, run this on one to confirm the model actually builds correctly. - The error column shows which grid rows failed and why, catch this before wasting compute. - extract_valid_grid() filters to successful builds; inform_errors() summarizes failures across the whole grid. - Rule: always compile before you tune.

Transition: Same workflow pattern, now with a non-linear graph. Functional API.

Functional API: Blocks + Graph

Blocks receive tensors, not models

input_block <- function(input_shape) {
  layer_input(shape = input_shape,
              name = "features")
}

dense_block <- function(tensor,
                        units = 64,
                        dropout = 0.0) {
  tensor |>
    layer_dense(units = units,
                activation = "relu") |>
    layer_dropout(rate = dropout)
}

concat_block <- function(input_a, input_b) {
  layer_concatenate(list(input_a, input_b))
}

output_block <- function(tensor, num_classes) {
  tensor |>
    layer_dense(units = num_classes,
                activation = "softmax")
}

inp_spec() wires outputs to inputs by name

create_keras_functional_spec(
  model_name = "attrition_towers",
  layer_blocks = list(
    main_input = input_block,
    tower_a    = inp_spec(
                   dense_block,
                   "main_input"),
    tower_b    = inp_spec(
                   dense_block,
                   "main_input"),
    joined     = inp_spec(
                   concat_block,
                   c(input_a = "tower_a",
                     input_b = "tower_b")),
    output     = inp_spec(
                   output_block,
                   "joined")
  ),
  mode = "classification"
)

Say: - Sequential: blocks receive a model and stack layers onto it. Functional: blocks receive tensors and return tensors. That is the only structural difference. - inp_spec(func, inputs) is just labeling which upstream output feeds which argument, like patch cables on a modular synth. - This graph: one input splits into two parallel towers, they concatenate, then output. Non-linear, but the workflow stays completely identical. - Use sequential for a straight chain. Use functional when you need branches, merges, or skip connections. - tower_a_units and tower_b_units are auto-generated by the same prefix convention as before.

Transition: Now the workflow, you will recognize every line.

Attrition Workflow

library(tidymodels)
library(modeldata)
data(attrition)

attr_split <- initial_split(attrition, strata = Attrition)
attr_train <- training(attr_split)

attr_rec <- recipe(Attrition ~ ., data = attr_train) |>
  step_zv(all_predictors()) |>
  step_dummy(all_nominal_predictors()) |>
  step_normalize(all_numeric_predictors())

attr_spec <- attrition_towers(
  tower_a_units = tune(),
  tower_b_units = tune(),
  fit_epochs    = 20
) |> set_engine("keras")

attr_wf <- workflow() |> add_recipe(attr_rec) |> add_model(attr_spec)

params <- extract_parameter_set_dials(attr_wf) |>
  update(tower_a_units = dials::hidden_units(c(16, 128)),
         tower_b_units = dials::hidden_units(c(16, 128)))

res <- tune_grid(attr_wf,
                 resamples = vfold_cv(attr_train, v = 3, strata = Attrition),
                 grid      = grid_latin_hypercube(params, size = 12))

Say: - Identical pattern to the sequential example. That is the whole point of kerasnip, the graph complexity is completely hidden. - Make sure the outcome is a factor with stable levels.

Transition: Results.

Results (Attrition): CV — Table

tower_a_units	tower_b_units	mean	std_err
70	64	0.8048	0.0218
41	33	0.8017	0.0239
47	24	0.7974	0.0185
21	105	0.7955	0.0278
80	95	0.7926	0.0219

Keep this slide to 30 seconds then move to the heatmap.

Say: - Same reading as before: mean ROC AUC plus std_err. Select on CV. - Pick the simplest architecture within 1 std_err of the best.

Results (Attrition): CV — Plot

Say: - A flat heatmap means the architecture is robust, tower size does not matter much, pick the smallest. - A sharp peak means the model is sensitive to tower sizes, worth narrowing the search around that region in a second pass.

Transition: Final test confirmation.

Results (Attrition): Test — Table

.metric	.estimate
accuracy	0.8699
roc_auc	0.8232

Say: - On imbalanced datasets like attrition, ROC AUC is more informative than accuracy, accuracy can look fine just by predicting the majority class. - Again: test is for reporting, not for deciding.

Results (Attrition): Test — Plot

Say: - Further from the diagonal = better discrimination. - When two architectures give similar curves, always pick the simpler one.

Transition: Close with the practical summary.

Practical Tips & Trade-offs

To avoid pain

• Always run compile_keras_grid() before tuning
• Keep blocks small and testable, isolate errors with 2–3 blocks
• Tune structure (depth/width) first; training hyperparameters later
• Keep search spaces reasonable, depth × width explodes fast

Why it is worth it

1. Workflow parity — recipes, workflows, tune work exactly like with glmnet
2. Reproducibility — topology is code; version-control your architecture
3. Extensibility — wrap any Keras layer (Transformers, RNNs) into a block

Goal: leave people with a clear answer to “should I try this?”

Say: - The learning curve is writing good blocks. After that, everything is standard tidymodels. - If you already use tidymodels, the only new concept is defining blocks and calling create_keras_*_spec(). - Package is on GitHub, contributions and feedback welcome.

Stop sharing screen and open Q&A.

Resources

• 📦 github.com/davidrsch/kerasnip
• 📑 davidrsch.github.io/kerasnip
• 📑 Slides