rudra-js는 동적 제품 추천을 생성하기 위한 오픈 소스 TypeScript 라이브러리입니다.
사용자가 트래킹 입력을 생성기에 지정하면, rudra-js가 모든 작업을 수행합니다.
- 제공업체가 구성된 경우에만 적용되는 정제된 데이터를 LLM (Large Language Model)으로 전송합니다.
- LLM은 제품 페이지의 응답으로 하나의 제품 추천 블록을 설계하여 다시 보냅니다.
- rudra-js는 이를 카탈로그와 비교하고, React가 렌더링합니다.
만약 언어 모델이 원시 HTML을 작성하도록 허용된다면, 가격을 임의로 만들 수 있습니다. 또한 판매하지 않는 제품을 보여줄 수도 있습니다. 이것이 바로 rudra-js가 모델에게 아예 HTML 작성을 허용하지 않는 이유입니다. 대신 모델은 '스펙(spec)'을 반환해야 합니다: 즉, rudra-js가 정의한 필드만으로 구성된 블록의 짧은 설명입니다. 레이아웃과 헤드라인 및 본문 텍스트는 작성하지만, 가격, 제품 이름, 이미지 또는 링크를 위한 필드는 없습니다. 제품 이름을 지정하려면 제공된 목록에서 SKU(재고 관리 코드)를 사용해야 합니다.
The example shop's product page. The heading and the highlighting are the model's. The products, their order and the line under each are core's picks, and every title, price and image is the shop's.
@rudra-js/react는 이 스펙을 HTML로 변환합니다. 이를 위해 페이지가 제공되는 동안 카탈로그에서 제품의 제목, 가격, 이미지 및 링크를 읽습니다. 모델이 작성한 모든 내용은 이스케이프된 텍스트(escaped text)로 렌더링됩니다.
rudra-js는 또한 모델이 작성한 모든 단어를 세 번의 패스(passes)를 거쳐 확인합니다:
- 가격, 할인, 평점, 배송 날짜 및 재고 수량 패턴 검사.
- 숫자 검사. 문장에 있는 모든 숫자는 모델에게 보여진 제품의 카테고리나 태그와 같이 사용자의 입력에서 나와야 합니다.
- "최고 인기 상품(top pick)"이나 "고객이 가장 좋아하는 상품(customer favourite)"과 같이 숫자를 포함하지 않는 클레임 목록 검사.
패스를 통과하지 못한 모든 필드는 제거됩니다.
두 가지 검증 단계(passes)는 단순히 단어 목록일 뿐입니다. 이는 두 목록 어디에도 없는 방식으로 재구성된 문구는 통과할 수 있다는 것을 의미합니다. 또한, 숫자를 글로 풀어서 쓴 경우도 숫자 검사기(digit check)를 우회할 수 있는데, 이 검사기는 오직 숫자를 읽을 수 있기 때문입니다. 예를 들어, "다른 하이커들이 준 별점 네 개 반" 같은 문구는 세 가지 검증 단계를 모두 통과합니다. 얼마나 큰 격차가 있는지 확인해 볼 수 있습니다: 테스트에서는 여전히 통과하는 재구성 목록을 유지하고 있습니다. 이것이 바로 진정한 방어막인 구조적(structural) 측면입니다. 모델은 가격 정보를 절대 받지 못하며, 사양(spec) 어디에도 이를 넣을 곳이 없습니다.
이 블록은 첫 번째 HTML 응답의 일부이며 클라이언트 측 JavaScript가 필요하지 않습니다. 심지어 JavaScript를 실행하지 않는 크롤러도 이 내용을 읽을 수 있습니다.
당사의 500명의 쇼퍼(shopper) 벤치마크에서, 기본 모드는 페이지뷰 1,000회당 모델 호출을 460회 수행합니다. 만약 각 쇼퍼마다 생성한다면 1,000회가 될 것입니다.
상태: 0.9.1, 초기 버전. 설치하고 작동합니다: 아래의 시작하기(Getting started) 가이드는 모든 커밋에서 테스트로 실행됩니다. 하지만 1.0 이전에는 공개 API가 여전히 변경될 수 있습니다. 이러한 변경 사항은 모두 변경 로그(changelog)에 기록될 것입니다.
시작하기 (Getting started)
시작하는 데 API 키가 필요하지 않습니다. 제공자(provider)를 생략하면, @rudra-js/core가 자체적으로 블록을 구축합니다(모델 없이).
npm install @rudra-js/core@latest @rudra-js/react@latest @rudra-js/attested@latest
새로운 앱과 이미 rudra-js를 사용하는 앱 모두 이 하나의 명령만 사용하면 됩니다. 또한 업그레이드할 때도 마찬가지입니다. 만약 앱에 @rudra-js/anthropic이 있다면, 해당 명령어에도 @latest를 추가해야 합니다. @rudra-js/a2ui의 경우, 대신 해당 패키지의 README에 있는 설치 라인을 사용하세요. 이 라인은 두 개의 A2UI 패키지 이름을 명시합니다.
React 18 또는 19가 필요하지만, Server Components는 필요하지 않습니다. @rudra-js/react는 Hooks가 없는 순수한 React입니다. renderToString 및 클라이언트 렌더링된 앱에서 작동할 것입니다. 만약 프레임워크가 Server Components를 지원한다면, 그것으로도 사용될 수 있습니다. 이 블록을 첫 번째 HTML 응답에 넣으려면 서버 측에서 렌더링해야 합니다.
또한 Node 22.12 이상이 필요합니다.
import { createComponentGenerator, parseTrackingInput } from '@rudra-js/core';
import { RudraComponent } from '@rudra-js/react';
...
이 샘플을 사용하면, 이미 장바구니에 냄비(dutch oven)가 담겨 있는 스킬렛(skillet)을 보고 있는 쇼핑객에게 "장바구니와 함께 사용되는 제품"이라는 제목 아래 칼이 표시됩니다. 그들은 현재 보고 있는 제품이나 장바구니의 제품은 표시되지 않습니다. 모델에 요청하거나 비용이 청구되지는 않습니다.
Next.js에서는 샘플 하단에 export default recommendations를 추가하여 이를 페이지로 만드세요.
create-next-app으로 생성된 새로운 Next.js 앱에는 Cache Components가 활성화되어 있습니다. 이는 샘플과 generate 함수가 페이지 렌더링 시 클럭(clock)을 읽기 때문에 "Next.js encountered the unstable value Date.now() while prerendering" 오류로 빌드가 중단됩니다. 이를 수정하려면 npx create-next-app@latest my-app --yes --no-cache-components 명령어로 앱을 생성할 수 있습니다. 또한, next.config.ts에서 cacheComponents: true와 partialPrefetching: true를 삭제해도 됩니다. 자세한 내용은 quick start를 참고하세요.
모델을 사용할 준비가 되면 @rudra-js/anthropic를 추가하고 이를 provider로 전달하면 됩니다. 위의 다른 모든 설정은 동일하게 유지됩니다. 그러면 모델이 문구를 작성합니다. 또한 레이아웃과 강조점도 선택합니다. 기본적으로 그리드나 캐러셀에 있는 제품들은 여전히 core에 의해 선택됩니다. 이는 요청마다, 사용자가 전달하는 후보(candidates)들로부터 수행됩니다.
실제 쇼핑객 트래픽을 보낼 계획이라면, 먼저 Running it in a regulated shop를 읽어보세요.
Anthropic 어댑터를 사용할 필요는 없습니다. 어떤 모델이든 Any provider에 설명된 작은 인터페이스 뒤에 배치할 수 있습니다.
만약 A2UI 에이전트가 페이지를 구축한다면, @rudra-js/a2ui도 추가하세요.
패키지 (Packages)
| 패키지 | 기능 설명 |
|---|
@rudra-js/core | 추적 입력(tracking input)을 코드에서 렌더링할 수 있는 스펙(spec)으로 변환하는 스키마와 로직. 이 스펙은 @rudra-js/attested를 통해 검증됩니다. |
| ... | |
개발 환경 설정 (Development)
이 저장소에서 작업하려면 Node >=22.12가 필요합니다.
스텁 모델(stub model) 하에서 각 생성 모드의 비용을 확인하려면 다음 명령어를 실행하세요:
ANTHROPIC_API_KEY= RUDRA_REPLAY_ONLY=1 npm run bench. bench/README.md에는 열에 대한 설명이 나와 있습니다.
또한, 예시 쇼핑몰(example shop)을 빌드하고 크롤러가 여전히 해당 블록을 페이지의 일부로 인식하는지 확인하기 위한 두 번째 작업도 있습니다. CI 환경에서는 RUDRA_SHOP_MODE를 설정하지 않기 때문에, 쇼핑몰은 리플레이(replay)됩니다. 이 작업은 일반적인 빌드를 실행합니다:
npm run build --workspace @rudra-js/example-shop
pm run verify:crawlable
이 빌드는 로컬에서 단독으로 실행해도 안전합니다. 빌드 자체는 모델을 호출하지 않습니다. 쇼핑몰에 서비스를 제공할 때만 RUDRA_SHOP_MODE=record를 사용하면 비용이 발생합니다. 이를 기본값이 아닌 규칙으로 만들려면 아래 접두사(prefix)를 사용하세요:
ANTHROPIC_API_KEY= RUDRA_REPLAY_ONLY=1 npm run build --workspace @rudra-js/example-shop
예시 (Example)
examples/shop은 실제 페이지에서 rudra-js를 실행하는 작은 Next.js 쇼핑몰입니다. 이 제품 페이지는 LLM(대규모 언어 모델)에게 추천 블록을 요청합니다. 이 블록은 서버에 의해 페이지의 HTML 응답 일부로 렌더링됩니다. 따라서 페이지 로드 후에 가져오는 것이 아닙니다.
npm run dev --workspace @rudra-js/example-shop
이는 examples/shop/recordings/ 아래에 커밋된 트랜스크립트를 재생합니다. 여기에는 프롬프트와 모델의 답변으로 구성된 저장된 모델 호출이 포함됩니다. 환경 변수에 어떤 키가 설정되어 있더라도, 재현(replaying)하는 것만으로는 비용이 청구되지 않습니다. 돈을 쓰려면 RUDRA_SHOP_MODE를 record로 설정해야 합니다:
RUDRA_SHOP_MODE=record npm run dev --workspace @rudra-js/example-shop
이렇게 하면 아직 트랜스크립트가 없는 프롬프트마다 Claude를 한 번 호출하고, 답변을 새로운 트랜스크립트로 저장합니다. 만약 프롬프트에 이미 트랜스크립트가 있다면, 다른 페이지에서도 무료로 재생됩니다. 하지만 같은 페이지의 다른 쇼퍼는 트랜스크립트가 모델 ID와 프롬프트를 일치시켜야 하므로 새로운 호출이 필요할 수 있습니다.
examples/shop/README.md에서 나머지 내용을 다룹니다:
- 환경 변수(environment variables)
- 프롬프트 변경 후 트랜스크립트를 재녹화하는 방법
- 왜
recordings/ 아래의 파일은 데모 쇼퍼와 데모 카탈로그만 포함해야 하는지
도움받기
기여(Contributing)
이 저장소의 주요 목적은 rudra-js를 지속적으로 발전시켜 더 좋고 사용하기 쉽게 만드는 것입니다. CONTRIBUTING.md에는 설정 및 프로젝트가 다루는 범위에 대한 내용이 포함되어 있습니다. 또한 명명 규칙(naming)과 테스트 관례(testing conventions)도 다룹니다. 참여하는 모든 분들은 행동 강령(code of conduct)을 따라 주시기를 기대합니다.
특허(Patent)
미국에서 출원 대기 중입니다. 코호트 캐싱 디자인—spec-cache.ts의 결합된 캐시 키 및 프롬프트 투영(prompt projection)—에 대한 임시 출원(provisional application)이 2026년 9월 20일, 출원 번호 64/158,649로 제출되었습니다.
이는 rudra-js를 사용하는 방식에 변화를 주지 않습니다. 코드는 MIT 라이선스이며 계속 MIT 라이선스를 유지합니다. 이 출원은 방어적인 목적으로 제기된 것이므로, 다른 사람이 디자인을 특허 내고 사용자들을 따라잡는 것을 막기 위함입니다. 임시 출원은 심사되지 않으며 승인된 특허가 되지 않을 수도 있습니다.
라이선스(Licence)
[MIT] 라이선스 파일 참조](./LICENSE) © Clive Dsouza