foxclaw 0.1.2 → 0.1.4

package/python/bench/cd_audit.py

@@ -14,8 +14,6 @@ from hkc.hkc_kde.extractor import Extractor
 from hkc.hkc_api.ingest_jobs import IngestJobRegistry
 
 
-# ── D1: IngestJobRegistry 4 thread 并发 ────────────────
-
 def d1_ingest_4_workers():
     """D1. 4 worker 真并发 peak=4,4 任务 ~0.3s 完成"""
     reg = IngestJobRegistry(max_workers=4)
@@ -36,7 +34,6 @@ def d1_ingest_4_workers():
     t0 = time.time()
     for j in jobs:
         reg.submit(j, work)
-    # wait done
     while True:
         statuses = [reg.get(j.job_id)["status"] for j in jobs]
         if all(s == "done" for s in statuses):
@@ -49,8 +46,6 @@ def d1_ingest_4_workers():
     print(f"  D1 PASS: peak={peak[0]}, 4 jobs in {elapsed*1000:.0f}ms (串行需 1.2s)")
 
 
-# ── D2: Extractor 16 chunk 限流雪崩 ────────────────────
-
 def d2_429_snowball():
     """D2. 16 chunk × 4 worker × 100% 429 永不成功,验证不死循环 + 总调用有上界"""
     state = {"calls": 0}
@@ -62,8 +57,6 @@ def d2_429_snowball():
         raise err
 
     ext = Extractor(provider="anthropic", model="m")
-    # 替换 _extract_chunk:走 _retry_llm 但传极小 base_delay 测试用
-    # 同时 monkey-patch time.sleep 避免真睡
     import hkc.hkc_kde.extractor as ex_mod
     orig_sleep = ex_mod.time.sleep
     sleeps = []
@@ -88,7 +81,6 @@ def d2_429_snowball():
         result = ext.extract(chunks)
         elapsed = time.time() - t0
 
-        # 期望:16 chunk 全 fail,总调用 = 16 * (1+3 retry) = 64,无死循环
         success = sum(1 for item in result.items if item is not None)
         assert success == 0, f"expected 0 success, got {success}"
         assert state["calls"] == 64, f"snowball: expected 64 calls, got {state['calls']}"
@@ -99,17 +91,13 @@ def d2_429_snowball():
         ex_mod.time.sleep = orig_sleep
 
 
-# ── D3: progress_cb 线程安全 ─────────────────────────
-
 def d3_progress_cb_thread_safe():
     """D3. progress_cb 在 as_completed 循环调,主线程串行;16 chunk 计数无重复无漏"""
     ext = Extractor(provider="anthropic", model="m")
 
-    # 替换 _extract_chunk 为 fast mock:50% 概率 fail(模拟 chunk 失败)
     import random
     random.seed(42)
     def mock_extract(chunk, timeout=60.0):
-        # 永远返 RawExtraction
         from hkc.hkc_kde.models import RawExtraction
         return RawExtraction()
     ext._extract_chunk = mock_extract
@@ -131,21 +119,16 @@ def d3_progress_cb_thread_safe():
     chunks = [MockChunk(i) for i in range(16)]
     result = ext.extract(chunks, progress_cb=cb)
 
-    # 验证:done_calls 长度 16(每个 chunk 一次)
     assert len(done_calls) == 16, f"expected 16 callbacks, got {len(done_calls)}"
-    # 验证:1..16 各一次(set 大小 = 16,排序后 1..16)
     assert sorted(done_calls) == list(range(1, 17)), \
         f"expected processed 1..16, got {sorted(done_calls)}"
     print(f"  D3 PASS: {len(done_calls)} callbacks, all 1..16 unique")
 
 
-# ── D4: max_retries 可调 ──────────────────────────────
-
 def d4_max_retries_configurable():
     """D4. _retry_llm 的 max_retries 真的生效"""
     ext = Extractor(provider="mock", model="m")
 
-    # 测 max_retries=2(默认 3):4 次后 raise
     call_count = [0]
     def always_fail():
         call_count[0] += 1
@@ -153,7 +136,6 @@ def d4_max_retries_configurable():
         err.status_code = 429
         raise err
 
-    # 用 monkey-patch 把 time.sleep 替换掉,这样不会真睡
     import hkc.hkc_kde.extractor as ex_mod
     orig_sleep = ex_mod.time.sleep
     sleeps = []
