dndwright 0.2.0__py3-none-any.whl

dndwright/content/species.json

@@ -0,0 +1,111 @@
+{
+  "metadata": {
+    "source": "dndwright original homebrew",
+    "license": "Original content — not derived from any copyrighted RPG product.",
+    "note": "Sample starter content; generate more with dndwright.content.generate."
+  },
+  "species": [
+    {
+      "name": "Kryth-Vaal",
+      "mechanics": {
+        "size": "Medium",
+        "speed": 30,
+        "ability_bonuses": "+2 Strength, +1 Constitution",
+        "traits": [
+          "Crystalline carapace grants natural armor",
+          "Resonant hum creates minor sonic pulses",
+          "Photosynthetic skin heals in sunlight"
+        ]
+      },
+      "narrative": {
+        "description": "Living statues composed of sentient quartz and volcanic glass. They process solar energy into kinetic force.",
+        "flavor": "Born from the heat of the mantle, tempered by the light of the stars."
+      }
+    },
+    {
+      "name": "Orynthian",
+      "mechanics": {
+        "size": "Small",
+        "speed": 30,
+        "ability_bonuses": "+2 Dexterity, +1 Intelligence",
+        "traits": [
+          "Gliding membranes under outstretched arms",
+          "Multi-faceted eyes grant darkvision",
+          "Prehensile quill-tipped tail"
+        ]
+      },
+      "narrative": {
+        "description": "Avian-insectoid hybrids with slender frames and iridescent, hive-integrated consciousness. They excel at high-altitude navigation.",
+        "flavor": "The wind is not merely a path, but the language they speak."
+      }
+    },
+    {
+      "name": "Mire-Strider",
+      "mechanics": {
+        "size": "Medium",
+        "speed": 30,
+        "ability_bonuses": "flexible +2/+1",
+        "traits": [
+          "Amphibious dual-lung system",
+          "Mud-camo grants stealth in foliage",
+          "Enzymatic touch dissolves organic bonds"
+        ]
+      },
+      "narrative": {
+        "description": "Slime-skinned beings with symbiotic fungal colonies living within their porous outer layers. They act as the immune system of the wetlands.",
+        "flavor": "Where the water meets the rot, the Strider finds home."
+      }
+    },
+    {
+      "name": "Nebulite",
+      "mechanics": {
+        "size": "Medium",
+        "speed": 30,
+        "ability_bonuses": "+2 Charisma, +1 Wisdom",
+        "traits": [
+          "Incorporeal shimmer avoids opportunity attacks",
+          "Gravitational tether lifts small objects",
+          "Stellar glow illuminates dark spaces"
+        ]
+      },
+      "narrative": {
+        "description": "Sentient gas clouds contained within intricate, self-forged brass shells. They are chroniclers of cosmic anomalies.",
+        "flavor": "A flicker of starlight trapped in a cage of clockwork."
+      }
+    },
+    {
+      "name": "Thrum-Kin",
+      "mechanics": {
+        "size": "Small",
+        "speed": 30,
+        "ability_bonuses": "+2 Constitution, +1 Charisma",
+        "traits": [
+          "Vibration sense detects movement",
+          "Sonic scream creates minor concussions",
+          "Dense fur absorbs elemental impact"
+        ]
+      },
+      "narrative": {
+        "description": "Subterranean mammals that communicate through rhythmic drumming against cave walls. They possess deep empathy for the tremors of the earth.",
+        "flavor": "They hear the heartbeat of the world before it even begins to pulse."
+      }
+    },
+    {
+      "name": "Xylosian",
+      "mechanics": {
+        "size": "Medium",
+        "speed": 30,
+        "ability_bonuses": "+2 Intelligence, +1 Wisdom",
+        "traits": [
+          "Root-link telepathy with other Xylosians",
+          "Hardwood skin hardens when stationary",
+          "Chlorophyll stores allow for brief starvation"
+        ]
+      },
+      "narrative": {
+        "description": "Bipedal plant-folk whose blood is essentially concentrated sap. They spend decades in deep meditation to gain ancestral knowledge.",
+        "flavor": "Growth is slow, but the memory of the forest is eternal."
+      }
+    }
+  ]
+}

dndwright/ontology/__init__.py

@@ -0,0 +1,25 @@
+"""D&D component ontology — a graph schema for D&D building blocks.
+
+    from dndwright import load_ontology
+    onto = load_ontology()
+    onto.node_types["Class"].properties["hit_die"].type   # "string"
+    onto.edges_from("Character")                           # ["HAS_CLASS", ...]
+"""
+
+from .loader import (
+    EdgeTypeDef,
+    NodeTypeDef,
+    Ontology,
+    PropertyDef,
+    load_ontology,
+    parse_ontology,
+)
+
+__all__ = [
+    "load_ontology",
+    "parse_ontology",
+    "Ontology",
+    "NodeTypeDef",
+    "EdgeTypeDef",
+    "PropertyDef",
+]

dndwright/ontology/dnd.yaml

