@molecule/api-ai-embeddings-molecule

molecule.dev hosted embeddings provider for @molecule/api-ai-embeddings.

Embeddings run on molecule.dev and are billed to your molecule project, so the app needs no OpenAI account. It is an ordinary bond: swap it for @molecule/api-ai-embeddings-openai (your own key) or @molecule/api-ai-embeddings-local (self-hosted) without changing code that calls the core.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider, requireProvider } from '@molecule/api-ai-embeddings'
import { provider } from '@molecule/api-ai-embeddings-molecule'

setProvider(provider) // reads MOLECULE_API_KEY from the environment

const { embeddings, usage } = await requireProvider().embed({
  input: ['first document', 'second document'],
})
const queryVector = await requireProvider().embedQuery('what is molecule?')

Type

provider

Installation

npm install @molecule/api-ai-embeddings-molecule @molecule/api-ai-embeddings @molecule/api-secrets

API

Interfaces

MoleculeEmbeddingsConfig

Options for createProvider. Every field falls back to an env var, so the zero-argument provider export works from .env alone.

interface MoleculeEmbeddingsConfig {
  /**
   * The molecule project API key (`mk_…`), or the sandbox token molecule.dev
   * writes for in-IDE apps (`mbk_…`). Defaults to `MOLECULE_API_KEY`.
   */
  apiKey?: string
  /**
   * The hosted services base URL, without a trailing slash. Defaults to
   * `MOLECULE_SERVICES_URL`, then `https://api.molecule.dev/api/v1/services`.
   */
  servicesUrl?: string
  /** Default model: `text-embedding-3-small` (default) or `text-embedding-3-large`. */
  defaultModel?: string
  /** Default output dimensions (1–3072). Omit for the model's native size. */
  dimensions?: number
  /** Per-request timeout in milliseconds. Default 60000. */
  timeoutMs?: number
}

ProcessEnv

Environment variables this provider reads.

interface ProcessEnv {
  MOLECULE_API_KEY?: string
  MOLECULE_SERVICES_URL?: string
}

Classes

MoleculeServiceError

Error thrown for a refused or failed hosted-service call.

class MoleculeServiceError extends Error {
  /** HTTP status from molecule.dev. */
  readonly status: number
  /** Stable error key from molecule.dev, e.g. `broker.error.budgetExceeded`. */
  readonly errorKey: string | undefined

  /**
   * Create the error.
   *
   * @param message - Human-readable message.
   * @param status - HTTP status.
   * @param errorKey - Stable error key, when the service sent one.
   * @param cause - The underlying error, if any.
   */
  constructor(message: string, status: number, errorKey?: string, cause?: unknown) {
    super(message, cause === undefined ? undefined : { cause })
    this.name = 'MoleculeServiceError'
    this.status = status
    this.errorKey = errorKey
  }
}

MoleculeEmbeddingsProvider

Embeddings through molecule.dev's hosted service.

class MoleculeEmbeddingsProvider implements AIEmbeddingsProvider {
  readonly name = 'molecule'

  private readonly apiKey: string
  private readonly servicesUrl: string
  private readonly defaultModel: string
  private readonly defaultDimensions: number | undefined
  private readonly timeoutMs: number

  /**
   * Create the provider.
   *
   * @param config - Options; each falls back to its env var.
   */
  constructor(config: MoleculeEmbeddingsConfig = {}) {
    this.apiKey = config.apiKey ?? process.env.MOLECULE_API_KEY ?? ''
    this.servicesUrl = resolveServicesUrl(
      config.servicesUrl ?? process.env.MOLECULE_SERVICES_URL ?? DEFAULT_SERVICES_URL,
    )
    this.defaultModel = config.defaultModel ?? 'text-embedding-3-small'
    this.defaultDimensions = config.dimensions
    this.timeoutMs = config.timeoutMs ?? 60_000
  }

