@nahisaho/katashiro-llm 2.0.0

package/src/providers/BaseLLMProvider.ts

@@ -0,0 +1,110 @@
+/**
+ * Base LLM Provider
+ *
+ * @requirement REQ-LLM-001
+ * @design DES-KATASHIRO-003-LLM §3.1.1
+ */
+
+import type { z, ZodType } from 'zod';
+import type {
+  LLMProvider,
+  ProviderConfig,
+  GenerateRequest,
+  GenerateResponse,
+  StreamChunk,
+} from '../types.js';
+
+/**
+ * 抽象LLMプロバイダー基底クラス
+ */
+export abstract class BaseLLMProvider implements LLMProvider {
+  abstract readonly name: string;
+  abstract readonly supportedModels: string[];
+
+  protected config: ProviderConfig;
+  protected defaultModel: string;
+
+  constructor(config: ProviderConfig = {}) {
+    this.config = {
+      timeout: 30000,
+      maxRetries: 3,
+      ...config,
+    };
+    this.defaultModel = config.defaultModel ?? this.getDefaultModel();
+  }
+
+  /**
+   * デフォルトモデル取得
+   */
+  protected abstract getDefaultModel(): string;
+
+  /**
+   * テキスト生成（抽象メソッド）
+   */
+  abstract generate(request: GenerateRequest): Promise<GenerateResponse>;
+
+  /**
+   * ストリーミング生成（抽象メソッド）
+   */
+  abstract generateStream(request: GenerateRequest): AsyncGenerator<StreamChunk>;
+
+  /**
+   * 構造化出力生成
+   */
+  async generateStructured<T extends ZodType>(
+    request: GenerateRequest,
+    schema: T
+  ): Promise<z.infer<T>> {
+    const jsonSchema = this.zodToJsonSchema(schema);
+
+    const enhancedRequest: GenerateRequest = {
+      ...request,
+      responseFormat: { type: 'json_object' },
+      messages: [
+        ...request.messages,
+        {
+          role: 'user',
+          content: `Respond with valid JSON matching this schema:\n${JSON.stringify(jsonSchema, null, 2)}`,
+        },
+      ],
+    };
+
+    const response = await this.generate(enhancedRequest);
+    const parsed = JSON.parse(response.content);
+    return schema.parse(parsed);
+  }
+
+  /**
+   * トークン数カウント（デフォルト実装）
+   */
+  async countTokens(text: string, _model?: string): Promise<number> {
+    // 簡易実装: 4文字 ≈ 1トークン
+    return Math.ceil(text.length / 4);
+  }
+
+  /**
+   * モデルサポート確認
+   */
+  isModelSupported(model: string): boolean {
+    return this.supportedModels.includes(model);
+  }
+
+  /**
+   * モデル取得（デフォルトまたは指定）
+   */
+  protected getModel(request: GenerateRequest): string {
+    return request.model ?? this.defaultModel;
+  }
+
+  /**
+   * Zodスキーマ→JSONスキーマ変換（簡易実装）
+   */
+  protected zodToJsonSchema(schema: ZodType): Record<string, unknown> {
+    // 実際にはzod-to-json-schemaライブラリを使用
+    const description = (schema as { description?: string }).description;
+    return {
+      type: 'object',
+      description: description ?? 'Generated schema',
+    };
+  }
+}

package/src/providers/LLMFactory.ts

