build_tools.syllable_walk.server
================================

.. py:module:: build_tools.syllable_walk.server

.. autoapi-nested-parse::

   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
-------

.. autoapisummary::

   build_tools.syllable_walk.server.WalkerHTTPHandler


Functions
---------

.. autoapisummary::

   build_tools.syllable_walk.server.run_server


Module Contents
---------------

.. py:class:: WalkerHTTPHandler(request, client_address, server)

   Bases: :py:obj:`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


   .. py:attribute:: walker
      :type:  build_tools.syllable_walk.walker.SyllableWalker | None
      :value: None



   .. py:method:: log_message(format, *args)

      Override to suppress default request logging to keep console clean.

      :param format: Log message format string
      :param \*args: Arguments to format into the message



   .. py:method:: do_GET()

      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



   .. py:method:: do_POST()

      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
          }



.. py:function:: run_server(data_path, max_neighbor_distance = 3, port = 5000, verbose = True)

   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.

   :param data_path: Path to syllables_annotated.json file
   :param max_neighbor_distance: Maximum Hamming distance for neighbor graph (1-3).
                                 Higher values allow more diverse walks but slower initialization. Default: 3
   :param port: Port number for HTTP server. Default: 5000
   :param verbose: Whether to print initialization progress. Default: True

   :raises FileNotFoundError: If data_path does not exist
   :raises ValueError: If max_neighbor_distance is invalid
   :raises OSError: If port is already in use

   .. admonition:: Example

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