Semantic Sift

🔍 Semantic-Sift

高忠実度のエージェント型ワークフローを実現する、推論ファーストのミドルウェア。

「コンテキストを維持しながらトークンを節約し、推論を最大化して、幻覚を最小限に抑えます。」

Semantic-Sift は、ローカルで動作する Model Context Protocol (MCP) サーバーです。生データと AI のコンテキストウィンドウの間に、インテリジェントな「サニタイズ層」として機能します。

最新の LLM は巨大なコンテキストウィンドウを備えていますが、ノイズが増えるにつれて推論の精度が低下することがよくあります。Semantic-Sift は、LLMLingua-2 を使用して技術ログ、長文ドキュメント、チャット履歴を高密度なコンテキストへと凝縮し、この問題を解決します。コンテキストウィンドウを貴重なリソースとして扱い、**信号対雑音比（SNR）**を最適化することで、モデルが定型文の処理に費やす時間を減らし、推論により多くの時間を使えるようにします。

🧠 哲学：二人のスタジオ

Semantic-Sift は、人間のアーキテクトと自律型 AI サイドカーが高忠実度で協働することこそ、エンジニアリングの未来だという二人のスタジオの哲学に基づいています。生データの取り込みに伴う摩擦を管理することで、Sift はこの「スタジオ」が単に パッチ を適用するのではなく、システム の構築に集中できるようにします。認知フィルターとして機能し、あなたとエージェントの双方が、技術的な事実を最も明確かつ適切に表現した情報をもとに協働できるようにします。

---

⚡ クイックスタート（60秒）

# 1. Install
pip install "semantic-sift[neural]"

# 2. Onboard your project (writes IDE hooks and opencode.json)
semantic-sift-onboard   # or: ask your AI "Run sift_onboard()"

# 3. Add to your MCP config (example: Cursor / Claude Desktop)
# { "mcpServers": { "semantic-sift": { "command": "semantic-sift" } } }

# 4. Warm up the model (optional — avoids first-call latency)
# Ask your AI: "Run sift_warmup()"

セットアップ完全ガイド（venv の構成、IDE 設定マトリックス、Sovereign Pattern）：doc/INTEGRATION_ENCYCLOPEDIA.md

---

🏛️ 学際的な価値

Semantic-Sift は、4つの主要な職種における注意力の管理を目的に設計された戦略的なレイヤーです。

• シニアエンジニア向け： デュアルエンジン方式（ヒューリスティック・シーブ＋ニューラル・リランカー）を採用した、ローカルファーストで低レイテンシのミドルウェアです。タイムスタンプ、繰り返しの定型文、冗長な JSON を送信前に精査し、レイテンシを低減するとともに、「Lost in the Middle」による推論の失敗を防ぎます。
• プロジェクトマネージャー向け： 「コンテキスト保険」です。トークンのオーバーヘッドを30～70％削減することで、Sift は API コストに対する直接的な投資収益をもたらし、雑然としたデータ環境でモデルが幻覚を起こすことによる「リトライループ」を減らします。
• 研究者向け： 大規模環境でのデータ整合性を実現します。MarkItDown（[multi-modal] のオプション追加機能経由）をサポートし、複雑な .pdf、.docx、.xlsx を構造化された、要点を凝縮した Markdown に変換できます。重要な意味上の手掛かりを失わずに、大規模な技術リポジトリを迅速に統合できます。
• ナレッジパートナー向け： 認知負荷を管理します。Sift は生データの取り込みに伴う摩擦を管理し、人間と AI のパートナーシップが手作業でデータを仕分けるのではなく、高度な戦略やアーキテクチャ上の意思決定に集中できるようにします。

---

💰 バリューエンジニアリング：運用面と経済面の投資収益率

Semantic-Sift は二層の価値を提供します。経済的なメリットは料金プランによって異なりますが、運用上のメリットはあらゆるプロフェッショナルなワークフローに当てはまります。

1. 経済的な ROI（直接的なコスト削減）

対象：トークン単位の API プランを利用しているユーザー（GPT-4o、Claude 3.5）。

• コストの保護： Sift はローカルフィルターとして機能し、通常、送信トークン量を 30～70％削減します。
• 複利効果： 反復的なエージェントのループでは、こうした削減効果が急速に積み重なります。取り除かれた文字の一つひとつが、予算の節約につながります。

