mud_server.api.models

Pydantic models for API requests and responses.

This module defines all the data models used for API communication between the FastAPI backend and the Gradio frontend. Pydantic models provide: - Automatic request/response validation - Type checking and conversion - Clear API documentation via FastAPI’s automatic OpenAPI schema generation - Serialization/deserialization to/from JSON

Models are organized into two categories: 1. Request models: Data sent FROM the client TO the server 2. Response models: Data sent FROM the server TO the client

Classes

`LoginRequest`	Login request with username and password.
`RegisterRequest`	Registration request for creating a new player account.
`RegisterGuestRequest`	Registration request for creating a temporary guest account.
`SelectCharacterRequest`	Request to select an active character for a session.
`LoginDirectRequest`	Direct login request that binds a session to a world + character.
`ChangePasswordRequest`	Request to change the current user's password.
`UserManagementRequest`	Admin request to manage user accounts.
`CreateUserRequest`	Admin request to create a new user account.
`ServerStopRequest`	Admin request to stop the server gracefully.
`LogoutRequest`	Request to logout and end the current session.
`CommandRequest`	Request to execute a game command.
`ChatRequest`	Request to send a chat message.
`LoginResponse`	Response to login request.
`LoginDirectResponse`	Response to direct login request.
`SelectCharacterResponse`	Response to character selection request.
`CharactersResponse`	Response containing the user's characters.
`RegisterResponse`	Response to registration request.
`RegisterGuestResponse`	Response to guest registration request.
`CreateUserResponse`	Response to admin user creation request.
`CommandResponse`	Response to game command execution.
`StatusResponse`	Response containing player's current game status.
`UserListResponse`	Response containing list of user accounts.
`DatabasePlayersResponse`	Admin response containing all user records from database.
`DatabaseTableInfo`	Metadata about a single database table.
`DatabaseTablesResponse`	Admin response containing database table metadata.
`DatabaseTableRowsResponse`	Admin response containing rows for a specific database table.
`DatabasePlayerLocationsResponse`	Admin response containing character locations with names.
`DatabaseConnectionsResponse`	Admin response containing active session connections.
`KickSessionRequest`	Request to force-disconnect a session.
`KickSessionResponse`	Response for a kick session request.
`DatabaseSessionsResponse`	Admin response containing all active sessions from database.
`DatabaseChatResponse`	Admin response containing recent chat messages across all rooms.
`UserManagementResponse`	Response to user management action (role change, ban, unban).
`ServerStopResponse`	Response to server stop request.
`OllamaCommandRequest`	Request to execute an Ollama command.
`OllamaCommandResponse`	Response to Ollama command execution.
`ClearOllamaContextRequest`	Request to clear Ollama conversation context for the current session.
`ClearOllamaContextResponse`	Response to clear Ollama context request.

Module Contents

class mud_server.api.models.LoginRequest(/, **data)[source]

Bases: pydantic.BaseModel

Login request with username and password.

username: Account username (case-sensitive for database lookup)

password: Plain text password (will be verified against bcrypt hash)

world_id: Optional world id used to filter characters on login

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

username: str

password: str

world_id: str | None = None

class mud_server.api.models.RegisterRequest(/, **data)[source]

Bases: pydantic.BaseModel

Registration request for creating a new player account.

username: Desired username (2-20 characters, must be unique)

password: Desired password (minimum 8 characters)

password_confirm: Password confirmation (must match password)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

username: str

password: str

password_confirm: str

class mud_server.api.models.RegisterGuestRequest(/, **data)[source]

Bases: pydantic.BaseModel

Registration request for creating a temporary guest account.

password: Desired password (validated against STANDARD policy)

password_confirm: Password confirmation (must match password)

character_name: Initial character name for the guest account

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

password: str

password_confirm: str

character_name: str

class mud_server.api.models.SelectCharacterRequest(/, **data)[source]

Bases: pydantic.BaseModel

Request to select an active character for a session.

session_id: Active session ID for authentication

