OlympiaAI/raix

OlympiaAI / raix – Ruby AI 扩展

是什么 – Raix 是一个 Ruby 库，可将离散的大语言模型（LLM）功能轻松集成到任何 Ruby 类中。它提供三个混入模块：

Raix::ChatCompletion – 核心模块，管理 对话记录（会话历史），并通过底层的 RubyLLM 包装器（OpenAI、Anthropic、Google Gemini 等，通过 OpenRouter）向 LLM 发送聊天补全请求。
Raix::FunctionDispatch – 可选的 DSL，用于声明模型可以调用的工具（函数）定义。Raix 会自动执行函数，将结果添加到对话记录中，并持续对话，直到模型返回纯文本。
Raix::PromptDeclarations – 可选的 DSL，用于构建可重用的 提示链（顺序提示、流式传输、条件循环）。

这三个模块可混入普通 Ruby 对象；只要包含 activesupport，也可在非 Rails 应用中使用。

主要特性（如 README 所述）

特性	README 说明	为何重要
统一的提供者访问	由 `ruby_llm` 驱动，支持 OpenAI、Anthropic、Google Gemini 以及通过 OpenRouter 的众多其他提供者。	无需更改代码即可切换模型或提供者。
对话记录处理	`transcript` 以短格式 `{ role: "user", content: "…" }` 或简写形式 `role => content` 存储消息。除非传入 `save_response: false`，否则会自动追加 AI 回复。	保持对话状态简单且灵活。
预测输出	传入 `prediction:` 参数（OpenAI）可获得低延迟的推测性响应。
提示缓存	对 Anthropic Claude 模型，可设置 `cache_at` 将大消息拆分为缓存的“断点”。
JSON 模式	`json: true` 强制模型返回有效 JSON；Raix 为 OpenAI 设置 `response_format`，并从其他提供者的 `<json>` 标签中提取 JSON。
`before_completion` 钩子	全局、类级别或实例级别的 lambda（或可调用对象），可用于修改请求、添加系统提示、记录日志、脱敏 PII、按租户选择模型等。
函数（工具）分发	使用 `function :name, "description", param_schema do … end` 声明函数。当模型请求工具时，Raix 会自动调用，并将结果添加到对话记录中，循环直到返回正常文本。支持：

通过 available_tools 选择性暴露
一次响应中多次工具调用
自定义 dispatch_tool_function 覆盖
通过 ActiveSupport 缓存函数结果 | | 提示链 DSL | prompt call: SomePromptClass 或 prompt text: -> { … } 可组合多步骤对话（例如：URL 检测、内存扫描、流式回复）。 | | 配置 | Raix.configure 用于设置全局默认值（例如：默认模型、最大工具调用次数、全局钩子）。 |

典型用例

场景	如何使用 Raix
为 Rails 或 Sinatra 应用添加聊天机器人功能	在服务对象中包含 `Raix::ChatCompletion`，将用户消息推入 `transcript`，调用 `chat_completion` 并渲染返回的字符串。
构建可调用内部服务的 AI 驱动助手	添加 `Raix::FunctionDispatch` 并声明如 `check_weather`、`fetch_user_profile` 等函数。模型将决定何时调用它们，Raix 会自动处理往返通信。
强制数据隐私 / PII 脱敏	设置全局 `before_completion` 钩子，扫描 `context.messages` 并在请求离开服务器前屏蔽 SSN、邮箱等。
多步骤处理流水线	使用 `Raix::PromptDeclarations` 运行 URL 检查、内存扫描、主对话提示，无需编写样板循环。
成本感知的模型选择	在 `before_completion` 钩子中从数据库读取租户设置，并按请求注入 `model`、`temperature`、`max_tokens`。
缓存昂贵的工具调用	重写 `dispatch_tool_function` 以传入 `Rails.cache`，让 Raix 重用相同参数的先前结果。

项目成熟度（来自 README）

版本 – 提及 Raix 2.0（至少一次主要发布）。
来源 – 从生产级 Olympia 聊天平台中提取，作者声称其为“用 Ruby 完全编写、规模最大且最成功的 AI 聊天项目之一”。
依赖 – 依赖 ruby_llm（提供者包装器）和 activesupport（用于缓存和工具）。
测试 – README 包含 RSpec 示例，表明存在测试套件。
文档 – README 本身相当详尽，涵盖核心 API、钩子、函数分发、缓存和提示链。
社区 – 未明确提及外部贡献者，但该库是开源的，与商业产品（Olympia）和 Leanpub 书籍相关，表明拥有小而专注的用户群。

生态系统与兼容性

项目	详情
Ruby 版本	未说明，但依赖 `ruby_llm` 和 `activesupport`；可能为 Ruby 2.7+ 或 3.x。
Rails 支持	适用于任何 Ruby 应用；Rails 集成可选，但示例使用 Rails 日志和缓存。
提供者支持	OpenAI、Anthropic、Google Gemini 以及通过 OpenRouter 的“数十个其他提供者”。
其他 gem	`ruby_llm`、`activesupport`，可选 `rails` 用于缓存/日志。
许可证	README 中未提及（需检查仓库）。

快速入门（基于 README）

添加 gem（假设名称为 raix）到 Gemfile 并运行 bundle install。
在任意类中包含核心模块 以获得 AI 能力：
```
class MyAssistant
  include Raix::ChatCompletion
end
```

将消息推送到对话记录并调用完成：

ai = MyAssistant.new
ai.transcript << { user: "What is the meaning of life?" }
puts ai.chat_completion   # => 模型响应字符串

可选：添加函数分发（如需工具）：

class WeatherBot
  include Raix::ChatCompletion
  include Raix::FunctionDispatch

  function :check_weather, "Check weather", location: {type: "string", required: true} do |args|
    "It is sunny in #{args[:location]}"
  end
end

全局配置（例如：默认模型、钩子）：

Raix.configure do |c|
  c.before_completion = ->(ctx) { { temperature: 0.7 } }
end

运行你的应用 – 该库将为你处理请求构建、响应解析、工具执行和对话记录管理。

TL;DR

Raix 是一个以 Ruby 为先的 SDK，抽象掉了与 LLM API 交互的样板代码。通过混入几个模块，你即可获得：

受管理的对话记录，
通过 OpenRouter 的统一多提供者访问，
用于动态请求调整的强大钩子，
允许模型调用 Ruby 方法的声明式工具调用系统，以及
用于复杂多步骤流程的提示链 DSL。

它面向希望在不离开 Ruby 生态系统的情况下嵌入 LLM 驱动功能（聊天机器人、助手、RAG 流水线、自动化）的 Ruby 开发者。README 提供了足够详细的信息，可立即开始构建。