grimoire-spec 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. grimoire_spec-0.1.1/.github/agents/prompt-engineer.agent.md +74 -0
  2. grimoire_spec-0.1.1/.github/workflows/ci.yml +71 -0
  3. grimoire_spec-0.1.1/.github/workflows/release-please.yml +26 -0
  4. grimoire_spec-0.1.1/.github/workflows/release.yml +60 -0
  5. grimoire_spec-0.1.1/.gitignore +4 -0
  6. grimoire_spec-0.1.1/.release-please-manifest.json +3 -0
  7. grimoire_spec-0.1.1/AI_GUIDANCE.md +31 -0
  8. grimoire_spec-0.1.1/CHANGELOG.md +45 -0
  9. grimoire_spec-0.1.1/PKG-INFO +11 -0
  10. grimoire_spec-0.1.1/README.md +115 -0
  11. grimoire_spec-0.1.1/examples/load_system.py +106 -0
  12. grimoire_spec-0.1.1/pyproject.toml +38 -0
  13. grimoire_spec-0.1.1/release-please-config.json +11 -0
  14. grimoire_spec-0.1.1/spec/README.md +221 -0
  15. grimoire_spec-0.1.1/spec/compendium_spec.md +261 -0
  16. grimoire_spec-0.1.1/spec/flow_spec.md +593 -0
  17. grimoire_spec-0.1.1/spec/model_spec.md +262 -0
  18. grimoire_spec-0.1.1/spec/prompt_spec.md +219 -0
  19. grimoire_spec-0.1.1/spec/source_spec.md +283 -0
  20. grimoire_spec-0.1.1/spec/system_spec.md +127 -0
  21. grimoire_spec-0.1.1/spec/table_spec.md +372 -0
  22. grimoire_spec-0.1.1/src/grimoire/__init__.py +0 -0
  23. grimoire_spec-0.1.1/src/grimoire/loader.py +444 -0
  24. grimoire_spec-0.1.1/src/grimoire/models/compendium_definition.py +97 -0
  25. grimoire_spec-0.1.1/src/grimoire/models/flow.py +342 -0
  26. grimoire_spec-0.1.1/src/grimoire/models/model_definition.py +216 -0
  27. grimoire_spec-0.1.1/src/grimoire/models/prompt.py +68 -0
  28. grimoire_spec-0.1.1/src/grimoire/models/source.py +31 -0
  29. grimoire_spec-0.1.1/src/grimoire/models/system.py +146 -0
  30. grimoire_spec-0.1.1/src/grimoire/models/table.py +159 -0
  31. grimoire_spec-0.1.1/systems/knave-1e/compendiums/armor/helmets-and-shields.yaml +25 -0
  32. grimoire_spec-0.1.1/systems/knave-1e/compendiums/armor/suits.yaml +60 -0
  33. grimoire_spec-0.1.1/systems/knave-1e/compendiums/items/clothing.yaml +42 -0
  34. grimoire_spec-0.1.1/systems/knave-1e/compendiums/items/food.yaml +141 -0
  35. grimoire_spec-0.1.1/systems/knave-1e/compendiums/items/munitions.yaml +31 -0
  36. grimoire_spec-0.1.1/systems/knave-1e/compendiums/items/tools-and-gear.yaml +480 -0
  37. grimoire_spec-0.1.1/systems/knave-1e/compendiums/light_sources/light.yaml +60 -0
  38. grimoire_spec-0.1.1/systems/knave-1e/compendiums/weapons/melee.yaml +133 -0
  39. grimoire_spec-0.1.1/systems/knave-1e/compendiums/weapons/ranged.yaml +40 -0
  40. grimoire_spec-0.1.1/systems/knave-1e/fixtures/character/basic.json +30 -0
  41. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/character_creation/basic_character.yaml +13 -0
  42. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/inventory/add_item.json +32 -0
  43. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/inventory/add_item.yaml +17 -0
  44. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/perform_saving_throw/basic.json +25 -0
  45. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/perform_saving_throw/basic.yaml +14 -0
  46. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_opposed_save/basic.json +27 -0
  47. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_opposed_save/basic.yaml +17 -0
  48. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/advantage.json +5 -0
  49. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/advantage.yaml +3 -0
  50. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/basic.json +5 -0
  51. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/basic.yaml +3 -0
  52. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/disadvantage.json +5 -0
  53. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/disadvantage.yaml +3 -0
  54. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/failure.json +5 -0
  55. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/failure.yaml +3 -0
  56. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/success.json +5 -0
  57. grimoire_spec-0.1.1/systems/knave-1e/fixtures/flows/roll_saving_throw/success.yaml +3 -0
  58. grimoire_spec-0.1.1/systems/knave-1e/flows/character_creation/choose_name_and_gender.yaml +118 -0
  59. grimoire_spec-0.1.1/systems/knave-1e/flows/character_creation/choose_starting_weapon.yaml +54 -0
  60. grimoire_spec-0.1.1/systems/knave-1e/flows/character_creation/determine_traits.yaml +84 -0
  61. grimoire_spec-0.1.1/systems/knave-1e/flows/character_creation/roll_abilities.yaml +66 -0
  62. grimoire_spec-0.1.1/systems/knave-1e/flows/character_creation/roll_hit_points.yaml +47 -0
  63. grimoire_spec-0.1.1/systems/knave-1e/flows/character_creation/roll_starting_gear.yaml +71 -0
  64. grimoire_spec-0.1.1/systems/knave-1e/flows/character_creation.yaml +141 -0
  65. grimoire_spec-0.1.1/systems/knave-1e/flows/combat/perform_initiative.yaml +27 -0
  66. grimoire_spec-0.1.1/systems/knave-1e/flows/determine_npc_reaction.yaml +25 -0
  67. grimoire_spec-0.1.1/systems/knave-1e/flows/inventory/add_item_to_character.yaml +37 -0
  68. grimoire_spec-0.1.1/systems/knave-1e/flows/inventory/add_items_to_character.yaml +43 -0
  69. grimoire_spec-0.1.1/systems/knave-1e/flows/saving_throws/perform_saving_throw.yaml +109 -0
  70. grimoire_spec-0.1.1/systems/knave-1e/flows/saving_throws/roll_opposed_save.yaml +72 -0
  71. grimoire_spec-0.1.1/systems/knave-1e/flows/saving_throws/roll_saving_throw.yaml +73 -0
  72. grimoire_spec-0.1.1/systems/knave-1e/models/armor.yaml +9 -0
  73. grimoire_spec-0.1.1/systems/knave-1e/models/breakable.yaml +7 -0
  74. grimoire_spec-0.1.1/systems/knave-1e/models/character.yaml +43 -0
  75. grimoire_spec-0.1.1/systems/knave-1e/models/character_abilities.yaml +12 -0
  76. grimoire_spec-0.1.1/systems/knave-1e/models/character_ability.yaml +8 -0
  77. grimoire_spec-0.1.1/systems/knave-1e/models/character_traits.yaml +17 -0
  78. grimoire_spec-0.1.1/systems/knave-1e/models/item.yaml +13 -0
  79. grimoire_spec-0.1.1/systems/knave-1e/models/weapon.yaml +10 -0
  80. grimoire_spec-0.1.1/systems/knave-1e/prompts/determine-saving-throw-ability.yaml +81 -0
  81. grimoire_spec-0.1.1/systems/knave-1e/prompts/determine-saving-throw-type.yaml +87 -0
  82. grimoire_spec-0.1.1/systems/knave-1e/prompts/fix-json.yaml +17 -0
  83. grimoire_spec-0.1.1/systems/knave-1e/prompts/generate-character-description.yaml +65 -0
  84. grimoire_spec-0.1.1/systems/knave-1e/prompts/item-description.yaml +31 -0
  85. grimoire_spec-0.1.1/systems/knave-1e/sources/rules-toolkit.yaml +8 -0
  86. grimoire_spec-0.1.1/systems/knave-1e/system.yaml +14 -0
  87. grimoire_spec-0.1.1/systems/knave-1e/tables/gear/armor.yaml +12 -0
  88. grimoire_spec-0.1.1/systems/knave-1e/tables/gear/dungeoneering-gear.yaml +28 -0
  89. grimoire_spec-0.1.1/systems/knave-1e/tables/gear/general-gear-1.yaml +28 -0
  90. grimoire_spec-0.1.1/systems/knave-1e/tables/gear/general-gear-2.yaml +28 -0
  91. grimoire_spec-0.1.1/systems/knave-1e/tables/gear/helmets-and-shields.yaml +12 -0
  92. grimoire_spec-0.1.1/systems/knave-1e/tables/gear/weapons.yaml +24 -0
  93. grimoire_spec-0.1.1/systems/knave-1e/tables/misc/gender.yaml +10 -0
  94. grimoire_spec-0.1.1/systems/knave-1e/tables/misc/npc-reactions.yaml +12 -0
  95. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/alignment.yaml +10 -0
  96. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/background.yaml +27 -0
  97. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/clothing.yaml +27 -0
  98. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/face.yaml +27 -0
  99. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/hair.yaml +27 -0
  100. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/misfortunes.yaml +27 -0
  101. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/physique.yaml +27 -0
  102. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/skin.yaml +27 -0
  103. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/speech.yaml +27 -0
  104. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/vice.yaml +27 -0
  105. grimoire_spec-0.1.1/systems/knave-1e/tables/traits/virtue.yaml +27 -0
  106. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/compendiums/armor/armor.yaml +36 -0
  107. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/compendiums/gear/gear.yaml +106 -0
  108. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/compendiums/spells/tier_1.yaml +51 -0
  109. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/compendiums/starting_gear/cloak.yaml +14 -0
  110. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/compendiums/weapons/weapons.yaml +106 -0
  111. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/flows/character_creation/calculate_starting_hp.yaml +103 -0
  112. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/flows/character_creation/determine_traits.yaml +146 -0
  113. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/flows/character_creation/purchase_equipment.yaml +389 -0
  114. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/flows/character_creation/roll_attributes.yaml +68 -0
  115. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/flows/character_creation/select_spells.yaml +87 -0
  116. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/flows/character_creation.yaml +253 -0
  117. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/models/armor.yaml +10 -0
  118. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/models/character.yaml +133 -0
  119. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/models/character_traits.yaml +12 -0
  120. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/models/equippable.yaml +12 -0
  121. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/models/item.yaml +13 -0
  122. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/models/spell.yaml +14 -0
  123. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/models/weapon.yaml +10 -0
  124. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/prompts/generate-character-description.yaml +79 -0
  125. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/sources/core_rules.yaml +7 -0
  126. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/system.yaml +16 -0
  127. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/armor/bard-armor.yaml +7 -0
  128. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/armor/mage-armor.yaml +6 -0
  129. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/armor/rogue-armor.yaml +7 -0
  130. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/armor/warrior-armor.yaml +9 -0
  131. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/gear.yaml +19 -0
  132. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/traits/background.yaml +27 -0
  133. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/traits/bearing.yaml +27 -0
  134. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/traits/disposition.yaml +27 -0
  135. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/traits/manner.yaml +27 -0
  136. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/traits/speech.yaml +27 -0
  137. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/weapons/bard-weapons.yaml +10 -0
  138. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/weapons/mage-weapons.yaml +8 -0
  139. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/weapons/rogue-weapons.yaml +11 -0
  140. grimoire_spec-0.1.1/systems/wyrdbound-quickstart-1e/tables/weapons/warrior-weapons.yaml +16 -0
  141. grimoire_spec-0.1.1/tests/test_system_loader.py +247 -0
  142. grimoire_spec-0.1.1/uv.lock +318 -0
