@reftrixmcp/ml 0.1.7

package/src/embeddings/style-embedding.service.ts

@@ -0,0 +1,201 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Style Embedding Service
+ *
+ * スタイル特徴量のテキスト表現から埋め込みベクトルを生成するサービス。
+ * 既存のEmbeddingServiceをラップし、スタイル特徴量に特化した機能を提供。
+ *
+ * @module embeddings/style-embedding.service
+ * @version 0.1.0
+ */
+
+import { EmbeddingService } from "./service.js";
+import type { CacheStats } from "./types.js";
+
+// 開発環境でのログ出力
+const isDevelopment = process.env.NODE_ENV === "development";
+const log = (message: string, data?: unknown): void => {
+  if (isDevelopment) {
+    // eslint-disable-next-line no-console
+    console.log(`[StyleEmbedding] ${message}`, data ?? "");
+  }
+};
+
+/**
+ * スタイル埋め込みの設定
+ */
+export interface StyleEmbeddingConfig {
+  /**
+   * 内部で使用するEmbeddingServiceのインスタンス
+   * デフォルトは新規インスタンスを作成
+   */
+  embeddingService?: EmbeddingService;
+
+  /**
+   * バッチ処理時の最大並列数
+   * @default 32
+   */
+  batchSize?: number;
+}
+
+/**
+ * スタイル特徴量埋め込み生成サービス
+ *
+ * スタイル特徴量テキスト表現から768次元の埋め込みベクトルを生成。
+ * multilingual-e5-baseモデルを使用し、HNSWベクトル検索と互換。
+ */
+export class StyleEmbeddingService {
+  private embeddingService: EmbeddingService;
+  private batchSize: number;
+
+  constructor(config: StyleEmbeddingConfig = {}) {
+    this.embeddingService = config.embeddingService ?? new EmbeddingService();
+    this.batchSize = config.batchSize ?? 32;
+
+    log("StyleEmbeddingService created", { batchSize: this.batchSize });
+  }
+
+  /**
+   * スタイル特徴量テキストから埋め込みを生成
+   *
+   * @param styleText - StyleFeaturesToTextで生成されたテキスト表現
+   * @returns 768次元の正規化済み埋め込みベクトル
+   *
+   * @example
+   * ```typescript
+   * const styleText = 'Design style: thin stroke (1px) consistent outlined simple complexity';
+   * const embedding = await service.generateEmbedding(styleText);
+   * // embedding.length === 768
+   * ```
+   */
+  async generateEmbedding(styleText: string): Promise<number[]> {
+    log("Generating embedding for style text", { length: styleText.length });
+
+    // "passage:" プレフィックスを使用（ドキュメント埋め込みとして扱う）
+    // スタイル特徴量は検索対象のドキュメント側なのでpassageを使用
+    const embedding = await this.embeddingService.generateEmbedding(styleText, "passage");
+
+    log("Embedding generated", { dimension: embedding.length });
+
+    return embedding;
+  }
+
+  /**
+   * クエリテキストから検索用埋め込みを生成
+   *
+   * 類似デザイン検索時に使用。ユーザーのクエリや参照デザインの
+   * スタイル特徴量テキストから検索用の埋め込みを生成。
+   *
+   * @param queryText - 検索クエリまたは参照スタイルテキスト
+   * @returns 768次元の正規化済み埋め込みベクトル
+   *
+   * @example
+   * ```typescript
+   * const queryEmbedding = await service.generateQueryEmbedding('thin stroke outlined icon');
+   * // HNSW検索で使用
+   * ```
+   */
+  async generateQueryEmbedding(queryText: string): Promise<number[]> {
+    log("Generating query embedding", { length: queryText.length });
+
+    // "query:" プレフィックスを使用（検索クエリとして扱う）
+    const embedding = await this.embeddingService.generateEmbedding(queryText, "query");
+
+    log("Query embedding generated", { dimension: embedding.length });
+
+    return embedding;
+  }
+
+  /**
+   * 複数のスタイル特徴量テキストからバッチで埋め込みを生成
+   *
+   * @param styleTexts - スタイル特徴量テキストの配列
+   * @returns 768次元の埋め込みベクトルの配列
+   *
+   * @example
+   * ```typescript
+   * const embeddings = await service.generateBatchEmbeddings([
+   *   'Design style: thin stroke outlined',
+   *   'Design style: thick stroke filled',
+   * ]);
+   * // embeddings.length === 2
+   * ```
+   */
+  async generateBatchEmbeddings(styleTexts: string[]): Promise<number[][]> {
+    if (styleTexts.length === 0) {
+      return [];
+    }
+
+    log("Generating batch embeddings", { count: styleTexts.length });
+
+    const startTime = performance.now();
+
+    // "passage:" プレフィックスを使用（ドキュメント埋め込み）
+    const embeddings = await this.embeddingService.generateBatchEmbeddings(styleTexts, "passage");
+
+    const elapsed = performance.now() - startTime;
+    log("Batch embeddings generated", {
+      count: embeddings.length,
+      elapsedMs: elapsed,
+      avgMs: elapsed / embeddings.length,
+    });
+
+    return embeddings;
+  }
+
+  /**
+   * キャッシュ統計を取得
+   */
+  getCacheStats(): CacheStats {
+    return this.embeddingService.getCacheStats();
+  }
+
+  /**
+   * キャッシュをクリア
+   */
+  clearCache(): void {
+    this.embeddingService.clearCache();
+    log("Cache cleared");
+  }
+}
+
+// =============================================================================
+// シングルトンとヘルパー関数
+// =============================================================================
+
+/**
+ * デフォルトのスタイル埋め込みサービスインスタンス
+ */
+export const styleEmbeddingService = new StyleEmbeddingService();
+
+/**
+ * スタイル特徴量テキストから埋め込みを生成するヘルパー関数
+ *
+ * @param styleText - スタイル特徴量テキスト
+ * @returns 768次元の埋め込みベクトル
+ */
+export async function createStyleEmbedding(styleText: string): Promise<number[]> {
+  return styleEmbeddingService.generateEmbedding(styleText);
+}
+
+/**
+ * 複数のスタイル特徴量テキストからバッチで埋め込みを生成するヘルパー関数
+ *
+ * @param styleTexts - スタイル特徴量テキストの配列
+ * @returns 768次元の埋め込みベクトルの配列
+ */
+export async function createBatchStyleEmbeddings(styleTexts: string[]): Promise<number[][]> {
+  return styleEmbeddingService.generateBatchEmbeddings(styleTexts);
+}
+
+/**
+ * 検索クエリ用の埋め込みを生成するヘルパー関数
+ *
+ * @param queryText - 検索クエリテキスト
+ * @returns 768次元の埋め込みベクトル
+ */
+export async function createQueryEmbedding(queryText: string): Promise<number[]> {
+  return styleEmbeddingService.generateQueryEmbedding(queryText);
+}

