### How to build a real-time streaming UI with Python, FastAPI, and HTMX in less than 200 lines of code. ![](/images/javascript-fatigued-build-an-agentic-chatbot-with-htmx/1*ckYxd8EabT-DMqJas_GkCA.png) ## Summary - Introduction about HTML and the Web - A simple HTMX demo - A basic Chat with HTMX and FastAPI - A more advanced chat with Streaming and Server-Sent Events - An agentic chatbot with Gemini and ADK - Conclusion ## Introduction I remember there was a time, long ago, when building websites was easy. HTML and CSS. It felt simple. Nowadays, Javascript frameworks are everywhere. Relentless change, increasing complexity. This phenomenon is called “*Javascript Fatigue*” and is all about developers exhausted by chasing the latest frameworks, build tools, libraries, and trying to keep the pace. But with **HTMX**, developers now have a way to build engaging web applications with greater simplicity and less burnout — and without all the JS hassle. And by engaging web applications, I mean something like ChatGPT, in less than 200 lines of code, pure Python and HTML. Like this one: ![Image from author](/images/javascript-fatigued-build-an-agentic-chatbot-with-htmx/1*1MVU3aG1zKrKkg8ZV5cfzQ.gif) ### A quick refresher on how the Web works When Tim Berners-Lee created the first web page in 1990, the system he designed was mostly a “read-only” system, that would lead to pages connected between themselves with hyperlinks, which we all know as anchor tags in HTML. HTML 1.0 was therefore relying on one single tag for navigation (there are of course other tags for text structure) and offered simple navigation between pages. ```xml About Us ``` The anchor tag is a hypermedia control that does the following process: - show the user that this is a link (clickable) - issue a GET request to the hyperlink URL When the server responds with a new page, the browser will replace the current page with the new page (navigation). Then came HTML 2.0 which introduced a new tag, the `

` tag. This tag allowed to update ressources in addition to reading them via the `` tag. Being able to update ressources meant that we could really start building web applications. All of this with only two controls: `` and ``. ```xml ``` The process when submitting a form is quite similar to the anchor tag, except that we can: - choose which kind of request we want to perform (GET or POST) - attach user information like email, password, etc. to be passed with the request The two tags are the only elements, in pure HTML, that can interact with a server. ### And then came Javascript JavaScript was originally created to add simple interactions to web pages: form validation, data fetching, and basic animations. But with the introduction of XMLHttpRequest (later known as AJAX), JavaScript evolved into something much more powerful and complex. With AJAX, developers could now trigger HTTP requests without the two tags. AJAX allows fetching data from the server, and though XHR can fetch any type of data — including raw HTML fragments, text, or XML — JSON became the de facto data exchange format. This means there needs to be an additional step where JSON gets converted to HTML, via a function that renders HTML from JSON. As shown in the example below, we proceed by: - fetching JSON data from the `/api/users` endpoints (the `response => response.json()` part) - inserting this data into a HTML templates (the `const html` part) - that will then be added to the DOM (the `document.getElementById()` part) ```javascript // The JavaScript way: JSON → HTML conversion fetch('/api/users') .then(response => response.json()) .then(users => { const html = users.map(user => `

