dndwright 0.2.0__py3-none-any.whl

dndwright/rules/operations.py

@@ -0,0 +1,412 @@
+"""Closed set of formula operations for the computation graph DSL.
+
+Every operation is a pure function: (args, lookup_tables) -> value.
+No eval(), no lambdas, no side effects. JSON-serializable operation names
+map to Python functions here (and will map to TypeScript functions in Phase 3).
+
+Operations fall into three categories:
+1. Arithmetic: add, sub, mul, floor_div, max_val, min_val
+2. D&D compound ops: ability_mod, prof_bonus, prof_add, hp_at_level, ac_with_armor
+3. Logic: if_then_else, eq, gt, gte, in_set, not_op
+4. Utility: lookup, format_mod, coalesce, const
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Arithmetic
+# ---------------------------------------------------------------------------
+
+
+def op_add(args: list[Any], _tables: dict) -> int | float:
+    """Sum all arguments."""
+    return sum(args)
+
+
+def op_sub(args: list[Any], _tables: dict) -> int | float:
+    """Subtract: args[0] - args[1] - args[2] - ..."""
+    result = args[0]
+    for a in args[1:]:
+        result -= a
+    return result
+
+
+def op_mul(args: list[Any], _tables: dict) -> int | float:
+    """Multiply all arguments."""
+    result = 1
+    for a in args:
+        result *= a
+    return result
+
+
+def op_floor_div(args: list[Any], _tables: dict) -> int:
+    """Integer division: args[0] // args[1]."""
+    return int(args[0]) // int(args[1])
+
+
+def op_max_val(args: list[Any], _tables: dict) -> int | float:
+    """Maximum of all arguments."""
+    return max(args)
+
+
+def op_min_val(args: list[Any], _tables: dict) -> int | float:
+    """Minimum of all arguments."""
+    return min(args)
+
+
+# ---------------------------------------------------------------------------
+# D&D compound operations
+# ---------------------------------------------------------------------------
+
+
+def op_ability_mod(args: list[Any], _tables: dict) -> int:
+    """(score - 10) // 2. Standard D&D ability modifier."""
+    score = int(args[0])
+    return (score - 10) // 2
+
+
+def op_prof_bonus(args: list[Any], _tables: dict) -> int:
+    """2 + ((level - 1) // 4). Proficiency bonus from character level."""
+    level = int(args[0])
+    return 2 + ((level - 1) // 4)
+
+
+def op_prof_add(args: list[Any], _tables: dict) -> int:
+    """ability_mod + (prof_bonus if proficient else 0).
+
+    args: [ability_mod, prof_bonus, is_proficient]
+    """
+    ability_mod = int(args[0])
+    prof_bonus = int(args[1])
+    is_proficient = bool(args[2])
+    return ability_mod + (prof_bonus if is_proficient else 0)
+
+
+def op_skill_bonus(args: list[Any], _tables: dict) -> int:
+    """ability_mod + (prof_bonus * 2 if expertise, prof_bonus if proficient, else 0).
+
+    args: [ability_mod, prof_bonus, is_proficient, has_expertise]
+    """
+    ability_mod = int(args[0])
+    prof_bonus = int(args[1])
+    is_proficient = bool(args[2])
+    has_expertise = bool(args[3])
+    if has_expertise:
+        return ability_mod + prof_bonus * 2
+    elif is_proficient:
+        return ability_mod + prof_bonus
+    return ability_mod
+
+
+def op_hp_at_level(args: list[Any], _tables: dict) -> int:
+    """HP = hit_die_max + con_mod + (level-1) * (avg_roll + con_mod), min level.
+
+    args: [hit_die_size, con_mod, level]
+    hit_die_size: integer (8 for d8, 10 for d10, etc.)
+    """
+    hit_die_size = int(args[0])
+    con_mod = int(args[1])
+    level = int(args[2])
+    avg_roll = (hit_die_size // 2) + 1
+    hp = hit_die_size + con_mod  # Level 1: max die + CON
+    hp += (level - 1) * (avg_roll + con_mod)  # Levels 2+: average
+    return max(hp, level)  # Minimum 1 HP per level
+
+
+def op_multiclass_hp(args: list[Any], _tables: dict) -> int:
+    """HP for multiclass character.
+
+    args: [class_levels_json, class_hit_dice_json, con_mod]
+    class_levels_json: dict like {"bard": 5, "warlock": 3}
+    class_hit_dice_json: dict like {"bard": 8, "warlock": 8}
+    con_mod: constitution modifier
+
+    First level of primary class (first in order) gets max die.
+    All subsequent levels get average.
+    """
+    class_levels = args[0]  # dict
+    class_hit_dice = args[1]  # dict
+    con_mod = int(args[2])
+
+    if not class_levels or not class_hit_dice:
+        return 1
+
+    total_hp = 0
+    first_class = True
+
+    for class_name, class_level in class_levels.items():
+        hit_die_size = class_hit_dice.get(class_name, 8)
+        avg_roll = (hit_die_size // 2) + 1
+
+        if first_class:
+            # First class, level 1: max die + CON
+            total_hp += hit_die_size + con_mod
+            # Remaining levels in first class: average
+            total_hp += (class_level - 1) * (avg_roll + con_mod)
+            first_class = False
+        else:
+            # All levels in secondary classes: average
+            total_hp += class_level * (avg_roll + con_mod)
+
+    character_level = sum(class_levels.values())
+    return max(total_hp, character_level)
+
+
+def op_ac_with_armor(args: list[Any], tables: dict) -> int:
+    """Compute AC from armor type + dex mod.
+
+    args: [armor_type, dex_mod, magic_bonus, has_shield]
+    Uses lookup tables: armor_base_ac, armor_max_dex
+    """
+    armor_type = str(args[0]).lower().replace(" ", "_") if args[0] else "none"
+    dex_mod = int(args[1])
+    magic_bonus = int(args[2]) if len(args) > 2 else 0
+    has_shield = bool(args[3]) if len(args) > 3 else False
+
+    armor_base_ac = tables.get("armor_base_ac", {})
+    armor_max_dex = tables.get("armor_max_dex", {})
+
+    base_ac = armor_base_ac.get(armor_type, 10)
+    max_dex = armor_max_dex.get(armor_type)
+
+    if max_dex == 0:  # Heavy armor
+        ac = base_ac
+    elif max_dex is not None:  # Medium armor
+        ac = base_ac + min(dex_mod, max_dex)
+    else:  # Light armor or unarmored
+        ac = base_ac + dex_mod
+
+    ac += magic_bonus
+    if has_shield:
+        ac += 2
+
+    return ac
+
+
+def op_spell_slots(args: list[Any], tables: dict) -> dict[str, int]:
+    """Look up spell slots from progression table.
+
+    args: [spellcasting_type, level, class_name]
+    Uses lookup tables: spell_slots_full, spell_slots_half, spell_slots_warlock
+    """
+    spellcasting_type = str(args[0]) if args[0] else "none"
+    level = int(args[1])
+    class_name = str(args[2]).lower() if len(args) > 2 and args[2] else ""
+
+    if class_name == "warlock":
+        table = tables.get("spell_slots_warlock", {})
+        return table.get(level, {})
+    elif spellcasting_type == "half_caster":
+        table = tables.get("spell_slots_half", {})
+        return table.get(level, {})
+    elif spellcasting_type in ("full_caster", "prepared_caster"):
+        table = tables.get("spell_slots_full", {})
+        return table.get(level, {})
+    return {}
+
+
+def op_multiclass_spell_slots(args: list[Any], tables: dict) -> dict[str, int]:
+    """Compute spell slots for multiclass characters.
+
+    Per D&D 5e multiclass rules: sum full caster levels + floor(half caster levels / 2),
+    look up on the full caster table. Warlock pact slots are separate.
+
+    args: [class_levels_json, class_spellcasting_types_json]
+    class_levels_json: {"wizard": 5, "fighter": 3}
+    class_spellcasting_types_json: {"wizard": "full_caster", "fighter": "none"}
+    """
+    class_levels = args[0]  # dict
+    class_types = args[1]  # dict
+
+    if not class_levels or not class_types:
+        return {}
+
+    # Calculate effective caster level
+    effective_caster_level = 0
+    warlock_level = 0
+    has_warlock = False
+
+    for class_name, level in class_levels.items():
+        casting_type = class_types.get(class_name, "none")
+        if class_name.lower() == "warlock":
+            warlock_level = level
+            has_warlock = True
+        elif casting_type in ("full_caster", "prepared_caster"):
+            effective_caster_level += level
+        elif casting_type == "half_caster":
+            effective_caster_level += level // 2
+
+    result = {}
+
+    # Standard spell slots from effective caster level
+    if effective_caster_level > 0:
+        full_table = tables.get("spell_slots_full", {})
+        result = dict(full_table.get(effective_caster_level, {}))
+
+    # Warlock pact slots are separate (added alongside)
+    if has_warlock and warlock_level > 0:
+        warlock_table = tables.get("spell_slots_warlock", {})
+        pact_info = warlock_table.get(warlock_level, {})
+        if pact_info:
+            result["pact"] = pact_info.get("pact", 0)
+            result["pact_level"] = pact_info.get("pact_level", 0)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Logic
+# ---------------------------------------------------------------------------
+
+
+def op_if_then_else(args: list[Any], _tables: dict) -> Any:
+    """args: [condition, true_value, false_value]."""
+    return args[1] if args[0] else args[2]
+
+
+def op_eq(args: list[Any], _tables: dict) -> bool:
+    """args[0] == args[1]."""
+    return args[0] == args[1]
+
+
+def op_gt(args: list[Any], _tables: dict) -> bool:
+    """args[0] > args[1]."""
+    return args[0] > args[1]
+
+
+def op_gte(args: list[Any], _tables: dict) -> bool:
+    """args[0] >= args[1]."""
+    return args[0] >= args[1]
+
+
+def op_in_set(args: list[Any], _tables: dict) -> bool:
+    """args[0] in args[1] (where args[1] is a list/set)."""
+    return args[0] in args[1]
+
+
+def op_not(args: list[Any], _tables: dict) -> bool:
+    """not args[0]."""
+    return not args[0]
+
+
+# ---------------------------------------------------------------------------
+# Utility
+# ---------------------------------------------------------------------------
+
+
+def op_lookup(args: list[Any], tables: dict) -> Any:
+    """Look up a value from a named table.
+
+    args: [table_name, key] or [table_name, key, default]
+    """
+    table_name = str(args[0])
+    key = args[1]
+    default = args[2] if len(args) > 2 else None
+    table = tables.get(table_name, {})
+    # Try direct lookup, then string version of key
+    result = table.get(key)
+    if result is None:
+        result = table.get(str(key))
+    if result is None:
+        result = default
+    return result
+
+
+def op_format_mod(args: list[Any], _tables: dict) -> str:
+    """Format an integer as a modifier string: +X or -X."""
+    val = int(args[0])
+    return f"+{val}" if val >= 0 else str(val)
+
+
+def op_coalesce(args: list[Any], _tables: dict) -> Any:
+    """Return first non-None argument."""
+    for a in args:
+        if a is not None:
+            return a
+    return None
+
+
+def op_const(args: list[Any], _tables: dict) -> Any:
+    """Return a constant value. args: [value]."""
+    return args[0]
+
+
+def op_passive_score(args: list[Any], _tables: dict) -> int:
+    """10 + skill_bonus. Standard passive score formula."""
+    return 10 + int(args[0])
+
+
+def op_spell_mod_resolve(args: list[Any], _tables: dict) -> int:
+    """Resolve spellcasting modifier from ability name + all 6 modifiers.
+
+    args: [spell_ability_name, str_mod, dex_mod, con_mod, int_mod, wis_mod, cha_mod]
+    spell_ability_name is e.g. "intelligence", "wisdom", "charisma"
+    """
+    ability_name = str(args[0]).lower() if args[0] else "charisma"
+    ability_order = ["strength", "dexterity", "constitution", "intelligence", "wisdom", "charisma"]
+    try:
+        idx = ability_order.index(ability_name)
+    except ValueError:
+        idx = 5  # default to charisma
+    return int(args[1 + idx])
+
+
+def op_hit_dice_str(args: list[Any], _tables: dict) -> str:
+    """Format hit dice as string: '5d8' or '5d8 + 3d10' for multiclass.
+
+    args: [class_levels_json, class_hit_dice_json]
+    """
+    class_levels = args[0]  # dict
+    class_hit_dice = args[1]  # dict
+
+    if not class_levels:
+        return "1d8"
+
+    parts = []
+    for class_name, class_level in class_levels.items():
+        die_size = class_hit_dice.get(class_name, 8)
+        parts.append(f"{class_level}d{die_size}")
+
+    return " + ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Operation registry
+# ---------------------------------------------------------------------------
+
+OPERATIONS: dict[str, callable] = {
+    # Arithmetic
+    "add": op_add,
+    "sub": op_sub,
+    "mul": op_mul,
+    "floor_div": op_floor_div,
+    "max_val": op_max_val,
+    "min_val": op_min_val,
+    # D&D compound
+    "ability_mod": op_ability_mod,
+    "prof_bonus": op_prof_bonus,
+    "prof_add": op_prof_add,
+    "skill_bonus": op_skill_bonus,
+    "hp_at_level": op_hp_at_level,
+    "multiclass_hp": op_multiclass_hp,
+    "ac_with_armor": op_ac_with_armor,
+    "spell_slots": op_spell_slots,
+    "multiclass_spell_slots": op_multiclass_spell_slots,
+    "hit_dice_str": op_hit_dice_str,
+    # Logic
+    "if_then_else": op_if_then_else,
+    "eq": op_eq,
+    "gt": op_gt,
+    "gte": op_gte,
+    "in_set": op_in_set,
+    "not": op_not,
+    # Utility
+    "lookup": op_lookup,
+    "format_mod": op_format_mod,
+    "coalesce": op_coalesce,
+    "const": op_const,
+    "passive_score": op_passive_score,
+    "spell_mod_resolve": op_spell_mod_resolve,
+}

dndwright/rules/schema.py

@@ -0,0 +1,69 @@
+"""Pydantic models for the computation graph schema."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class NodeType(str, Enum):
+    """Type of computation node."""
+
+    INPUT = "input"  # User-provided value (ability score, level, class)
+    FORMULA = "formula"  # Computed from other nodes via a formula
+    LOOKUP = "lookup"  # Value from a lookup table keyed by another node
+    AGGREGATE = "aggregate"  # Combines multiple nodes (e.g., sum of class HP contributions)
+    OUTPUT = "output"  # Terminal display node (formatted string, etc.)
+
+
+class FormulaSpec(BaseModel):
+    """A formula expressed as a named operation + arguments.
+
+    Safe, JSON-serializable, portable to TypeScript. Never eval().
+
+    Examples:
+        FormulaSpec(op="ability_mod", args=["str_score"])
+        FormulaSpec(op="add", args=["dex_mod", "proficiency_bonus"])
+        FormulaSpec(op="prof_add", args=["wis_mod", "proficiency_bonus", "save.wisdom.proficient"])
+        FormulaSpec(op="lookup", args=["armor_base_ac", "armor_type"])
+    """
+
+    op: str
+    args: list[Any] = Field(default_factory=list)
+
+
+class ComputationNode(BaseModel):
+    """A single node in the character sheet computation graph.
+
+    Each node represents one value on the character sheet. Nodes can depend
+    on other nodes via their formula args (which reference node IDs).
+    """
+
+    id: str  # Unique ID: "str_mod", "hp_max", "skill.perception"
+    node_type: NodeType
+    label: str  # Human-readable: "Strength Modifier"
+    layer: int = 0  # 0=input, 1=simple derived, 2=complex derived
+    group: str = ""  # "ability_scores", "combat", "skills", "spellcasting"
+    formula: FormulaSpec | None = None  # How to compute this node
+    inputs: list[str] = Field(default_factory=list)  # Explicit dependency list (node IDs)
+    default_value: Any = None
+    min_value: float | None = None  # Constraint: minimum allowed value
+    max_value: float | None = None  # Constraint: maximum allowed value
+    description: str = ""  # Rule citation, e.g., "PHB p.13"
+
+
+class Ruleset(BaseModel):
+    """A complete computation graph definition + lookup tables.
+
+    The D&D 5e 2024 ruleset is the built-in default. Custom rulesets
+    (Phase 4) will be stored in Neo4j.
+    """
+
+    id: str  # "dnd_5e_2024"
+    name: str  # "D&D 5th Edition (2024)"
+    version: str = "1.0.0"
+    nodes: dict[str, ComputationNode]  # Keyed by node ID
+    lookup_tables: dict[str, Any] = Field(default_factory=dict)  # Named tables
+    metadata: dict[str, Any] = Field(default_factory=dict)

dndwright/rules/theme_scaling.py

@@ -0,0 +1,207 @@
+"""Theme-specific scaling overrides for the computation graph.
+
+Allows themes (sci_fi, modern_warfare, steampunk, cosmic_horror, etc.) to override
+input node values and lookup table entries so the same computation graph produces
+mechanically appropriate results for any setting.
+
+Example: in a modern_warfare theme, "plate" armor becomes "tactical body armor"
+with the same mechanical AC 18, but weapon ranges and mount speeds change.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ThemeScalingLayer(BaseModel):
+    """Theme-specific overrides for computation graph input values."""
+
+    theme: str = Field(..., description="Theme identifier (e.g., 'modern_warfare', 'sci_fi')")
+    description: str = Field("", description="Human-readable description of the theme")
+    input_overrides: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Computation node ID -> override value. Applied before evaluation.",
+    )
+    lookup_overrides: dict[str, dict] = Field(
+        default_factory=dict,
+        description="Lookup table name -> {key: new_value}. Merged into ruleset tables.",
+    )
+    flavor_renames: dict[str, str] = Field(
+        default_factory=dict,
+        description="Original term -> themed term for display (e.g., 'plate' -> 'power armor').",
+    )
+    notes: list[str] = Field(
+        default_factory=list,
+        description="DM-facing notes about how the theme changes mechanics.",
+    )
+
+
+# =============================================================================
+# Predefined scaling profiles
+# =============================================================================
+
+PREDEFINED_THEME_SCALING: dict[str, ThemeScalingLayer] = {
+    "traditional_dnd": ThemeScalingLayer(
+        theme="traditional_dnd",
+        description="Standard D&D 5e rules. No mechanical overrides.",
+        input_overrides={},
+        lookup_overrides={},
+        flavor_renames={},
+        notes=["Default ruleset, no scaling applied."],
+    ),
+    "modern_warfare": ThemeScalingLayer(
+        theme="modern_warfare",
+        description="Modern military setting. Firearms, ballistic vests, vehicles.",
+        input_overrides={},
+        lookup_overrides={
+            "armor_base_ac": {
+                "leather": 11,
+                "studded_leather": 12,
+                "chain_shirt": 14,
+                "breastplate": 15,
+                "half_plate": 16,
+                "plate": 18,
+            },
+            "weapon_ranges": {
+                "shortbow": 300,
+                "longbow": 600,
+                "light_crossbow": 400,
+                "heavy_crossbow": 800,
+                "hand_crossbow": 200,
+            },
+        },
+        flavor_renames={
+            "plate": "tactical body armor",
+            "chain_mail": "flak jacket",
+            "breastplate": "kevlar vest",
+            "leather": "light ballistic vest",
+            "studded_leather": "reinforced ballistic vest",
+            "shield": "riot shield",
+            "longbow": "assault rifle",
+            "shortbow": "submachine gun",
+            "heavy_crossbow": "sniper rifle",
+            "light_crossbow": "carbine",
+            "hand_crossbow": "pistol",
+            "longsword": "combat knife",
+            "greatsword": "machete",
+            "mount_warhorse": "armored vehicle",
+            "mount_riding_horse": "jeep",
+        },
+        notes=[
+            "Firearms use crossbow/bow mechanics with extended ranges.",
+            "Armor retains AC values but is re-flavored as modern equipment.",
+            "Mounts become vehicles with equivalent movement.",
+            "Spellcasting can be re-flavored as tech gadgets or psionics.",
+        ],
+    ),
+    "sci_fi": ThemeScalingLayer(
+        theme="sci_fi",
+        description="Science fiction setting. Energy weapons, force shields, starships.",
+        input_overrides={},
+        lookup_overrides={
+            "armor_base_ac": {
+                "leather": 12,
+                "studded_leather": 13,
+                "chain_shirt": 14,
+                "breastplate": 15,
+                "half_plate": 16,
+                "plate": 19,
+            },
+        },
+        flavor_renames={
+            "plate": "power armor",
+            "chain_mail": "medium exosuit",
+            "breastplate": "light exosuit",
+            "leather": "enviro-suit",
+            "studded_leather": "reinforced enviro-suit",
+            "shield": "energy shield generator",
+            "longbow": "plasma rifle",
+            "shortbow": "laser carbine",
+            "heavy_crossbow": "rail gun",
+            "light_crossbow": "blaster pistol",
+            "longsword": "energy blade",
+            "greatsword": "plasma sword",
+            "mount_warhorse": "hoverbike",
+            "mount_riding_horse": "speeder",
+        },
+        notes=[
+            "Energy weapons use existing damage types (radiant for lasers, force for plasma).",
+            "Shields are energy-based but use the same +2 AC bonus.",
+            "Heavy armor is powered exosuits; no STR requirement change.",
+            "Starship combat uses a separate encounter framework.",
+        ],
+    ),
+    "steampunk": ThemeScalingLayer(
+        theme="steampunk",
+        description="Victorian-era clockwork and steam-powered technology.",
+        input_overrides={},
+        lookup_overrides={
+            "armor_base_ac": {
+                "chain_shirt": 14,
+                "breastplate": 15,
+                "plate": 19,
+            },
+        },
+        flavor_renames={
+            "plate": "clockwork full-plate",
+            "chain_mail": "riveted iron chassis",
+            "breastplate": "brass cuirass",
+            "leather": "oiled duster",
+            "studded_leather": "reinforced duster",
+            "shield": "pneumatic buckler",
+            "heavy_crossbow": "steam cannon",
+            "light_crossbow": "clockwork repeater",
+            "hand_crossbow": "derringer",
+            "longbow": "aether rifle",
+            "shortbow": "spring-bolt pistol",
+            "mount_warhorse": "steam walker",
+            "mount_riding_horse": "velocipede",
+        },
+        notes=[
+            "Clockwork mechanisms replace magic for non-spellcasters.",
+            "Steam-powered armor may overheat (DM discretion for flavor).",
+            "Alchemy replaces standard potion mechanics.",
+        ],
+    ),
+    "cosmic_horror": ThemeScalingLayer(
+        theme="cosmic_horror",
+        description="Lovecraftian horror. Sanity mechanics, reality distortion, eldritch entities.",
+        input_overrides={},
+        lookup_overrides={},
+        flavor_renames={
+            "plate": "warded armor",
+            "shield": "elder sign ward",
+            "longbow": "bolt-action rifle",
+            "shortbow": "revolver",
+            "heavy_crossbow": "elephant gun",
+            "greatsword": "ritual blade",
+        },
+        notes=[
+            "Optional sanity mechanic: WIS saves against cosmic horror (DC 12-20).",
+            "Failure costs 1d4 to 1d10 'Insight' (tracked separately from HP).",
+            "At 0 Insight, character gains a short-term madness.",
+            "Eldritch spells may require Insight instead of spell slots.",
+            "Reality distortion can impose disadvantage on perception checks.",
+        ],
+    ),
+}
+
+
+def get_theme_scaling(theme: str) -> ThemeScalingLayer | None:
+    """Get a predefined theme scaling layer, or None if not predefined."""
+    return PREDEFINED_THEME_SCALING.get(theme)
+
+
+def list_predefined_themes() -> list[dict]:
+    """Return summaries of all predefined theme scaling profiles."""
+    return [
+        {
+            "theme": layer.theme,
+            "description": layer.description,
+            "override_count": len(layer.input_overrides) + len(layer.lookup_overrides),
+            "rename_count": len(layer.flavor_renames),
+        }
+        for layer in PREDEFINED_THEME_SCALING.values()
+    ]