@xenkai-inc/llm

Xenkai LLM SDK — server-side 専用の薄いラッパー。

市民開発者が Cloudflare Pages Functions / Workers で Claude / Gemini を呼び出すための最小限のインターフェースを提供する。認証情報の記述はゼロ。

重要: このパッケージは server-side 専用です。ブラウザでは動作しません。 理由: Cloudflare Access が付与する Cf-Access-Jwt-Assertion ヘッダはブラウザ環境では取得できないため。

バージョン安定性について（v0 unstable）

現バージョン（0.x）は unstable です。破壊的変更が予告なく行われることがあります。

• 0.x の期間は、minor バンプ（例: 0.1.x → 0.2.0）でも破壊的変更を含む可能性があります。
• 1.0.0 到達時点で SemVer（Semantic Versioning）に準拠し、breaking changes は major バンプでのみ行います。
• 本番利用時はバージョンを pin することを強く推奨します（例: "@xenkai-inc/llm": "0.1.1"）。

インストール

monorepo 内（workspace 参照）

xenkai-citizen-dev-platform monorepo に相乗りする場合、npm install のみで利用できる。

# monorepo root で
npm install

apps/chat 等のパッケージから @xenkai-inc/llm を依存に追加する場合:

{
  "dependencies": {
    "@xenkai-inc/llm": "*"
  }
}

外部リポジトリから（npmjs）

別プロジェクトのリポジトリから利用する場合は npmjs.com から認証なしで install できる。

npm install @xenkai-inc/llm

.npmrc の設定や PAT（Personal Access Token）の発行は不要。

使い方

Pages Functions での使い方

// apps/chat/functions/api/chat.ts
import { XenkaiLLM } from '@xenkai-inc/llm';
import type { Message } from '@xenkai-inc/llm';

export const onRequestPost: PagesFunction = async ({ request }) => {
  const { messages, model } = await request.json<{
    messages: Message[];
    model?: 'claude-sonnet-4-6' | 'gemini-3.1-flash-lite';
  }>();

  const llm = new XenkaiLLM(request);

  // ストリーミング応答（useChat フック互換）
  return llm.stream(messages, { model });
};

Cloudflare Workers での使い方

// workers/my-worker/src/index.ts
import { XenkaiLLM } from '@xenkai-inc/llm';
import type { Message } from '@xenkai-inc/llm';

export default {
  async fetch(request: Request): Promise<Response> {
    const llm = new XenkaiLLM(request);

    // 非ストリーミング応答
    const response = await llm.chat([
      { role: 'user', content: 'Xenkai の業務改善アイデアを3つ挙げてください。' },
    ]);

    return new Response(response.content, { headers: { 'Content-Type': 'text/plain' } });
  },
};

API リファレンス

new XenkaiLLM(request, options?)

| パラメータ | 型 | 必須 | 説明 | |---|---|---|---| | request | Request | 必須 | Pages Functions / Worker の Request オブジェクト | | options.baseURL | string | 任意 | Worker の URL（デフォルト: https://llm.xenkai.jp） |

request.headers.get('Cf-Access-Jwt-Assertion') が空の場合は Error を throw する。

llm.chat(messages, options?)

非ストリーミング応答。短い応答や同期的な処理が必要な場面で使う。

const response = await llm.chat(messages, {
  model: 'gemini-3.1-flash-lite',   // デフォルト: 'claude-sonnet-4-6'
});
// response.content: string
// response.usage: { promptTokens: number; completionTokens: number }
// response.model: ModelId

llm.stream(messages, options?)

ストリーミング応答。チャット UI でのリアルタイム表示に使う。

// Response オブジェクトをそのまま返す（useChat 互換）
return llm.stream(messages, { model: 'claude-sonnet-4-6' });

Worker が返す text/event-stream（AI SDK data stream protocol）を Response オブジェクトとしてそのまま返すため、@ai-sdk/react の useChat フックと直接互換性がある。

ChatOptions

v1.1 変更点: sessionId オプションを削除。Worker はステートレスになり、履歴管理は呼び出し側（Pages Functions）が担う。

interface ChatOptions {
  model?: 'claude-sonnet-4-6' | 'gemini-3.1-flash-lite';
}

Message

interface Message {
  role: 'user' | 'assistant';  // 'system' は受け付けない（Prompt Injection 防止）
  content: string;
}

エラーハンドリング

HTTP エラーは XenkaiLLMError として throw される。

import { XenkaiLLM, XenkaiLLMError } from '@xenkai-inc/llm';

try {
  const response = await llm.chat(messages);
} catch (err) {
  if (err instanceof XenkaiLLMError) {
    switch (err.status) {
      case 401:
        // JWT 欠落 or 期限切れ → Cloudflare Access 再ログインへ誘導
        return new Response(null, { status: 302, headers: { Location: '/login' } });
      case 403:
        // JWT 不正 or Linked App Token policy 違反
        return new Response('認証エラー', { status: 403 });
      case 429:
        // rate limit
        const retryAfter = err.retryAfter ?? '60';
        return new Response(`現在混雑しています。${retryAfter}秒後に再試行してください`, { status: 429 });
      case 400:
        // モデル不正 / messages 超過
        return new Response('リクエストが不正です', { status: 400 });
      default:
        // 5xx — Worker / AI Gateway / プロバイダ障害
        return new Response('内部エラー', { status: 502 });
    }
  }
  throw err;
}

baseURL のカスタマイズ

開発環境や別インスタンスへの向き先変更:

const llm = new XenkaiLLM(request, {
  baseURL: 'https://llm-staging.xenkai.jp',
});

ローカル開発では LLM 利用不可（[memo-local-dev-api-tradeoff-v0] 参照）。Cloudflare Pages のプレビュー URL で動作確認する。

依存関係

依存ライブラリなし。標準 fetch / Request / Response API のみ使用。

AI SDK（ai / @ai-sdk/*）は Worker 側（workers/llm-proxy/）で完結しており、このパッケージには含まれない。

公開状況

npmjs.com への public 公開を予定（移行対象）。org 作成・NPM_TOKEN 登録・tag push 完了後に外部リポジトリから認証不要で npm install @xenkai-inc/llm で利用可能になります。公開完了後はこのドキュメントを更新してください。

関連

• Worker 実装: /workers/llm-proxy/
• JWT 検証共通モジュール: /packages/cf-access/
• チャットアプリ: /apps/chat/
• 設計仕様: T0328 spec