avrae-ls 0.4.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

avrae_ls/api.py

@@ -1,2014 +0,0 @@
-from __future__ import annotations
-
-import math
-from dataclasses import dataclass, field
-from typing import Any, ClassVar, Iterable, Mapping, MutableMapping, Optional, Sequence
-
-import d20
-
-from .dice import RerollableStringifier
-
-UNSET = object()
-
-
-def _safe_int(value: Any, default: int = 0) -> int:
-    try:
-        return int(value)
-    except Exception:
-        return default
-
-
-class _DirMixin:
-    ATTRS: ClassVar[list[str]] = []
-    METHODS: ClassVar[list[str]] = []
-
-    def __dir__(self) -> list[str]:
-        data_keys = list(getattr(self, "_data", {}).keys())
-        return sorted(set(self.ATTRS + self.METHODS + data_keys))
-
-    def __post_init__(self) -> None:
-        # Ensure draconic's approx_len cache is initialized to a numeric value
-        # so nested objects don't trip TypeErrors when measured.
-        if getattr(self, "__approx_len__", None) is None:
-            self.__approx_len__ = 0
-
-
-class SimpleRollResult(_DirMixin):
-    ATTRS: ClassVar[list[str]] = ["dice", "total", "full", "result", "raw"]
-    METHODS: ClassVar[list[str]] = ["consolidated"]
-
-    def __init__(self, roll_result: d20.RollResult):
-        self._roll = roll_result
-        self.dice = d20.MarkdownStringifier().stringify(roll_result.expr.roll)
-        self.total = roll_result.total
-        self.full = str(roll_result)
-        self.result = roll_result
-        self.raw = roll_result.expr
-        self.__approx_len__ = 0
-
-    def consolidated(self) -> str:
-        d20.utils.simplify_expr(self._roll.expr, ambig_inherit="left")
-        return RerollableStringifier().stringify(self._roll.expr.roll)
-
-    def __str__(self) -> str:
-        return self.full
-
-
-# === Context API ===
-@dataclass
-class GuildAPI(_DirMixin):
-    _data: Mapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["name", "id"]
-    METHODS: ClassVar[list[str]] = ["servsettings"]
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "Guild"))
-
-    @property
-    def id(self) -> int | None:
-        raw = self._data.get("id")
-        return int(raw) if raw is not None else None
-
-    def servsettings(self) -> Mapping[str, Any] | None:
-        return self._data.get("servsettings")
-
-    def __getitem__(self, item: str) -> Any:
-        if isinstance(item, int):
-            raise TypeError("CustomCounter indices must be strings (e.g., 'value', 'max').")
-        return getattr(self, str(item))
-
-    def __iter__(self):
-        return iter(())
-
-    def __len__(self) -> int:
-        return 0
-
-
-@dataclass
-class CategoryAPI(_DirMixin):
-    _data: Mapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["name", "id"]
-    METHODS: ClassVar[list[str]] = []
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "Category"))
-
-    @property
-    def id(self) -> int | None:
-        raw = self._data.get("id")
-        return int(raw) if raw is not None else None
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-@dataclass
-class ChannelAPI(_DirMixin):
-    _data: Mapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["name", "id", "topic", "category", "parent"]
-    METHODS: ClassVar[list[str]] = []
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "channel"))
-
-    @property
-    def id(self) -> int | None:
-        raw = self._data.get("id")
-        return int(raw) if raw is not None else None
-
-    @property
-    def topic(self) -> str | None:
-        val = self._data.get("topic")
-        return str(val) if val is not None else None
-
-    @property
-    def category(self) -> CategoryAPI | None:
-        cat = self._data.get("category")
-        return CategoryAPI(cat) if cat is not None else None
-
-    @property
-    def parent(self) -> ChannelAPI | None:
-        parent = self._data.get("parent")
-        return ChannelAPI(parent) if parent is not None else None
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-@dataclass
-class RoleAPI(_DirMixin):
-    _data: Mapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["name", "id"]
-    METHODS: ClassVar[list[str]] = []
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "Role"))
-
-    @property
-    def id(self) -> int | None:
-        raw = self._data.get("id")
-        return int(raw) if raw is not None else None
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-@dataclass
-class AuthorAPI(_DirMixin):
-    _data: Mapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["name", "id", "discriminator", "display_name", "roles"]
-    METHODS: ClassVar[list[str]] = ["get_roles"]
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "User"))
-
-    @property
-    def id(self) -> int | None:
-        raw = self._data.get("id")
-        return int(raw) if raw is not None else None
-
-    @property
-    def discriminator(self) -> str:
-        return str(self._data.get("discriminator", "0000"))
-
-    @property
-    def display_name(self) -> str:
-        return str(self._data.get("display_name", self.name))
-
-    def get_roles(self) -> list[RoleAPI]:
-        roles = self._data.get("roles") or []
-        return [RoleAPI(r) for r in roles]
-
-    @property
-    def roles(self) -> list[RoleAPI]:
-        return self.get_roles()
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-    def __str__(self) -> str:
-        return f"{self.name}#{self.discriminator}"
-
-
-@dataclass
-class AliasContextAPI(_DirMixin):
-    _data: Mapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["guild", "channel", "author", "prefix", "alias", "message_id"]
-    METHODS: ClassVar[list[str]] = []
-
-    @property
-    def guild(self) -> GuildAPI | None:
-        """Guild info for the alias invocation (server context)."""
-        guild_data = self._data.get("guild")
-        return GuildAPI(guild_data) if guild_data is not None else None
-
-    @property
-    def channel(self) -> ChannelAPI | None:
-        """Channel where the alias was invoked."""
-        channel_data = self._data.get("channel")
-        return ChannelAPI(channel_data) if channel_data is not None else None
-
-    @property
-    def author(self) -> AuthorAPI | None:
-        """User who invoked the alias."""
-        author_data = self._data.get("author")
-        return AuthorAPI(author_data) if author_data is not None else None
-
-    @property
-    def prefix(self) -> str | None:
-        """Command prefix that triggered the alias (e.g., `!`)."""
-        val = self._data.get("prefix")
-        return str(val) if val is not None else None
-
-    @property
-    def alias(self) -> str | None:
-        """Alias name that was run."""
-        val = self._data.get("alias")
-        return str(val) if val is not None else None
-
-    @property
-    def message_id(self) -> int | None:
-        """Discord message id for the invocation."""
-        raw = self._data.get("message_id")
-        return int(raw) if raw is not None else None
-
-    def __getattr__(self, item: str) -> Any:
-        return self._data.get(item)
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-# === StatBlock primitives ===
-_SKILL_CANONICAL = {
-    "acrobatics": "acrobatics",
-    "animalhandling": "animalHandling",
-    "arcana": "arcana",
-    "athletics": "athletics",
-    "deception": "deception",
-    "history": "history",
-    "initiative": "initiative",
-    "insight": "insight",
-    "intimidation": "intimidation",
-    "investigation": "investigation",
-    "medicine": "medicine",
-    "nature": "nature",
-    "perception": "perception",
-    "performance": "performance",
-    "persuasion": "persuasion",
-    "religion": "religion",
-    "sleightofhand": "sleightOfHand",
-    "sleight_of_hand": "sleightOfHand",
-    "stealth": "stealth",
-    "survival": "survival",
-    "strength": "strength",
-    "dexterity": "dexterity",
-    "constitution": "constitution",
-    "intelligence": "intelligence",
-    "wisdom": "wisdom",
-    "charisma": "charisma",
-}
-
-_SKILL_ABILITIES = {
-    "acrobatics": "dexterity",
-    "animalHandling": "wisdom",
-    "arcana": "intelligence",
-    "athletics": "strength",
-    "deception": "charisma",
-    "history": "intelligence",
-    "initiative": "dexterity",
-    "insight": "wisdom",
-    "intimidation": "charisma",
-    "investigation": "intelligence",
-    "medicine": "wisdom",
-    "nature": "intelligence",
-    "perception": "wisdom",
-    "performance": "charisma",
-    "persuasion": "charisma",
-    "religion": "intelligence",
-    "sleightOfHand": "dexterity",
-    "stealth": "dexterity",
-    "survival": "wisdom",
-    "strength": "strength",
-    "dexterity": "dexterity",
-    "constitution": "constitution",
-    "intelligence": "intelligence",
-    "wisdom": "wisdom",
-    "charisma": "charisma",
-}
-
-
-@dataclass
-class AliasBaseStats(_DirMixin):
-    _data: Mapping[str, Any]
-    prof_bonus_override: int | None = None
-    ATTRS: ClassVar[list[str]] = [
-        "prof_bonus",
-        "strength",
-        "dexterity",
-        "constitution",
-        "intelligence",
-        "wisdom",
-        "charisma",
-    ]
-    METHODS: ClassVar[list[str]] = ["get_mod", "get"]
-
-    @property
-    def prof_bonus(self) -> int:
-        if self.prof_bonus_override is not None:
-            return self.prof_bonus_override
-        return _safe_int(self._data.get("prof_bonus"), 2)
-
-    @property
-    def strength(self) -> int:
-        return _safe_int(self._data.get("strength"), 10)
-
-    @property
-    def dexterity(self) -> int:
-        return _safe_int(self._data.get("dexterity"), 10)
-
-    @property
-    def constitution(self) -> int:
-        return _safe_int(self._data.get("constitution"), 10)
-
-    @property
-    def intelligence(self) -> int:
-        return _safe_int(self._data.get("intelligence"), 10)
-
-    @property
-    def wisdom(self) -> int:
-        return _safe_int(self._data.get("wisdom"), 10)
-
-    @property
-    def charisma(self) -> int:
-        return _safe_int(self._data.get("charisma"), 10)
-
-    def get_mod(self, stat: str) -> int:
-        stat_lower = str(stat).lower()
-        lookup = {
-            "str": self.strength,
-            "dex": self.dexterity,
-            "con": self.constitution,
-            "int": self.intelligence,
-            "wis": self.wisdom,
-            "cha": self.charisma,
-            "strength": self.strength,
-            "dexterity": self.dexterity,
-            "constitution": self.constitution,
-            "intelligence": self.intelligence,
-            "wisdom": self.wisdom,
-            "charisma": self.charisma,
-        }
-        score = lookup.get(stat_lower, 10)
-        return math.floor((score - 10) / 2)
-
-    def get(self, stat: str) -> int:
-        stat_lower = str(stat).lower()
-        lookup = {
-            "strength": self.strength,
-            "dexterity": self.dexterity,
-            "constitution": self.constitution,
-            "intelligence": self.intelligence,
-            "wisdom": self.wisdom,
-            "charisma": self.charisma,
-        }
-        return lookup.get(stat_lower, 10)
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-@dataclass
-class AliasLevels(_DirMixin):
-    _data: Mapping[str, Any]
-    ATTRS: ClassVar[list[str]] = ["total_level"]
-    METHODS: ClassVar[list[str]] = ["get"]
-
-    @property
-    def total_level(self) -> int | float:
-        total = 0
-        for _, value in self._data.items():
-            try:
-                total += value
-            except Exception:
-                try:
-                    total += int(value)
-                except Exception:
-                    continue
-        return total
-
-    def get(self, cls_name: str, default: int | float = 0) -> int | float:
-        val = self._data.get(str(cls_name))
-        if val is None:
-            return default
-        try:
-            return val
-        except Exception:
-            return default
-
-    def __iter__(self) -> Iterable[tuple[str, Any]]:
-        return iter(self._data.items())
-
-    def __getitem__(self, item: str) -> Any:
-        return self._data[item]
-
-
-@dataclass
-class AliasAttack(_DirMixin):
-    _data: Mapping[str, Any]
-    parent_statblock: Mapping[str, Any]
-    ATTRS: ClassVar[list[str]] = ["name", "verb", "proper", "activation_type", "raw"]
-    METHODS: ClassVar[list[str]] = []
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "Attack"))
-
-    @property
-    def verb(self) -> str | None:
-        val = self._data.get("verb")
-        return str(val) if val is not None else None
-
-    @property
-    def proper(self) -> bool:
-        return bool(self._data.get("proper", False))
-
-    @property
-    def activation_type(self) -> int | None:
-        raw = self._data.get("activation_type")
-        return int(raw) if raw is not None else None
-
-    @property
-    def raw(self) -> Mapping[str, Any]:
-        return self._data.get("raw", self._data)
-
-    def __str__(self) -> str:
-        damage = self.raw.get("damage")
-        verb = f" {self.verb}" if self.verb else ""
-        if damage:
-            return f"{self.name}{verb}: {damage}"
-        return f"{self.name}{verb}".strip()
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-@dataclass
-class AliasAttackList(_DirMixin):
-    attacks: Sequence[Mapping[str, Any]]
-    parent_statblock: Mapping[str, Any]
-    ATTRS: ClassVar[list[str]] = []
-    METHODS: ClassVar[list[str]] = []
-
-    def __iter__(self) -> Iterable[AliasAttack]:
-        for atk in self.attacks:
-            yield AliasAttack(atk, self.parent_statblock)
-
-    def __getitem__(self, item: int | slice) -> Any:
-        if isinstance(item, slice):
-            return AliasAttackList(self.attacks[item], self.parent_statblock)
-        return AliasAttack(self.attacks[item], self.parent_statblock)
-
-    def __len__(self) -> int:
-        return len(self.attacks)
-
-    def __str__(self) -> str:
-        return "\n".join(str(AliasAttack(atk, self.parent_statblock)) for atk in self.attacks)
-
-
-@dataclass
-class AliasSkill(_DirMixin):
-    _data: Mapping[str, Any]
-    ATTRS: ClassVar[list[str]] = ["value", "prof", "bonus", "adv"]
-    METHODS: ClassVar[list[str]] = ["d20"]
-
-    @property
-    def value(self) -> int:
-        return _safe_int(self._data.get("value"), 0)
-
-    @property
-    def prof(self) -> float | int:
-        raw = self._data.get("prof")
-        try:
-            return float(raw)
-        except Exception:
-            return 0
-
-    @property
-    def bonus(self) -> int:
-        return _safe_int(self._data.get("bonus"), 0)
-
-    @property
-    def adv(self) -> bool | None:
-        val = self._data.get("adv")
-        if val is None:
-            return None
-        return bool(val)
-
-    def d20(self, base_adv=None, reroll=None, min_val=None, mod_override=None) -> str:
-        mod = mod_override if mod_override is not None else self.value
-        adv_prefix = "2d20kh1" if base_adv else "2d20kl1" if base_adv is False else "1d20"
-        suffix = f"+{mod}" if mod >= 0 else str(mod)
-        parts = [adv_prefix + suffix]
-        if reroll is not None:
-            parts.append(f"(reroll {reroll})")
-        if min_val is not None:
-            parts.append(f"(min {min_val})")
-        return " ".join(parts)
-
-    def __int__(self) -> int:
-        return self.value
-
-    def __repr__(self) -> str:
-        return f"<AliasSkill value={self.value} prof={self.prof} bonus={self.bonus} adv={self.adv}>"
-
-    def __gt__(self, other: Any) -> bool:
-        return self.value > other
-
-    def __ge__(self, other: Any) -> bool:
-        return self.value >= other
-
-    def __eq__(self, other: Any) -> bool:
-        return self.value == other
-
-    def __le__(self, other: Any) -> bool:
-        return self.value <= other
-
-    def __lt__(self, other: Any) -> bool:
-        return self.value < other
-
-
-@dataclass
-class AliasSkills(_DirMixin):
-    _data: Mapping[str, Any]
-    prof_bonus: int
-    abilities: Mapping[str, int]
-    ATTRS: ClassVar[list[str]] = list(_SKILL_ABILITIES.keys())
-    METHODS: ClassVar[list[str]] = []
-
-    def __getattr__(self, item: str) -> AliasSkill:
-        return self._get_skill(item)
-
-    def __getitem__(self, item: str) -> AliasSkill:
-        return self._get_skill(str(item))
-
-    def _get_skill(self, name: str) -> AliasSkill:
-        normalized = _SKILL_CANONICAL.get(name.lower().replace(" ", "").replace("_", ""), name)
-        skill_data = self._data.get(normalized) or self._data.get(name) or {}
-        if not skill_data:
-            ability = _SKILL_ABILITIES.get(normalized)
-            ability_mod = 0
-            if ability:
-                ability_score = self.abilities.get(ability, 10)
-                ability_mod = math.floor((ability_score - 10) / 2)
-            skill_data = {"value": ability_mod, "prof": 0, "bonus": 0, "adv": None}
-        return AliasSkill(skill_data)
-
-    def __iter__(self) -> Iterable[tuple[str, AliasSkill]]:
-        for name in _SKILL_ABILITIES.keys():
-            yield name, self._get_skill(name)
-
-    def __str__(self) -> str:
-        return ", ".join(f"{name}: {skill.value}" for name, skill in self)
-
-
-@dataclass
-class AliasSaves(_DirMixin):
-    _data: Mapping[str, Any]
-    prof_bonus: int
-    abilities: Mapping[str, int]
-    ATTRS: ClassVar[list[str]] = []
-    METHODS: ClassVar[list[str]] = ["get"]
-
-    def get(self, base_stat: str) -> AliasSkill:
-        normalized = base_stat.lower()
-        raw = self._data.get(normalized) or self._data.get(base_stat) or {}
-        if isinstance(raw, (int, float)):
-            raw = {"value": raw}
-        if not raw:
-            ability_score = self.abilities.get(normalized, 10)
-            raw = {"value": math.floor((ability_score - 10) / 2)}
-        return AliasSkill(raw)
-
-    def __iter__(self) -> Iterable[tuple[str, AliasSkill]]:
-        for key in ("str", "dex", "con", "int", "wis", "cha"):
-            yield key, self.get(key)
-
-    def __str__(self) -> str:
-        return ", ".join(f"{name}: {skill.value}" for name, skill in self)
-
-
-@dataclass
-class ResistanceEntry:
-    dtype: str
-    unless: set[str] = field(default_factory=set)
-    only: set[str] = field(default_factory=set)
-
-
-@dataclass
-class AliasResistances(_DirMixin):
-    _data: Mapping[str, Any]
-    ATTRS: ClassVar[list[str]] = ["resist", "vuln", "immune", "neutral"]
-    METHODS: ClassVar[list[str]] = ["is_resistant", "is_immune", "is_vulnerable", "is_neutral"]
-
-    @staticmethod
-    def _entries(key: str, _data: Mapping[str, Any]) -> list[ResistanceEntry]:
-        entries = []
-        for entry in _data.get(key, []):
-            entries.append(
-                ResistanceEntry(
-                    dtype=str(entry.get("dtype", "")),
-                    unless=set(entry.get("unless", []) or []),
-                    only=set(entry.get("only", []) or []),
-                )
-            )
-        return entries
-
-    @property
-    def resist(self) -> list[ResistanceEntry]:
-        return self._entries("resist", self._data)
-
-    @property
-    def vuln(self) -> list[ResistanceEntry]:
-        return self._entries("vuln", self._data)
-
-    @property
-    def immune(self) -> list[ResistanceEntry]:
-        return self._entries("immune", self._data)
-
-    @property
-    def neutral(self) -> list[ResistanceEntry]:
-        return self._entries("neutral", self._data)
-
-    def is_resistant(self, damage_type: str) -> bool:
-        token = str(damage_type).lower()
-        return self._matches(self.resist, token)
-
-    def is_immune(self, damage_type: str) -> bool:
-        token = str(damage_type).lower()
-        return self._matches(self.immune, token)
-
-    def is_vulnerable(self, damage_type: str) -> bool:
-        token = str(damage_type).lower()
-        return self._matches(self.vuln, token)
-
-    def is_neutral(self, damage_type: str) -> bool:
-        token = str(damage_type).lower()
-        return self._matches(self.neutral, token)
-
-    @staticmethod
-    def _matches(entries: Iterable[ResistanceEntry], token: str) -> bool:
-        for entry in entries:
-            if entry.only and token not in entry.only:
-                continue
-            if entry.unless and token in entry.unless:
-                continue
-            if entry.dtype.lower() == token:
-                return True
-        return False
-
-
-@dataclass
-class AliasSpellbookSpell(_DirMixin):
-    _data: Mapping[str, Any]
-    ATTRS: ClassVar[list[str]] = ["name", "dc", "sab", "mod", "prepared"]
-    METHODS: ClassVar[list[str]] = []
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "Spell"))
-
-    @property
-    def dc(self) -> int | None:
-        raw = self._data.get("dc")
-        return int(raw) if raw is not None else None
-
-    @property
-    def sab(self) -> int | None:
-        raw = self._data.get("sab")
-        return int(raw) if raw is not None else None
-
-    @property
-    def mod(self) -> int | None:
-        raw = self._data.get("mod")
-        return int(raw) if raw is not None else None
-
-    @property
-    def prepared(self) -> bool:
-        return bool(self._data.get("prepared", True))
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-    def __str__(self) -> str:
-        return self.name
-
-
-@dataclass
-class AliasSpellbook(_DirMixin):
-    _data: MutableMapping[str, Any]
-    _spells_cache: list[AliasSpellbookSpell] = field(default_factory=list, init=False)
-    ATTRS: ClassVar[list[str]] = [
-        "dc",
-        "sab",
-        "caster_level",
-        "spell_mod",
-        "spells",
-        "pact_slot_level",
-        "num_pact_slots",
-        "max_pact_slots",
-    ]
-    METHODS: ClassVar[list[str]] = [
-        "find",
-        "slots_str",
-        "get_max_slots",
-        "get_slots",
-        "set_slots",
-        "use_slot",
-        "reset_slots",
-        "reset_pact_slots",
-        "remaining_casts_of",
-        "cast",
-        "can_cast",
-    ]
-
-    @property
-    def dc(self) -> int:
-        return _safe_int(self._data.get("dc"), 10)
-
-    @property
-    def sab(self) -> int:
-        return _safe_int(self._data.get("sab"), 0)
-
-    @property
-    def caster_level(self) -> int:
-        return _safe_int(self._data.get("caster_level"), 0)
-
-    @property
-    def spell_mod(self) -> int:
-        return _safe_int(self._data.get("spell_mod"), 0)
-
-    @property
-    def spells(self) -> list[AliasSpellbookSpell]:
-        if not self._spells_cache:
-            spell_list = self._data.get("spells") or []
-            self._spells_cache = [AliasSpellbookSpell(s) for s in spell_list]
-        return self._spells_cache
-
-    @property
-    def pact_slot_level(self) -> int | None:
-        raw = self._data.get("pact_slot_level")
-        return int(raw) if raw is not None else None
-
-    @property
-    def num_pact_slots(self) -> int | None:
-        raw = self._data.get("num_pact_slots")
-        return int(raw) if raw is not None else None
-
-    @property
-    def max_pact_slots(self) -> int | None:
-        raw = self._data.get("max_pact_slots")
-        return int(raw) if raw is not None else None
-
-    def find(self, spell_name: str) -> list[AliasSpellbookSpell]:
-        needle = str(spell_name).lower()
-        return [spell for spell in self.spells if spell.name.lower() == needle]
-
-    def slots_str(self, level: int) -> str:
-        slots = self.get_slots(level)
-        max_slots = self.get_max_slots(level)
-        return f"{slots}/{max_slots}"
-
-    def get_max_slots(self, level: int) -> int:
-        slots = self._data.get("max_slots") or {}
-        return _safe_int(slots.get(int(level)), 0)
-
-    def get_slots(self, level: int) -> int:
-        slots = self._data.get("slots") or {}
-        if int(level) == 0:
-            return 1
-        return _safe_int(slots.get(int(level)), 0)
-
-    def set_slots(self, level: int, value: int, pact: bool = True) -> int:
-        slots = self._data.setdefault("slots", {})
-        slots[int(level)] = int(value)
-        return slots[int(level)]
-
-    def use_slot(self, level: int) -> int:
-        current = self.get_slots(level)
-        return self.set_slots(level, max(0, current - 1))
-
-    def reset_slots(self) -> None:
-        slots = self._data.get("slots") or {}
-        max_slots = self._data.get("max_slots") or {}
-        for level, maximum in max_slots.items():
-            slots[int(level)] = _safe_int(maximum)
-        self._data["slots"] = slots
-
-    def reset_pact_slots(self) -> None:
-        if self.max_pact_slots is None:
-            return
-        self._data["num_pact_slots"] = self.max_pact_slots
-
-    def remaining_casts_of(self, spell: str, level: int) -> str:
-        return self.slots_str(level)
-
-    def cast(self, spell: str, level: int) -> str:
-        self.use_slot(level)
-        return f"Casted {spell} at level {level}"
-
-    def can_cast(self, spell: str, level: int) -> bool:
-        return self.get_slots(level) > 0
-
-    def __contains__(self, item: object) -> bool:
-        if not isinstance(item, str):
-            return False
-        return any(spell.name.lower() == item.lower() for spell in self.spells)
-
-
-@dataclass
-class AliasCoinpurse(_DirMixin):
-    _data: MutableMapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["pp", "gp", "ep", "sp", "cp", "total"]
-    METHODS: ClassVar[list[str]] = ["coin_str", "compact_str", "modify_coins", "set_coins", "autoconvert", "get_coins"]
-
-    def __getattr__(self, item: str) -> Any:
-        if item in {"pp", "gp", "ep", "sp", "cp"}:
-            return _safe_int(self._data.get(item), 0)
-        return self._data.get(item)
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-    @property
-    def total(self) -> float:
-        return self.pp * 10 + self.gp + self.ep * 0.5 + self.sp * 0.1 + self.cp * 0.01
-
-    def coin_str(self, cointype: str) -> str:
-        cointype = str(cointype)
-        value = getattr(self, cointype)
-        return f"{value} {cointype}"
-
-    def compact_str(self) -> str:
-        return f"{self.total:.2f} gp"
-
-    def modify_coins(
-        self,
-        pp: int = 0,
-        gp: int = 0,
-        ep: int = 0,
-        sp: int = 0,
-        cp: int = 0,
-        autoconvert: bool = True,
-    ) -> dict[str, Any]:
-        self._data["pp"] = self.pp + int(pp)
-        self._data["gp"] = self.gp + int(gp)
-        self._data["ep"] = self.ep + int(ep)
-        self._data["sp"] = self.sp + int(sp)
-        self._data["cp"] = self.cp + int(cp)
-        return self.get_coins()
-
-    def set_coins(self, pp: int, gp: int, ep: int, sp: int, cp: int) -> None:
-        self._data["pp"] = int(pp)
-        self._data["gp"] = int(gp)
-        self._data["ep"] = int(ep)
-        self._data["sp"] = int(sp)
-        self._data["cp"] = int(cp)
-
-    def autoconvert(self) -> None:
-        total_cp = int(self.total * 100)
-        self._data["pp"], remainder = divmod(total_cp, 1000)
-        self._data["gp"], remainder = divmod(remainder, 100)
-        self._data["ep"], remainder = divmod(remainder, 50)
-        self._data["sp"], self._data["cp"] = divmod(remainder, 10)
-
-    def get_coins(self) -> dict[str, Any]:
-        return {"pp": self.pp, "gp": self.gp, "ep": self.ep, "sp": self.sp, "cp": self.cp, "total": self.total}
-
-
-@dataclass
-class AliasDeathSaves(_DirMixin):
-    _data: MutableMapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["successes", "fails"]
-    METHODS: ClassVar[list[str]] = ["succeed", "fail", "is_stable", "is_dead", "reset"]
-
-    @property
-    def successes(self) -> int:
-        return _safe_int(self._data.get("successes"), 0)
-
-    @property
-    def fails(self) -> int:
-        return _safe_int(self._data.get("fails"), 0)
-
-    def succeed(self, num: int = 1) -> None:
-        self._data["successes"] = self.successes + int(num)
-
-    def fail(self, num: int = 1) -> None:
-        self._data["fails"] = self.fails + int(num)
-
-    def is_stable(self) -> bool:
-        return self.successes >= 3 and self.fails < 3
-
-    def is_dead(self) -> bool:
-        return self.fails >= 3
-
-    def reset(self) -> None:
-        self._data["successes"] = 0
-        self._data["fails"] = 0
-
-    def __str__(self) -> str:
-        return f"{self.successes} successes / {self.fails} failures"
-
-
-@dataclass
-class AliasAction(_DirMixin):
-    _data: Mapping[str, Any]
-    parent_statblock: Mapping[str, Any]
-    ATTRS: ClassVar[list[str]] = ["name", "activation_type", "activation_type_name", "description", "snippet"]
-    METHODS: ClassVar[list[str]] = []
-
-    @property
-    def name(self) -> str:
-        """Action name."""
-        return str(self._data.get("name", "Action"))
-
-    @property
-    def activation_type(self) -> int | None:
-        """Numeric activation type (matches Avrae constants)."""
-        raw = self._data.get("activation_type")
-        return int(raw) if raw is not None else None
-
-    @property
-    def activation_type_name(self) -> str | None:
-        """Human-readable activation type (e.g., ACTION, BONUS_ACTION)."""
-        val = self._data.get("activation_type_name")
-        return str(val) if val is not None else None
-
-    @property
-    def description(self) -> str:
-        """Long description of the action."""
-        return str(self._data.get("description", ""))
-
-    @property
-    def snippet(self) -> str:
-        """Short snippet shown in the sheet for the action."""
-        return str(self._data.get("snippet", self.description))
-
-    def __str__(self) -> str:
-        return f"**{self.name}**: {self.description}"
-
-    def __getitem__(self, item: str) -> Any:
-        if isinstance(item, int) or (isinstance(item, str) and item.isdigit()):
-            raise TypeError("AliasAction attributes must be accessed by name (e.g., 'name', 'activation_type').")
-        return getattr(self, str(item))
-
-    def __iter__(self):
-        return iter(())
-
-    def __len__(self) -> int:
-        return 0
-
-
-@dataclass
-class AliasCustomCounter(_DirMixin):
-    _data: MutableMapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = [
-        "name",
-        "title",
-        "desc",
-        "value",
-        "max",
-        "min",
-        "reset_on",
-        "display_type",
-        "reset_to",
-        "reset_by",
-    ]
-    METHODS: ClassVar[list[str]] = ["mod", "set", "reset", "full_str"]
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "Counter"))
-
-    @property
-    def title(self) -> str | None:
-        val = self._data.get("title")
-        return str(val) if val is not None else None
-
-    @property
-    def desc(self) -> str | None:
-        val = self._data.get("desc")
-        return str(val) if val is not None else None
-
-    @property
-    def value(self) -> int:
-        return _safe_int(self._data.get("value"), 0)
-
-    @property
-    def max(self) -> int:
-        return _safe_int(self._data.get("max"), 2**31 - 1)
-
-    @property
-    def min(self) -> int:
-        return _safe_int(self._data.get("min"), -(2**31))
-
-    @property
-    def reset_on(self) -> str | None:
-        val = self._data.get("reset_on")
-        return str(val) if val is not None else None
-
-    @property
-    def display_type(self) -> str | None:
-        val = self._data.get("display_type")
-        return str(val) if val is not None else None
-
-    @property
-    def reset_to(self) -> int | None:
-        raw = self._data.get("reset_to")
-        return int(raw) if raw is not None else None
-
-    @property
-    def reset_by(self) -> str | None:
-        val = self._data.get("reset_by")
-        return str(val) if val is not None else None
-
-    def mod(self, value: int, strict: bool = False) -> int:
-        return self.set(self.value + int(value), strict)
-
-    def set(self, new_value: int, strict: bool = False) -> int:
-        val = int(new_value)
-        if strict:
-            if val > self.max or val < self.min:
-                raise ValueError("Counter out of bounds")
-        val = max(self.min, min(val, self.max))
-        self._data["value"] = val
-        return val
-
-    def reset(self) -> dict[str, Any]:
-        if self.reset_to is not None:
-            target = self.reset_to
-        elif self.reset_by is not None:
-            target = self.value + _safe_int(self.reset_by, 0)
-        else:
-            target = self.max
-        old_value = self.value
-        new_value = self.set(target)
-        return {"new_value": new_value, "old_value": old_value, "target_value": target, "delta": new_value - old_value}
-
-    def full_str(self, include_name: bool = False) -> str:
-        prefix = f"**{self.name}**\n" if include_name else ""
-        content = f"{self.value}/{self.max}"
-        if self.display_type:
-            content = self.display_type
-        return prefix + content
-
-    def __str__(self) -> str:
-        return f"{self.value}/{self.max}"
-
-    def __getitem__(self, item: str) -> Any:
-        if isinstance(item, int) or (isinstance(item, str) and item.isdigit()):
-            raise TypeError("CustomCounter indices must be strings (e.g., 'value', 'max').")
-        return getattr(self, str(item))
-
-    def __iter__(self):
-        return iter(())
-
-    def __len__(self) -> int:
-        return 0
-
-
-# === StatBlock + Character ===
-@dataclass
-class AliasStatBlock(_DirMixin):
-    _data: MutableMapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = [
-        "name",
-        "stats",
-        "levels",
-        "attacks",
-        "skills",
-        "saves",
-        "resistances",
-        "ac",
-        "max_hp",
-        "hp",
-        "temp_hp",
-        "spellbook",
-        "creature_type",
-    ]
-    METHODS: ClassVar[list[str]] = ["set_hp", "modify_hp", "hp_str", "reset_hp", "set_temp_hp"]
-
-    def _prof_bonus(self) -> int:
-        stats = self._data.get("stats") or {}
-        if "prof_bonus" in stats:
-            return _safe_int(stats.get("prof_bonus"), 2)
-        levels = self._data.get("levels") or self._data.get("class_levels") or {}
-        total_level = sum(_safe_int(val, 0) for val in levels.values()) or 1
-        return max(2, 2 + (math.ceil(total_level / 4)))
-
-    @property
-    def name(self) -> str:
-        """Character or statblock name."""
-        return str(self._data.get("name", "Statblock"))
-
-    @property
-    def stats(self) -> AliasBaseStats:
-        """Ability scores and proficiency bonus helper."""
-        return AliasBaseStats(self._data.get("stats") or {}, prof_bonus_override=self._prof_bonus())
-
-    @property
-    def levels(self) -> AliasLevels:
-        """Class levels keyed by class name."""
-        return AliasLevels(self._data.get("levels") or self._data.get("class_levels") or {})
-
-    @property
-    def attacks(self) -> AliasAttackList:
-        """Attacks available on the statblock."""
-        return AliasAttackList(self._data.get("attacks") or [], self._data)
-
-    @property
-    def skills(self) -> AliasSkills:
-        """Skill bonuses computed from abilities and prof bonus."""
-        abilities = {
-            "strength": self.stats.strength,
-            "dexterity": self.stats.dexterity,
-            "constitution": self.stats.constitution,
-            "intelligence": self.stats.intelligence,
-            "wisdom": self.stats.wisdom,
-            "charisma": self.stats.charisma,
-        }
-        return AliasSkills(self._data.get("skills") or {}, self._prof_bonus(), abilities)
-
-    @property
-    def saves(self) -> AliasSaves:
-        """Saving throw bonuses computed from abilities and prof bonus."""
-        abilities = {
-            "strength": self.stats.strength,
-            "dexterity": self.stats.dexterity,
-            "constitution": self.stats.constitution,
-            "intelligence": self.stats.intelligence,
-            "wisdom": self.stats.wisdom,
-            "charisma": self.stats.charisma,
-            "str": self.stats.strength,
-            "dex": self.stats.dexterity,
-            "con": self.stats.constitution,
-            "int": self.stats.intelligence,
-            "wis": self.stats.wisdom,
-            "cha": self.stats.charisma,
-        }
-        return AliasSaves(self._data.get("saves") or {}, self._prof_bonus(), abilities)
-
-    @property
-    def resistances(self) -> AliasResistances:
-        """Damage resistances, immunities, and vulnerabilities."""
-        return AliasResistances(self._data.get("resistances") or {})
-
-    @property
-    def ac(self) -> int | None:
-        """Armor class."""
-        raw = self._data.get("ac")
-        return int(raw) if raw is not None else None
-
-    @property
-    def max_hp(self) -> int | None:
-        """Maximum hit points."""
-        raw = self._data.get("max_hp")
-        return int(raw) if raw is not None else None
-
-    @property
-    def hp(self) -> int | None:
-        """Current hit points."""
-        raw = self._data.get("hp")
-        return int(raw) if raw is not None else None
-
-    @property
-    def temp_hp(self) -> int:
-        """Temporary hit points."""
-        return _safe_int(self._data.get("temp_hp"), 0)
-
-    @property
-    def spellbook(self) -> AliasSpellbook:
-        """Known/prepared spells grouped by level."""
-        return AliasSpellbook(self._data.get("spellbook") or {})
-
-    @property
-    def creature_type(self) -> str | None:
-        """Creature type (e.g., humanoid, undead)."""
-        val = self._data.get("creature_type")
-        return str(val) if val is not None else None
-
-    def set_hp(self, new_hp: int) -> int:
-        """Set current hit points."""
-        self._data["hp"] = int(new_hp)
-        return self._data["hp"]
-
-    def modify_hp(self, amount: int, ignore_temp: bool = False, overflow: bool = True) -> int:
-        """Adjust hit points by `amount`, respecting overflow limits when requested."""
-        hp = self.hp or 0
-        new_hp = hp + int(amount)
-        if not overflow and self.max_hp is not None:
-            new_hp = max(0, min(new_hp, self.max_hp))
-        self._data["hp"] = new_hp
-        return new_hp
-
-    def hp_str(self) -> str:
-        """String summary of HP and temp HP."""
-        return f"{self.hp}/{self.max_hp} (+{self.temp_hp} temp)"
-
-    def reset_hp(self) -> int:
-        """Restore to max HP and clear temp HP."""
-        if self.max_hp is not None:
-            self._data["hp"] = self.max_hp
-        self._data["temp_hp"] = 0
-        return self.hp or 0
-
-    def set_temp_hp(self, new_temp: int) -> int:
-        """Set temporary hit points."""
-        self._data["temp_hp"] = int(new_temp)
-        return self.temp_hp
-
-    def __getattr__(self, item: str) -> Any:
-        return self._data.get(item)
-
-    def __getitem__(self, item: str) -> Any:
-        if isinstance(item, int) or (isinstance(item, str) and item.isdigit()):
-            raise TypeError("AliasStatBlock attributes must be accessed by name (e.g., 'name', 'stats').")
-        return getattr(self, str(item))
-
-    def __iter__(self):
-        return iter(())
-
-    def __len__(self) -> int:
-        return 0
-
-
-@dataclass
-class CharacterAPI(AliasStatBlock):
-    ATTRS: ClassVar[list[str]] = AliasStatBlock.ATTRS + [
-        "actions",
-        "coinpurse",
-        "csettings",
-        "race",
-        "background",
-        "owner",
-        "upstream",
-        "sheet_type",
-        "cvars",
-        "consumables",
-        "death_saves",
-        "description",
-        "image",
-    ]
-    METHODS: ClassVar[list[str]] = AliasStatBlock.METHODS + [
-        "cc",
-        "get_cc",
-        "get_cc_max",
-        "get_cc_min",
-        "set_cc",
-        "mod_cc",
-        "delete_cc",
-        "create_cc_nx",
-        "create_cc",
-        "edit_cc",
-        "cc_exists",
-        "cc_str",
-        "get_cvar",
-        "set_cvar",
-        "set_cvar_nx",
-        "delete_cvar",
-    ]
-
-    def _consumable_map(self) -> MutableMapping[str, MutableMapping[str, Any]]:
-        consumables = self._data.setdefault("consumables", {})
-        if isinstance(consumables, list):
-            # normalize list payloads to map
-            mapped: dict[str, MutableMapping[str, Any]] = {}
-            for item in consumables:
-                name = str(item.get("name", f"cc_{len(mapped)}"))
-                mapped[name] = dict(item)
-            self._data["consumables"] = mapped
-            consumables = mapped
-        return consumables  # type: ignore[return-value]
-
-    @property
-    def actions(self) -> list[AliasAction]:
-        """Actions on the character sheet (mapped from Beyond/custom actions)."""
-        acts = self._data.get("actions") or []
-        return [AliasAction(a, self._data) for a in acts]
-
-    @property
-    def coinpurse(self) -> AliasCoinpurse:
-        """Coin totals by denomination."""
-        return AliasCoinpurse(self._data.get("coinpurse") or {})
-
-    @property
-    def csettings(self) -> Mapping[str, Any]:
-        """Character settings blob."""
-        return self._data.get("csettings", {})
-
-    @property
-    def race(self) -> str | None:
-        """Race label."""
-        val = self._data.get("race")
-        return str(val) if val is not None else None
-
-    @property
-    def background(self) -> str | None:
-        """Background name."""
-        val = self._data.get("background")
-        return str(val) if val is not None else None
-
-    @property
-    def owner(self) -> int | None:
-        """Discord user id of the owning account."""
-        raw = self._data.get("owner")
-        return int(raw) if raw is not None else None
-
-    @property
-    def upstream(self) -> str | None:
-        """Upstream character id (e.g., Beyond character slug)."""
-        val = self._data.get("upstream")
-        return str(val) if val is not None else None
-
-    @property
-    def sheet_type(self) -> str | None:
-        """Source sheet provider (beyond, custom, etc.)."""
-        val = self._data.get("sheet_type")
-        return str(val) if val is not None else None
-
-    @property
-    def cvars(self) -> Mapping[str, Any]:
-        """Character variables (string values)."""
-        return dict(self._data.get("cvars") or {})
-
-    def get_cvar(self, name: str, default: Any = None) -> Optional[str]:
-        """Fetch a character variable, returning `default` if missing."""
-        val = self._data.setdefault("cvars", {}).get(str(name), default)
-        return str(val) if val is not None else default
-
-    def set_cvar(self, name: str, val: str) -> Optional[str]:
-        """Sets a character variable. Avrae stores cvars as strings."""
-        str_val = str(val) if val is not None else None
-        self._data.setdefault("cvars", {})[str(name)] = str_val
-        return str_val
-
-    def set_cvar_nx(self, name: str, val: str) -> str:
-        """Set a character variable only if it does not already exist."""
-        cvars = self._data.setdefault("cvars", {})
-        str_val = str(val) if val is not None else None
-        return cvars.setdefault(str(name), str_val)
-
-    def delete_cvar(self, name: str) -> Optional[str]:
-        """Delete a character variable and return its old value if present."""
-        return self._data.setdefault("cvars", {}).pop(str(name), None)
-
-    @property
-    def consumables(self) -> list[AliasCustomCounter]:
-        """Custom counters/consumables on the character."""
-        return [AliasCustomCounter(v) for v in self._consumable_map().values()]
-
-    def cc(self, name: str) -> AliasCustomCounter:
-        """Get (or create placeholder for) a custom counter by name."""
-        return AliasCustomCounter(self._consumable_map()[str(name)])
-
-    def get_cc(self, name: str) -> int:
-        """Current value of a custom counter."""
-        return self.cc(name).value
-
-    def get_cc_max(self, name: str) -> int:
-        """Maximum value for a custom counter."""
-        return self.cc(name).max
-
-    def get_cc_min(self, name: str) -> int:
-        """Minimum value for a custom counter."""
-        return self.cc(name).min
-
-    def set_cc(self, name: str, value: int | None = None, maximum: int | None = None, minimum: int | None = None) -> int:
-        """Set value/max/min for a custom counter."""
-        con = self._consumable_map().setdefault(str(name), {"name": str(name)})
-        if value is not None:
-            con["value"] = int(value)
-        if maximum is not None:
-            con["max"] = int(maximum)
-        if minimum is not None:
-            con["min"] = int(minimum)
-        return _safe_int(con.get("value"), 0)
-
-    def mod_cc(self, name: str, val: int, strict: bool = False) -> int:
-        """Modify a custom counter by `val` (optionally enforcing bounds)."""
-        counter = self.cc(name)
-        return counter.mod(val, strict)
-
-    def delete_cc(self, name: str) -> Any:
-        """Remove a custom counter and return its payload."""
-        return self._consumable_map().pop(str(name), None)
-
-    def create_cc_nx(
-        self,
-        name: str,
-        minVal: str | None = None,
-        maxVal: str | None = None,
-        reset: str | None = None,
-        dispType: str | None = None,
-        reset_to: str | None = None,
-        reset_by: str | None = None,
-        title: str | None = None,
-        desc: str | None = None,
-        initial_value: str | None = None,
-    ) -> AliasCustomCounter:
-        """Create a custom counter if missing, preserving existing ones."""
-        if not self.cc_exists(name):
-            self.create_cc(
-                name,
-                minVal=minVal,
-                maxVal=maxVal,
-                reset=reset,
-                dispType=dispType,
-                reset_to=reset_to,
-                reset_by=reset_by,
-                title=title,
-                desc=desc,
-                initial_value=initial_value,
-            )
-        return self.cc(name)
-
-    def create_cc(
-        self,
-        name: str,
-        minVal: str | None = None,
-        maxVal: str | None = None,
-        reset: str | None = None,
-        dispType: str | None = None,
-        reset_to: str | None = None,
-        reset_by: str | None = None,
-        title: str | None = None,
-        desc: str | None = None,
-        initial_value: str | None = None,
-    ) -> AliasCustomCounter:
-        """Create or overwrite a custom counter."""
-        payload = {
-            "name": str(name),
-            "min": _safe_int(minVal, -(2**31)) if minVal is not None else -(2**31),
-            "max": _safe_int(maxVal, 2**31 - 1) if maxVal is not None else 2**31 - 1,
-            "reset_on": reset,
-            "display_type": dispType,
-            "reset_to": _safe_int(reset_to) if reset_to is not None else None,
-            "reset_by": reset_by,
-            "title": title,
-            "desc": desc,
-            "value": _safe_int(initial_value, 0) if initial_value is not None else 0,
-        }
-        self._consumable_map()[str(name)] = payload
-        return AliasCustomCounter(payload)
-
-    def edit_cc(
-        self,
-        name: str,
-        minVal: Any = UNSET,
-        maxVal: Any = UNSET,
-        reset: Any = UNSET,
-        dispType: Any = UNSET,
-        reset_to: Any = UNSET,
-        reset_by: Any = UNSET,
-        title: Any = UNSET,
-        desc: Any = UNSET,
-        new_name: str | None = None,
-    ) -> AliasCustomCounter:
-        """Edit fields on an existing custom counter."""
-        counter = dict(self._consumable_map().get(str(name)) or {"name": str(name)})
-        for key, val in (
-            ("min", minVal),
-            ("max", maxVal),
-            ("reset_on", reset),
-            ("display_type", dispType),
-            ("reset_to", reset_to),
-            ("reset_by", reset_by),
-            ("title", title),
-            ("desc", desc),
-        ):
-            if val is not UNSET:
-                counter[key] = val
-        counter["name"] = str(new_name) if new_name else counter.get("name", str(name))
-        self._consumable_map().pop(str(name), None)
-        self._consumable_map()[counter["name"]] = counter
-        return AliasCustomCounter(counter)
-
-    def cc_exists(self, name: str) -> bool:
-        """Return True if a custom counter with the name exists."""
-        return str(name) in self._consumable_map()
-
-    def cc_str(self, name: str) -> str:
-        """String form of a custom counter."""
-        return str(self.cc(name))
-
-    @property
-    def death_saves(self) -> AliasDeathSaves:
-        """Death save successes/failures."""
-        return AliasDeathSaves(self._data.get("death_saves") or {})
-
-    @property
-    def description(self) -> str | None:
-        """Character description/biography."""
-        val = self._data.get("description")
-        return str(val) if val is not None else None
-
-    @property
-    def image(self) -> str | None:
-        """Avatar or sheet image URL."""
-        val = self._data.get("image")
-        return str(val) if val is not None else None
-
-
-# === Combat API ===
-MAX_COMBAT_METADATA_SIZE = 100000
-
-
-@dataclass
-class SimpleEffect(_DirMixin):
-    _data: MutableMapping[str, Any]
-    ATTRS: ClassVar[list[str]] = [
-        "name",
-        "duration",
-        "remaining",
-        "effect",
-        "attacks",
-        "buttons",
-        "conc",
-        "desc",
-        "ticks_on_end",
-        "combatant_name",
-        "parent",
-        "children",
-    ]
-    METHODS: ClassVar[list[str]] = ["set_parent"]
-
-    @property
-    def name(self) -> str:
-        return str(self._data.get("name", "Effect"))
-
-    @property
-    def duration(self) -> int | None:
-        raw = self._data.get("duration")
-        return int(raw) if raw is not None else None
-
-    @property
-    def remaining(self) -> int | None:
-        raw = self._data.get("remaining")
-        return int(raw) if raw is not None else None
-
-    @property
-    def effect(self) -> Mapping[str, Any]:
-        return self._data.get("effects") or self._data.get("effect") or {}
-
-    @property
-    def attacks(self) -> list[Mapping[str, Any]]:
-        return list(self._data.get("attacks") or [])
-
-    @property
-    def buttons(self) -> list[Mapping[str, Any]]:
-        return list(self._data.get("buttons") or [])
-
-    @property
-    def conc(self) -> bool:
-        return bool(self._data.get("conc") or self._data.get("concentration", False))
-
-    @property
-    def desc(self) -> str | None:
-        val = self._data.get("desc")
-        return str(val) if val is not None else None
-
-    @property
-    def ticks_on_end(self) -> bool:
-        return bool(self._data.get("ticks_on_end") or self._data.get("end_on_turn_end", False))
-
-    @property
-    def combatant_name(self) -> str | None:
-        val = self._data.get("combatant_name")
-        return str(val) if val is not None else None
-
-    @property
-    def parent(self) -> "SimpleEffect" | None:
-        parent = self._data.get("parent")
-        return SimpleEffect(parent) if parent else None
-
-    @property
-    def children(self) -> list["SimpleEffect"]:
-        return [SimpleEffect(c) for c in self._data.get("children", [])]
-
-    def set_parent(self, parent: "SimpleEffect") -> None:
-        if not isinstance(parent, SimpleEffect):
-            raise TypeError("Parent effect must be a SimpleEffect.")
-        self._data["parent"] = parent._data
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-@dataclass
-class SimpleCombatant(AliasStatBlock):
-    ATTRS: ClassVar[list[str]] = AliasStatBlock.ATTRS + [
-        "effects",
-        "init",
-        "initmod",
-        "type",
-        "note",
-        "controller",
-        "group",
-        "race",
-        "monster_name",
-        "is_hidden",
-        "id",
-    ]
-    METHODS: ClassVar[list[str]] = AliasStatBlock.METHODS + [
-        "save",
-        "damage",
-        "set_ac",
-        "set_maxhp",
-        "set_init",
-        "set_name",
-        "set_group",
-        "set_note",
-        "get_effect",
-        "add_effect",
-        "remove_effect",
-    ]
-
-    def __post_init__(self) -> None:
-        super().__post_init__()
-        self._data.setdefault("type", "combatant")
-
-    @property
-    def id(self) -> str | None:
-        """Unique combatant id."""
-        val = self._data.get("id")
-        return str(val) if val is not None else None
-
-    @property
-    def effects(self) -> list[SimpleEffect]:
-        """Active effects on the combatant."""
-        return [SimpleEffect(e) for e in self._data.get("effects", [])]
-
-    @property
-    def init(self) -> int:
-        """Initiative score."""
-        return _safe_int(self._data.get("init"), 0)
-
-    @property
-    def initmod(self) -> int:
-        """Initiative modifier."""
-        return _safe_int(self._data.get("initmod"), 0)
-
-    @property
-    def type(self) -> str:
-        """Combatant type (combatant/group)."""
-        return str(self._data.get("type", "combatant"))
-
-    @property
-    def note(self) -> str | None:
-        """DM note attached to the combatant."""
-        val = self._data.get("note")
-        return str(val) if val is not None else None
-
-    @property
-    def controller(self) -> int | None:
-        """Discord id of the controller (if any)."""
-        raw = self._data.get("controller")
-        return int(raw) if raw is not None else None
-
-    @property
-    def group(self) -> str | None:
-        """Group name the combatant belongs to."""
-        val = self._data.get("group")
-        return str(val) if val is not None else None
-
-    @property
-    def race(self) -> str | None:
-        """Race/creature type label."""
-        val = self._data.get("race")
-        return str(val) if val is not None else None
-
-    @property
-    def monster_name(self) -> str | None:
-        """Monster name if this combatant represents a monster."""
-        val = self._data.get("monster_name")
-        return str(val) if val is not None else None
-
-    @property
-    def is_hidden(self) -> bool:
-        """Whether the combatant is hidden in the tracker."""
-        return bool(self._data.get("is_hidden", False))
-
-    def save(self, ability: str, adv: bool | None = None) -> SimpleRollResult:
-        """Roll a saving throw using the combatant's stats."""
-        roll_expr = self.saves.get(ability).d20(base_adv=adv)
-        try:
-            roll_result = d20.roll(roll_expr)
-        except Exception:
-            roll_result = d20.roll("0")
-        return SimpleRollResult(roll_result)
-
-    def damage(
-        self,
-        dice_str: str,
-        crit: bool = False,
-        d=None,
-        c=None,
-        critdice: int = 0,
-        overheal: bool = False,
-    ) -> dict[str, Any]:
-        """Apply damage expression to the combatant and return the roll breakdown."""
-        expr = str(dice_str)
-        if crit:
-            expr = f"({expr})*2"
-        if d is not None:
-            expr = f"({expr})+({d})"
-        if c is not None and crit:
-            expr = f"({expr})+({c})"
-        if critdice:
-            expr = f"({expr})+{int(critdice)}"
-        try:
-            roll_result = d20.roll(expr)
-        except Exception:
-            roll_result = d20.roll("0")
-        label = "Damage (CRIT!)" if crit else "Damage"
-        return {"damage": f"**{label}**: {roll_result}", "total": roll_result.total, "roll": SimpleRollResult(roll_result)}
-
-    def set_ac(self, ac: int) -> None:
-        """Set armor class."""
-        self._data["ac"] = int(ac)
-
-    def set_maxhp(self, maxhp: int) -> None:
-        """Set maximum HP."""
-        self._data["max_hp"] = int(maxhp)
-
-    def set_init(self, init: int) -> None:
-        """Set initiative score."""
-        self._data["init"] = int(init)
-
-    def set_name(self, name: str) -> None:
-        """Rename the combatant."""
-        self._data["name"] = str(name)
-
-    def set_group(self, group: str | None) -> str | None:
-        """Assign the combatant to a group."""
-        self._data["group"] = str(group) if group is not None else None
-        return self.group
-
-    def set_note(self, note: str) -> None:
-        """Attach/update a DM note."""
-        self._data["note"] = str(note) if note is not None else None
-
-    def get_effect(self, name: str, strict: bool = False) -> SimpleEffect | None:
-        """Find an effect by name (optionally requiring exact match)."""
-        name_lower = str(name).lower()
-        for effect in self.effects:
-            if strict and effect.name.lower() == name_lower:
-                return effect
-            if not strict and name_lower in effect.name.lower():
-                return effect
-        return None
-
-    def add_effect(
-        self,
-        name: str,
-        args: str | None = None,
-        duration: int | None = None,
-        concentration: bool = False,
-        parent: SimpleEffect | None = None,
-        end: bool = False,
-        desc: str | None = None,
-        passive_effects: dict | None = None,
-        attacks: list[dict] | None = None,
-        buttons: list[dict] | None = None,
-        tick_on_combatant_id: str | None = None,
-    ) -> SimpleEffect:
-        """Add a new effect to the combatant."""
-        duration_val = int(duration) if duration is not None else None
-        desc_val = str(desc) if desc is not None else None
-        payload: dict[str, Any] = {
-            "name": str(name),
-            "duration": duration_val,
-            "remaining": duration_val,
-            "args": str(args) if args is not None else None,
-            "desc": desc_val,
-            "concentration": bool(concentration),
-            "conc": bool(concentration),
-            "ticks_on_end": end,
-            "effect": dict(passive_effects or {}),
-            "attacks": list(attacks or []),
-            "buttons": list(buttons or []),
-            "combatant_name": self.name,
-        }
-        if tick_on_combatant_id is not None:
-            payload["tick_on_combatant_id"] = str(tick_on_combatant_id)
-        if parent is not None:
-            if not isinstance(parent, SimpleEffect):
-                raise TypeError("Parent effect must be a SimpleEffect.")
-            payload["parent"] = parent._data
-        effects = self._data.setdefault("effects", [])
-        existing = self.get_effect(name, strict=True)
-        if existing:
-            try:
-                effects.remove(existing._data)
-            except ValueError:
-                pass
-        effects.append(payload)
-        return SimpleEffect(payload)
-
-    def remove_effect(self, name: str, strict: bool = False) -> None:
-        """Remove an effect by name."""
-        effect = self.get_effect(name, strict)
-        if effect:
-            try:
-                self._data.setdefault("effects", []).remove(effect._data)
-            except ValueError:
-                pass
-
-
-@dataclass
-class SimpleGroup(_DirMixin):
-    _data: MutableMapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["combatants", "type", "init", "name", "id"]
-    METHODS: ClassVar[list[str]] = ["get_combatant", "set_init"]
-
-    def __post_init__(self) -> None:
-        super().__post_init__()
-        self._data.setdefault("type", "group")
-
-    @property
-    def combatants(self) -> list[SimpleCombatant]:
-        """Members of the group."""
-        return [SimpleCombatant(c) for c in self._data.get("combatants", [])]
-
-    @property
-    def type(self) -> str:
-        """Group type identifier (always 'group')."""
-        return str(self._data.get("type", "group"))
-
-    @property
-    def init(self) -> int:
-        """Initiative score for the group."""
-        return _safe_int(self._data.get("init"), 0)
-
-    @property
-    def name(self) -> str:
-        """Group name."""
-        return str(self._data.get("name", "Group"))
-
-    @property
-    def id(self) -> str | None:
-        """Group id."""
-        val = self._data.get("id")
-        return str(val) if val is not None else None
-
-    def get_combatant(self, name: str, strict: bool | None = None) -> SimpleCombatant | None:
-        """Find a combatant within the group."""
-        name_lower = str(name).lower()
-        for combatant in self.combatants:
-            if strict is True and combatant.name.lower() == name_lower:
-                return combatant
-            if strict is None and combatant.name.lower() == name_lower:
-                return combatant
-            if strict is False and name_lower in combatant.name.lower():
-                return combatant
-        if strict is None:
-            for combatant in self.combatants:
-                if name_lower in combatant.name.lower():
-                    return combatant
-        return None
-
-    def set_init(self, init: int) -> None:
-        self._data["init"] = int(init)
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-@dataclass
-class SimpleCombat(_DirMixin):
-    _data: MutableMapping[str, Any] = field(default_factory=dict)
-    ATTRS: ClassVar[list[str]] = ["combatants", "groups", "me", "current", "name", "round_num", "turn_num", "metadata"]
-    METHODS: ClassVar[list[str]] = ["get_combatant", "get_group", "set_metadata", "get_metadata", "delete_metadata", "set_round", "end_round"]
-
-    @property
-    def combatants(self) -> list[SimpleCombatant]:
-        """All combatants in the encounter."""
-        return [SimpleCombatant(c) for c in self._data.get("combatants", [])]
-
-    @property
-    def groups(self) -> list[SimpleGroup]:
-        """Combatant groups in the encounter."""
-        return [SimpleGroup(g) for g in self._data.get("groups", [])]
-
-    @property
-    def me(self) -> SimpleCombatant | None:
-        """The player's combatant if present."""
-        me_data = self._data.get("me")
-        return SimpleCombatant(me_data) if me_data is not None else None
-
-    @property
-    def current(self) -> SimpleCombatant | SimpleGroup | None:
-        """Current turn holder (combatant or group)."""
-        cur = self._data.get("current")
-        if cur is None:
-            return None
-        if cur.get("type") == "group":
-            return SimpleGroup(cur)
-            return SimpleCombatant(cur)
-
-    @property
-    def name(self) -> str | None:
-        """Name of the combat encounter."""
-        val = self._data.get("name")
-        return str(val) if val is not None else None
-
-    @property
-    def round_num(self) -> int:
-        """Current round number."""
-        return _safe_int(self._data.get("round_num"), 1)
-
-    @property
-    def turn_num(self) -> int:
-        """Current turn number within the round."""
-        return _safe_int(self._data.get("turn_num"), 1)
-
-    @property
-    def metadata(self) -> MutableMapping[str, Any]:
-        """Free-form metadata key/value store for the combat."""
-        return self._data.setdefault("metadata", {})
-
-    def get_combatant(self, name: str, strict: bool | None = None) -> SimpleCombatant | None:
-        """Find a combatant by name (strict, substring, or fuzzy)."""
-        name_lower = str(name).lower()
-        for combatant in self.combatants:
-            if strict is True and combatant.name.lower() == name_lower:
-                return combatant
-            if strict is None and combatant.name.lower() == name_lower:
-                return combatant
-            if strict is False and name_lower in combatant.name.lower():
-                return combatant
-        if strict is None:
-            for combatant in self.combatants:
-                if name_lower in combatant.name.lower():
-                    return combatant
-        return None
-
-    def get_group(self, name: str, strict: bool | None = None) -> SimpleGroup | None:
-        """Find a combatant group by name."""
-        name_lower = str(name).lower()
-        for group in self.groups:
-            if strict is True and group.name.lower() == name_lower:
-                return group
-            if strict is None and group.name.lower() == name_lower:
-                return group
-            if strict is False and name_lower in group.name.lower():
-                return group
-        if strict is None:
-            for group in self.groups:
-                if name_lower in group.name.lower():
-                    return group
-        return None
-
-    def set_metadata(self, k: str, v: str) -> None:
-        """Set a metadata key/value pair, enforcing Avrae size limits."""
-        key = str(k)
-        value = str(v)
-        existing = {str(ke): str(va) for ke, va in self.metadata.items() if str(ke) != key}
-        proposed_size = sum(len(ke) + len(va) for ke, va in existing.items()) + len(key) + len(value)
-        if proposed_size > MAX_COMBAT_METADATA_SIZE:
-            raise ValueError("Combat metadata is too large")
-        self.metadata[key] = value
-
-    def get_metadata(self, k: str, default: Any = None) -> Any:
-        return self.metadata.get(str(k), default)
-
-    def delete_metadata(self, k: str) -> Any:
-        """Delete a metadata key."""
-        return self.metadata.pop(str(k), None)
-
-    def set_round(self, round_num: int) -> None:
-        """Advance combat to the specified round number."""
-        self._data["round_num"] = int(round_num)
-
-    def end_round(self) -> None:
-        """Increment round number and reset turn counter."""
-        self._data["turn_num"] = 0
-        self._data["round_num"] = self.round_num + 1
-
-    def __getattr__(self, item: str) -> Any:
-        return self._data.get(item)
-
-    def __getitem__(self, item: str) -> Any:
-        return getattr(self, str(item))
-
-
-# Backwards-compatible aliases for existing consumers
-CombatantAPI = SimpleCombatant
-SimpleEffectAPI = SimpleEffect
-SimpleGroupAPI = SimpleGroup
-CombatAPI = SimpleCombat