OlympiaAI/raix

OlympiaAI / raix – Ruby AI eXtensions

是什麼 – 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 提供足夠詳細的資訊，可立即開始建構。