@@ -0,0 +1,216 @@
+/**
+ * LLM Provider Factory
+ *
+ * Esperanto-style factory for creating LLM providers
+ *
+ * @requirement REQ-LLM-001
+ * @design DES-KATASHIRO-003-LLM
+ */
+
+import type { LLMProvider, ProviderConfig } from '../types.js';
+import { MockLLMProvider } from './MockLLMProvider.js';
+import { OllamaLLMProvider } from './OllamaLLMProvider.js';
+import type { OllamaProviderConfig } from './OllamaLLMProvider.js';
+import { OpenAILLMProvider } from './OpenAILLMProvider.js';
+import type { OpenAIProviderConfig } from './OpenAILLMProvider.js';
+import { AzureOpenAILLMProvider } from './AzureOpenAILLMProvider.js';
+import type { AzureOpenAIProviderConfig } from './AzureOpenAILLMProvider.js';
+
+/**
+ * プロバイダータイプ
+ */
+export type LLMProviderType =
+  | 'mock'
+  | 'ollama'
+  | 'openai'
+  | 'openai-compatible'
+  | 'azure-openai';
+
+/**
+ * プロバイダー設定マップ
+ */
+export interface LLMProviderConfigMap {
+  mock: ProviderConfig;
+  ollama: OllamaProviderConfig;
+  openai: OpenAIProviderConfig;
+  'openai-compatible': OpenAIProviderConfig;
+  'azure-openai': AzureOpenAIProviderConfig;
+}
+
+/**
+ * 環境変数から設定を取得
+ */
+function getConfigFromEnv(
+  provider: LLMProviderType
+): Partial<LLMProviderConfigMap[LLMProviderType]> {
+  switch (provider) {
+    case 'ollama':
+      return {
+        baseUrl: process.env.OLLAMA_BASE_URL ?? process.env.OLLAMA_HOST,
+        model: process.env.OLLAMA_MODEL,
+      };
+
+    case 'openai':
+      return {
+        apiKey: process.env.OPENAI_API_KEY,
+        organization: process.env.OPENAI_ORGANIZATION,
+        baseUrl: process.env.OPENAI_BASE_URL,
+        model: process.env.OPENAI_MODEL,
+      };
+
+    case 'openai-compatible':
+      return {
+        apiKey:
+          process.env.OPENAI_COMPATIBLE_API_KEY_LLM ??
+          process.env.OPENAI_COMPATIBLE_API_KEY,
+        baseUrl:
+          process.env.OPENAI_COMPATIBLE_BASE_URL_LLM ??
+          process.env.OPENAI_COMPATIBLE_BASE_URL,
+      };
+
+    case 'azure-openai':
+      return {
+        endpoint: process.env.AZURE_OPENAI_ENDPOINT,
+        apiKey: process.env.AZURE_OPENAI_API_KEY,
+        deploymentName: process.env.AZURE_OPENAI_DEPLOYMENT,
+        apiVersion: process.env.AZURE_OPENAI_API_VERSION,
+      };
+
+    default:
+      return {};
+  }
+}
+
+/**
+ * LLM Provider Factory
+ *
+ * Esperantoスタイルのファクトリクラス
+ *
+ * @example
+ * ```typescript
+ * // 利用可能なプロバイダーを確認
+ * const providers = LLMFactory.getAvailableProviders();
+ *
+ * // プロバイダーを作成
+ * const provider = LLMFactory.create('ollama', {
+ *   baseUrl: 'http://192.168.224.1:11434',
+ *   model: 'llama3.2',
+ * });
+ *
+ * // または環境変数から自動設定
+ * const provider = LLMFactory.create('openai');
+ * ```
+ */
+export class LLMFactory {
+  /**
+   * プロバイダー作成
+   */
+  static create<T extends LLMProviderType>(
+    provider: T,
+    config?: Partial<LLMProviderConfigMap[T]>
+  ): LLMProvider {
+    // 環境変数からの設定とマージ
+    const envConfig = getConfigFromEnv(provider);
+    const mergedConfig = { ...envConfig, ...config };
+
+    switch (provider) {
+      case 'mock':
+        return new MockLLMProvider(mergedConfig as unknown as import('./MockLLMProvider.js').MockProviderConfig);
+
+      case 'ollama':
+        return new OllamaLLMProvider(mergedConfig as OllamaProviderConfig);
+
+      case 'openai':
+      case 'openai-compatible':
+        return new OpenAILLMProvider(mergedConfig as OpenAIProviderConfig);
+
+      case 'azure-openai':
+        return new AzureOpenAILLMProvider(
+          mergedConfig as AzureOpenAIProviderConfig
+        );
+
+      default:
+        throw new Error(`Unknown LLM provider: ${provider}`);
+    }
+  }
+
+  /**
+   * 利用可能なプロバイダー一覧
+   */
+  static getAvailableProviders(): LLMProviderType[] {
+    return ['mock', 'ollama', 'openai', 'openai-compatible', 'azure-openai'];
+  }
+
+  /**
+   * デフォルトプロバイダー取得
+   *
+   * 環境変数から自動判定
+   */
+  static getDefaultProvider(): LLMProvider {
+    // 優先順位: AZURE > OPENAI > OLLAMA > MOCK
+    if (
+      process.env.AZURE_OPENAI_ENDPOINT &&
+      process.env.AZURE_OPENAI_API_KEY
+    ) {
+      return this.create('azure-openai');
+    }
+
+    if (process.env.OPENAI_API_KEY) {
+      return this.create('openai');
+    }
+
+    if (process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST) {
+      return this.create('ollama');
+    }
+
+    // フォールバック: モック
+    return this.create('mock');
+  }
+
+  /**
+   * プロバイダーの利用可能確認
+   */
+  static isProviderConfigured(provider: LLMProviderType): boolean {
+    switch (provider) {
+      case 'mock':
+        return true;
+
+      case 'ollama':
+        return !!(process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST);
+
+      case 'openai':
+        return !!process.env.OPENAI_API_KEY;
+
+      case 'openai-compatible':
+        return !!(
+          process.env.OPENAI_COMPATIBLE_BASE_URL_LLM ||
+          process.env.OPENAI_COMPATIBLE_BASE_URL
+        );
+
+      case 'azure-openai':
+        return !!(
+          process.env.AZURE_OPENAI_ENDPOINT && process.env.AZURE_OPENAI_API_KEY
+        );
+
+      default:
+        return false;
+    }
+  }
+}
+
+/**
+ * 便利関数: LLMプロバイダー作成
+ */
+export function createLLMProvider<T extends LLMProviderType>(
+  provider: T,
+  config?: Partial<LLMProviderConfigMap[T]>
+): LLMProvider {
+  return LLMFactory.create(provider, config);
+}
+
+/**
+ * 便利関数: デフォルトプロバイダー取得
+ */
+export function getDefaultLLMProvider(): LLMProvider {
+  return LLMFactory.getDefaultProvider();
+}

