120 lines
7 KiB
Markdown
120 lines
7 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.
|
|
- 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:
|
|
|
|
```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.
|
|
|
|
6. To run an agent that orchestrates several tools, use:
|
|
|
|
```text
|
|
#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:
|
|
|
|
```text
|
|
#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:
|
|
|
|
```text
|
|
#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!
|