Kebivo

Kebivo：AI エージェント向けのセルフホスト可能なナレッジギャップフィードバック

AI アシスタントが回答できなかった質問を収集します。

Kebivo は、REST または MCP 経由で AI エージェントから、未回答の質問や提案されたナレッジの修正を収集します。同じ報告をまとめ、管理者の受信トレイ、メール、または署名付き Webhook を通じて、ナレッジを管理する担当者に届けます。クラウドアカウントも AI プロバイダーも必要なく、1 つのコンテナで自分で運用できます。

Kebivo は、Langfuse や Phoenix などのオブザーバビリティおよびトレーシングツールと連携して動作します。これらのツールは、実行中に何が起きたかをエンジニアに示します。Kebivo はエージェントが報告したギャップを収集し、ナレッジを管理する担当者に送ります。RAG エンジンではないため、トレースのスコアリング、ドキュメントの検索、質問への回答は行いません。行わないことをご覧ください。

デモでは、アシスタントが質問に回答できず、エージェントが MCP 経由で report_knowledge_gap を呼び出します。ルーティングルールにより、報告が Webhook 経由でドキュメント担当者に届きます。同じ質問が繰り返されると同じグループにまとめられるため、通知を増やさずに件数が増えます。担当者はメモを追加し、グループを解決済みとしてマークします。製品画面は合成データを使った実際の Kebivo コンテナのスクリーンショットです。チャットとエンドカードは描画したものです。ソースは docs/assets/demo-src にあります。

ステータス：最初のリリースである 0.1.0 です。 公開済みイメージ ghcr.io/ocnai/kebivo:0.1.0（linux/amd64、linux/arm64）を実行するか、このリポジトリからビルドしてください。Apache-2.0 ライセンスです。

クイックスタートから始めてください。フレームワークのチュートリアルについては、Kebivo ガイドをご覧ください。デプロイ、API の動作、制限については、技術ドキュメントをご利用ください。

なぜ必要か

アシスタントが回答できなかったとき、ドキュメント担当者はその質問を知らないままかもしれません。同じ質問で再び失敗することがあり、チャットで提案された修正が、コンテンツを管理する担当者に届かないこともあります。Kebivo はそうした報告を 1 か所に集め、担当者がトリアージして、使用しているツールに振り分けられるようにします。

AI アシスタントが質問に回答できないと、Kebivo はそのナレッジギャップをドキュメントまたはサポートの担当者に送り、確認を促します。繰り返される質問をまとめるため、担当者は何度も話題に上がる問題を把握できます。RAG アプリケーションやエージェントフレームワークと併用できますが、コンテンツの検索やナレッジベースの更新は行いません。

機能

• アプリケーションコードから REST 経由でレポートを送信するか、エージェントに Streamable HTTP MCP ツール report_knowledge_gap と submit_knowledge_correction を提供します。
• アシスタントまたはチームごとにプロジェクトを作成し、デフォルトのタグ、修正ポリシー、一度だけ表示され、有効期限を設定したり取り消したりできるベアラートークンを設定します。
• 順序付きルール、ANY／ALL タグ照合、ルールごとの複数の宛先、フォールバック、ドライランシミュレーターを使ってレポートを振り分けます。
• バージョン管理された JSON ペイロードを使う署名付き Webhook、SMTP メール、または組み込みの受信トレイに配信します。配信は、バックオフ付きの永続的な再試行、再起動後の復旧、配信ログ、手動での再試行に対応しています。
• 同一の質問は自動的にグループ化されます。LLM プロバイダーを設定して、意味に基づくグループ化を行うこともできます。
• 受信トレイでレポートをトリアージできます。検索、フィルター、ステータス、メモ、タグ、統合、分割、削除に対応しています。各グループには全履歴が記録されます。
• プロジェクトごとに OpenAI 互換、Azure OpenAI、またはローカル（Ollama、LM Studio）プロバイダーを有効にして、意味に基づくグループ化を行えます。この機能はデフォルトで無効です。
• SQLite ファイルを 1 つ使ってコンテナーを 1 つ実行します。起動時のマイグレーション、オンラインバックアップと検証付き復元、保持（デフォルトで有効）、JSON Lines エクスポート、ヘルスチェックが含まれています。

スクリーンショット

すべてのスクリーンショットには合成データを使用しています。

ダッシュボード	受信トレイ
フィードバックグループ	クライアントを接続
振り分けルール	失敗した配信

その他：宛先、設定、LLM 設定、サインイン。make e2e-ui SCREENSHOTS=1 で再生成できます。

対応していないこと

• 質問への回答、ナレッジベースの編集、修正の適用は行いません。すべて人が確認します。
• チャットボット、チケット管理システム、分析製品ではありません。フィードバックを、お使いのツールに渡します。
• マルチユーザーアカウント、SSO、ロールには対応していません。ローカル管理者は 1 人です。
• ホスト型サービス、テレメトリー、アカウントはありません。デフォルトのインストールでは外部への接続は行わず、AI プロバイダーも不要です。
• 高可用性には対応していません。ローカルストレージ上で、1 つのプロセスと 1 つの SQLite ファイルを使用します。