character_id: Character id to bind to the session

world_id: World id to bind to the session (must match character’s world)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

character_id: int

world_id: str | None = None

class mud_server.api.models.LoginDirectRequest(/, **data)[source]

Bases: pydantic.BaseModel

Direct login request that binds a session to a world + character.

username: Account username (case-sensitive for database lookup)

password: Plain text password (will be verified against bcrypt hash)

world_id: Target world id (must be accessible by the user)

character_name: Existing character name (optional)

create_character: When true, create the character if missing

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

username: str

password: str

world_id: str

character_name: str | None = None

create_character: bool = False

class mud_server.api.models.ChangePasswordRequest(/, **data)[source]

Bases: pydantic.BaseModel

Request to change the current user’s password.

session_id: Active session ID for authentication

old_password: Current password (verified before change)

new_password: New password (minimum 8 characters, must differ from old)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

old_password: str

new_password: str

class mud_server.api.models.UserManagementRequest(/, **data)[source]

Bases: pydantic.BaseModel

Admin request to manage user accounts.

Requires admin or superuser permissions. Allows role changes, banning, unbanning, and password changes of user accounts. Superusers can manage all users, admins can only manage users with lower permissions.

session_id: Active session ID (must have appropriate permission)

target_username: Username of the account to manage

action: Management action - one of: - “change_role”: Change user’s role (requires new_role parameter) - “ban” or “deactivate”: Deactivate user account (prevents login, removes active session) - “delete”: Permanently delete user and related data (superuser only) - “unban”: Reactivate previously banned account - “change_password”: Change user’s password (requires new_password parameter)

new_role: (Optional) New role when action is “change_role” Valid roles: “player”, “worldbuilder”, “admin”, “superuser”

new_password: (Optional) New password when action is “change_password” Must be at least 8 characters

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

target_username: str

action: str

new_role: str | None = None

new_password: str | None = None

class mud_server.api.models.CreateUserRequest(/, **data)[source]

Bases: pydantic.BaseModel

Admin request to create a new user account.

Requires admin or superuser permissions. Admins may create Player or WorldBuilder accounts. Superusers may create any role, including Admin and Superuser.

Passwords must meet the STANDARD password policy, and password_confirm must match password.

session_id: Active session ID (must have appropriate permission)

username: Desired username (2-20 characters, must be unique)

password: Desired password (must meet STANDARD policy)

password_confirm: Password confirmation (must match password)

role: Role to assign to the new account Valid roles: “player”, “worldbuilder”, “admin”, “superuser”

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

username: str

password: str

password_confirm: str

role: str

class mud_server.api.models.ServerStopRequest(/, **data)[source]

Bases: pydantic.BaseModel

Admin request to stop the server gracefully.

Requires STOP_SERVER permission (admin or superuser only). Server will shutdown 0.5 seconds after sending response to allow the HTTP response to be delivered.

session_id: Active session ID (must have STOP_SERVER permission)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

class mud_server.api.models.LogoutRequest(/, **data)[source]

Bases: pydantic.BaseModel

Request to logout and end the current session.

session_id: Active session ID to be terminated

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

class mud_server.api.models.CommandRequest(/, **data)[source]

Bases: pydantic.BaseModel

Request to execute a game command.

Supports all game commands including movement, inventory management, chat, and special commands. Commands can be prefixed with “/” or not.

session_id: Active session ID for authentication

command: Game command to execute, examples: - Movement: “north”, “n”, “south”, “s”, “east”, “e”, “west”, “w”, “up”, “u”, “down”, “d” - Actions: “look”, “inventory”, “get <item>”, “drop <item>” - Chat: “say <message>”, “yell <message>”, “whisper <player> <message>” - Info: “who”, “help”

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

command: str

class mud_server.api.models.ChatRequest(/, **data)[source]

Bases: pydantic.BaseModel

Request to send a chat message.

Note: This model is defined but may not be actively used. Chat is typically sent via CommandRequest with “/say” command.

session_id: Active session ID for authentication

