[FEATURE] Build an offline Jev routing and guardrail evaluation runner

问题场景

贡献者在 CrewAI 仓库中为一个离线 Jev 路由与防护栏评测脚本（evaluation runner）落地实现：从 JSON/JSONL 读取标注的路由记录与防护栏记录，配合录制或伪造的决策，统计准确率、路由覆盖率与弃权率、防护栏误接受/误拒绝，以及可得的录制延迟与用量。触发点集中在模块放置位置、记录字段形状与指标定义（尤其是缺失或异常决策如何计数），与当前 main 上尚未合入的 jev_decision_tool/ 产生重叠。

报错原文

[FEATURE] Build an offline Jev routing and guardrail evaluation runner

原因分析

该 Issue 本质是功能设计协调，不是运行时崩溃。可能原因包括：新包 tools/jev_evaluation/ 与 #8076 引入的 jev_decision_tool/ 路径归属未定；失败决策在指标分母中的处理方式与 #8095 的 Noul 防护栏实现不一致（后者对缺失/畸形 Noul 答案返回拒绝并向上抛出 SDK 异常）；离线归一化未强制校验 type == "noul" 判别字段；以及针对 typesafe-sdk 0.7.3 SystemOneResponse.answers 的静态告警尚未用真实 SDK 响应对象验证。

环境排查

• 确认 Python 版本在 3.10–3.13 范围内（PR 已在该区间通过测试）。
• 确认检出分支中是否存在 crewai_tools/tools/jev_evaluation/，并核对 jev_decision_tool/ 是否已从 #8076 合入 main。
• 确认数据集文件为合法 JSON/JSONL，记录含 choice、confidence、probabilities、noul，可选 model、usage、latency_ms。
• 确认 min_confidence 阈值语义为含等号的 >=，且 Choice confidence 与 Noul probability 未互相换算。
• 使用 live 模式时确认已显式传入自定义 client 与凭据；测试本身不需要付费 API 调用。
• 若出现 typesafe-sdk 相关告警，核对 SDK 版本为 0.7.3，并确认 SystemOneResponse.answers 存在于已发布源码中。

解决步骤

1. 先按已提交 PR #8230 的离线实现作为基线，用 JSON/JSONL 样例数据跑通，确认 decided / abstained / failed 三类记录分类正确。
2. 把失败记录（缺失、畸形、抛错的决策）单独计数：不计为正确或接受，也不进入误接受与误拒绝的分母。
3. 阈值比较统一使用含等号的 >=；低于 min_confidence 判为弃权；已知路由上的高置信选择判为已决策。
4. 保持 Choice confidence 与 Noul probability 为独立字段，分别评阈值，不做互相转换；缺失 token 计数保持缺失，不回填 0。
5. 将 live 采集设为显式 opt-in：由调用方传入自己的 client，不引入 typesafe_sdk 顶层导入，不改动 pyproject.toml 或 uv.lock；延迟仅在成功的 live 调用上测量。
6. 在文档中写明归一化边界：离线决策校验 noul 值但不要求 type == "noul" 判别字段，并补充一个「答案类型错误」的 live 采集用例。
7. 用真实 SDK 响应对象（typesafe-sdk 0.7.3）编写一项测试，覆盖 SystemOneResponse.answers 与 nouls/choices 过滤视图，以澄清静态扫描告警。
8. 补齐针对分母口径、阈值边界、缺失记录与非法输入的测试；包最终位置与 Noul 契约待维护者 @lorenzejay 确认后再调整。

验证方法

离线测试在 Python 3.10–3.13 全部通过；可故意破坏阈值与分母逻辑，确认测试能捕获回归。在指标口径上，检查失败记录数独立呈现且未进入误接受/误拒绝分母，阈值边界用例覆盖 >= 的含等号情形。live 相关告警则应以 typesafe-sdk 0.7.3 真实响应对象构造的测试结果为准，而非静态扫描结论。

参考来源

crewAIInc/crewAI #8124

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。