The Geometric Knowledge Engine

This white-box, geometric model is the perfect architectural fit for categorizing and reasoning about in-world entities like monsters, magic items, and even plot hooks.

It directly addresses the core needs of a GM: Consistency, Explainability, and Control. A black-box model might suggest a random monster; this model can explain why a "Ghoul" is a better thematic fit for a Lich's tomb than an "Ogre," based on shared conceptual traits.

---

1. Executive Summary

The Codex Engine will implement the proposed white-box, geometric classification model as its core "Knowledge Engine." This engine will be used to represent, categorize, and query all non-geographic game entities, such as monsters, magic items, spells, and factions.

By defining these entities as vectors in a high-dimensional "conceptual space," we enable powerful, intuitive, and fully explainable tools for the GM. This moves beyond simple database tagging to allow for nuanced, context-aware searching and dynamic content generation. For example, a GM will be able to ask, "Find me a cowardly, low-threat monster that uses traps and lives underground," and receive a ranked, explainable list of candidates.

2. The Bestiary: The First Implementation

The most immediate and powerful application is a "Geometric Bestiary."

2.1. The Knowledge Base (bestiary.json or monsters table)

First, we establish a knowledge base where each monster is defined by its coordinates along conceptual axes. This is the "A Priori Knowledge" from the iris_flower.py example.

Example Monster Entries:

code JSON




{

  "goblin": {
    "traits": {
      "is_humanoid": 1.0, "is_small": 0.8, "is_social": 0.9, "is_cowardly": 0.7,
      "uses_traps": 0.8, "lives_underground": 0.9, "threat_level": 0.2
    },
    "metadata": { "cr": "1/4", "ruleset": "D&D 5e" }
  },
  "lich": {
    "traits": {
      "is_undead": 1.0, "is_intelligent": 1.0, "uses_magic": 1.0, "is_solitary": 0.8,
      "is_scheming": 0.9, "is_immortal": 0.8, "lives_underground": 0.7, "threat_level": 0.9
    },
    "metadata": { "cr": "21", "ruleset": "D&D 5e" }
  },
  "owlbear": {
    "traits": {
      "is_magical_beast": 1.0, "is_predator": 1.0, "is_territorial": 0.9,
      "lives_in_forests": 0.9, "is_aggressive": 0.9, "is_solitary": 0.6, "threat_level": 0.4
    },
    "metadata": { "cr": "3", "ruleset": "D&D 5e" }
  }
}
  

2.2. The Conceptual Space

The "axes" of our space are the keys from the traits dictionaries. The engine will dynamically discover these, creating a space with dimensions like:
[is_humanoid, is_undead, is_magical_beast, is_intelligent, uses_magic, lives_underground, threat_level, ...]

2.3. The Tool: The "Bestiary Query Engine"

This is the user-facing implementation—the "Caller." It's a UI panel where the GM describes the creature they need.

User Workflow:

1. GM's Intent: The GM is stocking a dungeon level and thinks, "I need a weak, magical undead creature to guard this hallway."

2. UI Interaction: The GM uses a set of sliders or dropdowns in the UI labeled with the conceptual traits:

   • is_undead: 1.0

   • uses_magic: 0.7

   • threat_level: 0.3

3. Encoding: The UI creates an "observation vector" from these preferences.

4. Classification: The WhiteBoxClassifier (instantiated with the bestiary) runs classify() on this vector. It calculates the cosine similarity of the GM's request against every monster in the knowledge base.

5. Results: The UI displays a ranked list:

   1. Skeleton Mage (Similarity: 0.92)

   2. Ghoul (Similarity: 0.85)

   3. Specter (Similarity: 0.78)

6. Explainability: The GM clicks on "Explain" next to Ghoul. The system runs explain_classification(), showing:

   Explanation for GHOUL

   • is_undead: Strong Match (The interest: 1.0, Ghoul: 1.0)

   • threat_level: Good Match (The interest: 0.3, Ghoul: 0.3)

   • uses_magic: Weak Match (The interest: 0.7, Ghoul: 0.1) -> This is why it's ranked below Skeleton Mage.

3. Integration with Dynamic Dungeon Scaling

This is where the architecture becomes truly powerful. The Dungeon Instance Manager we designed previously becomes a programmatic user of the Bestiary Query Engine.

• The Blueprint says: "This room needs an encounter with role: 'guards', difficulty: 'APL-2', and tags: ['undead']."

• The Instance Manager:

  1. Calculates the target threat_level (e.g., 0.4) from APL-2.

  2. Constructs an observation vector: {'is_undead': 1.0, 'threat_level': 0.4, 'is_social': 0.8} (assuming guards are social).

  3. Calls the WhiteBoxClassifier.

  4. The classifier returns the best-fitting monster(s) from the bestiary.

  5. The Instance Manager populates the room with that monster.

This provides an explainable, consistent, and thematically coherent way to automatically stock a dungeon that scales to the party.

4. Broader Applications

This is not limited to monsters. The same WhiteBoxClassifier class can be instantiated with different knowledge bases to power other tools:

• Magic Item Catalog:

  • Axes: is_weapon, is_cursed, requires_attunement, has_fire_damage, is_utility.

  • Query: "Find me a utility item that isn't cursed and doesn't require attunement."

• Spellbook:

  • Axes: is_evocation, is_illusion, has_verbal_component, is_combat_spell, is_ritual.

  • Query: "Show me all non-combat illusion spells that can be cast as a ritual."

• Faction Aligner:

  • Axes: is_lawful, is_mercenary, is_secretive, is_religious, has_political_power.

  • Query: "Which of my world's factions is most similar to the Zhentarim?" (where "Zhentarim" is also a vector in the space).

5. Conclusion

This geometric model is the key to unlocking the next layer of intelligence in the Codex Engine. It provides a single, unified, and understandable framework for reasoning about the content of the world, not just its geography. By separating the Knowledge Base (the JSON/DB files) from the Logic Engine (the classifier), we create a system that is infinitely extensible, perfectly auditable, and puts the GM in complete creative control.