chat485

EECS 485 P2: Server-side Dynamic Pages

A ChatGPT clone implemented with server-side dynamic pages.

Due 11:59pm ET FIXME.

Change Log

DRAFT: This project is in pre-release beta.

Introduction

Build a generative AI chat application using server-side dynamic pages. Every page is rendered on the server with a Jinja template and returned as a complete HTML document. The server uses an LLM as a black box.

The learning goals of this project are server-side dynamic pages, CRUD over a SQL database, sessions and access control, LLM integration, and guided use of generative AI tools.

Products like ChatGPT look like a single smart system, but they are really two parts: a stateless API and a stateful application. The LLM API takes messages in and returns a response. It remembers nothing. The backend application stores conversations in a database, manages sessions, and assembles message history into a prompt for each API call. In this project, you build the application layer and learn that conversation continuity comes from your code, not the model.

Glossary

• Model (LLM, Large Language Model): A stateless neural network that takes a list of messages as input and returns a response. Examples include gpt-5 from OpenAI and claude-sonnet-4-6 from Anthropic.
• Chat application (harness): The stateful layer wrapped around a stateless model. It stores conversations, manages sessions, and orchestrates each request by assembling message history and a system prompt into the model’s input. Chat485 and ChatGPT are chat applications.
• Conversation: A sequence of user and assistant messages on a single topic, stored by the chat application and shown as one item in the sidebar.
• User message: What the human sends.
• Assistant message: What the model sends.
• System prompt: Instructions from the chat application that shape the model’s behavior, e.g., its name and response style.
• Prompt: The full input sent to the model on each request, including the system prompt and all prior user and assistant messages in the conversation.
• Response: The model’s generated output.
• Session: The server’s record of one browser, tracked with a cookie. A session can be anonymous or linked to a logged-in user.

Generative AI policy

A learning goal of this project is guided use of generative AI tools. Use GenAI to learn, not to write the code you submit.

Core rule: Do not use GenAI to write any code you submit for the core project. This includes the Flask route handlers, the SQL queries and schema, and the Jinja templates. CSS and styling are fine. If GenAI writes your route handler, the next bug feels like magic.

For learning: Use GenAI to explain concepts, compare approaches, and surface tradeoffs, then write the code yourself. Identify yourself as a student in the prompt so the model explains rather than codes. Example:

What is the difference between a Flask route that handles GET and one that handles POST, and when does a POST handler redirect instead of rendering a template? I am a student learning Flask.

Exceptions: Codegen, including agentic tools, is allowed for reach goals.

Your responsibility: You are responsible for every line you submit. If you cannot explain a line, you should not have submitted it.

Setup

If your group has already followed the setup tutorials, you can skip to Fresh install.

Group registration

Register your group on the Autograder.

Project folder

Create a folder for this project. Your folder location might be different.

$ pwd
/Users/awdeorio/src/eecs485/p2-chat485-serverside

Version control

Set up version control using the Version control tutorial.

After you’re done, you should have a local repository with a “clean” status and your local repository should be connected to a remote GitHub repository.

$ git status
On branch main
Your branch is up-to-date with 'origin/main'.

nothing to commit, working tree clean
$ git remote -v
origin	https://github.com/awdeorio/p2-chat485-serverside.git (fetch)
origin	https://github.com/awdeorio/p2-chat485-serverside.git (push)

You should have a .gitignore file (instructions).

Starter files

Download and unpack the starter files in your project directory.

$ pwd
/Users/awdeorio/src/eecs485/p2-chat485-serverside
$ wget https://eecs485staff.github.io/p2-chat485-serverside/starter_files.tar.gz
$ tar -xvzf starter_files.tar.gz

Move the starter files into your project directory and remove the original folder.