package/src/embeddings/types.ts

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Embedding service type definitions
+ */
+
+/**
+ * Type of text for embedding generation
+ * - 'query': For search queries (prefixed with "query: ")
+ * - 'passage': For document/content (prefixed with "passage: ")
+ */
+export type EmbeddingTextType = "query" | "passage";
+
+/**
+ * Configuration options for EmbeddingService
+ */
+export interface EmbeddingServiceConfig {
+  /**
+   * Model ID from Hugging Face Hub
+   * @default "Xenova/multilingual-e5-base"
+   */
+  modelId?: string;
+
+  /**
+   * Cache directory for downloaded models
+   */
+  cacheDir?: string;
+
+  /**
+   * Device to run inference on
+   * @default "cpu"
+   */
+  device?: "cpu" | "cuda" | "webgpu";
+
+  /**
+   * Data type for model precision
+   * @default "fp32"
+   */
+  dtype?: "fp32" | "fp16" | "q8" | "q4";
+
+  /**
+   * Maximum number of entries in the embedding cache (LRU eviction)
+   * @default 5000
+   */
+  maxCacheSize?: number;
+
+  /**
+   * Number of inferences before the ONNX pipeline is disposed and recreated.
+   *
+   * onnxruntime-node uses a native C++ arena allocator that grows monotonically
+   * during inference. Pipeline recycling tears down the InferenceSession via
+   * session.release(), freeing the arena's native memory back to the OS.
+   *
+   * Lower values reduce peak memory but increase overhead from model re-initialization.
+   * Higher values reduce overhead but allow more native memory accumulation.
+   *
+   * Set to 0 to disable automatic recycling.
+   *
+   * @default 30
+   */
+  pipelineRecycleThreshold?: number;
+}
+
+/**
+ * Cache statistics interface
+ */
+export interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  evictions: number;
+}
+
+/**
+ * Embedding result with metadata
+ */
+export interface EmbeddingResult {
+  embedding: number[];
+  text: string;
+  type: EmbeddingTextType;
+  cached: boolean;
+  processingTimeMs: number;
+}
+
+/**
+ * Batch embedding result
+ */
+export interface BatchEmbeddingResult {
+  embeddings: number[][];
+  texts: string[];
+  type: EmbeddingTextType;
+  totalProcessingTimeMs: number;
+  cachedCount: number;
+}

