Charactercheck

CharacterCheck

Agents start here → [SKILL.md](SKILL.md) — when to call this, worked examples, MUST/MUST NOTs. Family contract: FAMILY.md.

CharacterCheck is an experimental, read-only compiler for selected D&D Beyond character-sheet fields. It turns a public share, saved character-service JSON, or versioned snapshot into deterministic mechanical context with provenance and named findings.

Current release: 0.7.0. Pin charactercheck==0.7.0 when installation

must be reproducible. Verify the installed package version and each field's

trust state; a version string alone is not proof that a value is supported.

It is not a complete or rules-authoritative character validator. Its output is not encounter, world, or session state and does not prove that an action is legal. Unknown upstream fields and unsupported restrictions can affect results; read the trust and finding data before using a value.

Run 0.7.0 offline

Python 3.9 or newer is required. The runtime has no third-party dependencies.

git clone https://github.com/chaoz23/charactercheck

cd charactercheck python3 -m charactercheck selftest python3 -m charactercheck derive examples/sample-character.json --brief

The bundled example is project-authored synthetic data. The smoke test checks this checkout and selected derivations; it is not evidence of complete D&D rules correctness.

Install the published package into a virtual environment for the console entry points:

python3 -m venv .venv

.venv/bin/python -m pip install charactercheck==0.7.0 .venv/bin/charactercheck derive examples/sample-character.json --brief

The direct python3 -m charactercheck path from a clone has no runtime dependency install. An editable pip install may bootstrap the setuptools build frontend if the environment does not already provide it. See MIGRATING.md before comparing 0.7.0 output or MCP surfaces with 0.6.x.

For an explicitly public character:

python3 -m charactercheck derive https://www.dndbeyond.com/characters/<id>

Public sharing permits retrieval at that moment; it does not establish consent for publication, recurring tests, persistence, model training, or reuse of persona and third-party narrative content.

CharacterCheck requests no credentials. For a private sheet, use an authorized saved character-service JSON file through the local CLI or library; do not pass cookies, tokens, or session data.

Product and authority boundary

CharacterCheck currently supports mechanical, read-only preparation for a human or AI-controlled DM, PC, or NPC. It observes a character source and emits context or reconciliation candidates. It exposes no mutation tools and does not become the authority for HP, conditions, concentration, expended resources, equipment declarations, DM rulings, encounter state, or world state.

The human principal remains responsible for access and use. An AI actor must not infer permission, role, or visibility from sheet contents or a tool argument. Where a value is marked confirm, unsupported, unknown, or invalid, the agent should ask the named human authority or decline to use the value. Manual play without CharacterCheck remains the fallback.

Ecosystem and calculation boundary

CharacterCheck is being developed as a versioned D&D Beyond-to-agent compiler and conformance facade, not a new complete 5e rules engine. The strict source/snapshot/privacy/trust layer remains local. Adapter vocabulary is seeded from a pinned offline DDB config registry that was independently observed and cross-checked against the MIT-licensed DDB Importer fallback. The production runtime never fetches that config endpoint. The distributed registry is a purpose-limited allowlist for current evaluator branches—not a copy of DDB's full configuration or third-party catalog vocabulary.

Registry membership establishes only that an upstream ID/name was observed; it does not prove that CharacterCheck implements its mechanics. Bounded unknown IDs are retained as opaque adapter evidence, fixed semantic-gap codes prevent default calculations, and unsafe formula/property prose is omitted. Current weapon proficiency/hand state and unimplemented property semantics therefore remain explicitly unsupported even when a provisional attack line can be rendered.

The next mechanics work is a differential conformance spike using exact SRD revisions, narrow MIT-compatible DDB Importer evidence, and Foundry dnd5e as a versioned model/behavior oracle. DDB/displayed and third-party calculated values are attributed claims, not unquestionable truth; disagreement must become a non-trusted conflict. See ECOSYSTEM_CONFORMANCE.md SOURCE_FIELD_ROUTING.md, and THIRD_PARTY_NOTICES.md.

The observed DDB service/config surfaces remain undocumented and unsupported as public APIs. Their technical availability does not grant commercial access, content rights, stability, or consent. A commercial build needs a licensed or counsel-approved input/update path and should prefer an authorized user/host export until then.

Inputs

