### Quickstart: Initialize SemanticStore and perform basic operations

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Demonstrates the basic usage of the `SemanticStore` class from `ferrovex-embeddings`. It shows how to initialize the store, insert text with metadata, embed single or multiple strings, and query for similar text.

```typescript
import { SemanticStore } from 'ferrovex-embeddings'

const store = new SemanticStore({
  dbPath: './data/lancedb', // optional; temp dir is used when omitted
  tableName: 'docs' // optional; default is "embeddings"
})

await store.insert('Rust + Node bindings', { source: 'intro', id: 1 })
await store.insert('LanceDB stores vectors on disk', { source: 'intro', id: 2 })

const v = await store.embed('Rust + Node bindings')
const vv = await store.embed(['first text', 'second text'])

const matches = await store.query('node native extensions', { limit: 5 })
console.log(v.length, vv.length, matches[0])
```

--------------------------------

### Install and build ferrovex-embeddings for direct development

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Installs project dependencies and builds the ferrovex-embeddings library from source. This is used when developing the repository directly, not for end-users installing the package.

```bash
npm install
npm run build
```

--------------------------------

### Complete Ferrovex Example: Store, Insert, Embed, Query

Source: https://context7.com/dinedal/ferrovex/llms.txt

This end-to-end example showcases the full lifecycle of using Ferrovex's SemanticStore. It covers creating a temporary database, inserting documents with rich metadata, generating embeddings for a query, and performing a semantic search, followed by cleanup.

```typescript
import { SemanticStore } from 'ferrovex-embeddings'
import * as fs from 'node:fs/promises'
import * as os from 'node:os'
import * as path from 'node:path'

async function main() {
  // Create temporary directory for demo
  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ferrovex-demo-'))
  const dbPath = path.join(tmpDir, 'vectors')

  try {
    const store = new SemanticStore({
      dbPath,
      tableName: 'knowledge',
      runtime: 'hf',
      modelId: 'sentence-transformers/paraphrase-MiniLM-L3-v2'
    })

    // Insert documents with rich metadata
    const documents = [
      {
        text: 'Rust provides memory safety without garbage collection through ownership.',
        metadata: { topic: 'rust', subtopic: 'memory', difficulty: 'intermediate' }
      },
      {
        text: 'Node.js uses an event-driven, non-blocking I/O model for scalability.',
        metadata: { topic: 'nodejs', subtopic: 'architecture', difficulty: 'beginner' }
      },
      {
        text: 'Vector embeddings transform text into numerical representations.',
        metadata: { topic: 'ml', subtopic: 'embeddings', difficulty: 'intermediate' }
      },
      {
        text: 'LanceDB is a columnar vector database optimized for AI workloads.',
        metadata: { topic: 'databases', subtopic: 'vector', difficulty: 'advanced' }
      }
    ]

    for (const doc of documents) {
      await store.insert(doc.text, doc.metadata)
    }
    console.log(`Inserted ${documents.length} documents`)

    // Generate standalone embeddings
    const queryEmbedding = await store.embed('memory management in programming')
    console.log(`Query embedding dimension: ${queryEmbedding.length}`)

    // Semantic search
    const searchResults = await store.query('How does Rust handle memory?', { limit: 2 })

    console.log('\nSearch Results:')
    searchResults.forEach((result, idx) => {
      console.log(`\n${idx + 1}. ${result.text}`)
      console.log(`   Score: ${result.score?.toFixed(4)}`)
      console.log(`   Topic: ${result.metadata?.topic}, Difficulty: ${result.metadata?.difficulty}`)
    })

  } finally {
    // Cleanup
    await fs.rm(tmpDir, { recursive: true, force: true })
  }
}

main().catch(console.error)
```

--------------------------------

### Complete Working Example

Source: https://context7.com/dinedal/ferrovex/llms.txt

An end-to-end example demonstrating store creation, document insertion, embedding generation, and semantic search using the Ferrovex Semantic Store.

```APIDOC
## Example: Full Workflow

### Description
This example illustrates the complete lifecycle of using the `SemanticStore`, from initialization and document insertion to generating embeddings and performing semantic searches. It includes setting up the store with a specific model, inserting documents with rich metadata, generating a query embedding, and then executing a semantic search.

### Method
N/A (Illustrative Code)

### Endpoint
N/A (Illustrative Code)

### Request Example
```typescript
import { SemanticStore } from 'ferrovex-embeddings'
import * as fs from 'node:fs/promises'
import * as os from 'node:os'
import * as path from 'node:path'