  /**
   * Embed one or more texts. Inputs beyond one request's limits are sent as
   * several requests, in order, and their usage is summed.
   *
   * @param params - Input text(s), model and dimensions.
   * @returns Vectors in input order, the model that served them, and usage.
   */
  async embed(params: EmbedParams): Promise<EmbeddingResult> {
    if (!this.apiKey) {
      throw new MoleculeServiceError(
        'MOLECULE_API_KEY is not set. Create a project API key on molecule.dev (or with `mlcl apikey create`) and put it in the API .env.',
        401,
        'hostedServices.error.tokenInvalid',
      )
    }
    const inputs = typeof params.input === 'string' ? [params.input] : params.input
    if (inputs.length === 0)
      return {
        embeddings: [],
        model: params.model ?? this.defaultModel,
        usage: { promptTokens: 0, totalTokens: 0 },
      }

    const model = params.model ?? this.defaultModel
    const dimensions = params.dimensions ?? this.defaultDimensions
    const result: EmbeddingResult = {
      embeddings: [],
      model,
      usage: { promptTokens: 0, totalTokens: 0 },
    }
    for (const batch of batchInputs(inputs)) {
      const part = await this.request({
        input: batch,
        model,
        ...(dimensions ? { dimensions } : {}),
      })
      result.embeddings.push(...part.embeddings)
      result.model = part.model
      result.usage.promptTokens += part.usage.promptTokens
      result.usage.totalTokens += part.usage.totalTokens
    }
    return result
  }

  /**
   * Embed a single query string.
   *
   * @param text - The query.
   * @returns Its vector.
   */
  async embedQuery(text: string): Promise<number[]> {
    const { embeddings } = await this.embed({ input: text })
    return embeddings[0]
  }

  /**
   * Embed many documents.
   *
   * @param texts - The documents.
   * @returns One vector per document, in order.
   */
  async embedDocuments(texts: string[]): Promise<number[][]> {
    const { embeddings } = await this.embed({ input: texts })
    return embeddings
  }

  /** One POST to the hosted service. */
  private async request(body: EmbedParams): Promise<EmbeddingResult> {
    const response = await fetch(`${this.servicesUrl}/embeddings/embed`, {
      method: 'POST',
      headers: { authorization: `Bearer ${this.apiKey}`, 'content-type': 'application/json' },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(this.timeoutMs),
    })
    const text = await response.text()
    let data: unknown
    try {
      data = text ? JSON.parse(text) : {}
    } catch (error) {
      // A proxy/gateway error page, not the service: report the status only.
      throw new MoleculeServiceError(
        `molecule.dev returned ${response.status} with a non-JSON body.`,
        response.status,
        undefined,
        error,
      )
    }
    if (!response.ok) {
      const err = data as { error?: string; errorKey?: string }
      const hint = HINTS[response.status]
      throw new MoleculeServiceError(
        `molecule.dev embeddings failed (${response.status}): ${err.error ?? 'error'}${hint ? ` ${hint}` : ''}`,
        response.status,
        err.errorKey,
      )
    }
    return data as EmbeddingResult
  }
}

Functions

batchInputs(inputs)

Split inputs into batches that each fit the service's per-request limits.

function batchInputs(inputs: string[]): string[][]

• inputs — The texts to embed.

Returns: Batches in order.

createProvider(config)

Create a hosted embeddings provider.

function createProvider(config?: MoleculeEmbeddingsConfig): AIEmbeddingsProvider

• config — Options; each falls back to its env var.

Returns: An AIEmbeddingsProvider backed by molecule.dev.

Constants

provider

The provider implementation.

const provider: AIEmbeddingsProvider

DEFAULT_SERVICES_URL

Default hosted services base URL.

const DEFAULT_SERVICES_URL: 'https://api.molecule.dev/api/v1/services'

SERVICE_LIMITS

Per-request limits of the hosted service. Larger inputs are split into several requests by this provider, never sent whole.

const SERVICE_LIMITS: {
  readonly maxInputs: 256
  readonly maxCharsPerInput: 32000
  readonly maxTotalChars: 400000
}

aiEmbeddingsMoleculeSecretDefinitions

Secret definitions required by the molecule.dev hosted embeddings bond.