クイックスタート

Docker Compose、OpenSSL、および空いているポート 8000 が必要です。

1. Kebivo を起動します。

git clone <REPOSITORY_URL> kebivo
cd kebivo
cp .env.example .env
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'ENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'ALLOWED_ORIGINS=http://127.0.0.1:8000\n' >> .env
docker compose up --build -d
curl -fsS http://127.0.0.1:8000/health/ready

<REPOSITORY_URL> は、クローン元のアドレスです。最初のビルドには数分かかります。マイグレーションが適用されると、準備完了の応答として {"status":"ok",...} が返ります。

または、クローンしてビルドする代わりに公開イメージを実行します。 同じコンテナです。kebivo.env は非公開にし、データボリュームとは別にバックアップしてください。

(umask 077; printf 'SECRET_KEY=%s\nENCRYPTION_KEY=%s\nALLOWED_ORIGINS=http://127.0.0.1:8000\n' \
  "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > kebivo.env)
docker run -d --name kebivo --restart unless-stopped -p 127.0.0.1:8000:8000 \
  -v kebivo-data:/data --env-file kebivo.env ghcr.io/ocnai/kebivo:0.1.0
curl -fsS --retry 30 --retry-all-errors --retry-delay 1 http://127.0.0.1:8000/health/ready

マイグレーションの実行中に curl が Connection reset エラーを数回出力することがありますが、その後、準備完了の応答として {"status":"ok",...} が返ります。このコンテナを使用する場合は、ステップ 2 のコマンドを docker exec -it kebivo python -m kebivo.cli bootstrap --email [email protected] として実行し、docker stop kebivo で停止します。データは kebivo-data ボリュームに保持されます。

2. 管理者を作成します。 コマンドの実行時にパスワードを求められます（12 文字以上）。

docker compose exec app python -m kebivo.cli bootstrap --email [email protected]

3. プロジェクトとトークンを作成します。 http://127.0.0.1:8000/ を開き（このアドレスを正確に使用してください。localhost は別のオリジンとなり、サインインに失敗します）、サインインします。プロジェクトを作成し、Project tokens で feedback:gap スコープのトークンを発行してコピーします。トークンは一度しか表示されません。

4. 最初のイベントを送信します。

export KEBIVO_TOKEN='<PROJECT_TOKEN>'
curl -i http://127.0.0.1:8000/api/v1/feedback \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KEBIVO_TOKEN" \
  -H 'Idempotency-Key: first-event-001' \
  --data '{"event_type":"knowledge_gap","question":"How do I reset my corporate VPN?","tags":["it"]}'

応答は 202 Accepted で、event_id が含まれます。5. UI で受信トレイを開きます。 質問が独立したグループとして表示されます。宛先とルーティングルールを追加すると、次のイベントからメールまたは Webhook に送信できます。

停止するには docker compose down を実行します（データは保持されます）。docker compose down --volumes を実行すると、すべてのデータが削除されます。本番環境（TLS、バックアップ、アップグレード、すべての設定）については、セルフホスティングガイドをお読みください。

REST で AI エージェントのフィードバックを収集する

プロジェクトトークンを使って POST /api/v1/feedback を送信します。202 はレポートが永続的に保存されたことを意味します。ルーティングと配信はバックグラウンドで行われます。Idempotency-Key を送信し、再試行時にも同じ値を使ってください。429 と 5xx の応答はバックオフを行って再試行し、その他の 4xx エラーは再試行しないでください。

実行可能なクライアントとして、cURL、Python（標準ライブラリ）、TypeScript（Node.js 24、ビルド不要）が examples/ にあります。また、UI のプロジェクトページには、使用中のエンドポイントを含む同じスニペットが表示されます。REST 統合ガイドでは、フィールド、認証、冪等性、エラー、再試行、レート制限について説明しています。

MCP でナレッジギャップを報告する

MCP クライアントから、ヘッダー Authorization: Bearer <PROJECT_TOKEN> を付けて http://127.0.0.1:8000/mcp に接続します。Claude Code の場合：

claude mcp add --transport http kebivo http://127.0.0.1:8000/mcp --header "Authorization: Bearer <PROJECT_TOKEN>"

feedback:gap を持つトークンでは report_knowledge_gap を使用できます。submit_knowledge_correction には feedback:correction も必要で、プロジェクトが修正を受け付けている必要があります。モデルが必要なときにツールを呼び出さないこともあるため、すべてのレポートが重要な場合は REST を使用してください。MCP ガイド、クライアント設定、Python クライアント、コピーして使えるエージェント向け指示をご覧ください。

宛先とルーティング

宛先	送信内容
組み込みの受信トレイ	常に利用可能です。すべてのイベントが管理者の受信トレイに表示されます。
Webhook	HTTPS POST で、バージョン管理された JSON ペイロードを送信します。Standard Webhooks の署名に対応し、任意でベアラーまたはカスタムヘッダーを設定できます。受信側の例では、両方の署名を検証します。
SMTP メール	STARTTLS、暗黙的 TLS、または認証なしのローカルリレーを通じて、1～20 人の受信者にメッセージを送信します（プレーンテキストと、エスケープ済み HTML の代替形式）。

各プロジェクトには順序付きのルールがあります。ルールはタグの ANY または ALL に一致し、任意で評価を停止しながら、1 つ以上の宛先に送信します。一致しないイベントはフォールバック宛先に送信されます。例：it → IT 部門のメール、customer-service → サポート用 Webhook。各宛先では、新しいグループに対してのみ配信するか、発生のたびに配信するかを設定できます。ルーティングと宛先をご覧ください。

オプションの AI

デフォルトではモデルは呼び出されません。表現の異なる質問をまとめるには、LLM プロバイダー（UI の LLM settings）を設定し、質問文がそのプロバイダーに送信されることを確認したうえで、プロジェクトをセマンティック重複排除に切り替えます。プロバイダーが失敗した場合、イベントは独自のグループにとどまり、引き続きルーティングされ、配信されます。重複排除とLLM プロバイダーを参照してください。

セキュリティ

• TLS リバースプロキシの背後で実行し、アプリのポートをループバックに限定してください（ガイド）。
• .env は非公開にしてください。SECRET_KEY と ENCRYPTION_KEY は、データベースのバックアップとは別にバックアップしてください。
• フィードバックは SQLite に暗号化されずに保存されます。ボリュームとバックアップを保護し、アシスタントに秘密情報や不要な個人データを送信させないでください。
• 各クライアントに個別のトークンを付与し、顧客対応エージェントには feedback:gap のみを許可し、使用しなくなったトークンは失効させてください。
• Webhook と LLM プロバイダーがプライベートアドレスやループバックアドレスにアクセスすることは、宛先またはプロバイダーごとに明示的に許可しない限りできません。クラウドメタデータのアドレスは SMTP でも常にブロックされます。管理者による書き込みには、設定済みの Origin と CSRF トークンが必要です。
• ログにフィードバックの内容や認証情報が含まれることはありません。

脆弱性は SECURITY.md の説明に従って報告してください。

データ、保持、エクスポート

データ保持はデフォルトで有効です。180 日を超えたフィードバック、完了した配信試行の詳細のうち 30 日を超えたもの、90 日を超えた監査エントリは、毎日削除されます。環境変数で個別に変更または無効化できます（0 で無効になります）。データ保持の設定は、すでに作成したバックアップには適用されません。管理者はプロジェクトのフィードバックを JSON Lines 形式でエクスポートできます。データ保持とエクスポートを参照してください。

既知の制限

• 少なくとも 1 回の配信。 受信側に配信が 2 回届く場合があります。Webhook ID または配信 ID で重複を排除してください。
• ローカルストレージ上の 管理者 1 人、インスタンス 1 つ、SQLite ファイル 1 つ。レプリカやネットワークファイルシステムには対応していません。
• MCP ではベアラートークンを手動で設定する必要があります。OAuth のみのクライアントは接続できません。レスポンスはステートレスな JSON であり、ストリーミング通知には対応していません。
• レート制限はメモリ上でカウントされ、コンテナの再起動時にリセットされます。
• 削除したフィードバックは、すでに受信した宛先や既存のバックアップから取り消すことはできません。
• フィードバックの内容は保存時に暗号化されません。

ドキュメント

フレームワークのチュートリアルはウェブサイトのガイドにあります。実行可能なクライアントとフレームワークの例は examples/ にあります。以下のページでは技術的な詳細を説明しています。

ガイド	内容
セルフホスティング	要件、すべての設定、TLS プロキシ、秘密情報、バックアップと復元、アップグレード、認証情報のローテーション、トラブルシューティング
REST API	認証、フィールド、冪等性、エラー、再試行、例
MCP	クライアントの接続、ツールと権限、テスト、制限事項
ルーティングと宛先	ルール、フォールバック、Webhook、署名、SMTP
重複排除とLLM プロバイダー	厳密なグループ化とセマンティックなグループ化、プロバイダー、プライバシー
フィードバック管理	グループ、検索構文、ステータス、統合、分割、削除
データ保持とエクスポート	自動削除、JSON Lines エクスポート
リリース	バージョン管理、イメージラベル、リリースとアップグレードの確認
サードパーティライセンス	同梱されている依存関係の一覧
変更履歴	バージョンごとのユーザー向け変更

貢献

開発環境のセットアップ、make のターゲット、スタイル、テスト、ドキュメントに関するルールは CONTRIBUTING.md に記載されています。概要は次のとおりです。make install を実行し、コミットの前に毎回 make check を実行して、同じ変更でドキュメントも更新してください。すべてのコミットに Developer Certificate of Origin に基づく署名（git commit -s）を付けてください。CLA はありません。

参加者は全員、行動規範を遵守してください。検討中のアイデア（確定事項ではありません）はロードマップに記載されています。

ライセンス

Kebivo は Apache License 2.0 のもとでライセンスされています。貢献は、Developer Certificate of Origin に基づく署名付きで、同じライセンスのもと受け入れられます。CLA はありません。サードパーティライセンス一覧には、イメージに含まれるすべてのもののライセンスが記載されています。