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.
• Higher-level agents (fixed, loop, intelligent) that can string multiple tools together via #agent <spec>.
• Built-in tools (LookTool, ExploreTool, CommunicationTool, MovementTool, IntelligentCommunicationTool) with a pluggable interface for custom behaviours.
• Background "sideload" channel so helper tools (e.g. intelligent replies) can keep watching chat while other work continues.

Requirements

• Python 3.10+
• A reachable Telnet-based MUD server

Quick Start

1. Create a virtual environment and install dependencies:

   pip install -e .
   

2. Copy .env.example (if available) or create a .env file in the project root, then fill in the connection details described below.

3. Run the client:

   python app.py
   

4. Type commands directly into the console. Press Ctrl-C to exit; the client will send any configured shutdown command to the MUD.

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

6. To run an agent that orchestrates several tools, use:

   #agent fixed move,explore
   

   This example uses the fixed strategy agent to run move and then explore once. The first token after #agent selects the agent type (fixed today, more to come), and any remaining text is passed as that agent's configuration.

7. To run a looping agent that repeats tools, use:

   #agent loop move,explore
   

   Append :delay to pause between iterations, e.g. #agent loop move,explore:2.5.

8. To let the LLM decide the next action, use the intelligent agent:

   #agent intelligent
   

   Add guidance text after the type and optional modifiers separated by |, e.g. #agent intelligent explore carefully|model=mistral/mistral-large-2407|delay=2. The agent only calls built-in tools (look, move, movement, explore, communication, intelligentcommunication) and refuses unknown names.

9. Prefer a TUI? Run python textual_ui.py to open a two-pane interface (MUD output on the left, agent output on the right) with an input box at the bottom. It accepts the same commands as the CLI (#execute …, #agent …, or raw MUD commands).

Environment Variables

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: look (default, alias simple), explore, communication, movement, intelligent/intelligentcommunication (LLM-backed), or custom spec module:ClassName.
MISTLE_SIDELOAD_TOOL	❌	Comma-separated list of tool specs that should always run in the background (same syntax as MISTLE_TOOL). Useful for running intelligent alongside another primary tool.
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.

Tool Development

• 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.
• To keep specific helpers always-on (for example, the intelligent communication tool), set MISTLE_SIDELOAD_TOOL=intelligent. Multiple specs can be separated with commas; each runs in its own listener thread in parallel with the primary tool or interactive session.

On-Demand Tools

• 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 look, #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.

Danger Zone

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

Contributing

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

---

Happy MUDding!