@@ -0,0 +1,141 @@
+# dndwright — D&D 5e (2024) component ontology
+#
+# A graph schema for the building blocks of a D&D character/world: the mechanical
+# component types (Class, Species, Spell, …) and how a Character connects to them.
+# Domain-neutral — a host app supplies the `Character` (and any narrative) nodes;
+# this schema describes the D&D components those nodes attach to.
+#
+# `mechanics` / `narrative` properties hold a JSON blob (rules data / flavour),
+# so a component can carry arbitrary structured detail without schema churn.
+#
+# Component facts derive from the D&D SRD 5.2 (CC-BY-4.0); see NOTICE.
+
+schema:
+  name: dnd
+  version: 1
+
+  node_types:
+
+    Class:
+      properties:
+        name: { type: string, required: true }
+        description: { type: string }
+        hit_die: { type: string, description: "Hit die, e.g. 'd8' (string so the 'd' prefix shows)." }
+        primary_ability: { type: string }
+        mechanics: { type: string, description: "JSON: progression, proficiencies, spellcasting, features." }
+        narrative: { type: string, description: "JSON: concept, role, flavour." }
+
+    Subclass:
+      properties:
+        name: { type: string, required: true }
+        class_name: { type: string, description: "Name of the parent Class." }
+        description: { type: string }
+        mechanics: { type: string }
+        narrative: { type: string }
+
+    Species:
+      properties:
+        name: { type: string, required: true }
+        description: { type: string }
+        size: { type: string }
+        speed: { type: int }
+        mechanics: { type: string, description: "JSON: traits, ability bonuses." }
+        narrative: { type: string }
+
+    Background:
+      properties:
+        name: { type: string, required: true }
+        description: { type: string }
+        mechanics: { type: string }
+        narrative: { type: string }
+
+    Feat:
+      properties:
+        name: { type: string, required: true }
+        description: { type: string }
+        prerequisite: { type: string }
+        mechanics: { type: string }
+
+    Spell:
+      properties:
+        name: { type: string, required: true }
+        level: { type: int }
+        school: { type: string }
+        description: { type: string }
+        mechanics: { type: string }
+        narrative: { type: string }
+
+    Equipment:
+      properties:
+        name: { type: string, required: true }
+        equipment_type: { type: string, description: "weapon | armor | gear | tool | …" }
+        rarity: { type: string }
+        description: { type: string }
+        mechanics: { type: string, description: "JSON: damage, properties, cost, weight." }
+        narrative: { type: string }
+
+    MagicItem:
+      properties:
+        name: { type: string, required: true }
+        category: { type: string, indexed: true, description: "Armor | Potion | Ring | Rod | Scroll | Staff | Wand | Weapon | Wondrous Item." }
+        rarity: { type: string, indexed: true, description: "common | uncommon | rare | very_rare | legendary | artifact." }
+        attunement_required: { type: bool, indexed: true }
+        type_line: { type: string, description: "Display type line, e.g. 'Wondrous Item, Rare (Requires Attunement)'." }
+        description: { type: string }
+        # True for reusable library templates; instances copy from them (see INSTANCE_OF).
+        is_library: { type: bool, indexed: true }
+
+    Creature:
+      properties:
+        name: { type: string, required: true }
+        creature_type: { type: string, description: "aberration | beast | dragon | fiend | undead | …" }
+        size: { type: string }
+        alignment: { type: string }
+        cr: { type: string, description: "Challenge rating as a string, e.g. '1/4', '8'." }
+        challenge_rating: { type: float, description: "Numeric CR for sorting/budgeting (1/4 -> 0.25)." }
+        ac: { type: int }
+        hp_max: { type: int }
+        speed_walk: { type: int }
+        # Full stat block as a JSON string (abilities, actions, traits, …).
+        stat_block: { type: string }
+        description: { type: string }
+        is_library: { type: bool, indexed: true }
+      embedding_field: description
+
+  edge_types:
+
+    # === A Character is built from components ===
+    HAS_CLASS:      { from: Character, to: Class }
+    HAS_SUBCLASS:   { from: Character, to: Subclass }
+    HAS_SPECIES:    { from: Character, to: Species }
+    HAS_BACKGROUND: { from: Character, to: Background }
+    HAS_FEAT:       { from: Character, to: Feat }
+    HAS_SPELL:      { from: Character, to: Spell }
+    HAS_EQUIPMENT:  { from: Character, to: Equipment }
+
+    SUBCLASS_OF:
+      from: [Subclass]
+      to: [Class]
+      description: "A Subclass specialises a Class."
+
+    # === Mechanical form of an entity ===
+    HAS_STAT_BLOCK:
+      from: [Character]
+      to: [MagicItem, Equipment, Creature]
+      properties:
+        is_overridden: { type: bool, description: "Instance values diverge from its INSTANCE_OF template." }
+      description: >
+        Bridge from an identity-bearing entity to its D&D mechanical form
+        (e.g. a named NPC -> a Creature stat block; a signature weapon -> a
+        MagicItem/Equipment). A host app may extend `from` with its own
+        narrative node types.
+
+    # === Library template / instance ===
+    INSTANCE_OF:
+      from: [MagicItem, Equipment, Creature]
+      to: [MagicItem, Equipment, Creature]
+      description: >
+        Links a campaign-scoped instance to a reusable library template
+        (target is_library=true, source is_library=false), same type only.
+        Instances copy template properties at creation; this edge is for
+        traceability / 'modified-from-template' diffing, not runtime fallback.

