realm-fabric 0.7.0__tar.gz

realm_fabric-0.7.0/.gitignore

@@ -0,0 +1,158 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff
+instance/
+.webassets-cache
+
+# Scrapy stuff
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.local
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project specific
+logs/
+*.log
+examples/web/realm-studio/frontend/tokens/pip.png
+examples/web/realm-studio/.custom_modules/

realm_fabric-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DaveH-Ghost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

realm_fabric-0.7.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: realm-fabric
+Version: 0.7.0
+Summary: Grid-based LLM agent simulation engine — Session API, multi-area worlds, tactical movement, compound turns, pluggable memory
+Project-URL: Homepage, https://github.com/DaveH-Ghost/Realm-Fabric
+Project-URL: Documentation, https://github.com/DaveH-Ghost/Realm-Fabric/blob/main/docs/README.md
+Project-URL: Repository, https://github.com/DaveH-Ghost/Realm-Fabric
+Project-URL: Issues, https://github.com/DaveH-Ghost/Realm-Fabric/issues
+Project-URL: Changelog, https://github.com/DaveH-Ghost/Realm-Fabric/blob/main/docs/changelog/README.md
+Author-email: DaveH-Ghost <davidhall.a27@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,game-engine,grid,llm,roleplay,simulation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: openai
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+Requires-Dist: rich
+Description-Content-Type: text/markdown
+
+# Realm Fabric
+
+Grid-based LLM agent simulation engine: multi-area worlds, compound turns (move → look → speak → interact/emote), pluggable memory modules, and a stable `realm_fabric` library API. The `realm` CLI and [realm-studio](examples/web/realm-studio) are reference clients — apps build on the engine with their own UI and scenarios.
+
+**License:** [MIT](LICENSE) — open source.
+
+**Current version:** **V0.7.0** (`0.7.0` in `pyproject.toml`) — stable `realm_fabric` exports, typed `Session` world API, [documentation](docs/README.md), and [minimal-server](examples/minimal-server/). **0.7.1** on this repo is for engine follow-ups from the external demo; the demo itself will version from **0.1.0** in its own repository.
+
+## Quick start
+
+```powershell
+# Engine + CLI
+cd path\to\Realm-Fabric
+uv sync
+uv run realm
+
+# Example web UI
+cd examples\web\realm-studio
+uv sync
+copy ..\..\..\.env.example .env   # optional; or use Settings gear in the UI
+uv run realm-studio
+```
+
+On Windows, if Smart App Control blocks `uv run realm-studio`, use:
+
+```powershell
+uv run python -m backend.main
+```
+
+Open [http://127.0.0.1:8765](http://127.0.0.1:8765). See [realm-studio README](examples/web/realm-studio/README.md).
+
+## Library API
+
+```python
+from realm_fabric import Session, load_profile, AgentCompoundTurn
+
+session = Session.from_profile(load_profile("default_compound"))
+session.create_agent(name="Scout", position=(0, 0), personality="...")
+session.create_object(name="Chest", position=(2, 1), passive_description="...")
+prompt = session.build_prompt()
+result = session.run_compound_turn(AgentCompoundTurn(...))
+save_doc = session.to_save_dict()
+restored = Session.from_snapshot(save_doc)
+```
+
+See [documentation](docs/README.md) and [minimal-server](examples/minimal-server/).
+
+## Environment
+
+Copy [`.env.example`](.env.example) to `.env` and set `OPENROUTER_API_KEY` for LLM turns. Optional `OPENROUTER_MODEL` (default `deepseek/deepseek-v4-flash`). Manual commands work without a key.
+
+realm-studio **Settings** (gear icon) can set API key and model **in memory for the current server process only** — nothing is written to disk.
+
+## V0.7.0 highlights
+
+- **Public API** — expanded `realm_fabric` exports (lorebooks, prompt blocks, `ObjectAction`, `WorldMutationResult`, memory registration)
+- **Typed world API** — `session.create_object()`, `create_agent()`, `edit_object()`, areas, actions — no CLI strings in app code
+- **minimal-server** — thin FastAPI reference at `examples/minimal-server/`
+- **Docs** — [docs/README.md](docs/README.md)
+- **V0.7.1** — engine follow-ups from external demo (demo app **0.1.0**+ in its own repo)
+
+## V0.6.1 highlights
+
+- **Pluggable handlers** — `register_interaction_handler()`; `ObjectAction.handler_id` + `handler_params`
+- **Reference handlers** — `delete_self`, `random_move_self`, `move_area` in `examples/reference_handlers/` (CLI + realm-studio register at startup)
+- **Interacts + triggers** — same handler surface for LLM interacts and path-step triggers
+- **Saves** — `snapshot_version: 4` (v1–v3 import supported; `effects` migrates to handlers)
+- **Breaking** — CLI `effect` → `handler`; `effects` command → `handlers` (alias kept)
+
+## V0.6.0 highlights
+
+- **Movement blocking** — objects block tiles by default; BFS pathfinding when `move_speed` is set
+- **Interact pathing** — compound `interact` paths toward the object (replaces explicit `move` that turn)
+- **Passive vision** — look guidance and in-range interactions merged into one prompt slot
+- **Multi-tile objects** — `width` / `height` footprints; range uses nearest footprint tile
+- **Hidden objects + triggers** — GM-only placements; engine-fired triggers on path steps (`Session.emit_area_event`)
+- **Saves** — `snapshot_version: 3` (v1–v2 import still supported)
+- **realm-studio** — footprint overlay, hidden-trigger wizard, collapsible create/edit modals, `private_data` for custom apps
+
+## Custom memory modules (V0.4.6)
+
+Load `.py` modules at runtime before create-agent or session import:
+
+```text
+add-memory-module path\to\my_module.py
+```
+
+Saves store `module_id` + state only (no bundled source). Import **fails** if a save references a module that is not loaded. Example: [examples/custom_memory/](examples/custom_memory/).
+
+## Lorebooks (V0.5.0)
+
+Load SillyTavern-style `.json` lorebooks into the session (CLI `load-lorebook` or realm-studio **Lorebooks** tab). Add a `lorebook` prompt block (per book) in Prompt layout to inject matched world info. Not included in the default prompt layout.
+
+## CLI reference
+
+Full command list, world editing, blocking, hidden objects, triggers, and compound-turn examples: [docs/guides/cli.md](docs/guides/cli.md).
+
+## Tests
+
+```powershell
+# Engine (repo root)
+uv run pytest
+
+# realm-studio
+cd examples\web\realm-studio
+uv run pytest
+```
+
+No API key or network required — LLM calls are mocked in tests.
+
+## Documentation
+
+Start at **[docs/README.md](docs/README.md)** — guides, API overview, and changelog index.
+
+| Doc | Topic |
+|-----|--------|
+| [Building on Realm-Fabric](docs/guides/building-on-realm-fabric.md) | App integration (typed API, hosting) |
+| [CLI reference](docs/guides/cli.md) | `realm` stepper commands |
+| [V0.7.0 changelog](docs/changelog/v0.7.0-changelog.md) | Platform SDK, minimal-server |
+| [Roadmap](docs/ROADMAP.md) | Version plans |
+| [realm-studio](examples/web/realm-studio/README.md) | Full GM reference UI |
+| [Long-term goals](LONG_TERM_GOALS.md) | Aspirational features |
+
+Older version notes: [changelog index](docs/changelog/README.md).

realm_fabric-0.7.0/README.md

@@ -0,0 +1,124 @@
+# Realm Fabric
+
+Grid-based LLM agent simulation engine: multi-area worlds, compound turns (move → look → speak → interact/emote), pluggable memory modules, and a stable `realm_fabric` library API. The `realm` CLI and [realm-studio](examples/web/realm-studio) are reference clients — apps build on the engine with their own UI and scenarios.
+
+**License:** [MIT](LICENSE) — open source.
+
+**Current version:** **V0.7.0** (`0.7.0` in `pyproject.toml`) — stable `realm_fabric` exports, typed `Session` world API, [documentation](docs/README.md), and [minimal-server](examples/minimal-server/). **0.7.1** on this repo is for engine follow-ups from the external demo; the demo itself will version from **0.1.0** in its own repository.
+
+## Quick start
+
+```powershell
+# Engine + CLI
+cd path\to\Realm-Fabric
+uv sync
+uv run realm
+
+# Example web UI
+cd examples\web\realm-studio
+uv sync
+copy ..\..\..\.env.example .env   # optional; or use Settings gear in the UI
+uv run realm-studio
+```
+
+On Windows, if Smart App Control blocks `uv run realm-studio`, use:
+
+```powershell
+uv run python -m backend.main
+```
+
+Open [http://127.0.0.1:8765](http://127.0.0.1:8765). See [realm-studio README](examples/web/realm-studio/README.md).
+
+## Library API
+
+```python
+from realm_fabric import Session, load_profile, AgentCompoundTurn
+
+session = Session.from_profile(load_profile("default_compound"))
+session.create_agent(name="Scout", position=(0, 0), personality="...")
+session.create_object(name="Chest", position=(2, 1), passive_description="...")
+prompt = session.build_prompt()
+result = session.run_compound_turn(AgentCompoundTurn(...))
+save_doc = session.to_save_dict()
+restored = Session.from_snapshot(save_doc)
+```
+
+See [documentation](docs/README.md) and [minimal-server](examples/minimal-server/).
+
+## Environment
+
+Copy [`.env.example`](.env.example) to `.env` and set `OPENROUTER_API_KEY` for LLM turns. Optional `OPENROUTER_MODEL` (default `deepseek/deepseek-v4-flash`). Manual commands work without a key.
+
+realm-studio **Settings** (gear icon) can set API key and model **in memory for the current server process only** — nothing is written to disk.
+
+## V0.7.0 highlights
+
+- **Public API** — expanded `realm_fabric` exports (lorebooks, prompt blocks, `ObjectAction`, `WorldMutationResult`, memory registration)
+- **Typed world API** — `session.create_object()`, `create_agent()`, `edit_object()`, areas, actions — no CLI strings in app code
+- **minimal-server** — thin FastAPI reference at `examples/minimal-server/`
+- **Docs** — [docs/README.md](docs/README.md)
+- **V0.7.1** — engine follow-ups from external demo (demo app **0.1.0**+ in its own repo)
+
+## V0.6.1 highlights
+
+- **Pluggable handlers** — `register_interaction_handler()`; `ObjectAction.handler_id` + `handler_params`
+- **Reference handlers** — `delete_self`, `random_move_self`, `move_area` in `examples/reference_handlers/` (CLI + realm-studio register at startup)
+- **Interacts + triggers** — same handler surface for LLM interacts and path-step triggers
+- **Saves** — `snapshot_version: 4` (v1–v3 import supported; `effects` migrates to handlers)
+- **Breaking** — CLI `effect` → `handler`; `effects` command → `handlers` (alias kept)
+
+## V0.6.0 highlights
+
+- **Movement blocking** — objects block tiles by default; BFS pathfinding when `move_speed` is set
+- **Interact pathing** — compound `interact` paths toward the object (replaces explicit `move` that turn)
+- **Passive vision** — look guidance and in-range interactions merged into one prompt slot
+- **Multi-tile objects** — `width` / `height` footprints; range uses nearest footprint tile
+- **Hidden objects + triggers** — GM-only placements; engine-fired triggers on path steps (`Session.emit_area_event`)
+- **Saves** — `snapshot_version: 3` (v1–v2 import still supported)
+- **realm-studio** — footprint overlay, hidden-trigger wizard, collapsible create/edit modals, `private_data` for custom apps
+
+## Custom memory modules (V0.4.6)
+
+Load `.py` modules at runtime before create-agent or session import:
+
+```text
+add-memory-module path\to\my_module.py
+```
+
+Saves store `module_id` + state only (no bundled source). Import **fails** if a save references a module that is not loaded. Example: [examples/custom_memory/](examples/custom_memory/).
+
+## Lorebooks (V0.5.0)
+
+Load SillyTavern-style `.json` lorebooks into the session (CLI `load-lorebook` or realm-studio **Lorebooks** tab). Add a `lorebook` prompt block (per book) in Prompt layout to inject matched world info. Not included in the default prompt layout.
+
+## CLI reference
+
+Full command list, world editing, blocking, hidden objects, triggers, and compound-turn examples: [docs/guides/cli.md](docs/guides/cli.md).
+
+## Tests
+
+```powershell
+# Engine (repo root)
+uv run pytest
+
+# realm-studio
+cd examples\web\realm-studio
+uv run pytest
+```
+
+No API key or network required — LLM calls are mocked in tests.
+
+## Documentation
+
+Start at **[docs/README.md](docs/README.md)** — guides, API overview, and changelog index.
+
+| Doc | Topic |
+|-----|--------|
+| [Building on Realm-Fabric](docs/guides/building-on-realm-fabric.md) | App integration (typed API, hosting) |
+| [CLI reference](docs/guides/cli.md) | `realm` stepper commands |
+| [V0.7.0 changelog](docs/changelog/v0.7.0-changelog.md) | Platform SDK, minimal-server |
+| [Roadmap](docs/ROADMAP.md) | Version plans |
+| [realm-studio](examples/web/realm-studio/README.md) | Full GM reference UI |
+| [Long-term goals](LONG_TERM_GOALS.md) | Aspirational features |
+
+Older version notes: [changelog index](docs/changelog/README.md).

realm_fabric-0.7.0/profiles/default_compound/few_shots.txt

@@ -0,0 +1,63 @@
+Example 1: Move, look, and speak
+
+Context:
+Passive Vision:
+You are at (1, 1).
+Detail marked [?] can be examined with look.
+Ceramic Ball (obj_ball_01), (2, 2) - [?]
+  - kick (range 1)
+Wooden Sign (obj_sign_01), (2, 4) - [?] A simple wooden sign on the wall.
+
+Output:
+{
+  "reasoning": "The ball is at (2, 2). I will move closer, examine it, and comment.",
+  "move": "2,3",
+  "look": "obj_ball_01",
+  "say": "Interesting ball.",
+  "action": "none",
+  "target": null,
+  "verb": null
+}
+
+Example 2: Stay in place and speak
+
+Context:
+Passive Vision:
+You are at (2, 2).
+Detail marked [?] can be examined with look.
+Ceramic Ball (obj_ball_01), (2, 2) - [?]
+  - kick (range 1)
+Wooden Sign (obj_sign_01), (2, 4) - [?] A simple wooden sign on the wall.
+
+Output:
+{
+  "reasoning": "Nothing new to examine. I will speak from here.",
+  "move": null,
+  "look": null,
+  "say": "Hello, room.",
+  "action": "none",
+  "target": null,
+  "verb": null
+}
+
+Example 3: Move only
+
+Context:
+Passive Vision:
+You are at (1, 1).
+Detail marked [?] can be examined with look.
+Ceramic Ball (obj_ball_01), (2, 2) - [?]
+  - kick (range 1)
+Wooden Sign (obj_sign_01), (2, 4) - [?] A simple wooden sign on the wall.
+You may move to any coordinate (x, y) where x is an integer from 0 to 4 and y is an integer from 0 to 4.
+
+Output:
+{
+  "reasoning": "The sign is at (2, 4). I will move closer.",
+  "move": "2,3",
+  "look": null,
+  "say": null,
+  "action": "none",
+  "target": null,
+  "verb": null
+}

realm_fabric-0.7.0/profiles/default_compound/template.txt

@@ -0,0 +1,17 @@
+{{character}}
+
+Passive Vision:
+{{passive_vision}}
+
+{{grid_description}}
+
+{{compound_rules}}
+
+{{area_description}}
+
+{{move_instructions}}
+
+Memory:
+{{memory}}
+
+{{output_format}}

realm_fabric-0.7.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "realm-fabric"
+version = "0.7.0"
+description = "Grid-based LLM agent simulation engine — Session API, multi-area worlds, tactical movement, compound turns, pluggable memory"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "DaveH-Ghost", email = "davidhall.a27@gmail.com" },
+]
+keywords = [
+    "llm",
+    "agents",
+    "simulation",
+    "game-engine",
+    "grid",
+    "roleplay",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pydantic",
+    "openai",
+    "rich",
+    "python-dotenv",
+]
+
+[project.urls]
+Homepage = "https://github.com/DaveH-Ghost/Realm-Fabric"
+Documentation = "https://github.com/DaveH-Ghost/Realm-Fabric/blob/main/docs/README.md"
+Repository = "https://github.com/DaveH-Ghost/Realm-Fabric"
+Issues = "https://github.com/DaveH-Ghost/Realm-Fabric/issues"
+Changelog = "https://github.com/DaveH-Ghost/Realm-Fabric/blob/main/docs/changelog/README.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+addopts = "-q"
+
+[project.scripts]
+realm = "src.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+packages = ["src", "realm_fabric"]
+
+[tool.hatch.build.targets.wheel]
+force-include = { "profiles" = "profiles" }
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/profiles",
+]
+force-include = { "profiles" = "profiles" }
+
+[tool.uv]
+package = true