Building AI-Native Applications with Streamlit and Gradio

What they are — Python UIs, no frontend advanced

Picture the moment your LLM code finally works — and nobody can see it. You've built a classifier, a RAG bot, an agent loop. It runs beautifully in your terminal, prints to stdout, returns clean JSON. Then your manager, or a friend, or a potential user asks the fair question: "Can I try it?" And you freeze, because the honest answer is "sure — install Python, clone this repo, set an env var, and run this script from a shell." That gap — between working logic and something a human can actually touch — is the entire reason this chapter exists. It's called the last mile, and historically it was the expensive mile: it meant learning HTML, CSS, JavaScript, a frontend framework, and how to wire all of that back to your Python. Streamlit and Gradio delete that mile.

Here's the mental shift, and it's a big one: treat these tools as a translation layer, not a web framework. You keep writing the Python you already know — variables, functions, loops — and the library watches what you produce and paints a matching web interface. Write st.text_input("Name") and a text box appears; write st.write(df) and a scrollable table appears. You are never authoring a webpage; you are describing an interface in Python and letting the tool be the frontend engineer you didn't have to hire. The analogy that lands for most people: it's the difference between writing a stage play — you script who says what, and the theatre supplies the lights, the set, the sound — versus building the theatre yourself, brick by brick.

The common beginner mistake is treating one of these like a real frontend: reaching for custom CSS, fighting the layout, trying to control every pixel. That way lies frustration, because these tools trade fine-grained control for speed on purpose. They are opinionated — they pick sensible defaults so you don't have to make a hundred small decisions. So the moment you catch yourself battling the framework to get a pixel "just right," read it as a signal, not a bug: you've probably outgrown the tool and want a real frontend (or the FastAPI backend of §UI-only vs backend). Used for what they're built for — getting working Python in front of humans fast — they feel close to magic. The two differ mainly in grain, which the table below makes concrete: Streamlit thinks in whole apps, Gradio thinks in single functions.

Streamlit and Gradio both turn a Python script into a web app. You write Python; they render widgets (text boxes, buttons, chat, charts, file uploaders) and run a local/hosted server. No HTML/CSS/JS. The difference is emphasis:

The Streamlit mental model: rerun-on-interaction advanced

This one idea is the difference between Streamlit feeling magical and feeling haunted. Almost every "why is my app doing that?!" story from a Streamlit beginner traces back to a single misunderstanding, and if you internalize it now you'll skip a week of confusion. So let's put the stakes plainly: a variable you set at the top of your script will look, to your eyes, like it should stick around — and it won't. Your counter resets to zero. Your chat forgets the last message. Your loaded model reloads on every keystroke. None of that is a bug in your logic. It's the execution model, and once you see it, it all becomes obvious and predictable.

Here's the analogy that makes it click. Most UI frameworks you may have seen work like a whiteboard: you draw the screen once, then reach in and erase-and-redraw only the one number that changed. Streamlit does the opposite — it works like a photocopier. Every time the user touches anything, Streamlit throws away the whole page and re-runs your entire script from line 1 to the last line to produce a brand-new copy. There is no "update just this widget." There is only "run the whole thing again and show me the fresh result." Your script isn't a program that sets up a UI once and then listens; your script is the description of the page, re-executed in full on every click, keystroke, and slider drag.

Why would anyone design it that way? Because it's gloriously simple to reason about: your UI is always just a pure function of the current widget values, top to bottom, with no tangle of callbacks and event handlers to trace. The price you pay for that simplicity is exactly the trap above — ordinary variables can't remember anything, because they're born fresh each run and die at the bottom. Streamlit's answer is a special dictionary, st.session_state, that it deliberately preserves between reruns. Anything that must survive — chat history, a counter, a loaded model, a user's choices — lives there; everything else is happily rebuilt each pass. (There's a sibling trap too: expensive setup like loading a dataframe or building a retriever also re-runs every time unless you cache it — the callout after the lab covers that.) Keep the photocopier picture in your head as you read the diagram: interaction in, whole-script-rerun in the middle, fresh screen out.

The one thing that confuses every Streamlit beginner: your entire script re-runs top-to-bottom on every interaction. Click a button, type in a box — the whole file executes again. Understand this and Streamlit is simple; miss it and state behaves "randomly."

