ModelBuilder¶

ModelBuilder provides an educational, intuitive interface for building neural network architectures — similar to Keras, but with built-in explanations.

What is ModelBuilder?¶

ModelBuilder lets you:

Build neural networks layer by layer
Understand what each layer does
Get explanations and best-practice suggestions
Use pre-built templates for common tasks

Quick Start¶

from neurogebra import ModelBuilder

builder = ModelBuilder()

# Build a simple classifier
model = builder.Sequential([
    builder.Dense(128, activation="relu"),
    builder.Dropout(0.2),
    builder.Dense(64, activation="relu"),
    builder.Dense(10, activation="softmax")
])

# See what you built
model.summary()

Layer Types¶

Dense (Fully Connected)¶

Every neuron connects to every neuron in the next layer.

# Basic dense layer
layer = builder.Dense(128, activation="relu")

# With input shape (first layer only)
first_layer = builder.Dense(128, activation="relu", input_shape=(784,))

# Learn what it does
layer.explain()

Output of explain():

📚 DENSE Layer
   Fully connected layer - every neuron connects to every neuron in next layer

   Best used for:
   • Classification
   • Regression
   • Final output layer

   Neurons/Units: 128
   Activation: relu

Dropout¶

Randomly deactivates neurons during training to prevent overfitting.

dropout = builder.Dropout(rate=0.2)  # Drop 20% of neurons
dropout.explain()

Conv2D (Convolutional)¶

Detects patterns in images using sliding filters.

conv = builder.Conv2D(filters=32, kernel_size=3, activation="relu")
conv.explain()

MaxPooling2D¶

Reduces image dimensions by taking maximum values in regions.

pool = builder.MaxPooling2D(pool_size=2)
pool.explain()

Flatten¶

Converts multi-dimensional data to 1D for dense layers.

flatten = builder.Flatten()

BatchNorm¶

Normalizes layer outputs to stabilize training.

bn = builder.BatchNorm()
bn.explain()

Building Models¶

Sequential Model¶

Layers stacked one after another:

# Simple classifier
classifier = builder.Sequential([
    builder.Dense(128, activation="relu"),
    builder.Dropout(0.2),
    builder.Dense(64, activation="relu"),
    builder.Dense(10, activation="softmax")
], name="my_classifier")

classifier.summary()

From Template¶

Use pre-built architectures:

# See available templates
builder.list_templates()

# Create from template
model = builder.from_template("simple_classifier")
model.summary()

# Other templates:
# - "simple_classifier"  → Basic dense network
# - "image_classifier"   → CNN for images
# - "regression"         → For predicting numbers
# - "binary_classifier"  → For yes/no tasks

Model Templates¶

Simple Classifier¶

model = builder.from_template("simple_classifier")
model.explain_architecture()

Architecture:

Dense(128, relu) → Dropout(0.2) → Dense(64, relu) → Dense(10, softmax)

Image Classifier (CNN)¶

model = builder.from_template("image_classifier")
model.explain_architecture()

Architecture:

Conv2D(32) → MaxPool → Conv2D(64) → MaxPool → Flatten → Dense(128) → Dense(10)

Regression Network¶

model = builder.from_template("regression")

Architecture:

Dense(64, relu) → Dense(32, relu) → Dense(1, linear)

Binary Classifier¶

model = builder.from_template("binary_classifier")

Architecture:

Dense(64, relu) → Dropout(0.3) → Dense(32, relu) → Dense(1, sigmoid)

Architecture Suggestions¶

ModelBuilder can suggest architectures based on your task:

# Get suggestion for a task
builder.suggest_architecture(
    task="classification",
    input_size=784,
    output_size=10
)

Understanding Your Model¶

Summary¶

model.summary()

Shows the layer structure with types, units, and activations.

Explain Architecture¶

model.explain_architecture()

Gives plain-English explanation of what each layer does and why it's there.

Building an Image Classifier Step by Step¶

from neurogebra import ModelBuilder

builder = ModelBuilder()

# Step 1: Feature extraction (convolutions)
# Step 2: Dimensionality reduction (pooling)
# Step 3: Classification (dense layers)

model = builder.Sequential([
    # Feature extraction
    builder.Conv2D(32, kernel_size=3, activation="relu"),
    builder.MaxPooling2D(pool_size=2),
    builder.Conv2D(64, kernel_size=3, activation="relu"),
    builder.MaxPooling2D(pool_size=2),

    # Bridge
    builder.Flatten(),

    # Classification
    builder.Dense(128, activation="relu"),
    builder.Dropout(0.5),
    builder.Dense(10, activation="softmax")
], name="mnist_classifier")

# Understand it
model.summary()
model.explain_architecture()

Layer Selection Guide¶

Task	Layers to Use
Tabular data classification	Dense → Dropout → Dense → Softmax
Image classification	Conv2D → MaxPool → Dense → Softmax
Binary classification	Dense → Dense → Dense(1) → Sigmoid
Regression	Dense → Dense → Dense(1) → Linear

Layer	When to Use
Dense	Always (at least for the output)
Dropout	When you have overfitting
Conv2D	For images/spatial data
MaxPooling2D	After Conv2D to reduce size
Flatten	Between Conv and Dense
BatchNorm	For deeper networks to stabilize training

Next: NeuroCraft Interface →