Skip to content

Legacy library

This page describes the old TypeScript @sylphx/coderag library. It is not the Locus MCP server. The live server is local Rust BM25 in @sylphx/locus. Start at the quickstart.

Embedding Providers ​

Locus supports multiple embedding providers for semantic vector search. Providers use the Vercel AI SDK with OpenAI-compatible APIs.

createEmbeddingProvider() ​

Factory function to create embedding providers.

typescript
function createEmbeddingProvider(config: EmbeddingConfig): EmbeddingProvider

Parameters ​

config EmbeddingConfig

typescript
interface EmbeddingConfig {
  provider: 'openai' | 'openai-compatible' | 'mock'
  model: string              // Model name
  dimensions: number         // Vector dimensions
  apiKey?: string           // API key (or use OPENAI_API_KEY env var)
  baseURL?: string          // Custom endpoint for OpenAI-compatible APIs
  batchSize?: number        // Embedding batch size (default: 10)
}

Returns ​

EmbeddingProvider instance

typescript
interface EmbeddingProvider {
  name: string
  model: string
  dimensions: number
  generateEmbedding(text: string): Promise<number[]>
  generateEmbeddings(texts: string[]): Promise<number[][]>
}

Example ​

typescript
import { createEmbeddingProvider } from '@sylphx/coderag'

const provider = createEmbeddingProvider({
  provider: 'openai',
  model: 'text-embedding-3-small',
  dimensions: 1536,
  apiKey: process.env.OPENAI_API_KEY
})

// Generate single embedding
const embedding = await provider.generateEmbedding('function hello() {}')
console.log(embedding.length)  // 1536

// Generate batch
const embeddings = await provider.generateEmbeddings([
  'function a() {}',
  'class B {}'
])
console.log(embeddings.length)  // 2

OpenAI Provider ​

Uses OpenAI's embedding models.

Supported Models ​

text-embedding-3-small (recommended)

  • Dimensions: 1536
  • Performance: Fast
  • Cost: Low
  • Quality: Good for code

text-embedding-3-large

  • Dimensions: 3072
  • Performance: Slower
  • Cost: Higher
  • Quality: Better semantic understanding

text-embedding-ada-002 (legacy)

  • Dimensions: 1536
  • Performance: Fast
  • Cost: Low
  • Quality: Good

Example ​

typescript
const provider = createEmbeddingProvider({
  provider: 'openai',
  model: 'text-embedding-3-small',
  dimensions: 1536,
  apiKey: process.env.OPENAI_API_KEY
})

Environment Variables ​

bash
OPENAI_API_KEY=sk-...
EMBEDDING_MODEL=text-embedding-3-small  # Optional
EMBEDDING_DIMENSIONS=1536               # Optional

OpenAI-Compatible Provider ​

Use OpenAI-compatible endpoints (OpenRouter, Together AI, etc.).

Example ​

typescript
// OpenRouter
const provider = createEmbeddingProvider({
  provider: 'openai-compatible',
  model: 'openai/text-embedding-3-small',
  dimensions: 1536,
  apiKey: process.env.OPENROUTER_API_KEY,
  baseURL: 'https://openrouter.ai/api/v1'
})

// Together AI
const provider = createEmbeddingProvider({
  provider: 'openai-compatible',
  model: 'togethercomputer/m2-bert-80M-8k-retrieval',
  dimensions: 768,
  apiKey: process.env.TOGETHER_API_KEY,
  baseURL: 'https://api.together.xyz/v1'
})

Environment Variables ​

bash
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://custom-endpoint/v1
EMBEDDING_MODEL=custom-model-name
EMBEDDING_DIMENSIONS=768

Mock Provider ​

Deterministic hash-based embeddings for testing (no API calls).

Example ​

typescript
const provider = createEmbeddingProvider({
  provider: 'mock',
  model: 'mock',
  dimensions: 1536
})

// Or use createMockProvider() directly
import { createMockProvider } from '@sylphx/coderag'

const provider = createMockProvider(1536)

Use Cases ​

  • Testing without API costs
  • Offline development
  • CI/CD pipelines
  • Fallback when API unavailable

Default Provider ​

Get provider from environment variables.

typescript
import { getDefaultEmbeddingProvider } from '@sylphx/coderag'

const provider = await getDefaultEmbeddingProvider()
// Detects from OPENAI_API_KEY and OPENAI_BASE_URL

Detection Logic ​

  1. If OPENAI_BASE_URL set: openai-compatible
  2. If OPENAI_API_KEY set: openai
  3. Otherwise: mock

Custom Providers ​

Register custom embedding providers.

typescript
import { registerProvider } from '@sylphx/coderag'

registerProvider('huggingface', (config) => ({
  name: 'huggingface',
  model: config.model,
  dimensions: config.dimensions,
  generateEmbedding: async (text) => {
    // Your implementation
    const response = await fetch('https://api-inference.huggingface.co/...', {
      method: 'POST',
      headers: { Authorization: `Bearer ${config.apiKey}` },
      body: JSON.stringify({ inputs: text })
    })
    const data = await response.json()
    return data.embeddings
  },
  generateEmbeddings: async (texts) => {
    // Batch implementation
    return Promise.all(texts.map(text => this.generateEmbedding(text)))
  }
}))

