Streamlit for Data Apps: Build Interactive Dashboards in Pure Python

import streamlit as st
import datetime

# io.thecodeforge: Tracking the execution lifecycle
# This line runs EVERY time the user interacts with anything in the app.
st.write(f"Script last ran at: {datetime.datetime.now().strftime('%H:%M:%S')}")

st.title("Understanding Streamlit's Re-Run Model")

# When the user moves this slider, the ENTIRE script above AND below re-executes.
temperature_celsius = st.slider(
    label="Set temperature (°C)",
    min_value=-20,
    max_value=50,
    value=22
)

temperature_fahrenheit = (temperature_celsius * 9 / 5) + 32

st.metric(
    label="Temperature in Fahrenheit",
    value=f"{temperature_fahrenheit:.1f} °F",
    delta=f"{temperature_celsius} °C input"
)

if temperature_celsius > 35:
    st.warning("That's dangerously hot. Stay hydrated and limit outdoor exposure.")
elif temperature_celsius < 0:
    st.info("Below freezing — roads may be icy. Check local transport advisories.")
else:
    st.success("Comfortable temperature range.")

import streamlit as st
import pandas as pd
import time

# ── CACHING DATA (io.thecodeforge standard) ───────────────────────────────────
@st.cache_data(ttl=3600)  # Cache expires after 1 hour — reduces DB load significantly
def load_sales_data(num_records: int) -> pd.DataFrame:
    """
    Simulates a slow data fetch. With @st.cache_data, this only
    runs once per hour regardless of how many times the user
    interacts with widgets.
    """
    time.sleep(2)  # Simulated network/DB latency
    return pd.DataFrame({
        "record_id": range(num_records),
        "revenue": [i * 1.5 for i in range(num_records)]
    })

# ── CACHING RESOURCES ─────────────────────────────────────────────────────────
@st.cache_resource
def init_connection():
    """
    @st.cache_resource is for non-serializable infrastructure.
    This object is created once and shared across all user sessions.
    Use it for DB pools and ML models — never for DataFrames.
    """
    return {"status": "connected", "provider": "ForgeCloud"}

# ── SESSION STATE ─────────────────────────────────────────────────────────────
# Always guard initialization — without this check, state resets on every re-run.
if "analysis_count" not in st.session_state:
    st.session_state.analysis_count = 0

st.title("Forge Analytics Dashboard")

col1, col2 = st.columns([3, 1])
with col1:
    record_count = st.slider("Number of records to load", 100, 10000, 1000)
with col2:
    st.metric("Analyses Run", st.session_state.analysis_count)

if st.button("Run Analysis"):
    st.session_state.analysis_count += 1
    df = load_sales_data(record_count)  # Cached — will not re-query on every click
    st.dataframe(df.head(10))
    st.write(f"Analysis #{st.session_state.analysis_count} complete. Loaded {len(df)} records.")

conn = init_connection()  # Shared resource — created once, reused across sessions
st.caption(f"Connection status: {conn['status']} via {conn['provider']}")

import streamlit as st
import pandas as pd
import numpy as np

# io.thecodeforge: Professional dashboard layout
# st.set_page_config MUST be the first Streamlit call — anything before it raises StreamlitAPIException.
st.set_page_config(
    page_title="Forge Intelligence Hub",
    page_icon="🔬",
    layout="wide",
    initial_sidebar_state="expanded"
)

# ── SIDEBAR CONTROLS ──────────────────────────────────────────────────────────
with st.sidebar:
    st.header("Control Panel")
    st.divider()
    mode = st.radio(
        "Analysis Mode",
        ["Standard", "Advanced"],
        help="Advanced mode enables cohort segmentation and confidence intervals."
    )
    date_range = st.date_input("Reporting Period", [])

# ── KPI HEADER ROW ────────────────────────────────────────────────────────────
st.title("Forge Intelligence Hub")
kpi1, kpi2, kpi3, kpi4 = st.columns(4)
kpi1.metric("Revenue", "$1.24M", delta="+12.3%")
kpi2.metric("Active Users", "8,412", delta="+340")
kpi3.metric("Churn Rate", "2.4%", delta="-0.5%", delta_color="inverse")
kpi4.metric("Model Accuracy", "94.1%", delta="+1.2%")

st.divider()

# ── TABBED CONTENT ────────────────────────────────────────────────────────────
overview_tab, forecast_tab, settings_tab = st.tabs(["Overview", "Forecast", "Settings"])

with overview_tab:
    chart_data = pd.DataFrame(
        np.random.randn(30, 3),
        columns=["Revenue", "Cost", "Profit"]
    )
    st.line_chart(chart_data)