async function main() {
  // Create temporary directory for demo
  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ferrovex-demo-'))
  const dbPath = path.join(tmpDir, 'vectors')

  try {
    const store = new SemanticStore({
      dbPath,
      tableName: 'knowledge',
      runtime: 'hf',
      modelId: 'sentence-transformers/paraphrase-MiniLM-L3-v2'
    })

    // Insert documents with rich metadata
    const documents = [
      {
        text: 'Rust provides memory safety without garbage collection through ownership.',
        metadata: { topic: 'rust', subtopic: 'memory', difficulty: 'intermediate' }
      },
      {
        text: 'Node.js uses an event-driven, non-blocking I/O model for scalability.',
        metadata: { topic: 'nodejs', subtopic: 'architecture', difficulty: 'beginner' }
      },
      {
        text: 'Vector embeddings transform text into numerical representations.',
        metadata: { topic: 'ml', subtopic: 'embeddings', difficulty: 'intermediate' }
      },
      {
        text: 'LanceDB is a columnar vector database optimized for AI workloads.',
        metadata: { topic: 'databases', subtopic: 'vector', difficulty: 'advanced' }
      }
    ]

    for (const doc of documents) {
      await store.insert(doc.text, doc.metadata)
    }
    console.log(`Inserted ${documents.length} documents`)

    // Generate standalone embeddings
    const queryEmbedding = await store.embed('memory management in programming')
    console.log(`Query embedding dimension: ${queryEmbedding.length}`)

    // Semantic search
    const searchResults = await store.query('How does Rust handle memory?', { limit: 2 })

    console.log('\nSearch Results:')
    searchResults.forEach((result, idx) => {
      console.log(`\n${idx + 1}. ${result.text}`)
      console.log(`   Score: ${result.score?.toFixed(4)}`)
      console.log(`   Topic: ${result.metadata?.topic}, Difficulty: ${result.metadata?.difficulty}`)
    })

  } finally {
    // Cleanup
    await fs.rm(tmpDir, { recursive: true, force: true })
  }
}

main().catch(console.error)
```

### Response
#### Success Response (200)
- **void** - The function executes the operations and logs results to the console. No direct API response is returned as this is a client-side example.
```

--------------------------------

### Install ferrovex-embeddings npm package

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Installs the ferrovex-embeddings package using npm. This is the standard installation command for using the library in a Node.js or TypeScript project.

```bash
npm install ferrovex-embeddings
```

--------------------------------

### ferrovex-embeddings npm prebuilt binary platform packages

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Lists the npm packages that provide prebuilt binaries for different platforms for the ferrovex-embeddings library. This allows users to install the correct binary for their operating system and architecture without needing to compile from source.

