MUD Server Client

Synchronous HTTP client for the MUD server lab API.

app/mud_server_client.py

Synchronous HTTP client for the mud server’s lab API endpoints.

This module provides a thin wrapper around the mud server’s REST API, enabling the Axis Descriptor Lab to delegate OOC→IC translation to the mud server’s canonical pipeline instead of running its own Ollama calls.

Environment values still provide startup defaults, but the active chat mode is now runtime-configurable inside the app. That lets the Chat Translation page switch between offline mode, a local development mud server, and an optional configured server without editing .env or restarting FastAPI.

The client stores the session token in memory only — never written to disk. On any 401 response from a lab endpoint the cached token is cleared and MudServerSessionExpiredError is raised so the caller can signal the frontend to re-authenticate.

Connection management

A persistent httpx.Client is created once in __init__ and reused for all subsequent requests. This ensures TCP connections and TLS sessions are pooled across calls, avoiding the cost of a fresh TLS handshake on every request to a remote HTTPS server. httpx.Client is thread-safe, which is required since FastAPI runs sync handlers in a thread-pool executor.

Sync rationale

The lab’s route handlers are synchronous (FastAPI runs them in a thread-pool executor), so a blocking httpx call here matches the existing pattern used by ChatRenderer.

exception app.mud_server_client.MudServerSessionExpiredError

Bases: Exception

Raised when the mud server returns 401 (session invalid/expired).

exception app.mud_server_client.MudServerConnectionError

Bases: Exception

Raised when the mud server is unreachable or a request times out.

exception app.mud_server_client.MudServerFeatureUnavailableError

Bases: Exception

Raised when the active mud server does not implement a required lab feature.

class app.mud_server_client.MudRuntimeModeOption(key, label, translation_mode, server_url)

Bases: object

One runtime-selectable chat translation mode.

key

Stable frontend/backend selector key.

Type:

str

label

Human-readable label for the mode selector.

Type:

str

translation_mode

External mode string used by existing UI badges.

Type:

str

server_url

Mud server base URL for server-backed modes, or None for standalone/offline mode.

Type:

str | None

key: str

label: str

translation_mode: str

server_url: str | None

__init__(key, label, translation_mode, server_url)

class app.mud_server_client.MudModeOptionDict

Bases: TypedDict

Serialised runtime mode option returned to the route layer.

key: str

label: str

translation_mode: str

server_url: str | None

class app.mud_server_client.MudModeConfigDict

Bases: TypedDict

Serialised runtime mode configuration returned to the route layer.

mode_key: str

translation_mode: str

active_server_url: str | None

available_modes: list[MudModeOptionDict]

class app.mud_server_client.MudServerClient(base_url, timeout=120.0)

Bases: object

Synchronous client for the mud server’s lab API endpoints.

Maintains an in-memory session token obtained via login(). All lab endpoint calls attach the session_id in the request body (POST) or query params (GET), matching the mud server’s pattern.

A persistent httpx.Client is created once and reused for all requests, enabling TCP/TLS connection pooling to the remote server.

Parameters:

• base_url (str) – Mud server base URL (e.g. 'https://api.pipe-works.org').

• timeout (float) – HTTP read timeout in seconds. Defaults to 120.

__init__(base_url, timeout=120.0)

close()

Close the underlying httpx.Client and release connections.

property is_authenticated: bool

True when a session token is cached in memory.

property selected_world_id: str | None

Currently selected world ID, or None.

login(username, password)

POST /login → store session_id + role in memory.

Returns:

The full LoginResponse dict from the mud server.

Raises:

• httpx.HTTPStatusError – Non-2xx response (e.g. 401 bad credentials).

• MudServerConnectionError – Server unreachable or timed out.

Return type:

dict

logout()

POST /logout → clear in-memory session.

Always clears the local session, even if the server call fails.

session_status()

Return current auth status without contacting the server.

select_world(world_id)

Store the selected world_id in memory.

list_worlds()

GET /api/lab/worlds → return worlds list.

Raises:

• MudServerSessionExpiredError – Session invalid/expired.

• MudServerConnectionError – Server unreachable or timed out.

world_config(world_id)

GET /api/lab/world-config/{world_id} → return config.

Raises:

• MudServerSessionExpiredError – Session invalid/expired.

• MudServerConnectionError – Server unreachable or timed out.