package/src/embeddings/vision-embedding.service.ts

@@ -0,0 +1,273 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Vision Embedding Service
+ *
+ * Vision Embedding生成ロジック
+ *
+ * 視覚特徴量（VisionFeatures）からテキスト表現を生成し、
+ * multilingual-e5-baseモデルで768次元の埋め込みベクトルを生成するサービス
+ */
+
+import type {
+  VisionFeatures,
+  VisionEmbeddingServiceConfig,
+  VisionCacheStats,
+} from "./vision-embedding.types.js";
+import { EmbeddingService } from "./service.js";
+
+/**
+ * デフォルトのキャッシュサイズ
+ */
+const DEFAULT_MAX_CACHE_SIZE = 5000;
+
+/**
+ * VisionFeaturesをテキスト表現に変換する
+ *
+ * @param features - 視覚特徴量
+ * @returns テキスト表現
+ */
+export function visionFeaturesToText(features: VisionFeatures): string {
+  const parts: string[] = [
+    `visual_rhythm: ${features.rhythm}`,
+    `whitespace_ratio: ${features.whitespaceRatio}`,
+    `content_density: ${features.density}`,
+    `visual_gravity: ${features.gravity}`,
+    `color_theme: ${features.theme}`,
+  ];
+
+  // オプショナルフィールドを追加（存在する場合のみ）
+  if (features.mood !== undefined && features.mood !== null) {
+    parts.push(`mood: ${features.mood}`);
+  }
+
+  if (features.brandTone !== undefined && features.brandTone !== null) {
+    parts.push(`brandTone: ${features.brandTone}`);
+  }
+
+  return parts.join(", ");
+}
+
+/**
+ * VisionFeaturesからキャッシュキーを生成
+ */
+function getCacheKey(features: VisionFeatures): string {
+  return JSON.stringify({
+    r: features.rhythm,
+    w: features.whitespaceRatio,
+    d: features.density,
+    g: features.gravity,
+    t: features.theme,
+    m: features.mood,
+    b: features.brandTone,
+  });
+}
+
+/**
+ * VisionEmbeddingService
+ *
+ * 視覚特徴量から768次元の埋め込みベクトルを生成するサービス
+ */
+export class VisionEmbeddingService {
+  private embeddingService: EmbeddingService;
+  private cache: Map<string, number[]> = new Map();
+  private cacheHits = 0;
+  private cacheMisses = 0;
+  private cacheEvictions = 0;
+  private maxCacheSize: number;
+
+  constructor(config: VisionEmbeddingServiceConfig = {}) {
+    this.maxCacheSize = config.maxCacheSize ?? DEFAULT_MAX_CACHE_SIZE;
+    this.embeddingService = new EmbeddingService();
+
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.log("[VisionEmbedding] Service created with maxCacheSize:", this.maxCacheSize);
+    }
+  }
+
+  /**
+   * VisionFeaturesから768次元の埋め込みベクトルを生成
+   *
+   * @param features - 視覚特徴量
+   * @returns 768次元のL2正規化されたベクトル
+   */
+  async generateVisionEmbedding(features: VisionFeatures): Promise<number[]> {
+    const cacheKey = getCacheKey(features);
+
+    // キャッシュチェック（LRU更新付き）
+    const cached = this.getCacheEntry(cacheKey);
+    if (cached) {
+      this.cacheHits++;
+      if (process.env.NODE_ENV === "development") {
+        // eslint-disable-next-line no-console
+        console.log("[VisionEmbedding] Cache hit");
+      }
+      return cached;
+    }
+
+    this.cacheMisses++;
+
+    // テキスト表現に変換
+    const text = visionFeaturesToText(features);
+
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.log("[VisionEmbedding] Generating embedding for:", text.substring(0, 80));
+    }
+
+    // EmbeddingServiceを使用して埋め込み生成
+    // 'passage'プレフィックスを使用（ドキュメント埋め込み）
+    const embedding = await this.embeddingService.generateEmbedding(text, "passage");
+
+    // キャッシュに保存（LRU eviction付き）
+    this.setCacheEntry(cacheKey, embedding);
+
+    return embedding;
+  }
+
+  /**
+   * 複数のVisionFeaturesから埋め込みベクトルを一括生成
+   *
+   * @param featuresArray - 視覚特徴量の配列
+   * @returns 768次元ベクトルの配列
+   */
+  async generateBatchVisionEmbeddings(featuresArray: VisionFeatures[]): Promise<number[][]> {
+    if (featuresArray.length === 0) {
+      return [];
+    }
+
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.log("[VisionEmbedding] Batch processing", featuresArray.length, "items");
+    }
+
+    // キャッシュチェックと未キャッシュアイテムの特定
+    const results: (number[] | undefined)[] = new Array(featuresArray.length);
+    const uncachedIndices: number[] = [];
+    const uncachedTexts: string[] = [];
+
+    for (let i = 0; i < featuresArray.length; i++) {
+      const features = featuresArray[i];
+      if (!features) continue;
+
+      const cacheKey = getCacheKey(features);
+      const cached = this.getCacheEntry(cacheKey);
+
+      if (cached) {
+        this.cacheHits++;
+        results[i] = cached;
+      } else {
+        this.cacheMisses++;
+        uncachedIndices.push(i);
+        uncachedTexts.push(visionFeaturesToText(features));
+      }
+    }
+
+    // 未キャッシュアイテムの一括生成
+    if (uncachedTexts.length > 0) {
+      const embeddings = await this.embeddingService.generateBatchEmbeddings(
+        uncachedTexts,
+        "passage"
+      );
+
+      for (let j = 0; j < uncachedIndices.length; j++) {
+        const originalIndex = uncachedIndices[j];
+        const embedding = embeddings[j];
+        const features = featuresArray[originalIndex ?? 0];
+
+        if (originalIndex !== undefined && embedding && features) {
+          results[originalIndex] = embedding;
+
+          // キャッシュに保存
+          const cacheKey = getCacheKey(features);
+          this.setCacheEntry(cacheKey, embedding);
+        }
+      }
+    }
+
+    // undefinedを除去して返却
+    return results.filter((r): r is number[] => r !== undefined);
+  }
+
+  /**
+   * キャッシュ統計を取得
+   */
+  getCacheStats(): VisionCacheStats {
+    return {
+      hits: this.cacheHits,
+      misses: this.cacheMisses,
+      size: this.cache.size,
+      evictions: this.cacheEvictions,
+    };
+  }
+
+  /**
+   * キャッシュをクリア
+   */
+  clearCache(): void {
+    this.cache.clear();
+    this.cacheHits = 0;
+    this.cacheMisses = 0;
+    this.cacheEvictions = 0;
+
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.log("[VisionEmbedding] Cache cleared");
+    }
+  }
+
+  /**
+   * キャッシュエントリを取得（LRU更新）
+   */
+  private getCacheEntry(key: string): number[] | undefined {
+    const value = this.cache.get(key);
+    if (value !== undefined) {
+      // LRU: 最近使用したエントリを末尾に移動
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  /**
+   * キャッシュエントリを設定（LRU eviction）
+   */
+  private setCacheEntry(key: string, value: number[]): void {
+    // キャッシュがいっぱいの場合、最も古いエントリを削除
+    while (this.cache.size >= this.maxCacheSize) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.cache.delete(oldestKey);
+        this.cacheEvictions++;
+        if (process.env.NODE_ENV === "development") {
+          // eslint-disable-next-line no-console
+          console.log("[VisionEmbedding] Cache evicted oldest entry");
+        }
+      } else {
+        break;
+      }
+    }
+    this.cache.set(key, value);
+  }
+}
+
+// シングルトンインスタンス
+export const visionEmbeddingService = new VisionEmbeddingService();
+
+/**
+ * 単一のVisionFeaturesから埋め込みを生成するヘルパー関数
+ */
+export async function createVisionEmbedding(features: VisionFeatures): Promise<number[]> {
+  return visionEmbeddingService.generateVisionEmbedding(features);
+}
+
+/**
+ * 複数のVisionFeaturesから埋め込みを一括生成するヘルパー関数
+ */
+export async function createBatchVisionEmbeddings(
+  featuresArray: VisionFeatures[]
+): Promise<number[][]> {
+  return visionEmbeddingService.generateBatchVisionEmbeddings(featuresArray);
+}

