diff --git a/docs/specification/01_system_overview.md b/docs/specification/01_system_overview.md index 15d3cc6..cb9dd43 100644 --- a/docs/specification/01_system_overview.md +++ b/docs/specification/01_system_overview.md @@ -4,11 +4,11 @@ **TelosDB** は、プライバシーを重視したローカル専用の「意味検索（Vector Search）基盤」を提供するために開発されました。 -現代の AI 活用において、外部クラウド（OpenAI 等）へのデータ送信はセキュリティ上の大きな懸念事項です。本システムは、LLM（Embedding モデル）とベクトルエンジンをすべてユーザーのローカル環境（Windows Desktop）で動作させることにより、以下の価値を提供します。 +現代の AI 活用において、外部クラウド（OpenAI 等）へのデータ送信はセキュリティ上の大きな懸念事項です。本システムは、数学的な文書解析（Latent Semantic Analysis）とベクトルエンジンをすべてユーザーのローカル環境（Windows Desktop）で動作させることにより、以下の価値を提供します。 - **絶対的なプライバシー**: 文章データやベクトルデータがネットワークを介して外部に送信されることはありません。 -- **オフライン動作**: サーバーメンテナンスやインターネット接続環境に左右されず、常に高速な検索が可能です。 -- **コストゼロ**: 推論はローカル GPU/CPU で行われるため、月額費用や API トークン費用が発生しません。 +- **オフライン動作**: 重い推論モデルやインターネット接続環境に左右されず、常に高速な検索が可能です。 +- **省リソース・ゼロコスト**: 推論はローカル CPU のみで行われるため、ハイスペックな GPU や API トークン費用は一切不要です。 ## 2. 主要機能詳説 @@ -18,7 +18,7 @@ | **MCP (Model Context Protocol)** | AI エージェント（Cursor, Claude Desktop, IDE 等）が本ツールを「外部知識」として呼び出すための標準規格。 | SSE Transport (Port 3001) | | **低レイテンシ・省リソース** | モデル推論の代わりに LSA を採用。超軽量かつ高速なインデックス更新・検索を実現。 | `ndarray` + `SVD` | | **セルフヒーリング (Self-healing)** | DB 内のテキストとベクトルの不一致を検出し、バックグラウンドで自動同期。 | `db::sync_vectors` | -| **常駐・軽量 UI** | システムトレイに常駐し、SSE を使った非同期通信でバックグラウンドログをリアルタイム表示。 | Tauri 2 + HTML/JS/Axum | +| **常駐・軽量 UI** | システムトレイに常駐し、SSE を使った非同期通信でバックグラウンドログをリアルタイム表示。 | Tauri 2 + Vanilla JS + Axum | ## 3. システム特性 (Technical Highlights) diff --git a/docs/specification/02_architecture_design.md b/docs/specification/02_architecture_design.md index 9944ea3..a1ec5a0 100644 --- a/docs/specification/02_architecture_design.md +++ b/docs/specification/02_architecture_design.md @@ -2,7 +2,7 @@ ## 1. 全体構造図 -本システムは、OS のシステムトレイに常駐する「ホストプロセス（Tauri 2）」と、推論を担う「サイドカープロセス（llama-server）」、および外部エージェントとの通信を担う「MCP サーバ（Axum）」の 3 つが有機的に連携する構造です。 +本システムは、OS のシステムトレイに常駐する「ホストプロセス（Tauri 2）」の中で、GUI、外部エージェントとの通信（MCP）、および数学的な文書解析（LSA）をすべて完結させる、シングルプロセス・マルチスレッド構造です。 ```mermaid graph TD @@ -38,18 +38,18 @@ 本システムの最大の特徴は、デスクトップアプリとしての GUI 管理を Tauri が行い、外部通信インターフェース（MCP）を Axum が担当する「デュアルサーバ」構成にあります。 両者はメモリを共有していますが、非同期なデータ操作通知（例：エージェントが MCP 経由でデータを登録した際に UI の件数を増やす）には **Tokio Broadcast Channel** を使用し、疎結合な連携を実現しています。 -### 2.2 推論サイドカー (llama-server) の制御 +### 2.2 ベクトル解析 (LSA Engine) -Embedding 計算を行う `llama-server` は、Tauri のサイドカー機能によって起動・管理されます。 +Embedding 計算は外部の `llama-server` に依存せず、Rust バックエンド内で `ndarray` を用いた特異値分解（SVD）により直接行われます。 -- **起動時**: `lib.rs` の `setup` フックでサイドカーをスポーン。 -- **通信**: Rust バックエンドが `reqwest` を用いてローカルポート 8080 へ HTTP 要求を送信。 -- **終了時**: Tauri のプロセスマネージャにより、アプリ終了と同時にサイドカーも安全にクリーンアップされます。 +- **処理フロー**: テキスト入力に対し、分かち書き（Vibrato） -> 単語出現頻度計算 -> SVD 射影 の工程を経てベクトルを生成。 +- **メリット**: 低スペック PC でも動作可能、GPU 不要、モデルファイル管理不要。 +- **一貫性**: アプリケーション本体のライフサイクルと完全に一致し、サイドカーの起動待ちやゾンビプロセスのリスクがありません。 ## 3. 各レイヤーの役割分担 | レイヤー | 主要コンポーネント | 役割と責務 | | :--- | :--- | :--- | -| **Presentation** | フロントエンド (index.html) | 設定状況の表示、アクティビティログ（SSE）の可視化、システム操作。 | -| **Application** | Rust コア (`lib.rs`, `mcp.rs`) | ビジネスロジック。MCP 要求のパース、サイドカーとの通信、DB 操作のオーケストレーション。 | -| **Infrastructure** | SQLite, llama-server | データの永続化、ベクトル空間の管理、LLM 推論エンジンの実行。 | +| **Presentation** | フロントエンド (`src/frontend`) | 設定状況の表示、アクティビティログ（SSE）の可視化、システム操作。 | +| **Application** | Rust コア (`src/backend`) | ビジネスロジック。MCP 要求のパース、LSA 解析、DB 操作のオーケストレーション。 | +| **Infrastructure** | SQLite (`telos.db`) | データの永続化、ベクトル空間の管理。 | diff --git a/docs/specification/03_database_specification.md b/docs/specification/03_database_specification.md index 233d4ff..6bafa17 100644 --- a/docs/specification/03_database_specification.md +++ b/docs/specification/03_database_specification.md @@ -16,6 +16,7 @@ ```mermaid erDiagram items ||--|| vec_items : "Reference by ID (1:1)" + items ||--|| items_lsa : "Metadata by ID (1:1)" items { integer id PK "文書ID (自動採番)" @@ -26,7 +27,12 @@ vec_items { integer id PK "items.id と紐付け" - blob embedding "640次元ベクトルデータ(f32)" + blob embedding "50次元ベクトルデータ(f32)" + } + + items_lsa { + integer item_id PK "items.id と紐付け" + text feature_json "特徴量メタデータ" } ``` @@ -36,7 +42,7 @@ 検索クエリが入力されると、システムは以下の手順を踏みます。 -1. クエリを `llama-server` に送り、ベクトル化する。 +1. クエリを内部の **LSA Engine** に送り、現在のボキャブラリに基づいて 50 次元のベクトルに射影する。 2. SQLite 上で `vec_items` テーブルをスキャンし、クエリベクトルに近い順（L2距離順）に `items.id` を取得。 3. `items` テーブルから実際のテキストを取得して結合。 @@ -46,7 +52,7 @@ 本システムは `db::sync_vectors` ロジックを備えており： - 起動時または特定のトリガーで `items` を全走査。 -- ベクトルが欠落している行を自動検出し、サイドカー経由で再生成・補完。 +- ベクトルが欠落している行を自動検出し、LSA エンジンで再生成・補完。 これにより、常に検索結果の網羅性を保証します。 ## 4. テーブル詳細 @@ -57,4 +63,8 @@ ### 4.2 `vec_items` (ベクトル演算用仮想テーブル) -`sqlite-vec` によって定義された仮想テーブルです。`dimensions=640` として設定されており、Gemma-3 の出力層と完全一致させています。 +`sqlite-vec` によって定義された仮想テーブルです。`dimensions=50` として設定されており、LSA エンジンの射影次元数と一致させています。 + +### 4.3 `items_lsa` (LSAメタデータ) + +LSA の計算に使用された中間データや、特定の単語重みなどのメタ情報を保持します。将来的なインデックス再構築の高速化に使用されます。 diff --git a/docs/specification/04_mcp_api_specification.md b/docs/specification/04_mcp_api_specification.md index b3badc5..d1d9f2d 100644 --- a/docs/specification/04_mcp_api_specification.md +++ b/docs/specification/04_mcp_api_specification.md @@ -24,8 +24,8 @@ | ツール名 | 役割 | 解説 | | :--- | :--- | :--- | -| `add_item_text` | 文書の永続化 | テキストを Embedding 化して DB へ保存。 | -| `search_text` | 意味検索 | 記述内容の類似度に基づいたベクトル検索。 | +| `add_item_text` | 文書の永続化 | テキストを LSA 解析によってベクトル化し DB へ保存。 | +| `search_text` | 意味検索 | 記述内容を LSA 解析し、類似度に基づいたベクトル検索を実行。 | | `update_item` | 知識の更新 | ID 指定による既存データの書き換え。 | | `delete_item` | 知識の抹消 | ID 指定による物理削除。 | | `get_item_by_id` | 生データ取得 | メタデータを含むレコードの直接参照。 | @@ -52,4 +52,4 @@ ## 5. 開発者向けデバッグ情報 - `/status` エンドポイントにアクセスすることで、現在の MCP セッション数やシステム負荷状況を確認できます。 -- エラーコード `-32000` が返された場合は、バックグラウンドの `llama-server` との通信エラー（タイムアウト等）の可能性が高いです。 +- エラーコード `-32000` が返された場合は、内部の **LSA Engine** の初期化不良（語彙データが空、またはメモリ不足）の可能性が高いです。ログを確認して LSA モデルが正しくロードされているか検証してください。 diff --git a/docs/specification/07_ui_design_spec.md b/docs/specification/07_ui_design_spec.md index 2462737..0a433f5 100644 --- a/docs/specification/07_ui_design_spec.md +++ b/docs/specification/07_ui_design_spec.md @@ -18,7 +18,7 @@ ヘッダー右側に配置されたバッジは、システムの状態をリアルタイムに示します。 -- `Running`: LSA エンジンおよび MCP サーバーが待機中または処理中。 +- `Running`: LSA エンジン（Vibrato 形態素解析 + ndarray 行列演算）および MCP サーバーが待機中または処理中。 - `Stopped`: 重大な構成エラーまたはプロセス停止。 ### 2.2 アクティビティ・ログ (SSE Listener) diff --git a/docs/specification/mcp.json b/docs/specification/mcp.json index 6d82804..a290e41 100644 --- a/docs/specification/mcp.json +++ b/docs/specification/mcp.json @@ -7,7 +7,7 @@ "tools": [ { "name": "search_text", - "description": "Semantic search using sqlite-vec (640d).", + "description": "Semantic search using sqlite-vec (50d).", "arguments": { "content": "string", "limit": "number" @@ -47,4 +47,4 @@ ] } } -} +} \ No newline at end of file diff --git "a/journals/20260223-0007-\344\273\225\346\247\230\346\233\270\343\201\256\347\217\276\344\273\243\345\214\226\343\201\250LSA\345\214\226\343\201\256\345\217\215\346\230\240.md" "b/journals/20260223-0007-\344\273\225\346\247\230\346\233\270\343\201\256\347\217\276\344\273\243\345\214\226\343\201\250LSA\345\214\226\343\201\256\345\217\215\346\230\240.md" new file mode 100644 index 0000000..ad108cc --- /dev/null +++ "b/journals/20260223-0007-\344\273\225\346\247\230\346\233\270\343\201\256\347\217\276\344\273\243\345\214\226\343\201\250LSA\345\214\226\343\201\256\345\217\215\346\230\240.md" @@ -0,0 +1,39 @@ +# 作業報告: 仕様書の現代化とLSA化の反映 + +## 1. 作業実施の理由と指示 + +- **背景**: システムの基本設計が LLM (Gemma-3) メディアから LSA (Latent Semantic Analysis) へと大きく転換されたが、`docs/specification/` 内のドキュメントが旧来の `src-tauri` 依存や LLM 前提の記述（レガシー）のまま残っていた。 +- **意図と指示**: 現状のディレクトリ構造 (`src/frontend`, `src/backend`) および、高速・軽量な LSA ベースの検索エンジンに即した内容にすべての仕様書を更新すること。 + +## 2. 指摘事項とその対応 + +- **指摘**: 仕様書がレガシーなままである。 + - **対応**: 以下のファイルを全面的にリフレッシュした。 + - `01_system_overview.md`: コア技術を LSA に変更、GPU 不要の環境要件に修正。 + - `02_architecture_design.md`: 外部プロセス (llama-server) の排除、Rust 内部での SVD 解析への構成図更新。 + - `03_database_specification.md`: ベクトル次元数を 640 から 50 に、ER図に `items_lsa` を追記。 + - `04_mcp_api_specification.md`: LLM 通信エラーの記述を LSA 初期化エラー等に修正。 + - `07_ui_design_spec.md`: LSA ステータス表示の記述を更新。 + - `mcp.json`: 通信時の 640d 記述を 50d に修正。 + +## 3. 作業詳細 + +AIエージェントは以下の作業を実行した： + +- `docs/specification/` 内の全ファイルを走査し、`src-tauri` および `llama-server`, `Gemma-3` のキーワードを検索。 +- 各ドキュメントを現状の「脱LLM・LSA特化」の設計思想に合わせて論理的に書き換え。 +- Mermaid 図解も、サイドカープロセスを持たない「シングルプロセス・マルチスレッド」構成に修正。 + +## 4. AI視点での結果 + +```mermaid +graph LR + A[Legacy Docs] --> B{Modernization} + B --> C[01: Concepts -> LSA] + B --> D[02: Arch -> No Sidecar] + B --> E[03: DB -> 50 Dimensions] + B --> F[04/07: API/UI -> Verified] + C & D & E & F --> G[Consistent Specification] +``` + +これにより、開発環境の混乱（古いドキュメントを見て llama-server を探すなど）を未然に防ぎ、プロジェクトの「唯一の正（Single Source of Truth）」としての仕様書が現在のソースコードと完全に一致する状態になった。