Lab B4.1 · A Streamlit chat app advanced

shellpip install streamlit anthropic
streamlit run app.py

app.pyimport streamlit as st
from anthropic import Anthropic
client = Anthropic()

st.title("Chat with Claude")

# history must survive reruns → session_state
if "messages" not in st.session_state:
    st.session_state.messages = []

# re-draw the whole conversation every run
for m in st.session_state.messages:
    st.chat_message(m["role"]).write(m["content"])

if prompt := st.chat_input("Ask something"):
    st.session_state.messages.append({"role":"user","content": prompt})
    st.chat_message("user").write(prompt)

    with st.chat_message("assistant"):
        with client.messages.stream(model="claude-opus-4-8", max_tokens=1024,
                messages=st.session_state.messages) as stream:
            text = st.write_stream(stream.text_stream)   # streams tokens live
    st.session_state.messages.append({"role":"assistant","content": text})

shellpip install streamlit openai
streamlit run app.py

app.pyimport streamlit as st
from openai import OpenAI
client = OpenAI()

st.title("Chat with GPT")

# history must survive reruns → session_state
if "messages" not in st.session_state:
    st.session_state.messages = []

# re-draw the whole conversation every run
for m in st.session_state.messages:
    st.chat_message(m["role"]).write(m["content"])

if prompt := st.chat_input("Ask something"):
    st.session_state.messages.append({"role":"user","content": prompt})
    st.chat_message("user").write(prompt)

    with st.chat_message("assistant"):
        with client.responses.stream(model="gpt-5.5", max_output_tokens=1024,
                input=st.session_state.messages) as stream:
            deltas = (e.delta for e in stream
                      if e.type == "response.output_text.delta")
            text = st.write_stream(deltas)               # streams tokens live
    st.session_state.messages.append({"role":"assistant","content": text})

Lab B4.2 · The same, in Gradio expert

You just wrote a Streamlit chat and had to hand-manage its memory — the session_state guard, the redraw loop, appending each turn. Now watch the same app disappear into a single function. That contrast is the point of this section: it's not "here's another tool," it's "here's the opposite philosophy, so you can feel which grain fits which job." Getting this comparison in your bones is what lets you answer the interview question "Streamlit or Gradio?" with a reason instead of a shrug.

The mental model flips completely. In Streamlit you own the app — the script, the state, the redraw — and the framework just renders whatever you produce. In Gradio, the framework owns the app and you just supply one function: give it a respond(message, history), and Gradio hands you the past conversation, builds the entire chat interface (input box, message bubbles, streaming, a share link), and calls your function whenever the user says something. The analogy: Streamlit is renting an empty apartment and furnishing every room yourself; Gradio is checking into a hotel room that's already made up — you bring your toothbrush (the function) and nothing else. That's why the whole app below is one function plus gr.ChatInterface(respond).launch().

The common mistake here is expecting Gradio to behave like Streamlit — hunting for the equivalent of session_state, or trying to manually redraw the history. Don't; there's nothing to manage. Gradio passes the history into your function as an argument, so your job shrinks to "given this message and this history, what do I say back?" And streaming comes free from a Python feature you already know: instead of return-ing the finished reply, you yield the answer as it grows, and each yield updates the chat box live. The trade-off is the mirror of the tool's strength — you get a polished chat UI in one line, but you give up Streamlit's freedom to arrange arbitrary widgets, tabs, and layouts across a custom page. Rule of thumb to carry out of this lab: Gradio when the app is the function (a model demo, a chat over your agent); Streamlit when the function is just one part of a bigger app.

Gradio's model is different: you define a function and wrap a chat interface around it. Less boilerplate for a pure "wrap my model" demo.

gradio_app.pyimport gradio as gr
from anthropic import Anthropic
client = Anthropic()

def respond(message, history):     # Gradio passes history for you
    msgs = [{"role": h["role"], "content": h["content"]} for h in history]
    msgs.append({"role":"user","content": message})
    with client.messages.stream(model="claude-opus-4-8", max_tokens=1024,
            messages=msgs) as stream:
        partial = ""
        for t in stream.text_stream:
            partial += t
            yield partial          # yield to stream into the chat UI

gr.ChatInterface(respond).launch()     # a full chat UI from one function