2. 運用上の ROI（品質とパフォーマンス）

対象：すべてのユーザー（「無制限」またはリクエスト単位のサブスクリプションを利用しているユーザーを含む）。

• 注意力の精度： 「無限」のコンテキストがあっても、LLM は「Lost in the Middle」症候群に悩まされます。ノイズを取り除くことで、モデルの推論能力を技術的なシグナルに集中させ、より高品質なコードとハルシネーションの減少を実現します。
• レイテンシの低減： プロンプトが小さくなれば、「最初のトークンが出力されるまでの時間」（TTFT）も短縮されます。定型文を「クラウド」が処理するのを待つ時間が減り、フロー状態を保てる時間が増えます。
• コンテキストの保険： 複雑なタスクで「Context length exceeded」エラーが発生するのを防ぎます。Sift は、モデルの上限を 100％、書式ではなく情報で満たします。

---

📚 ドキュメント総合インデックス

技術的な詳細、アーキテクチャのロジック、統合ガイドは、要約によるデータ損失を防ぐため、すべて doc/ ディレクトリで厳密に管理されています。

• doc/INDEX.md：ドキュメント構成のナビゲーションマップおよび信頼できる情報源です。
• doc/ARCHITECTURE.md：Sift Hook Interceptor、Distillation Kernel（Heuristic／Semantic／Ranking エンジン）、キャッシュの仕様です。
• doc/TOOL_REFERENCE.md：すべての FastMCP ツール（例：sift_read_file、sift_logs、sift_chat、sift_rank）を網羅したオペレーター向けマニュアルです。
• doc/INTEGRATION_ENCYCLOPEDIA.md：IDE（Cursor、Gemini、VS Code、OpenCode など）との接続に関する、互換性マップ、Hook Injector のロジック、ペイロード構造、総合設定マトリックスです。
• doc/TELEMETRY_SPEC.md：OpenTelemetry トレーシング、Echo-Detector（二重 Sifting の防止）、監査ヘッダー、プライバシー制御の設計です。
• doc/ORCHESTRATION_BLUEPRINTS.md：ファイル取り込みの判断ツリー、マルチドキュメント RAG、履歴の圧縮など、AI エージェント向けの実践的なワークフローです。

---

🎯 効果の大きいユースケース

📚 知識を探求するユーザー（研究者・アーキテクト）

• 課題： 50 ページの PDF、複雑な Word 仕様書、雑然としたドキュメントサイトを読むこと。
• Sift の効果： [multi-modal] オプションのエクストラを通じて MarkItDown をサポートし、.pdf、.docx、.xlsx をネイティブに取り込めます。企業内の「ノイズ」を構造化された Markdown に変換することで、エージェントは 1 回のターンで複数の 14MB のドキュメントを統合できます。

🛠️ ログを探求するユーザー（DevOps・SRE）

• 課題： 技術ログ 100,000 行の中から、1 つのエラーを見つけること。
• Sift の効果： Heuristic Sieve がタイムスタンプや定型文を数ミリ秒で整えます。Subconscious Hook が結果を自動で再ランク付けするため、エージェントには最も関連性の高いデータブロックだけが表示されます。

🧠 コンテキスト戦略を立てるユーザー（AI エンジニア）

• 課題： 整理されていないデータストリームによる、LLM のハルシネーションや推論能力の低下。
• Sift の効果： 意味の 95％を保持した高密度のコンテキストを提供することで、Sift は認知の橋渡しとして機能します。LLM の注意力をシグナルだけに集中させます。

---

⚡ パフォーマンスティア

Semantic-Sift には、2 つのパフォーマンスティアがあります。ユースケースに応じて選択してください。

	Python MCP Server (pip install semantic-sift)	Rust CLI Sidecar (sift-core)
ヒューリスティックなログの絞り込み	✅ 約500ms	✅ 1ms未満（ネイティブ）
ニューラルセマンティック絞り込み	✅ 約500ms（PyTorch）	✅ 約150ms（ONNX）
Python の依存関係	必須	なし
Rust ツールチェーン	不要	不要（ビルド済み）
配布方法	PyPI ホイール（ビルド済みの sift-core を含む）	ホイールに同梱。開発用インストールでは fetch_sift_core.py を使用