$ mv starter_files/* .
$ rmdir starter_files

You should have these files.

$ tree
.
├── chat485
│   └── echo.py
├── pyproject.toml
├── requirements.txt
└── tests
    └── ...

Before making any changes to the clean starter files, it’s a good idea to make a commit to your Git repository.

Python virtual environment

Create a Python virtual environment inside of the project directory using the Python Virtual Environment Tutorial.

$ source env/bin/activate

You should now have Python tools and third party packages installed locally. Notice that the path to python is in the virtual environment (p2-chat485-serverside/env/bin).

$ which python
/Users/awdeorio/src/eecs485/p2-chat485-serverside/env/bin/python

Sanity-check your Flask version. Your version may be different, but they should match. If not, re-run pip install -r requirements.txt.

$ flask --version
Python 3.12.0
Flask 3.1.2
Werkzeug 3.1.5
$ grep -i ^flask requirements.txt
Flask==3.1.2

Install utilities

Install sqlite3.

Linux and Windows Subsystem for Linux

$ sudo apt-get install sqlite3

MacOS

$ brew install sqlite3

chat485install script

Write an installation shell script bin/chat485install. It creates a Python virtual environment and installs the back end.

#!/bin/bash
set -Eeuo pipefail
set -x

# Python virtual environment
python3 -m venv env
source env/bin/activate

# Install back end
pip install -r requirements.txt
pip install -e .

Make your script executable and run it.

$ chmod +x bin/chat485install
$ ./bin/chat485install

Fresh install

Here’s how to start over with a fresh install. This removes your database and reinstalls dependencies.

$ deactivate  # If your virtual environment is activated
$ rm -rf env var
$ ./bin/chat485install
$ source env/bin/activate

Database

If you’re new to SQL, take a look at the w3Schools SQL Intro.

This project assumes you have completed the SQLite Tutorial.

chat485db script

Write a database management shell script bin/chat485db following the Database management shell script section of the SQLite Tutorial. Your script should support these subcommands:

$ ./bin/chat485db create
$ ./bin/chat485db destroy
$ ./bin/chat485db reset

Schema

Create sql/schema.sql to create four tables: users, sessions, conversations, and messages. The list below describes the tables and columns. Include the line PRAGMA foreign_keys = ON; at the top of schema.sql so SQLite enforces foreign key constraints.

• users table
  • userid, integer, primary key, automatically incremented with AUTOINCREMENT
  • fullname, at most 255 chars
  • email, at most 255 chars, unique
  • password, at most 255 chars
  • created, DATETIME type, automatically set by SQL engine to current date/time
• sessions table
  • The column design of the sessions table is up to you. Deleting a user should automatically remove their session rows. See Sessions for how the backend uses the table.
• conversations table
  • conversationid, integer, primary key, automatically incremented with AUTOINCREMENT
  • uuid, at most 36 chars, unique. This is the public identifier used in URLs. Use a canonical lowercase-hex UUID, the 36-char 8-4-4-4-12 form produced by str(uuid.uuid4()) (for example 550e8400-e29b-41d4-a716-446655440000).
  • sessionid, at most 36 chars, nullable, foreign key to sessions. Set on conversations created by an anonymous session; NULL on conversations owned by a logged-in user.
  • userid, integer, nullable, foreign key to users. Set on conversations owned by a logged-in user; NULL on anonymous conversations.
  • title, at most 255 chars, nullable.
  • created, DATETIME type, automatically set by SQL engine to current date/time
  • Deleting a session or user should automatically remove the conversations linked to it.
  • Exactly one of sessionid and userid is set per row, never both and never neither. Enforce this with a CHECK constraint.
• messages table
  • messageid, integer, primary key, automatically incremented with AUTOINCREMENT
  • conversationid, integer, foreign key to conversations
  • role, at most 20 chars. One of user, assistant, or system.
  • content, TEXT type
  • created, DATETIME type, automatically set by SQL engine to current date/time
  • Deleting a conversation should automatically remove its messages.

Every column listed above is required (see NOT NULL) unless explicitly marked optional or nullable. PRIMARY KEY and DEFAULT attributes automatically imply the NOT NULL constraint.

With schema.sql written, you should pass one unit test.

$ source env/bin/activate  # Make sure virtual environment is activated
$ pytest -v tests/test_database_public.py::test_sql_schema

Sessions

The backend tracks one session per browser using a cookie. The session implementation supports anonymous browsing while still keeping each user’s conversation history separate.

A write request (a form POST) with no cookie mints a fresh session UUID and inserts a row into the sessions table with no user attached. Anonymous users can create and view conversations the same way logged-in users can; each anonymous session sees only its own conversations.

A read request (a page GET) never mints a session. An HTTP GET must be safe: it reports whatever session it finds, and finds none for a first-time visitor, rather than creating one as a side effect.

Logging in or signing up makes the user’s conversations visible in any future login, including anonymous conversations from this browser and conversations they previously owned on any browser. The backend does two things:

1. Claim anonymous conversations. Every conversation currently linked to this session by sessionid gets userid set to the authenticated user and its sessionid cleared, so it now belongs to the user.
2. Rotate the sessionid. The backend mints a fresh session UUID, inserts a new sessions row linked to the user, deletes the old session row, and sets the new sessionid cookie on the response.

Logging out deletes the session row and clears the sessionid cookie. The next write request from the same browser mints a fresh anonymous session, the same path a first-time visitor takes.

Data

Create sql/data.sql to add initial data for each table. Do not specify created timestamps in your INSERT statements; let the SQL engine fill them in automatically.

Paste the hashed (“encrypted”) password directly into data.sql. It looks like this: sha512$34e94a05$7eaca2b4, explained later under Password storage. The plain text password for awdeorio@umich.edu is chickens.

Seed the database with:

• The awdeorio user (userid = 1), full name Andrew DeOrio, email awdeorio@umich.edu.
• A sessions row with session UUID 550e8400-e29b-41d4-a716-446655440000 linked to awdeorio (userid = 1).
• Two conversations owned by awdeorio: Hello World and Visiting Ann Arbor, with their messages.

Reproduce the seed contents in docs/chat485db-dump.txt for the awdeorio user, the seed sessions row, and conversations 1 (“Hello World”) and 2 (“Visiting Ann Arbor”) with their messages. Tests pin the titles and message contents, not the timestamps; your timestamps will differ and that is fine. You may add more rows for your own development or manual testing, but do not change the provided conversations or messages.

With data.sql written, you should pass one unit test.

$ pytest -v tests/test_database_public.py::test_sql_data

Make sure both database tests pass before moving on. The other tests rely on a working database and bin/chat485db script.

Server-side Chat485

Build the Flask application that renders pages and handles form submissions.

Setup

Complete the Flask Tutorial.

You should now have a directory containing a chat485 Python module.

$ tree chat485 -I '__pycache__'
chat485
├── __init__.py
├── config.py
├── model.py
├── static
│   └── css
│       └── style.css
├── templates
│   └── index.html
└── views
    ├── __init__.py
    └── index.py

Run the Flask development server.

$ flask --app chat485 --debug run --host 0.0.0.0 --port 8000

Navigate to http://localhost:8000/. You should see the “hello world” page from the Flask Tutorial, which confirms your app is wired up. You’ll replace it with the real home page next.

Lint early and often. As you write code, fix style problems automatically.

$ ruff check --fix chat485
$ ruff format chat485

Commit these changes and push to your Git repository.

chat485run script

Write a shell script bin/chat485run that starts the development server on port 8000.

#!/bin/bash
set -Eeuo pipefail

# Make sure database exists
if [ ! -e var/chat485.sqlite3 ]; then
  echo "Error: can't find database var/chat485.sqlite3"
  echo "Try: ./bin/chat485db create"
  exit 1
fi

set -x
flask --app chat485 --debug run --host 0.0.0.0 --port 8000

Reset the database and start the server.

$ ./bin/chat485db reset
$ ./bin/chat485run

Navigate to http://localhost:8000/.

Chat completions API

We ship an OpenAI-compatible chat completions endpoint (chat485/echo.py) that echoes messages back to the user. Your forwarding code (see Forwarding the request) calls it exactly as it would a real LLM provider.

Register the echo server in chat485/__init__.py:

import chat485.echo  # noqa: E402
import chat485.model  # noqa: E402
import chat485.views  # noqa: E402

Try the echo server end-to-end from the command line:

$ brew install httpie  # macos
$ apt install httpie   # WSL
$ http POST http://localhost:8000/api/v1/chat/completions \
    model=echo-1 \
    messages:='[{"role": "user", "content": "Hello world"}]'

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "Hello world",
                "role": "assistant"
            }
        }
    ],
    "created": 1747055123,
    "id": "chatcmpl-7b3c2d1e4f5a67890abcdef123456",
    "model": "echo-1",
    "object": "chat.completion"
}

The echo server returns the last user message regardless of the system prompt and earlier messages. Sending the full message history is how a stateless model would know about the conversation so far.

The echo server enforces a hard-coded context window of 8000 characters across all messages in a single request, including the system prompt. Requests over the limit return HTTP 400 with an OpenAI-style error body. Real providers enforce similar limits in tokens. The echo server uses characters so it is deterministic and easy to test.

$ http POST http://localhost:8000/api/v1/chat/completions \
    model=echo-1 \
    messages:="$(python3 -c 'import json; print(json.dumps([{"role":"user","content":"x"*8001}]))')"

{
    "error": {
        "code": "context_length_exceeded",
        "message": "Request exceeds context window of 8000 characters (got 8001)."
    }
}

Pages overview

Chat485 is five distinct pages, all rendered server-side from Jinja templates: the home page, a conversation page, and three account pages (create, login, edit). This section is a quick visual tour so the route specs that follow have a picture to attach to.

A first-time visitor lands on the home page anonymously, with an empty sidebar.

After logging in, the sidebar lists the user’s conversations. A brand-new conversation that has not yet received a first message shows the literal placeholder “New conversation”; older conversations show their generated title.

Clicking a conversation renders its messages and a send form.

The three account pages are conventional forms. Create-account collects full name, email, and password. Login collects email and password. Edit-account is pre-filled with the current full name and email.

The home and conversation pages share a sidebar layout; the three account pages are standalone forms. Build each shared layout as a base template that leaf templates extend with {% extends %}, so the common parts lives in one place.

The recurring pieces:

• Sidebar: Appears on the home and conversation pages. Lists the current session’s conversations, newest first, each linking to its conversation page. Includes a “New chat” button at the top and, at the bottom, the current user’s full name (when logged in) or a “Log in” link (when anonymous).
• Conversation list: The body of the sidebar. Each entry shows the conversation’s title, or “New conversation” when the title is still NULL. Each entry has a delete button. On a conversation page, mark the current conversation (the one whose uuid equals current_uuid) by adding aria-current="page" to its sidebar link. The home page marks no conversation. Styling the marked conversation is optional (see Reach goals).
• Send form: Below the messages on the conversation page only. A <textarea name="content">, a <select name="model"> model picker, and a submit button.
• Account pages: Standalone forms at /accounts/create/, /accounts/login/, and /accounts/edit/.

Authentication and access control

A conversation belongs to exactly one of a session (anonymous) or a user (logged in).

• A logged-in user owns conversations by userid. These survive logout and are reachable on any browser after login.
• An anonymous session owns conversations by sessionid.

For any route that names a conversation by UUID:

• If no conversation with that UUID exists, respond 404 Not Found.
• If the conversation exists but the current session does not own it, respond 403 Forbidden.

Home page

GET /

Render the sidebar (the current session’s conversations) and an empty main area inviting the user to select a conversation or start a new chat.

An anonymous visitor with no conversations sees an empty sidebar. A logged-in user sees their conversations.

You should now pass one unit test, which renders the home page for an anonymous visitor.

$ pytest -v tests/test_index_public.py::test_index_anonymous

Conversation detail

GET /conversations/<uuid>/

Render the conversation’s 10 most recent messages in chronological order with the oldest first.

Below the messages, render a send form (see Message create) containing:

• a <textarea name="content"> for the message text.
• a <select name="model"> model picker, populated from the models configured in chat485/config.py. Each model is an <option> whose value is the model id, for example <option value="echo-1">. echo-1 is always present, listed first, and selected by default; additional models appear when configured (see Reach goals).
• a submit button.

Apply the access control rules: 404 if the UUID does not exist, 403 if the current session does not own it.

See Pagination for loading older messages. See Markdown rendering for formatting Markdown in the message text.

Conversation create

POST /conversations/

Create a new conversation owned by the current session, then respond with a 302 redirect to its conversation page (see Conversation detail).

A new conversation starts with a NULL title. Later, the first user message will set the title.

If the request arrives with no session, mint a fresh anonymous session, insert the conversation under that session, and set the sessionid cookie on the redirect response.

You should now pass one unit test, which creates a conversation and follows the redirect to its page.

$ pytest -v tests/test_conversations_public.py::test_create_redirects_to_conversation

import uuid
sessionid = str(uuid.uuid4())  # e.g. '550e8400-e29b-41d4-a716-446655440000'

Message create

POST /conversations/<uuid>/messages/

Send a message. This is the route that triggers the LLM round-trip.

The form body has two fields: content (the message text) and model (the model id from the picker). On success:

1. Save the user’s message with role user.
2. If this is the first message in the conversation, set the conversation title (see Conversation title).
3. Forward the recent history to the chat completions API (see Chat completions API).
4. Save the assistant’s reply with role assistant.
5. Respond with a 302 redirect back to the conversation page so the browser reloads with both new messages rendered.

If content is empty, do nothing and respond with a 302 redirect back to the conversation page.

If the chat completions call fails, see Chat completions API failure.

Apply the access control rules: 404 if the UUID does not exist, 403 if the current session does not own it.

Once a sent message stores both the user message and the echoed assistant reply, you should pass one unit test.

$ pytest -v tests/test_messages_public.py::test_send_message_echo_reply

Forwarding the request

Forward the conversation history to the chosen model’s chat completions endpoint with requests.post(). Send at most the 20 most recent messages, including the user message you just persisted. Older messages remain in the database but do not enter the upstream request. This keeps request size bounded so long conversations do not exceed the model’s context window or grow request latency without bound. Send the messages in chronological order (oldest first), not the newest-first order a database query returns.

Prepend a single system message at index 0 with role system. Its content must include the product name Chat485. Build it at request time, and do not store it in the database. Beyond naming the product, the wording is yours: a typical system prompt also gives guidelines for response style and states the current date.

The outgoing payload is a JSON object with two keys: model (the model id from the form, or echo-1 if omitted) and messages (the OpenAI-compatible list of role and content objects). Example for a conversation with two prior exchanges plus a new user message:

{
  "model": "echo-1",
  "messages": [
    {"role": "system", "content": "You are Chat485..."},
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there"},
    {"role": "user", "content": "Tell me a joke"},
    {"role": "assistant", "content": "..."},
    {"role": "user", "content": "What is Flask?"}
  ]
}

Store assistant content from the reply verbatim in the database. The endpoint’s request and response format, including its context-window limit, are documented in Chat completions API.

Conversation delete

POST /conversations/<uuid>/delete/

Delete a conversation and all of its messages, then respond with a 302 redirect to the home page (see Home page).

Apply the access control rules: 404 if the UUID does not exist, 403 if the current session does not own it.

The delete button lives in each conversation-list entry (see Pages overview).

Account create

GET, POST /accounts/create/

The create-account page. GET renders the form. POST processes it.

The form has three fields: fullname, email, and password. On POST:

• If any field is empty, re-render the form with an error message and no redirect.
• If the email already belongs to an existing account, re-render the form with an error message and no redirect.
• Otherwise, hash the password (see Password storage), insert the new user, log the new user in (claim anonymous conversations and rotate the sessionid, see Sessions), and respond with a 302 redirect to the home page.

Password storage

Store each password in a single password column formatted as algorithm$salt$hexdigest. Use the sha512 algorithm:

import hashlib
import uuid

algorithm = "sha512"
salt = uuid.uuid4().hex
hash_obj = hashlib.new(algorithm)
password_salted = salt + password
hash_obj.update(password_salted.encode("utf-8"))
password_hash = hash_obj.hexdigest()
password_db_string = "$".join([algorithm, salt, password_hash])

To verify a login attempt, split the stored entry on $ to recover the algorithm and salt, hash salt + candidate_password with the same algorithm, and compare the result against the stored hexdigest.

Salting defeats rainbow-table attacks. An attacker who steals the database cannot precompute a single lookup table and reuse it across accounts because each row uses a unique salt.

Account edit

GET, POST /accounts/edit/

The edit-account page. This route requires a logged-in user; an anonymous request returns 403 Forbidden.

GET renders the form pre-filled with the user’s current full name and email. POST updates the user’s fullname and email, then responds with a 302 redirect to the home page. If a field is empty, or the new email already belongs to a different account, re-render the form with an error message and no redirect.

Account login

GET, POST /accounts/login/

The login page. GET renders the form. POST processes it.

The form has two fields: email and password. On POST:

• If the credentials are invalid, re-render the form with an error message and no redirect.
• Otherwise, log the user in (claim anonymous conversations and rotate the sessionid, see Sessions) and respond with a 302 redirect to the home page.

Account logout

POST /accounts/logout/

Delete the current session row, clear the sessionid cookie, and respond with a 302 redirect to the home page. The user’s owned conversations are unaffected because they are keyed off userid.

With login and logout both working, you should pass one unit test that logs the seed user in and back out.

$ pytest -v tests/test_accounts_public.py::test_login_logout_round_trip

Enhancements

These features are graded but not needed for the core send-and-reply flow. Build them once the happy path works. They are independent and can be done in any order.

Conversation title

The first user message in a conversation sets the conversation’s title. Title generation rule:

1. If the message is 30 characters or fewer, the title equals the message verbatim.
2. Otherwise, take the first 30 characters. If that window contains a space, cut at the last space (drop the partial trailing word, no trailing space). If the window contains no space at all, keep all 30 characters.
3. Append the three-character ASCII suffix "..." (not the Unicode … character).

Examples:

Chat completions API failure

A request can fail two ways: the LLM API returns an error response, or it never completes (a timeout or unreachable server). In either case, no assistant message is saved; the user’s message stays in the database.

Redirect back to the conversation page (same as a successful send), then render an inline error bubble below the last message, “Something went wrong, please try again.” Do not render the error when the conversation is opened again later.

See chat completions call for API failure examples.

$ python3 -c 'print("lorem ipsum " * 700)' | pbcopy    # macos
$ python3 -c 'print("lorem ipsum " * 700)' | clip.exe  # WSL

Markdown rendering

Render every message as Markdown, and syntax-highlight fenced code blocks by language. Use the Markdown library with the fenced_code, tables, and codehilite extensions.

Use a custom Jinja filter applied in a template with the | syntax:

<div>
{{ message.content | markdown }}
</div>

Define the filter in chat485/filters.py:

import markdown
import markupsafe

import chat485


@chat485.app.template_filter("markdown")
def render_markdown(text):
    """Render Markdown text to safe HTML."""
    html = markdown.markdown(
        text or "",
        extensions=["fenced_code", "tables", "codehilite"],
    )
    return markupsafe.Markup(html)

Register the filter in chat485/__init__.py:

import chat485.echo  # noqa: E402
import chat485.filters  # noqa: E402
import chat485.model  # noqa: E402
import chat485.views  # noqa: E402

Add a seed conversation with Markdown messages (headings, code blocks, lists, tables) to sql/data.sql so you can see the rendering as you build.

The autograder checks the generated HTML: h1/h2/h3, strong/em/code, ul/ol/li, blockquote, table, and syntax-highlighted code (codehilite wraps each token in a span). The Markdown library emits all of these for you. It does not grade CSS.

Optional: Two stylesheets make the rendering look polished, and neither is graded. github-markdown.css styles the markdown-body container; highlight.css colors the code blocks (pygmentize ships with Pygments). Generate them, link both in base.html ahead of style.css, and add the markdown-body class to the container around assistant messages.

$ wget https://cdn.jsdelivr.net/npm/github-markdown-css@5/github-markdown-light.css -O chat485/static/css/github-markdown.css
$ pygmentize -S default -f html -a .codehilite > chat485/static/css/highlight.css

<link rel="stylesheet" type="text/css"
      href="{{ url_for('static', filename='css/github-markdown.css') }}">
<link rel="stylesheet" type="text/css"
      href="{{ url_for('static', filename='css/highlight.css') }}">

In P3 you’ll move this same Markdown rendering to the client, where the React app renders it in the browser as messages arrive over the API.

Scroll to bottom

Show the newest message at the bottom of the message list, the way a chat app shows the latest reply without a manual scroll. Apply this when a conversation opens and after every user message.

Every send round-trips through Post/Redirect/Get, so the browser reloads the whole page and lands back at the top. Solve it with CSS or markup, not client-side JavaScript, and without moving keyboard focus to force the scroll (for example, by focusing a hidden element).

Your solution must hold up once a conversation is long enough to overflow the message area: the newest message starts in view at the bottom, and the user can still scroll up to read the oldest messages.

The awkwardness of this implementation is the point. In P3 you’ll rebuild this page with client-side JavaScript, where a few lines handle the scroll with no reload and no tricks.

Pagination

A conversation page renders the 10 most recent messages, not the whole transcript. When older messages exist, render a “Load older messages” link at the top of the message list. With 10 or fewer messages, render no link.

Following the link is a full-page GET to /conversations/<uuid>/?before=<messageid>, where <messageid> is the id of the oldest message currently shown. The page re-renders with the 10 newest messages that are older than <messageid>, again with the link if more remain. Reopen the conversation to return to the newest messages.

Use a messageid cursor, not a page number: messages are only appended at the newest end, so an id stays stable as the conversation grows, while a page number would shift whenever the user sends more.

Pagination is a display concern, separate from the model-history cap (see Message create) that bounds how many messages reach the model; the two limits are independent.

Testing

Lint with ruff, which checks conformance to the PEP 8 Style Guide and PEP 257 Docstring Conventions. Do not add inline suppressions like # noqa; refactor the code instead.

$ ruff check chat485              # Report style and correctness problems
$ ruff check --fix chat485        # Fix lint errors automatically where possible
$ ruff format --check chat485     # Check formatting
$ ruff format chat485             # Fix formatting

With every page and its GET route in place, you should pass one unit test, which validates the HTML5 of all five rendered pages (see Pages overview).

$ pytest -v tests/test_html_validation_public.py::test_html_valid

Run all tests.

$ pytest -v

Write your own tests

Write your own tests in tests/test_student.py. Each def test_... function is one test.

Run your tests the same way as the instructor-written tests:

$ pytest -v tests/test_student.py

Your tests are graded by mutation testing. Target distinct spec-mandated behavior the public tests do not already cover.

$ cat tests/test_accounts_public.py | pbcopy  # macOS
$ cat tests/test_accounts_public.py | clip.exe  # WSL

Reach goals

Reach goals are optional. The autograder does not test them. A reach goal you complete stays in your submission and the autograder still passes, because it checks required behavior, not the absence of extras.

The Paid providers and Ollama reach goals add models to chat485/config.py. A model is available, and appears in the send form’s picker, when it has no API key requirement (echo-1 and the local Ollama model) or when its API key is set in the environment (a paid provider). A paid provider with no key configured is hidden.

Paid providers

Connect Chat485 to a real LLM. Chat485 already speaks the OpenAI chat completions format, so the setup is short: get an API key, add it to .env, update config.py, and attach the key as an Authorization header when you forward the request.

Authenticating requests

A paid provider authenticates each request with your API key, sent as an HTTP Authorization: Bearer <key> header. In your chat completions forwarding code (see Forwarding the request), add the header only when the chosen model’s config.py entry has an api_key. The echo server and the Ollama model have no key, so their requests send no Authorization header:

headers = {}
api_key = model_config.get("api_key")
if api_key:
    headers["Authorization"] = f"Bearer {api_key}"
response = requests.post(
    # ...
    headers=headers,
)

Storing secrets

Chat485 reads API keys from a .env file at the project root. Before you create the file, add .env to .gitignore so it can never be committed:

...
# API keys
.env

We included python-dotenv so flask --app chat485 run automatically loads .env.

Anthropic. Get an API key, add credits, and set a spending cap.

CHAT485_ANTHROPIC_API_KEY=sk-ant-...

# Anthropic Models (Paid)
# 1. Get an API key at https://console.anthropic.com/settings/keys
# 2. Add it to .env: CHAT485_ANTHROPIC_API_KEY=sk-ant-...
# 3. Set a spending cap and add credits at
#    https://platform.claude.com/settings/billing
{
    "model": "claude-sonnet-4-6",
    "api_url": "https://api.anthropic.com/v1/chat/completions",
    "api_key": os.environ.get("CHAT485_ANTHROPIC_API_KEY"),
},

OpenAI. Get an API key, add credits, and set a spending cap.

CHAT485_OPENAI_API_KEY=sk-...

# OpenAI Models (Paid)
# 1. Get an API key at https://platform.openai.com/api-keys
# 2. Add it to .env: CHAT485_OPENAI_API_KEY=sk-...
# 3. Set a spending cap and add credits at
#    https://platform.openai.com/settings/organization/billing
{
    "model": "gpt-5",
    "api_url": "https://api.openai.com/v1/chat/completions",
    "api_key": os.environ.get("CHAT485_OPENAI_API_KEY"),
},

Gemini. Get an API key, add credits, and set a spending cap.

CHAT485_GEMINI_API_KEY=...

# Google Gemini Models (Paid)
# 1. Get an API key at https://aistudio.google.com/apikey
# 2. Add it to .env: CHAT485_GEMINI_API_KEY=...
# 3. Set a spending cap and add credits at
#    https://aistudio.google.com/billing
{
    "model": "gemini-3.0-flash",
    "api_url": "https://generativelanguage.googleapis.com"
    "/v1beta/openai/chat/completions",
    "api_key": os.environ.get("CHAT485_GEMINI_API_KEY"),
},

When a key is present, its model appears in the model picker.

Ollama local model

Ollama downloads and runs pretrained LLMs locally. It has a built-in REST API compatible with the OpenAI format. The echo server works without Ollama, but you can optionally install it to chat with a real model.

Install Ollama and start the service:

$ brew install ollama
$ brew services start ollama

Select a model. We recommend llama3.2:3b. 8 GB of RAM is enough if you close down most apps. 16 GB is comfortable.

Pull a model. The llama3.2:3b model is about 2 GB and could take 10 minutes:

$ ollama pull llama3.2:3b

Once running, the local model appears in the model picker.

CSS / styling

Style your pages with CSS. This reach goal originates in Project 1, where you first style static pages, and carries forward here. Add a stylesheet under chat485/static/ and link it from your base template.

Submitting and grading

One team member should register your group on the autograder.

Submit a tarball to the autograder, which is linked from https://eecs485.org. Include the --disable-copyfile flag only on macOS.

$ tar \
  --disable-copyfile \
  --exclude '*__pycache__*' \
  -czvf submit.tar.gz \
  bin \
  chat485 \
  sql \
  tests/test_student.py

FIXME: add the direct link to the Winter 2026 Project 2 autograder (https://autograder.io/web/project/<id>) once the autograder project is created.

The autograder uses its own build, dependency, and lint configuration. Do not add or change dependencies, and do not relax lint rules.

Public tests run with their full output visible on the autograder. Private tests show only pass/fail status. No additional tests run after the deadline.

Testing

Run these before submitting; the autograder runs the same checks plus hidden ones.

Lint:

$ ruff check chat485
$ ruff format --check chat485

Test:

$ pytest -v

chat485test script

Write a shell script bin/chat485test that does this:

1. Stop on errors and print commands
2. Run ruff check chat485
3. Run ruff format --check chat485
4. Run all unit tests using pytest -v

Mutation testing

We autograde the tests you write in tests/test_student.py. See Write your own tests for the file and run command.

A suite must run within the autograder’s time limit and contain 10 or fewer test_ functions.

To grade your tests, we use a set of intentionally buggy instructor solutions called mutants. You earn points for catching the bugs.

1. We rebuild the app with the correct solution and run your tests.
   • Tests that pass are valid.
   • Tests that fail are invalid; they falsely report a bug and earn no credit.
2. We run your valid tests against each buggy solution (mutant).
   • If any of your tests fails, you caught the bug.
   • You earn points for each mutant you catch.

Acknowledgments

Original project written by Andrew DeOrio awdeorio@umich.edu, 2026.

This document is licensed under a Creative Commons Attribution-NonCommercial 4.0 License.