// Use custom provider
const provider = createEmbeddingProvider({
  provider: 'huggingface',
  model: 'sentence-transformers/all-MiniLM-L6-v2',
  dimensions: 384,
  apiKey: process.env.HF_API_KEY
})

Provider Composition ​

Combine providers for fallback behavior.

typescript
import { composeProviders, createOpenAIProvider, createMockProvider } from '@sylphx/coderag'

const primary = createOpenAIProvider({
  provider: 'openai',
  model: 'text-embedding-3-small',
  dimensions: 1536,
  apiKey: process.env.OPENAI_API_KEY
})

const fallback = createMockProvider(1536)

const composed = composeProviders(primary, fallback)
// Uses primary, falls back to mock if primary fails

Utility Functions ​

generateMockEmbedding() ​

Generate deterministic mock embedding.

typescript
import { generateMockEmbedding } from '@sylphx/coderag'

const embedding = generateMockEmbedding('hello world', 1536)
// Always returns same vector for same input

cosineSimilarity() ​

Calculate similarity between two vectors.

typescript
import { cosineSimilarity } from '@sylphx/coderag'

const similarity = cosineSimilarity(embedding1, embedding2)
// Returns: -1 to 1 (1 = identical, 0 = orthogonal, -1 = opposite)

normalizeVector() ​

Normalize vector to unit length.

typescript
import { normalizeVector } from '@sylphx/coderag'

const normalized = normalizeVector([3, 4])
// Returns: [0.6, 0.8] (magnitude = 1)

chunkText() ​

Split text into chunks for embedding.

typescript
import { chunkText } from '@sylphx/coderag'

const chunks = chunkText(longText, {
  maxChunkSize: 1000,
  overlap: 100
})

Usage with CodebaseIndexer ​

typescript
import { CodebaseIndexer, createEmbeddingProvider, PersistentStorage } from '@sylphx/coderag'

const embeddingProvider = createEmbeddingProvider({
  provider: 'openai',
  model: 'text-embedding-3-small',
  dimensions: 1536,
  apiKey: process.env.OPENAI_API_KEY
})

const indexer = new CodebaseIndexer({
  codebaseRoot: './src',
  storage: new PersistentStorage(),
  embeddingProvider,
  vectorBatchSize: 20  // Generate 20 embeddings at once
})

await indexer.index()
// Generates embeddings for each code chunk

Performance ​

Batch Size ​

Control API request size:

typescript
const provider = createEmbeddingProvider({
  provider: 'openai',
  model: 'text-embedding-3-small',
  dimensions: 1536,
  batchSize: 10  // Default
})

// Larger batches = fewer API calls but higher latency
const indexer = new CodebaseIndexer({
  embeddingProvider: provider,
  vectorBatchSize: 50  // 50 chunks per batch
})

Speed Comparison ​

Model speeds (approximate):

  • text-embedding-3-small: ~1000 tokens/sec
  • text-embedding-3-large: ~500 tokens/sec
  • text-embedding-ada-002: ~1000 tokens/sec

Indexing 1000 code chunks (~500 tokens each):

  • Small model: ~250 seconds (50 batches of 20)
  • Large model: ~500 seconds
  • Mock provider: ~1 second (no API calls)

Cost Estimation ​

OpenAI pricing (as of 2024):

  • text-embedding-3-small: $0.02 / 1M tokens
  • text-embedding-3-large: $0.13 / 1M tokens
  • text-embedding-ada-002: $0.10 / 1M tokens

Example: 10,000 code chunks, 500 tokens each = 5M tokens

  • Small: $0.10
  • Large: $0.65
  • Ada-002: $0.50

Error Handling ​

Automatic Fallback ​

Provider automatically falls back to mock on error:

typescript
const provider = createEmbeddingProvider({
  provider: 'openai',
  model: 'text-embedding-3-small',
  dimensions: 1536,
  apiKey: 'invalid-key'
})

const embedding = await provider.generateEmbedding('test')
// Logs: [WARN] OpenAI embedding failed, falling back to mock
// Returns: Mock embedding (deterministic hash)

Manual Error Handling ​

typescript
try {
  const embedding = await provider.generateEmbedding(text)
} catch (error) {
  console.error('Embedding generation failed:', error)
  // Handle error
}

Best Practices ​

Use environment variables:

typescript
// Good
const provider = createEmbeddingProvider({
  provider: 'openai',
  model: 'text-embedding-3-small',
  dimensions: 1536,
  apiKey: process.env.OPENAI_API_KEY  // From env
})

// Avoid
const provider = createEmbeddingProvider({
  apiKey: 'sk-hardcoded-key'  // Security risk
})

Batch when possible:

typescript
// Good: Single API call
const embeddings = await provider.generateEmbeddings(texts)

// Avoid: Multiple API calls
const embeddings = await Promise.all(
  texts.map(text => provider.generateEmbedding(text))
)

Choose appropriate dimensions:

typescript
// For code search: 1536 is sufficient
const provider = createEmbeddingProvider({
  model: 'text-embedding-3-small',
  dimensions: 1536
})

// For semantic understanding: 3072 is better
const provider = createEmbeddingProvider({
  model: 'text-embedding-3-large',
  dimensions: 3072
})

Released under the MIT License.