@@ -164,7 +146,6 @@ def d4_max_retries_configurable():
             assert False, "expected raise"
         except Exception:
             pass
-        # max_retries=2 + 1 = 3 次尝试
         assert call_count[0] == 3, f"max_retries=2 expected 3 calls, got {call_count[0]}"
         assert len(sleeps) == 2, f"max_retries=2 expected 2 sleeps, got {len(sleeps)}"
         print(f"  D4 PASS: max_retries=2 -> 3 calls, 2 sleeps")
@@ -172,8 +153,6 @@ def d4_max_retries_configurable():
         ex_mod.time.sleep = orig_sleep
 
 
-# ── D5: retry + progress_cb 顺序 ─────────────────────
-
 def d5_retry_no_progress_leak():
     """D5. retry 期间 progress_cb 仍只调 1 次/chunk(不管 retry 几次)"""
     import time as time_mod
@@ -209,9 +188,7 @@ def d5_retry_no_progress_leak():
                 cb_count[0] += 1
         chunks = [MockChunk(i) for i in range(8)]
         result = ext.extract(chunks, progress_cb=cb)
-        # 不管 retry 几次,每个 chunk 调 1 次 progress_cb
         assert cb_count[0] == 8, f"expected 8 progress, got {cb_count[0]}"
-        # 8 chunk 全 fail,总调用 = 8 * 4 = 32
         assert state["calls"] == 32, f"expected 32 calls, got {state['calls']}"
         success = sum(1 for item in result.items if item is not None)
         assert success == 0

package/python/bench/chaos.py

@@ -21,7 +21,6 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-# 关闭联网触发(chaos 只测 LLM 咽喉,不触发搜索)
 import foxclaw.core.web_search as ws  # noqa: E402
 ws.needs_search = lambda q: False
 
@@ -37,7 +36,7 @@ def _make_router(primary="deepseek", fallback=None):
     if fallback:
         os.environ[PROVIDER_ENV[fallback]] = "chaos-test-key"
     r = ModelRouter(provider=primary)
-    r._client = object()                     # 使 is_stub == False
+    r._client = object()
     r._clients[primary] = object()
     if fallback:
         r._clients[fallback] = object()
@@ -87,11 +86,11 @@ def case4_circuit_breaker():
     """[4] 断路器:provider 失败后进入冷却,立即重试被跳过(不再紧密重试)。"""
     r = _make_router("deepseek")
     r._call_provider = _boom
-    r.complete(_SYS, _MSG)                    # 第一次失败 → 进入 cooldown
+    r.complete(_SYS, _MSG)
     cooled = "deepseek" in r._cooldown
     t0 = time.perf_counter()
-    r.complete(_SYS, _MSG)                    # 第二次:cooldown 未过期 → 直接跳过,不等超时
-    fast = (time.perf_counter() - t0) < 0.5   # 跳过热 provider,应远快于真实超时
+    r.complete(_SYS, _MSG)
+    fast = (time.perf_counter() - t0) < 0.5
     ok = cooled and fast and r.is_degraded()
     return ok, (f"冷却中={cooled} 跳过耗时={((time.perf_counter()-t0)*1000):.0f}ms"), "断路器生效"
 
@@ -101,11 +100,10 @@ def case5_recovery():
     r = _make_router("deepseek")
     r._call_provider = _boom
     r.complete(_SYS, _MSG)
-    assert "deepseek" in r._cooldown           # 先确认在冷却
-    r._cooldown["deepseek"] = 0                # 模拟冷却过期
+    assert "deepseek" in r._cooldown
+    r._cooldown["deepseek"] = 0
     r._call_provider = lambda *a, **k: ("恢复后的正常回复", None)
     out = r.complete(_SYS, _MSG)
-    # 注:degraded 是「曾降级」的累积运维标志(不因恢复清零),恢复语义看「解冻 + 成功返回」。
     ok = (out == "恢复后的正常回复") and ("deepseek" not in r._cooldown)
     return ok, ("解冻=" + str("deepseek" not in r._cooldown)), out[:40]
 

package/python/bench/e2e_real_models.py

@@ -26,7 +26,6 @@ from foxclaw.core.model_router import ModelRouter  # noqa: E402
 _SYS = "你是 Foxclaw 助手。"
 _MSG = [{"role": "user", "content": "请只回复两个字：你好"}]
 _MAX_TOKENS = 64
