Metadata-Version: 2.4
Name: nhemo
Version: 0.1.1
Summary: NetHack Expert Machine Operator — automated NetHack player
Author-email: "Javier Novoa C." <jstitch@gmail.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/jstitch/nhemo-nethack-expert-machine-operator
Project-URL: Repository, https://gitlab.com/jstitch/nhemo-nethack-expert-machine-operator
Project-URL: Bug Tracker, https://gitlab.com/jstitch/nhemo-nethack-expert-machine-operator/-/issues
Keywords: nethack,roguelike,bot,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pexpect>=4.9
Requires-Dist: pyte>=0.8
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: ty>=0.0.29; extra == "dev"
Dynamic: license-file

# NHEMO — NetHack Expert Machine Operator

An automated [NetHack](https://www.nethack.org/) 3.6.x player that reads the
terminal screen, parses the game state, and makes decisions — just like a human
player would, but faster and without getting distracted.

**MVP goal**: a bot that consistently reaches [Minetown](https://nethackwiki.com/wiki/Minetown)
as a dwarven Valkyrie.

---

## What NHEMO can do right now

NHEMO v0.1.0 covers dungeon exploration through level 4 of the workflow:

| Capability | Status |
|------------|--------|
| Connect to a live NetHack session via PTY | done |
| Read and parse the terminal screen | done |
| Navigate without walking into walls | done |
| Open and kick locked doors | done |
| Explore rooms systematically (A\* pathfinding) | done |
| Descend stairs across multiple dungeon levels | done |
| Detect hunger and eat food from inventory | done |
| Monitor HP and wait in place to heal | done |

**What it cannot do yet:** fight monsters (it will flee or die), pick up
items, remember previously visited levels, use knowledge about monsters or
items, or consult an LLM. See [CHANGELOG.md](CHANGELOG.md) for a full
capability breakdown by version.

---

## Requirements

- Python 3.12+
- NetHack 3.6.x — the real ELF binary, **not** a shell wrapper.
  Typical paths: `/usr/lib/nethack/nethack` (Arch), `/usr/games/nethack` (Debian/Ubuntu)

> **Important**: NHEMO must point at the actual setgid binary. Shell wrappers
> like `/usr/bin/nethack` override `NETHACKOPTIONS` and break the custom
> configuration.

---

## Installation

```bash
pip install nhemo
# or, with uv:
uv add nhemo
```

---

## Configuration

Create a `config.yaml` in your working directory before running:

```yaml
nethack:
  binary_path: "/usr/lib/nethack/nethack"   # adjust for your distro
  playground_dir: "/var/games/nethack"

player:
  role: "Valkyrie"
  race: "Dwarf"
  alignment: "Neutral"
  gender: "Female"

llm:
  mode: "offline"
```

A fully annotated example with every available option is at
[`config.yaml.example`](https://gitlab.com/jstitch/nhemo-nethack-expert-machine-operator/-/blob/main/config.yaml.example).

---

## Quick Start

```bash
# 30-turn smoke test
python -m nhemo

# Watch the bot play live
python -m nhemo --turns 500 --watch

# Slower watch mode, easier to follow
python -m nhemo --turns 500 --watch --delay 0.5
```

### Watch mode display

Running with `--watch` renders the NetHack screen live, followed by NHEMO's
status line and a persistent message log:

```
This door is locked.                                    <- row 0: game message
                                                        <- rows 1-21: dungeon map
             --------
             |....#.|
             |......|
             |......|
             |......|
             ----.---          +
                ##             @
                #             ##
             ...
    -------.--------    #----.-
    |..............|    #|....|
    |......$........#####|"....###          ----------
    |..............|    #.....|#############..$$.....|
    |..............|`####------   #####     |........|
    ----------------                  ######|.<......|
                                            ----------
NHEMO the Stripling  St:16 Dx:14 Co:17 In:8 Wi:12 Ch:8 Lawful
Dlvl:1 $:0 HP:18(18) Pw:1(1) AC:6 Xp:1/0 T:118
 NHEMO turn 321  action: ---
-- message log --------------------------------------------------
  t 314: This door is locked.
  t 315: This door is locked.
  t 316: This door is locked.
> t 321: This door is locked.                          <- most recent (bold >)
```

---

## Observability

### Logging

```bash
# Verbose per-turn decisions
python -m nhemo --turns 200 --watch --log-level DEBUG

# Capture to file (logging goes to stderr, safe to combine with --watch)
python -m nhemo --turns 500 --log-level DEBUG 2>nhemo_debug.log
```

| Level | What you see |
|-------|-------------|
| `WARNING` (default) | Parse failures, bot stuck and giving up |
| `INFO` | Level transitions, doors opened, stairs descended, food eaten |
| `DEBUG` | Every turn: position, visited tile count, chosen action and phase |

### Decision event log

```bash
python -m nhemo --turns 200 --log-events /tmp/events.jsonl
```

Each turn emits one JSON line:

```json
{"turn":42,"screen_mode":"NORMAL","action":"MOVE_E","phase":"pathfind","pos":[12,40],"hp":15,"max_hp":19,"dlvl":"Dlvl:3"}
```

Flags combine freely:

```bash
python -m nhemo --turns 500 --watch --log-events /tmp/events.jsonl --log-level DEBUG 2>nhemo_debug.log
```

---

## How it works

NHEMO never reads NetHack's internals — it sees only what a human player sees
on a terminal. Under the hood it has four layers: a PTY screen reader, a
parser that turns raw screen output into structured game state, a behavior-tree
decision engine, and a future LLM consultation layer.

Curious about the architecture? See [CONTRIBUTING.md](CONTRIBUTING.md) for the
component overview, module breakdown, and design documents.

---

## Roadmap

| Phase | Target |
|-------|--------|
| V5–V7 | Combat, item management, SQLite persistence, knowledge base |
| V8–V9 | LLM integration, full data-driven behavior tree |
| V10 | MVP: consistent Minetown arrival as dwarven Valkyrie |
| V11+ | Mines End, Sokoban, shop interaction, quest completion, ascension |

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## License

Copyright (C) 2025 Javier Novoa C.

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

See [`LICENSE`](LICENSE) for the full text.
