warpvector 0.1.0 → 0.1.1

package/README.md

@@ -1,4 +1,9 @@
-# warpvector
+# warpvector 🌌
+
+[![npm version](https://badge.fury.io/js/warpvector.svg)](https://badge.fury.io/js/warpvector)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Edge Ready](https://img.shields.io/badge/Edge-Ready-success.svg)](#)
+[![Zero Dependency](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)](#)
 
 `warpvector` は、AIモデルの再学習や重い再推論を行うことなく、検索クエリやコンテキスト（意図）に応じてベクトル空間を動的に変形させる、TypeScriptネイティブの軽量ミドルウェア・ユーティリティです。
 
@@ -10,44 +15,80 @@
 
 従来のベクトル検索は静的であり、事前に生成された埋め込みベクトルの距離（類似度）に依存していました。コンテキストに応じた検索の微調整を行いたい場合、これまではメタデータのフィルタリングに頼るか、重い指示チューニング型モデルを再度動かすしかなく、リアルタイム性や柔軟性に欠けていました。
 
-`warpvector` は、次世代のベクトルデータベースのミドルウェアとして機能します。ベースとなるベクトルデータはそのままに、検索の瞬間に数KBの軽量な「意図行列（Matrix）」と「バイアス（Bias）」を適用することで、ベクトル空間全体をインメモリで高速に変形（アフィン変換）させます。これにより、ファイルやデータ間の意味的類似性をユーザーの「真の意図」に極限まで近づけ、次世代の検索体験を提供します。
+`warpvector` は、次世代のベクトルデータベースのミドルウェアとして機能します。ベースとなるベクトルデータはそのままに、検索の瞬間に数KBの軽量な「意図行列（Matrix）」と「バイアス（Bias）」を適用することで、ベクトル空間全体をインメモリで高速に変形させます。これにより、ファイルやデータ間の意味的類似性をユーザーの「真の意図」に極限まで近づけ、次世代の検索体験を提供します。
 
 ---
 
-## 📖 公式ドキュメント
-
-より詳しい使い方や API の詳細については、以下のドキュメントをご参照ください。
+## 🚀 主な特徴
 
-- [🔰 Getting Started (はじめに)](./docs/getting-started.md): インストール方法と基本的な使い方
-- [⚙️ Advanced Usage (高度な使い方)](./docs/advanced-usage.md): 非線形活性化関数、自動ブレンド、WASMバッチ処理、LoRAなどの応用
-- [📚 API Reference](./docs/api-reference.md): クラス・メソッド・ユーティリティ関数の完全なリファレンス
+- **統一された `WarpAdapter` インターフェース [✨ NEW]:** 全てのアダプターが同一の `tune()` メソッドを備えたインターフェースを実装。設計の共通化により、Prisma拡張やLangChain拡張にどのアダプターでもシームレスに組み込めます。
+- **次世代DBミドルウェア:** 既存のベクトルDB（Pinecone, Qdrant, DuckDBなど）とフロントエンドの間に立ち、動的なコンテキストルーティングを提供。
+- **動的アフィン変換 & 非線形MLP [NEW]:** 単純な行列変換（$W \cdot x + b$）に加え、WASMを用いた超高速な多層パーセプトロン(MLP)と非線形活性化関数(ReLU, Sigmoid, Tanh)による高度な空間変形をサポート。
+- **オンライン等方化 (Whitening) [NEW]:** Oja's Rule を用いたオンラインPCAにより、OpenAI `ada-002` などが抱える「検索空間の極端な偏り（異方性）」をエッジ側でストリーミング補正し、検索精度を劇的に向上。
+- **ColBERT / Late Interaction (WASM) [✨ NEW]:** 単一ベクトルの代わりに「トークン行列」を用いて検索する最高峰の手法 (ColBERT) を WASM 化。TS環境では絶望的に遅い MaxSim 演算を爆速で処理し、RAGの検索品質を極限まで引き上げます。
+- **Vector Quantization (量子化) [✨ NEW]:** `Float32` のベクトルを `Int8` (スカラー量子化: メモリ1/4) または `Binary` (二値化: メモリ1/32) に圧縮。大規模ベクトルデータの保持コストを激減させ、ハミング距離計算で超高速検索を実現します。
+- **Hybrid Search (RRF & RSF) [✨ NEW]:** ベクトル検索（Dense）とキーワード検索（Sparse/BM25）の結果を統合するハイブリッド検索ユーティリティ（Reciprocal Rank Fusionなど）を内蔵。
+- **WASM/SIMDによる超高速処理:** 行列変換、PCA更新、ColBERT処理にはAssemblyScriptでコンパイルされたインラインWebAssembly（WASM）バックエンドを呼び出し、計算速度を最大化します。
+- **InfoNCE & Triplet 学習エンジン (Adam Optimizer内蔵) [NEW]:** Pythonサーバー不要。ユーザーのフィードバックから Contrastive Learning (複数Negative対応の対照学習) をエッジワーカー上で直接オンライン学習。
+- **LoRA (低ランク適応) アーキテクチャ:** `LoraIntentAdapter` により、超高次元ベクトル（1536次元など）でもメモリ使用量・計算量を劇的に削減。
+- **Prisma + pgvector ネイティブ統合拡張 [NEW]:** Prisma Client Extensionとして透過的に統合。複雑なSQLを書かずに WarpVector で推論・補正されたベクトルでのデータベース検索がメソッド1つで完結。
+- **TypeScriptネイティブ & ゼロ依存:** 外部の機械学習ライブラリは一切不要。Cloudflare Workers、Bun、Node.jsなどのモダンなサーバーレス/エッジ環境に完全対応。
 
 ---
 
-## 🚀 主な特徴
+## 基本的な使い方 (WarpPipeline)
 
-- **次世代DBミドルウェア:** 既存のベクトルDB（Pinecone, Qdrant, DuckDBなど）とフロントエンドの間に立ち、動的なコンテキストルーティングを提供。
-- **動的アフィン変換 ($W \cdot x + b$):** 回転・拡大・縮小（行列 $W$）と平行移動（バイアス $b$）を組み合わせ、コンテキストに最適化されたベクトル空間を動的に生成。
-- **WASM/SIMDによる超高速バッチ処理:** 大量のベクトル処理にはAssemblyScriptでコンパイルされたインラインWebAssembly（WASM）バックエンドを自動的にフォールバックなしで呼び出し、計算速度を最大化します。外部依存（Zero-dependency）の哲学を維持しています。
-- **意図の動的合成（Blending）と自動ルーティング:** `tuneBlended` による手動合成に加え、自己アテンション型の `tuneAutoBlended` を搭載。クエリベクトル自体から適切な意図をSoftmax関数を用いて自動で推論・合成します。
-- **非線形空間のサポート:** 空間をさらに複雑に歪める非線形活性化関数 (`relu`, `sigmoid`, `tanh`) をネイティブサポート。
-- **LoRA (低ランク適応) アーキテクチャ:** `LoraIntentAdapter` により、超高次元ベクトル（1536次元など）でもメモリ使用量・計算量を劇的に削減。数百万件のベクトルデータに対しても瞬時にワープ可能。
-- **最先端の幾何学アプローチ:** 空間の幾何学構造（コサイン類似度）を破壊せずにベクトルを補間する球面線形補間（`slerp`）を標準搭載。
-- **TypeScriptネイティブ & ゼロ依存（Zero-dependency）:** Python環境や重厚な機械学習ライブラリは一切不要。`Float32Array` をベースにした極限まで無駄を削ぎ落とした行列演算ロジック。
-- **エッジ・ローカルファースト対応:** 超軽量かつ高速に動作するため、Cloudflare Workers、Bun、Node.jsなどのモダンなサーバーレス/エッジ環境に即座に組み込み可能。
+新しく導入された `WarpPipeline` を使うと、複雑なベクトル変換（非線形推論、インテント変換、量子化）からDBフォーマットへの出力までを数行で直感的に記述できます。
+
+```typescript
+import { WarpPipeline } from 'warpvector';
 
-## 🎯 なぜ「新しいベクトルDB」ではなく「ミドルウェア」なのか？
+// 1. パイプラインの構築
+const pipeline = new WarpPipeline(1536)
+  .addMlp(layers)                             // 非線形変換 (WASM使用)
+  .addIntent({ "domain_x": intentWeights })   // ユーザーごとに空間を歪める
+  .quantize("int8");                          // 最後に Int8 に量子化して圧縮
 
-ベクトル検索の体験を根本から変えるにあたり、`warpvector` はあえて「データベース（ストレージやインデックス機能）そのもの」を作ることを避けました。これにはオープンソースとしての強力な戦略と明確な理由があります。
+// 2. 非同期初期化 (WASMモジュールのセットアップなどを一括実行)
+await pipeline.init();
 
-1. **既存の強固なDBエコシステムへの「タダ乗り」（ベンダーロックインの排除）**
-   Pinecone、Qdrant、Supabase (pgvector)、DuckDB など、すでに世界中で使われている非常に優秀なベクトルDBが存在します。`warpvector` が自前のDBを持たないことで、**「ユーザーは今使っているお気に入りのDBをそのまま使いながら、検索クエリの際に warpvector を挟むだけで次世代の動的ルーティング体験へとアップグレードできる」**という、導入ハードルの極めて低い立ち位置を実現しています。
+// 3. 超高速バッチ処理 (WASM/SIMD対応)
+const batchVectors = [[0.1, ...], [0.5, ...]]; // 大量データ
+const results = pipeline.runBatch(batchVectors, { intent: "domain_x" });
 
-2. **UNIX哲学に基づく極限の集中（超軽量・高速化）**
-   データの永続化や近似最近傍探索（HNSW等）の重厚な処理を既存のDBに丸投げすることで、本プロジェクトは**「ユーザーの意図に応じたインメモリでの超高速なベクトルワープ」という一点に極限まで集中**できました。その結果、Pythonや重い機械学習ライブラリに依存しない、純粋な `Float32Array` および WASM ロジックのみで完結しています。
+// 4. Vector DB 用フォーマットへの直接出力
+const pineconeQuery = pipeline.runAndFormat(
+  rawVector, 
+  { format: "pinecone", topK: 10, filter: { genre: "action" } }
+);
+
+// 5. パイプライン丸ごとの永続化と復元
+const stateJson = pipeline.exportState(); 
+const restoredPipeline = WarpPipeline.importState(stateJson);
+```
 
-3. **究極のポータビリティ（エッジ＆ローカルファースト）**
-   ストレージ管理の責務を持たないため、`warpvector` は非常に身軽です。Cloudflare Workers などのエッジ環境や、ユーザーのスマホのブラウザ上、サーバーレス環境など、どこにでも瞬時にデプロイ可能です。これにより、「重いベクトル検索自体はクラウドのDBで行い、コンテキスト空間のワープはユーザーの手元のエッジで行う」といった次世代のアーキテクチャが可能になります。
+## 各機能のドキュメント (Documentation)
+
+各機能のより詳細な仕組み、コードスニペット、ユースケースについては以下の個別ドキュメントをご参照ください。
+
+1. **[コアアダプタ (Core Adapters)](./docs/1-core-adapters.md)**
+   - `IntentAdapter`, `ProjectionAdapter`, `LoraIntentAdapter` の基本
+2. **[ニューラルネットワーク (Neural Networks)](./docs/2-neural-networks.md)**
+   - `MlpAdapter` を用いた多層パーセプトロンと非線形活性化関数
+3. **[オンライン等方化・PCA (Whitening)](./docs/3-whitening-pca.md)**
+   - 空間的偏り (異方性) のストリーミング学習による除去
+4. **[量子化と圧縮 (Quantization)](./docs/4-quantization.md)**
+   - `Int8` (1/4圧縮) および `Binary` (1/32圧縮) による高速化と省メモリ化
+5. **[Late Interaction / ColBERT](./docs/5-colbert.md)**
+   - WASM を用いた MaxSim 演算による緻密なトークン照合
+6. **[ハイブリッド検索フュージョン (Hybrid Search)](./docs/6-hybrid-search.md)**
+   - ベクトル検索とキーワード検索の統合 (`RRF`, `RSF`)
+7. **[オンライン学習エンジン (Trainers)](./docs/7-trainers.md)**
+   - 対照学習によるリアルタイムな空間最適化 (`InfoNCETrainer`, `TripletTrainer`)
+8. **[エコシステム統合 (Integrations)](./docs/8-integrations.md)**
+   - `LangChain`, `LlamaIndex`, `Prisma + pgvector` とのシームレスな連携
+9. **[状態の永続化・シリアライズ (Serialization)](./docs/9-serialization.md)**
+   - 学習結果の JSON / バイナリ形式での保存と復元
 
 ---
 
@@ -57,124 +98,248 @@
 npm install warpvector
 # または
 bun add warpvector
-
 ```
 
-🛠 クイックスタートTypeScript
-```ts
-import { IntentAdapter, LoraIntentAdapter, normalize, slerp } from 'warpvector';
+---
+
+## 🛠 クイックスタート
+
+### 1. 基本的なアフィン変換 (IntentAdapter)
 
-// 1. 意図（インテント）ごとの変換行列とバイアス、代表ベクトル(ルーティング用)を定義
-const myIntents: Record<string, IntentWeights> = {
+```typescript
+import { IntentAdapter } from 'warpvector';
+
+// 意図ごとの変換行列とバイアスを定義
+const myIntents = {
   riskAnalysis: {
     matrix: [
       [1.2, 0.1, -0.4],
       [-0.1, 1.5, 0.2],
       [0.3, -0.2, 1.1],
     ],
-    bias: [0.05, -0.1, 0.2],
-    routingVector: [1.0, 0.0, 0.0] // 自動ブレンド計算用の代表方向
-  },
-  economicImpact: {
-    matrix: [
-      [0.5, 0.8, 0.1],
-      [0.2, 0.6, -0.3],
-      [-0.1, 0.1, 1.4],
-    ],
-    bias: [-0.2, 0.4, 0.0],
-    routingVector: [0.0, 1.0, 0.0]
-  },
+    bias: [0.05, -0.1, 0.2]
+  }
 };
 
-// 2. アダプターの初期化
-// ※初期化時にWASMエンジンが自動的にマウントされます
 const adapter = new IntentAdapter(myIntents);
-
-// 3. AIモデルから生成された標準のベースベクトル
 const baseVector = [0.15, -0.23, 0.88];
 
-// 4. ユーザーの意図に合わせて、インメモリで高速にベクトルを調律（ワープ）
-// 必要に応じて非線形活性化関数('relu', 'sigmoid', 'tanh')を指定可能
-const tunedVectorForRisk = adapter.tune(baseVector, "riskAnalysis", "relu");
+// "riskAnalysis" の意図に合わせてベクトルをワープ
+const warpedVector = adapter.tune(baseVector, "riskAnalysis");
+```
+
+### 2. 多層ニューラルネットワークの高速推論 (MlpAdapter) [✨ NEW]
+
+WASMバックエンドにより、ブラウザやエッジ環境で重厚なフレームワークなしに多層MLPの推論が可能です。
+
+```typescript
+import { MlpAdapter } from 'warpvector';
+
+// 1536次元から128次元の中間層を経て2次元に出力する2層MLP
+const mlp = new MlpAdapter([
+  { inputDim: 1536, outputDim: 128, activation: "relu" },
+  { inputDim: 128, outputDim: 2, activation: "linear" }
+]);
+
+mlp.setLayerWeights(0, matrix1, bias1);
+mlp.setLayerWeights(1, matrix2, bias2);
+
+// 超高速非線形推論 (WASM)
+const output = mlp.tune(baseVector);
+```
+
+### 3. 検索空間の等方化 (Online Whitening) [✨ NEW]
+
+事前学習済みモデル（ada-002等）特有の「全ての類似度が高く出てしまう空間の偏り」をオンラインで自動補正します。
+
+```typescript
+import { WhiteningAdapter } from 'warpvector';
+
+// トップ1つの主成分（偏り）をストリーミング学習して除去するアダプター
+const adapter = new WhiteningAdapter(1536, { learningRate: 0.01, numComponents: 1 });
+
+// ベクトルを受信するたびに自動で偏りの方向を学習 (Oja's Rule)
+adapter.update(rawVector1);
+adapter.update(rawVector2);
+
+// 検索時に偏りを除去（検索の解像度が劇的に向上）
+const whitenedVector = adapter.tune(searchVector);
+```
+
+### 4. Prisma + pgvector ネイティブ統合 [✨ NEW]
+
+WarpVector を Prisma Client Extension としてアタッチすることで、ベクトル推論とデータベース検索を統合します。
 
-console.log(tunedVectorForRisk);
-// 出力: Float32Array [ 0.211, 0, 1.259 ] (アフィン変換 + ReLU適用後のベクトル)
+```typescript
+import { PrismaClient } from '@prisma/client';
+import { withWarpVector } from 'warpvector/integrations/prisma';
+import { WhiteningAdapter } from 'warpvector';
 
-// 5. 自己アテンション型動的ブレンド (Auto-blending)
-// クエリベクトルの中身を分析し、最適なインテント比率を自動で推論・合成して適用します
-const autoBlendedVector = adapter.tuneAutoBlended(baseVector);
+const adapter = new WhiteningAdapter(1536);
 
-// 6. WASM/SIMDによる複数ベクトルの超高速バッチ変換
-const batchVectors = [
-  [0.15, -0.23, 0.88],
-  [0.44, 0.11, -0.05]
+// Prisma Client に WarpVector 拡張をアタッチ
+const prisma = new PrismaClient().$extends(
+  withWarpVector({
+    adapter: adapter,
+    vectorField: "embedding", // DB上の pgvector 保存先カラム名
+    distanceOperator: "<=>"   // コサイン距離を使用
+  })
+);
+
+// 生のベクトルを渡すだけ！（内部でWarpVector推論とpgvector用SQL生成が自動で行われる）
+const results = await prisma.document.searchByVector({
+  vector: rawSearchVector,
+  topK: 10,
+  where: "category = 'science'" // 通常のSQL WHERE条件も併用可能
+});
+```
+
+### 5. 高品質 RAG のための Late Interaction (ColBERT) [✨ NEW]
+
+単一ベクトルでは潰れてしまう細かいニュアンスを、トークンごとの行列で保持し、WASMの超高速 MaxSim 演算によって緻密に照合します。
+
+```typescript
+import { ColbertAdapter } from 'warpvector';
+
+const adapter = new ColbertAdapter();
+
+// queryTokens: クエリのトークン行列 (平坦化された Float32Array)
+// documentTokensArray: 各ドキュメントのトークン行列の配列
+const results = adapter.rank(queryTokens, [doc1Tokens, doc2Tokens, doc3Tokens], 1536);
+
+console.log(results); // [{ index: 1, score: 1.44 }, { index: 0, score: 0.76 }, ...]
+```
+
+### 6. Hybrid Search / 検索結果の統合 (RRF & RSF) [✨ NEW]
+
+ベクトル検索結果（Dense）とキーワード検索結果（Sparse/BM25）をシームレスに統合（フュージョン）するための独立したアルゴリズムを提供します。WarpVector のコアなベクトル変形機能と組み合わせることで、最高峰の検索精度を達成できます。
+
+```typescript
+import { rrf, rsf } from 'warpvector';
+
+const denseResults = [
+  { id: "doc1", score: 0.95 }, 
+  { id: "doc2", score: 0.88 }
 ];
-// 行列の数が多い場合、内部で自動的にWASMメモリへ転送され高速に処理されます
-const tunedBatch = adapter.tuneBatch(batchVectors, "riskAnalysis");
-const normalizedVector = normalize(tunedBatch[0]); // コサイン類似度計算用などにL2正規化
 
-// 7. LoRA (低ランク適応) による超高次元ベクトルの高速変換
-const loraAdapter = new LoraIntentAdapter(1536, 16); // 次元=1536, ランク=16
-// ... LoraIntentWeights { matrixA, matrixB, bias } を addIntent する
-const warpedVector = loraAdapter.tune(baseVector, "newContext");
+const sparseResults = [
+  { id: "doc2", score: 15.2 }, 
+  { id: "doc1", score: 12.1 }
+];
+
+// RRF (Reciprocal Rank Fusion): スコアの絶対値に依存せず、順位(Rank)のみを使って公平に統合
+const rrfResults = rrf([denseResults, sparseResults]);
 
-// 8. 球面線形補間 (Slerp) で空間構造（コサイン類似度）を維持したベクトル補間
-const interpolated = slerp(baseVector, normalizedVector, 0.5);
+// RSF (Relative Score Fusion): Min-Max正規化を行い、重み(Dense 70%, Sparse 30%)をつけて加算統合
+const rsfResults = rsf([denseResults, sparseResults], [0.7, 0.3]);
 ```
 
-## 📐 数学的背景：動的アフィン変換と非線形性
+### 7. ベクトル量子化 (Vector Quantization) [✨ NEW]
 
-`warpvector` の核心は、高次元ベクトル空間において**「データの意味的構造を破壊せずに、コンテキスト（意図）に応じて空間を幾何学的に変形させる」**ことにあります。
+メモリ制約の厳しいエッジ環境向けに、`Float32` (32ビット) のベクトルを `Int8` (8ビットスカラー) または `Binary` (1ビット) に圧縮するアダプターを提供します。
 
-このセクションでは、なぜ単純な行列乗算ではなく、バイアスを加えた「アフィン変換」が必要なのか、そしてそれがベクトル検索（コサイン類似度など）にどのような数学的影響を与えるのかを詳細に解説します。
+```typescript
+import { QuantizationAdapter } from 'warpvector';
 
----
+// Int8 量子化 (メモリを 1/4 に削減)
+const int8Adapter = new QuantizationAdapter({ type: "int8", dim: 1536 });
+const int8Vec = int8Adapter.tune(floatVector); // Int8Array
+const dot = QuantizationAdapter.int8DotProduct(int8Vec, int8Vec2);
 
-### 1. 基本数式モデル
+// Binary 量子化 (メモリを 1/32 に削減)
+const binaryAdapter = new QuantizationAdapter({ type: "binary", dim: 1536 });
+const binVec = binaryAdapter.tune(floatVector); // Uint8Array(192バイト)
+const dist = QuantizationAdapter.hammingDistance(binVec, binVec2); // 超高速なXORハミング距離計算
+```
 
-入力となる標準的なベースベクトル（例：埋め込みモデルから出力された直後の固定ベクトル）を $\mathbf{x} \in \mathbb{R}^d$ とします。
+### 8. 動的学習エンジン (Trainers with Adam) [✨ UPGRADED]
 
-ユーザーが指定した意図 $I$ に対し、`warpvector` は以下の**アフィン写像（Affine Map）**を適用し、調律された新しいベクトル $\mathbf{x}' \in \mathbb{R}^d$ を生成します。
+Pythonサーバーを立てることなく、ユーザーのフィードバックをもとにエッジ上でベクトル空間を最適化できます。Adamオプティマイザーと InfoNCE Loss (複数Negative) に対応しました。
 
-$$\mathbf{x}' = \sigma(\mathbf{W}_I \mathbf{x} + \mathbf{b}_I)$$
+```typescript
+import { InfoNCETrainer } from 'warpvector';
 
-ここで、それぞれのパラメータは以下の役割を持っています。
+const trainer = new InfoNCETrainer(1536, { learningRate: 0.001 });
 
-- $\mathbf{W}_I \in \mathbb{R}^{d \times d}$ ：**意図変換行列（Intent Matrix）**
-- $\mathbf{b}_I \in \mathbb{R}^d$ ：**意図バイアスベクトル（Intent Bias）**
-- $\sigma$ ：**非線形活性化関数（Activation Function, オプション）**
+// 1つの正解と複数の不正解（In-batch Negatives）を同時に学習
+const loss = trainer.updateOnline(
+  anchorVector, 
+  positiveVector, 
+  [negativeVector1, negativeVector2], 
+  currentWeights
+);
+```
 
----
+### 9. LangChain / LlamaIndex との統合 (Integrations)
 
-### 2. 幾何学的な意味とシステムへの作用
+`warpvector` は、既存の巨大エコシステムに「たった数行」で組み込むことができます。
 
-高次元空間におけるアフィン変換は、線形変換（行列乗算）と平行移動（バイアス加算）の組み合わせです。これが検索システムにおいて強力な表現力を持つ理由は、空間を「回転・拡大縮小」させた後に「シフト」できる点にあります。
+#### LangChain 統合 (`WarpEmbeddings`)
+```typescript
+import { OpenAIEmbeddings } from "@langchain/openai";
+import { IntentAdapter } from "warpvector";
+import { WarpEmbeddings } from "warpvector/integrations/langchain";
 
-#### ① 変換行列 $\mathbf{W}_I$ による「空間の歪み（Warping）」
+const baseEmbeddings = new OpenAIEmbeddings();
+const adapter = new IntentAdapter(myIntents);
 
-行列 $\mathbf{W}_I$ をベクトルに乗算することは、特定の次元（特徴量）の軸を縮めたり、別の軸を伸ばしたり、あるいは空間全体を回転させることを意味します。
+const warpEmbeddings = new WarpEmbeddings({
+  baseEmbeddings, adapter, intentName: "riskAnalysis"
+});
+// 検索時のみ動的ワープが適用されます
+const vectorStore = new MemoryVectorStore(warpEmbeddings);
+```
+
+#### LlamaIndex 統合 (`WarpLlamaIndexEmbeddings`) [✨ NEW]
+```typescript
+import { OpenAIEmbedding } from "llamaindex";
+import { WarpLlamaIndexEmbeddings } from "warpvector/integrations/llama-index";
+
+const warpLlamaIndexEmbeddings = new WarpLlamaIndexEmbeddings({
+  baseEmbeddings: new OpenAIEmbedding(),
+  adapter: intentAdapter,
+  intentName: "riskAnalysis"
+});
+// LlamaIndex の VectorStoreIndex などに直接渡せます
+```
 
-- **特徴量の重み付け:** ユーザーが「リスク分析」という意図を選択した場合、行列 $\mathbf{W}_I$ は「異常」「遅延」「脆弱性」といった概念に対応する次元のスケールを拡大（強調）し、それ以外のノイズとなる次元を縮小させます。
-- **相関の結合:** 本来は独立していた2つの特徴軸（例：「気象の数値」と「テキストのネガティブ度」）を、行列の回転作用によって同じ方向へ傾け、データ間の潜在的な相関関係を強制的に浮かび上がらせます。
+### 10. 全アダプタの状態永続化 (Universal Serialization) [✨ NEW]
 
-#### ② バイアスベクトル $\mathbf{b}_I$ による「前提知識の付与（Shifting）」
+Cloudflare Workers 等の揮発性環境でも、オンライン学習やPCAで得られたコンポーネントを即座にJSONで保存・復元できます。
 
-行列乗算だけ（ $\mathbf{W}_I \mathbf{x}$ ）の場合、原点（ゼロベクトル $\mathbf{0}$ ）はどのように変換しても原点のまま（ $\mathbf{W}_I \mathbf{0} = \mathbf{0}$ ）となり、空間のトポロジーに強い制約が残ります。バイアス $\mathbf{b}_I$ は、空間全体を特定の方向へ一律に平行移動させます。
+```typescript
+import { WhiteningAdapter } from 'warpvector';
 
-- **コンテキストの強制結合:** 「宇宙デブリ」という共通のバイアス $\mathbf{b}_I$ を加えることで、全く異なる初期ベクトルを持つデータ群（軌道数値データと、地上のニューステキスト）のベースラインを同じ領域へと強制的にシフトさせます。これにより、次の類似度計算において、両者が「宇宙デブリ」という共通の文脈の上で比較されるようになります。
+const adapter = new WhiteningAdapter(1536);
+// ... オンライン学習 (update) を実行 ...
 
-#### ③ 活性化関数 $\sigma$ による「非線形ドメインマッピング」
+// 状態をシリアライズしてRedis等に保存
+const stateJson = adapter.exportState();
 
-新しい機能として導入された非線形関数 (`relu`, `sigmoid`, `tanh`) を通すことで、負の次元をゼロに切り捨てたり、空間を [0, 1] や [-1, 1] の立方体空間へと曲げ込むことが可能になります。これにより、単純なアフィン変換を超えた複雑な概念の切り分けが可能になります。
+// 次回起動時や別インスタンスで即座に復元
+const restoredAdapter = WhiteningAdapter.importState(stateJson);
+```
 
 ---
 
-### 3. 軽量性とスケーラビリティのトレードオフ
+## 📐 数学的背景：動的アフィン変換と非線形性
+
+入力となる標準的なベースベクトル $\mathbf{x} \in \mathbb{R}^d$ に対し、`warpvector` は以下の**アフィン写像（Affine Map）**を適用し、調律された新しいベクトル $\mathbf{x}' \in \mathbb{R}^d$ を生成します。
+
+$$\mathbf{x}' = \sigma(\mathbf{W}_I \mathbf{x} + \mathbf{b}_I)$$
+
+- $\mathbf{W}_I \in \mathbb{R}^{d \times d}$ ：**意図変換行列（Intent Matrix）**。空間の回転や特徴量の強調（歪み）を担当します。
+- $\mathbf{b}_I \in \mathbb{R}^d$ ：**意図バイアスベクトル（Intent Bias）**。空間全体を特定のコンテキストへ平行移動（シフト）させます。
+- $\sigma$ ：**非線形活性化関数（Activation Function）**。空間を曲げ込み、複雑な意味の切り分けを可能にします (`relu`, `sigmoid`, `tanh`)。
+
+この計算複雑度はわずか $\mathcal{O}(d^2)$ （LoRAの場合は $\mathcal{O}(d \cdot r)$）であり、WASM（WebAssembly）と `Float32Array` によるメモリアライメント最適化を活用することで、**ブラウザ上やエッジ環境でも数千〜数万件の推論を数ミリ秒で完了**させることができます。
+
+---
 
-本アーキテクチャの最大の数学的メリットは、**「計算のオフロード」**が可能な点にあります。
+## 🤝 貢献 (Contributing)
 
-もし、検索クエリ $\mathbf{q}$ に対して毎回巨大なLLMを動かして意図を埋め込もうとすると、数億回のパラメータ推論（レイヤごとの非線形変換）が必要になります。
+本プロジェクトはオープンソースです。新機能の追加、VectorDB用の最適化アダプターの提供、パフォーマンス改善のプルリクエストを歓迎します！
 
-しかし、`warpvector` のアフィン変換は実行時の計算複雑度がわずか $\mathcal{O}(d^2)$ です。さらに、WASM（WebAssembly）とFloat32Arrayによるメモリアライメント最適化を活用することで、**ブラウザ上やエッジワーカー上でも10,000件規模のバッチベクトルを数ミリ秒で変換できます。**
+## 📄 ライセンス
 
-300TBのような巨大なローカルデータレイクを運用する際、データ側（ $\mathbf{x}$ ）を毎回変換して書き換えるのではなく、**「ユーザーのクエリ $\mathbf{q}$ 側だけを $\mathbf{q}' = \mathbf{W}_I \mathbf{q} + \mathbf{b}_I$ と変換して、DB（DuckDBなど）の検索に投げる」**という運用が数学的に等価になります。これにより、ディスクリートなインフラコストを最小限に抑えたまま、リアルタイムな意図適応検索が達成されます。
+MIT License