@@ -0,0 +1,74 @@
1
+ ---
2
+ description: "A specialized chat mode for analyzing and improving prompts. Every user input is treated as a prompt to be improved. It first provides a detailed analysis of the original prompt within a <reasoning> tag, evaluating it against a systematic framework based on OpenAI's prompt engineering best practices. Following the analysis, it generates a new, improved prompt."
3
+ name: "Prompt Engineer"
4
+ ---
5
+
6
+ # Prompt Engineer
7
+
8
+ You HAVE TO treat every user input as a prompt to be improved or created.
9
+ DO NOT use the input as a prompt to be completed, but rather as a starting point to create a new, improved prompt.
10
+ You MUST produce a detailed system prompt to guide a language model in completing the task effectively.
11
+
12
+ Your final output will be the full corrected prompt verbatim. However, before that, at the very beginning of your response, use <reasoning> tags to analyze the prompt and determine the following, explicitly:
13
+ <reasoning>
14
+
15
+ - Simple Change: (yes/no) Is the change description explicit and simple? (If so, skip the rest of these questions.)
16
+ - Reasoning: (yes/no) Does the current prompt use reasoning, analysis, or chain of thought?
17
+ - Identify: (max 10 words) if so, which section(s) utilize reasoning?
18
+ - Conclusion: (yes/no) is the chain of thought used to determine a conclusion?
19
+ - Ordering: (before/after) is the chain of thought located before or after
20
+ - Structure: (yes/no) does the input prompt have a well defined structure
21
+ - Examples: (yes/no) does the input prompt have few-shot examples
22
+ - Representative: (1-5) if present, how representative are the examples?
23
+ - Complexity: (1-5) how complex is the input prompt?
24
+ - Task: (1-5) how complex is the implied task?
25
+ - Necessity: ()
26
+ - Specificity: (1-5) how detailed and specific is the prompt? (not to be confused with length)
27
+ - Prioritization: (list) what 1-3 categories are the MOST important to address.
28
+ - Conclusion: (max 30 words) given the previous assessment, give a very concise, imperative description of what should be changed and how. this does not have to adhere strictly to only the categories listed
29
+ </reasoning>
30
+
31
+ After the <reasoning> section, you will output the full prompt verbatim, without any additional commentary or explanation.
32
+
33
+ # Guidelines
34
+
35
+ - Understand the Task: Grasp the main objective, goals, requirements, constraints, and expected output.
36
+ - Minimal Changes: If an existing prompt is provided, improve it only if it's simple. For complex prompts, enhance clarity and add missing elements without altering the original structure.
37
+ - Reasoning Before Conclusions\*\*: Encourage reasoning steps before any conclusions are reached. ATTENTION! If the user provides examples where the reasoning happens afterward, REVERSE the order! NEVER START EXAMPLES WITH CONCLUSIONS!
38
+ - Reasoning Order: Call out reasoning portions of the prompt and conclusion parts (specific fields by name). For each, determine the ORDER in which this is done, and whether it needs to be reversed.
39
+ - Conclusion, classifications, or results should ALWAYS appear last.
40
+ - Examples: Include high-quality examples if helpful, using placeholders [in brackets] for complex elements.
41
+ - What kinds of examples may need to be included, how many, and whether they are complex enough to benefit from placeholders.
42
+ - Clarity and Conciseness: Use clear, specific language. Avoid unnecessary instructions or bland statements.
43
+ - Formatting: Use markdown features for readability. DO NOT USE ``` CODE BLOCKS UNLESS SPECIFICALLY REQUESTED.
44
+ - Preserve User Content: If the input task or prompt includes extensive guidelines or examples, preserve them entirely, or as closely as possible. If they are vague, consider breaking down into sub-steps. Keep any details, guidelines, examples, variables, or placeholders provided by the user.
45
+ - Constants: DO include constants in the prompt, as they are not susceptible to prompt injection. Such as guides, rubrics, and examples.
46
+ - Output Format: Explicitly the most appropriate output format, in detail. This should include length and syntax (e.g. short sentence, paragraph, JSON, etc.)
47
+ - For tasks outputting well-defined or structured data (classification, JSON, etc.) bias toward outputting a JSON.
48
+ - JSON should never be wrapped in code blocks (```) unless explicitly requested.
49
+
50
+ The final prompt you output should adhere to the following structure below. Do not include any additional commentary, only output the completed system prompt. SPECIFICALLY, do not include any additional messages at the start or end of the prompt. (e.g. no "---")
51
+
52
+ [Concise instruction describing the task - this should be the first line in the prompt, no section header]
53
+
54
+ [Additional details as needed.]
55
+
56
+ [Optional sections with headings or bullet points for detailed steps.]
57
+
58
+ # Steps [optional]
59
+
60
+ [optional: a detailed breakdown of the steps necessary to accomplish the task]
61
+
62
+ # Output Format
63
+
64
+ [Specifically call out how the output should be formatted, be it response length, structure e.g. JSON, markdown, etc]
65
+
66
+ # Examples [optional]
67
+
68
+ [Optional: 1-3 well-defined examples with placeholders if necessary. Clearly mark where examples start and end, and what the input and output are. User placeholders as necessary.]
69
+ [If the examples are shorter than what a realistic example is expected to be, make a reference with () explaining how real examples should be longer / shorter / different. AND USE PLACEHOLDERS! ]
70
+
71
+ # Notes [optional]
72
+
73
+ [optional: edge cases, details, and an area to call or repeat out specific important considerations]
74
+ [NOTE: you must start with a <reasoning> section. the immediate next token you produce should be <reasoning>]
@@ -0,0 +1,71 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, develop]
6
+ pull_request:
7
+ branches: [main, develop]
8
+
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ python-version: ["3.11", "3.12"]
15
+
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - name: Set up Python ${{ matrix.python-version }}
20
+ uses: actions/setup-python@v5
21
+ with:
22
+ python-version: ${{ matrix.python-version }}
23
+
24
+ - name: Install dependencies
25
+ run: |
26
+ python -m pip install --upgrade pip
27
+ pip install -e ".[dev]"
28
+
29
+ - name: Run tests with pytest
30
+ run: python -m pytest tests/ -v --tb=short
31
+
32
+ code-quality:
33
+ runs-on: ubuntu-latest
34
+ steps:
35
+ - uses: actions/checkout@v4
36
+
37
+ - name: Set up Python
38
+ uses: actions/setup-python@v5
39
+ with:
40
+ python-version: "3.11"
41
+
42
+ - name: Install dependencies
43
+ run: |
44
+ python -m pip install --upgrade pip
45
+ pip install -e ".[dev]"
46
+
47
+ - name: Check code formatting and linting with Ruff
48
+ run: |
49
+ ruff check src/ tests/
50
+ ruff format --check src/ tests/
51
+
52
+ - name: Type checking with mypy
53
+ run: mypy src/
54
+
55
+ install-test:
56
+ runs-on: ubuntu-latest
57
+ steps:
58
+ - uses: actions/checkout@v4
59
+
60
+ - name: Set up Python
61
+ uses: actions/setup-python@v5
62
+ with:
63
+ python-version: "3.11"
64
+
65
+ - name: Test package installation
66
+ run: |
67
+ python -m pip install --upgrade pip
68
+ pip install .
69
+
70
+ - name: Test basic import
71
+ run: python -c "import grimoire; print('Import successful')"
@@ -0,0 +1,26 @@
1
+ name: Release Please
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+
8
+ permissions:
9
+ contents: write
10
+ pull-requests: write
11
+
12
+ jobs:
13
+ release-please:
14
+ runs-on: ubuntu-latest
15
+ env:
16
+ FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
17
+ outputs:
18
+ release_created: ${{ steps.release.outputs.release_created }}
19
+ tag_name: ${{ steps.release.outputs.tag_name }}
20
+ steps:
21
+ - uses: googleapis/release-please-action@v4
22
+ id: release
23
+ with:
24
+ token: ${{ secrets.GITHUB_TOKEN }}
25
+ config-file: release-please-config.json
26
+ manifest-file: .release-please-manifest.json
@@ -0,0 +1,60 @@
1
+ name: Release
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+ inputs:
8
+ tag:
9
+ description: "Tag to publish (e.g. v0.1.0)"
10
+ required: true
11
+
12
+ jobs:
13
+ test:
14
+ runs-on: ubuntu-latest
15
+ strategy:
16
+ matrix:
17
+ python-version: ["3.11", "3.12"]
18
+
19
+ steps:
20
+ - uses: actions/checkout@v4
21
+
22
+ - name: Set up Python ${{ matrix.python-version }}
23
+ uses: actions/setup-python@v5
24
+ with:
25
+ python-version: ${{ matrix.python-version }}
26
+
27
+ - name: Install dependencies
28
+ run: |
29
+ python -m pip install --upgrade pip
30
+ pip install -e ".[dev]"
31
+
32
+ - name: Run tests
33
+ run: python -m pytest tests/ -v
34
+
35
+ build-and-publish:
36
+ needs: test
37
+ runs-on: ubuntu-latest
38
+ environment: release
39
+ permissions:
40
+ contents: read
41
+ id-token: write # required for PyPI trusted publishing
42
+
43
+ steps:
44
+ - uses: actions/checkout@v4
45
+
46
+ - name: Set up Python
47
+ uses: actions/setup-python@v5
48
+ with:
49
+ python-version: "3.11"
50
+
51
+ - name: Install build dependencies
52
+ run: |
53
+ python -m pip install --upgrade pip
54
+ pip install build
55
+
56
+ - name: Build package
57
+ run: python -m build
58
+
59
+ - name: Publish to PyPI
60
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,4 @@
1
+ # Python Env
2
+ .venv/
3
+ .tool-versions
4
+ *.pyc
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.1.1"
3
+ }
@@ -0,0 +1,31 @@
1
+ # AI Guidance
2
+
3
+ ALWAYS adhere to the following points as you are working on this code base:
4
+
5
+ 1. Use `uv` to create our Python virtual env, manage package dependencies, and run scripts.
6
+
7
+ 2. NEVER mask issues by using fallbacks that hide errors. Prefer explicit errors over fallbacks. Fixing issues is the only way to ensure a stable system.
8
+
9
+ 3. Follow good software development practices (like SOLID).
10
+
11
+ 4. Simpler is better.
12
+
13
+ 5. Remember the purpose of this package is to provide its functionality in a clear and maintainable manner. Avoid adding special-cases or hack fixes simply to get around issues.
14
+
15
+ 6. Do NOT make bandaid fixes that break the rearchitecture goals for the library. Always respect the architectural boundaries.
16
+
17
+ 7. **Practice Test-Driven Development (TDD):** Write tests BEFORE implementing features using the red-green-refactor cycle:
18
+ - **Red:** Write a failing test that defines the desired behavior
19
+ - **Green:** Write minimal code to make the test pass
20
+ - **Refactor:** Improve code quality while keeping tests green
21
+
22
+ Benefits:
23
+ - Forces clear requirement thinking before coding
24
+ - Ensures all code is testable and tested
25
+ - Creates a safety net for refactoring
26
+ - Documents expected behavior through tests
27
+ - Prevents scope creep and over-engineering
28
+
29
+ 8. All package imports should be at the top of the file, following standard Python conventions. Avoid dynamic imports or imports within functions. Instead, consider refactoring code to allow for static imports. If circular dependencies arise, it's a sign that the code structure may need to be reconsidered.
30
+
31
+ 9. When implementing new features, always create corresponding example files in the `examples/` folder demonstrating usage. Follow existing example patterns (clear docstring, multiple use cases, well-commented code).
@@ -0,0 +1,45 @@
1
+ # Changelog
2
+
3
+ ## [0.1.1](https://github.com/wyrdbound/grimoire/compare/grimoire-spec-v0.1.0...grimoire-spec-v0.1.1) (2026-04-18)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * publishing to PyPI ([7098477](https://github.com/wyrdbound/grimoire/commit/709847743b3291d2296a2d61b535848817ad526e))
9
+
10
+ ## 0.1.0 (2026-04-18)
11
+
12
+
13
+ ### Features
14
+
15
+ * add release-please and CI/CD workflows for PyPI publishing ([b4a7db5](https://github.com/wyrdbound/grimoire/commit/b4a7db50b891f8169f144247415d1e0433c2e85e))
16
+ * add release-please and CI/CD workflows for PyPI publishing ([d9fbb2b](https://github.com/wyrdbound/grimoire/commit/d9fbb2b0b2b6323d30fee372fb994365a8c761ec))
17
+ * add system loader with validation ([9c06637](https://github.com/wyrdbound/grimoire/commit/9c0663703003c3803142add229f8c8c209c2345d))
18
+ * character model equipped slots use model types; inventory tracks item IDs ([fbafdbc](https://github.com/wyrdbound/grimoire/commit/fbafdbcdcaa0b129bbaf5e5c1e931189305ea0ab))
19
+ * continuous equipment shop with category routing, afford check, and equip prompt ([225ee2f](https://github.com/wyrdbound/grimoire/commit/225ee2f7f6b867bba3df4615f10838e4096e3755))
20
+ * migrate calculate_starting_hp to structured then/else blocks with next_step ([479b45d](https://github.com/wyrdbound/grimoire/commit/479b45d9b8a988c2cedbecfd01bf01489762258d))
21
+ * **wq1e:** add default to determine_traits description output ([b85c1fa](https://github.com/wyrdbound/grimoire/commit/b85c1fad3b3490c8c65b18826fb9128fe63b8047))
22
+ * **wq1e:** add equipment system ([c9520d6](https://github.com/wyrdbound/grimoire/commit/c9520d614995e968f7b4c45b6ca33e3f6a028947))
23
+ * **wq1e:** add trait selection and character description to character creation ([3b9ebda](https://github.com/wyrdbound/grimoire/commit/3b9ebdacba3c3d36c941cdd11cec27195ddb9a27))
24
+ * **wq1e:** class-specific weapon/armor tables ([5bc6b9f](https://github.com/wyrdbound/grimoire/commit/5bc6b9fa3ad788d75745c4e3f38185691abbc8de))
25
+ * **wq1e:** dice details, confirm steps, LLM progress indicator ([038424f](https://github.com/wyrdbound/grimoire/commit/038424fb835bf7efbec600306b51a577745d189f))
26
+ * **wq1e:** move generate_description step to character_creation flow ([8ac36a7](https://github.com/wyrdbound/grimoire/commit/8ac36a70f7b0e11f1944af8da8f257131e2b9d1c))
27
+ * **wq1e:** replace physique/virtue/vice with bearing/manner/disposition ([f2f4e60](https://github.com/wyrdbound/grimoire/commit/f2f4e60a21fec890f0b8a23c6bc4e0f2b6b2f8a8))
28
+ * **wq1e:** use wyrdbound-dice description string for dice display ([138b383](https://github.com/wyrdbound/grimoire/commit/138b3832a4341cc2262312da9139f9015e98a8bd))
29
+ * **wyrdbound-quickstart-1e:** initial system spec ([e46ced7](https://github.com/wyrdbound/grimoire/commit/e46ced7b238ff558256a30e574a96671ec8d839b))
30
+
31
+
32
+ ### Bug Fixes
33
+
34
+ * bug with wrong system name in load_system.py ([4516f52](https://github.com/wyrdbound/grimoire/commit/4516f5256cc4b69fb0b1cee6f08c7bde36fc360b))
35
+ * mypy failure ([ba1a610](https://github.com/wyrdbound/grimoire/commit/ba1a610ec95c16628784a68c6fbad664de7c48a9))
36
+ * permissions issue in release.yml ([88b1dff](https://github.com/wyrdbound/grimoire/commit/88b1dffb8377efe63c2ae30a1e63897195e96be7))
37
+ * remove manual modifier set_value steps from character_creation ([bc67df6](https://github.com/wyrdbound/grimoire/commit/bc67df6805015acb54cae5c80164ccd2d0f22220))
38
+ * silence warning with FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true ([#4](https://github.com/wyrdbound/grimoire/issues/4)) ([85065a0](https://github.com/wyrdbound/grimoire/commit/85065a0abed1f4ccca42f3ad0a2af9e3a7690fed))
39
+ * test failures ([e646fd1](https://github.com/wyrdbound/grimoire/commit/e646fd1408951d9ec235314fa95e427e9aa42166))
40
+ * **wq1e:** roll_attributes display uses description only (no redundant total) ([e787a18](https://github.com/wyrdbound/grimoire/commit/e787a18401923b8122b392ab80c7a03892c55d00))
41
+
42
+
43
+ ### Documentation
44
+
45
+ * improve spec and Knave 1e reference implementation ([82b70e6](https://github.com/wyrdbound/grimoire/commit/82b70e6e37bbf31e2f09af163f008173546a5b50))
@@ -0,0 +1,11 @@
1
+ Metadata-Version: 2.4
2
+ Name: grimoire-spec
3
+ Version: 0.1.1
4
+ Summary: GRIMOIRE system definition loader and validator for tabletop RPG systems
5
+ Requires-Python: >=3.11
6
+ Requires-Dist: pyyaml>=6.0
7
+ Provides-Extra: dev
8
+ Requires-Dist: mypy>=1.9; extra == 'dev'
9
+ Requires-Dist: pytest>=8.0; extra == 'dev'
10
+ Requires-Dist: ruff>=0.3; extra == 'dev'
11
+ Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
@@ -0,0 +1,115 @@
1
+ # GRIMOIRE
2
+
3
+ **GRIMOIRE** (Generic Rule Implementation Model for Omniversal Interactive Roleplaying Engines) is a Python library for loading, validating, and working with structured tabletop RPG system definitions.
4
+
5
+ It provides a declarative YAML-based specification format for encoding game systems — covering models, flows, tables, compendiums, prompts, and sources — and a Python loader that parses and validates those definitions into typed Python objects.
6
+
7
+ GRIMOIRE is system-agnostic and not tied to any particular game or application. It is designed to be used as a foundation for tools that need to reason about RPG rules programmatically: AI game masters, character generators, rule validators, or any application that needs to load and execute structured game logic.
8
+
9
+ ---
10
+
11
+ ## Installation
12
+
13
+ To add to a uv-managed project:
14
+
15
+ ```bash
16
+ uv add grimoire-spec
17
+ ```
18
+
19
+ Or to install directly into an environment:
20
+
21
+ ```bash
22
+ uv pip install grimoire-spec
23
+ ```
24
+
25
+ ## Quick Start
26
+
27
+ ```python
28
+ from pathlib import Path
29
+ from grimoire.loader import SystemLoader
30
+
31
+ loader = SystemLoader()
32
+ system = loader.load(Path("systems/knave-1e"))
33
+
34
+ print(system.name) # "Knave (1st Edition)"
35
+ print(len(system.models)) # number of loaded models
36
+ print(len(system.flows)) # number of loaded flows
37
+
38
+ errors = system.validate()
39
+ if not errors:
40
+ print("System is valid")
41
+ ```
42
+
43
+ See the [`examples/`](examples/) directory for more usage patterns.
44
+
45
+ ## System Definition Format
46
+
47
+ A GRIMOIRE system is a directory containing YAML files organised by type:
48
+
49
+ ```
50
+ my-system/
51
+ system.yaml # root metadata, currency, attribution
52
+ models/ # data model definitions
53
+ flows/ # rule sequences and game mechanics
54
+ tables/ # random tables
55
+ compendiums/ # item/entity catalogues
56
+ prompts/ # AI prompt templates
57
+ sources/ # source material attribution
58
+ ```
59
+
60
+ Full specification for each file type is in [`spec/`](spec/).
61
+
62
+ ## Development
63
+
64
+ This project uses [`uv`](https://github.com/astral-sh/uv) for environment and dependency management.
65
+
66
+ ### Setup
67
+
68
+ ```bash
69
+ uv sync --extra dev
70
+ ```
71
+
72
+ ### Run tests
73
+
74
+ ```bash
75
+ uv run pytest
76
+ ```
77
+
78
+ ### Linting and formatting
79
+
80
+ ```bash
81
+ uv run ruff check src/ tests/
82
+ uv run ruff format src/ tests/
83
+ ```
84
+
85
+ ### Type checking
86
+
87
+ ```bash
88
+ uv run mypy src/
89
+ ```
90
+
91
+ ### Run an example
92
+
93
+ ```bash
94
+ uv run python examples/load_system.py
95
+ ```
96
+
97
+ ## Project Structure
98
+
99
+ ```
100
+ src/grimoire/ # library source
101
+ loader.py # SystemLoader — entry point for loading a system directory
102
+ models/ # typed Python models for each definition type
103
+ spec/ # YAML format specification documents
104
+ systems/ # bundled example systems (knave-1e, wyrdbound-quickstart-1e)
105
+ examples/ # usage examples
106
+ tests/ # test suite
107
+ ```
108
+
109
+ ## Contributing
110
+
111
+ Contributions are welcome. Please follow the existing code style (enforced by Ruff) and ensure all tests pass before submitting a pull request. New features should be accompanied by tests and an example in `examples/`.
112
+
113
+ ## License
114
+
115
+ See [LICENSE](LICENSE) for details.
@@ -0,0 +1,106 @@
1
+ """Examples demonstrating SystemLoader usage.
2
+
3
+ Shows how to load a GRIMOIRE system directory into a System object,
4
+ inspect its contents, and run validation.
5
+ """
6
+
7
+ from pathlib import Path
8
+
9
+ from grimoire.loader import SystemLoader, SystemLoadError
10
+
11
+ SYSTEMS_DIR = Path(__file__).parent.parent / "systems"
12
+
13
+
14
+ def example_load_and_validate(system_name: str) -> None:
15
+ """Load a system directory and run validation, printing any errors."""
16
+ loader = SystemLoader()
17
+ system_path = SYSTEMS_DIR / system_name
18
+
19
+ print(f"\n── Loading system: {system_path} ──")
20
+ system = loader.load(system_path)
21
+
22
+ print(f" id: {system.id}")
23
+ print(f" name: {system.name}")
24
+ print(f" version: {system.version}")
25
+ print(f" models: {len(system.models)}")
26
+ print(f" flows: {len(system.flows)}")
27
+ print(f" tables: {len(system.tables)}")
28
+ print(f" compendiums: {len(system.compendiums)}")
29
+ print(f" prompts: {len(system.prompts)}")
30
+ print(f" sources: {len(system.sources)}")
31
+
32
+ errors = system.validate()
33
+ if errors:
34
+ print(f"\n ✗ Validation errors ({len(errors)}):")
35
+ for error in errors:
36
+ print(f" - {error}")
37
+ else:
38
+ print("\n ✓ System is valid")
39
+
40
+
41
+ def example_inspect_models(system_name: str = "knave-1e") -> None:
42
+ """Load a system and print the names of all loaded models."""
43
+ loader = SystemLoader()
44
+ system = loader.load(SYSTEMS_DIR / system_name)
45
+
46
+ print(f"\n── Models in '{system.name}' ──")
47
+ for model_id, model in sorted(system.models.items()):
48
+ extends = f" extends: {model.extends}" if model.extends else ""
49
+ print(f" {model_id}: {model.name}{extends}")
50
+
51
+
52
+ def example_inspect_flows(system_name: str = "knave-1e") -> None:
53
+ """Load a system and print a summary of all loaded flows."""
54
+ loader = SystemLoader()
55
+ system = loader.load(SYSTEMS_DIR / system_name)
56
+
57
+ print(f"\n── Flows in '{system.name}' ──")
58
+ for flow_id, flow in sorted(system.flows.items()):
59
+ step_count = len(flow.steps)
60
+ print(f" {flow_id}: {flow.name} ({step_count} steps)")
61
+
62
+
63
+ def example_inspect_compendiums(system_name: str = "knave-1e") -> None:
64
+ """Load a system and print compendium entry counts."""
65
+ loader = SystemLoader()
66
+ system = loader.load(SYSTEMS_DIR / system_name)
67
+
68
+ print(f"\n── Compendiums in '{system.name}' ──")
69
+ for comp_id, comp in sorted(system.compendiums.items()):
70
+ print(
71
+ f" {comp_id}: {comp.name} "
72
+ f"(model={comp.model}, entries={len(comp.entries)})"
73
+ )
74
+
75
+
76
+ def example_error_handling() -> None:
77
+ """Demonstrate error handling for invalid system paths."""
78
+ loader = SystemLoader()
79
+
80
+ print("\n── Error handling examples ──")
81
+
82
+ # Non-existent path
83
+ try:
84
+ loader.load(Path("/nonexistent/system"))
85
+ except SystemLoadError as e:
86
+ print(f" Non-existent path → SystemLoadError: {e}")
87
+
88
+ # Directory missing system.yaml
89
+ import tempfile
90
+
91
+ with tempfile.TemporaryDirectory() as tmpdir:
92
+ try:
93
+ loader.load(Path(tmpdir))
94
+ except SystemLoadError as e:
95
+ print(f" Missing system.yaml → SystemLoadError: {e}")
96
+
97
+
98
+ if __name__ == "__main__":
99
+ # Run all examples
100
+ for system_dir in ["knave-1e", "wyrdbound-quickstart-1e"]:
101
+ example_load_and_validate(system_dir)
102
+
103
+ example_inspect_models("knave-1e")
104
+ example_inspect_flows("knave-1e")
105
+ example_inspect_compendiums("knave-1e")
106
+ example_error_handling()
@@ -0,0 +1,38 @@
1
+ [project]
2
+ name = "grimoire-spec"
3
+ version = "0.1.1"
4
+ description = "GRIMOIRE system definition loader and validator for tabletop RPG systems"
5
+ requires-python = ">=3.11"
6
+ dependencies = [
7
+ "pyyaml>=6.0",
8
+ ]
9
+
10
+ [project.optional-dependencies]
11
+ dev = [
12
+ "pytest>=8.0",
13
+ "ruff>=0.3",
14
+ "mypy>=1.9",
15
+ "types-PyYAML>=6.0",
16
+ ]
17
+
18
+ [build-system]
19
+ requires = ["hatchling"]
20
+ build-backend = "hatchling.build"
21
+
22
+ [tool.hatch.build.targets.wheel]
23
+ packages = ["src/grimoire"]
24
+
25
+ [tool.ruff]
26
+ line-length = 88
27
+ target-version = "py311"
28
+
29
+ [tool.ruff.lint]
30
+ select = ["E", "F", "I", "UP"]
31
+
32
+ [tool.mypy]
33
+ python_version = "3.11"
34
+ strict = true
35
+ ignore_missing_imports = true
36
+
37
+ [tool.pytest.ini_options]
38
+ testpaths = ["tests"]
@@ -0,0 +1,11 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
3
+ "release-type": "python",
4
+ "packages": {
5
+ ".": {
6
+ "release-type": "python",
7
+ "package-name": "grimoire-spec",
8
+ "version-file": "pyproject.toml"
9
+ }
10
+ }
11
+ }