` ).join(''); document.getElementById('users').innerHTML = html; }); ``` **This rendering involves a tight coupling between the JSON data format and the HTML rendering: if the JSON data format changes, it breaks the HTML rendering function**. This point is usually a source of friction between frontend and backend developers: frontend dev builds a UI based on an expected JSON format, backend dev decides to change the format, frontend dev needs to update UI, backend dev changes again, frontend dev changes again, etc. Eventually, the industry pivoted heavily toward JSON-driven architectures, giving rise to **Single-Page Applications (SPAs)**. We stopped building websites that navigated from page to page and started building software that lives entirely inside the browser. In this model, the server is reduced to a simple data API, while JavaScript handles the heavy lifting of state management and UI rendering. This is the engine behind React, Angular, and Vue — powerful, but complex. Below are some thoughts from an excellent source which I encourage you to read so you can make your mind: > *“*The emerging norm for web development is to build a React single-page application, with server rendering. The two key elements of this architecture are something like: > – The main UI is built & updated in JavaScript using React or something similar. > – The backend is an API that that application makes requests against. > This idea has really swept the internet. It started with a few major popular websites and has crept into corners like marketing sites and blogs.*”* > (…) > But there are also a *lot* of problems for which I can’t see any concrete benefit to using React. Those are things like blogs, shopping-cart-websites, mostly-[CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)-and-forms-websites. > *(…)* > I don’t think that everyone’s using the SPA pattern for no reason. For large corporations, it allows teams to work independently: the “frontend engineers” can “consume” “APIs” from teams that probably work in a different language and can only communicate through the hierarchy.*”* *(Tom MacWright, *[*https://macwright.com/2020/05/10/spa-fatigue*](https://macwright.com/2020/05/10/spa-fatigue)*)* ### Javascript Fatigue is real As the dominance of SPAs grew, so did the number of Javascript frameworks and the complexity associated to it. For developers, this profusion of choices, opinionated frameworks and libraries eventually led to a collective sense of exhaustion called “Javascript Fatigue”. Here are some reasons to this Javascript frameworks burn-out: - **Increasing complexity**: Libraries and frameworks have become increasingly heavy and complex, requiring big teams to manage. Some opinionated frameworks also mean that JS developers have to specialize on one tech. No Python developer ever called themself “A Tensorflow Python developer”. They’re just Python developers, and switching from TF to Pytorch is not a problem. - **Tight coupling**: The coupling between data APIs and the UI creates friction within teams. Breaking changes occur everyday, and there is no way to solve this as long as teams use JSON as their exchange interface. - **Framework proliferation**: The number of frameworks keeps increasing, leading to a real feeling of “fatigue” among JS developers. - **Over-engineering**: You don’t need JS-heavy frameworks 90% of the time. And in some cases (content-heavy apps), it is even a bad idea (cf Tom MacWright’s blog post) Except for highly interactive/collaborative UIs, simple HTML with Multi-Page Applications is often enough. So how do we go back to good old HTML ? ### HTMX is All You Need HTMX is a very lightweight JS library (14k) that offers a HTML-centric approach to building dynamic web applications. It extends HTML by allowing any element to make AJAX requests and update any part of the DOM. Unlike JS frameworks which do all the rendering on the client side, the heavy lifting is done by the server by returning HTML fragments to be inserted in the DOM. This also means that if you already know templating engines and HTML, the learning curve will be much much much easier compared to learning React or Angular. Instead of abandoning hypermedia for JSON APIs, HTMX makes HTML more capable with the following: - Any element can make HTTP requests (not just `

` and `

`) - Any HTTP method (GET, POST, PUT, DELETE, PATCH) - Any element can be targeted for updates - Any event can trigger requests (click, submit, load, etc.) In fact, you can actually write your own little GPT-like UI with HTMX and just a few lines of Python! ## A Simple HTMX demo For this article, we will build a little chat with less than 100 lines of Python and HTML. But before that, we will start with a simple demo to show how HTMX works. Let’s assume we have an API that returns a list of users. We want to click a button to fetch the data and display a list. ![Image from author](/images/javascript-fatigued-build-an-agentic-chatbot-with-htmx/1*Ui4BQj-47PRUlSMf6i-lZA.gif) In the traditional, JS-way, one would probably do like below. Notice how in this case we are using vanilla Javascript, and not even installing Next or Vite with their dozens of Mb of dependencies ! ```xml ``` And now is the time we look at HTMX. First create your backend with FastAPI (could be Go, PHP, whatever you like. HTMX does not care): ```python from fastapi import FastAPI, Request from fastapi.responses import HTMLResponse from fastapi.templating import Jinja2Templates import requests app = FastAPI() templates = Jinja2Templates(directory="templates") @app.get("/", response_class=HTMLResponse) async def home(request: Request): return templates.TemplateResponse("demo.html", {"request": request}) @app.get("/users") async def get_users(): r = requests.get("https://dummyjson.com/users") data = r.json() html = "" for row in data['users']: html += f"

{row['firstName']} {row['lastName']}

\n" return HTMLResponse(html) ``` And then write a simple HTML page: ```xml Demo

Users

``` You get exactly the same result! What happened just here? Look at the `

``` Let’s have a closer look the `

` tag. This tag has several attributes, so let’s take a minute to review them: - `hx-post="/send"`: It will make a POST request to the `/send` endpoint. - `hx-trigger="click from:#submitButton"`: This means the request will be triggered when the `submitButton`is clicked - `hx-target="#chat"`: This tells the browser where to put the HTML response. In that case, we want the response to be appended to the list. - `hx-swap="beforeend"`: The hx-target tells where to put the content, the hx-swap tells HOW. In that case, we want the content to be added before the end (so after the last child) The `hx-on::before-request` is a little bit more complex, but can be explained easily. It basically happens between the click and the moment the request is sent. It will add the user input the bottom of the list, and clear the user input. This way, we get a snappy user experience! ## A Better chat with Streaming and SSE What we built is a very simple yet functional chat, however if we want to plug a LLM, we might find some moments when the response from the server takes a long time to be returned. The way our current chat is built is *synchronous*, meaning nothing will show until the LLM is finished writing. Not a great user experience. What we need now is *streaming*, and a real LLM to have a conversation with. Here are the next steps : - Real-time streaming with SSE - Session-based architecture for multiple users - Async coordination with `asyncio.Queue` - Clean HTMX patterns with dedicated SSE handling - A Google Search Agent to answer queries with fresh data Here is what the final result will look like: ![Image by author](/images/javascript-fatigued-build-an-agentic-chatbot-with-htmx/1*1MVU3aG1zKrKkg8ZV5cfzQ.gif) ### From sync communication to async What we built previously leveraged very basic web functionalities leveraging forms. Our communication was synchronous, meaning we don’t get anything until the server is done. We issue a request, we wait for the full response, and we display it. Between the two, we just…wait. But modern chatbots work differently, by providing asynchronous communication capabilities. This is done using streaming: we get updates and partial responses instead of waiting for the full response. This is particularly helpful when the response process takes time, which is typically the case for LLMs when the answer is large. ### SSE vs Websockets *SSE (Server-sent Events)* and *Websockets* are two real-time data exchanges protocols between a client and a server. *Websockets* allows for full-duplex connections: this means the browser and the server can both send and receive data simultaneously. This is typically used in online gaming, chat applications, and collaborative tools (think Google Sheets). *SSE* are unidirectional and only allow for a one-way conversation, from server to client. This means that the client cannot send anything to the server via this protocol. If websockets is a two-way phone conversation where people can speak and listen at the same time, SSE is like listening to the radio. SSE are typically used to send notifications, update charts in finance applications, or newsfeeds. So why do we choose SSE? Well because in our use case we don’t need full duplex, and that simple HTTP (which is not how Websockets work) is enough for our use case : we send data, we receive data. SSE means that we will receive data in a stream, nothing more is needed. ### Overview Here is the flow we will build: 1. User inputs a query 2. Server receives the query and sends it to the LLM 3. LLM starts producing content 4. For each piece of content, the server returns it immediately 5. Browser adds this piece of information to the DOM ### Backend The backend will proceed in 2 steps: - A POST endpoint that will receive the message, and return nothing - A GET endpoint that will read a queue and produce an output stream. In our demo, to begin with, we will create a fake LLM response by repeating the user input, meaning that the words of the stream will be exactly the same as the user input. To keep things clean, we need to separate the message streams (the queues) by user session, otherwise we would end up mixing up conversations. We will therefore create a session dictionary to host our queues. Next, we need to tell the backend to wait before the queue is filled before streaming our response. If we don’t, we will encounter concurrency run or timing issues: SSE starts on client side, queue is empty, SSE closes, user inputs a message but…it’s too late! The solution: async queues! Using asynchronous queues has several advantages: - If queue has data: Returns immediately - If queue is empty: Suspends execution until queue.put() is called - Multiple consumers: Each gets their own data - Thread-safe: No race conditions Here is the code below: ```python from fastapi import FastAPI, Request, Form from fastapi.templating import Jinja2Templates from fastapi.responses import HTMLResponse, StreamingResponse import asyncio import time import uuid app = FastAPI() templates = Jinja2Templates("templates") # This object will store session id and their corresponding value, an async queue. sessions = dict() @app.get("/") async def root(request: Request): session_id = str(uuid.uuid4()) sessions[session_id] = asyncio.Queue() return templates.TemplateResponse(request, "index.html", context={"session_id": session_id}) @app.post("/chat") async def chat(request: Request, query: str=Form(...), session_id: str=Form(...)): """ Send message to session-based queue """ # Create the session if it does not exist if session_id not in sessions: sessions[session_id] = asyncio.Queue() # Put the message in the queue await sessions[session_id].put(query) return {"status": "queued", "session_id": session_id} @app.get("/stream/{session_id}") async def stream(session_id: str): async def response_stream(): if session_id not in sessions: print(f"Session {session_id} not found!") return queue = sessions[session_id] # This BLOCKS until data arrives print(f"Waiting for message in session {session_id}") data = await queue.get() print(f"Got message: {data}") message = "" await asyncio.sleep(1) for token in data.replace("\n", " ").split(" "): message += token + " " data = f"""data:

{message}

\n\n""" yield data await asyncio.sleep(0.03) queue.task_done() return StreamingResponse(response_stream(), media_type="text/event-stream") ``` Let’s explain a couple of key concepts here. ### Session isolation It is important that each user gets their own message queue, so as not to mix up conversations. We will handle that by using a sessions dictionary. *Note: For this demo, we store sessions in a global dictionary. In production, we would use Redis or a database, otherwise, our server memory will fill up indefinitely.* In the code below, we see that a new session id is created on page load, and stored in the sessions dictionary. Reloading the page will start a new session, we are not persisting the message queues but we could via a database for example. ```python # This object will store session id and their corresponding value, an async queue. sessions = dict() @app.get("/") async def root(request: Request): session_id = str(uuid.uuid4()) sessions[session_id] = asyncio.Queue() return templates.TemplateResponse(request, "index.html", context={"session_id": session_id}) ``` ### Blocking coordination We need to control the order in which SSE are sent and the user query is received. The order is, on the backend side: 1. Receive user message 2. Create a message queue and populate it 3. Send messages from the queue in a Streaming Response Failure to do so may lead to unwanted behavior, ie. first reading the (empty) message queue, then populating it with the user’s query. The solution to control the order is to use `asyncio.Queue`. This object will be used twice: - When we insert new messages in the queue. Inserting messages will “wake up” the polling in the SSE endpoint ```python await sessions[session_id].put(query) ``` - When we pull messages from the queue. In this line, the code is blocked until a signal from the queue arrives saying “hey, i have new data!”: ```python data = await queue.get() ``` This pattern offers several advantages: - Each user has its own queue - There is no risk of race conditions ### Streaming simulation Before plugging a real LLM, we will simulate a LLM response by splitting the user’s query in words and return those words one by one. The streaming is handled via the `StreamingResponse` object from FastAPI. This object expects an asynchronous generator that will yield data until the generator is over. We have to use the `yield` keyword instead of the `return` keyword, otherwise our generator would just stop after the first iteration. Let’s decompose our streaming function: - First, we need to ensure we have a queue for the current session from which we will pull messages: ```python if session_id not in sessions: print(f"Session {session_id} not found!") return queue = sessions[session_id] ``` - Next, once we have the queue, we will pull messages from the queue if it contains any, otherwise the code pauses and waits for messages to arrive. This is the most important part of our function: ```python # This BLOCKS until data arrives print(f"Waiting for message in session {session_id}") data = await queue.get() print(f"Got message: {data}") ``` To simulate a stream, we will now chunk the message in words (called `tokens` here), and add some time sleeps to simulate the text generation process from a LLM (the `asyncio.sleep` parts). Notice how the data we *yield* is actually HTML strings, encapsulated in strings starting with “data:”. This is how SSE messages are sent. You can also choose to flag your messages with the “event:” metadata. An example would be: ```plaintext event: my_custom_event data:

Content to swap into your HTML page.

``` Let’s see how we implement it in Python (for the purists, use Jinja templates to render the HTML instead of a string:) ): ```python message = "" # First pause to let the browser display "Thinking when the message is sent" await asyncio.sleep(1) # Simulate streaming by splitting message in words for token in data.replace("\n", " ").split(" "): # We append tokens to the message message += token + " " # We wrap the message in HTML tags with the "data" metadata data = f"""data:

{message}

\n\n""" yield data # Pause to simulate the LLM generation process await asyncio.sleep(0.03) queue.task_done() ``` ### Frontend Our frontend has 2 jobs: send user queries to the backend, and listen for SSE message on a specific channel (the session_id). To do that, we apply a concept called “Separation of concepts”, meaning each HTMX element is responsible for a single job only. - the form sends a user input - the SSE listener handles the streaming - the

", "
").replace("