message: Chat message text

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

message: str

class mud_server.api.models.LoginResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to login request.

success: True if login succeeded, False otherwise

message: Welcome message on success, error message on failure

session_id: (Optional) UUID session identifier on successful login

role: (Optional) User’s role on successful login (“player”, “worldbuilder”, “admin”, or “superuser”)

characters: List of available characters for selection

available_worlds: List of available worlds for selection

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

session_id: str | None = None

role: str | None = None

characters: list[dict[str, Any]] = []

available_worlds: list[dict[str, Any]] = []

class mud_server.api.models.LoginDirectResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to direct login request.

success: True if login succeeded, False otherwise

message: Welcome message on success, error message on failure

session_id: Session identifier on successful login

role: User’s role on successful login

character_name: Selected character name on success

world_id: World bound to the session

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

session_id: str | None = None

role: str | None = None

character_name: str | None = None

world_id: str | None = None

class mud_server.api.models.SelectCharacterResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to character selection request.

success: True if character selected

message: Success or error message

character_name: Selected character name on success

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

character_name: str | None = None

class mud_server.api.models.CharactersResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response containing the user’s characters.

characters: List of character summaries

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

characters: list[dict[str, Any]]

class mud_server.api.models.RegisterResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to registration request.

success: True if account created, False otherwise

message: Success confirmation or error details

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

class mud_server.api.models.RegisterGuestResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to guest registration request.

success: True if account created, False otherwise

message: Success confirmation or error details

username: Generated guest username for login

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

username: str | None = None

class mud_server.api.models.CreateUserResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to admin user creation request.

success: True if account created, False otherwise

message: Success confirmation or error details

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

class mud_server.api.models.CommandResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to game command execution.

success: True if command executed successfully, False for errors

message: Command result, room description, error message, etc. For movement: includes new room description For inventory: lists items in inventory For chat: confirmation message For errors: explanation of what went wrong

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

class mud_server.api.models.StatusResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response containing player’s current game status.

Used for periodic status updates to keep the UI synchronized.

Attributes:
active_players: List of usernames currently online current_room: Player’s current room ID (e.g., “spawn”, “forest_1”) inventory: Formatted inventory string (e.g., “Your inventory:

Torch
Rope”)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

active_players: list[str]

current_room: str | None

inventory: str

class mud_server.api.models.UserListResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response containing list of user accounts.

Used for admin user management interfaces.

users: List of user data dictionaries with account information

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

users: list[dict[str, Any]]

class mud_server.api.models.DatabasePlayersResponse(/, **data)[source]

Bases: pydantic.BaseModel

Admin response containing all user records from database.

Requires VIEW_LOGS permission. Includes account details and character counts.

players: List of user data dictionaries with fields: - id: Database record ID - username: Account username - password_hash: Truncated password hash (first 20 chars + “…”) - role: User role - account_origin: Account provenance (“visitor”, “admin”, “superuser”, “system”, “legacy”) - is_guest: Guest flag - guest_expires_at: Guest expiry timestamp - character_count: Number of linked characters - created_at: Account creation timestamp - last_login: Last login timestamp - is_active: Account status (True=active, False=banned)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

players: list[dict[str, Any]]

class mud_server.api.models.DatabaseTableInfo(/, **data)[source]

Bases: pydantic.BaseModel

Metadata about a single database table.

name: Table name.

columns: List of column names in order.

row_count: Number of rows in the table.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

name: str

columns: list[str]

row_count: int

class mud_server.api.models.DatabaseTablesResponse(/, **data)[source]

Bases: pydantic.BaseModel

Admin response containing database table metadata.

Requires VIEW_LOGS permission. Used for table discovery in the admin UI.

tables: List of DatabaseTableInfo entries.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

tables: list[DatabaseTableInfo]

class mud_server.api.models.DatabaseTableRowsResponse(/, **data)[source]

Bases: pydantic.BaseModel

Admin response containing rows for a specific database table.

