Keras Sequential vs Functional API — Which to Use and When

# io.thecodeforge.keras.sequential_vs_functional.sequential_example

import keras
from keras import layers

# Sequential API — pass a list of layers to the constructor
# This is equivalent to calling model.add() for each layer in order
model = keras.Sequential([
    layers.Input(shape=(784,)),          # Always include Input() — enables shape propagation from the start
    layers.Dense(256, activation='relu'),
    layers.Dropout(0.3),
    layers.Dense(128, activation='relu'),
    layers.Dropout(0.3),
    layers.Dense(10, activation='softmax'),
], name='mnist_classifier')

model.compile(
    optimizer='adam',
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy']
)
model.summary()

# Equivalent using model.add() — same result, different style
# Some teams prefer this for conditional layer addition during setup
model_v2 = keras.Sequential(name='mnist_classifier_v2')
model_v2.add(layers.Input(shape=(784,)))
model_v2.add(layers.Dense(256, activation='relu'))
model_v2.add(layers.Dropout(0.3))
model_v2.add(layers.Dense(128, activation='relu'))
model_v2.add(layers.Dropout(0.3))
model_v2.add(layers.Dense(10, activation='softmax'))

# Both models have identical architectures and would produce identical weights
# after training on the same data with the same random seed
print(f"model   params: {model.count_params():,}")
print(f"model_v2 params: {model_v2.count_params():,}")
print(f"Architectures identical: {model.count_params() == model_v2.count_params()}")

# io.thecodeforge.keras.sequential_vs_functional.functional_example

import keras
from keras import layers

# ── SIMPLE FUNCTIONAL MODEL — same architecture as Sequential example ───────
# This demonstrates that Functional can express everything Sequential can
# while also being able to express things Sequential cannot

inputs = keras.Input(shape=(784,), name='image_flat')

x = layers.Dense(256, activation='relu', name='dense_1')(inputs)
x = layers.Dropout(0.3, name='dropout_1')(x)
x = layers.Dense(128, activation='relu', name='dense_2')(x)
x = layers.Dropout(0.3, name='dropout_2')(x)
outputs = layers.Dense(10, activation='softmax', name='predictions')(x)

model = keras.Model(inputs=inputs, outputs=outputs, name='mnist_functional')

model.compile(
    optimizer='adam',
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy']
)
model.summary()

# ── MULTI-INPUT FUNCTIONAL MODEL — impossible with Sequential ───────────────
# Example: fusing image features with metadata for a richer prediction
image_input    = keras.Input(shape=(224, 224, 3), name='image')
metadata_input = keras.Input(shape=(12,), name='metadata')   # e.g. timestamp, location encoding

# Image branch — a simple CNN backbone for illustration
image_features = layers.Conv2D(32, 3, activation='relu')(image_input)
image_features = layers.GlobalAveragePooling2D()(image_features)
image_features = layers.Dense(64, activation='relu')(image_features)

# Metadata branch — simpler processing
meta_features  = layers.Dense(16, activation='relu')(metadata_input)

# Merge both branches
combined       = layers.Concatenate()([image_features, meta_features])
combined       = layers.Dense(64, activation='relu')(combined)
predictions    = layers.Dense(5, activation='softmax', name='class_output')(combined)

multi_input_model = keras.Model(
    inputs=[image_input, metadata_input],   # both inputs declared here
    outputs=predictions,
    name='image_plus_metadata_model'
)

print(f"\nMulti-input model inputs: {[i.name for i in multi_input_model.inputs]}")
print(f"Parameters: {multi_input_model.count_params():,}")

# io.thecodeforge.keras.sequential_vs_functional.subclassing_example

import keras
from keras import layers

class ResidualBlock(keras.Model):
    """A single residual block — a natural Subclassing use case because
    the block encapsulates reusable internal logic with its own layer state.
    
    Note: for a full static model, you'd wire these blocks together with
    the Functional API. Subclassing the block itself is the right boundary.
    """
    def __init__(self, filters, use_projection=False):
        super().__init__()
        self.conv1 = layers.Conv2D(filters, 3, padding='same', activation='relu')
        self.conv2 = layers.Conv2D(filters, 3, padding='same')
        self.bn1   = layers.BatchNormalization()
        self.bn2   = layers.BatchNormalization()
        self.relu  = layers.Activation('relu')

        # Optional projection shortcut when input/output channels differ
        self.use_projection = use_projection
        if use_projection:
            self.projection = layers.Conv2D(filters, 1, padding='same')

    def call(self, inputs, training=False):
        shortcut = inputs

        x = self.conv1(inputs)
        x = self.bn1(x, training=training)
        x = self.conv2(x)
        x = self.bn2(x, training=training)

        if self.use_projection:
            shortcut = self.projection(inputs)

        # This Add is why we need Subclassing — conditional shortcut projection
        # makes the graph topology depend on a constructor argument
        return self.relu(x + shortcut)


