Mistle Mudbot

Python-based Telnet helper for connecting to MUD servers, handling login flows, and optionally running automated "tools" alongside interactive play.

Features

Lightweight wrapper (TelnetClient) around telnetlib with sane defaults and context-manager support.
Loads credentials and connection settings from a local .env file.
Interactive console session that mirrors server output and lets you type commands directly.
Optional always-on tool mode plus an on-demand #execute <tool> escape hatch for ad-hoc automations.
Built-in tools (SimpleTool, ExploreTool, CommunicationTool, MovementTool, IntelligentCommunicationTool) with a pluggable interface for custom behaviours.

Create a virtual environment and install dependencies:
```
pip install -e .
```
Copy .env.example (if available) or create a .env file in the project root, then fill in the connection details described below.
Run the client:
```
python app.py
```
Type commands directly into the console. Press Ctrl-C to exit; the client will send any configured shutdown command to the MUD.
When not running in tool mode you can kick off one-off automations from the prompt:
```
#execute explore
```
The command remains interactive while the tool works in the background and stops automatically a few seconds after things quiet down.

All variables can be placed in the .env file (one KEY=value per line) or provided through the shell environment.

Variable	Required	Description
`MISTLE_HOST`	✅	DNS name or IP of the target MUD server.
`MISTLE_PORT`	✅	Telnet port number (will be cast to `int`).
`MISTLE_USER`	❌	Username or character name; sent automatically after login banner, if provided.
`MISTLE_PASSWORD`	❌	Password sent after the username. Leave blank for manual entry.
`MISTLE_LOGIN_PROMPT`	❌	Prompt string that signals the client to send credentials (e.g., `"Name:"`). When omitted, the client just waits for the initial banner.
`MISTLE_EXIT_COMMAND`	❌	Command issued during graceful shutdown (after pressing `Ctrl-C`). Useful for `quit`/`save` macros.
`MISTLE_TOOL_MODE`	❌	Enable full-time tool thread when set to truthy values (`1`, `true`, `yes`, `on`). Defaults to interactive-only mode.
`MISTLE_TOOL`	❌	Select which tool class to instantiate when tool mode is active. Accepted values: `simple` (default), `explore`, `communication`, `movement`, `intelligent`/`intelligentcommunication` (LLM-backed), or custom spec `module:ClassName`.
`MISTLE_LLM_MODEL`	❌	Override the `litellm` model used by the intelligent tool (defaults to `mistral/mistral-small-2407`).
`MISTRAL_API_KEY`	❌	API key used by `IntelligentCommunicationTool` (via `litellm`) when calling the `mistral/mistral-small-2407` model.

Implement new tools by subclassing tools.Tool and overriding observe() and decide().
Register the tool by either:
- Adding the class to tools.py and referencing it in MISTLE_TOOL (e.g., explore for ExploreTool).
- Placing the class elsewhere and configuring MISTLE_TOOL to your_module:YourTool.
observe(output) receives the latest server text; decide() returns the next command string or None to stay idle.
Commands issued by the tool are throttled to one per second so manual commands can still interleave smoothly.
ExploreTool showcases a richer workflow: it sends schau, identifies German nouns, inspects each with untersuche, and prints [Tool] progress updates like Explored 3/7 — untersuche Tisch.
MovementTool parses room descriptions/exits and issues a single direction command, preferring unvisited exits and randomising choices to avoid oscillation. Trigger it via #execute move (or set MISTLE_TOOL=movement for continuous roaming).
CommunicationTool auto-replies to every direct tell with a canned greeting, while IntelligentCommunicationTool routes each tell through litellm (default model mistral/mistral-small-2407) to craft a contextual answer via the configured LLM.

When MISTLE_TOOL_MODE is off, you can trigger an ephemeral tool at any time with #execute <tool_spec>.
The syntax accepts the same values as MISTLE_TOOL and reuses the build_tool helper, so #execute simple, #execute explore, #execute move, #execute intelligent, or #execute mypackage.mymodule:CustomTool are all valid.
On-demand runs share the current session, respect the one-command-per-second limit, and stop automatically after a few seconds of inactivity.

The Telnet session runs until you interrupt it. Make sure the terminal is in a state where Ctrl-C is available.
When adding new tools, guard any long-running logic to avoid blocking the tool thread.

Feel free to open issues or submit pull requests for additional MUD-specific helpers, new tools, or quality-of-life improvements.

Happy MUDding!