Requires VIEW_LOGS permission. Includes column names and raw row values.

table: Table name.

columns: Column names in order.

rows: Row values as a list of rows (each row is a list of values).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

table: str

columns: list[str]

rows: list[list[Any]]

class mud_server.api.models.DatabasePlayerLocationsResponse(/, **data)[source]

Bases: pydantic.BaseModel

Admin response containing character locations with names.

Requires VIEW_LOGS permission. Useful for cross-referencing room occupancy.

locations: List of dicts with fields: - character_id - character_name - zone_id - room_id - updated_at

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

locations: list[dict[str, Any]]

class mud_server.api.models.DatabaseConnectionsResponse(/, **data)[source]

Bases: pydantic.BaseModel

Admin response containing active session connections.

Requires VIEW_LOGS permission. Includes activity age for dashboards.

connections: List of session dictionaries with fields: - id - username - session_id - created_at - last_activity - expires_at - client_type - age_seconds

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

connections: list[dict[str, Any]]

class mud_server.api.models.KickSessionRequest(/, **data)[source]

Bases: pydantic.BaseModel

Request to force-disconnect a session.

Requires KICK_USERS permission.

session_id: Admin’s active session id.

target_session_id: Session id to disconnect.

reason: Optional reason for audit/logging.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

target_session_id: str

reason: str | None = None

class mud_server.api.models.KickSessionResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response for a kick session request.

success: True if session was removed.

message: Human-readable result.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

class mud_server.api.models.DatabaseSessionsResponse(/, **data)[source]

Bases: pydantic.BaseModel

Admin response containing all active sessions from database.

Requires VIEW_LOGS permission. Shows who is currently logged in.

sessions: List of session data dictionaries with fields: - id: Database record ID - username: Logged in account - character_name: Active character for the session (if selected) - session_id: UUID session identifier - created_at: Login timestamp - last_activity: Most recent API request timestamp - expires_at: Session expiry timestamp (NULL means no expiry) - client_type: Client identifier (tui, browser, api)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

sessions: list[dict[str, Any]]

class mud_server.api.models.DatabaseChatResponse(/, **data)[source]

Bases: pydantic.BaseModel

Admin response containing recent chat messages across all rooms.

Requires VIEW_LOGS permission. Useful for moderation and monitoring.

messages: List of chat message dictionaries with fields: - id: Database record ID - username: Message sender - message: Message text (includes [WHISPER], [YELL] prefixes) - room: Room ID where message was sent - timestamp: Message timestamp

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

messages: list[dict[str, Any]]

class mud_server.api.models.UserManagementResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to user management action (role change, ban, unban).

success: True if action completed successfully

message: Confirmation message or error details

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

class mud_server.api.models.ServerStopResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to server stop request.

Server will shutdown shortly after sending this response.

success: True if shutdown initiated

message: Confirmation message indicating who initiated shutdown

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str

class mud_server.api.models.OllamaCommandRequest(/, **data)[source]

Bases: pydantic.BaseModel

Request to execute an Ollama command.

Requires VIEW_LOGS permission (admin or superuser only).

session_id: Active session ID (must have appropriate permission)

server_url: URL of the Ollama server (e.g., “http://localhost:11434”)

command: Ollama command to execute (e.g., “list”, “ps”, “run llama2”)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

server_url: str

command: str

class mud_server.api.models.OllamaCommandResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to Ollama command execution.

success: True if command executed successfully

output: Command output or error message

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

output: str

class mud_server.api.models.ClearOllamaContextRequest(/, **data)[source]

Bases: pydantic.BaseModel

Request to clear Ollama conversation context for the current session.

Requires VIEW_LOGS permission (admin or superuser only).

session_id: Active session ID (must have appropriate permission)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

session_id: str

class mud_server.api.models.ClearOllamaContextResponse(/, **data)[source]

Bases: pydantic.BaseModel

Response to clear Ollama context request.

success: True if context was cleared successfully

message: Confirmation message

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

success: bool

message: str