Metadata-Version: 2.4
Name: MnesOS
Version: 0.6.0
Summary: MnesOS is fully Agentic RPG Game Engine.
Author-email: neolaw84 <neolaw@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/neolaw84/MnesOS
Project-URL: Documentation, https://neolaw84.github.io/MnesOS/
Project-URL: Issues, https://github.com/neolaw84/MnesOS/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: langgraph<1.3,>=1.1.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: api
Requires-Dist: fastapi<1.0,>=0.115; extra == "api"
Requires-Dist: uvicorn[standard]<1.0,>=0.34; extra == "api"
Requires-Dist: python-multipart>=0.0.22; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mkdocs>=1.5; extra == "dev"
Requires-Dist: mkdocs-material>=9.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "dev"
Requires-Dist: pymdown-extensions>=10.0; extra == "dev"
Requires-Dist: ipywidgets>=8.0; extra == "dev"
Requires-Dist: fastapi<1.0,>=0.115; extra == "dev"
Requires-Dist: uvicorn[standard]<1.0,>=0.34; extra == "dev"
Requires-Dist: python-multipart>=0.0.22; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"

# MnesOS

MnesOS is an agentic RPG engine that separates deterministic game mechanics from LLM-driven narration.

[![PyPI version](https://badge.fury.io/py/MnesOS.svg)](https://badge.fury.io/py/MnesOS)
[![Documentation](https://img.shields.io/badge/docs-gh--pages-blue)](https://neolaw84.github.io/MnesOS/)

## What It Does

MnesOS combines four concerns into a single turn pipeline:

- `VectorLoreStore` retrieves relevant lore from `bot_lore.md`
- the Director LLM maps player intent to YARE events
- `YAREInterpreter` applies deterministic state changes
- the Director can query NPC intents via the `query_npc_intent` tool
- the Narrator LLM reacts to the resolved turn
The engine state is explicit. The caller passes a `GameState` into `app.invoke(...)` and receives the updated state back.

## Turn Model

The graph itself is stateless between invocations. The client is responsible for persisting and re-supplying the returned game state for the next turn.

- `client_messages`: persistent story history owned by the caller
- agent message lists: per-node, per-turn working prompts rebuilt on each invocation
- `bot_memory`: persistent deterministic world state

## Cartridge Layout

Each cartridge lives under `cartridges/<name>/` and contains:

- `yare.yaml`: procedural rules and state schema
- `bot_lore.md`: markdown lore used for retrieval
- `prompt_directives.yaml`: optional LLM directives for `director`, `npc`, and `narrator`

`prompt_directives` must not be embedded in `yare.yaml`; the loader rejects that configuration.

## Installation

```bash
pip install MnesOS
```

## Development

```bash
python -m venv venv
source venv/bin/activate
pip install -e ".[dev,docs]"
```

### Run Tests

```bash
python -m pytest
```

### Build Docs

```bash
mkdocs build
```

## Further Reading

- `docs/architecture.md`: current graph architecture and turn flow
- `docs/cartridge-guide.md`: cartridge authoring guidance
- `docs/yare-specification.md`: supported YARE syntax and execution rules

## License

MIT.
