From f8a6372d95368ae67bfc835f8a2274770bf8e7da Mon Sep 17 00:00:00 2001
From: Sean Sube <seansube@gmail.com>
Date: Mon, 17 Jun 2024 09:32:25 -0500
Subject: [PATCH] start dev guide

---
 README.md                     |  2 +-
 docs/guides/developer.md      | 86 +++++++++++++++++++++++++++++++++++
 taleweave/systems/planning.py |  6 ++-
 3 files changed, 92 insertions(+), 2 deletions(-)
 create mode 100644 docs/guides/developer.md

diff --git a/README.md b/README.md
index 271d566..1d624f4 100644
--- a/README.md
+++ b/README.md
@@ -36,7 +36,7 @@ TaleWeave AI can:
 - Be run locally - does not require any cloud services, but does play nicely with them
 - Connect to your data - game systems can fetch data for RAG
 - Export training data for fine tuning character models
-- Plug in to your workflow - run step by step in notebook as a Python library
+- Plug in to your workflow - run the simulation step by step in Jupyter notebooks as a Python library
 - Connect to your server and vice versa - the Discord bot is a plugin and can be replaced with your favorite chat platform
 
 ## Contents
diff --git a/docs/guides/developer.md b/docs/guides/developer.md
new file mode 100644
index 0000000..caa231a
--- /dev/null
+++ b/docs/guides/developer.md
@@ -0,0 +1,86 @@
+# Developer's Guide to TaleWeave AI
+
+## Contents
+
+- [Developer's Guide to TaleWeave AI](#developers-guide-to-taleweave-ai)
+  - [Contents](#contents)
+  - [Extending the Game](#extending-the-game)
+    - [Developing Extra Actions](#developing-extra-actions)
+    - [Developing Game Systems](#developing-game-systems)
+  - [Modifying the Prompts](#modifying-the-prompts)
+  - [Modifying the World](#modifying-the-world)
+    - [Using the World Editor](#using-the-world-editor)
+    - [Creating New Worlds](#creating-new-worlds)
+    - [Modifying Existing Worlds](#modifying-existing-worlds)
+
+## Extending the Game
+
+There are two primary ways to extend TaleWeave AI: extra actions and new game systems.
+
+Extra actions offer characters new ways to interact with the world or give administrators new ways to control the world.
+
+Game systems can add new game mechanics, logical systems, and even new stages during each turn. All of the base game
+mechanics are implemented using optional systems - you can disable the planning and action stages, if you want.
+
+### Developing Extra Actions
+
+Actions are Python functions using the Langchain tool calling mechanism and OpenAI tool JSON schema.
+
+### Developing Game Systems
+
+Game systems can provide callbacks to:
+
+- `format` entity attributes to be added to their prompt
+- `generate` attributes and other data for the system
+- `initialize` the system's data
+- `simulate` the system on each turn
+
+## Modifying the Prompts
+
+TaleWeave AI ships with prompts that are compatible with most Llama-based models, but you may want to use custom
+prompts if you are using models that use a different prompt style or were trained in a different language.
+
+## Modifying the World
+
+### Using the World Editor
+
+TaleWeave AI comes with a basic command-line world editor that can be used to add, remove, and modify entities in
+your game worlds and saved states.
+
+### Creating New Worlds
+
+TaleWeave AI worlds are stored in human-readable markup languages, usually JSON or YAML. You can create new worlds
+using the world editor or your favorite text editor.
+
+You can use the JSON schema for the `World` entity to generate new worlds using models that understand JSON schemas
+or tools like `outlines`.
+
+Prompts for ChatGPT and similar models:
+
+> Characters:
+>
+> - Alice
+> - Bob
+>
+> Rooms:
+>
+> - House
+> - Office
+>
+> Remember these lists and help generate each room, one by one, based on the following schema.
+> I will prompt you for each room. Do not generate any rooms until prompted.
+> Generate one room for each prompt, and include some characters. Only include each character in one room, do not reuse characters.
+
+Followed by:
+
+> Generate the "House" room based on this JSON schema.
+
+Upload the `schema/room.json` file along with the last prompt.
+
+To generate more rooms:
+
+> Generate another room using the same JSON schema. Generate the "Office" room.
+
+If the model starts to forget the schema, upload the prompt again and alternate prompts as needed.
+
+### Modifying Existing Worlds
diff --git a/taleweave/systems/planning.py b/taleweave/systems/planning.py
index 3868ac0..e5d6c25 100644
--- a/taleweave/systems/planning.py
+++ b/taleweave/systems/planning.py
@@ -193,4 +193,8 @@ def simulate_planning(world: World, turn: int, data: Any | None = None):
 
 def init_planning():
     # TODO: add format method that renders the recent notes and upcoming events
-    return [GameSystem("planning", simulate=simulate_planning)]
+    return [
+        GameSystem(
+            "planning", initialize=initialize_planning, simulate=simulate_planning
+        )
+    ]