jev-clinical-cleaner

中文 · English

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

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

安装

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. 密钥只放环境变量，不要写进文件、脚本或截图：

export JEV_API_KEY="<你的密钥>"                           # 也识别 TYPESAFE_API_KEY
export JEV_BASE_URL="https://api.typesafe.ai/v1/systemone"   # 默认值，可不设

本仓库不含任何密钥。

快速上手

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

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:

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

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.