-# stub/故障 的特征文案(出现即视为"非真实成功")
 _BAD_MARKERS = ("【未执行】", "【模型返回为空】", "【全部模型失败】", "【模型流式中断】", "STUB")
 
 

package/python/bench/llm_retry_test.py

@@ -19,8 +19,6 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'vendor'))
 from hkc.hkc_kde.extractor import Extractor
 
 
-# ── Mock 异常类型 ────────────────────────────────────
-
 class FakeResponse:
     def __init__(self, headers=None):
         self.headers = headers or {}
@@ -53,7 +51,6 @@ class FakeRateLimitName(Exception):
     """模拟 openai.RateLimitError(type name 含 'RateLimit',无 status_code)"""
     def __init__(self, msg="rate"):
         super().__init__(msg)
-        # 不设 status_code;靠 type name 'RateLimit' 识别
 
 
 class FakeValueError(Exception):
@@ -63,9 +60,6 @@ class FakeValueError(Exception):
         self.status_code = 400
 
 
-# ── 测试实例化 ───────────────────────────────────────
-# KnowledgeExtractor __init__ 不调 LLM,只是记 provider/model 配置
-# _retry_llm 是 instance method,任意实例都能调
 ext = Extractor(provider="mock", model="mock-model")
 
 
@@ -133,8 +127,8 @@ def t3_429_exhaust():
             assert False, "应该 raise"
         except Fake429Error:
             pass
-        assert calls[0] == 4  # 1 + 3 retries
-        assert len(sleeps) == 3  # 3 次 retry 才 sleep
+        assert calls[0] == 4
+        assert len(sleeps) == 3
         print("  3. 429 4 次后 raise (1+3 retry): PASS, calls={}, sleeps={}".format(calls[0], sleeps))
     finally:
         restore_sleep(ex, original)
@@ -207,7 +201,6 @@ def t8_backoff():
             ext._retry_llm(func, max_retries=3, base_delay=1.0, max_delay=3.0)
         except Fake429Error:
             pass
-        # 3 次 retry:sleeps = [1, 2, 3] (4 cap at max_delay=3)
         assert sleeps == [1.0, 2.0, 3.0], f"expected [1,2,3], got {sleeps}"
         print("  8. 退避 1→2→3 (max_delay cap): PASS, sleeps={}".format(sleeps))
     finally:

package/python/bench/load_test.py

@@ -23,13 +23,12 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 PORT = int(os.environ.get("FOXCLAW_BENCH_PORT", "8231"))
 BASE = f"http://127.0.0.1:{PORT}"
 
-# 一批覆盖不同分诊路径的任务模板（每个请求附唯一编号,便于校验会话唯一性）
 TEMPLATES = [
-    "分析本月理财预算与收支",       # finance
-    "总结这篇论文的核心要点",       # office
-    "安排明天上午的会议日程",       # admin
-    "整理并汇总这批资料",           # assistant
-    "你能做什么",                   # supervisor 自答(meta)
+    "分析本月理财预算与收支",
+    "总结这篇论文的核心要点",
+    "安排明天上午的会议日程",
+    "整理并汇总这批资料",
+    "你能做什么",
 ]
 
 
@@ -46,7 +45,6 @@ def _start_server():
     import uvicorn
     os.environ.setdefault("FOXCLAW_DATA_DIR", tempfile.mkdtemp())
     os.environ["FOXCLAW_SHADOW_ROUNDS"] = "50"
-    # 不配任何 LLM key → Router 自动降级 stub(不联网、瞬时返回)
     for k in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "DEEPSEEK_API_KEY",
               "GOOGLE_API_KEY", "DASHSCOPE_API_KEY"):
         os.environ.pop(k, None)
@@ -132,7 +130,6 @@ async def main_async(total, concurrency):
         print("✗ 服务未就绪"); return 1
     print("服务就绪。先测单请求基线(concurrency=1)...")
 
-    # 基线:串行 10 个请求,量"单请求真实成本"(无并发争用),用于解释并发下的延迟来源
     base = await _run_load(10, 1)
     base_lat = base["latencies"]
     base_p50 = _pct(base_lat, 50)

package/python/bench/vector_ivf_upgrade.py

@@ -21,10 +21,8 @@ import time
 from pathlib import Path
 from types import SimpleNamespace
 