class SimpleClassifier(keras.Model):
    """A classifier using the residual block above.
    Uses Subclassing here only because the forward pass contains
    a training-conditional dropout rate — otherwise Functional would be better.
    """
    def __init__(self, num_classes, dropout_rate=0.3):
        super().__init__()
        self.conv_stem     = layers.Conv2D(32, 3, activation='relu', padding='same')
        self.residual_1    = ResidualBlock(32)
        self.residual_2    = ResidualBlock(64, use_projection=True)  # conditional projection
        self.pool          = layers.GlobalAveragePooling2D()
        self.dropout       = layers.Dropout(dropout_rate)
        self.classifier    = layers.Dense(num_classes, activation='softmax')

    def call(self, inputs, training=False):
        x = self.conv_stem(inputs)
        x = self.residual_1(x, training=training)
        x = self.residual_2(x, training=training)
        x = self.pool(x)
        x = self.dropout(x, training=training)  # training flag passed explicitly
        return self.classifier(x)


model = SimpleClassifier(num_classes=10, dropout_rate=0.4)
model.compile(
    optimizer='adam',
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy']
)

# Build with concrete shapes so summary() shows layer dimensions
model.build(input_shape=(None, 32, 32, 3))
print(f"Parameters: {model.count_params():,}")

# io.thecodeforge.keras.sequential_vs_functional.transfer_learning_example

import keras
from keras import layers
import numpy as np

# Simulate training data — replace with your actual data pipeline
X_train = np.random.rand(200, 224, 224, 3).astype(np.float32)
y_train = np.random.randint(0, 10, size=(200,))

# Load pretrained backbone — include_top=False removes the original classifier head
# The returned model is built with the Functional API
base_model = keras.applications.ResNet50(
    weights='imagenet',
    include_top=False,
    input_shape=(224, 224, 3)
)

print(f"Backbone layers: {len(base_model.layers)}")
print(f"Backbone params: {base_model.count_params():,}")

# ── PHASE 1: Freeze backbone, train only the new head ──────────────────────
# This must come BEFORE compiling — the trainable flag is read at compile time
base_model.trainable = False

# Add custom classification head using Functional API
# base_model.input and base_model.output are standard Functional API tensors
x = base_model.output
x = layers.GlobalAveragePooling2D(name='gap')(x)
x = layers.Dense(256, activation='relu', name='head_dense')(x)
x = layers.Dropout(0.4, name='head_dropout')(x)
outputs = layers.Dense(10, activation='softmax', name='predictions')(x)

model = keras.Model(
    inputs=base_model.input,
    outputs=outputs,
    name='resnet_transfer'
)

trainable_in_phase1 = sum(1 for l in model.layers if l.trainable)
print(f"\nPhase 1 — trainable layers: {trainable_in_phase1} of {len(model.layers)}")

model.compile(
    optimizer=keras.optimizers.Adam(learning_rate=1e-3),
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy']
)

model.fit(X_train, y_train, epochs=3, batch_size=16, verbose=1)

# ── PHASE 2: Unfreeze top layers, fine-tune with very low LR ───────────────
# Enable backbone training
base_model.trainable = True

# Freeze all layers except the top 20 — preserve low-level features
# that transfer well (edges, textures) while adapting high-level representations
for layer in base_model.layers[:-20]:
    layer.trainable = False

trainable_in_phase2 = sum(1 for l in model.layers if l.trainable)
print(f"\nPhase 2 — trainable layers: {trainable_in_phase2} of {len(model.layers)}")

# CRITICAL: always recompile after changing trainable flags
# The optimiser needs to know which parameters to track
model.compile(
    optimizer=keras.optimizers.Adam(learning_rate=1e-5),  # 100x lower than Phase 1
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy']
)

model.fit(X_train, y_train, epochs=5, batch_size=16, verbose=1)

