mdcontext 0.0.1 → 0.2.0

package/src/embeddings/provider-factory.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Provider Factory Unit Tests
+ *
+ * Tests for the embedding provider factory module ensuring correct
+ * provider creation with appropriate baseURL mapping.
+ */
+
+import { Effect, Option, Redacted } from 'effect'
+import { describe, expect, it } from 'vitest'
+import {
+  createEmbeddingProviderDirect,
+  getProviderBaseURL,
+  PROVIDER_BASE_URLS,
+} from './provider-factory.js'
+
+describe('Provider Factory', () => {
+  describe('PROVIDER_BASE_URLS constant', () => {
+    it('should have undefined for openai (uses SDK default)', () => {
+      expect(PROVIDER_BASE_URLS.openai).toBeUndefined()
+    })
+
+    it('should have correct URL for ollama', () => {
+      expect(PROVIDER_BASE_URLS.ollama).toBe('http://localhost:11434/v1')
+    })
+
+    it('should have correct URL for lm-studio', () => {
+      expect(PROVIDER_BASE_URLS['lm-studio']).toBe('http://localhost:1234/v1')
+    })
+
+    it('should have correct URL for openrouter', () => {
+      expect(PROVIDER_BASE_URLS.openrouter).toBe('https://openrouter.ai/api/v1')
+    })
+
+    it('should have all five providers defined', () => {
+      const providers = Object.keys(PROVIDER_BASE_URLS)
+      expect(providers).toHaveLength(5)
+      expect(providers).toContain('openai')
+      expect(providers).toContain('ollama')
+      expect(providers).toContain('lm-studio')
+      expect(providers).toContain('openrouter')
+      expect(providers).toContain('voyage')
+    })
+  })
+
+  describe('getProviderBaseURL', () => {
+    it('should return config baseURL when Option.some is provided', () => {
+      const customURL = 'https://custom.api.com/v1'
+      const result = getProviderBaseURL('openai', Option.some(customURL))
+      expect(result).toBe(customURL)
+    })
+
+    it('should return config baseURL over provider default', () => {
+      const customURL = 'https://custom-ollama.example.com/v1'
+      const result = getProviderBaseURL('ollama', Option.some(customURL))
+      expect(result).toBe(customURL)
+    })
+
+    it('should return provider default when Option.none for ollama', () => {
+      const result = getProviderBaseURL('ollama', Option.none())
+      expect(result).toBe('http://localhost:11434/v1')
+    })
+
+    it('should return provider default when Option.none for lm-studio', () => {
+      const result = getProviderBaseURL('lm-studio', Option.none())
+      expect(result).toBe('http://localhost:1234/v1')
+    })
+
+    it('should return provider default when Option.none for openrouter', () => {
+      const result = getProviderBaseURL('openrouter', Option.none())
+      expect(result).toBe('https://openrouter.ai/api/v1')
+    })
+
+    it('should return undefined for openai when Option.none', () => {
+      const result = getProviderBaseURL('openai', Option.none())
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('createEmbeddingProviderDirect', () => {
+    it('should create provider with ollama default baseURL', async () => {
+      const program = createEmbeddingProviderDirect({
+        provider: 'ollama',
+        apiKey: 'test-key',
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider.name).toContain('ollama')
+    })
+
+    it('should create provider with lm-studio default baseURL', async () => {
+      const program = createEmbeddingProviderDirect({
+        provider: 'lm-studio',
+        apiKey: 'test-key',
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider.name).toContain('lm-studio')
+    })
+
+    it('should create provider with openrouter default baseURL', async () => {
+      const program = createEmbeddingProviderDirect({
+        provider: 'openrouter',
+        apiKey: 'test-key',
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider.name).toContain('openrouter')
+    })
+
+    it('should create openai provider with SDK default (no baseURL)', async () => {
+      const program = createEmbeddingProviderDirect({
+        provider: 'openai',
+        apiKey: 'test-key',
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider.name).toContain('openai')
+    })
+
+    it('should respect custom baseURL override for any provider', async () => {
+      const customURL = 'https://my-proxy.example.com/v1'
+      const program = createEmbeddingProviderDirect({
+        provider: 'openai',
+        baseURL: customURL,
+        apiKey: 'test-key',
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider).toBeDefined()
+    })
+
+    it('should accept baseURL as Option.some', async () => {
+      const customURL = 'https://custom.api.com/v1'
+      const program = createEmbeddingProviderDirect({
+        provider: 'openai',
+        baseURL: Option.some(customURL),
+        apiKey: 'test-key',
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider).toBeDefined()
+    })
+
+    it('should use provider default when baseURL is Option.none', async () => {
+      const program = createEmbeddingProviderDirect({
+        provider: 'ollama',
+        baseURL: Option.none(),
+        apiKey: 'test-key',
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider.name).toContain('ollama')
+    })
+
+    it('should pass custom model to provider', async () => {
+      const program = createEmbeddingProviderDirect({
+        provider: 'openai',
+        model: 'text-embedding-3-large',
+        apiKey: 'test-key',
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider.name).toContain('text-embedding-3-large')
+    })
+
+    it('should accept apiKey as Option.some', async () => {
+      const program = createEmbeddingProviderDirect({
+        provider: 'openai',
+        apiKey: Option.some('test-key'),
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider).toBeDefined()
+    })
+
+    it('should fail when no API key provided', async () => {
+      const originalEnv = process.env.OPENAI_API_KEY
+      delete process.env.OPENAI_API_KEY
+
+      try {
+        const program = createEmbeddingProviderDirect({
+          provider: 'openai',
+        })
+
+        await expect(Effect.runPromise(program)).rejects.toThrow()
+      } finally {
+        if (originalEnv) {
+          process.env.OPENAI_API_KEY = originalEnv
+        }
+      }
+    })
+
+    it('should fail when apiKey is Option.none and no env var', async () => {
+      const originalEnv = process.env.OPENAI_API_KEY
+      delete process.env.OPENAI_API_KEY
+
+      try {
+        const program = createEmbeddingProviderDirect({
+          provider: 'openai',
+          apiKey: Option.none(),
+        })
+
+        await expect(Effect.runPromise(program)).rejects.toThrow()
+      } finally {
+        if (originalEnv) {
+          process.env.OPENAI_API_KEY = originalEnv
+        }
+      }
+    })
+
+    it('should accept apiKey as Redacted<string>', async () => {
+      const redactedKey = Redacted.make('test-redacted-key')
+      const program = createEmbeddingProviderDirect({
+        provider: 'openai',
+        apiKey: redactedKey,
+      })
+
+      const provider = await Effect.runPromise(program)
+      expect(provider).toBeDefined()
+      expect(provider.name).toContain('openai')
+    })
+
+    it('should not expose Redacted API key when stringified', () => {
+      const redactedKey = Redacted.make('sk-secret-key-12345')
+      const stringified = String(redactedKey)
+
+      // Redacted type shows <redacted> when stringified
+      expect(stringified).not.toContain('sk-secret-key-12345')
+      expect(stringified).toContain('<redacted>')
+    })
+
+    it('should preserve API key value in Redacted wrapper', () => {
+      const secretKey = 'sk-secret-key-12345'
+      const redactedKey = Redacted.make(secretKey)
+
+      // Value can still be extracted when needed
+      expect(Redacted.value(redactedKey)).toBe(secretKey)
+    })
+  })
+})

package/src/embeddings/provider-factory.ts

@@ -0,0 +1,225 @@
+/**
+ * Embedding Provider Factory
+ *
+ * Creates embedding providers based on configuration. Supports multiple
+ * providers (OpenAI, Ollama, LM Studio, OpenRouter) with automatic
+ * baseURL mapping for OpenAI-compatible APIs.
+ */
+
+import { Effect, Option, Redacted } from 'effect'
+import { ConfigService, type EmbeddingProvider } from '../config/index.js'
+import type { EmbeddingsConfig } from '../config/schema.js'
+import type { ApiKeyMissingError } from '../errors/index.js'
+import { createOpenAIProvider } from './openai-provider.js'
+import { PROVIDER_BASE_URLS } from './provider-constants.js'
+import type { EmbeddingProvider as EmbeddingProviderInterface } from './types.js'
+import { createVoyageProvider } from './voyage-provider.js'
+
+// Re-export provider constants for backward compatibility
+export { PROVIDER_BASE_URLS } from './provider-constants.js'
+
+/**
+ * Get the base URL for a provider, respecting config override.
+ *
+ * Precedence:
+ * 1. Explicit baseURL from config (highest priority)
+ * 2. Provider-specific default from PROVIDER_BASE_URLS
+ * 3. OpenAI SDK default (undefined means use SDK default)
+ */
+export const getProviderBaseURL = (
+  provider: EmbeddingProvider,
+  configBaseURL: Option.Option<string>,
+): string | undefined => {
+  // Config baseURL takes precedence
+  if (Option.isSome(configBaseURL)) {
+    return configBaseURL.value
+  }
+  // Fall back to provider default
+  return PROVIDER_BASE_URLS[provider]
+}
+
+// ============================================================================
+// Provider Factory
+// ============================================================================
+
+/**
+ * Configuration subset needed for provider creation.
+ * Extracted from EmbeddingsConfig to allow direct config passing.
+ */
+export interface ProviderFactoryConfig {
+  readonly provider: EmbeddingProvider
+  readonly baseURL?: Option.Option<string> | string | undefined
+  readonly model?: string | undefined
+  readonly dimensions?: number | undefined
+  readonly batchSize?: number | undefined
+  /**
+   * API key for the provider. Accepts multiple formats:
+   * - Plain string: 'sk-...'
+   * - Redacted<string>: Redacted.make('sk-...') (recommended for security)
+   * - Option<string>: Option.some('sk-...')
+   */
+  readonly apiKey?:
+    | Option.Option<string>
+    | string
+    | Redacted.Redacted<string>
+    | undefined
+  /**
+   * Request timeout in milliseconds.
+   * Default: 30000 (30 seconds)
+   */
+  readonly timeout?: number | undefined
+}
+
+/**
+ * Normalize baseURL from various input formats to Option<string>.
+ */
+const normalizeBaseURL = (
+  baseURL: Option.Option<string> | string | undefined,
+): Option.Option<string> => {
+  if (baseURL === undefined) {
+    return Option.none()
+  }
+  if (typeof baseURL === 'string') {
+    return Option.some(baseURL)
+  }
+  return baseURL
+}
+
+/**
+ * Normalize apiKey from various input formats to string | Redacted<string> | undefined.
+ * Preserves Redacted wrapper for security - don't unwrap until needed.
+ */
+const normalizeApiKey = (
+  apiKey:
+    | Option.Option<string>
+    | string
+    | Redacted.Redacted<string>
+    | undefined,
+): string | Redacted.Redacted<string> | undefined => {
+  if (apiKey === undefined) {
+    return undefined
+  }
+  // Check for Redacted first (keep wrapped for security)
+  if (Redacted.isRedacted(apiKey)) {
+    return apiKey
+  }
+  if (typeof apiKey === 'string') {
+    return apiKey
+  }
+  // Handle Option<string>
+  return Option.isSome(apiKey) ? apiKey.value : undefined
+}
+
+/**
+ * Create an embedding provider based on configuration.
+ *
+ * All supported providers (OpenAI, Ollama, LM Studio, OpenRouter) use
+ * OpenAI-compatible APIs, so we use the OpenAI provider with different
+ * base URLs.
+ *
+ * @param config - Optional explicit config (if not provided, reads from ConfigService)
+ * @returns Effect yielding the configured EmbeddingProvider
+ *
+ * @example
+ * ```typescript
+ * // Using ConfigService (reads from environment/config file)
+ * const provider = yield* createEmbeddingProvider()
+ *
+ * // Explicit config override
+ * const provider = yield* createEmbeddingProvider({
+ *   provider: 'ollama',
+ *   model: 'nomic-embed-text',
+ * })
+ * ```
+ */
+export const createEmbeddingProvider = (
+  config?: ProviderFactoryConfig,
+): Effect.Effect<
+  EmbeddingProviderInterface,
+  ApiKeyMissingError,
+  ConfigService
+> =>
+  Effect.gen(function* () {
+    // Get embeddings config from service if not provided
+    const embeddingsConfig: EmbeddingsConfig = config
+      ? ({
+          provider: config.provider,
+          baseURL: normalizeBaseURL(config.baseURL),
+          model: config.model ?? 'text-embedding-3-small',
+          dimensions: config.dimensions, // Let provider determine default if not specified
+          batchSize: config.batchSize ?? 100,
+          maxRetries: 3,
+          retryDelayMs: 1000,
+          timeoutMs: 30000,
+          apiKey: Option.fromNullable(normalizeApiKey(config.apiKey)),
+        } as EmbeddingsConfig)
+      : (yield* ConfigService).embeddings
+
+    const provider = embeddingsConfig.provider
+    const baseURL = getProviderBaseURL(provider, embeddingsConfig.baseURL)
+
+    // Extract API key from config if available
+    const apiKey = Option.isSome(embeddingsConfig.apiKey)
+      ? embeddingsConfig.apiKey.value
+      : undefined
+
+    // Voyage AI uses its own native API, not OpenAI-compatible
+    if (provider === 'voyage') {
+      return yield* createVoyageProvider({
+        model: embeddingsConfig.model,
+        batchSize: embeddingsConfig.batchSize,
+        apiKey,
+        timeout: embeddingsConfig.timeoutMs,
+      })
+    }
+
+    // All other providers use OpenAI-compatible API
+    return yield* createOpenAIProvider({
+      model: embeddingsConfig.model,
+      dimensions: embeddingsConfig.dimensions,
+      batchSize: embeddingsConfig.batchSize,
+      baseURL,
+      apiKey,
+      timeout: embeddingsConfig.timeoutMs,
+    })
+  })
+
+/**
+ * Create an embedding provider without ConfigService dependency.
+ *
+ * Use this when you need to create a provider outside of the Effect
+ * context or when you have explicit config values.
+ *
+ * @param config - Explicit provider configuration
+ * @returns Effect yielding the configured EmbeddingProvider
+ */
+export const createEmbeddingProviderDirect = (
+  config: ProviderFactoryConfig,
+): Effect.Effect<EmbeddingProviderInterface, ApiKeyMissingError> =>
+  Effect.gen(function* () {
+    const provider = config.provider
+    const baseURL = getProviderBaseURL(
+      provider,
+      normalizeBaseURL(config.baseURL),
+    )
+
+    // Voyage AI uses its own native API, not OpenAI-compatible
+    if (provider === 'voyage') {
+      return yield* createVoyageProvider({
+        model: config.model,
+        batchSize: config.batchSize,
+        apiKey: normalizeApiKey(config.apiKey),
+        timeout: config.timeout,
+      })
+    }
+
+    // All other providers use OpenAI-compatible API
+    return yield* createOpenAIProvider({
+      model: config.model,
+      dimensions: config.dimensions,
+      batchSize: config.batchSize,
+      baseURL,
+      apiKey: normalizeApiKey(config.apiKey),
+      timeout: config.timeout,
+    })
+  })