@obie：嘿，Ruby 开发者们，这是试玩来自 @typesafeai 的这些新决策模型如 JEV 的最佳方式 功能齐全，并且未来可期…

嘿，Ruby 开发者们，这里有个体验 @typesafeai 推出的 JEV 等新型决策模型的最佳方式。功能完备，面向未来。欢迎查看 https://t.co/uBODOfdVjm — # obie/ruby_decision_model 来源：https://github.com/obie/ruby_decision_model # ruby_decision_model 专为 Ruby 设计的决策模型接口。决策模型通过校准概率回答关于状态的类型化问题，而非生成文本。此 gem 通过单一 Client 与模型交互，并默认使用 OpenRouter 作为后端提供商，Typesafe 的原生 API 作为备选通道，未来也会支持更多实验室推出的服务。除标准库外无运行时依赖。 ## 安装 ruby gem "ruby_decision_model" ## 快速开始 ruby require "ruby_decision_model" client = RubyDecisionModel::Client.new response = client.ask( state: { title: "Server returns 500 on checkout", reporter: "support" }, questions: { "urgent" => RubyDecisionModel::Questions.noul("Is this urgent?"), "severity" => RubyDecisionModel::Questions.score( "How severe is this issue?", criteria: ["cosmetic", "minor", "major", "critical"] ) } ) response["urgent"].noul # => 0.87 response["severity"].score # => 2.4 response.usage.input_tokens # => 120 Client.new 无参数调用时会读取环境变量：设置 TYPESAFE_API_KEY 则使用 Typesafe，否则设置 OPENROUTER_API_KEY 则使用 OpenRouter。若两者均未设置，将抛出 ConfigurationError 并提示需配置这两个变量之一。RubyDecisionModel.client 会缓存默认客户端实例；赋值 nil 可重置。 ## 提供商 ### OpenRouter（默认） ruby # ENV["OPENROUTER_API_KEY"] client = RubyDecisionModel::Client.new(provider: :open_router) # 或直接传入密钥；仅指定 api_key: 仍默认使用 OpenRouter client = RubyDecisionModel::Client.new(api_key: "sk-or-...") 请求将发送至 https://openrouter.ai/api/alpha/decisions。默认模型为 typesafe/jev-1.13。使用量报告包含 input_tokens、output_tokens 和 cost。 ### Typesafe 原生 API ruby # ENV["TYPESAFE_API_KEY"] client = RubyDecisionModel::Client.new(provider: :typesafe) 请求将发送至 https://api.typesafe.ai/v1/systemone。默认模型为 jev-latest。使用量报告包含 input_tokens 和 output_tokens；cost 为 nil。Typesafe 会在响应头中返回 x-typesafe-request-id，可通过 response.request_id 获取（OpenRouter 中为 nil）。向 Typesafe 反馈问题时请提供此 ID。 ### 配置项 ruby RubyDecisionModel::Client.new( provider: :typesafe, # :open_router, :typesafe 或 Providers::Base 实例 api_key: nil, # 覆盖提供商对应的环境变量 model: nil, # nil 表示使用提供商默认模型；别名见下文 base_url: nil, # 覆盖提供商基础 URL timeout: 5, # 连接和读取超时（秒） retry: { max_retries: 2 }, # RetryPolicy 对象或配置哈希 transport: nil # 参见 Transport 说明 ) client.provider # => #<RubyDecisionModel::Providers::Typesafe:0x...> client.model # => "jev-latest"（别名解析后） 两个提供商的请求头均包含 User-Agent: ruby_decision_model/。 ### 模型别名 每个提供商都会将部分友好名称映射至其规范模型名。未列出的名称将直接透传。响应中的 model 字段始终为提供商返回的原始值。 | 你传入的值 | OpenRouter 发送 | Typesafe 发送 | | — | — | — | | nil | typesafe/jev-1.13 | jev-latest | | "jev" | typesafe/jev-1.13 | jev-latest | | "jev-latest" | typesafe/jev-1.13 | jev-latest | | "typesafe/jev-1.13" | typesafe/jev-1.13 | jev-latest | | 其他任意值 | 原样传入 | 原样传入 | ### 自定义提供商 继承 RubyDecisionModel::Providers::Base 并实现 name、env_var、default_base_url、endpoint_path、default_model，可选覆盖 aliases 和 reports_cost?。当通信格式不同时，可重写 headers、request_body 或 usage。将实例通过 provider: 参数传入。 ## 问题与答案 三种问题类型通过 RubyDecisionModel::Questions 构建： ruby Questions.noul("Is this spam?") # 是/否概率 Questions.choice("Which team?", criteria: { "billing" => "...", "auth" => "..." }) # 最多255个选项 Questions.score("How severe?", criteria: ["cosmetic", "minor", "major"]) # 2到10个等级 答案按类型返回：Answers::Noul（noul、probabilities）、Answers::Choice（choice、confidence、probabilities）和 Answers::Score（score、confidence、probabilities、legend）。response.nouls、response.choices 和 response.scores 按与 response.answers 相同的键结构返回对应类型的答案。Score 的 probabilities 和 legend 以传输层的字符串键（"0"、"1" …）索引，而非使用标准名称。Choice 的 probabilities 总和约为1；应视为校准概率而非归一化值。 ## 重试机制 重试行为遵循官方 Typesafe SDK 规范，实现于 RubyDecisionModel::RetryPolicy。通过 retry: 传入策略对象或覆盖哈希。 | 选项 | 默认值 | 说明 | | — | — | — | | max_retries | 2 | 首次尝试后的重试次数 | | backoff_initial | 0.5 | 初始退避时间（秒），每次重试加倍 | | backoff_max | 5.0 | 退避时间上限（秒） | | backoff_jitter | 0.25 | 随机缩减的退避时间比例 | | http_statuses | [408, 429] + (500..599) | 触发重试的 HTTP 状态码 | | respect_retry_after | true | 遵守 Retry-After 和 retry-after-ms 头 | | max_retry_after | 60.0 | 服务器指定延迟的上限 | | retry_connection_errors | true | 重试套接字和连接错误 | | retry_timeouts | true | 重试连接和读取超时 | | total_timeout | 30.0 | 所有尝试和延迟的总预算（秒）；nil 表示不限制 | 当下次延迟将超出 total_timeout 时，客户端会停止并抛出最后错误而非等待。该预算决定是否发起新尝试；已进行的尝试仍会运行至其 timeout。无效设置（负时长、非整数 max_retries、超出0..1的 jitter、NaN 预算）会在构建客户端时抛出 ConfigurationError。 ruby RubyDecisionModel::Client.new(retry: { max_retries: 4, total_timeout: 60.0 }) RubyDecisionModel::Client.new(retry: RubyDecisionModel::RetryPolicy.new(max_retries: 0)) ## 传输层 客户端默认使用 Net::HTTP。可通过 transport: 注入任意可调用对象，需接受 url:、headers:、body: 参数并返回 [status, body_string, headers_hash]。返回两元素 [status, body_string] 仍有效，视为无响应头，这意味着不支持 Retry-After 且 request_id 为 nil。 ## 错误类型 | 错误类型 | 说明 | | — | — | | ConfigurationError | 无法解析提供商、缺少 api_key、未知提供商或无效 retry: 配置 | | RequestError | 问题哈希为空 | | TransportError（TimeoutError） | 重试后仍发生网络或超时错误，包含 #cause_error | | ApiError | 非2xx响应，包含 #status、#body 和 #headers | | Unauthorized | 401 | | PayloadTooLarge | 413 | | UnprocessableEntity | 422（永不重试） | | RateLimited | 429（会重试） | | Overloaded | 529（会重试） | | InvalidResponse | 响应体非JSON、非哈希或答案格式错误 | | MissingAnswers | 一个或多个问题ID缺失或类型错误，包含 #missing | 状态：0.1.0，API可能变更。配套 gem decide 基于此客户端构建决策和裁定流程。 ## 发布流程 发布通过 RubyGems 可信发布机制完成，无需存储API密钥。版本发布步骤： 1. 更新 lib/ruby_decision_model/version.rb 版本号 2. 在 CHANGELOG.md 添加版本说明 3. 合并至 main 分支 Release工作流会运行测试套件，使用 gem build --strict 构建gem包，检查构建产物包含 lib/ 下所有文件，然后推送至RubyGems。已存在的版本会被跳过，因此可安全重复运行。也可从Actions选项卡手动启动或使用 gh workflow run release.yml。