package/src/providers/MockLLMProvider.ts

@@ -0,0 +1,173 @@
+/**
+ * Mock LLM Provider - テスト用モックプロバイダー
+ *
+ * @requirement REQ-LLM-001
+ * @design DES-KATASHIRO-003-LLM §3.1
+ */
+
+import type { ZodType, z } from 'zod';
+import type {
+  LLMProvider,
+  GenerateRequest,
+  GenerateResponse,
+  StreamChunk,
+} from '../types.js';
+
+/**
+ * モックプロバイダー設定
+ */
+export interface MockProviderConfig {
+  /** デフォルトレスポンス */
+  defaultResponse?: string;
+  /** 遅延（ミリ秒） */
+  delay?: number;
+  /** エラーを発生させるか */
+  shouldFail?: boolean;
+  /** エラーメッセージ */
+  errorMessage?: string;
+  /** カスタムレスポンス生成関数 */
+  responseGenerator?: (request: GenerateRequest) => string;
+}
+
+/**
+ * テスト用モックLLMプロバイダー
+ */
+export class MockLLMProvider implements LLMProvider {
+  readonly name = 'mock';
+  readonly supportedModels = ['mock-model', 'mock-model-v2'];
+
+  private config: MockProviderConfig;
+  private callCount = 0;
+  private callHistory: GenerateRequest[] = [];
+
+  constructor(config: MockProviderConfig = {}) {
+    this.config = {
+      defaultResponse: 'This is a mock response.',
+      delay: 0,
+      shouldFail: false,
+      ...config,
+    };
+  }
+
+  /**
+   * 呼び出し回数取得
+   */
+  getCallCount(): number {
+    return this.callCount;
+  }
+
+  /**
+   * 呼び出し履歴取得
+   */
+  getCallHistory(): GenerateRequest[] {
+    return [...this.callHistory];
+  }
+
+  /**
+   * リセット
+   */
+  reset(): void {
+    this.callCount = 0;
+    this.callHistory = [];
+  }
+
+  /**
+   * 設定更新
+   */
+  updateConfig(config: Partial<MockProviderConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  async generate(request: GenerateRequest): Promise<GenerateResponse> {
+    this.callCount++;
+    this.callHistory.push(request);
+
+    if (this.config.delay && this.config.delay > 0) {
+      await this.sleep(this.config.delay);
+    }
+
+    if (this.config.shouldFail) {
+      throw new Error(this.config.errorMessage ?? 'Mock provider error');
+    }
+
+    const content = this.config.responseGenerator
+      ? this.config.responseGenerator(request)
+      : this.config.defaultResponse ?? '';
+
+    return {
+      id: `mock-${Date.now()}-${this.callCount}`,
+      model: request.model ?? 'mock-model',
+      content,
+      usage: {
+        promptTokens: this.estimateTokens(request.messages.map((m) => 
+          typeof m.content === 'string' ? m.content : ''
+        ).join('')),
+        completionTokens: this.estimateTokens(content),
+        totalTokens: 0, // 後で計算
+      },
+      finishReason: 'stop',
+    };
+  }
+
+  async *generateStream(request: GenerateRequest): AsyncGenerator<StreamChunk> {
+    this.callCount++;
+    this.callHistory.push(request);
+
+    if (this.config.shouldFail) {
+      throw new Error(this.config.errorMessage ?? 'Mock provider error');
+    }
+
+    const content = this.config.responseGenerator
+      ? this.config.responseGenerator(request)
+      : this.config.defaultResponse ?? '';
+
+    // 文字ごとにストリーミング
+    const words = content.split(' ');
+    for (let i = 0; i < words.length; i++) {
+      if (this.config.delay && this.config.delay > 0) {
+        await this.sleep(this.config.delay / words.length);
+      }
+      yield { type: 'content', content: (i > 0 ? ' ' : '') + words[i] };
+    }
+
+    yield {
+      type: 'done',
+      usage: {
+        promptTokens: this.estimateTokens(request.messages.map((m) => 
+          typeof m.content === 'string' ? m.content : ''
+        ).join('')),
+        completionTokens: this.estimateTokens(content),
+        totalTokens: 0,
+      },
+    };
+  }
+
+  async generateStructured<T extends ZodType>(
+    request: GenerateRequest,
+    schema: T
+  ): Promise<z.infer<T>> {
+    this.callCount++;
+    this.callHistory.push(request);
+
+    if (this.config.shouldFail) {
+      throw new Error(this.config.errorMessage ?? 'Mock provider error');
+    }
+
+    // デフォルトの空オブジェクトを返す（実際のテストでは適切なデータを設定）
+    const defaultValue = {};
+    return schema.parse(defaultValue);
+  }
+
+  async countTokens(text: string, _model?: string): Promise<number> {
+    return this.estimateTokens(text);
+  }
+
+  private estimateTokens(text: string): number {
+    // 簡易トークン推定: 4文字 ≈ 1トークン
+    return Math.ceil(text.length / 4);
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}