package/src/embeddings/vision-embedding.types.ts

@@ -0,0 +1,117 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Vision Embedding Types
+ *
+ * Vision Embedding生成ロジック
+ *
+ * 視覚特徴量を表す型定義
+ */
+
+/**
+ * 視覚的リズムの種類
+ * - regular: 規則的なリズム（均等配置）
+ * - varied: 変化のあるリズム（意図的な強弱）
+ * - asymmetric: 非対称なリズム（アシンメトリック）
+ */
+export type VisionRhythm = "regular" | "varied" | "asymmetric";
+
+/**
+ * コンテンツ密度の種類
+ * - sparse: 疎（ホワイトスペースが多い）
+ * - moderate: 中程度
+ * - dense: 密集（コンテンツが多い）
+ */
+export type VisionDensity = "sparse" | "moderate" | "dense";
+
+/**
+ * 視覚的重心の位置
+ * - top: 上部
+ * - center: 中央
+ * - bottom: 下部
+ * - left: 左側
+ * - right: 右側
+ */
+export type VisionGravity = "top" | "center" | "bottom" | "left" | "right";
+
+/**
+ * カラーテーマの種類
+ * - light: ライトテーマ
+ * - dark: ダークテーマ
+ * - mixed: 混合テーマ
+ */
+export type VisionTheme = "light" | "dark" | "mixed";
+
+/**
+ * 視覚特徴量インターフェース
+ *
+ * Webページのレイアウト/デザインから抽出された視覚的特徴を表す
+ */
+export interface VisionFeatures {
+  /**
+   * 視覚的リズム
+   * 要素の配置パターン・繰り返しの規則性
+   */
+  rhythm: VisionRhythm;
+
+  /**
+   * ホワイトスペース比率 (0-1)
+   * 0: ホワイトスペースなし（完全にコンテンツで埋まっている）
+   * 1: 完全にホワイトスペース（コンテンツなし）
+   */
+  whitespaceRatio: number;
+
+  /**
+   * コンテンツ密度
+   * ページ上のコンテンツ要素の密集度
+   */
+  density: VisionDensity;
+
+  /**
+   * 視覚的重心
+   * コンテンツの視覚的な重心位置
+   */
+  gravity: VisionGravity;
+
+  /**
+   * カラーテーマ
+   * 全体的な色調
+   */
+  theme: VisionTheme;
+
+  /**
+   * ムード (オプション)
+   * Vision AIから取得したページの雰囲気/印象
+   * 例: 'professional', 'playful', 'elegant', 'minimal'
+   */
+  mood?: string;
+
+  /**
+   * ブランドトーン (オプション)
+   * Vision AIから取得したブランドの印象
+   * 例: 'corporate', 'startup', 'luxury', 'friendly'
+   */
+  brandTone?: string;
+}
+
+/**
+ * VisionEmbeddingServiceの設定オプション
+ */
+export interface VisionEmbeddingServiceConfig {
+  /**
+   * キャッシュの最大サイズ
+   * @default 5000
+   */
+  maxCacheSize?: number;
+}
+
+/**
+ * キャッシュ統計情報
+ */
+export interface VisionCacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  evictions: number;
+}