# jev-clinical-cleaner

**中文** · [English](#english)

用 Jev 这类“决策模型”清洗临床研究表格（xlsx / csv）：字段映射、分级和影像描述归类、数字交给代码、置信度门槛 0.9、人工复核队列、审计日志。

> **隐私警告：** 默认走托管 API，单元格文本和字段样例会发到 `https://api.typesafe.ai`。运行前必须先去标识化（姓名、身份证号、住院号、电话、出生日期等）。拿不准就不要上传。
> **干跑模式**（`--dry-run`）用的是“替身匹配器”，它不是 Jev，只按 schema 里的同义词做字符串匹配，输出里会标明。

### 安装
```bash
git clone https://github.com/picspin/jev-clinical-cleaner.git && cd jev-clinical-cleaner
python -m venv .venv && source .venv/bin/activate
pip install -e ".[mcp]"        # 需要 Python 3.10+
```

### 拿到 Jev 的密钥
1. 注册和登录入口：<https://console.typesafe.ai/>（官网 typesafe.ai 上的 “Sign in” 链接；登录页提供 Google 或邮箱登录）。
2. 文档：<https://docs.typesafe.ai>。官方快速开始写的是“从控制台获取 API key”。
3. 新用户注册是开放的（2026-10-05 确认）。
4. 密钥只放环境变量，不要写进文件、脚本或截图：
```bash
export JEV_API_KEY="<你的密钥>"                           # 也识别 TYPESAFE_API_KEY
export JEV_BASE_URL="https://api.typesafe.ai/v1/systemone"   # 默认值，可不设
```
本仓库不含任何密钥。

### 快速上手
```bash
python examples/make_synthetic.py                              # 生成合成演示表（40 行）
jevclean run examples/demo_raw.xlsx --schema examples/schema.json --out out --dry-run   # 无需密钥
jevclean run examples/demo_raw.xlsx --schema examples/schema.json --out out             # 用 Jev（需密钥）
```
输出在 `out/`：`cleaned.csv`（只含自动通过的值）、`review_queue.csv`（要人看的格子）、`audit.jsonl`（每次调用的记录，不含密钥）、`report.md`、`mapping.json`、`decisions.jsonl`。

分步命令：`jevclean map-fields` → `normalize` → `route` → `report`；`gate-check` 用你手工标注的样本检验门槛。

Excel 演示：`python examples/excel_demo.py`，生成带实时公式的 `jevclean_demo.xlsx`。

MCP 服务（stdio）：`jevclean-mcp`。工具：`map_fields`、`classify_cells`、`normalize_numeric`、`route_confidence`、`export_report`。

Agent 技能：见 `SKILL.md`。本地部署（openjev、llama.cpp 等）：见 `docs/local-deployment.md`。

### 许可
MIT。示例数据全部是合成的。

---

## English

Clean clinical-research tables (xlsx / csv) with a Jev-style decision API: field mapping, grades and imaging text, numbers handled by code, a 0.9 confidence gate, a review queue and an audit log.

> **Privacy warning:** by default the hosted API receives your cell text and sample values (`https://api.typesafe.ai`). De-identify first: names, national IDs, MRNs, phone numbers, birth dates. If unsure, do not upload.
> **Dry-run** (`--dry-run`) uses a *stand-in matcher*. It is not Jev. It matches strings using the synonyms in your schema, and every output says so.

### Install
```bash
git clone https://github.com/picspin/jev-clinical-cleaner.git && cd jev-clinical-cleaner
python -m venv .venv && source .venv/bin/activate
pip install -e ".[mcp]"        # Python 3.10+
```

### Get a Jev key
1. Sign-in page: <https://console.typesafe.ai/> (the "Sign in" link on typesafe.ai; Google or email login).
2. Docs: <https://docs.typesafe.ai>. The official quickstart says to get the key from the dashboard.
3. New sign-ups are open (confirmed 2026-10-05).
4. Keep the key in the environment only:
```bash
export JEV_API_KEY="<your key>"                            # TYPESAFE_API_KEY also works
export JEV_BASE_URL="https://api.typesafe.ai/v1/systemone"   # default; optional
```
This repo contains no key.

### Quick start
```bash
python examples/make_synthetic.py
jevclean run examples/demo_raw.xlsx --schema examples/schema.json --out out --dry-run   # no key
jevclean run examples/demo_raw.xlsx --schema examples/schema.json --out out             # Jev (key needed)
```
Outputs in `out/`: `cleaned.csv` (auto-passed values only), `review_queue.csv`, `audit.jsonl` (one record per call, no key), `report.md`, `mapping.json`, `decisions.jsonl`.

Step by step: `jevclean map-fields` → `normalize` → `route` → `report`. `gate-check` tests the gate on your own labelled sample.

Excel demo: `python examples/excel_demo.py` writes `jevclean_demo.xlsx` with live formulas.
MCP server (stdio): `jevclean-mcp`; tools `map_fields`, `classify_cells`, `normalize_numeric`, `route_confidence`, `export_report`.
Agent skill: `SKILL.md`. Local servers (openjev, llama.cpp): `docs/local-deployment.md`.

### Licence
MIT. All sample data is synthetic.