gradio_app.pyimport gradio as gr
from openai import OpenAI
client = OpenAI()

def respond(message, history):     # Gradio passes history for you
    msgs = [{"role": h["role"], "content": h["content"]} for h in history]
    msgs.append({"role":"user","content": message})
    with client.responses.stream(model="gpt-5.5", max_output_tokens=1024,
            input=msgs) as stream:
        partial = ""
        for event in stream:
            if event.type == "response.output_text.delta":
                partial += event.delta
                yield partial      # yield to stream into the chat UI

gr.ChatInterface(respond).launch()     # a full chat UI from one function

Beyond chat: the widgets that matter for AI apps expert

A chat box is where everyone starts, and it's also where a lot of AI apps get stuck. It's tempting to believe every problem is a conversation — but ask yourself what your users actually need to do. An analyst doesn't want to chat about a spreadsheet; she wants to drop the file in and see a chart. A reviewer doesn't want to type "the answer was good"; he wants to click 👍. The stakes of this section are quiet but real: the difference between a toy and a tool is usually not a smarter prompt — it's the right handful of widgets around the model, so a human can get their real work in and out.

Think of a widget as a doorway in and out of your Python. Each one is a two-way translation: a file uploader turns a PDF on someone's desktop into a bytes object your RAG code can chunk; a slider turns a mouse drag into a float you pass as temperature; a chart component turns the Matplotlib Figure you built in B2 back into pixels the user sees. You already wrote the logic in earlier chapters — the classifier, the retriever, the Pandas transforms, the plots. Widgets are simply the doors that let that logic meet a human, and picking the right doors is a design skill worth more than it looks.

Here's the mindset that makes the table below click: read each row as "an earlier chapter, now with a face." File upload isn't a new feature — it's the front door of your Ch 3 RAG pipeline or the P4 Document Intelligence project. The dataframe display is your B1 Pandas result, made visible. The chart component is your B2 figure, rendered. The 👍/👎 buttons are the missing input to your O4/I4 evaluation loop — the moment a real user's judgment becomes data you can measure and improve against. A subtle mistake worth flagging: don't over-widget. Every extra control is another thing to explain, validate, and secure; the best AI UIs expose the two or three knobs that matter (usually: bring-your-own-input, one model parameter, and a way to give feedback) and hide the rest. Match the door to the job, and you're building tools, not toys.

Chat is the headline, but both frameworks give you the pieces to build real AI tools — connecting straight back to earlier modules.

UI-only vs UI + FastAPI backend expert

Here's a decision that quietly separates a weekend demo from a system you can stand behind. The very thing that makes Streamlit and Gradio wonderful — you write one script, it talks to Claude, done — is also a trap you can fall into without noticing. It works so well for the demo that you keep bolting features onto that one script: a bit of auth here, a rate limit there, a background job, a second kind of client… until one file is trying to be a frontend, a backend, and a security perimeter all at once. The stakes are concrete: get this call wrong in the "too simple" direction and you ship your API key to the world; get it wrong in the "too complex" direction and you spend a day building a backend for an app three people will ever use.

The clean way to think about it is to separate two jobs that the demo accidentally fuses. One job is presentation — draw the boxes, take the input, show the answer. The other is logic — hold the secret key, call the model, enforce who's allowed and how often, run the long agent loops. A Streamlit/Gradio app is a superb face. Whether it should also be the brain is the whole question. The analogy: a small café can have one person take your order, cook it, and run the till — perfectly efficient at that scale. A restaurant chain cannot; it splits the front-of-house (the UI) from the kitchen (the backend) so the kitchen can serve many locations, enforce standards, and be swapped or scaled without retraining every waiter. The diagram below is exactly those two arrangements.

So how do you actually decide? Lean on who and how many. If it's you, or a few trusted colleagues, and the logic is simple, let the UI call Claude directly — the left stack — and enjoy the speed. Reach for the FastAPI backend (B3) — the right stack — the instant any one of these is true: more than one kind of client will use it (web and mobile and another service), you need real auth, rate limits, or scaling (O3), the work is heavy or long-running, or you simply want the core logic reusable and independently testable rather than trapped inside a UI script. A useful gut-check: can this thing embarrass me or bill me? The moment it's reachable by people you don't personally trust, the backend stops being optional — because a UI-only app puts your key and your cost meter one layer from the open internet, which is precisely what the security section is about. The tables spell out both sides row by row.