-# 必须在 import VectorIndex 之前设,否则模块级常量已固化
 os.environ["HKC_VECTOR_IVF_THRESHOLD"] = "500"
 
-# 让 vendor.hkc.* 可导入(脚本放在 bench/,不在 vendor 树内)
 ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT))
 
@@ -70,7 +68,6 @@ def main() -> None:
     idx = VectorIndex(backend=backend)
     print(f"index type 初始: {type(idx._index).__name__}")
 
-    # ── Phase 1: append < threshold,保持 Flat ──────────────────
     phase1_n = threshold - 1
     print(f"\n[Phase 1] append {phase1_n} 条(< {threshold},应保持 Flat)...")
     for ku in kus[:phase1_n]:
@@ -79,7 +76,6 @@ def main() -> None:
     med, mn, mx = bench_search(idx, "find something about topic 7")
     print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
 
-    # ── Phase 2: append 触发升级 Flat → IVF ──────────────────
     print(f"\n[Phase 2] append 第 {threshold} 条(应触发升级)...")
     t0 = time.perf_counter()
     idx.append_ku(kus[phase1_n])
@@ -91,7 +87,6 @@ def main() -> None:
     med, mn, mx = bench_search(idx, "find something about topic 7")
     print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
 
-    # ── Phase 3: append 1000 条,验证 IVF 追加正常 ──────────────────
     rest = N - threshold
     print(f"\n[Phase 3] append {rest} 条(应直接 add 到 IVF)...")
     t0 = time.perf_counter()
@@ -103,7 +98,6 @@ def main() -> None:
     med, mn, mx = bench_search(idx, "find something about topic 7")
     print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
 
-    # ── Phase 4: save/load roundtrip(IVF 必须正确持久化) ──────────────────
     print(f"\n[Phase 4] save/load roundtrip(IVF 持久化)...")
     with tempfile.TemporaryDirectory() as td:
         p = str(Path(td) / "vec")
@@ -120,7 +114,7 @@ def main() -> None:
         print(f"  loaded ntotal={n_loaded}, type={type_loaded}")
         if n_loaded != N:
             print(f"  [FAIL] 数据丢失! 期望 {N} 实际 {n_loaded}")
-        elif "FlatIP" in type_loaded:   # 严格判:IndexFlatIP 才算 Flat(IndexIVFFlat 含 "Flat" 字符串,要排除)
+        elif "FlatIP" in type_loaded:
             print(f"  [FAIL] IVF 没保存,降回 FlatIP")
         else:
             print(f"  [OK] IVF 完整保存/加载(ntotal={n_loaded}, type={type_loaded})")

package/python/docs/CONTENT_GUARD.md

