TypeSafe AI
TypeSafe AI 官方开发者文档（docs.typesafe.ai，共 109 页 + llms.txt 全站索引）的来源摘要，逐条覆盖文档结构、三类原语（Primitive）的字段契约、定价、限速、上下文长度、语言支持与数据承诺。原始语料归档在 processed/jev-原始资料/官方-文档/。
一句话摘要
这是 Jev（jev-1.13.0）唯一的权威技术契约：它把模型能力收窄成三种带类型的问句（Choice / Score / Noul），只收输入词元费（$0.042 / Mtok，输出免费），一次请求最多 64k 词元、最多 1200 请求/分钟，并明确声明不用客户数据训练、不做微调。
关键要点
一、文档全站结构（据 llms.txt 索引逐条列出）
llms.txt 是官方提供的全站页面索引，共列出约 109 个页面，按功能分组如下：
- 入门（Introduction）：
Introduction（Jev 是什么）、Quick start（Playground / API / Python SDK / Agent skill 四条上手路径） - 核心概念（System One）：
System One（模型类别定义）、State（输入材料）、Primitives (Questions)（三类原语总览） - 原语分页：
Choice、Score、Noul、Advanced: structure（instructions / Choice options / Score levels / Noul criteria 均接受 JSON 结构） - TypeSafe foundations：
AI primer（为什么用校准决策而不是生成文本）、Confidence（置信度）、How to build with TypeSafe（工程方法）、Example use cases（用例地图）、Patterns（架构模式） - Patterns 四个子页：
Speculative fan-out（投机式扇出）、Confidence-gated routing（置信度门控路由）、Composite scoring（复合评分）、Intent routing（意图路由） - Demos：
Demos索引页、Smart home assistant demo（智能家居助手，唯一官方 demo 页） - Client SDKs：
Client SDKs总览、Python SDK（+Usage/Changelog/API reference，再下分 async client、sync client、Questions、Answers and responses、Retries、Common types、Exceptions、Constants）、JavaScript SDK（+Changelog/API reference，API reference 再分 14 个 Class、~20 个 Interface、~15 个 Type Alias、3 个 Variable、3 个 Function） - Reference：
Models（模型卡与别名）、API reference（HTTP 接口全量）、Agent skill（面向 AI 编程助手的技能包）、Legal（法务文件）、Jev 1.13 jaggedness（官方缺陷清单） - Cookbooks（18 个实操模板）：按索引分四组——
- Self-consistency：
nouls、choices - Batching：
parallel questions - How-to：
re-ranking、line-by-line search、structure recovery、function calling、skill suggestion、knowledge graph entity alignment、classifying RAG passages、double-checking citations、guardrails for LLMs - Extraction / Classification：
SDE cascade、date extraction、pre-parsed value extraction、hierarchical classification、autoresearch feature discovery、classification using confidence
- Self-consistency：
二、三类原语（Primitives）与字段契约
TypeSafe 只暴露三种「AI 原语（AI Primitives）」，官方称其「模块化、可组合、结构化、可靠、快速」，比作软件原语。一次请求里的所有问句并行（Parallel）且彼此隔离地评估同一份 state。
| 原语 | 问什么 | 返回字段 | 上限 |
|---|---|---|---|
| Choice（选择题） | 从给定选项里挑一个 | choice、probabilities、confidence | criteria 最多 255 个选项 |
| Score（打分题） | 用有序列的等级给 state 打分 | score、legend、probabilities、confidence | criteria 至少 2 级、最多 10 级 |
| Noul（是非题） | 判断「是/否」 | noul（0–1） | 二选一，无 confidence |
- 统一请求体：顶层三个字段
state（string / object / array）、model、questions（map<问句 id, Question>）。问句 id 由用户自取，不会发送给模型。 - 统一问句字段：
type（"choice"/"score"/"noul"）、instructions（必填）、criteria（Choice 为 option→描述的 map；Score 为有序数组；Noul 可选，含true/false两个键）。 instructions与criteria均可为 string / object / array。官方建议先用字符串；两个选项易混时改用对象，字段名由用户自定（官方示例用question/focus/what/not_for/examples），无保留字段名。- Choice 返回的
probabilities是跨全部选项的分布（和为 1），choice是概率最高的选项；Score 的score是「各级编号 × 该级概率」的加权和，可落在两级之间（例：0 × 0.0 + 1 × 0.57 + 2 × 0.43 = 1.43），legend把级别编号映射回描述；Noul 只有两个结果，单个noul值已完整描述该分布，故不另给confidence。 - 并行所以「加问句几乎不加时间」：官方称把可能用到的全部问句一次发出、事后由代码挑用得上的，叫投机式扇出（Speculative Fan-out）。
- 依赖必须跨请求：同一请求内问句互相独立，一个答案不会成为另一个问句的上下文；只有「必须拿到上一个答案才能构造下一个请求」时才发第二次请求（官方点名的三个例外见
skill suggestion、structure recovery、hierarchical classification三个 cookbook）。
三、定价与限速（Models 页）
| 项目 | 数值 |
|---|---|
| 模型版本 | jev-1.13.0；别名 jev-latest（最新稳定版，SDK 默认）、jev-preview（当前与 jev-latest 指向同一模型，暂无预览版） |
| 价格 | 0.042 / 百万输入词元；输出词元免费（官方原话 “too cheap to meter”） |
| 限速 | 250,000 词元/秒；1,200 请求/分钟；超限返回 429 Too Many Requests |
| 上下文长度 | 每请求 64k 词元；其中 state + 最长的那一个问句不超过 32k |
| 输入类型 | 仅文本（string、JSON object、文本数组）；图像 / 音频 / 视频不支持（官方标注 “yet”） |
| 接口 | 所有模型共用 POST /v1/systemone；GET /v1/models 列出账号可用的名称 |
- 官方明确警告限速在动态调整中，称正为「非常大的需求量」服务，上线大额 GPU 交易期间限值可能无预告变更；更高额度走定制 / 企业方案（sales@typesafe.ai）。
- 别名会随新版本发布而移动，答案可能在用户侧无改动的情况下改变；官方建议把置信度阈值调过的场景改为固定版本号，并靠响应里的
model字段记录实际作答版本。 - 错误码：
401 Unauthorized（密钥缺失或非法）、422 Unprocessable Entity（请求体校验失败）、429 Too Many Requests（超限）、529 Overloaded（服务过载）；429 / 529 建议指数退避重试，官方 SDK 默认自带。
四、置信度（Confidence）
confidence是从probabilities推导出的统计量，取值 0–1：分布越集中在一个选项/等级上越接近 1.0，越平坦越低。- 官方给的近似公式（三选项时）：(选项数 × 最大概率 − 1) ÷ (选项数 − 1)，即
(3 × largest probability − 1) / 2。 - 官方三种用法的默认模式：高置信度 → 自动执行；中置信度 → 请用户确认 / 标记复核 / 补信息；低置信度 → 不行动，转人工或转别的系统。
- 阈值随风险缩放：官方给的可运行示例里，
confidence < 0.5一律转人工；「查余额」这类只读动作低门槛即可；「批准转账」这类高风险动作要在confidence > 0.9才「确认后执行」，否则先让用户确认。 - 官方原话提醒：正确的阈值取决于业务领域与该模型在具体用例上的表现，先用保守阈值、用自己的数据测、再按观测结果调整。
五、语言支持与数据承诺
- 语言支持：Jev 主要训练语言是英文，也是当前准确率最好的语言；其他语言（含 CJK 文字）可处理但准确率不相等，官方要求非英语场景先用自己的内容测试，并在路由时密切关注置信度。
- 不做微调：Jev 不用客户数据做微调或 LoRA 适配，全部账号共用同一套权重；定制方式是往
state塞专有内容、往instructions/criteria写领域规则与边界情况、把宽问题拆成原子问题后在代码里组合。 - 数据承诺：官方声明 Jev 不用客户请求或响应训练；企业客户可申请零数据保留（Zero Data Retention, ZDR）。
- Legal 页列出的三份文件：数据处理协议（Data Processing Agreement）、主客户协议（Master Customer Agreement）、隐私政策（Privacy Policy），ZDR 咨询 privacy@typesafe.ai。
六、工程方法与生态入口
- 三种软件架构（
How to build页）：传统软件（传统代码原语可组合）、LLM 智能体（每层循环都多一次「跑偏」机会）、AI 驱动的软件（代码掌握控制流，模型只出现在需要可编程常识的地方）。 - 可组合的六个属性：结构化（Type-safe，决策符合 JSON schema）、并行、可比（可排序、可驱动
if与阈值）、快（多数查询约 100 ms）、校准置信度、自洽。 - 官方宣称目标是大于 100 倍的「智能 / 速度与成本」比；核心赌注是更便宜的智能会创造更多需求。
- 上手四条路径：Playground（console.typesafe.ai）、HTTP API、Python SDK（
pip install typesafe-sdk/uv add typesafe-sdk，需 Python >= 3.10）、JavaScript SDK（npm install @typesafe-ai/sdk，需 Node.js 20+）。 - Agent skill：面向 Claude Code / Codex 等 AI 编程助手的技能包，安装方式
npx skills add typesafe-ai/skills --skill typesafe-ai或 Claude Code 插件市场，官方提醒要放在单一文件里便于审查「questions 与 threshold 常量」。 - Demos：官方只发布了一个 demo 页——智能家居助手，演示投机式扇出 + 与 LLM 分工（拆复合请求、闲聊回退给生成模型）。
重要引用
“Large language models (LLMs) are designed to produce text for humans to read. When you need a model to make a judgment that your code will consume, that creates a mismatch: you are coercing a text-generation system into outputting structured decisions, then parsing the results back into something your code can depend on.”
大语言模型是为「给人读」而生的。当你需要模型做出会被代码消费的判断时，就产生了错配：你在逼一个文本生成系统输出结构化决策，再把结果解析回代码能依赖的东西。
“Jev outputs all probabilities in parallel instead of autoregressively generating by token.”（引自官方博客，文档
Primitives页亦转述其并行采样机制）Jev 并行输出全部概率，而不是按词元自回归生成。
“Calibration is measured across groups of predictions; it does not guarantee that an individual answer is correct.”
校准是在一群预测上度量的；它不保证单个答案是对的。
“The correct threshold values depend on your domain and the performance of the model for your use case. Start with conservative thresholds, test with your own data, and adjust as you observe results.”
正确的阈值取决于你的领域与该模型在你用例上的表现。先用保守阈值，用你自己的数据测试，再按观测结果调整。
“Jev is not fine-tuned or LoRA-adapted with customer data. It is trained with RLCD to return calibrated decisions, and the same weights serve every account.”
Jev 不用客户数据进行微调或 LoRA 适配。它用 RLCD 训练以返回校准决策，同一套权重服务每个账号。
相关页面
- Jev 知识——面向非技术读者的全貌综合页
- Jev官方缺陷清单jaggedness、Jev官方评测与用例地图、TypeSafe发布博客SystemOne与Jev
- 模型与框架分责、Harness工程、上下文腐坏、工具调用