kt-audit 0.1.0__tar.gz

kt_audit-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.sh text eol=lf
+*.bat text eol=crlf

kt_audit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Install
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+      - name: Type check
+        run: uv run basedpyright
+      - name: Test
+        run: uv run pytest --cov=kt_audit --cov-report=term-missing --cov-fail-under=85
+      - name: Build
+        run: uv build
+
+  wheel-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Wheel smoke
+        run: bash scripts/wheel-smoke.sh

kt_audit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,74 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+      - name: Build
+        run: uv build
+      - name: Check tag matches version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          version=$(uv run python -c "import kt_audit; print(kt_audit.__version__)")
+          test "v$version" = "$GITHUB_REF_NAME"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/kt-audit
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        run: uv publish --publish-url https://test.pypi.org/legacy/ --trusted-publishing always
+
+  publish-pypi:
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kt-audit
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

kt_audit-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.basedpyright/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+kt-audit-report/
+
+# local uv lock (regenerated per environment)
+uv.lock
+
+# local scratch
+.tmp/

kt_audit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+`kt-audit` is intentionally small. The v0.1 scope is frozen to three checks:
+
+- `temporal_split`
+- `multi_kc`
+- `alignment`
+
+A new check needs an issue with a concrete failure mode and a minimal example first. Please do not open a large refactor or a new framework PR.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest --cov=kt_audit --cov-report=term-missing
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+```
+
+## Rules
+
+- Keep runtime dependencies to `numpy`, `pandas`, and `scikit-learn`.
+- Add a test for every new branch. Synthetic data only; do not commit restricted datasets.
+- Every finding must have a severity, a count, and bounded examples.
+- Document limitations next to the check, not only in the README.
+- Disclose AI assistance in the PR body. The maintainer reviews every check definition and test.
+
+## Reporting a false positive
+
+Open an issue with:
+
+1. the command,
+2. the input schema (not the full private dataset),
+3. the actual finding,
+4. why you think it is wrong.
+
+A reproducible counterexample is more useful than a general complaint.

kt_audit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xia Jiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kt_audit-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: kt-audit
+Version: 0.1.0
+Summary: Audit knowledge-tracing evaluation before you trust the AUC.
+Project-URL: Homepage, https://github.com/summeriver13/kt-audit
+Project-URL: Repository, https://github.com/summeriver13/kt-audit
+Project-URL: Issues, https://github.com/summeriver13/kt-audit/issues
+Author: Xia Jiang
+License: MIT
+License-File: LICENSE
+Keywords: benchmark,education,evaluation,knowledge-tracing,leakage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: scikit-learn>=1.4
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.17; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kt-audit
+
+**Before you trust an AUC, audit the evaluation.**
+
+`kt-audit` is a small, opinionated audit tool for knowledge-tracing (KT) experiments. It does not train models. It checks whether the evaluation setup behind a reported AUC is trustworthy.
+
+Status: **alpha (0.1.0)**. The scope is intentionally narrow; see [docs/charter.md](docs/charter.md) for the scope and non-goals.
+
+## Why
+
+KT papers and libraries report AUC, but the evaluation protocol is often under-specified:
+
+- Are train events strictly before validation/test events for each user?
+- Does the same item appear in train and test?
+- When an item has multiple knowledge components (KCs), are some KCs train-only and others test-only?
+- Do the reported metrics match a recomputation from the released predictions?
+
+`kt-audit` turns those questions into a machine-readable report you can attach to a paper artifact, a PR, or a model release.
+
+## Install
+
+Not on PyPI yet. From source:
+
+```bash
+git clone https://github.com/summeriver13/kt-audit
+cd kt-audit
+uv sync
+uv run kt-audit --help
+```
+
+Or with pip:
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+uv run kt-audit run examples/leaky.csv --out /tmp/kt-audit-report
+```
+
+Output:
+
+```text
+verdict: fail
+findings: 6 error, 2 warn
+report: /tmp/kt-audit-report/report.md
+```
+
+The command writes:
+
+- `report.json` — stable, machine-readable.
+- `report.md` — human-readable, with examples and limitations.
+
+Exit codes: `0` pass/warn, `1` fail, `2` input/config error.
+
+## What it checks
+
+| Check | Catches | Default |
+| --- | --- | --- |
+| `temporal_split` | train timestamps after validation/test; users across splits | error / warn |
+| `multi_kc` | same item with train-only and test-only KCs | error |
+| `alignment` | missing/duplicate/out-of-range predictions; constant predictions; reported AUC mismatch | error / warn |
+
+Each finding has a `severity`, a `count`, and up to three examples.
+
+## Input
+
+One row per interaction or prediction. CSV or JSONL.
+
+| Column | Required | Notes |
+| --- | :--: | --- |
+| `user_id` | yes | non-null |
+| `timestamp` | yes | ISO8601 or numeric; comparable within a user |
+| `split` | yes | `train` / `valid` / `test` |
+| `kc_ids` | yes | pipe-separated KCs or JSON array |
+| `item_id` | no | needed for multi-KC check |
+| `y_true` | no | 0/1; required with `y_pred` |
+| `y_pred` | no | [0,1]; omit to skip metric checks |
+| `fold` | no | checks run per fold |
+| `sequence_id`, `position` | no | reserved for sequence checks |
+
+See [docs/data-contract.md](docs/data-contract.md) for the full contract.
+
+## Python API
+
+```python
+from kt_audit import AuditConfig, audit_path
+
+report = audit_path("events.csv", AuditConfig(reported_auc=0.80))
+print(report.verdict)
+for finding in report.findings:
+    print(finding.severity, finding.check, finding.count)
+```
+
+## Design constraints
+
+- Runtime dependencies: `numpy`, `pandas`, `scikit-learn`.
+- CLI uses `argparse`; config uses JSON.
+- Each check is a pure function over a prepared `DataFrame`.
+- Synthetic examples only; no dataset is bundled.
+- Findings are heuristics, not causal proof.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest --cov=kt_audit --cov-report=term-missing
+bash scripts/wheel-smoke.sh
+```
+
+## Release
+
+See [docs/release.md](docs/release.md). TestPyPI and PyPI publish through GitHub Actions trusted publishing.
+
+## Roadmap
+
+- v0.2: pyKT adapter, bootstrap AUC intervals, HTML report.
+- v0.3: duplicate interactions, cold-start, sequence truncation, label leakage.
+
+## AI disclosure
+
+AI tools are used in development. The maintainer reviews every check definition, test, and release. Findings generated by the tool are deterministic and do not call an LLM.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The v0.1 scope is frozen to the three checks above.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

kt_audit-0.1.0/README.md

@@ -0,0 +1,137 @@
+# kt-audit
+
+**Before you trust an AUC, audit the evaluation.**
+
+`kt-audit` is a small, opinionated audit tool for knowledge-tracing (KT) experiments. It does not train models. It checks whether the evaluation setup behind a reported AUC is trustworthy.
+
+Status: **alpha (0.1.0)**. The scope is intentionally narrow; see [docs/charter.md](docs/charter.md) for the scope and non-goals.
+
+## Why
+
+KT papers and libraries report AUC, but the evaluation protocol is often under-specified:
+
+- Are train events strictly before validation/test events for each user?
+- Does the same item appear in train and test?
+- When an item has multiple knowledge components (KCs), are some KCs train-only and others test-only?
+- Do the reported metrics match a recomputation from the released predictions?
+
+`kt-audit` turns those questions into a machine-readable report you can attach to a paper artifact, a PR, or a model release.
+
+## Install
+
+Not on PyPI yet. From source:
+
+```bash
+git clone https://github.com/summeriver13/kt-audit
+cd kt-audit
+uv sync
+uv run kt-audit --help
+```
+
+Or with pip:
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+uv run kt-audit run examples/leaky.csv --out /tmp/kt-audit-report
+```
+
+Output:
+
+```text
+verdict: fail
+findings: 6 error, 2 warn
+report: /tmp/kt-audit-report/report.md
+```
+
+The command writes:
+
+- `report.json` — stable, machine-readable.
+- `report.md` — human-readable, with examples and limitations.
+
+Exit codes: `0` pass/warn, `1` fail, `2` input/config error.
+
+## What it checks
+
+| Check | Catches | Default |
+| --- | --- | --- |
+| `temporal_split` | train timestamps after validation/test; users across splits | error / warn |
+| `multi_kc` | same item with train-only and test-only KCs | error |
+| `alignment` | missing/duplicate/out-of-range predictions; constant predictions; reported AUC mismatch | error / warn |
+
+Each finding has a `severity`, a `count`, and up to three examples.
+
+## Input
+
+One row per interaction or prediction. CSV or JSONL.
+
+| Column | Required | Notes |
+| --- | :--: | --- |
+| `user_id` | yes | non-null |
+| `timestamp` | yes | ISO8601 or numeric; comparable within a user |
+| `split` | yes | `train` / `valid` / `test` |
+| `kc_ids` | yes | pipe-separated KCs or JSON array |
+| `item_id` | no | needed for multi-KC check |
+| `y_true` | no | 0/1; required with `y_pred` |
+| `y_pred` | no | [0,1]; omit to skip metric checks |
+| `fold` | no | checks run per fold |
+| `sequence_id`, `position` | no | reserved for sequence checks |
+
+See [docs/data-contract.md](docs/data-contract.md) for the full contract.
+
+## Python API
+
+```python
+from kt_audit import AuditConfig, audit_path
+
+report = audit_path("events.csv", AuditConfig(reported_auc=0.80))
+print(report.verdict)
+for finding in report.findings:
+    print(finding.severity, finding.check, finding.count)
+```
+
+## Design constraints
+
+- Runtime dependencies: `numpy`, `pandas`, `scikit-learn`.
+- CLI uses `argparse`; config uses JSON.
+- Each check is a pure function over a prepared `DataFrame`.
+- Synthetic examples only; no dataset is bundled.
+- Findings are heuristics, not causal proof.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest --cov=kt_audit --cov-report=term-missing
+bash scripts/wheel-smoke.sh
+```
+
+## Release
+
+See [docs/release.md](docs/release.md). TestPyPI and PyPI publish through GitHub Actions trusted publishing.
+
+## Roadmap
+
+- v0.2: pyKT adapter, bootstrap AUC intervals, HTML report.
+- v0.3: duplicate interactions, cold-start, sequence truncation, label leakage.
+
+## AI disclosure
+
+AI tools are used in development. The maintainer reviews every check definition, test, and release. Findings generated by the tool are deterministic and do not call an LLM.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The v0.1 scope is frozen to the three checks above.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

kt_audit-0.1.0/docs/charter.md

@@ -0,0 +1,136 @@
+# kt-audit charter
+
+> 状态：draft，2026-10-20。目标：4 周 MVP，每周 2-4 小时。
+
+## 一句话
+
+**Before you trust an AUC, audit the evaluation.**
+
+## 问题
+
+知识追踪（KT）论文和库都在报 AUC，但评估协议不一致：
+
+- split 是否按时间？用户是否跨 split？
+- 一道题有多个知识点时，训练集和测试集是否共享了同一道题的不同 KC？
+- question-level 与 KC-level 的预测是否被混用？
+- 报告的 AUC 和用公开预测重算的 AUC 是否一致？
+
+pyKT 是事实上的 KT benchmark，但无 CI、几乎无测试、外部 PR 通道已冷。研究者需要一个**轻量、可机器读取、能放进论文 artifact** 的审计工具。
+
+## 用户
+
+- 准备投稿或放 artifact 的 KT 研究者。
+- 接 KT 模型做产品原型的工程师。
+- 复现实验、审稿、带学生的研究生。
+
+## 非目标
+
+- 不训练 DKT/AKT，不做模型库。
+- 不做 leaderboard，不托管数据集。
+- 不证明因果，只标记可疑模式。
+- v0.1 不做 LLM-KT 评估。
+- 不替代人工判断；报告里的 finding 是证据，不是判决。
+
+## MVP：三个检查
+
+| 检查 | 问题 | 默认严重度 |
+| --- | --- | --- |
+| temporal split | 同一用户的 train 事件是否晚于 valid/test？用户是否跨 split？ | error / warn |
+| multi-KC leakage | 同一道题是否同时含有 train-only 和 test-only 的 KC？ | error |
+| prediction alignment | 是否有缺失、重复、越界、常量预测？重算 AUC 是否与报告一致？ | error / warn |
+
+### 1. temporal split
+
+- 同一 user 的 `max(train timestamp) >= min(valid/test timestamp)`：error。
+- 同一 user 同时出现在多个 split：warn（可能是随机 split，也可能泄漏）。
+- 全局 split 时间区间重叠：warn。
+- 没有 `timestamp`：跳过并 warn。
+
+### 2. multi-KC leakage
+
+- 构建 `item_id -> set(kc_ids)`。
+- 同一道题的 KC 集合里，既有只在 train 出现的 KC，又有只在 test 出现的 KC：error。
+- 同一道题同时出现在 train 和 test：warn。
+- 没有 `item_id`：跳过并 warn。
+- 这是启发式，不是因果证明；报告必须写清。
+
+### 3. prediction alignment
+
+- `y_pred` 为 NaN/inf/越界：error。
+- 主键重复（`user_id + item_id + timestamp`）：error。
+- 预测常量（标准差为 0）：warn。
+- 可选 `reported_auc`：与重算 AUC 差值超过 tolerance：error。
+- 没有 `y_pred`：跳过指标检查。
+
+## 输入契约
+
+一行一个交互/预测。CSV 或 JSONL。
+
+| 列 | 必填 | 说明 |
+| --- | :--: | --- |
+| `user_id` | 是 | 用户 ID |
+| `timestamp` | 是 | ISO8601 或数值；同一用户内可比较 |
+| `split` | 是 | `train` / `valid` / `test` |
+| `kc_ids` | 是 | 管道分隔或 JSON 数组 |
+| `item_id` | 否 | 题目 ID；缺失时跳过 multi-KC 检查 |
+| `y_true` | 否 | 0/1；有 `y_pred` 时必填 |
+| `y_pred` | 否 | [0,1]；缺失时跳过指标检查 |
+| `fold` | 否 | 交叉验证折 |
+| `sequence_id` | 否 | 序列 ID |
+| `position` | 否 | 序列内位置 |
+
+完整说明见 `docs/data-contract.md`。
+
+## 输出
+
+`kt-audit run events.csv --out report/` 生成：
+
+- `report.json`：机器可读，带 `schema_version`、`findings`、`metrics`、`verdict`。
+- `report.md`：人读，先给 verdict，再给证据与限制。
+
+退出码：
+
+- `0`：pass 或 warn。
+- `1`：fail（至少一个 error）。
+- `2`：输入/配置错误。
+
+## 设计约束
+
+- 运行依赖只加 `numpy`、`pandas`、`scikit-learn`。
+- CLI 用标准库 `argparse`，不引入 Typer/Click。
+- 配置用 JSON，不引入 YAML/TOML 解析器。
+- `src/` 布局；包名 `kt_audit`，命令 `kt-audit`。
+- 每个 check 是纯函数：输入 DataFrame + config，输出 Finding 列表。
+- 报告排序稳定，示例截断，避免大文件。
+- 对外 README/文档英文；内部 charter/notes 中文。
+
+## 4 周成功标准
+
+- `uv run pytest` 绿，三个 check 都有正反例。
+- `kt-audit run examples/leaky.csv --out /tmp/report` 能生成 JSON + Markdown。
+- 示例报告能抓到三类故意泄漏。
+- GitHub Actions 在 Python 3.10-3.13 上绿。
+- 一个陌生人按 README 能在 5 分钟内跑出报告。
+
+**不以下载量、stars、外部 PR 数作为早期成功标准。**
+
+## 后续（v0.2+）
+
+- pyKT 输出 adapter。
+- bootstrap AUC 置信区间。
+- HTML 报告。
+- 更多检查：重复交互、冷启动、序列截断、标签泄漏。
+- 真实数据集 case study（注意授权）。
+
+## 风险
+
+- 启发式会有假阳性；必须提供 examples 和 limitations。
+- 容易膨胀成“又一个 KT 框架”；v0.1 冻结在三个检查。
+- 数据集不能随便打包；示例用合成数据。
+- 维护时间有限；每周 2-4 小时，不承诺 SLA。
+
+## 许可与治理
+
+- MIT。
+- 初始单维护者；PR 欢迎，但不承诺响应时间。
+- AI 可参与开发，但每条 finding 的定义和测试必须有人复核。

kt_audit-0.1.0/docs/data-contract.md

@@ -0,0 +1,60 @@
+# Data contract
+
+`kt-audit` 接受 **一行一个交互/预测** 的宽表。CSV（UTF-8）或 JSONL；Python API 直接收 `pandas.DataFrame`。
+
+## 列
+
+| 列 | 类型 | 必填 | 约束 |
+| --- | --- | :--: | --- |
+| `user_id` | string/int | 是 | 非空；同一用户内 timestamp 可比较 |
+| `timestamp` | ISO8601 / 数值 | 是 | 可解析；不要混用 naive 与 timezone-aware |
+| `split` | string | 是 | `train` / `valid` / `test`；`val`、`validation` 会归一为 `valid` |
+| `kc_ids` | string/list | 是 | 管道分隔或 `["kc_a","kc_b"]`；至少一个 |
+| `item_id` | string/int | 否 | 缺失时跳过 multi-KC 检查 |
+| `y_true` | 0/1 | 否 | 有 `y_pred` 时必填；不能是 NaN |
+| `y_pred` | float | 否 | 有限值，且 `0 <= y_pred <= 1` |
+| `fold` | int/string | 否 | 有 fold 时按 fold 分别跑检查 |
+| `sequence_id` | string/int | 否 | 用于序列级检查（v0.2） |
+| `position` | int | 否 | 序列内位置（v0.2） |
+
+## 解析规则
+
+- `split`：转小写并 strip；`val` / `validation` -> `valid`；其他值报错。
+- `kc_ids`：以 `[` 开头按 JSON 数组解析；否则按 `|` 分割、strip、去空。
+- `timestamp`：优先 `pandas.to_datetime`；数值保持数值。若解析后既有 tz-aware 又有 naive，报错。
+- `user_id` / `item_id`：统一转字符串，保留原始值用于报告。
+- `y_true`：只接受 0/1（含 `0.0`/`1.0`）。
+- `y_pred`：必须是有限浮点，范围 [0,1]。
+
+## 主键
+
+按可用列依次选择：
+
+1. `(fold, user_id, item_id, timestamp)`
+2. `(fold, user_id, timestamp, sequence_id, position)`
+3. `(fold, user_id, timestamp)`
+
+主键重复记一条 `alignment` error。
+
+## 最小示例
+
+```csv
+user_id,item_id,kc_ids,timestamp,split,y_true,y_pred
+u1,q1,kc_a|kc_b,2024-01-01T10:00:00,train,1,0.80
+u1,q2,kc_b,2024-01-01T10:05:00,train,0,0.30
+u2,q1,kc_a|kc_b,2024-01-02T09:00:00,test,1,0.75
+u2,q3,kc_c,2024-01-02T09:10:00,test,0,0.20
+```
+
+这个例子里 `q1` 同时出现在 train/test，且 `kc_a` 只在 train、`kc_b` 在两边都有——multi-KC 检查会给出 warn/error，具体看配置。
+
+## pyKT 映射（v0.2）
+
+pyKT 的列名不同（`uid`、`questions`、`concepts` 等）。v0.1 不内置 adapter；示例用合成数据，避免数据集授权问题。v0.2 再加 `--adapter pykt`。
+
+## 限制
+
+- 时间戳只用于 split 泄漏检查，不推断因果。
+- 没有 `item_id` 时无法检查题目级多 KC 泄漏。
+- 没有 `y_pred` 时只做数据/泄漏检查，不算指标。
+- 跨 fold 的重复不一定是错；默认按 fold 隔离检查。