@molecule/api-semantic-search

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.

@molecule/api-semantic-search — semantic search over any document corpus.

Composes the @molecule/api-ai-embeddings and @molecule/api-ai-vector-store bonds into a reusable "index a corpus, then semantically search it" capability. Wire an embeddings provider and a vector-store provider at startup (see remarks), then:

Quick Start

import { indexDocuments, search, removeDocuments } from '@molecule/api-semantic-search'

await indexDocuments({
  collection: 'docs',
  documents: [
    { id: 'a', text: 'Cats are feline animals.', metadata: { topic: 'animals' } },
    { id: 'b', text: 'Cars are fast vehicles.', metadata: { topic: 'vehicles' } },
  ],
})

const hits = await search({
  collection: 'docs',
  query: 'domestic feline pet',
  topK: 3,
  filter: [{ field: 'topic', operator: 'eq', value: 'animals' }],
})

await removeDocuments({ collection: 'docs', ids: ['a'] })

Type

utility

Installation

npm install @molecule/api-semantic-search @molecule/api-ai-embeddings @molecule/api-ai-vector-store

API

Interfaces

IndexDocumentsParams

Parameters for {@link indexDocuments}.

interface IndexDocumentsParams {
  /** The collection/namespace to index the documents into. */
  collection: string
  /** The documents to embed and upsert. An empty array is a no-op. */
  documents: SemanticDocument[]
  /** Embedding model override (provider-specific). Falls back to the provider default. */
  model?: string
}

IndexResult

Result of {@link indexDocuments}.

interface IndexResult {
  /** Number of documents embedded and upserted. */
  indexed: number
  /** Dimensionality of the embedding vectors (0 when no documents were indexed). */
  dimension: number
}

RemoveDocumentsParams

Parameters for {@link removeDocuments}.

interface RemoveDocumentsParams {
  /** The collection/namespace to remove documents from. */
  collection: string
  /** Ids of the documents to remove. */
  ids: string[]
}

SearchHit

A single semantic-search hit.

interface SearchHit {
  /** The matched document's id. */
  id: string
  /** Similarity score (higher is more similar). */
  score: number
  /** Metadata stored with the matched document, if any. */
  metadata?: Record<string, unknown>
  /** The matched document's original text, if the store retained it. */
  content?: string
}

SearchParams

Parameters for {@link search}.

interface SearchParams {
  /** The collection/namespace to search within. */
  collection: string
  /** The natural-language query to embed and match against the corpus. */
  query: string
  /** Maximum number of results to return (provider default applies when omitted). */
  topK?: number
  /** Optional metadata filters to narrow results before scoring. */
  filter?: MetadataFilter[]
  /** Minimum similarity score threshold — hits below this are excluded. */
  minScore?: number
  /** Embedding model override (provider-specific). Falls back to the provider default. */
  model?: string
}

SemanticDocument

A single document to index into a semantic-search collection.

interface SemanticDocument {
  /** Stable unique identifier for this document (used as the vector record id). */
  id: string
  /** The document's text — embedded and stored so it can be returned on a hit. */
  text: string
  /** Arbitrary metadata stored alongside the vector and usable as a search filter. */
  metadata?: Record<string, unknown>
}

Functions

indexDocuments(params)

Embed a corpus of documents and upsert them into a vector-store collection, creating the collection on first use.

When documents is empty this short-circuits and returns without touching either provider. The embedding model is chosen via model when supplied, otherwise the provider's embedDocuments default is used. The target collection is ensured idempotently — it is only created if not already present.

function indexDocuments(params: IndexDocumentsParams): Promise<IndexResult>

• params — The collection, documents, and optional embedding model.

Returns: The number of documents indexed and the embedding dimensionality.

removeDocuments(params)

Remove previously-indexed documents from a collection by their ids.

function removeDocuments(params: RemoveDocumentsParams): Promise<void>

• params — The collection and the ids of the documents to remove.

Returns: A promise that resolves once the documents have been deleted.

search(params)

Semantically search an indexed collection: embed the query, then return the most similar documents ranked by similarity.

The query is embedded with model when supplied, otherwise the provider's embedQuery default. topK, filter, and minScore are forwarded to the vector store to bound, narrow, and threshold the results respectively.

function search(params: SearchParams): Promise<SearchHit[]>

• params — The collection, query text, and optional topK/filter/minScore/model.

Returns: The matching documents (id, score, metadata, content) ranked most-similar first.

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ai-embeddings >=1.0.1
• @molecule/api-ai-vector-store >=1.0.1

Runtime Dependencies

• @molecule/api-ai-embeddings
• @molecule/api-ai-vector-store

Wiring: @molecule/api-ai-embeddings and @molecule/api-ai-vector-store are provider-singleton cores — wire them with each core's setProvider(), NOT with bond() (bonding those category names is silently ignored):

import { setProvider as setEmbeddings } from '@molecule/api-ai-embeddings'
import { setProvider as setVectorStore } from '@molecule/api-ai-vector-store'
import { provider as embeddings } from '@molecule/api-ai-embeddings-openai'
import { provider as vectorStore } from '@molecule/api-ai-vector-store-memory'

setEmbeddings(embeddings)
setVectorStore(vectorStore)

Provider prereqs apply: -openai embeddings need OPENAI_API_KEY; -local embeddings download their model on first use (network + several hundred MB of runtime). The -memory vector store keeps the index in process memory — it is lost on restart and not shared across processes; use -pgvector / -pinecone / -chroma for persistence. Both providers throw a "no provider" error from the first indexDocuments/search call when unwired.