const aiEmbeddingsMoleculeSecretDefinitions: SecretDefinition[]

Core Interface

Implements @molecule/api-ai-embeddings interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-ai-embeddings'
import { provider } from '@molecule/api-ai-embeddings-molecule'

export function setupAiEmbeddingsMolecule(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ai-embeddings >=1.0.1
• @molecule/api-secrets ^1.0.1

Environment Variables

• MOLECULE_API_KEY (required) — molecule.dev project API key
  • Setup: Create one for your project with mlcl apikey create --project <id> --name <name> (keys start with mk_).
  • Get it here: https://www.molecule.dev
  • Example: mk_...

Runtime Dependencies

• @molecule/api-ai-embeddings

• @molecule/api-secrets

• Config: MOLECULE_API_KEY (SERVER-side only) — a molecule project API key (mk_…) with scope broker or broker:embeddings. In the molecule.dev IDE the platform can write it for you. Optional MOLECULE_SERVICES_URL (default https://api.molecule.dev/api/v1/services; https required — a required — plain-http is refused unless the host is loopback or a private-network endpoint (RFC 1918 / *.docker.internal, e.g. the sandbox gateway host.docker.internal)).

• Models: text-embedding-3-small (default, 1536 dims) and text-embedding-3-large (3072). Other model ids are refused with a 400 — the service never runs a model it cannot price. dimensions (1–3072) shortens vectors.

• Vectors from different models (or different dimensions) are NOT comparable. Store the model id next to each vector, and re-embed everything if you change it. Swapping this bond for the OpenAI bond with the same model keeps vectors compatible; swapping to the local bond does not.

• Large inputs are split automatically into requests of at most 256 texts / 400,000 characters; one text over 32,000 characters throws — chunk long documents first (you should anyway, for retrieval quality).

• Errors are MoleculeServiceError with status and errorKey. 401: bad or revoked key. 402: the project owner's included allowance is used up — usage billing must be enabled on molecule.dev. 429: too many requests for the project. 503: the platform paused the service briefly (retry later). None of these are retried for you.

• Never import this from browser code: the key would ship to every visitor.

E2E Tests

Integration checklist — drive the real flow (no mocks), adapt each item to this app's actual data and features, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip. Embeddings are infrastructure, so PROVE them through the feature they power (semantic search / "related items" / dedup) AND with a direct property check on the vectors:

• embedQuery(text) returns a non-empty numeric number[] of the model's fixed dimension, and every vector from embed/embedDocuments has that SAME length — no empty arrays, no NaN/null entries, and the length is identical across calls (a query and a document must be comparable).
• The semantic property holds — there is NO built-in similarity helper, so compute cosine similarity yourself (dot product over the two magnitudes): two related texts ("dog"/"puppy", or a query and a matching doc) score HIGH, two unrelated texts ("dog"/"quarterly taxes") score clearly LOWER. If every pair scores alike the vectors are dead — one positive check alone doesn't prove it.
• Ranking works: embed a query plus a handful of documents and sort by cosine similarity — the semantically closest document ranks ABOVE the unrelated ones. This ordering is the whole point; a query that ranks an off-topic doc first is broken.
• The feature built on it works end-to-end from the real UI: semantic search / "related items" / dedup returns results ranked by MEANING, not keyword — a search for a synonym or paraphrase finds the right item even when it shares NO words with the query (the case a plain text/keyword search would miss).
• Embedding is stable: the same text embedded twice yields (near-)identical vectors, so a stored index stays valid — re-embedding an item must not silently drift it out of its own neighborhood.
• Batching is order-preserving: embedDocuments([a, b, c]) (or embed({ input })) returns exactly one vector per input in the SAME order — embeddings[i] is the vector for input[i], never shuffled, merged, or dropped.
• Embedding runs SERVER-SIDE: the call goes through the app's API and the provider key never reaches the browser (no provider request or key in the Network tab). Any endpoint that embeds caller-supplied text is authenticated and rate-limited — an open embed endpoint is an unbounded per-token cost/abuse vector.