```bash
# Root package: `ferrovex-embeddings`
# Platform packages under `npm/*`:
#   `ferrovex-embeddings-linux-x64-gnu`
#   `ferrovex-embeddings-win32-x64-msvc`
#   `ferrovex-embeddings-darwin-x64`
#   `ferrovex-embeddings-darwin-arm64`
```

--------------------------------

### Understanding Ferrovex QueryResult Interface

Source: https://context7.com/dinedal/ferrovex/llms.txt

This snippet details the structure of the QueryResult object returned by the Ferrovex SemanticStore query method. It includes type annotations and an example of how to access the text, metadata, distance, and score of a query match.

```typescript
interface QueryResult {
  text: string                          // Original inserted text
  metadata?: Record<string, unknown>    // Associated metadata object
  distance?: number                     // LanceDB distance (lower = more similar)
  score?: number                        // Similarity score: 1 / (1 + max(distance, 0))
}

// Example usage with type annotations
import { SemanticStore, QueryResult } from 'ferrovex-embeddings'

const store = new SemanticStore()
await store.insert('Sample document', { category: 'test' })

const results: QueryResult[] = await store.query('sample', { limit: 5 })
const topMatch: QueryResult = results[0]

if (topMatch.score && topMatch.score > 0.8) {
  console.log(`High confidence match: ${topMatch.text}`)
  console.log(`Category: ${topMatch.metadata?.category}`)
}
```

--------------------------------

### Disable Metal acceleration for macOS builds

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Command to disable Metal GPU acceleration during the build process for ferrovex-embeddings on macOS. This is useful for CI environments or sandboxed setups where Metal might not be available or desired.

```bash
FERROVEX_DISABLE_METAL=1 npm run build
```

--------------------------------

### Initialize SemanticStore in TypeScript

Source: https://context7.com/dinedal/ferrovex/llms.txt

Demonstrates how to create instances of the SemanticStore class. It shows configurations for ephemeral (in-memory) stores and persistent stores with custom database paths, table names, and embedding model runtimes (HuggingFace or ONNX).

```typescript
import { SemanticStore } from 'ferrovex-embeddings'

// Ephemeral store (temporary directory, data lost on process exit)
const ephemeralStore = new SemanticStore()

// Persistent store with custom configuration
const store = new SemanticStore({
  dbPath: './data/lancedb',           // Path to persist LanceDB data
  tableName: 'documents',              // Custom table name (default: "embeddings")
  runtime: 'hf',                       // 'hf' (HuggingFace) or 'onnx'
  modelId: 'jinaai/jina-embeddings-v2-small-en'  // Model identifier
})

// ONNX runtime configuration
const onnxStore = new SemanticStore({
  dbPath: './data/onnx-store',
  runtime: 'onnx',
  onnxModelId: 'sentence-transformers/all-MiniLM-L6-v2',
  modelArchitecture: 'bert'            // Default: 'bert'
})
```

--------------------------------

### SemanticStore Constructor

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Initializes a new SemanticStore instance. Options can be provided to configure the database path, table name, and runtime settings for embedding models.

```APIDOC
## `new SemanticStore(options?)`

### Description
Initializes a new SemanticStore instance. Options can be provided to configure the database path, table name, and runtime settings for embedding models.

### Method
Constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (StoreOptions) - Optional - Configuration options for the SemanticStore.
  - **dbPath** (string) - Optional - Path to persist the vector database. If omitted, a temporary directory is used.
  - **tableName** (string) - Optional - The name of the table to use in the vector database. Defaults to "embeddings".
  - **runtime** ('hf' | 'onnx') - Optional - The runtime to use for embeddings. Defaults to 'hf'.
  - **modelArchitecture** (string) - Optional - The architecture of the model to use (primarily for ONNX runtime).
  - **modelId** (string) - Optional - The model ID to load (e.g., from HuggingFace Hub).
  - **revision** (string) - Optional - The specific revision of the model to load.
  - **onnxModelId** (string) - Optional - The model ID for ONNX runtime.
  - **onnxPathInRepo** (string) - Optional - The path to the ONNX model file within the repository.

### Request Example
```json
{
  "dbPath": "./data/lancedb",
  "tableName": "docs",
  "runtime": "onnx",
  "modelId": "sentence-transformers/all-MiniLM-L6-v2"
}
```

### Response
#### Success Response (200)
Returns an instance of `SemanticStore`.

#### Response Example
```javascript
// Returns a SemanticStore instance
const store = new SemanticStore({ dbPath: './data' });
```
```

--------------------------------

### Local development build commands for ferrovex-embeddings

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Commands for building the ferrovex-embeddings library locally. Includes options for release and debug builds, running end-to-end smoke tests, and performing a Rust compile check.

```bash
# native build (release)
npm run build

# native build (debug)
npm run build:debug

# end-to-end smoke test (embed + insert + query)
npm run smoke

# rust compile check
cargo check
```

--------------------------------

### Perform Semantic Similarity Search with Ferrovex

Source: https://context7.com/dinedal/ferrovex/llms.txt

This snippet demonstrates how to use the SemanticStore in Ferrovex to perform semantic similarity searches. It shows inserting documents with metadata and querying for similar text. The query method supports basic searches and filtering using Lance SQL predicates.

```typescript
import { SemanticStore } from 'ferrovex-embeddings'

const store = new SemanticStore({ dbPath: './data/knowledge-base' })

// Insert sample documents
await store.insert('JavaScript is a dynamic programming language.', { type: 'lang', id: 1 })
await store.insert('TypeScript adds static types to JavaScript.', { type: 'lang', id: 2 })
await store.insert('Rust is a systems programming language focused on safety.', { type: 'lang', id: 3 })
await store.insert('Python is popular for data science and machine learning.', { type: 'lang', id: 4 })

// Basic query - returns QueryResult[]
const results = await store.query('statically typed languages', { limit: 3 })

results.forEach((match, i) => {
  console.log(`${i + 1}. "${match.text}"`);
  console.log(`   Score: ${match.score?.toFixed(4)}, Distance: ${match.distance?.toFixed(4)}`);
  console.log(`   Metadata: ${JSON.stringify(match.metadata)}`);
})

// Query with SQL filter (Lance SQL predicate syntax)
const filteredResults = await store.query('programming language', {
  limit: 10,
  filter: "metadata_json LIKE '%\"type\":\"lang\"%'"
})
```

--------------------------------

### GitHub Actions release workflow configuration

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Describes the GitHub Actions workflow for releasing ferrovex-embeddings. It triggers on tag pushes, builds native artifacts for various targets, and publishes platform-specific packages and the root package to npm.

```yaml
# Trigger: push tags matching `v*`
# Builds native artifacts per target
# Publishes platform packages + root package to npm

Required secrets/variables:

- npm Trusted Publishing (GitHub Actions OIDC) must be configured in npm for:
  - `ferrovex-embeddings`
  - `ferrovex-embeddings-linux-x64-gnu`
  - `ferrovex-embeddings-win32-x64-msvc`
  - `ferrovex-embeddings-darwin-x64`
  - `ferrovex-embeddings-darwin-arm64`
- Optional repo variable: `FERROVEX_DISABLE_METAL=1` (for CI fallback)
```

--------------------------------

### ferrovex-embeddings SemanticStore options type definition

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Defines the TypeScript type for the options object used when initializing the `SemanticStore`. It includes parameters for database path, table name, and runtime configurations for embedding models.

```typescript
type StoreOptions = {
  dbPath?: string
  tableName?: string
  runtime?: 'hf' | 'onnx'
  modelArchitecture?: string
  modelId?: string
  revision?: string
  onnxModelId?: string
  onnxPathInRepo?: string
}
```

--------------------------------

### Insert text and metadata into SemanticStore

Source: https://context7.com/dinedal/ferrovex/llms.txt

Shows how to insert text content along with optional metadata into the SemanticStore. The library automatically generates embeddings and persists them in LanceDB. Supports single inserts and batch inserts.

```typescript
import { SemanticStore } from 'ferrovex-embeddings'

const store = new SemanticStore({ dbPath: './data/docs' })

// Insert with metadata
await store.insert(
  'Rust and N-API are a good fit for high performance Node.js extensions.',
  { id: 'doc-1', category: 'performance', tags: ['rust', 'node'] }
)

// Insert without metadata
await store.insert('LanceDB stores vectors on disk and supports nearest-neighbor queries.')

// Batch insert multiple documents
const documents = [
  { text: 'TypeScript bindings make native modules easier to adopt.', meta: { id: 1 } },
  { text: 'Vector databases enable semantic search capabilities.', meta: { id: 2 } },
  { text: 'Embeddings capture semantic meaning of text.', meta: { id: 3 } }
]

for (const doc of documents) {
  await store.insert(doc.text, doc.meta)
}
```

--------------------------------

### SemanticStore Query API

Source: https://context7.com/dinedal/ferrovex/llms.txt

Perform semantic similarity search by embedding the query text and finding nearest neighbors in LanceDB. Supports basic queries and queries with SQL filters.

```APIDOC
## POST /query

### Description
Performs a semantic similarity search by embedding the query text and finding nearest neighbors in LanceDB. This endpoint allows for both basic similarity searches and more advanced searches with SQL-based filtering.

### Method
POST

### Endpoint
`/query`

### Parameters
#### Query Parameters
- **limit** (number) - Optional - The maximum number of results to return.
- **filter** (string) - Optional - A SQL predicate string to filter results based on metadata.

#### Request Body
- **text** (string) - Required - The query text to embed and search for.
- **params** (object) - Optional - Additional parameters for the query, such as `limit` and `filter`.
  - **limit** (number) - Optional - The maximum number of results to return.
  - **filter** (string) - Optional - A SQL predicate string to filter results based on metadata.

### Request Example
```json
{
  "text": "statically typed languages",
  "params": {
    "limit": 3,
    "filter": "metadata_json LIKE '%\"type\":\"lang\"%'"
  }
}
```

### Response
#### Success Response (200)
- **QueryResult[]** - An array of QueryResult objects, each containing the matched text, metadata, distance, and similarity score.

#### QueryResult Interface
```typescript
interface QueryResult {
  text: string                          // Original inserted text
  metadata?: Record<string, unknown>    // Associated metadata object
  distance?: number                     // LanceDB distance (lower = more similar)
  score?: number                        // Similarity score: 1 / (1 + max(distance, 0))
}
```

#### Response Example
```json
[
  {
    "text": "TypeScript adds static types to JavaScript.",
    "metadata": {"type":"lang","id":2},
    "distance": 0.2145,
    "score": 0.8234
  },
  {
    "text": "Rust is a systems programming language focused on safety.",
    "metadata": {"type":"lang","id":3},
    "distance": 0.3978,
    "score": 0.7156
  }
]
```
```

--------------------------------

### Generate text embeddings with SemanticStore

Source: https://context7.com/dinedal/ferrovex/llms.txt

Demonstrates the `embed` method for generating embedding vectors from text without storing them. It handles both single string inputs (returning a single vector) and array inputs (returning an array of vectors).

```typescript
import { SemanticStore } from 'ferrovex-embeddings'

const store = new SemanticStore()

// Single text embedding - returns number[]
const singleVector = await store.embed('Semantic search with embeddings')
console.log(`Embedding dimension: ${singleVector.length}`)
// Output: Embedding dimension: 512 (varies by model)

// Batch text embedding - returns number[][]
const texts = [
  'First document about machine learning',
  'Second document about natural language processing',
  'Third document about vector databases'
]
const batchVectors = await store.embed(texts)
console.log(`Batch size: ${batchVectors.length}, Each dimension: ${batchVectors[0].length}`)
// Output: Batch size: 3, Each dimension: 512
```

--------------------------------

### insert(text, metadata?)

Source: https://context7.com/dinedal/ferrovex/llms.txt

Embed text and store it in LanceDB along with optional metadata. The embedding vector is automatically generated and persisted.

```APIDOC
## insert(text, metadata?)

### Description
Embed text and store it in LanceDB along with optional metadata. The embedding vector is automatically generated and persisted.

### Method
`await store.insert(text: string, metadata?: Record<string, any>): Promise<void>`

### Parameters
#### Path Parameters
- **text** (string) - Required - The text content to embed and store.
- **metadata** (object) - Optional - An object containing key-value pairs for metadata associated with the text.

### Request Example
```typescript
import { SemanticStore } from 'ferrovex-embeddings'

const store = new SemanticStore({ dbPath: './data/docs' })

// Insert with metadata
await store.insert(
  'Rust and N-API are a good fit for high performance Node.js extensions.',
  { id: 'doc-1', category: 'performance', tags: ['rust', 'node'] }
)

// Insert without metadata
await store.insert('LanceDB stores vectors on disk and supports nearest-neighbor queries.')

// Batch insert multiple documents
const documents = [
  { text: 'TypeScript bindings make native modules easier to adopt.', meta: { id: 1 } },
  { text: 'Vector databases enable semantic search capabilities.', meta: { id: 2 } },
  { text: 'Embeddings capture semantic meaning of text.', meta: { id: 3 } }
]

for (const doc of documents) {
  await store.insert(doc.text, doc.meta)
}
```

### Response
#### Success Response (200)
- **void** - This method does not return a value upon successful completion.

#### Response Example
```
// No response body for successful insertion.
```
```

--------------------------------

### Query Semantic Store

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Embeds the query text, performs a nearest-neighbor search in the LanceDB, and returns matching results.

```APIDOC
## `query(text, params?) => Promise<QueryResult[]>`

### Description
Embeds the query text, performs a nearest-neighbor search in the LanceDB, and returns matching results. Results include the original text, metadata, and a similarity score.

### Method
POST

### Endpoint
`/semantic-store/query` (Conceptual - this is a method call, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **text** (string) - Required - The query text to find similar items.
- **params** (QueryParams) - Optional - Parameters for the query.
  - **limit** (number) - Optional - The maximum number of results to return. Defaults to a sensible value.
  - **filter** (string) - Optional - A Lance SQL predicate string to filter results before searching.

### Request Example
```javascript
const matches = await store.query('What are node native extensions?', { limit: 5, filter: "source = 'intro'" });
console.log(matches);
```

### Response
#### Success Response (200)
- **results** (QueryResult[]) - An array of query results.
  - **text** (string) - The text content of the matched item.
  - **metadata** (Record<string, unknown>) - Optional - The metadata associated with the matched item.
  - **distance** (number) - Optional - The distance metric from LanceDB (e.g., `_distance`).
  - **score** (number) - Optional - A calculated similarity score, typically `1 / (1 + distance)`.

#### Response Example
```json
[
  {
    "text": "Rust + Node bindings",
    "metadata": {"source": "intro", "id": 1},
    "distance": 0.123,
    "score": 0.887
  },
  {
    "text": "LanceDB stores vectors on disk",
    "metadata": {"source": "intro", "id": 2},
    "distance": 0.456,
    "score": 0.685
  }
]
```
```

--------------------------------

### embedBatch(texts)

Source: https://context7.com/dinedal/ferrovex/llms.txt

Explicitly embed multiple texts in a single batch operation. Equivalent to `embed(string[])`.

```APIDOC
## embedBatch(texts)

### Description
Explicitly embed multiple texts in a single batch operation. Equivalent to `embed(string[])`.

### Method
`await store.embedBatch(texts: string[]): Promise<number[][]>`

### Parameters
#### Path Parameters
- **texts** (string[]) - Required - An array of texts to generate embeddings for in a batch.

### Request Example
```typescript
import { SemanticStore } from 'ferrovex-embeddings'

const store = new SemanticStore()

const embeddings = await store.embedBatch([
  'Query optimization techniques',
  'Database indexing strategies',
  'Full-text search implementations'
])

// Use embeddings for custom operations
embeddings.forEach((vec, i) => {
  console.log(`Document ${i}: ${vec.length} dimensions, first value: ${vec[0].toFixed(4)}`)
})
```

### Response
#### Success Response (200)
- **number[][]** - An array of embedding vectors, where each inner array represents the embedding for a corresponding input text.

#### Response Example
```json
[ [0.123, -0.456, ..., 0.789], [-0.987, 0.654, ..., -0.321], [0.111, -0.222, ..., 0.333] ]
```
```

--------------------------------

### Smoke test environment variable overrides

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Lists environment variables that can be used to override default settings for the ferrovex-embeddings smoke tests. Allows specifying the runtime and model ID for testing different configurations.

```bash
# FERROVEX_SMOKE_RUNTIME (`hf` or `onnx`)
# FERROVEX_SMOKE_MODEL_ID (defaults to `sentence-transformers/paraphrase-MiniLM-L3-v2`)
```

--------------------------------

### embed(text) / embed(texts)

Source: https://context7.com/dinedal/ferrovex/llms.txt

Generate embedding vectors for text without storing them. Returns a single vector for string input or an array of vectors for array input.

```APIDOC
## embed(text) / embed(texts)

### Description
Generate embedding vectors for text without storing them. Returns a single vector for string input or an array of vectors for array input.

### Method
`await store.embed(text: string | string[]): Promise<number[] | number[][]>`

### Parameters
#### Path Parameters
- **text** (string | string[]) - Required - The text or an array of texts to generate embeddings for.

### Request Example
```typescript
import { SemanticStore } from 'ferrovex-embeddings'

const store = new SemanticStore()

// Single text embedding - returns number[]
const singleVector = await store.embed('Semantic search with embeddings')
console.log(`Embedding dimension: ${singleVector.length}`)
// Output: Embedding dimension: 512 (varies by model)

// Batch text embedding - returns number[][]
const texts = [
  'First document about machine learning',
  'Second document about natural language processing',
  'Third document about vector databases'
]
const batchVectors = await store.embed(texts)
console.log(`Batch size: ${batchVectors.length}, Each dimension: ${batchVectors[0].length}`)
// Output: Batch size: 3, Each dimension: 512
```

### Response
#### Success Response (200)
- **number[] | number[][]** - A single embedding vector (number array) if a string is provided, or an array of embedding vectors (number[][]) if an array of strings is provided.

#### Response Example
```json
// For single text input:
[0.123, -0.456, ..., 0.789]

// For array input:
[ [0.123, -0.456, ..., 0.789], [-0.987, 0.654, ..., -0.321] ]
```
```

--------------------------------

### ferrovex-embeddings QueryParams and QueryResult type definitions

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Defines the TypeScript types for query parameters and query results in the `ferrovex-embeddings` library. `QueryParams` allows specifying a limit and a Lance SQL filter, while `QueryResult` includes the embedded text, metadata, and distance/score.

```typescript
type QueryParams = {
  limit?: number
  filter?: string // Lance SQL predicate
}

type QueryResult = {
  text: string
  metadata?: Record<string, unknown>
  distance?: number
  score?: number
}
```

--------------------------------

### Embed Single Text

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Generates a single embedding vector for the provided input string.

```APIDOC
## `embed(text) => Promise<number[]>`

### Description
Generates a single embedding vector for the provided input string.

### Method
POST

### Endpoint
`/semantic-store/embed` (Conceptual - this is a method call, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **text** (string) - Required - The text string to embed.

### Request Example
```javascript
const embeddingVector = await store.embed('Generate an embedding for this text.');
console.log(embeddingVector.length); // Output: Dimension of the embedding vector
```

### Response
#### Success Response (200)
- **embedding** (number[]) - An array of numbers representing the embedding vector.

#### Response Example
```json
[
  0.1234,
  -0.5678,
  0.9876,
  ...
]
```
```

--------------------------------

### Perform explicit batch embedding generation

Source: https://context7.com/dinedal/ferrovex/llms.txt

Explains the `embedBatch` method, which is an explicit way to generate embedding vectors for multiple texts in a single batch operation. This method is equivalent to calling `embed` with an array of strings.

```typescript
import { SemanticStore } from 'ferrovex-embeddings'

const store = new SemanticStore()

const embeddings = await store.embedBatch([
  'Query optimization techniques',
  'Database indexing strategies',
  'Full-text search implementations'
])

// Use embeddings for custom operations
embeddings.forEach((vec, i) => {
  console.log(`Document ${i}: ${vec.length} dimensions, first value: ${vec[0].toFixed(4)}`)
})
```

--------------------------------

### Embed Multiple Texts

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Generates embedding vectors for an array of input strings. This method is equivalent to `embedBatch`.

```APIDOC
## `embed(texts: string[]) => Promise<number[][]>`
## `embedBatch(texts: string[]) => Promise<number[][]>`

### Description
Generates embedding vectors for an array of input strings. Both `embed(string[])` and `embedBatch(string[])` are equivalent and return one embedding vector per input string.

### Method
POST

### Endpoint
`/semantic-store/embed-batch` (Conceptual - this is a method call, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **texts** (string[]) - Required - An array of text strings to embed.

### Request Example
```javascript
const embeddingVectors = await store.embed(['First text to embed', 'Second text to embed']);
console.log(embeddingVectors.length); // Output: 2
console.log(embeddingVectors[0].length); // Output: Dimension of the embedding vector
```

### Response
#### Success Response (200)
- **embeddings** (number[][]) - An array of arrays, where each inner array is an embedding vector for the corresponding input string.

#### Response Example
```json
[
  [0.1111, -0.2222, 0.3333, ...],
  [0.4444, -0.5555, 0.6666, ...]
]
```
```

--------------------------------

### Insert Data

Source: https://github.com/dinedal/ferrovex/blob/main/README.md

Embeds the provided text and inserts it along with its metadata and the generated vector into the LanceDB.

```APIDOC
## `insert(text, metadata?) => Promise<void>`

### Description
Embeds the provided text and inserts it along with its metadata and the generated vector into the LanceDB.

### Method
POST

### Endpoint
`/semantic-store/insert` (Conceptual - this is a method call, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **text** (string) - Required - The text content to embed and insert.
- **metadata** (Record<string, unknown>) - Optional - Additional metadata to associate with the text.

### Request Example
```javascript
await store.insert('This is a document about embeddings.', { source: 'manual', id: 101 });
```

### Response
#### Success Response (200)
Returns a Promise that resolves when the insertion is complete.

#### Response Example
```javascript
// No explicit return value on success, Promise resolves.
Promise.resolve();
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.