zh-narrative-guard

Zero-dependency, deterministic consistency checkers for Chinese narrative text — the kind of self-consistency bugs an LLM produces while writing roleplay or fiction. Pure functions in, findings out. No LLM, no I/O, no state machine.

• No dependencies. Pure standard library (re, dataclasses).
• Deterministic. Same text always yields the same findings — safe to run in a hot path.
• Advisory, not destructive. Every checker reports; it never rewrites your text.
• Dormant when irrelevant. The weekday checker stays silent unless the text actually pins a concrete weekday, so calendar-free settings pay nothing.

The design philosophy: prefer a miss to a misfire (宁漏勿误)

Chinese single characters are hopelessly polysemous as signals:

Treating any single character as a time signal produces false positives, and these detectors were forged by fixing three successive production bug families that were all exactly that. So the rule throughout is: a missed issue is recoverable downstream, a false alarm directly harasses the writer. Every checker here errs toward silence.

Concretely, a time value is only accepted when it is a time-shaped token — a quantity + unit + after/before (三天后), an ordinal chapter/day (第3章 / 第二天), a year (公元1024年), a clock time (八点半), or a named time-of-day / season (清晨 / 傍晚 / 入冬). A lone polysemous character is never enough. Likewise a recall/flashback/fantasy framing (回想 / 梦见 / 想象) suppresses time-jump detection entirely — reminiscing is not jumping.

Install

pip install zh-narrative-guard

Requires Python 3.10+.

Quickstart

from zh_narrative_guard import (
    detect_time_directives,
    is_recall_framing,
    detect_weekday_violations,
    detect_cliche_violations,
)

# 1. Explicit "jump the timeline to <T>" directives.
d = detect_time_directives("时间跳到三天后")
assert d[0].target == "三天后"

# ...but action narration and flashbacks are NOT jumps:
assert detect_time_directives("进入后先用真气感知四周环境") == []
assert is_recall_framing("我继续回想:在进入主神空间前的日子")

# 2. Weekday arithmetic the model got wrong.
v = detect_weekday_violations("今天周日，明天周六")
assert v[0]["expected_name"] == "周一" and v[0]["claimed_name"] == "周六"
# Dormant with no concrete "today = 周X" anchor (fantasy / xianxia):
assert detect_weekday_violations("三天后我们在城门口集合") == []

# 3. Clichéd simile phrasing (surface it, do not strip).
assert detect_cliche_violations("他像投石入水般沉了下去")
# Literal usage and function words are never flagged:
assert detect_cliche_violations("他用投石机攻城") == []
assert detect_cliche_violations("如果投石入水就糟了") == []

API

timeline

weekday

Each weekday violation is {"rel", "match", "claimed", "expected", "claimed_name", "expected_name", "base_name"}.

cliche

Each cliché violation is {"pattern_label", "match", "position"}.

Behavior differences from the source platform

This library is extracted from a Chinese roleplay platform. Two deliberate changes were made for the general case:

1. Dropped book-specific timeline tokens. The source _TIME_TOKEN also matched a novel's place-name timeline labels (柏林 / 图卢兹 / 基地). In ordinary prose those are pure false positives (柏林墙倒塌那年, 回到基地), so they are removed here.
2. Fixed a simile false positive. The source simile marker 如同? also matched the lone 如 inside the common function words 如果 (if), 例如 (for example), 假如 (if), 如今 (nowadays), flagging non-similes such as "如果投石入水就糟了". The marker is now guarded (如同 plus a bare 如 with look-behind/look-ahead against those function words), while real similes — 像投石, 如同投石, literary bare 如投石问路 — still match.

Known limitations

Consistent with prefer a miss to a misfire: the weekday token accepts only ASCII 1-7, so full-width (周６) or Arabic-Indic (周٦) digits are silently missed rather than mis-checked (a miss is the safe direction). Chinese numerals (周三) and ASCII (周3) are fully supported.

License

MIT — see LICENSE.

Acknowledgements

Extracted from the RPG Roleplay platform (https://github.com/felixchaos/rpg-roleplay-platform).