The input parser accepts exactly:

• a positive 1–20 digit character ID with no leading zero;
• an HTTPS URL on dndbeyond.com or www.dndbeyond.com whose path is exactly /characters/ ;
• a direct local regular JSON file, when the calling surface permits files; or
• a CharacterSnapshotV1 JSON file.

Local symbolic links are rejected. Missing paths are not reinterpreted as IDs. Raw local character files and HTTP responses are bounded to 8 MiB; a local CharacterSnapshotV1 envelope may be up to 16 MiB so a maximum-size filtered source can round-trip with its metadata. JSON also has depth, node, string, collection, inventory, modifier, and container-traversal limits.

Commands

--pipe reads refs from standard input. charactercheck --schema emits the machine-readable CLI contract.

--table-evaluation is also accepted by report. It projects canonical field states and source/policy digests, never character values. Trusted fields count as evaluated; unsupported, unknown, invalid, and non-authority confirmation states fail closed. Mutable player-authority fields are outside the evaluator's scope and become advisories requiring player/session-host reconciliation. The envelope is always self_attested; it is not proof of source identity, freshness, table role, encounter state, or action legality.

Question catalog

The Coverage Inventory pairs each of its 100 answers with the corresponding human-readable D&D 2024 character-sheet lookup question. Structured rows carry number, field, question, state, value, and content_trust. The question catalog is an organizational contract, not an assertion that the supplied JSON Schema's value types or the complete 2024 rules are implemented. An answer remains unusable when its row is unsupported, unknown, or invalid; mutable confirm rows remain player/session-host authority.

The settlement quiz also includes each sheet-specific lint question exactly once. Those prompts never receive an expected answer when their affected family is not trusted. Account identity and roleplay/persona questions remain privacy-omitted from default output.

Snapshots and diff

Capture a baseline and compare a later observation:

python3 -m charactercheck snapshot examples/sample-character.json > baseline.json

python3 -m charactercheck diff examples/sample-character.json --baseline baseline.json

CharacterSnapshotV1 records the adapter, source ID, source-schema fingerprint (which commits to the pinned adapter registry and semantic-gap contract), observation time, engine/rules profile, privacy classification, hashes, coverage, and a snapshot ID. Canonical derived metadata also exposes the adapter-registry fingerprint directly. Account identifiers and linked images are always removed. Persona is excluded by default. Snapshots do not migrate silently; unsupported versions fail with snapshot_schema. Observation times use canonical UTC RFC 3339 (...Z) syntax; they describe caller/source observation order, not a trusted timestamp or proof of freshness.

The hash meanings are intentionally distinct:

• source.normalized_data_hash is the canonical hash of the default privacy-filtered mechanical character. Projections use it as source_revision; it deliberately excludes persona and every omitted field.
• source.snapshot_character_hash hashes the exact filtered character stored in the snapshot, so an explicitly persona-inclusive snapshot can differ from the default mechanical revision.
• meta.snapshot_id covers the complete snapshot envelope except for the ID field itself, including observation metadata, privacy declarations, coverage, and the stored character.

These hashes are deterministic integrity/content identifiers, not signatures, attestations, or proof of source authenticity. A party able to edit a snapshot can recompute unkeyed hashes. Keep baselines in a trusted store and let an authenticated session host bind them to principals and audit history.

Snapshot filtering is closed at the top level and inside supported nested objects. source.coverage contains three booleans: unclassified_top_level_omitted, unclassified_nested_omitted, and semantic_values_omitted, plus a sorted scoped_mechanical_omissions list of canonical family names. It never carries omitted source names or values. Reviewed display/provenance omissions are trust-neutral; reviewed mechanical omissions add source:scoped-fields-omitted and route only listed families to unsupported. The first two booleans have unknown mechanical scope; derive adds the static source:unclassified-fields-omitted finding and routes every mechanical family to unknown. The third records unsafe semantic text removed after a fixed, field-scoped _semanticGaps code was retained; the item-semantic ledger routes the affected family to unsupported without copying the text. The same coverage appears as meta.source_coverage; a downstream view may not turn any incomplete observation back into trusted.

Diff is partial by design. Its coverage.classified list enumerates the coarse source families it can compare. When either of two distinct snapshots says an unclassified or reviewed scoped field o