with forecast_tab:
    # st.form() buffers ALL widget interactions — re-run only fires on submit.
    # Without this, every slider nudge or text keystroke triggers a full re-run.
    with st.form("forecast_parameters"):
        st.subheader("Configure Forecast")
        col_a, col_b = st.columns(2)
        with col_a:
            horizon = st.slider("Forecast horizon (days)", 7, 90, 30)
            confidence = st.selectbox("Confidence interval", ["80%", "90%", "95%"])
        with col_b:
            target_metric = st.text_input("Target metric", placeholder="e.g. daily_revenue")
            include_weekends = st.checkbox("Include weekends", value=True)

        submitted = st.form_submit_button("Run Forecast", type="primary")

    if submitted:
        if not target_metric:
            st.error("Target metric is required before running the forecast.")
        else:
            with st.spinner(f"Running {horizon}-day forecast for '{target_metric}'..."):
                # In production this would call your ML backend API
                st.success(f"Forecast complete: {horizon} days, {confidence} CI, {'weekends included' if include_weekends else 'weekdays only'}.")

with settings_tab:
    st.info("Settings are persisted per session. Changes here reset on page refresh.")
    theme = st.selectbox("Dashboard theme", ["Light", "Dark", "System"])
    refresh_interval = st.number_input("Auto-refresh interval (seconds)", min_value=30, value=300)

-- io.thecodeforge: Persistence Layer for Streamlit Session Activity
-- This table captures dashboard interactions that must survive beyond a single session.
-- st.session_state cannot be used for this — it is lost on every page refresh.

CREATE TABLE IF NOT EXISTS io.thecodeforge.dashboard_activity (
    id              SERIAL PRIMARY KEY,
    session_id      TEXT        NOT NULL,
    user_email      TEXT,
    action_performed TEXT       NOT NULL,
    widget_context  JSONB,                          -- captures which filters/params were active
    interaction_ts  TIMESTAMP   DEFAULT CURRENT_TIMESTAMP
);

-- Index on session_id for fast per-session retrieval
CREATE INDEX IF NOT EXISTS idx_dashboard_activity_session
    ON io.thecodeforge.dashboard_activity (session_id);

-- Index on interaction_ts for time-range analysis of dashboard usage
CREATE INDEX IF NOT EXISTS idx_dashboard_activity_ts
    ON io.thecodeforge.dashboard_activity (interaction_ts DESC);

-- Example: record a forecast run triggered from the Streamlit UI
INSERT INTO io.thecodeforge.dashboard_activity
    (session_id, user_email, action_performed, widget_context)
VALUES
    (
        'sess_882',
        'editor@thecodeforge.io',
        'run_forecast',
        '{"horizon_days": 30, "confidence": "95%", "target_metric": "daily_revenue"}'
    );

-- Retrieve activity for a specific session (useful for debugging user-reported issues)
SELECT action_performed, widget_context, interaction_ts
FROM   io.thecodeforge.dashboard_activity
WHERE  session_id = 'sess_882'
ORDER  BY interaction_ts DESC;

package io.thecodeforge.api;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.time.Instant;

/**
 * io.thecodeforge: REST API consumed by the Streamlit frontend.
 * Streamlit calls this endpoint via requests.get() with @st.cache_data applied.
 * All business logic and heavy computation lives here — not in the dashboard script.
 */
@RestController
@RequestMapping("/api/v1/forge-metrics")
public class DashboardController {

    /**
     * Returns summary metrics for the Streamlit dashboard KPI row.
     * Streamlit caches this response — this endpoint typically receives
     * 1 request per 5 minutes per user, not 1 per interaction.
     */
    @GetMapping("/summary")
    public ResponseEntity<MetricResponse> getSummary(
            @RequestParam(defaultValue = "30") int horizonDays) {

        // In production: query your data warehouse or aggregation service here.
        // The compute stays in Java; the visualization stays in Streamlit.
        MetricResponse response = new MetricResponse(
            1_204_847.50,
            "USD",
            0.941,
            horizonDays,
            Instant.now().toString()
        );

        return ResponseEntity.ok(response);
    }

    /**
     * Record used as the JSON response body.
     * Streamlit receives this as a dict after requests.get().json().
     */
    record MetricResponse(
        double revenue,
        String currency,
        double modelAccuracy,
        int forecastHorizonDays,
        String generatedAt
    ) {}
}

# io.thecodeforge: Production Streamlit Container
# Built on python:3.11-slim to minimize image size while retaining pip and venv support.
FROM python:3.11-slim

WORKDIR /app

# Install system-level dependencies.
# curl is required for the HEALTHCHECK command below.
# Add any system packages your Python libraries need here (e.g., libgdal-dev for GeoPandas).
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements first to leverage Docker layer caching.
# If requirements.txt does not change, this layer is reused on rebuild.
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application source after dependencies to keep the source-change rebuild fast.
COPY . .

# Streamlit's default port. Expose it so orchestrators can route traffic correctly.
EXPOSE 8501

# Health check using Streamlit's built-in health endpoint.
# interval: how often to check. timeout: how long to wait. retries: failures before unhealthy.
HEALTHCHECK \
    --interval=30s \
    --timeout=5s \
    --start-period=10s \
    --retries=3 \
    CMD curl --fail http://localhost:8501/_stcore/health || exit 1

# --server.address=0.0.0.0 is REQUIRED in Docker.
# Without it, Streamlit binds to 127.0.0.1 inside the container
# and external connections get 'connection refused' with no obvious error.
ENTRYPOINT [
    "streamlit", "run", "app.py",
    "--server.port=8501",
    "--server.address=0.0.0.0",
    "--server.headless=true"
]