PyPI ホイール（pip install semantic-sift）：コンパイル済みの sift-core バイナリが同梱されているため、Rust ツールチェーンは不要です。

編集可能／開発用インストール（pip install -e .）：Rust のコンパイル手順はスキップされます。ビルド済みバイナリを取得するため、次のコマンドを一度実行してください。

python scripts/fetch_sift_core.py

任意の [native] マーカー：明示的な指定が必要な依存関係管理ツール向けに、pip install semantic-sift[native] を指定できます。これは何もしない追加指定です（バイナリは常にホイールに含まれています）。

---

🚀 クイックスタート

1. インストール

オプション A：クイックインストール（PyPI）

ℹ️ インストールされるもの： PyPI ホイールには、コンパイル済みの sift-core Rust バイナリが含まれているため、Rust ツールチェーンは不要です。[neural] オプションを追加すると、LLMLingua-2 を使って大きなペイロードをフォールバック処理するための PyTorch（約1.5 GB）がインストールされます。[multi-modal] を追加すると、PDF／DOCX／XLSX の取り込み用に MarkItDown がインストールされます。PyTorch のダウンロードサイズにより、初回のインストールには数分かかる場合があります。

uv venv
# Windows: .\.venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
uv pip install semantic-sift[neural,multi-modal]

オプション B：Sovereign Pattern（推奨）

リポジトリをクローンして、ネイティブ Rust サイドカーのソースコードとベンチマークを利用します。

⚠️ Rust コンパイラーが必要です： Sovereign Pattern では、ソースから sift-core をビルドします。以下のインストールコマンドを実行する前に、Rust コンパイラーをインストールしておく必要があります（rustup.rs）。Rust をインストールしない場合は、代わりにオプション A（PyPI）を使用してください。

git clone https://github.com/luismichio/semantic-sift.git
cd semantic-sift
# Use Python 3.12 for torch/CUDA compatibility
python3.12 -m venv venv312
# Windows:
.\venv312\Scripts\activate
# macOS/Linux:
# source venv312/bin/activate
uv pip install -e .[neural,multi-modal]

Windows のヒント（uv の環境検出）：uv が環境を検出できない場合（エラー："No virtual environment found"）、インタープリターを明示的に指定してください。 uv pip install -e . --python venv312\Scripts\python.exe

注： Context-Pipe の Sovereign Dual-Repo Pattern を使用している場合、semantic-sift は代わりに context-pipe/venv にクロスインストールされます（uv pip install -e ../semantic-sift を使用）。上記の venv312 が必要なのは、スタンドアロンの ML ランタイムを使用する場合、または server.py を直接実行する場合のみです。

🐍 Python 環境について

MCP の設定に適した Python のパスを選択することは、安定性の確保に欠かせません。

セットアップの種類	パスの例	メリット	デメリット
専用 Venv（Windows）	.../semantic-sift/venv312/Scripts/python.exe	依存関係を分離でき、torch のバージョン競合がありません。	ディスク容量がやや多く必要です。
専用 Venv（Mac/Linux）	.../semantic-sift/venv312/bin/python	Unix でも同様に分離できます。	同上。
グローバル Python	C:/Users/User/AppData/Local/.../python.exe	ライブラリを共有でき、セットアップが迅速です。	バージョン競合（例：transformers の不一致）が発生するリスクが高くなります。

推奨： 絞り込みカーネルを分離して安定して動作させるため、mcp_config.json では常に専用 Venvのパスを使用してください。

オーケストレーションに関する注記： Semantic-Sift は「インテリジェンスカーネル」です。複雑なマルチツールのワークフローには、IDE をブロックせずに Semantic-Sift へデータをネイティブにルーティングするユニバーサルなスイッチボード、Context-Pipe のインストールを強くおすすめします。

開発ツール（mypy、pytest）を使用する場合：

uv pip install -e .[dev]

編集可能インストール用の Rust バイナリ：pip install -e . では Rust のコンパイル手順がスキップされるため、sift-core は PATH に追加されません。ソースからコンパイルする代わりに、対応する GitHub リリースからお使いのプラットフォーム向けのビルド済みバイナリを、次のコマンドでダウンロードしてください。

