OlympiaAI/raix

OlympiaAI / raix – Ruby AI eXtensions

무엇인가요 – Raix는 어떤 Ruby 클래스에도 고립된 대규모언어모델(LLM) 기능을 쉽게 추가할 수 있는 Ruby 라이브러리입니다. 세 가지 믹스인 모듈을 제공합니다:

Raix::ChatCompletion – 대화 기록(트랜스크립트)을 관리하고, 하위의 RubyLLM 래퍼(OpenAI, Anthropic, Google Gemini 등)를 통해 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` 훅	글로벌, 클래스 수준, 인스턴스 수준의 람다(또는 호출 가능한 객체)로 요청 수정, 시스템 프롬프트 추가, 로깅, 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`를 스캔하고, 요청이 서버를 떠나기 전에 주민등록번호, 이메일 등을 마스킹합니다.
다단계 처리 파이프라인	`Raix::PromptDeclarations`를 사용하여 URL 검색 체크, 메모리 스캔, 메인 대화 프롬프트를 순차적으로 실행하며, 루프 코드를 작성하지 않고도 가능합니다.
비용 인식 모델 선택	`before_completion` 훅에서 DB에서 테넌트 설정을 읽고 요청별로 `model`, `temperature`, `max_tokens`를 주입합니다.
비용이 큰 도구 호출 캐시	`dispatch_tool_function`을 오버라이드하여 `Rails.cache`를 전달하고, 동일한 인수로 이전 결과를 재사용하게 합니다.

프로젝트 성숙도 (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는 LLM API와의 대화에서 발생하는 반복 코드를 추상화하는 Ruby 우선 SDK입니다. 몇 가지 모듈을 믹스인함으로써 다음을 얻을 수 있습니다:

관리되는 대화 트랜스크립트
OpenRouter를 통한 통합 다중 제공자 접근
동적 요청 조정을 위한 강력한 훅
모델이 Ruby 메서드를 호출할 수 있는 선언형 도구 호출 시스템
복잡한 다단계 흐름을 위한 프롬프트 체인 DSL

Ruby 생태계를 벗어나지 않고 LLM 기반 기능(챗봇, 어시스턴트, RAG 파이프라인, 자동화)을 내장하고자 하는 Ruby 개발자를 위한 것입니다. README는 즉시 개발을 시작할 수 있는 충분한 정보를 제공합니다.