AI Engineering: Agents and Applications › Full-Stack AI Applications › Day 318

Hands-on lab — 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

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 skeleton
  • examples/chat_stream_frontend.py: Verified reference implementation
  • tests/test_chat_stream_frontend.py: Test suite
  • expected-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.

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"

Troubleshooting

Troubleshooting - Day 318\nCheck distance from bottom threshold to ensure smooth auto-scrolling.\n

Security notes

Security - Day 318\nRendered Markdown must be sanitized on frontend to prevent XSS injection attacks.\n