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 (FixedStrategyAgent so far) that can string multiple tools together via #agent <spec>.
• Built-in tools (SimpleTool, ExploreTool, CommunicationTool, MovementTool, IntelligentCommunicationTool) with a pluggable interface for custom behaviours.

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.

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

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.

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

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!