print(f"\nFinal model params: {model.count_params():,}")
print(f"Final trainable params: {sum(np.prod(w.shape) for w in model.trainable_weights):,}")

# io.thecodeforge.keras.sequential_vs_functional.api_decision_example
# Demonstrates that Sequential and Functional produce identical models
# for the same linear architecture — confirming zero performance difference

import keras
from keras import layers
import numpy as np

# ── SAME ARCHITECTURE expressed two ways ────────────────────────────────────

# Sequential version
seq_model = keras.Sequential([
    layers.Input(shape=(20,)),
    layers.Dense(64, activation='relu'),
    layers.Dense(32, activation='relu'),
    layers.Dense(1, activation='sigmoid'),
], name='sequential_version')

# Functional version — identical architecture
inputs = keras.Input(shape=(20,))
x = layers.Dense(64, activation='relu')(inputs)
x = layers.Dense(32, activation='relu')(x)
outputs = layers.Dense(1, activation='sigmoid')(x)
func_model = keras.Model(inputs, outputs, name='functional_version')

# Verify identical parameter counts
print(f"Sequential params : {seq_model.count_params():,}")
print(f"Functional params : {func_model.count_params():,}")
print(f"Identical         : {seq_model.count_params() == func_model.count_params()}")

# ── CAPABILITY BOUNDARY — what Sequential cannot do ─────────────────────────

# This is the architecture Sequential cannot express:
# A model with a residual connection (shortcut from input to output)
skip_input   = keras.Input(shape=(64,), name='residual_demo_input')
processed    = layers.Dense(64, activation='relu')(skip_input)  # transform
processed    = layers.Dense(64)(processed)                      # second transform
shortcut     = skip_input                                        # hold original
merged       = layers.Add()([processed, shortcut])               # residual add
merged       = layers.Activation('relu')(merged)
resid_output = layers.Dense(10, activation='softmax')(merged)

residual_model = keras.Model(skip_input, resid_output, name='residual_model')
print(f"\nResidual model params: {residual_model.count_params():,}")
print("Residual model is impossible to express with Sequential API")

# ── VISUAL CONFIRMATION ─────────────────────────────────────────────────────
keras.utils.plot_model(
    residual_model,
    to_file='residual_model.png',
    show_shapes=True,
    show_layer_names=True
)
print("Graph saved to residual_model.png — the Add() merge is visible")

# io.thecodeforge.keras.sequential_vs_functional.debugging_example

import keras
from keras import layers

# ── ERROR 1: Graph disconnected — missing input in keras.Model() ─────────────
print("=== Demonstrating Graph Disconnected Error ===")

input_a = keras.Input(shape=(128,), name='branch_a')
input_b = keras.Input(shape=(64,),  name='branch_b')

branch_a_out = layers.Dense(64, activation='relu')(input_a)
branch_b_out = layers.Dense(64, activation='relu')(input_b)

merged = layers.Concatenate()([branch_a_out, branch_b_out])
output = layers.Dense(10, activation='softmax')(merged)

# WRONG: input_b is missing from the inputs list — will raise graph disconnected error
try:
    bad_model = keras.Model(inputs=input_a, outputs=output)  # input_b not listed!
except Exception as e:
    print(f"Expected error: {type(e).__name__}: {str(e)[:100]}...")

# CORRECT: both input tensors in the list
good_model = keras.Model(inputs=[input_a, input_b], outputs=output)
print(f"Correct model inputs: {[i.name for i in good_model.inputs]}")

# ── ERROR 2: None dimensions in Sequential — missing Input() layer ──────────
print("\n=== Sequential Without Input() — None Dimensions ===")

bad_sequential = keras.Sequential([
    layers.Dense(64, activation='relu'),   # No Input() — shapes are unknown
    layers.Dense(10, activation='softmax')
])
print("Without Input():")
bad_sequential.summary()  # Output Shape column shows (None, None)

good_sequential = keras.Sequential([
    layers.Input(shape=(784,)),             # Input() added — shapes now propagate
    layers.Dense(64, activation='relu'),
    layers.Dense(10, activation='softmax')
])
print("\nWith Input():")
good_sequential.summary()  # Output Shape column shows concrete dimensions

# ── ERROR 3: Weight sharing — wrong approach vs correct approach ─────────────
print("\n=== Weight Sharing: Wrong vs Correct ===")