world_prompts(world_id)

Return world prompt templates for one world.

The preferred source remains GET /api/lab/world-prompts/{world_id}. Newer mud-server builds may intentionally remove that legacy endpoint. In that case, this method falls back to canonical policy APIs and synthesises a single active prompt entry for compatibility with the existing lab prompt UI.

Raises:

• MudServerSessionExpiredError – Session invalid/expired.

• MudServerConnectionError – Server unreachable or timed out.

world_image_policy_bundle(world_id)

GET /api/lab/world-image-policy-bundle/{world_id} → image policy bundle.

Raises:

• MudServerSessionExpiredError – Session invalid/expired.

• MudServerConnectionError – Server unreachable or timed out.

compile_image_prompt(*, world_id, species, gender, axes, world_context=None, occupation_signals=None, model_id=None, aspect_ratio=None, seed=None)

POST /api/lab/compile-image-prompt → canonical compiled prompt package.

The mud server remains authoritative for policy/selection/provenance. This helper only forwards validated request fields and returns the server response verbatim.

Raises:

• MudServerSessionExpiredError – Session invalid/expired.

• MudServerConnectionError – Server unreachable or timed out.

generate_condition_axis_payload(*, world_id, seed=None, species, gender)

POST canonical condition-axis generation endpoint and return AxisPayload.

The canonical mud-server route requires session_id in query params plus strict runtime inputs in the JSON body under inputs.entity.

Raises:

• MudServerSessionExpiredError – Session invalid/expired.

• MudServerConnectionError – Server unreachable or timed out.

• MudServerFeatureUnavailableError – Upstream server lacks canonical axis generation route.

• httpx.HTTPStatusError – Non-404 upstream HTTP errors.

create_world_prompt_draft(*, world_id, draft_name, content, based_on_name=None)

POST /api/lab/world-prompts/{world_id}/drafts → create one server draft.

world_prompt_drafts(world_id)

GET /api/lab/world-prompts/{world_id}/drafts → list server prompt drafts.

world_prompt_draft(world_id, draft_name)

GET /api/lab/world-prompts/{world_id}/drafts/{name} → load one server draft.

promote_world_prompt_draft(*, world_id, draft_name, target_name)

POST /api/lab/world-prompts/{world_id}/drafts/{name}/promote → promote one draft.

world_policy_bundle(world_id)

GET /api/lab/world-policy-bundle/{world_id} → return normalized policy bundle.

create_world_policy_bundle_draft(*, world_id, draft_name, content, based_on_name=None)

POST /api/lab/world-policy-bundle/{world_id}/drafts → create one server draft.

world_policy_bundle_drafts(world_id)

GET /api/lab/world-policy-bundle/{world_id}/drafts → list server draft bundles.

world_policy_bundle_draft(world_id, draft_name)

GET /api/lab/world-policy-bundle/{world_id}/drafts/{name} → load one server draft.

promote_world_policy_bundle_draft(*, world_id, draft_name)

POST /api/lab/world-policy-bundle/{world_id}/drafts/{name}/promote → promote one draft.

translate(*, world_id, axes, channel, ooc_message, character_name='Lab Subject', seed=-1, temperature=0.7, prompt_template_override=None)

POST /api/lab/translate → return LabTranslateResponse dict.

Raises:

• MudServerSessionExpiredError – Session invalid/expired.

• MudServerConnectionError – Server unreachable or timed out.

app.mud_server_client.list_mud_mode_options()

Return all runtime-selectable mud translation modes.

The response is serialisable so the route layer can expose it directly to the frontend for mode-selector construction.

app.mud_server_client.get_mud_mode_config()

Return the current runtime mud-mode configuration.

app.mud_server_client.set_mud_mode(mode_key, server_url=None)

Activate a runtime mud mode by selector key.

Parameters:

• mode_key (str) – One of the keys returned by list_mud_mode_options().

• server_url (str | None) – Optional mud-server URL override for development mode.

Raises:

ValueError – The requested mode key is not available in this process.

app.mud_server_client.get_mud_client()

Return the active mud client for the current runtime mode, if any.

app.mud_server_client.close_all_mud_clients()

Close every cached mud client and clear the runtime client cache.

app.mud_server_client.compute_translation_mode()

Return the current public translation-mode string for the active mode.