データフロー詳細

本システムにおける主要な処理フロー（アイテムの登録とベクトル検索）を詳細に説明します。

1. アイテム登録フロー (add_item_text)

ユーザーまたは外部エージェントがテキストを送信してから、ベクトル化されて保存されるまでの流れです。

sequenceDiagram
    participant Client as MCP Client
    participant Axum as MCP Server (Axum)
    participant Llama as Llama Client
    participant LS as llama-server (Sidecar)
    participant DB as SQLite (SeaORM)

    Client->>Axum: Request: tools/call (add_item_text)
    Axum->>Llama: get_embedding(content)
    Llama->>LS: HTTP POST /embedding
    LS->>LS: Gemma 3 Inference (Vectorize)
    LS-->>Llama: JSON { embedding: [...] }
    Llama-->>Axum: Vec<f32> (768dim)
    
    Axum->>DB: INSERT INTO items (content, path)
    DB-->>Axum: Return id
    
    Axum->>DB: INSERT INTO vec_items (id, embedding)
    Note over DB: Binary serialization (Little Endian)
    DB-->>Axum: OK
    
    Axum-->>Client: Result: "Added item with id X"

2. ベクトル検索フロー (search_text)

クエリ文字列から類似する文章を高速に検索し、返却するまでの流れです。

sequenceDiagram
    participant Client as MCP Client
    participant Axum as MCP Server (Axum)
    participant Llama as Llama Client
    participant LS as llama-server (Sidecar)
    participant DB as SQLite (sqlite-vec)

    Client->>Axum: Request: tools/call (search_text)
    Axum->>Llama: get_embedding(query_text)
    Llama->>LS: HTTP POST /embedding
    LS-->>Llama: Result Vector
    Llama-->>Axum: Vec<f32>
    
    Axum->>DB: SELECT ... FROM vec_items ... MATCH ?
    Note over DB: Distance Calculation (Cosine / L2)
    DB-->>Axum: List of (id, content, distance)
    
    Axum-->>Client: JSON Format Results

主要なデータ変換

ベクトルシリアライズ

• llama-server から返却されるベクトルは Vec<f64>（または f32）の配列です。
• sqlite-vec で扱うために、Rust 側で f32 の Little Endian バイト列 (Vec<u8>) に変換して保存/クエリを行います。

MCP 通信

• すべての外部インターフェースは MCP (JSON-RPC 2.0) プロトコルに基づきます。
• 通信トランスポートとして SSE (Server-Sent Events) を使用し、Axum 経由でメッセージをパースします。