@@ -0,0 +1,189 @@
+# Content Gate and Lexicons
+
+This layer does one thing: it makes a deterministic decision on **both the user request and the model output**, and cuts the turn off with a fixed line when something matches.
+
+It does not call a model, does not do semantic understanding, and does not replace platform review or human moderation. The prompt layer keeps the model from crossing the line on its own; this layer holds the floor when either the model or the user gets around the prompt.
+
+## Three sources of judgement
+
+| Source | Where | Configurable | Covers |
+|---|---|---|---|
+| Built-in rules | `_BUILTIN_RULES` in `foxclaw/core/content_guard.py` | No (only `off` disables them) | Six **request-shaped** categories: drug/explosive manufacturing, fraud and money laundering, intrusion into someone else's systems, forged documents, suicide methods, sexual content involving minors |
+| External lexicon | Files listed in `FOXCLAW_CONTENT_LEXICON` | Yes | Whatever you decide — political, sexual, violent categories all live here |
+| Prompt | `KERNEL_PROMPT` §8 (Content boundaries) | Code change | Soft constraint; owns the tone and the refusal pattern |
+
+The built-in rules are deliberately narrow: a **verb plus a target** has to appear together. "How do I make explosives" matches; "I bought a book on the history of explosives" does not. The goal is something that works out of the box without interrupting ordinary conversation, not full coverage of every violative phrasing.
+
+**Large category lists are not built in.** Review requirements change, the blast radius of false positives is a deployment decision, and tens of thousands of terms do not belong in source. Whether to mount them, and which categories, is your call.
+
+## Default behaviour
+
+It is on out of the box, with no configuration:
+
+- mode defaults to `enforce`
+- only the built-in rules run when no lexicon is mounted
+- a request that matches returns the fixed line immediately — **the request never reaches the model**
+- an output that matches is replaced in full; no fragment of the original survives
+- a streamed output that matches stops emitting at the match
+
+The refusal follows the input language and exists in exactly two forms: `Let's talk about something else.` / `我们换个话题聊聊吧。`
+
+No explanation, no elaboration, no counter-question, no alternative offered. A refusal must not become a channel for leaking information or continuing the thread.
+
+## Three modes
+
+```bash
+FOXCLAW_CONTENT_GUARD_MODE=enforce   # default: actually block
+FOXCLAW_CONTENT_GUARD_MODE=audit     # record only, for measuring false positives
+FOXCLAW_CONTENT_GUARD_MODE=off       # disabled
+```
+
+An unrecognised value falls back to `enforce` — it over-blocks rather than failing silently.
+
+`audit` hits are written to the **process stdout**:
+
+```
+[Foxclaw] ⚠ 内容命中(未拦截): category=politics word='...'
+```
+
+Only `audit` prints. `enforce` hits are silent. If you need an audit trail, wire `Decision.to_dict()` at the call site, or run `audit` for a while to collect a baseline first.
+
+## Where to put the configuration
+
+Two paths, different behaviour:
+
+- **`.env` (recommended)**: the API service loads `.env` before importing the package, so values placed there take effect. Empty values count as "not configured" and never override a real environment variable.
+- **Process environment**: when you use `Foxclaw()` from the SDK, `.env` is not loaded for you — export the variables before the process starts.
+
+The `.env` load can be skipped with `FOXCLAW_SKIP_DOTENV=1`.
+
+## Lexicon format
+
+One term per line, UTF-8, `#` for comments:
+
+```
+# term<TAB>category; the category is optional
+some-term	politics
+another-term	sexual
+term-without-category
+```
+
+The details below come from the loader, not from convention:
+
+| Item | Behaviour |
+|---|---|
+| Separator | `term<TAB>category`; with no TAB the whole line is the term and the category becomes `platform` |
+| Comments | lines starting with `#` are skipped |
+| Whitespace and punctuation | every term goes through `compact()`: whitespace and CJK/ASCII punctuation stripped, NFKC-normalised, lowercased |
+| Length | anything shorter than 2 characters **after** `compact()` is dropped (single characters cause too much collateral damage and rarely catch real violations) |
+| Same term, several categories | allowed; scan results are deduplicated by `(category, term)` and the first hit wins |
+| Bad lines, unreadable files | skipped silently — a bad lexicon must not prevent the service from starting |
+| When it takes effect | the index is built **at process start**; editing a lexicon requires a restart, there is no hot reload |
+
+Prefer **absolute paths**. Relative paths resolve against the process working directory, which under systemd is often not the project root.
+
+After a restart, confirm how many terms actually loaded:
+
+```bash
+python -c "from foxclaw.core.content_guard import ContentGuard as C; print(C().lexicon_size)"
+```
+
+`0` means nothing was read.
+
+## Converting a third-party list
+
+Existing lists — the ~60k-term main dictionary of `houbb/sensitive-word`, or the versions already split into political / sexual / violent files — come in incompatible shapes: single file of bare terms or one file per category, GBK encoding, and the same term written three ways (`敏感词`, `敏 感 词`, `ＳＥＮＳＩＴＩＶＥ`).
+
+`tools/build_content_lexicon.py` does the conversion. **The script lives in the repository and is not shipped in the wheel** — if you installed from PyPI, take it from the GitHub repository:
+
+```bash
+# single-file dictionary, everything under the `platform` category
+python tools/build_content_lexicon.py sensitive_word_dict.txt -o content_lexicon.txt
+
+# per-category files: a CJK file name becomes the category (政治类.txt → 政治类)
+python tools/build_content_lexicon.py dict/*.txt -o content_lexicon.txt
+
+# keep only what you want
+python tools/build_content_lexicon.py dict/*.txt --exclude 政治类,色情类 --exclude "暴力*" -o content_lexicon.txt
+
+# single file, explicit category name
+python tools/build_content_lexicon.py ads.txt --category ads -o content_lexicon.txt
+```
+
+It does four things:
+
+1. **Detects the encoding**: `utf-8-sig` first, then `gb18030`. Many lists downloaded inside China are GBK, while the loader reads UTF-8 and ignores undecodable bytes — skip this step and terms go missing silently after mounting.
+2. **Normalises during conversion**, using the loader's own `compact()`, so duplicate spellings collapse now instead of bloating the automaton later.
+3. **Filters by category**: `--include` / `--exclude` accept wildcards, comma-separated and repeatable.
+4. **Verifies by reading back**: loads the output through a real `ContentGuard` and samples terms to confirm they still match; exits with code 1 if that fails.
+
+Common options:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `-o, --output` | `content_lexicon.txt` | output path |
+| `--category` | `platform` | category used when a file name has no CJK characters |
+| `--include` / `--exclude` | none | category filters, wildcards supported |
+| `--encoding` | `auto` | force a specific codec |
+| `--min-len` | `2` | drop shorter terms (matches the loader) |
+| `--max-len` | `0` | drop longer terms, `0` means no limit |
+| `--sample` | `5` | terms sampled during verification |
+| `--no-verify` | off | skip the read-back check |
+
+At 60k terms, conversion plus load and verification takes about half a second.
+
+Generated lexicons are ignored by git (`/content_lexicon*.txt`). Do not commit them.
+
+## Run `audit` before you enforce
+
+**This is the step most likely to be skipped, and the most expensive to skip.**
+
+A 60k-term list inevitably contains a lot of two-character terms. Mount it under `enforce` and ordinary order discussions, manuscript reviews, or medical questions will get cut off — the whole output is replaced, the user gets no explanation, only a sudden "let's talk about something else".
+
+Suggested sequence:
+
+1. mount the lexicon, set `FOXCLAW_CONTENT_GUARD_MODE=audit`
+2. use the product normally for a few days, collect the hit lines from stdout
+3. review `category` and `word` for each: genuine violation or collateral damage
+4. drop the noisy categories with `--exclude`, or regenerate with longer terms
+5. switch to `enforce` once the rate is acceptable
+
+There is no allowlist mechanism. The only levers against false positives are: mount fewer categories, use longer terms, raise `--min-len`.
+
+## Fidelity, stated plainly
+
+This is a **speed bump**, not a wall. It explicitly does not handle:
+
+- pinyin, homophones, split characters, transliteration (endless, and worse for false positives)
+- images, audio, attachment bodies
+- multi-turn grooming (splitting a sentence across three turns)
+- books, statutes, and medical texts imported into the knowledge base
+
+That last point is intentional: **the filter only sits on "user request" and "model output"**, and never touches the user's own material. A history book that describes an explosive formula should not fail to import.
+
+Streaming has an inherent limit: at the moment of the match it can only guarantee that nothing further is emitted — **a prefix already streamed out cannot be recalled**. The non-streaming path replaces the whole output and has no such gap.
+
+## Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| Nothing is blocked at all | is `FOXCLAW_CONTENT_GUARD_MODE` set to `off`; did the variable actually reach the process |
+| Built-in rules fire, lexicon does not | is `lexicon_size` 0; relative vs absolute path; file encoding |
+| Some mounted terms never match | was the term under 2 characters after `compact()`; did a space become part of the term |
+| Edited the lexicon, nothing changed | the process was not restarted; the index is built at start |
+| Normal conversation gets cut | too many two-character terms; switch to `audit` and drop that category |
+
+## Relationship to the prompt layer
+
+Different jobs, both required:
+
+- the prompt layer (`KERNEL_PROMPT` §8 plus `no_harmful_content` in `behavior.yaml`) owns the semantic boundary: what counts as violative, how a refusal should sound, how to tell the user's material from the user's instructions.
+- the code layer (this document) owns the deterministic floor: a match is a match, no model judgement involved.
+
+With only the prompt, a successful jailbreak leaves nothing behind it. With only the code, every edge case lives or dies by the lexicon, and answers turn mechanical. Together, the model knows where the line is and there is a backstop when it crosses anyway.
+
+## Scope of responsibility
+
+This repository ships no political, sexual, or violent term list. Whether to mount one, which categories, and which mode are deployment decisions — no policy is assumed here.
+
+The layer is string matching after normalisation: it does not guarantee coverage and is not a content moderation or compliance service. Deployers who expose the service publicly are responsible for their own content compliance. The software is provided "as is", see [LICENSE](../LICENSE).