build_tools.syllable_walk_web.api.walker

Walker API handlers for the web application.

Handles corpus loading, walk generation, name generation, analysis, and walker state queries.

Functions

handle_load_corpus(body, state)	Handle POST /api/walker/load-corpus.
handle_walk(body, state)	Handle POST /api/walker/walk.
handle_stats(state)	Handle GET /api/walker/stats.
handle_save_session(body, state)	Handle POST /api/walker/save-session.
handle_sessions(state)	Handle GET /api/walker/sessions.
handle_load_session(body, state)	Handle POST /api/walker/load-session.
handle_rebuild_reach_cache(body, state)	Handle POST /api/walker/rebuild-reach-cache.
handle_session_lock_heartbeat(body, state)	Handle POST /api/walker/session-lock/heartbeat.
handle_session_lock_release(body, state)	Handle POST /api/walker/session-lock/release.
handle_reach_syllables(body, state)	Handle POST /api/walker/reach-syllables.
handle_combine(body, state)	Handle POST /api/walker/combine.
handle_select(body, state)	Handle POST /api/walker/select.
handle_export(body, state)	Handle POST /api/walker/export.
handle_package(body, state)	Handle POST /api/walker/package.
handle_analysis(patch_key, state)	Handle GET /api/walker/analysis/<patch>.

Module Contents

build_tools.syllable_walk_web.api.walker.handle_load_corpus(body, state)

Handle POST /api/walker/load-corpus.

Loads syllables from a discovered pipeline run and initialises the SyllableWalker in a background thread.

Parameters:

• body (dict[str, Any]) – Request body with patch (“a” or “b”) and run_id.

• state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

Immediate response with syllable count and loading status.

Return type:

dict[str, Any]

build_tools.syllable_walk_web.api.walker.handle_walk(body, state)

Handle POST /api/walker/walk.

Generates walks for a specified patch.

Parameters:

• body (dict[str, Any]) – Request body with walk parameters.

• state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

Walk results with formatted walks.

Return type:

dict[str, Any]

build_tools.syllable_walk_web.api.walker.handle_stats(state)

Handle GET /api/walker/stats.

Returns current walker state for both patches.

Parameters:

state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

State summary for patches A and B.

Return type:

dict[str, Any]

build_tools.syllable_walk_web.api.walker.handle_save_session(body, state)

Handle POST /api/walker/save-session.

Persists one dual-patch session artifact under the runtime-resolved sessions base directory.

build_tools.syllable_walk_web.api.walker.handle_sessions(state)

Handle GET /api/walker/sessions.

Returns saved session artifacts ordered newest-first with verification metadata so clients can decide what is safe to load.

build_tools.syllable_walk_web.api.walker.handle_load_session(body, state)

Handle POST /api/walker/load-session.

Verifies one persisted session payload and triggers corpus loading for each referenced patch run. This reuses the existing corpus-load API semantics rather than mutating state via internal shortcuts.

build_tools.syllable_walk_web.api.walker.handle_rebuild_reach_cache(body, state)

Handle POST /api/walker/rebuild-reach-cache.

Recomputes profile reach tables for one loaded patch and rewrites the run-local IPC cache artifact.

build_tools.syllable_walk_web.api.walker.handle_session_lock_heartbeat(body, state)

Handle POST /api/walker/session-lock/heartbeat.

Refreshes a session lock lease for the caller’s holder id. This is cooperative multi-tab coordination, not an auth/security layer.

build_tools.syllable_walk_web.api.walker.handle_session_lock_release(body, state)

Handle POST /api/walker/session-lock/release.

Releases the current lease when called by lock owner.

build_tools.syllable_walk_web.api.walker.handle_reach_syllables(body, state)

Handle POST /api/walker/reach-syllables.

Returns the list of reachable syllables for a given profile and patch, sorted alphabetically with frequency data.

Parameters:

• body (dict[str, Any]) – Request body with patch and profile.

• state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

Dict with profile, reach, total, and syllables list.

Return type:

dict[str, Any]

build_tools.syllable_walk_web.api.walker.handle_combine(body, state)

Handle POST /api/walker/combine.

Generates name candidates from the loaded corpus syllables.

Supports two generation modes selected by the profile parameter:

• Flat (profile absent or "flat"): Independent random sampling using frequency_weight (0.0–1.0). No walker required.

• Walk-based (profile is a named profile or "custom"): Graph traversal using the walker’s neighbor graph. Requires the walker to be initialised (walker_ready).

Parameters:

• body (dict[str, Any]) – Request body with patch, count, syllables, seed, frequency_weight, and optionally profile, max_flips, temperature.

• state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

Candidate generation summary with count and sample.

Return type:

dict[str, Any]

build_tools.syllable_walk_web.api.walker.handle_select(body, state)

Handle POST /api/walker/select.

Selects names from candidates using a name class policy.

Parameters:

• body (dict[str, Any]) – Request body with patch, name_class, count, mode, seed.

• state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

Selection results with names and metadata.

Return type:

dict[str, Any]

build_tools.syllable_walk_web.api.walker.handle_export(body, state)

Handle POST /api/walker/export.

Returns selected names as a downloadable list.

Parameters:

• body (dict[str, Any]) – Request body with patch.

• state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

Dict with names list for client-side download.

Return type:

dict[str, Any]

build_tools.syllable_walk_web.api.walker.handle_package(body, state)

Handle POST /api/walker/package.

Builds a ZIP archive from in-memory walker state.

Parameters:

• body (dict[str, Any]) – Request body with name, version, and include flags.

• state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

Tuple of (zip_bytes, filename, error_message_or_none).

Return type:

tuple[bytes, str, str | None]

build_tools.syllable_walk_web.api.walker.handle_analysis(patch_key, state)

Handle GET /api/walker/analysis/<patch>.

Computes corpus shape metrics for a patch.

Parameters:

• patch_key (str) – "a" or "b".

• state (build_tools.syllable_walk_web.state.ServerState) – Global server state.

Returns:

Corpus analysis metrics (inventory, frequency, terrain).

Return type:

dict[str, Any]