CtrlK
BlogDocsLog inGet started
Tessl Logo

embeddings

Vector embeddings configuration and semantic search

40

Quality

40%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./src/skills/bundled/embeddings/SKILL.md
SKILL.md
Quality
Evals
Security

Embeddings - Complete API Reference

Configure embedding providers, manage vector storage, and perform semantic search.

Chat Commands

View Config

/embeddings                                 Show current settings
/embeddings status                          Provider status
/embeddings stats                           Cache statistics

Configure Provider

/embeddings provider openai                 Use OpenAI embeddings
/embeddings provider voyage                 Use Voyage AI
/embeddings provider local                  Use local model
/embeddings model text-embedding-3-small    Set model

Cache Management

/embeddings cache stats                     View cache stats
/embeddings cache clear                     Clear cache
/embeddings cache size                      Total cache size

Testing

/embeddings test "sample text"              Generate test embedding
/embeddings similarity "text1" "text2"      Compare similarity

TypeScript API Reference

Create Embeddings Service

import { createEmbeddingsService } from 'clodds/embeddings';

const embeddings = createEmbeddingsService({
  // Provider
  provider: 'openai',  // 'openai' | 'voyage' | 'local' | 'cohere'
  apiKey: process.env.OPENAI_API_KEY,

  // Model
  model: 'text-embedding-3-small',
  dimensions: 1536,

  // Caching
  cache: true,
  cacheBackend: 'sqlite',
  cachePath: './embeddings-cache.db',

  // Batching
  batchSize: 100,
  maxConcurrent: 5,
});

Generate Embeddings

// Single text
const embedding = await embeddings.embed('Hello world');
console.log(`Dimensions: ${embedding.length}`);

// Multiple texts (batched)
const vectors = await embeddings.embedBatch([
  'First document',
  'Second document',
  'Third document',
]);

Semantic Search

// Search against stored vectors
const results = await embeddings.search({
  query: 'trading strategies',
  collection: 'documents',
  limit: 10,
  threshold: 0.7,
});

for (const result of results) {
  console.log(`${result.text} (score: ${result.score})`);
}

Similarity

// Compare two texts
const score = await embeddings.similarity(
  'The cat sat on the mat',
  'A feline rested on the rug'
);

console.log(`Similarity: ${score}`);  // 0.0 - 1.0

Store Vectors

// Store embedding with metadata
await embeddings.store({
  collection: 'documents',
  id: 'doc-1',
  text: 'Original text',
  embedding: vector,
  metadata: {
    source: 'wiki',
    date: '2024-01-01',
  },
});

// Store batch
await embeddings.storeBatch({
  collection: 'documents',
  items: [
    { id: 'doc-1', text: 'First doc' },
    { id: 'doc-2', text: 'Second doc' },
  ],
});

Cache Management

// Get cache stats
const stats = await embeddings.getCacheStats();
console.log(`Cached: ${stats.count} embeddings`);
console.log(`Size: ${stats.sizeMB} MB`);
console.log(`Hit rate: ${stats.hitRate}%`);

// Clear cache
await embeddings.clearCache();

// Clear specific entries
await embeddings.clearCache({ olderThan: '7d' });

Provider Configuration

// Switch provider
embeddings.setProvider('voyage', {
  apiKey: process.env.VOYAGE_API_KEY,
  model: 'voyage-large-2',
});

// Use local model (Transformers.js)
// No API key required - runs locally via @xenova/transformers
embeddings.setProvider('local', {
  model: 'Xenova/all-MiniLM-L6-v2',  // 384 dimensions
});

Providers

ProviderModelsQualitySpeedCost
OpenAItext-embedding-3-small/largeExcellentFast$0.02/1M
Voyagevoyage-large-2ExcellentFast$0.02/1M
Cohereembed-english-v3GoodFast$0.10/1M
Local (Transformers.js)Xenova/all-MiniLM-L6-v2GoodMediumFree

Models

OpenAI

ModelDimensionsBest For
text-embedding-3-small1536General use
text-embedding-3-large3072High accuracy

Voyage

ModelDimensionsBest For
voyage-large-21024General use
voyage-code-21536Code search

Use Cases

Semantic Memory Search

// Store user memories
await embeddings.store({
  collection: 'memories',
  id: 'mem-1',
  text: 'User prefers conservative trading',
});

// Search memories
const relevant = await embeddings.search({
  query: 'what is user risk preference',
  collection: 'memories',
  limit: 5,
});

Document Similarity

// Find similar documents
const similar = await embeddings.findSimilar({
  text: 'How to trade options',
  collection: 'docs',
  limit: 5,
});

Best Practices

  1. Use caching — Avoid redundant API calls
  2. Batch requests — More efficient than single calls
  3. Choose dimensions wisely — Balance quality vs storage
  4. Monitor costs — Embeddings can add up
  5. Local for development — Use local model to save costs
Repository
alsk1992/CloddsBot
Path

src/skills/bundled/embeddings/SKILL.md

Commit

e71a5f6

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill