icey1287/SuperMew

SuperMew – 監査可能な、RAGファーストのエージェントプラットフォーム

概要 – SuperMewはセルフホスト型のAIエージェントフレームワークであり、すべてのユーザーインタラクションを一回限りのHTTP呼び出しではなく、永続的で再生可能なワークフローとして扱います。会話スレッド、実行（Runs）、イベント、チェックポイントを連携させることで、チャットをヒューマン・イン・ザ・ループ（HITL）レビューのために一時停止し、後で再開し、完全に監査することが可能になります。

コアコンセプト

永続化されたドメインオブジェクト – Thread、Message、Run、Event、Checkpoint、DocumentVersionはPostgreSQL（メタデータ）とMilvus（ベクトルチャンク）に保存されます。これにより、過去のインタラクションを再生したりデバッグしたりできます。
2段階のドキュメント公開 – 新しいドキュメントバージョンは隔離された候補スコープ内で構築され、検証された後、PostgreSQLのCAS操作によってアトミックに切り替えられます。進行中のクエリは、未完成のインデックスを見ることはありません。
ハイブリッドRAGパイプライン – 高密度ベクトル検索（Milvus）とネイティブBM25がReciprocal Rank Fusionで融合され、必要に応じて再ランキング、証拠品質の判定が行われ、単一のHyDEまたはステップバック書き換えにフォールバックできます。すべての中間ステップはUIで可視化されるrag_traceに記録されます。
スキル/ツールレジストリ – 固定バージョンのスキル（ナレッジベース検索、天気、読み取り専用SQL、ウェブリサーチ、サンドボックス化されたコード実行、制限付きHTTPS JSON）はレジストリで宣言されます。各ツールのスキーマは、実行の権限チェック後にのみエージェントに開示され、ガードレールが許可/拒否/承認ポリシーを強制します。
モデル制御プレーン – 管理者はモデルプロファイル（シークレットなし）を定義し、4つのロールに割り当てます：Answer、Fast、Grader、Evaluator。Runまたは評価ジョブが作成されると、正確なモデルスナップショットが凍結され、再現性が保証されます。
RAG評価フレームワーク – バージョン管理されたデータセット、ベースライン比較、CIゲート方式の品質チェック、永続的な評価ワーカーにより、正確性、根拠性、関連性、完全性、未サポートの主張、矛盾の開示を自動的に測定できます。
セキュリティと認証 – 短命なインメモリアクセストークン、HttpOnlyクッキーに保存されるローテーション可能な不透明なリフレッシュトークン、RBAC、エンドポイントごとのレート制限HMAC、CSP/ヘッダー、ASTとRLSチェックを備えた読み取り専用SQLサンドボックス。

なぜ重要なのか – すべてのステップを永続化することで、SuperMewは以下を可能にします：

監査 – どのドキュメント、ツール、モデル出力が応答を生み出したかを正確に追跡します。
再開 – 人間のレビューアが明確化を追加した後、一時停止された会話を再開します。
バージョン管理 – 既存のRunを壊さずにナレッジベースとモデル設定をバージョン管理します。
ベンチマーク – 本番環境に近い環境でRAGパイプラインをエンドツーエンドでベンチマークします。

アーキテクチャ概要

コンポーネント	技術	役割
APIサーバー	FastAPI (Python 3.12)	HTTP、SSE、認証、スレッド/Runオーケストレーション、静的フロントエンド配信
インデックスワーカー	Pythonモジュール `backend.workers.indexing`	不変なドキュメントバージョンの構築、Milvusベクトルの書き込み、候補スコープの管理
RAG評価ワーカー	Pythonモジュール `backend.workers.evaluation`	オフライン評価ジョブの実行、メトリクスの計算、結果の保存
ベクトルストア	Milvus (高密度 + ネイティブBM25)	高速な近傍検索
メタデータストア	PostgreSQL + SQLAlchemy + Alembic	スレッド、Run、イベント、モデルスナップショット、ドキュメントカタログ
キャッシュ / 低遅延通知	Redis	イベントプッシュ、レート制限カウンター
オブジェクトストレージ	MinIO (ワーカーで使用)	アップロードされた生ドキュメント
フロントエンド	Vite + Vue 3 + TypeScript + Pinia	チャット、スキルセンター、管理パネル、評価ワークベンチのUI

