UI Components API

Reusable Streamlit components for building ML training interfaces

Overview

The UI components API provides pre-built, reusable Streamlit components for building consistent and interactive ML training interfaces, including headers, sidebars, model cards, and experiment rows.

Header Component

render_header()

Render the persistent header section shown on all pages. Contains app title, session selector, configuration status indicators, and session controls.

from components.header import render_header

render_header()

Features:

• App title and branding
• Configuration status indicators (Dataset, Model, Training)
• Session selector dropdown (with past sessions)
• New session button

File reference: app/components/header.py:23

Configuration Status Indicators:

• ✅ Green checkmark = Step completed
• ⬜ Gray box = Step not completed

import streamlit as st
from components.header import render_header

st.set_page_config(page_title="My ML App", layout="wide")
render_header()

Sidebar Component

render_sidebar()

Render the persistent sidebar shown on all pages. Displays system resources, theme settings, and session actions.

from components.sidebar import render_sidebar

render_sidebar()

Features:

• Compute device information (CUDA/MPS/CPU)
• GPU memory usage
• System RAM usage
• CPU cores and threads
• Platform information
• Theme customization settings
• Delete session button

File reference: app/components/sidebar.py:18

Example:

import streamlit as st
from components.sidebar import render_sidebar

st.set_page_config(layout="wide")

with st.sidebar:
    render_sidebar()

Model Card Component

render_model_card(model, on_edit, on_delete, is_selected)

Render a single model card with actions.

model · dict · required

Model dictionary with id, name, model_type, created_at, and config

on_edit · callable · default: "None"

Callback function when edit button is clicked (receives model_id)

on_delete · callable · default: "None"

Callback function when delete button is clicked (receives model_id)

is_selected · bool · default: "False"

Whether this card is currently selected

from components.model_card import render_model_card

model = {
    "id": "model_a3f8b2c1",
    "name": "ResNet50 Transfer",
    "model_type": "Transfer Learning",
    "created_at": "2026-03-04T10:30:00",
    "config": {
        "transfer_config": {
            "base_model": "ResNet50",
            "strategy": "Fine-tuning"
        }
    }
}

def handle_edit(model_id):
    print(f"Editing model: {model_id}")

def handle_delete(model_id):
    print(f"Deleting model: {model_id}")

clicked = render_model_card(
    model,
    on_edit=handle_edit,
    on_delete=handle_delete,
    is_selected=True
)

if clicked:
    print("Card was clicked for selection")

Returns: bool - True if the card was clicked (for selection)

File reference: app/components/model_card.py:17

Model Card Visual Features:

• Model type icon (🔧 Custom CNN, 🎯 Transfer Learning, 🧪 Transformer)
• Model name and type
• Creation date
• Configuration summary subtitle
• Select, Edit, and Delete buttons
• Green border when selected

render_model_library(models, selected_id, on_select, on_edit, on_delete, cards_per_row)

Render the full model library as a grid of cards.

models · list[dict] · required

List of model dictionaries

selected_id · str | None · default: "None"

Currently selected model ID

on_select · callable · default: "None"

Callback when a model is selected (receives model_id)

on_edit · callable · default: "None"

Callback when edit button is clicked (receives model_id)

on_delete · callable · default: "None"

Callback when delete button is clicked (receives model_id)

cards_per_row · int · default: "3"

Number of cards to display per row

from components.model_card import render_model_library
from state.workflow import get_model_library

models = get_model_library()

def handle_select(model_id):
    st.session_state.selected_model = model_id
    st.rerun()

render_model_library(
    models=models,
    selected_id=st.session_state.get("selected_model"),
    on_select=handle_select,
    cards_per_row=3
)

File reference: app/components/model_card.py:116

Experiment Row Component

render_experiment_row(experiment, models, trainings, callbacks…)

Render a single experiment row with status, metrics, and action buttons.

experiment · dict · required

Experiment dictionary with id, name, model_id, training_id, status, and metrics

models · list[dict] · required

List of available model configurations

trainings · list[dict] · required

List of available training configurations

on_update · callable · default: "None"

Callback when experiment configuration changes (receives exp_id, updates)

on_delete · callable · default: "None"

Callback to delete experiment (receives exp_id)

on_start · callable · default: "None"

Callback to start/resume training (receives exp_id)

on_pause · callable · default: "None"

Callback to pause training (receives exp_id)

on_stop · callable · default: "None"

Callback to stop training (receives exp_id)

on_view_results · callable · default: "None"

Callback to view results (receives exp_id)

from components.experiment_row import render_experiment_row
from state.workflow import get_experiments, get_model_library, get_training_library

experiments = get_experiments()
models = get_model_library()
trainings = get_training_library()

def handle_start(exp_id):
    # Start training logic
    pass

def handle_delete(exp_id):
    from state.workflow import delete_experiment
    delete_experiment(exp_id)
    st.rerun()

for exp in experiments:
    render_experiment_row(
        experiment=exp,
        models=models,
        trainings=trainings,
        on_start=handle_start,
        on_delete=handle_delete
    )

File reference: app/components/experiment_row.py:18

Experiment Status Icons:

