build_tools.syllable_walk.server

HTTP server for the syllable walker web interface.

This module provides a web-based interface for exploring syllable walks using the standard library’s http.server module (no Flask dependency). The server handles: - Serving the HTML interface (/) - Serving CSS styles (/styles.css) - Providing walker statistics (/api/stats) - Generating syllable walks (/api/walk)

Usage:

from build_tools.syllable_walk.server import run_server run_server(data_path, max_neighbor_distance=3, port=5000)

Classes

WalkerHTTPHandler

HTTP request handler for the syllable walker web interface.

Functions

run_server(data_path[, max_neighbor_distance, port, ...])

Initialize syllable walker and start the web server.

Module Contents

class build_tools.syllable_walk.server.WalkerHTTPHandler(request, client_address, server)[source]

Bases: http.server.BaseHTTPRequestHandler

HTTP request handler for the syllable walker web interface.

This handler processes HTTP requests and serves the web interface. It maintains a reference to the SyllableWalker instance and handles routing for HTML, CSS, and API endpoints.

Class Attributes:

walker: Shared SyllableWalker instance used for all requests

walker: build_tools.syllable_walk.walker.SyllableWalker | None = None
log_message(format, *args)[source]

Override to suppress default request logging to keep console clean.

Parameters:

  • format (str) – Log message format string

  • *args (Any) – Arguments to format into the message

do_GET()[source]

Handle GET requests for HTML, CSS, and stats API endpoint.

Routes:

/: Serve main HTML interface /styles.css: Serve CSS stylesheet /api/stats: Return walker statistics as JSON *: 404 for all other paths

do_POST()[source]

Handle POST requests for walk generation API endpoint.

Routes:

/api/walk: Generate a syllable walk based on JSON parameters

Request JSON format:
{

“start”: str | null, # Starting syllable (null = random) “profile”: str, # Walk profile name or “custom” “steps”: int, # Number of steps in walk “max_flips”: int, # Max feature flips (for custom) “temperature”: float, # Temperature (for custom) “frequency_weight”: float, # Frequency weight (for custom) “seed”: int | null # Random seed (null = random)

}

Response JSON format:
{

“walk”: list[dict], # List of syllable dicts “profile”: str, # Profile name used “start”: str # Starting syllable used

}

build_tools.syllable_walk.server.run_server(data_path, max_neighbor_distance=3, port=5000, verbose=True)[source]

Initialize syllable walker and start the web server.

This function loads the syllable data, initializes the walker with neighbor graph construction, and starts the HTTP server on the specified port. The server runs until interrupted with Ctrl+C.

Parameters:

  • data_path (pathlib.Path | str) – Path to syllables_annotated.json file

  • max_neighbor_distance (int) – Maximum Hamming distance for neighbor graph (1-3). Higher values allow more diverse walks but slower initialization. Default: 3

  • port (int) – Port number for HTTP server. Default: 5000

  • verbose (bool) – Whether to print initialization progress. Default: True

Raises:

Example

>>> run_server("data/annotated/syllables_annotated.json", port=8000)
# Server starts on http://localhost:8000