python scripts/fetch_sift_core.py

これにより、sift-core[.exe] が現在の環境の Scripts／bin ディレクトリに直接配置されます。バージョンを更新するたびに、再実行してください。

2. MCP に接続する

重要：Cursor、Gemini、OpenCode、VS Code、Claude の正確な設定パスについては、**設定のマスターマトリックス**を参照してください。

3. 自動オンボーディング

接続したら、AI アシスタントに次のように依頼します。

「sift_onboard() を実行して、このプロジェクトを設定してください。」

---

📊 テレメトリと管理コマンド

Semantic-Sift は見えないところで動作しますが、LLM トークンを消費せずに、そのパフォーマンスとトークン削減効果をいつでも監査できます。

• ターミナル CLI：
  • semantic-sift-stats を実行すると、トークン削減数、レイテンシ、キャッシュヒットの全体ダッシュボードが表示されます。
  • semantic-sift-onboard を実行すると、任意のプロジェクトで Sift を手動で初期化できます（--env と --dry-run をサポート）。
• MCP プロンプト：対応クライアント（Claude Desktop、Cursor、Zed）では、UI に sift_dashboard プロンプトが表示されます（多くの場合、スラッシュコマンドまたはボタンから利用できます）。これにより、テレメトリ統計をすぐにチャットに挿入できます。
• OpenCode と Gemini CLI：sift_onboard() ツールは、IDE の設定にネイティブの /sift-stats と /sift-onboard カスタムスラッシュコマンドを自動的に挿入します。

---

🦀 ネイティブ Rust サイドカー（Meechi とデスクトップアプリ）

Meechi のような、高性能でローカルファーストのアプリケーション向けに、Semantic-Sift はネイティブの Rust バイナリ（sift-core）を提供します。このサイドカーは、Python への依存なしで、移植性と速度を最適化しています。

🔀 ハイブリッドエンジン（semantic-sift-cli）

両方の利点を活かすため、Python パッケージをインストールすると、semantic-sift-cli コマンドも利用できるようになります。これはインテリジェントルーターとして機能します。

• 短いタスク（30,000 文字未満）では、低レイテンシの Rust sift-core（ONNX）を即座に呼び出します。
• 大規模なバッチタスクでは、メモリの急激な消費を防ぐため、Flash Attention を備えた高スループットの PyTorch フレームワークを動的に読み込みます。

機能比較

機能	Python MCP サーバー	Rust Sift-Core（サイドカー）
ヒューリスティックによるログの選別	✅	✅（ネイティブ）
セマンティック圧縮	✅（PyTorch）	✅（ONNX）
マルチモーダル取り込み	✅（[multi-modal] 経由）	❌（テキストのみ）
対応形式	.pdf、.xlsx、.docx、.html、.txt	.txt、.log、.out（テキスト）
起動レイテンシ	3～5 秒	約 10 ミリ秒
バイナリサイズ	約 1.5 GB（モデルを含む）	約 15 MB

注：Meechi のようなネイティブアプリでは、階層型の取り込み戦略を推奨します。アプリのフロントエンド（例：pdf.js）でテキストを抽出してから、Rust サイドカーに渡すことで、高速なセマンティック選別を行います。

✨ ネイティブサイドカーのデモを見る

使用方法：

# Sift a log file instantly
cat app.log | sift-core logs

# Perform neural semantic compression
cat document.txt | sift-core semantic --model ./models/llmlingua2 --rate 0.4

---

🤖 AI エージェント向け：運用プロトコル

このリポジトリを読んでいる AI エージェント（例：Gemini CLI、Cursor、Claude Code）は、次のプロトコルに従ってください。

1. 初期化：sift_onboard() を呼び出して、バックグラウンドフックを登録します。ファイルを書き込まずに予定されているすべての操作を確認するには、sift_onboard(dry_run=True) を使用します。
2. コンテキストに関する注意：大きなファイル（1,000 文字超）を読む前に、sift_analyze_file(path) を呼び出してノイズ比率を判定します。
3. 選別の必須化：ノイズが 15% を超える場合は、データを推論に含める前に sift_logs または sift_chat に渡します。文書には sift_doc(text, rate=0.4) を使用し、rate（0.1～0.9）を調整して、圧縮の深さと忠実度のバランスを取ります。
4. ランキング：sift_rank を使用して、ユーザーのプロンプトに意味的に最も関連性の高いチャンクを特定します。
5. 抽出：PDF やスクレイピングしたコンテンツを要約する際は、sift_extraction(content, show_diff=True) を使用して、削除された内容を正確に確認し、忠実性を検証します。

