dndwright 0.2.0__tar.gz → 0.4.0__tar.gz

{dndwright-0.2.0 → dndwright-0.4.0}/.github/workflows/ci.yml

@@ -22,6 +22,6 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
       - name: Lint (ruff)
-        run: ruff check src tests
+        run: ruff check src tests examples
       - name: Test (pytest)
         run: pytest -q

{dndwright-0.2.0 → dndwright-0.4.0}/.github/workflows/publish.yml

@@ -8,6 +8,7 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
+  workflow_dispatch:          # allow manual publish of the current main (version in pyproject)
 
 jobs:
   build:
@@ -32,6 +33,7 @@ jobs:
     environment: pypi          # must match the "Environment name" in PyPI's publisher config
     permissions:
       id-token: write          # REQUIRED for Trusted Publishing (OIDC)
+      contents: read
     steps:
       - uses: actions/download-artifact@v4
         with:

{dndwright-0.2.0 → dndwright-0.4.0}/.gitignore

@@ -21,3 +21,7 @@ htmlcov/
 .vscode/
 .idea/
 .DS_Store
+
+# Local planning / scratch notes (never committed)
+*.local.md
+*.local

dndwright-0.4.0/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to dndwright are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+**Public API** = the names exported in `dndwright.__all__` (pinned by
+`tests/test_api_contract.py`). While the version is `0.x`, minor versions may make
+breaking changes; these will always be noted here.
+
+## [Unreleased]
+
+## [0.4.0] — 2026-06-01
+
+### Added
+- **Dice engine** (`dndwright.dice`) — `DiceEngine`: parse and roll D&D 5e dice
+  expressions (`1d20+5`, `4d6kh3`, `2d6r1`, `1d6!`, advantage/disadvantage) plus
+  `roll_attack`/`roll_save`/`roll_check`/`roll_damage`/`roll_initiative`/`roll_stat_array`/
+  `roll_hit_dice`/`roll_death_save`. Returns a **typed, frozen result surface**
+  (`ExpressionResult`, `RollResult`, `AttackRoll`, `SaveRoll`, `DamageRoll`, `DeathSave`,
+  `StatArray`, `HitDiceResult`, …). Deterministic by default (`DiceEngine(seed=…)`); for
+  unpredictable production rolls inject any `random.Random` (e.g.
+  `DiceEngine(rng=secrets.SystemRandom())`) — no NumPy dependency. `DiceEngine` is also
+  re-exported at the top level.
+
+### Fixed
+- **Dice engine hardening** — pathological groups can no longer hang the engine: rerolls
+  whose set covers every die face are skipped, exploding requires `sides > 1`, and both
+  loops are capped (`1d1!`, `1d2r1,2` now terminate). `reroll_once` is detected per dice
+  group instead of from the whole expression, so a later `ro` group can't flip an earlier
+  `r` group. Result value types are now genuinely immutable — sequence fields are tuples,
+  making every result hashable and usable as a set member / dict key.
+- **CLI robustness** — `dndwright eval` now reports a clean error for non-object JSON
+  (was an uncaught `AttributeError`), and `dndwright validate` reports a clean error for
+  valid-JSON-but-invalid rulesets (was an uncaught pydantic `ValidationError`).
+- **Graph export escaping** — `to_mermaid` now escapes label special characters
+  (`[](){}<>"#`) and emits subgraphs as `id["title"]`, so labels and group names with
+  spaces/punctuation no longer break the diagram. `to_dot` now escapes backslashes,
+  quotes, and newlines in labels and node ids.
+- **Strict input validation** — `validate_character_data` now rejects non-integer float
+  ability scores (e.g. `15.7`; integral floats like `15.0` are fine), reports an omitted
+  `level` (previously masked by the default-to-1 normalization), and handles non-dict
+  input without crashing.
+
+### Added
+- **Property-based tests** (hypothesis, dev-only) — invariants checked over wide input
+  ranges: ability-modifier and proficiency-bonus formulas, PB in its published 2..6 range,
+  and HP monotonic in level.
+- **Examples** — runnable scripts under `examples/` (quickstart, multiclass, stat-diff,
+  custom operation, graph export), exercised in CI so they can't rot.
+- **Input validation** — `validate_character_data(data) -> list[str]` reports problems
+  (missing/out-of-range ability scores, bad level, missing class) that would otherwise be
+  silently coerced into a plausible-but-wrong sheet. `evaluate_character(data, strict=True)`
+  raises `CharacterInputError` on those; default lenient behaviour is unchanged. The CLI
+  gains `dndwright eval --strict`.
+- **Custom operations** — `register_operation(name, fn)` extends the formula DSL without
+  forking. Custom ops are recognised everywhere the registry is consulted (`evaluate`,
+  `validate_ruleset`, `known_operations`). Built-in op names cannot be overwritten; the
+  `Operation` callable type is exported for typing custom ops.
+- **CLI** — a `dndwright` console command (stdlib only): `eval` (character JSON → sheet,
+  file or stdin), `graph` (export the DAG as Mermaid/DOT), `content` (list/dump bundled
+  content), `validate` (check a ruleset). Usable without writing Python.
+- **Graph export** — `to_mermaid(ruleset)` and `to_dot(ruleset)` render the computation
+  DAG as Mermaid or Graphviz DOT (node shapes by type, optional clustering by group),
+  making the "formulas as data / inspectable DAG" design visible for docs and debugging.
+- **Ruleset validation** — `validate_ruleset(ruleset) -> list[ValidationIssue]` and
+  `assert_valid_ruleset(ruleset)` statically check a ruleset before evaluation, catching
+  authoring mistakes (unknown op, key/`id` mismatch, missing formula, cycles) with clear
+  messages instead of a deep runtime `EvaluationError`, plus warnings (INPUT-with-formula,
+  unknown explicit input ref, absent lookup table). Also `known_operations()` lists every
+  op a formula may use, and `ValidationIssue` / `RulesetValidationError` are exported.
+
+### Changed
+- **Faster evaluation** — the evaluator now caches each ruleset's topological order
+  instead of recomputing it on every `evaluate()` call (~2.2× faster per evaluation;
+  ~0.41 → ~0.18 ms for a level-5 character). Cache is keyed per ruleset instance and
+  evicted on garbage collection, so custom/transient rulesets neither leak nor go stale.
+
+### Docs
+- Revamped the README landing page: centered header, status badges (PyPI version, Python
+  versions, CI, license, typed), and a hero SVG of the computation graph (`assets/`).
+- Added a "Command line" section and `validate_ruleset` / `to_mermaid` / `to_dot` rows.
+
+### Packaging
+- Ship a `py.typed` marker (PEP 561) so downstream type-checkers see dndwright's type
+  hints. Added Python 3.10–3.13, `Typing :: Typed`, `Intended Audience :: Developers`,
+  and `Topic :: Software Development :: Libraries` classifiers, plus `Changelog`/`Issues`
+  project URLs. Internal: `OPERATIONS` is now typed `dict[str, Operation]`.
+
+## [0.3.0] — 2026-06-01
+
+### Added
+- **Bundled starter content** — `load_content(category)` + `categories()`: original
+  homebrew classes/species/creatures, plus 236 SRD 5.2 (CC-BY) magic items.
+- **LLM-agnostic content generator** — `generate_library(llm, ...)` (and
+  `generate_classes`/`species`/`creatures`): you pass a `complete_json(prompt, system)
+  -> dict` callable wrapping your own LLM; prompts produce *original homebrew* (no
+  official content), matching the bundled schema and component ontology.
+
+## [0.2.0] — 2026-06-01
+
+### Added
+- **Component ontology** — `load_ontology()` → `Ontology`: a graph schema for D&D
+  building blocks (Class, Species, Spell, Equipment, MagicItem, Background, Feat,
+  Subclass, Creature) and how a Character connects to them (`HAS_*`, `INSTANCE_OF`,
+  `HAS_STAT_BLOCK`). Typed models (`NodeTypeDef`, `EdgeTypeDef`, `PropertyDef`) with
+  `edges_from`/`edges_to` helpers, parsed from the bundled `dnd.yaml`.
+- Dependency: `pyyaml` (for the ontology loader).
+
+## [0.1.0] — 2026-06-01
+
+Initial release. The D&D 5e (2024) rules & character-computation engine, extracted
+from a working application.
+
+### Added
+- `evaluate_character(data) -> dict` — one-call evaluation: character data in,
+  computed sheet out (ability modifiers, proficiency, saves, spell DC/attack, HP,
+  AC, initiative, …).
+- The computation engine: `DND_5E_2024_RULESET` (a 135-node DAG), `evaluate`,
+  `assemble_character_inputs`, `apply_modifiers`, and the `Ruleset` / `ComputationNode`
+  / `FormulaSpec` / `NodeType` schema — formulas as data, not code.
+- Neutral adapters: `character_data_to_inputs`, `computed_values_to_sheet`.
+- Typed component models under `dndwright.rules.components`
+  (`ClassMechanics`, `SpeciesMechanics`, …) and SRD-derived rules tables.
+
+Pure (pydantic + stdlib); no application/framework coupling. Rules content derives
+from the SRD 5.2 (CC-BY-4.0); see NOTICE.
+
+[Unreleased]: https://github.com/sligara7/dndwright/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/sligara7/dndwright/compare/v0.3.0...v0.4.0
+[0.1.0]: https://github.com/sligara7/dndwright/releases/tag/v0.1.0

