# 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`) 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:

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

## 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!