Key architectural call: is a Streamlit/Gradio app enough, or do you need a B3 FastAPI backend behind it?

Security & deployment basics expert

Let's be blunt about the failure mode this section exists to prevent: a public URL, no auth, your API key inside, and a surprise four-figure bill on Monday. It happens more than anyone admits, and it happens precisely because these tools are so friendly. Streamlit and Gradio give you a one-line "share" or "launch" that turns your laptop script into a link anyone can open — and that link feels so casual, so demo-y, that your brain files it under "just a script" instead of "a public LLM endpoint I am financially responsible for." The stakes are real money and real data. So the mental reframe to adopt before you ever hit share is simple and a little uncomfortable: the instant it's reachable by someone else, it's production, and every rule from T1 and O3 applies — the pretty UI changes nothing.

Why is that reframe so easy to skip? Because a nice interface feels like a boundary. A polished chat box and a friendly title trick you into thinking there's a wall between the user and the model. There isn't. The text a stranger types flows to the same LLM, spends the same tokens on the same API key, and carries the same prompt-injection risk it would through a raw curl. The UI is a coat of paint on a door, not a lock. Think of it like a shop: a beautiful storefront window doesn't secure the till — you still need a lock on the door (auth), a limit on how much any one person can take (rate limits), and the cash kept out of the customer's reach (the key server-side, never shipped to the browser).

The good news is that the defenses are a short, unglamorous checklist, and doing them is mostly discipline, not cleverness. Keep the API key in the environment or a secrets store — never a literal in the script or committed to the repo, because git history is forever and scanners crawl public repos within minutes. Put access behind auth or keep the app internal; assume "unlisted URL" is not privacy. Cap and monitor usage so a runaway loop or an abuser can't drain your budget (O2/O4). Treat every input as untrusted and remember the T1 threats didn't vanish behind the widget. And when it grows past a toy, containerize it and, per the previous section, move the real logic behind a FastAPI backend where these controls belong anyway. Read the table below as your pre-share checklist — the danger callout after it is the one-paragraph version to tattoo on your memory.

The moment your app is reachable by others, the T1/O3 rules apply — and these frameworks make it dangerously easy to skip them.

Common pitfalls expert

Exercises expert

import streamlit as st

st.title("Echo app")
name = st.text_input("Your name")
if name:
    st.write(f"Hello, {name}!")

# run:  streamlit run app.py

import streamlit as st

st.title("Chat")
if "messages" not in st.session_state:
    st.session_state.messages = []          # survives reruns

for m in st.session_state.messages:
    st.chat_message(m["role"]).write(m["content"])

if prompt := st.chat_input("Say something"):
    st.session_state.messages.append({"role": "user", "content": prompt})
    reply = f"You said: {prompt}"           # replace with an LLM call
    st.session_state.messages.append({"role": "assistant", "content": reply})
    st.chat_message("assistant").write(reply)

import gradio as gr

def respond(message, history):
    # history is a list of prior (user, assistant) turns, managed by Gradio
    return f"You said: {message}"           # replace with an LLM call

demo = gr.ChatInterface(fn=respond, title="Chat")
demo.launch()

import streamlit as st

uploaded = st.file_uploader("Upload a document", type=["txt", "pdf"])
if uploaded:
    st.success(f"Loaded {uploaded.name} ({uploaded.size} bytes)")

temperature = st.slider("Creativity (temperature)", 0.0, 1.0, 0.2, 0.05)
st.caption(f"Using temperature = {temperature}")

if st.button("Clear conversation"):
    st.session_state.pop("messages", None)
    st.rerun()                              # force a fresh run after clearing

import streamlit as st
import requests

prompt = st.chat_input("Ask")
if prompt:
    # the backend holds the API key and the real logic:
    r = requests.post("http://localhost:8000/ask", json={"prompt": prompt}, timeout=30)
    r.raise_for_status()
    st.chat_message("assistant").write(r.json()["answer"])

import os

api_key = os.environ.get("MODEL_API_KEY")
if not api_key:
    raise RuntimeError("MODEL_API_KEY is not set; refusing to start")
print("key loaded from environment:", bool(api_key))   # True, value never printed

Knowledge check check yourself