dndwright-0.4.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: dndwright
+Version: 0.4.0
+Summary: Domain-neutral D&D 5e (2024) rules & character-sheet computation engine: a data-driven DAG of formulas (ability mods, proficiency, spell DC/slots, HP, AC).
+Project-URL: Homepage, https://github.com/sligara7/dndwright
+Project-URL: Repository, https://github.com/sligara7/dndwright
+Project-URL: Changelog, https://github.com/sligara7/dndwright/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/sligara7/dndwright/issues
+Author: Anthony Sligar
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: character-sheet,computation-graph,dnd,dnd5e,rules-engine,srd,ttrpg
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">dndwright</h1>
+
+<p align="center">
+  <em>A domain-neutral D&amp;D 5e (2024) rules &amp; character-sheet computation engine —
+  formulas as data, not code.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/dndwright/"><img alt="PyPI" src="https://img.shields.io/pypi/v/dndwright.svg"></a>
+  <a href="https://pypi.org/project/dndwright/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/dndwright.svg"></a>
+  <a href="https://github.com/sligara7/dndwright/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/sligara7/dndwright/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/sligara7/dndwright/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
+  <img alt="Typed" src="https://img.shields.io/badge/typing-PEP%20561-blue.svg">
+</p>
+
+<p align="center">
+  <img alt="dndwright computation graph: ability scores, level, class and equipment flow through ability modifiers and proficiency bonus to saves, skills, spell DC/attack, spell slots, HP, AC and initiative" width="760" src="https://raw.githubusercontent.com/sligara7/dndwright/main/assets/computation-graph.svg">
+</p>
+
+A character sheet is modelled as a **directed acyclic computation graph** — nodes are values,
+edges are dependencies, and formulas are *data* (a JSON-serialisable DSL), not code. Pure
+Python (`pydantic` + stdlib), no application or framework coupling: map your own character
+data in, read computed stats out.
+
+> ⚠️ **Early development (alpha).** The API is still moving and may change between minor
+> versions while at `0.x`. Usable today — pin a version if you depend on it.
+
+## Install
+
+```bash
+pip install git+https://github.com/sligara7/dndwright.git
+# or, for local development:
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from dndwright import evaluate_character
+
+sheet = evaluate_character({
+    "ability_scores": {"strength": 8, "dexterity": 14, "constitution": 14,
+                       "intelligence": 18, "wisdom": 12, "charisma": 10},
+    "class_data": {"class_name": "wizard"},
+    "species_data": {"name": "Human", "speed": 30},
+    "level": 5,
+})
+
+sheet["proficiency_bonus"]    # 3
+sheet["ability_modifiers"]    # {"intelligence": 4, "dexterity": 2, ...}
+sheet["spellcasting_type"]    # "full_caster"
+# ...plus armor_class, hit_points, hit_dice, initiative, saves, features, ...
+```
+
+Lower level — assemble typed inputs and evaluate against the ruleset:
+
+```python
+from dndwright import DND_5E_2024_RULESET, assemble_character_inputs, evaluate, apply_modifiers
+from dndwright.rules.components import ClassMechanics
+
+inputs   = assemble_character_inputs(class_mechanics=..., ability_scores={...}, level=5)
+computed = apply_modifiers(evaluate(DND_5E_2024_RULESET, inputs), inputs)
+```
+
+## Command line
+
+Installing the package also installs a `dndwright` command (no Python required):
+
+```bash
+dndwright eval character.json          # character JSON → computed sheet (or '-' for stdin)
+dndwright graph --format mermaid        # export the computation DAG (mermaid|dot)
+dndwright content magic_items           # dump bundled content (omit category to list)
+dndwright validate ruleset.json         # check a ruleset (built-in if omitted)
+```
+
+## Rolling dice
+
+A self-contained, typed dice engine (`dndwright.dice`) — deterministic by default:
+
+```python
+from dndwright.dice import DiceEngine
+
+eng = DiceEngine(seed=42)               # reproducible (stdlib RNG)
+eng.roll("4d6kh3").total                # keep highest 3 of 4
+eng.roll("1d20", advantage=True)        # -> ExpressionResult
+eng.roll_attack(modifier=5, target_ac=15).is_hit
+eng.roll_damage("2d8", is_critical=True)  # crit doubles the dice
+
+# unpredictable production rolls (no NumPy dependency):
+import secrets
+DiceEngine(rng=secrets.SystemRandom())
+```
+
+## Why a computation graph?
+
+Derived character values form a dependency DAG: ability scores → modifiers → proficiency →
+save DCs / spell slots / AC / HP. dndwright represents that DAG explicitly and stores the
+formulas as **data** (`FormulaSpec`: an op + args), so the rules are inspectable, testable,
+and serialisable — not buried in imperative code. `DND_5E_2024_RULESET` is a 135-node graph.
+
+## What's inside
+
+| Component | What it does |
+|-----------|--------------|
+| `evaluate_character` | One call: character data dict → fully computed sheet. |
+| `DND_5E_2024_RULESET` | The 135-node 5e-2024 computation DAG (formulas as data). |
+| `evaluate` / `assemble_character_inputs` / `apply_modifiers` | The lower-level engine. |
+| `Ruleset` / `ComputationNode` / `FormulaSpec` / `NodeType` | The DAG schema. |
+| `validate_ruleset` / `assert_valid_ruleset` | Static integrity check for a ruleset (unknown ops, cycles, dangling refs) — catch authoring errors before evaluation. |
+| `to_mermaid` / `to_dot` | Render the computation DAG as Mermaid or Graphviz DOT — *see* the dependency graph. |
+| `dndwright.dice` | Typed dice engine: parse/roll 5e expressions, attacks, saves, damage, stat arrays. |
+| `dndwright.rules.components` | Typed inputs (`ClassMechanics`, `SpeciesMechanics`, …). |
+| `dndwright.rules.lookup_tables` | SRD-derived rules tables (hit dice, spell slots, AC, saves). |
+
+## API stability
+
+The public API is exactly `dndwright.__all__`, pinned by `tests/test_api_contract.py`.
+Versioning follows [SemVer](https://semver.org/); at `0.x` minor versions may break, with
+every change recorded in `CHANGELOG.md`.
+
+## Credits & license
+
+MIT licensed (see `LICENSE`). The rules tables encode game *mechanics* derived from the
+**D&D System Reference Document 5.2** (© Wizards of the Coast, **CC-BY-4.0**); see `NOTICE`.
+Not affiliated with or endorsed by Wizards of the Coast. Contains no PHB/DMG/MM content.

dndwright-0.4.0/README.md

@@ -0,0 +1,125 @@
+<h1 align="center">dndwright</h1>
+
+<p align="center">
+  <em>A domain-neutral D&amp;D 5e (2024) rules &amp; character-sheet computation engine —
+  formulas as data, not code.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/dndwright/"><img alt="PyPI" src="https://img.shields.io/pypi/v/dndwright.svg"></a>
+  <a href="https://pypi.org/project/dndwright/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/dndwright.svg"></a>
+  <a href="https://github.com/sligara7/dndwright/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/sligara7/dndwright/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/sligara7/dndwright/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
+  <img alt="Typed" src="https://img.shields.io/badge/typing-PEP%20561-blue.svg">
+</p>
+
+<p align="center">
+  <img alt="dndwright computation graph: ability scores, level, class and equipment flow through ability modifiers and proficiency bonus to saves, skills, spell DC/attack, spell slots, HP, AC and initiative" width="760" src="https://raw.githubusercontent.com/sligara7/dndwright/main/assets/computation-graph.svg">
+</p>
+
+A character sheet is modelled as a **directed acyclic computation graph** — nodes are values,
+edges are dependencies, and formulas are *data* (a JSON-serialisable DSL), not code. Pure
+Python (`pydantic` + stdlib), no application or framework coupling: map your own character
+data in, read computed stats out.
+
+> ⚠️ **Early development (alpha).** The API is still moving and may change between minor
+> versions while at `0.x`. Usable today — pin a version if you depend on it.
+
+## Install
+
+```bash
+pip install git+https://github.com/sligara7/dndwright.git
+# or, for local development:
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from dndwright import evaluate_character
+
+sheet = evaluate_character({
+    "ability_scores": {"strength": 8, "dexterity": 14, "constitution": 14,
+                       "intelligence": 18, "wisdom": 12, "charisma": 10},
+    "class_data": {"class_name": "wizard"},
+    "species_data": {"name": "Human", "speed": 30},
+    "level": 5,
+})
+
+sheet["proficiency_bonus"]    # 3
+sheet["ability_modifiers"]    # {"intelligence": 4, "dexterity": 2, ...}
+sheet["spellcasting_type"]    # "full_caster"
+# ...plus armor_class, hit_points, hit_dice, initiative, saves, features, ...
+```
+
+Lower level — assemble typed inputs and evaluate against the ruleset:
+
+```python
+from dndwright import DND_5E_2024_RULESET, assemble_character_inputs, evaluate, apply_modifiers
+from dndwright.rules.components import ClassMechanics
+
+inputs   = assemble_character_inputs(class_mechanics=..., ability_scores={...}, level=5)
+computed = apply_modifiers(evaluate(DND_5E_2024_RULESET, inputs), inputs)
+```
+
+## Command line
+
+Installing the package also installs a `dndwright` command (no Python required):
+
+```bash
+dndwright eval character.json          # character JSON → computed sheet (or '-' for stdin)
+dndwright graph --format mermaid        # export the computation DAG (mermaid|dot)
+dndwright content magic_items           # dump bundled content (omit category to list)
+dndwright validate ruleset.json         # check a ruleset (built-in if omitted)
+```
+
+## Rolling dice
+
+A self-contained, typed dice engine (`dndwright.dice`) — deterministic by default:
+
+```python
+from dndwright.dice import DiceEngine
+
+eng = DiceEngine(seed=42)               # reproducible (stdlib RNG)
+eng.roll("4d6kh3").total                # keep highest 3 of 4
+eng.roll("1d20", advantage=True)        # -> ExpressionResult
+eng.roll_attack(modifier=5, target_ac=15).is_hit
+eng.roll_damage("2d8", is_critical=True)  # crit doubles the dice
+
+# unpredictable production rolls (no NumPy dependency):
+import secrets
+DiceEngine(rng=secrets.SystemRandom())
+```
+
+## Why a computation graph?
+
+Derived character values form a dependency DAG: ability scores → modifiers → proficiency →
+save DCs / spell slots / AC / HP. dndwright represents that DAG explicitly and stores the
+formulas as **data** (`FormulaSpec`: an op + args), so the rules are inspectable, testable,
+and serialisable — not buried in imperative code. `DND_5E_2024_RULESET` is a 135-node graph.
+
+## What's inside
+
+| Component | What it does |
+|-----------|--------------|
+| `evaluate_character` | One call: character data dict → fully computed sheet. |
+| `DND_5E_2024_RULESET` | The 135-node 5e-2024 computation DAG (formulas as data). |
+| `evaluate` / `assemble_character_inputs` / `apply_modifiers` | The lower-level engine. |
+| `Ruleset` / `ComputationNode` / `FormulaSpec` / `NodeType` | The DAG schema. |
+| `validate_ruleset` / `assert_valid_ruleset` | Static integrity check for a ruleset (unknown ops, cycles, dangling refs) — catch authoring errors before evaluation. |
+| `to_mermaid` / `to_dot` | Render the computation DAG as Mermaid or Graphviz DOT — *see* the dependency graph. |
+| `dndwright.dice` | Typed dice engine: parse/roll 5e expressions, attacks, saves, damage, stat arrays. |
+| `dndwright.rules.components` | Typed inputs (`ClassMechanics`, `SpeciesMechanics`, …). |
+| `dndwright.rules.lookup_tables` | SRD-derived rules tables (hit dice, spell slots, AC, saves). |
+
+## API stability
+
+The public API is exactly `dndwright.__all__`, pinned by `tests/test_api_contract.py`.
+Versioning follows [SemVer](https://semver.org/); at `0.x` minor versions may break, with
+every change recorded in `CHANGELOG.md`.
+
+## Credits & license
+
+MIT licensed (see `LICENSE`). The rules tables encode game *mechanics* derived from the
+**D&D System Reference Document 5.2** (© Wizards of the Coast, **CC-BY-4.0**); see `NOTICE`.
+Not affiliated with or endorsed by Wizards of the Coast. Contains no PHB/DMG/MM content.

dndwright-0.4.0/assets/computation-graph.svg

@@ -0,0 +1,83 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 470" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#0f172a"/>
+      <stop offset="1" stop-color="#111827"/>
+    </linearGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#64748b"/>
+    </marker>
+    <style>
+      .lbl    { fill:#e2e8f0; font-size:13px; }
+      .node   { stroke-width:1.5; rx:9; }
+      .input  { fill:#1e293b; stroke:#f59e0b; }
+      .derive { fill:#1e293b; stroke:#2dd4bf; }
+      .output { fill:#1e293b; stroke:#a78bfa; }
+      .layer  { fill:#94a3b8; font-size:12px; letter-spacing:.14em; text-transform:uppercase; }
+      .edge   { stroke:#475569; stroke-width:1.5; fill:none; }
+    </style>
+  </defs>
+
+  <rect x="0" y="0" width="900" height="470" rx="16" fill="url(#bg)"/>
+
+  <text x="36" y="46" fill="#f8fafc" font-size="26" font-weight="700">dndwright</text>
+  <text x="36" y="72" fill="#94a3b8" font-size="15">A D&amp;D 5e character sheet as a directed acyclic computation graph — formulas as data.</text>
+
+  <!-- layer captions -->
+  <text class="layer" x="120" y="118" text-anchor="middle">Inputs</text>
+  <text class="layer" x="450" y="118" text-anchor="middle">Derived</text>
+  <text class="layer" x="780" y="118" text-anchor="middle">Computed outputs</text>
+
+  <!-- edges (drawn first, behind nodes) -->
+  <!-- inputs -> derived -->
+  <path class="edge" marker-end="url(#arrow)" d="M210 165 C300 165 300 190 360 190"/>
+  <path class="edge" marker-end="url(#arrow)" d="M210 225 C300 225 300 260 360 260"/>
+  <path class="edge" marker-end="url(#arrow)" d="M210 285 C300 285 300 268 360 264"/>
+  <!-- derived -> outputs -->
+  <path class="edge" marker-end="url(#arrow)" d="M540 190 C620 190 620 165 690 165"/>
+  <path class="edge" marker-end="url(#arrow)" d="M540 190 C620 190 620 215 690 215"/>
+  <path class="edge" marker-end="url(#arrow)" d="M540 190 C620 190 620 265 690 265"/>
+  <path class="edge" marker-end="url(#arrow)" d="M540 260 C620 260 620 315 690 315"/>
+  <path class="edge" marker-end="url(#arrow)" d="M540 260 C620 260 620 165 690 165"/>
+  <!-- level/class/equipment -> outputs directly -->
+  <path class="edge" marker-end="url(#arrow)" d="M210 285 C440 360 470 365 690 365"/>
+  <path class="edge" marker-end="url(#arrow)" d="M210 345 C440 415 470 415 690 415"/>
+
+  <!-- input nodes -->
+  <g>
+    <rect rx="9" class="node input" x="40" y="148" width="170" height="34"/>
+    <text class="lbl" x="56" y="170">Ability scores</text>
+    <rect rx="9" class="node input" x="40" y="208" width="170" height="34"/>
+    <text class="lbl" x="56" y="230">Level</text>
+    <rect rx="9" class="node input" x="40" y="268" width="170" height="34"/>
+    <text class="lbl" x="56" y="290">Class</text>
+    <rect rx="9" class="node input" x="40" y="328" width="170" height="34"/>
+    <text class="lbl" x="56" y="350">Equipment</text>
+  </g>
+
+  <!-- derived nodes -->
+  <g>
+    <rect rx="9" class="node derive" x="360" y="173" width="180" height="34"/>
+    <text class="lbl" x="376" y="195">Ability modifiers</text>
+    <rect rx="9" class="node derive" x="360" y="243" width="180" height="34"/>
+    <text class="lbl" x="376" y="265">Proficiency bonus</text>
+  </g>
+
+  <!-- output nodes -->
+  <g>
+    <rect rx="9" class="node output" x="690" y="148" width="180" height="34"/>
+    <text class="lbl" x="706" y="170">Saves &amp; skills</text>
+    <rect rx="9" class="node output" x="690" y="198" width="180" height="34"/>
+    <text class="lbl" x="706" y="220">Spell DC / attack</text>
+    <rect rx="9" class="node output" x="690" y="248" width="180" height="34"/>
+    <text class="lbl" x="706" y="270">Spell slots</text>
+    <rect rx="9" class="node output" x="690" y="298" width="180" height="34"/>
+    <text class="lbl" x="706" y="320">Hit points</text>
+    <rect rx="9" class="node output" x="690" y="348" width="180" height="34"/>
+    <text class="lbl" x="706" y="370">Armor class</text>
+    <rect rx="9" class="node output" x="690" y="398" width="180" height="34"/>
+    <text class="lbl" x="706" y="420">Initiative</text>
+  </g>
+
+  <text x="36" y="454" fill="#64748b" font-size="12">135-node ruleset · pure Python (pydantic + stdlib) · inspectable, testable, serialisable</text>
+</svg>

dndwright-0.4.0/examples/README.md

@@ -0,0 +1,19 @@
+# Examples
+
+Runnable scripts for the main dndwright workflows. From the repo root:
+
+```bash
+pip install -e .
+python examples/quickstart.py
+```
+
+| Script | Shows |
+|--------|-------|
+| [`quickstart.py`](quickstart.py) | One call: character dict → computed sheet (plus `strict=True`). |
+| [`multiclass.py`](multiclass.py) | Fighter 5 / Wizard 3 via the typed lower-level engine. |
+| [`stat_diff.py`](stat_diff.py) | Which key stats change on level-up (`compute_stat_diff`). |
+| [`custom_operation.py`](custom_operation.py) | Extend the DSL with `register_operation` + a custom `Ruleset`. |
+| [`export_graph.py`](export_graph.py) | Render the computation DAG as Mermaid / Graphviz DOT. |
+| [`dice.py`](dice.py) | Roll 5e dice (expressions, advantage, attacks/saves, crit damage, stat arrays). |
+
+See also the `dndwright` CLI (`dndwright eval`, `graph`, `content`, `validate`).

dndwright-0.4.0/examples/custom_operation.py

@@ -0,0 +1,34 @@
+"""Extend the formula DSL with your own operation, then build a tiny custom ruleset.
+
+Shows ``register_operation`` + authoring a ``Ruleset`` from nodes + ``validate_ruleset``.
+Everything that consults the registry (evaluate, validation, known_operations) picks up
+the new op automatically.
+
+    python examples/custom_operation.py
+"""
+
+from dndwright import (
+    ComputationNode,
+    FormulaSpec,
+    NodeType,
+    Ruleset,
+    assert_valid_ruleset,
+    evaluate,
+    register_operation,
+)
+
+# A pure (args, tables) -> value function — same shape as the built-ins.
+register_operation("average", lambda args, _tables: sum(args) / len(args))
+
+ruleset = Ruleset(
+    id="demo", name="Average demo",
+    nodes={
+        "a": ComputationNode(id="a", node_type=NodeType.INPUT, label="A"),
+        "b": ComputationNode(id="b", node_type=NodeType.INPUT, label="B"),
+        "mean": ComputationNode(id="mean", node_type=NodeType.FORMULA, label="Mean",
+                                formula=FormulaSpec(op="average", args=["a", "b"])),
+    },
+)
+
+assert_valid_ruleset(ruleset)                         # raises if the graph is broken
+print("mean of 4 and 8 =", evaluate(ruleset, {"a": 4, "b": 8})["mean"])   # 6.0

dndwright-0.4.0/examples/dice.py

@@ -0,0 +1,34 @@
+"""Roll D&D 5e dice with a typed, reproducible engine.
+
+    python examples/dice.py
+
+For unpredictable production rolls, inject OS entropy instead of seeding:
+    import secrets; DiceEngine(rng=secrets.SystemRandom())
+"""
+
+from dndwright.dice import DiceEngine
+
+eng = DiceEngine(seed=42)  # reproducible — same seed, same rolls
+
+# Basic expressions → ExpressionResult
+print("2d6+3      =", eng.roll("2d6+3").total)
+print("4d6kh3     =", eng.roll("4d6kh3").total, "(keep highest 3 of 4)")
+
+# Advantage on a single d20
+adv = eng.roll("1d20", advantage=True)
+print(f"1d20 adv   = {adv.total}  (rolled {adv.advantage_data.roll1} & "
+      f"{adv.advantage_data.roll2}, kept {adv.advantage_data.chosen})")
+
+# Attack vs AC, save vs DC
+atk = eng.roll_attack(modifier=5, target_ac=15)
+print(f"attack +5 vs AC 15 = {atk.roll.total} → {'HIT' if atk.is_hit else 'miss'}")
+save = eng.roll_save(modifier=3, dc=13)
+print(f"save +3 vs DC 13   = {save.roll.total} → {'pass' if save.is_success else 'fail'}")
+
+# Critical damage doubles the dice
+crit = eng.roll_damage("2d8", is_critical=True)
+print(f"crit 2d8   = {crit.roll.total}  (rolled as {crit.roll.dice_results[0].dice_group})")
+
+# A full ability-score array
+array = eng.roll_stat_array("4d6kh3")
+print("stat array =", list(array.scores))

dndwright-0.4.0/examples/export_graph.py

@@ -0,0 +1,21 @@
+"""Render the 135-node computation DAG as Mermaid or Graphviz DOT.
+
+    python examples/export_graph.py                # Mermaid to stdout
+    python examples/export_graph.py | dot -Tsvg    # (with --dot) → SVG via Graphviz
+
+Or use the CLI: ``dndwright graph --format dot``.
+"""
+
+import sys
+
+from dndwright import DND_5E_2024_RULESET, to_dot, to_mermaid
+
+if "--dot" in sys.argv:
+    print(to_dot(DND_5E_2024_RULESET))
+else:
+    # Just the first lines — the full graph is large (135 nodes).
+    text = to_mermaid(DND_5E_2024_RULESET)
+    print("\n".join(text.splitlines()[:12]))
+    print("...")
+    print(f"\n({len(DND_5E_2024_RULESET.nodes)} nodes total — "
+          "pipe `dndwright graph --format dot | dot -Tsvg` for the full picture)")