始める（ローカル開発）

前提条件 – Python 3.12+、uvパッケージマネージャー、Node 20+、Docker Compose。
設定 – .env.exampleを.envにコピーし、以下を入力します：
- モデル識別子 (MODEL、FAST_MODEL、…)
- JWT_SECRET_KEY (32文字以上のランダム文字列)
- 任意の管理者招待コード。
依存関係の起動 – docker compose up -d (Postgres、Redis、etcd、MinIO、Milvus、Attu)。
Python依存関係のインストール – uv sync --frozen。
フロントエンドのビルド – cd frontend && npm ci && npm run build && cd ..。

マイグレーションと健全性チェックの実行 –

uv run --frozen alembic upgrade head
uv run --frozen python -m backend.tools.registry_cli validate

3つのプロセスの起動 – ./scripts/start.sh (API、インデックスワーカー、評価ワーカー)。ホットリロードを無効にするには--no-reloadを使用します。
UIは http://127.0.0.1:8000/、OpenAPIは http://127.0.0.1:8000/docs、Milvus Attuは http://127.0.0.1:8080/ を開きます。

本番環境チェックリスト（概要）

同じ3つのサービス（API、インデックスワーカー、評価ワーカー）をスーパーバイザー（systemd、k8sなど）の下でデプロイし、同じコードバージョンとUPLOAD_DIRを共有していることを確認します。
APP_ENV=productionを設定し、JWT、レート制限HMAC、DBパスワード、モデルプロバイダーキーの実際のシークレットを提供します。
セキュアークッキーを有効にします (AUTH_REFRESH_COOKIE_SECURE=true)。
ワーカーをAPIより前に起動し、ヘルスチェックを実行し、パブリックエンドポイントを公開する前に最小限のエンドツーエンドテスト（スレッド作成、ドキュメントアップロード、RAGクエリ実行、小さな評価ジョブの開始）を行います。
期限切れのリフレッシュトークン台帳を削除するために、クリーンアップタスク python -m backend.auth.cleanup を定期的に実行します。

典型的なユースケース

ユースケース	SuperMewの支援内容
エンタープライズナレッジベースQ&A	PDF/ドキュメントをアップロードし、バージョン管理し、監査証跡を保持しながらハイブリッド検索でエージェントが取得するようにします。
ヒューマン・イン・ザ・ループサポート	`Checkpoint`でRunを一時停止し、レビューアがツール呼び出しを編集または承認し、コンテキストを失わずに再開します。
規制環境	厳格な許可リスト、サンドボックス化されたコード実行、ポリシー駆動のツールガードレールを備えた読み取り専用SQLアシスタントがコンプライアンスニーズを満たします。
モデル/RAGベンチマーク	データセットを定義し、評価ワーカーを実行し、ベースラインと比較し、品質メトリクスに基づいてリリースをゲートします。
カスタムスキル統合	レジストリを通じて新しいHTTP-JSONツールまたはドメイン固有のスキルを追加します。プラットフォームはバージョン管理、権限チェック、UI公開を自動的に処理します。

TL;DR

SuperMewは、検索拡張生成（RAG）に依存する本番環境グレードのAIエージェントを構築するためのフルスタック、オープンソースプラットフォームです。耐久性、監査可能性、ヒューマン・イン・ザ・ループ制御、安全なバージョン管理ツールを重視しています。すべてのステップを検査、再生、またはゲートできるセルフホスト型RAGシステムが必要な場合、SuperMewはPostgreSQLベースのイベントソーシングからVueベースのUI、堅牢な評価フレームワークまでの完全なスタックを提供します。