---

🛡️ セキュリティとテスト

Semantic-Sift は脆弱性ゼロのベースラインに基づいて構築されています。

• Pytest：ヒューリスティックの整合性テストで合格率 100％。
• Bandit (SAST)：Python のパターンを対象とする自動静的解析。
• Pip-Audit (SCA)：既知の脆弱性ゼロを目指したリアルタイムのサプライチェーン監視。

プライバシーとテレメトリの制御：

• SIFT_TELEMETRY_OPTED_IN=true を設定すると、テレメトリが有効になります（オプトイン方式。デフォルトでは無効）。
• SIFT_TELEMETRY_DISABLED=true（従来のキルスイッチ）を設定すると、テレメトリが完全に無効になります。
• SIFT_TELEMETRY_TTL_DAYS=90（デフォルト）を設定すると、古いエントリが削除されるまで .pipe_telemetry.json に保持されるセッション履歴の日数を指定できます。
• SIFT_TELEMETRY_URL=https://your-endpoint を設定すると、メタデータのパルスを独自のエンドポイントに送信できます。
• SIFT_PULSE_RATE_LIMIT_S=10（デフォルト）を設定すると、非同期テレメトリのパルス頻度を指定できます。

セキュリティ制御：

• SIFT_ALLOW_GLOBAL_READS=true を設定すると、ワークスペースのルート外での sift_read_file / sift_analyze_file の実行を許可します（パストラバーサル対策はデフォルトで有効です）。

パフォーマンス制御：

• SIFT_HOOK_TIMEOUT_MS=3000 を設定すると、ヒューリスティックへのフォールバックまでのフックのセマンティック処理時間に上限を設定できます。
• SIFT_MODEL_READY_WAIT_MS=1200 を設定すると、ヒューリスティックモードの出力を返すまでのセマンティックモデルのウォームアップ待機時間を指定できます。
• SIFT_COMPACTION_FIDELITY_THRESHOLD=0.3（デフォルト）を設定すると、低忠実度の圧縮警告が出力される語彙の重複率のしきい値を指定できます。
• SIFT_RANK_TOP_N=3（デフォルト）を設定すると、top_n が明示的に渡されない場合に sift_rank が返す結果のサーバー全体のデフォルト件数を指定できます。

フックのログ制御：

• SIFT_LOG_FILE を設定すると、フックログのパスを上書きできます（デフォルト：.gemini/sift_debug.log）。
• SIFT_LOG_LEVEL（DEBUG、INFO、WARNING、ERROR）を設定すると、フックログの詳細度を指定できます。

セキュリティポリシーの全文は SECURITY.md をご覧ください。

テレメトリのスキーマとエンドポイントの詳細は、doc/TELEMETRY_SPEC.md に記載されています。

---

🔗 エコシステム（Studio of Two）

Semantic-Sift は、Studio of Two インフラストラクチャの主要メンバーです。以下と高い忠実度で調和して動作するよう設計されています。

• Context-Pipe：コンテキストエンジニアリングのための汎用スイッチボードです。Sift がインテリジェンスを提供する一方、Context-Pipe はオーケストレーションを担います。マスキング、検索、マルチモーダルの取り込みツールと Sift ノードを連結するために、Context-Pipe の使用を強くお勧めします。

---

⚖️ ライセンス

Semantic-Sift は Apache License 2.0 の下でライセンスされています。詳細は LICENSE.md をご覧ください。

🤝 貢献

Semantic-Sift はオープンソースですが、コントリビューションは受け付けていません。

「Studio of Two」の厳格なアーキテクチャビジョンを維持し、メンテナンスの負担を完全にゼロに保つため、このリポジトリでは外部からのプルリクエストを受け付けていません。寛容な Apache 2.0 ライセンスの下で、コードの使用、組み込み、フォークを歓迎しますが、新機能やバグ修正の PR は提出しないでください。詳細は CONTRIBUTING.md をご覧ください。