@nahisaho/katashiro-rag 2.0.0

package/src/embedding/MockEmbeddingProvider.ts

@@ -0,0 +1,123 @@
+/**
+ * Mock Embedding Provider - テスト用
+ *
+ * @requirement REQ-RAG-001
+ * @design DES-KATASHIRO-003-RAG §3.1
+ */
+
+import type { EmbeddingProvider, Vector } from '../types.js';
+
+/**
+ * MockEmbeddingProvider設定
+ */
+export interface MockEmbeddingProviderConfig {
+  /** ベクトル次元数 */
+  dimensions?: number;
+  /** 遅延（ミリ秒） */
+  delay?: number;
+  /** エラーを発生させるか */
+  shouldFail?: boolean;
+}
+
+/**
+ * テスト用モックEmbeddingプロバイダー
+ */
+export class MockEmbeddingProvider implements EmbeddingProvider {
+  readonly name = 'mock';
+  readonly dimensions: number;
+
+  private delay: number;
+  private shouldFail: boolean;
+  private callCount = 0;
+
+  constructor(config: MockEmbeddingProviderConfig = {}) {
+    this.dimensions = config.dimensions ?? 1536;
+    this.delay = config.delay ?? 0;
+    this.shouldFail = config.shouldFail ?? false;
+  }
+
+  /**
+   * 呼び出し回数取得
+   */
+  getCallCount(): number {
+    return this.callCount;
+  }
+
+  /**
+   * リセット
+   */
+  reset(): void {
+    this.callCount = 0;
+  }
+
+  async embed(text: string): Promise<Vector> {
+    this.callCount++;
+
+    if (this.delay > 0) {
+      await this.sleep(this.delay);
+    }
+
+    if (this.shouldFail) {
+      throw new Error('Mock embedding provider error');
+    }
+
+    return this.generateDeterministicVector(text);
+  }
+
+  async embedBatch(texts: string[]): Promise<Vector[]> {
+    this.callCount++;
+
+    if (this.delay > 0) {
+      await this.sleep(this.delay);
+    }
+
+    if (this.shouldFail) {
+      throw new Error('Mock embedding provider error');
+    }
+
+    return texts.map((text) => this.generateDeterministicVector(text));
+  }
+
+  /**
+   * テキストから決定的なベクトルを生成
+   * 同じテキストからは常に同じベクトルが生成される
+   */
+  private generateDeterministicVector(text: string): Vector {
+    const vector: Vector = new Array(this.dimensions);
+    let seed = this.hashString(text);
+
+    for (let i = 0; i < this.dimensions; i++) {
+      seed = this.nextRandom(seed);
+      // -1から1の範囲に正規化
+      vector[i] = (seed / 2147483647) * 2 - 1;
+    }
+
+    // L2正規化
+    const norm = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
+    return vector.map((v) => v / norm);
+  }
+
+  /**
+   * 文字列のシンプルなハッシュ
+   */
+  private hashString(str: string): number {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash;
+    }
+    return Math.abs(hash);
+  }
+
+  /**
+   * 線形合同法による擬似乱数
+   */
+  private nextRandom(seed: number): number {
+    return (seed * 1103515245 + 12345) & 2147483647;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/embedding/OllamaEmbeddingProvider.ts

@@ -0,0 +1,197 @@
+/**
+ * Ollama Embedding Provider
+ *
+ * Local embedding provider using Ollama
+ *
+ * @requirement REQ-RAG-001
+ * @design DES-KATASHIRO-003-RAG
+ */
+
+import { BaseEmbeddingProvider } from './BaseEmbeddingProvider.js';
+import type { EmbeddingConfig } from '../types.js';
+
+/**
+ * Ollama設定
+ */
+export interface OllamaEmbeddingConfig extends EmbeddingConfig {
+  /** ベースURL（デフォルト: http://localhost:11434） */
+  baseUrl?: string;
+  /** モデル名（デフォルト: nomic-embed-text） */
+  model?: string;
+  /** Keep Alive（モデルをメモリに保持する時間） */
+  keepAlive?: string;
+}
+
+/**
+ * Ollama APIレスポンス
+ */
+interface OllamaEmbeddingResponse {
+  embedding: number[];
+  model: string;
+  total_duration?: number;
+  load_duration?: number;
+  prompt_eval_count?: number;
+}
+
+/**
+ * Ollama Embeddingプロバイダー
+ *
+ * ローカルでOllamaを使用した埋め込み生成
+ *
+ * @example
+ * ```typescript
+ * const provider = new OllamaEmbeddingProvider({
+ *   baseUrl: 'http://192.168.224.1:11434',
+ *   model: 'nomic-embed-text',
+ * });
+ *
+ * const embedding = await provider.embed('Hello, world!');
+ * ```
+ */
+export class OllamaEmbeddingProvider extends BaseEmbeddingProvider {
+  readonly name = 'ollama';
+
+  private readonly baseUrl: string;
+  private readonly model: string;
+  private readonly keepAlive: string;
+  private _dimensions: number;
+
+  get dimensions(): number {
+    return this._dimensions;
+  }
+
+  constructor(config: OllamaEmbeddingConfig = {}) {
+    super(config);
+
+    this.baseUrl = config.baseUrl ?? 'http://localhost:11434';
+    this.model = config.model ?? 'nomic-embed-text';
+    this.keepAlive = config.keepAlive ?? '5m';
+
+    // nomic-embed-text: 768次元
+    // mxbai-embed-large: 1024次元
+    // all-minilm: 384次元
+    this._dimensions = config.dimensions ?? this.getDefaultDimensions(this.model);
+  }
+
+  /**
+   * モデルごとのデフォルト次元数
+   */
+  private getDefaultDimensions(model: string): number {
+    const dimensionMap: Record<string, number> = {
+      'nomic-embed-text': 768,
+      'mxbai-embed-large': 1024,
+      'all-minilm': 384,
+      'snowflake-arctic-embed': 1024,
+      'bge-m3': 1024,
+    };
+
+    // モデル名の先頭マッチで検索
+    for (const [key, dims] of Object.entries(dimensionMap)) {
+      if (model.includes(key)) {
+        return dims;
+      }
+    }
+
+    return 768; // デフォルト
+  }
+
+  /**
+   * 単一テキストの埋め込み生成
+   */
+  async embed(text: string): Promise<number[]> {
+    return this.withRetry(async () => {
+      const url = `${this.baseUrl}/api/embeddings`;
+
+      const response = await this.fetchWithTimeout(
+        url,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            model: this.model,
+            prompt: text,
+            keep_alive: this.keepAlive,
+          }),
+        },
+        this.config.timeout
+      );
+
+      const data = (await response.json()) as OllamaEmbeddingResponse;
+
+      // 次元数を実際の値で更新（初回のみ）
+      if (this._dimensions === 768 && data.embedding.length !== 768) {
+        this._dimensions = data.embedding.length;
+      }
+
+      return data.embedding;
+    });
+  }
+
+  /**
+   * バッチ埋め込み生成（Ollama固有実装）
+   *
+   * Ollamaはネイティブのバッチ処理をサポートしていないため、
+   * 並列リクエストで処理
+   */
+  protected override async embedBatchInternal(
+    texts: string[]
+  ): Promise<number[][]> {
+    // 並列度を制限（5並列）
+    const concurrency = 5;
+    const results: number[][] = new Array(texts.length);
+
+    for (let i = 0; i < texts.length; i += concurrency) {
+      const batch = texts.slice(i, i + concurrency);
+      const embeddings = await Promise.all(
+        batch.map((text) => this.embed(text))
+      );
+
+      embeddings.forEach((embedding, j) => {
+        results[i + j] = embedding;
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * 利用可能なモデル一覧取得
+   */
+  async listModels(): Promise<string[]> {
+    const url = `${this.baseUrl}/api/tags`;
+
+    const response = await this.fetchWithTimeout(url, {
+      method: 'GET',
+    });
+
+    interface OllamaTagsResponse {
+      models: Array<{ name: string; model: string }>;
+    }
+
+    const data = (await response.json()) as OllamaTagsResponse;
+
+    // embeddingモデルをフィルタ（名前に embed を含むもの）
+    return data.models
+      .filter(
+        (m) =>
+          m.name.includes('embed') ||
+          m.name.includes('nomic') ||
+          m.name.includes('bge')
+      )
+      .map((m) => m.name);
+  }
+
+  /**
+   * モデルの存在確認
+   */
+  async isModelAvailable(): Promise<boolean> {
+    try {
+      const models = await this.listModels();
+      return models.some((m) => m.includes(this.model));
+    } catch {
+      return false;
+    }
+  }
+}

package/src/embedding/OpenAIEmbeddingProvider.ts

@@ -0,0 +1,226 @@
+/**
+ * OpenAI Embedding Provider
+ *
+ * OpenAI API embedding provider
+ *
+ * @requirement REQ-RAG-001
+ * @design DES-KATASHIRO-003-RAG
+ */
+
+import { BaseEmbeddingProvider } from './BaseEmbeddingProvider.js';
+import type { EmbeddingConfig } from '../types.js';
+
+/**
+ * OpenAI Embedding設定
+ */
+export interface OpenAIEmbeddingConfig extends EmbeddingConfig {
+  /** APIキー */
+  apiKey?: string;
+  /** ベースURL（カスタムエンドポイント用） */
+  baseUrl?: string;
+  /** モデル名 */
+  model?: string;
+  /** 組織ID */
+  organization?: string;
+  /** エンコーディングフォーマット */
+  encodingFormat?: 'float' | 'base64';
+}
+
+/**
+ * OpenAI Embedding APIレスポンス
+ */
+interface OpenAIEmbeddingResponse {
+  object: 'list';
+  data: Array<{
+    object: 'embedding';
+    embedding: number[];
+    index: number;
+  }>;
+  model: string;
+  usage: {
+    prompt_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/**
+ * OpenAI Embeddingプロバイダー
+ *
+ * OpenAI API（またはOpenAI互換API）を使用した埋め込み生成
+ *
+ * @example
+ * ```typescript
+ * // OpenAI API
+ * const provider = new OpenAIEmbeddingProvider({
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   model: 'text-embedding-3-small',
+ * });
+ *
+ * // OpenAI互換API（vLLM, LocalAI等）
+ * const localProvider = new OpenAIEmbeddingProvider({
+ *   baseUrl: 'http://localhost:8000/v1',
+ *   model: 'local-embedding-model',
+ * });
+ *
+ * const embedding = await provider.embed('Hello, world!');
+ * ```
+ */
+export class OpenAIEmbeddingProvider extends BaseEmbeddingProvider {
+  readonly name = 'openai';
+
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly model: string;
+  private readonly organization?: string;
+  private readonly encodingFormat: 'float' | 'base64';
+  private _dimensions: number;
+
+  get dimensions(): number {
+    return this._dimensions;
+  }
+
+  constructor(config: OpenAIEmbeddingConfig = {}) {
+    super(config);
+
+    this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? '';
+    this.baseUrl = config.baseUrl ?? 'https://api.openai.com/v1';
+    this.model = config.model ?? 'text-embedding-3-small';
+    this.organization = config.organization;
+    this.encodingFormat = config.encodingFormat ?? 'float';
+
+    // モデルごとのデフォルト次元数
+    this._dimensions = config.dimensions ?? this.getDefaultDimensions(this.model);
+  }
+
+  /**
+   * モデルごとのデフォルト次元数
+   */
+  private getDefaultDimensions(model: string): number {
+    const dimensionMap: Record<string, number> = {
+      'text-embedding-3-small': 1536,
+      'text-embedding-3-large': 3072,
+      'text-embedding-ada-002': 1536,
+    };
+
+    return dimensionMap[model] ?? 1536;
+  }
+
+  /**
+   * 単一テキストの埋め込み生成
+   */
+  async embed(text: string): Promise<number[]> {
+    const embeddings = await this.embedBatchInternal([text]);
+    const result = embeddings[0];
+    if (!result) {
+      throw new Error('Failed to generate embedding');
+    }
+    return result;
+  }
+
+  /**
+   * バッチ埋め込み生成（OpenAI固有実装）
+   *
+   * OpenAI APIはネイティブでバッチ処理をサポート
+   */
+  protected override async embedBatchInternal(
+    texts: string[]
+  ): Promise<number[][]> {
+    return this.withRetry(async () => {
+      const url = `${this.baseUrl}/embeddings`;
+
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`,
+      };
+
+      if (this.organization) {
+        headers['OpenAI-Organization'] = this.organization;
+      }
+
+      const body: Record<string, unknown> = {
+        model: this.model,
+        input: texts,
+        encoding_format: this.encodingFormat,
+      };
+
+      // 次元数指定（text-embedding-3系のみサポート）
+      if (
+        this._dimensions &&
+        (this.model.includes('text-embedding-3') ||
+          this.baseUrl !== 'https://api.openai.com/v1')
+      ) {
+        body.dimensions = this._dimensions;
+      }
+
+      const response = await this.fetchWithTimeout(
+        url,
+        {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+        },
+        this.config.timeout
+      );
+
+      const data = (await response.json()) as OpenAIEmbeddingResponse;
+
+      // インデックス順にソート
+      const sortedData = [...data.data].sort((a, b) => a.index - b.index);
+
+      // 実際の次元数を更新
+      const firstItem = sortedData[0];
+      if (firstItem) {
+        this._dimensions = firstItem.embedding.length;
+      }
+
+      return sortedData.map((d) => d.embedding);
+    });
+  }
+
+  /**
+   * 利用可能なモデル一覧取得
+   */
+  async listModels(): Promise<string[]> {
+    const url = `${this.baseUrl}/models`;
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+    };
+
+    if (this.organization) {
+      headers['OpenAI-Organization'] = this.organization;
+    }
+
+    const response = await this.fetchWithTimeout(url, {
+      method: 'GET',
+      headers,
+    });
+
+    interface OpenAIModelsResponse {
+      data: Array<{ id: string; owned_by: string }>;
+    }
+
+    const data = (await response.json()) as OpenAIModelsResponse;
+
+    // embeddingモデルをフィルタ
+    return data.data.filter((m) => m.id.includes('embedding')).map((m) => m.id);
+  }
+}
+
+/**
+ * OpenAI互換プロバイダー（ファクトリ関数）
+ *
+ * vLLM, LocalAI, LM Studio等のOpenAI互換エンドポイント用
+ */
+export function createOpenAICompatibleEmbeddingProvider(
+  baseUrl: string,
+  model: string,
+  config: Partial<OpenAIEmbeddingConfig> = {}
+): OpenAIEmbeddingProvider {
+  return new OpenAIEmbeddingProvider({
+    ...config,
+    baseUrl,
+    model,
+    apiKey: config.apiKey ?? 'not-required', // 一部のローカルAPIはキー不要
+  });
+}

package/src/embedding/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Embedding module exports
+ */
+
+// Manager
+export { EmbeddingManager } from './EmbeddingManager.js';
+
+// Base
+export { BaseEmbeddingProvider } from './BaseEmbeddingProvider.js';
+
+// Providers
+export { MockEmbeddingProvider } from './MockEmbeddingProvider.js';
+export type { MockEmbeddingProviderConfig } from './MockEmbeddingProvider.js';
+
+export { OllamaEmbeddingProvider } from './OllamaEmbeddingProvider.js';
+export type { OllamaEmbeddingConfig } from './OllamaEmbeddingProvider.js';
+
+export { OpenAIEmbeddingProvider, createOpenAICompatibleEmbeddingProvider } from './OpenAIEmbeddingProvider.js';
+export type { OpenAIEmbeddingConfig } from './OpenAIEmbeddingProvider.js';
+
+export { AzureOpenAIEmbeddingProvider } from './AzureOpenAIEmbeddingProvider.js';
+export type { AzureOpenAIEmbeddingConfig } from './AzureOpenAIEmbeddingProvider.js';
+
+// Factory
+export {
+  EmbeddingFactory,
+  createEmbeddingProvider,
+  getDefaultEmbeddingProvider,
+} from './EmbeddingFactory.js';
+export type {
+  EmbeddingProviderType,
+  EmbeddingProviderConfigMap,
+} from './EmbeddingFactory.js';

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * RAG Package - Main Entry Point
+ *
+ * @packageDocumentation
+ * @module @nahisaho/katashiro-rag
+ */
+
+// Types
+export type {
+  Document,
+  Chunk,
+  SearchResult,
+  RetrievalResult,
+  Vector,
+  EmbeddingProvider,
+  VectorStore,
+  ChunkingConfig,
+  RetrieverConfig,
+  RAGEngineConfig,
+} from './types.js';
+
+// Embedding
+export { EmbeddingManager } from './embedding/index.js';
+export { MockEmbeddingProvider } from './embedding/index.js';
+export type { MockEmbeddingProviderConfig } from './embedding/index.js';
+
+// Vector Store
+export { InMemoryVectorStore } from './vectordb/index.js';
+export type { InMemoryVectorStoreConfig } from './vectordb/index.js';
+
+// Chunking
+export { DocumentChunker } from './chunking/index.js';
+
+// Retriever
+export { Retriever } from './Retriever.js';
+
+// RAG Engine
+export { RAGEngine } from './RAGEngine.js';
+
+// RAG Pipeline (REQ-RAG-101)
+export { RAGPipeline, DEFAULT_RAG_SYSTEM_PROMPT, DEFAULT_CONTEXT_TEMPLATE } from './RAGPipeline.js';
+export type { RAGPipelineConfig, RAGPipelineResult, RAGQueryOptions } from './RAGPipeline.js';
+
+// Reranking (REQ-RAG-103)
+export {
+  LLMReranker,
+  rerankResults,
+  DEFAULT_RERANKER_CONFIG,
+  DEFAULT_RERANKER_PROMPT,
+} from './reranking/index.js';
+export type {
+  LLMRerankerConfig,
+  RerankedResult,
+  RerankerResponse,
+} from './reranking/index.js';