90 lines
5.1 KiB
Markdown
90 lines
5.1 KiB
Markdown
# 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.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.10+
|
|
- A reachable Telnet-based MUD server
|
|
|
|
## Quick Start
|
|
|
|
1. Create a virtual environment and install dependencies:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
#execute explore
|
|
```
|
|
|
|
The command remains interactive while the tool works in the background and stops automatically a few seconds after things quiet down.
|
|
|
|
## 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!
|