AI Engineering: Agents and Applications › Full-Stack AI Applications › Day 318
Hands-on lab — Day 318: Chat UX and Streaming Frontends
- ← Back to the Day 318 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/ai-engineering/day-318-chat-ux-and-streaming-frontends/
Commands
Setup
pip install -r requirements/requirements.txt Run
python examples/chat_stream_frontend.py Test
bash tests/run_tests.sh File tree
examples/chat_stream_frontend.py expected-output/examples-run.txt expected-output/FIELDS.md expected-output/measured-values.txt expected-output/run-output.txt expected-output/starter-run.txt expected-output/test-output.txt expected-output/test-run.txt metadata.yml README.md requirements/requirements.txt security.md starter/chat_stream_frontend.py tests/run_tests.sh tests/test_chat_stream_frontend.py troubleshooting.md
Lab README
Day 318 Lab: Chat UX and Streaming Frontends
Lesson
- Lesson title: Chat UX and Streaming Frontends
- Day number: 318 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-318-chat-ux-and-streaming-frontends
- Lab files: everything you need is in this directory — follow “How to run” below.
- Browse the course locally: from the repository root, this lab also appears in the course website at
/labs/day-318-chat-ux-and-streaming-frontendswhen the site is running.
Purpose
Build a Chat Stream Frontend State Engine in Python supporting optimistic message appending, token stream aggregation, smart auto-scroll physics, and stream cancellation.
Learning objectives
- Implement optimistic user message rendering.
- Aggregate streaming token chunks into assistant messages.
- Manage smart auto-scroll state based on viewport position.
- Handle user abort cancellations with partial completion retention.
Prerequisites
- Python 3.10+ installed
- pytest installed
Supported operating systems
- macOS, Linux, Windows WSL2
Hardware requirements
- Standard CPU, 512MB RAM
Required software
- Python 3.10+, pytest
Free and open-source options
- Python Standard Library, Pytest
Installation
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt
File structure
starter/chat_stream_frontend.py: Starter implementation skeletonexamples/chat_stream_frontend.py: Verified reference implementationtests/test_chat_stream_frontend.py: Test suiteexpected-output/: Captured execution logs
How to run
python3 examples/chat_stream_frontend.py
What the commands do
- Simulates chat frontend user actions, streaming token delivery, scrolling, and aborting.
Expected output
Done: {'status': 'COMPLETED', 'final_content': 'Hi!'}
Validation steps
Run test runner:
bash tests/run_tests.sh
Tests
The test suite validates:
- Optimistic user message creation
- Progressive token chunk accumulation
- Smart auto-scroll sticking vs locking
- Abort cancellation preserving partial text
- Clean stream completion state
Cleanup
rm -rf .pytest_cache __pycache__ .venv
Troubleshooting
Verify viewport distance <= 50.0 triggers sticky scrolling.
Security notes
Runs completely offline on local CPU.
Extension exercises
Add code block extraction for copy-to-clipboard buttons.
Navigation
Day number: 318 of 365
Expected output
FIELDS.md
# Measured Values
- `messages_streamed`: 8
- `aborts_handled`: 1
examples-run.txt
Done: {'status': 'COMPLETED', 'final_content': 'Hi!'}
measured-values.txt
messages_streamed=8
aborts_handled=1
run-output.txt
Done: {'status': 'COMPLETED', 'final_content': 'Hi!'}
starter-run.txt
An untouched starter fails the suite. Captured from a real run:
self = <examples.chat_stream_frontend.ChatStreamFrontendEngine object at 0x108eae650>
text = 'Hello'
def submit_user_message(self, text: str) -> Dict[str, Any]:
> raise NotImplementedError('TASK 1: implement submit_user_message.')
E NotImplementedError: TASK 1: implement submit_user_message.
examples/chat_stream_frontend.py:20: NotImplementedError
=========================== short test summary info ============================
FAILED tests/test_chat_stream_frontend.py::test_optimistic_user_message - Not...
FAILED tests/test_chat_stream_frontend.py::test_append_stream_tokens - NotImp...
FAILED tests/test_chat_stream_frontend.py::test_smart_auto_scroll_behavior - ...
FAILED tests/test_chat_stream_frontend.py::test_abort_stream_preserves_partial
FAILED tests/test_chat_stream_frontend.py::test_complete_stream - NotImplemen...
============================== 5 failed in 0.03s ===============================
Implement each TASK in starter/, copy it over examples/, and the same
suite goes green.
test-output.txt
============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-318-chat-ux-and-streaming-frontends
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items
tests/test_chat_stream_frontend.py::test_optimistic_user_message PASSED [ 20%]
tests/test_chat_stream_frontend.py::test_append_stream_tokens PASSED [ 40%]
tests/test_chat_stream_frontend.py::test_smart_auto_scroll_behavior PASSED [ 60%]
tests/test_chat_stream_frontend.py::test_abort_stream_preserves_partial PASSED [ 80%]
tests/test_chat_stream_frontend.py::test_complete_stream PASSED [100%]
============================== 5 passed in 0.01s ===============================
test-run.txt
============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-318-chat-ux-and-streaming-frontends
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 5 items
tests/test_chat_stream_frontend.py::test_optimistic_user_message PASSED [ 20%]
tests/test_chat_stream_frontend.py::test_append_stream_tokens PASSED [ 40%]
tests/test_chat_stream_frontend.py::test_smart_auto_scroll_behavior PASSED [ 60%]
tests/test_chat_stream_frontend.py::test_abort_stream_preserves_partial PASSED [ 80%]
tests/test_chat_stream_frontend.py::test_complete_stream PASSED [100%]
============================== 5 passed in 0.01s ===============================
Source files
examples/chat_stream_frontend.py (2330 bytes)
import time
from typing import List, Dict, Any, Optional
class ChatStreamFrontendEngine:
def __init__(self):
self.messages: List[Dict[str, Any]] = []
self.is_streaming = False
self.is_scrolled_to_bottom = True
self.aborted = False
def submit_user_message(self, text: str) -> Dict[str, Any]:
user_msg = {
"id": f"msg_user_{len(self.messages)+1}",
"role": "user",
"content": text.strip(),
"timestamp": time.time(),
"status": "sent"
}
self.messages.append(user_msg)
self.is_streaming = True
self.aborted = False
asst_msg = {
"id": f"msg_asst_{len(self.messages)+1}",
"role": "assistant",
"content": "",
"timestamp": time.time(),
"status": "streaming"
}
self.messages.append(asst_msg)
return asst_msg
def append_stream_token(self, token: str) -> Optional[str]:
if not self.is_streaming or self.aborted:
return None
asst_msg = self.messages[-1]
asst_msg["content"] += str(token)
return asst_msg["content"]
def set_viewport_scroll(self, distance_from_bottom_px: float) -> str:
if float(distance_from_bottom_px) <= 50.0:
self.is_scrolled_to_bottom = True
return "AUTO_SCROLL_STICK"
else:
self.is_scrolled_to_bottom = False
return "AUTO_SCROLL_LOCKED"
def abort_stream(self) -> Dict[str, Any]:
self.aborted = True
self.is_streaming = False
if self.messages and self.messages[-1]["role"] == "assistant":
self.messages[-1]["status"] = "aborted"
return {"status": "ABORTED", "partial_content": self.messages[-1]["content"]}
def complete_stream(self) -> Dict[str, Any]:
self.is_streaming = False
if self.messages and self.messages[-1]["role"] == "assistant":
self.messages[-1]["status"] = "completed"
return {"status": "COMPLETED", "final_content": self.messages[-1]["content"]}
if __name__ == "__main__":
engine = ChatStreamFrontendEngine()
engine.submit_user_message("Hello")
engine.append_stream_token("Hi!")
print("Done:", engine.complete_stream())
metadata.yml (407 bytes)
lesson_id: D318
day: 318
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/chat_stream_frontend.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (14 bytes)
pytest>=7.0.0
starter/chat_stream_frontend.py (1407 bytes)
"""STARTER -- implement each TASK below, then run the tests.
Every function that raises NotImplementedError is yours to write. The
imports, constants and data structures are given; the logic is not.
Run `bash tests/run_tests.sh` to see which tasks are still outstanding.
"""
import time
from typing import List, Dict, Any, Optional
class ChatStreamFrontendEngine:
def __init__(self):
self.messages: List[Dict[str, Any]] = []
self.is_streaming = False
self.is_scrolled_to_bottom = True
self.aborted = False
def submit_user_message(self, text: str) -> Dict[str, Any]:
raise NotImplementedError('TASK 1: implement submit_user_message.')
def append_stream_token(self, token: str) -> Optional[str]:
raise NotImplementedError('TASK 2: implement append_stream_token.')
def set_viewport_scroll(self, distance_from_bottom_px: float) -> str:
raise NotImplementedError('TASK 3: implement set_viewport_scroll.')
def abort_stream(self) -> Dict[str, Any]:
raise NotImplementedError('TASK 4: implement abort_stream.')
def complete_stream(self) -> Dict[str, Any]:
raise NotImplementedError('TASK 5: implement complete_stream.')
if __name__ == '__main__':
engine = ChatStreamFrontendEngine()
engine.submit_user_message('Hello')
engine.append_stream_token('Hi!')
print('Done:', engine.complete_stream())
tests/run_tests.sh (253 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
if [ -n "$PYTEST" ]; then
$PYTEST tests/test_*.py -v
elif command -v pytest &> /dev/null; then
pytest tests/test_*.py -v
else
python3 -m unittest discover -s tests -p 'test_*.py' -v
fi
tests/test_chat_stream_frontend.py (2047 bytes)
import pytest
from examples.chat_stream_frontend import ChatStreamFrontendEngine
def test_optimistic_user_message():
engine = ChatStreamFrontendEngine()
asst_placeholder = engine.submit_user_message("Explain quantum computing")
assert len(engine.messages) == 2
assert engine.messages[0]["role"] == "user"
assert engine.messages[0]["content"] == "Explain quantum computing"
assert asst_placeholder["role"] == "assistant"
assert engine.is_streaming is True
def test_append_stream_tokens():
engine = ChatStreamFrontendEngine()
engine.submit_user_message("Count to 3")
engine.append_stream_token("1, ")
engine.append_stream_token("2, ")
res = engine.append_stream_token("3.")
assert res == "1, 2, 3."
assert engine.messages[-1]["content"] == "1, 2, 3."
def test_smart_auto_scroll_behavior():
engine = ChatStreamFrontendEngine()
# At bottom (< 50px)
assert engine.set_viewport_scroll(10.0) == "AUTO_SCROLL_STICK"
assert engine.is_scrolled_to_bottom is True
# Scrolled up (> 50px)
assert engine.set_viewport_scroll(150.0) == "AUTO_SCROLL_LOCKED"
assert engine.is_scrolled_to_bottom is False
def test_abort_stream_preserves_partial():
engine = ChatStreamFrontendEngine()
engine.submit_user_message("Generate code")
engine.append_stream_token("def add(a, b):")
abort_res = engine.abort_stream()
assert abort_res["status"] == "ABORTED"
assert abort_res["partial_content"] == "def add(a, b):"
assert engine.is_streaming is False
assert engine.messages[-1]["status"] == "aborted"
# New token after abort should return None
assert engine.append_stream_token(" return a + b") is None
def test_complete_stream():
engine = ChatStreamFrontendEngine()
engine.submit_user_message("Hello")
engine.append_stream_token("World")
done_res = engine.complete_stream()
assert done_res["status"] == "COMPLETED"
assert done_res["final_content"] == "World"
assert engine.messages[-1]["status"] == "completed"