siamese_input_a = keras.Input(shape=(100,), name='left')
siamese_input_b = keras.Input(shape=(100,), name='right')

# WRONG: two separate Dense layers — double the parameters, not weight sharing
out_a_wrong = layers.Dense(64)(siamese_input_a)  # creates Dense layer #1
out_b_wrong = layers.Dense(64)(siamese_input_b)  # creates Dense layer #2 — DIFFERENT WEIGHTS
bad_siamese = keras.Model([siamese_input_a, siamese_input_b],
                           layers.Concatenate()([out_a_wrong, out_b_wrong]))
print(f"Wrong Siamese params: {bad_siamese.count_params():,}  (64*100+64 for each branch = two separate layers)")

# CORRECT: one layer object, called twice — same weights used in both branches
shared_encoder = layers.Dense(64, name='shared_encoder')  # ONE layer object
out_a_correct  = shared_encoder(siamese_input_a)           # call #1 — uses shared weights
out_b_correct  = shared_encoder(siamese_input_b)           # call #2 — same weights, accumulated gradients
good_siamese   = keras.Model([siamese_input_a, siamese_input_b],
                              layers.Concatenate()([out_a_correct, out_b_correct]))
print(f"Correct Siamese params: {good_siamese.count_params():,}  (one set of 64*100+64 shared weights)")

# Verify visually
keras.utils.plot_model(good_siamese, 'siamese.png', show_shapes=True, show_layer_names=True)
print("\nSiamese graph saved — shared_encoder node should appear once with two connections")

# io.thecodeforge.keras.sequential_vs_functional.autoencoder_example

import keras
from keras import layers
import numpy as np

# ── BUILD THE GRAPH — define layers and connect tensors ─────────────────────
encoder_input = keras.Input(shape=(784,), name='original_image')

# Encoder path — progressively compress the representation
encoded = layers.Dense(256, activation='relu', name='enc_256')(encoder_input)
encoded = layers.Dense(128, activation='relu', name='enc_128')(encoded)
latent  = layers.Dense(32,  activation='relu', name='latent')(encoded)  # 32-dim bottleneck

# Decoder path — reconstruct from the latent representation
decoded = layers.Dense(128, activation='relu', name='dec_128')(latent)
decoded = layers.Dense(256, activation='relu', name='dec_256')(decoded)
reconstructed = layers.Dense(784, activation='sigmoid', name='reconstructed')(decoded)

# ── CREATE MULTIPLE MODELS FROM THE SAME GRAPH ──────────────────────────────
# The autoencoder: input → encoder → decoder → reconstruction
autoencoder = keras.Model(
    inputs=encoder_input,
    outputs=reconstructed,
    name='autoencoder'
)

# The encoder only: input → latent representation
# This reuses the SAME layer objects — no weight copying, no new parameters
encoder = keras.Model(
    inputs=encoder_input,
    outputs=latent,
    name='encoder'
)

print("=== Model Parameter Counts ===")
print(f"Autoencoder params: {autoencoder.count_params():,}")
print(f"Encoder params:     {encoder.count_params():,}")
print(f"Encoder is subset:  {encoder.count_params() < autoencoder.count_params()}")
print()

# Compile and train the autoencoder — unsupervised, input = target
autoencoder.compile(
    optimizer='adam',
    loss='binary_crossentropy'
)

# Generate synthetic data for demonstration
X_demo = np.random.rand(500, 784).astype(np.float32)
autoencoder.fit(X_demo, X_demo, epochs=3, batch_size=32, verbose=1)

print("\n=== Using the Encoder After Training ===")
# Training the autoencoder updated the encoder's weights — automatically
# because they share the same layer objects — no sync needed
X_sample = X_demo[:5]
latent_vectors = encoder.predict(X_sample, verbose=0)
print(f"Input shape:        {X_sample.shape}")
print(f"Latent shape:       {latent_vectors.shape}")
print(f"Compression ratio:  {X_sample.shape[1] / latent_vectors.shape[1]:.0f}x")

# Verify shared weights: the encoder's output is the same as
# getting the intermediate tensor from the autoencoder
auto_latent = keras.Model(
    inputs=encoder_input,
    outputs=autoencoder.get_layer('latent').output
).predict(X_sample, verbose=0)

import numpy as np
print(f"\nEncoder vs autoencoder intermediate: outputs match = {np.allclose(latent_vectors, auto_latent)}")
print("This confirms shared weights — same layer objects, same computation")