• ⚪ Ready - Ready to start training
• 🔄 Training - Currently training
• ⏸️ Paused - Training paused
• ✅ Completed - Training finished successfully
• ❌ Failed - Training failed with error

Dynamic Features by Status:

Ready Status:

• Model and training config dropdowns
• START TRAINING button
• Delete button

Training Status:

• Progress bars (epoch and batch)
• Live metrics (train loss, train acc, val loss, val acc)
• Delta indicators showing improvement
• Pause, Stop, and Save buttons

Completed Status:

• Final metrics display
• Best epoch indicator
• Training duration
• View Results button
• Delete button

Theme Component

render_theme_settings()

Render theme customization settings in an expander.

from components.theme import render_theme_settings

with st.sidebar:
    render_theme_settings()

Features:

• Color pickers for primary, secondary, and background colors
• Preset themes (Soft Green, Soft Blue, Soft Pink, Soft Orange)
• Live preview with automatic page rerun

File reference: app/components/theme.py:18

Example with Custom Colors:

from state.ui import set_theme_colors

# Set custom theme programmatically
set_theme_colors(
    primary="#FF6B6B",
    secondary="#4ECDC4",
    background="#1A1A2E"
)

Utility Functions

get_compute_device()

Detect available compute device with detailed information.

from components.utils import get_compute_device

device = get_compute_device()
print(f"Type: {device['type']}")  # "CUDA", "MPS", or "CPU"
print(f"Name: {device['name']}")  # "NVIDIA RTX 3080", "Apple M1", etc.
print(f"Available: {device['available']}")  # True/False

Returns: dict with keys:

• type: str - Device type (“CUDA”, “MPS”, or “CPU”)
• name: str - Device name
• available: bool - Whether device is available

File reference: app/components/utils.py:15

get_gpu_memory()

Get GPU memory information if available.

from components.utils import get_gpu_memory

memory = get_gpu_memory()
print(memory)  # "4.2/8.0 GB" or "Unified" (MPS) or "N/A"

Returns: str - Formatted memory string

File reference: app/components/utils.py:61

get_system_memory()

Get system RAM information.

from components.utils import get_system_memory

memory = get_system_memory()
print(memory)  # "8.4/16.0 GB"

Returns: str - Formatted memory string (used/total GB)

File reference: app/components/utils.py:77

get_cpu_info()

Get CPU information including cores, threads, and usage.

from components.utils import get_cpu_info

info = get_cpu_info()
print(f"Cores: {info['cores']}")  # Physical cores
print(f"Threads: {info['threads']}")  # Logical processors
print(f"Usage: {info['usage']}%")  # Current CPU usage

Returns: dict with keys:

• cores: int - Physical CPU cores
• threads: int - Logical processors
• usage: float - Current CPU usage percentage

File reference: app/components/utils.py:88

get_platform_info()

Get platform/OS information.

from components.utils import get_platform_info

platform = get_platform_info()
print(platform)  # "macOS 14.0", "Linux", "Windows 11", etc.

Returns: str - Platform string

File reference: app/components/utils.py:100

clear_session()

Clear all session state (workflow + cache) while preserving UI preferences. Saves the current session to disk before clearing.

from components.utils import clear_session

clear_session()
# Session saved, state cleared, and reinitialized

File reference: app/components/utils.py:124

Tooltips

Pre-defined tooltip messages for UI components:

from components.tooltips import HEADER_TOOLTIPS, SIDEBAR_TOOLTIPS

# Header tooltips
HEADER_TOOLTIPS = {
    "new_session": "Create a new session and start fresh"
}

# Sidebar tooltips
SIDEBAR_TOOLTIPS = {
    "system_resources": "Hardware resources available for training",
    "gpu_memory": "GPU memory usage (allocated/total)",
    "system_ram": "System RAM usage",
    "cpu_info": "CPU cores and threads",
    "platform": "Operating system information"
}

Usage Example:

import streamlit as st
from components.tooltips import SIDEBAR_TOOLTIPS

st.caption("GPU Memory", help=SIDEBAR_TOOLTIPS["gpu_memory"])

Model Icons

Icon mappings for different model types:

from components.model_card import MODEL_ICONS

# Available model icons
MODEL_ICONS = {
    "Custom CNN": "🔧",
    "Transformer": "🧪",
    "Transfer Learning": "🎯",
}

# Usage
icon = MODEL_ICONS.get(model_type, "🧠")  # Default to brain emoji

Experiment Status Configuration

Status configuration for experiment rows:

from components.experiment_row import STATUS_CONFIG

# Available status configurations
STATUS_CONFIG = {
    "ready": {"icon": "⚪", "label": "Ready", "color": "gray"},
    "training": {"icon": "🔄", "label": "Training", "color": "blue"},
    "paused": {"icon": "⏸️", "label": "Paused", "color": "orange"},
    "completed": {"icon": "✅", "label": "Completed", "color": "green"},
    "failed": {"icon": "❌", "label": "Failed", "color": "red"},
}

# Usage
status = "training"
config = STATUS_CONFIG.get(status)
st.markdown(f"{config['icon']} {config['label']}")