dndwright/ontology/loader.py

@@ -0,0 +1,104 @@
+"""Load and model the D&D component ontology (``dnd.yaml``).
+
+Parses the bundled graph schema into typed, queryable pydantic models: node types
+(with typed properties) and edge types (with normalised from/to endpoints). A host
+graph app can use this to validate or drive its own D&D component graph.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class PropertyDef(BaseModel):
+    """A node/edge property definition."""
+
+    type: str
+    required: bool = False
+    indexed: bool = False
+    description: str | None = None
+
+
+class NodeTypeDef(BaseModel):
+    """A node type: a named set of typed properties."""
+
+    properties: dict[str, PropertyDef] = Field(default_factory=dict)
+    embedding_field: str | None = None
+
+    def required_properties(self) -> list[str]:
+        return [name for name, p in self.properties.items() if p.required]
+
+
+class EdgeTypeDef(BaseModel):
+    """An edge type with normalised ``source``/``target`` node-type lists."""
+
+    source: list[str] = Field(default_factory=list)  # the schema's `from`
+    target: list[str] = Field(default_factory=list)  # the schema's `to`
+    properties: dict[str, PropertyDef] = Field(default_factory=dict)
+    description: str | None = None
+
+
+class Ontology(BaseModel):
+    """The parsed component ontology: node types + edge types."""
+
+    name: str
+    version: int
+    node_types: dict[str, NodeTypeDef] = Field(default_factory=dict)
+    edge_types: dict[str, EdgeTypeDef] = Field(default_factory=dict)
+
+    def edges_from(self, node_type: str) -> list[str]:
+        """Edge-type names that may originate at ``node_type``."""
+        return [n for n, e in self.edge_types.items() if node_type in e.source]
+
+    def edges_to(self, node_type: str) -> list[str]:
+        """Edge-type names that may point at ``node_type``."""
+        return [n for n, e in self.edge_types.items() if node_type in e.target]
+
+
+def _as_list(value: object) -> list[str]:
+    if value is None:
+        return []
+    return list(value) if isinstance(value, list) else [str(value)]
+
+
+def parse_ontology(raw: dict) -> Ontology:
+    """Build an :class:`Ontology` from a parsed schema mapping."""
+    schema = raw["schema"]
+    node_types = {
+        name: NodeTypeDef(**(nt or {}))
+        for name, nt in (schema.get("node_types") or {}).items()
+    }
+    edge_types: dict[str, EdgeTypeDef] = {}
+    for name, edge in (schema.get("edge_types") or {}).items():
+        edge = edge or {}
+        edge_types[name] = EdgeTypeDef(
+            source=_as_list(edge.get("from")),
+            target=_as_list(edge.get("to")),
+            properties={
+                p: PropertyDef(**(d or {})) for p, d in (edge.get("properties") or {}).items()
+            },
+            description=(str(edge.get("description")).strip() or None)
+            if edge.get("description")
+            else None,
+        )
+    return Ontology(
+        name=schema["name"],
+        version=schema["version"],
+        node_types=node_types,
+        edge_types=edge_types,
+    )
+
+
+def load_ontology(path: str | Path | None = None) -> Ontology:
+    """Load an ontology. With no ``path``, loads the bundled D&D ``dnd.yaml``."""
+    if path is None:
+        text = (importlib.resources.files("dndwright.ontology") / "dnd.yaml").read_text(
+            encoding="utf-8"
+        )
+    else:
+        text = Path(path).read_text(encoding="utf-8")
+    return parse_ontology(yaml.safe_load(text))

dndwright/rules/__init__.py

@@ -0,0 +1,35 @@
+"""Character sheet computation graph engine.
+
+Models D&D character sheets as a directed acyclic graph where nodes are values
+and edges are dependencies. Formulas are data (JSON-serializable DSL), not code.
+
+Usage:
+    from rules.dnd_5e_2024 import DND_5E_2024_RULESET
+    from rules.evaluator import evaluate
+    from rules.assembler import assemble_character_inputs, apply_modifiers
+    from rules.components import ClassMechanics, SpeciesMechanics, ...
+
+    inputs = assemble_character_inputs(
+        class_mechanics=class_mech,
+        species_mechanics=species_mech,
+        background_mechanics=bg_mech,
+        ability_scores={...},
+        level=5,
+    )
+    computed = evaluate(DND_5E_2024_RULESET, inputs)
+    computed = apply_modifiers(computed, inputs)
+"""
+
+from .assembler import apply_modifiers, assemble_character_inputs
+from .evaluator import evaluate
+from .schema import ComputationNode, FormulaSpec, NodeType, Ruleset
+
+__all__ = [
+    "ComputationNode",
+    "FormulaSpec",
+    "NodeType",
+    "Ruleset",
+    "apply_modifiers",
+    "assemble_character_inputs",
+    "evaluate",
+]