@yarflam/potion-base-32m

Fast Model2Vec inference for minishlab/potion-base-32M embeddings without ONNX or heavy ML frameworks.

• ⚡ Lightning fast — Static embeddings with no neural network at runtime
• 📦 Zero heavy dependencies — No PyTorch, TensorFlow, or ONNX
• 🔧 Simple API — Just embed(texts) and go
• 🔍 Built-in semantic search — SemanticSearch class included
• 🪶 Tiny footprint — 32-dimensional embeddings, perfect for edge devices

Installation

npm install @yarflam/potion-base-32m

Usage

import { embed } from '@yarflam/potion-base-32m';

const texts = ['Hello world', 'How are you?'];
const embeddings = await embed(texts);

console.log(embeddings[0].length); // 32
console.log(embeddings[0]);        // Float32Array(32) [...]

How it works

Model2Vec uses static embeddings — no neural network needed at runtime:

1. Tokenize input using WordPiece tokenizer
2. Lookup each token's vector in the embedding matrix
3. Mean-pool all token vectors
4. L2-normalize the result

Done! No ML framework overhead.

API

embed(texts)

Embed one or more texts using potion-base-32M.

Parameters:

• texts (string | string[]) — Text(s) to embed

Returns:

• Promise<Float32Array[]> — Array of 32-dimensional embeddings

Example:

// Single text
const [embedding] = await embed('Hello world');

// Multiple texts
const embeddings = await embed(['Text one', 'Text two', 'Text three']);

cosineSimilarity(a, b)

Compute cosine similarity between two embeddings.

import { embed, cosineSimilarity } from '@yarflam/potion-base-32m';

const [emb1, emb2] = await embed(['cat', 'dog']);
const similarity = cosineSimilarity(emb1, emb2);
console.log(similarity); // 0.0 to 1.0

SemanticSearch

Built-in semantic search class for finding similar sentences.

import { SemanticSearch } from '@yarflam/potion-base-32m';

const search = new SemanticSearch();

// Index your documents
await search.index([
  'The cat sleeps on the couch',
  'The dog plays in the garden',
  'A bird sings in the tree'
]);

// Search
const results = await search.search('feline resting', { nb_results: 2 });
// [{ sentence: 'The cat sleeps on the couch', score: 0.85 }, ...]

Methods:

• index(sentences: string[]): Promise<SemanticSearch> — Index sentences for search
• search(query: string, options?): Promise<Array<{sentence, score}>> — Search indexed sentences
  • options.nb_results — Maximum results (default: 10)
  • options.threshold — Minimum similarity score 0-1 (default: null)
• clear(): void — Clear the index
• size: number — Number of indexed sentences (getter)

Model files

The package downloads model files from HuggingFace Hub during installation:

• model.safetensors — Embedding matrix [vocab_size, 32]
• tokenizer.json — WordPiece tokenizer
• config.json — Model metadata

Files are cached in the models/ directory and included in the published package.

Development

# Install dependencies
npm install

# Download model files
npm run download-models

# Run tests
npm test

GitLab CI Setup

To enable NPM publishing in GitLab CI:

1. Add your NPM token as a CI/CD variable:

   • Go to Settings > CI/CD > Variables
   • Add NPM_TOKEN with your npm access token

2. Create a tag to trigger publish:

   git tag v1.0.0
   git push origin v1.0.0

Or manually trigger from the main branch using the publish-main job.

Model Credit

This package uses minishlab/potion-base-32M by Minish Lab.

Model2Vec paper: arXiv:2411.01001

Authors

• Yarflam — Creator & maintainer
• Mira 🤫 — Assistant & co-conspirator

License

MIT