---

url: 'https://sqlrooms.org/api/ai.md'

---

# @sqlrooms/ai

High-level AI package for SQLRooms.

This package combines:

* AI slice state/logic (`@sqlrooms/ai-core`)

* AI settings UI/state (`@sqlrooms/ai-settings`)

* AI config schemas (`@sqlrooms/ai-config`)

* SQL query tool helpers (`createDefaultAiTools`, `createQueryTool`)

Use this package when you want AI chat + tool execution in a SQLRooms app without wiring low-level pieces manually.

## Installation

```bash

npm install @sqlrooms/ai @sqlrooms/room-shell @sqlrooms/duckdb @sqlrooms/ui

```

## Quick start

```tsx

import {

AiSettingsSliceState,

AiSliceState,

createAiSettingsSlice,

createAiSlice,

createDefaultAiInstructions,

createDefaultAiTools,

} from '@sqlrooms/ai';

import {

createRoomShellSlice,

createRoomStore,

RoomShellSliceState,

} from '@sqlrooms/room-shell';

type RoomState = RoomShellSliceState & AiSliceState & AiSettingsSliceState;

export const {roomStore, useRoomStore} = createRoomStore<RoomState>(

(set, get, store) => ({

...createRoomShellSlice({

config: {

dataSources: [

{

type: 'url',

tableName: 'earthquakes',

url: 'https://huggingface.co/datasets/sqlrooms/earthquakes/resolve/main/earthquakes.parquet',

},

],

},

})(set, get, store),

...createAiSettingsSlice()(set, get, store),

...createAiSlice({

tools: {

...createDefaultAiTools(store),

},

getInstructions: () => createDefaultAiInstructions(store),

})(set, get, store),

}),

);

```

## Render chat UI

```tsx

import {Chat} from '@sqlrooms/ai';

import {useRoomStore} from './store';

function AiPanel() {

const updateProvider = useRoomStore(

(state) => state.aiSettings.updateProvider,

);

return (

<Chat>

<Chat.Sessions />

<Chat.Messages />

<Chat.PromptSuggestions>

<Chat.PromptSuggestions.Item text="Summarize the available tables" />

</Chat.PromptSuggestions>

<Chat.Composer placeholder="Ask a question about your data">

<Chat.InlineApiKeyInput

onSaveApiKey={(provider, apiKey) => {

updateProvider(provider, {apiKey});

}}

/>

<Chat.ModelSelector />

</Chat.Composer>

</Chat>

);

}

```

## Add custom tools

```tsx

import {z} from 'zod';

import {

createAiSlice,

createDefaultAiInstructions,

createDefaultAiTools,

} from '@sqlrooms/ai';

// inside createRoomStore(...):

createAiSlice({

tools: {

...createDefaultAiTools(store),

echo: {

name: 'echo',

description: 'Return user text back to the chat',

parameters: z.object({

text: z.string(),

}),

execute: async ({text}) => ({

llmResult: {

success: true,

details: `Echo: ${text}`,

},

}),

},

},

getInstructions: () => createDefaultAiInstructions(store),

})(set, get, store);

```

## Use remote endpoint mode

If you want server-side model calls, set `chatEndPoint` and optional `chatHeaders`:

```tsx

// inside createRoomStore(...):

...createAiSlice({

tools: {

...createDefaultAiTools(store),

},

getInstructions: () => createDefaultAiInstructions(store),

chatEndPoint: '/api/chat',

chatHeaders: {

'x-app-name': 'my-sqlrooms-app',

},

})(set, get, store),

```

## Related packages

* `@sqlrooms/ai-core` for lower-level AI slice and chat primitives

* `@sqlrooms/ai-settings` for settings slice/components only

* `@sqlrooms/ai-config` for Zod schemas and migrations

## Classes

* [ToolAbortError](classes/ToolAbortError.md)

## Interfaces

* [AiSliceOptions](interfaces/AiSliceOptions.md)

* [StoredTool](interfaces/StoredTool.md)

* [ModelUsageData](interfaces/ModelUsageData.md)

## Type Aliases

* [ListCommandsToolParameters](type-aliases/ListCommandsToolParameters.md)

* [CommandToolDescriptor](type-aliases/CommandToolDescriptor.md)

* [ListCommandsToolLlmResult](type-aliases/ListCommandsToolLlmResult.md)

* [ExecuteCommandToolParameters](type-aliases/ExecuteCommandToolParameters.md)

* [ExecuteCommandToolLlmResult](type-aliases/ExecuteCommandToolLlmResult.md)

* [CommandToolsOptions](type-aliases/CommandToolsOptions.md)

* [DefaultCommandTools](type-aliases/DefaultCommandTools.md)

* [DefaultToolsOptions](type-aliases/DefaultToolsOptions.md)

* [DefaultAiToolRenderers](type-aliases/DefaultAiToolRenderers.md)

* [QueryToolRendererOptions](type-aliases/QueryToolRendererOptions.md)

* [QueryToolParameters](type-aliases/QueryToolParameters.md)

* [QueryToolOutput](type-aliases/QueryToolOutput.md)

* [QueryToolOptions](type-aliases/QueryToolOptions.md)

* [AiSettingsSliceConfig](type-aliases/AiSettingsSliceConfig.md)

* [AiSliceConfig](type-aliases/AiSliceConfig.md)

* [ErrorMessageSchema](type-aliases/ErrorMessageSchema.md)

* [AnalysisResultSchema](type-aliases/AnalysisResultSchema.md)

* [AnalysisSessionSchema](type-aliases/AnalysisSessionSchema.md)

* [ToolUIPart](type-aliases/ToolUIPart.md)

* [UIMessagePart](type-aliases/UIMessagePart.md)

* [AiSliceState](type-aliases/AiSliceState.md)

* [ErrorMessageComponentProps](type-aliases/ErrorMessageComponentProps.md)

* [SessionType](type-aliases/SessionType.md)

* [AgentToolCall](type-aliases/AgentToolCall.md)

* [AgentToolCallAdditionalData](type-aliases/AgentToolCallAdditionalData.md)

* [AgentStreamOutput](type-aliases/AgentStreamOutput.md)

* [StoredToolSet](type-aliases/StoredToolSet.md)

* [AddToolOutput](type-aliases/AddToolOutput.md)

* [ToolRendererProps](type-aliases/ToolRendererProps.md)

* [ToolRenderer](type-aliases/ToolRenderer.md)

* [ToolRendererRegistry](type-aliases/ToolRendererRegistry.md)

* [ToolRenderers](type-aliases/ToolRenderers.md)

* [AiSettingsSliceState](type-aliases/AiSettingsSliceState.md)

## Variables

* [ListCommandsToolParameters](variables/ListCommandsToolParameters.md)

* [ExecuteCommandToolParameters](variables/ExecuteCommandToolParameters.md)

* [QueryToolResult](variables/QueryToolResult.md)

* [QueryToolParameters](variables/QueryToolParameters.md)

* [AiSettingsSliceConfig](variables/AiSettingsSliceConfig.md)

* [AiSliceConfig](variables/AiSliceConfig.md)

* [ErrorMessageSchema](variables/ErrorMessageSchema.md)

* [AnalysisResultSchema](variables/AnalysisResultSchema.md)

* [AnalysisSessionSchema](variables/AnalysisSessionSchema.md)

* [AiThinkingDots](variables/AiThinkingDots.md)

* [AnalysisResult](variables/AnalysisResult.md)

* [AnalysisResultsContainer](variables/AnalysisResultsContainer.md)

* [Chat](variables/Chat.md)

* [ModelSelector](variables/ModelSelector.md)

* [PromptSuggestions](variables/PromptSuggestions.md)

* [QueryControls](variables/QueryControls.md)

* [SessionControls](variables/SessionControls.md)

* [ToolCallInfo](variables/ToolCallInfo.md)

* [DeleteSessionDialog](variables/DeleteSessionDialog.md)

* [SessionActions](variables/SessionActions.md)

* [SessionDropdown](variables/SessionDropdown.md)

* [SessionTitle](variables/SessionTitle.md)

* [AiModelParameters](variables/AiModelParameters.md)

* [AiModelUsage](variables/AiModelUsage.md)

* [AiModelsSettings](variables/AiModelsSettings.md)

* [AiProvidersSettings](variables/AiProvidersSettings.md)

* [AiSettingsPanel](variables/AiSettingsPanel.md)

## Functions

* [createCommandTools](functions/createCommandTools.md)

* [formatTablesForLLM](functions/formatTablesForLLM.md)

* [createDefaultAiInstructions](functions/createDefaultAiInstructions.md)

* [createDefaultAiTools](functions/createDefaultAiTools.md)

* [createDefaultAiToolRenderers](functions/createDefaultAiToolRenderers.md)

* [createQueryToolRenderer](functions/createQueryToolRenderer.md)

* [createQueryTool](functions/createQueryTool.md)

* [getQuerySummary](functions/getQuerySummary.md)

* [createDefaultAiConfig](functions/createDefaultAiConfig.md)

* [createAiSlice](functions/createAiSlice.md)

* [useStoreWithAi](functions/useStoreWithAi.md)

* [updateAgentToolCallData](functions/updateAgentToolCallData.md)

* [streamSubAgent](functions/streamSubAgent.md)

* [ErrorMessage](functions/ErrorMessage.md)

* [ToolErrorMessage](functions/ToolErrorMessage.md)

* [useScrollToBottom](functions/useScrollToBottom.md)

* [cleanupPendingAnalysisResults](functions/cleanupPendingAnalysisResults.md)

* [fixIncompleteToolCalls](functions/fixIncompleteToolCalls.md)

* [createAiSettingsSlice](functions/createAiSettingsSlice.md)

* [useStoreWithAiSettings](functions/useStoreWithAiSettings.md)

* [createDefaultAiSettingsConfig](functions/createDefaultAiSettingsConfig.md)

---

---

url: 'https://sqlrooms.org/api/ai-config.md'

---

# @sqlrooms/ai-config

## Type Aliases

* [AiSettingsSliceConfig](type-aliases/AiSettingsSliceConfig.md)

* [AiSliceConfig](type-aliases/AiSliceConfig.md)

* [ErrorMessageSchema](type-aliases/ErrorMessageSchema.md)

* [AnalysisResultSchema](type-aliases/AnalysisResultSchema.md)

* [AnalysisSessionSchema](type-aliases/AnalysisSessionSchema.md)

* [ToolUIPart](type-aliases/ToolUIPart.md)

* [UIMessagePart](type-aliases/UIMessagePart.md)

* [DynamicToolUIPart](type-aliases/DynamicToolUIPart.md)

## Variables

* [AiSettingsSliceConfig](variables/AiSettingsSliceConfig.md)

* [AiSliceConfig](variables/AiSliceConfig.md)

* [ErrorMessageSchema](variables/ErrorMessageSchema.md)

* [AnalysisResultSchema](variables/AnalysisResultSchema.md)

* [AnalysisSessionSchema](variables/AnalysisSessionSchema.md)

## Functions

* [createDefaultAiConfig](functions/createDefaultAiConfig.md)

---

---

url: 'https://sqlrooms.org/api/ai-core.md'

---

# @sqlrooms/ai-core

Core AI slice, chat UI primitives, and tool-streaming utilities for SQLRooms.

Use `@sqlrooms/ai-core` when you want lower-level control over AI state/transport/UI.

For most apps, use the higher-level `@sqlrooms/ai` package.

## Installation

```bash

npm install @sqlrooms/ai-core @sqlrooms/room-store @sqlrooms/ui zod ai

```

`@sqlrooms/ui` is a peer dependency used for Chat UI rendering/styling.

You typically import Chat components from `@sqlrooms/ai-core`, but `@sqlrooms/ui` must be installed for the visual components to work.

## Store setup (core mode)

`createAiSlice` requires:

* `tools` – an AI SDK `ToolSet` (created via the `tool()` helper from `ai`)

* `getInstructions`

* `toolRenderers` (optional) – a `ToolRendererRegistry` mapping tool names to React components

> **Upgrading from 0.28.x?** See the [0.29.0 migration guide](https://sqlrooms.org/upgrade-guide#_0-29-0-upcoming) for the full list of breaking changes: `parameters` → `inputSchema`, `component` → `toolRenderers`, `setSessionToolAdditionalData` removed.

```tsx

import {

createAiSlice,

type AiSliceState,

type ToolRendererRegistry,

} from '@sqlrooms/ai-core';

import {

BaseRoomStoreState,

createBaseRoomSlice,

createRoomStore,

} from '@sqlrooms/room-store';

import {tool} from 'ai';

import {z} from 'zod';

const EchoResult = ({

output,

}: {

output: {success: boolean; text: string} | undefined;

}) => <div>{output?.text}</div>;

type State = BaseRoomStoreState & AiSliceState;

export const {roomStore, useRoomStore} = createRoomStore<State>(

(set, get, store) => ({

...createBaseRoomSlice()(set, get, store),

...createAiSlice({

getInstructions: () => 'You are a helpful analytics assistant.',

tools: {

echo: tool({

description: 'Echo text back',

inputSchema: z.object({text: z.string()}),

execute: async ({text}) => ({success: true, text: `Echo: ${text}`}),

}),

},

toolRenderers: {

echo: EchoResult,

},

})(set, get, store),

}),

);

```

## Chat UI

```tsx

import {Chat} from '@sqlrooms/ai-core';

export function AiPanel() {

return (

<Chat>

<Chat.Sessions />

<Chat.Messages />

<Chat.PromptSuggestions>

<Chat.PromptSuggestions.Item text="What trends should I investigate first?" />

</Chat.PromptSuggestions>

<Chat.Composer placeholder="Ask a question" />

</Chat>

);

}

```

## Useful exports

* Slice/hooks: `createAiSlice`, `useStoreWithAi`, `AiSliceState`

* Chat UI: `Chat`, `ModelSelector`, `QueryControls`, `PromptSuggestions`

* Legacy/compat components: `AnalysisResultsContainer`, `AnalysisResult`, `ErrorMessage`

* Types: `ToolRendererProps`, `ToolRenderer`, `ToolRendererRegistry`, `StoredTool`, `StoredToolSet`

* Tool/agent utilities:

* `cleanupPendingAnalysisResults`

* `fixIncompleteToolCalls`

* `streamSubAgent`

## Related packages

* `@sqlrooms/ai` (recommended high-level integration)

* `@sqlrooms/ai-settings` (provider/model settings slice + UI)

* `@sqlrooms/ai-config` (config schemas and migrations)

## Classes

* [ToolAbortError](classes/ToolAbortError.md)

## Interfaces

* [AiSliceOptions](interfaces/AiSliceOptions.md)

* [StoredTool](interfaces/StoredTool.md)

## Type Aliases

* [AiSliceConfig](type-aliases/AiSliceConfig.md)

* [AiSliceState](type-aliases/AiSliceState.md)

* [ErrorMessageComponentProps](type-aliases/ErrorMessageComponentProps.md)

* [HoistableToolCall](type-aliases/HoistableToolCall.md)

* [SessionType](type-aliases/SessionType.md)

* [AgentToolCall](type-aliases/AgentToolCall.md)

* [AgentToolCallAdditionalData](type-aliases/AgentToolCallAdditionalData.md)

* [AgentStreamOutput](type-aliases/AgentStreamOutput.md)

* [PendingSubAgentApproval](type-aliases/PendingSubAgentApproval.md)

* [AgentProgressSnapshot](type-aliases/AgentProgressSnapshot.md)

* [ToolTimingEntry](type-aliases/ToolTimingEntry.md)

* [MessageTokenUsage](type-aliases/MessageTokenUsage.md)

* [AssistantMessageMetadata](type-aliases/AssistantMessageMetadata.md)

* [StoredToolSet](type-aliases/StoredToolSet.md)

* [AddToolOutput](type-aliases/AddToolOutput.md)

* [AddToolApprovalResponse](type-aliases/AddToolApprovalResponse.md)

* [ToolRendererProps](type-aliases/ToolRendererProps.md)

* [ToolRenderer](type-aliases/ToolRenderer.md)

* [ToolRendererRegistry](type-aliases/ToolRendererRegistry.md)

* [ToolRenderers](type-aliases/ToolRenderers.md)

## Variables

* [AiSliceConfig](variables/AiSliceConfig.md)

* [ActivityBox](variables/ActivityBox.md)

* [AiThinkingDots](variables/AiThinkingDots.md)

* [AnalysisResult](variables/AnalysisResult.md)

* [AnalysisResultsContainer](variables/AnalysisResultsContainer.md)

* [Chat](variables/Chat.md)

* [ContextUsageIndicator](variables/ContextUsageIndicator.md)

* [ExpandableContent](variables/ExpandableContent.md)

* [OrchestratorToolLogLine](variables/OrchestratorToolLogLine.md)

* [FlatAgentRenderer](variables/FlatAgentRenderer.md)

* [HoistedRenderersProvider](variables/HoistedRenderersProvider.md)

* [ModelSelector](variables/ModelSelector.md)

* [PromptSuggestions](variables/PromptSuggestions.md)

* [QueryControls](variables/QueryControls.md)

* [SessionControls](variables/SessionControls.md)

* [ToolCallInfo](variables/ToolCallInfo.md)

* [DeleteSessionDialog](variables/DeleteSessionDialog.md)

* [SessionActions](variables/SessionActions.md)

* [SessionDropdown](variables/SessionDropdown.md)

* [SessionTitle](variables/SessionTitle.md)

## Functions

* [createDefaultAiConfig](functions/createDefaultAiConfig.md)

* [createAiSlice](functions/createAiSlice.md)

* [useStoreWithAi](functions/useStoreWithAi.md)

* [updateAgentToolCallData](functions/updateAgentToolCallData.md)

* [formatAbortSnapshot](functions/formatAbortSnapshot.md)

* [streamSubAgent](functions/streamSubAgent.md)

* [ErrorMessage](functions/ErrorMessage.md)

* [useHoistedRenderers](functions/useHoistedRenderers.md)

* [collectHoistableRenderers](functions/collectHoistableRenderers.md)

* [ToolErrorMessage](functions/ToolErrorMessage.md)

* [useElapsedTime](functions/useElapsedTime.md)

* [useScrollToBottom](functions/useScrollToBottom.md)

* [useSessionChat](functions/useSessionChat.md)

* [extractModelsFromSettings](functions/extractModelsFromSettings.md)

* [cleanupPendingAnalysisResults](functions/cleanupPendingAnalysisResults.md)

* [shouldEndAnalysis](functions/shouldEndAnalysis.md)

* [fixIncompleteToolCalls](functions/fixIncompleteToolCalls.md)

* [humanizeToolName](functions/humanizeToolName.md)

---

---

url: 'https://sqlrooms.org/api/ai-rag.md'

---

# @sqlrooms/ai-rag

Retrieval Augmented Generation (RAG) slice for SQLRooms. Query vector embeddings stored in DuckDB for semantic search and AI-powered applications.

This package is designed to work with [sqlrooms-rag](https://pypi.org/project/sqlrooms-rag/), a Python package that prepares embedding/FTS-index databases for RAG search.

Refer to the [ai-rag example](https://github.com/sqlrooms/examples/tree/main/ai-rag) for a complete working example.

## Features

* 🔍 **Hybrid Search** - Combines vector similarity with full-text search (BM25) using Reciprocal Rank Fusion

* 🚀 **Semantic Search** - Query embeddings using vector similarity (cosine similarity)

* 🗄️ **Multiple Databases** - Attach and search across multiple embedding databases

* 🎯 **Per-Database Embedding Providers** - Each database can use a different embedding model

* ✅ **Metadata Validation** - Automatic validation of embedding dimensions and models

* 📊 **DuckDB-Powered** - Fast, in-process vector search with SQL and FTS

* 🔄 **Flexible** - Works with OpenAI, HuggingFace, Transformers.js, or custom embeddings

## Installation

```bash

npm install @sqlrooms/ai-rag @sqlrooms/duckdb @sqlrooms/room-store

```

## Quick Start

```typescript

import {createDuckDbSlice} from '@sqlrooms/duckdb';

import {createRagSlice, createAiEmbeddingProvider} from '@sqlrooms/ai-rag';

import {createRoomStore} from '@sqlrooms/room-store';

import {openai} from '@ai-sdk/openai';

// 1. Create an embedding provider (matches your database preparation)

const embeddingProvider = createAiEmbeddingProvider(

openai,

'text-embedding-3-small',

1536,

);

// 2. Configure your embedding databases

const embeddingsDatabases = [

{

databaseFilePathOrUrl: '/path/to/docs.duckdb',

databaseName: 'docs',

embeddingProvider,

embeddingDimensions: 1536,

},

];

// 3. Create the store with RAG capabilities

const store = createRoomStore({

slices: [

createDuckDbSlice({databasePath: ':memory:'}),

createRagSlice({embeddingsDatabases}),

],

});

// 4. Initialize and query

await store.getState().rag.initialize();

const results = await store

.getState()

.rag.queryByText('How do I create a table?', {topK: 5});

console.log(results);

```

## RAG Tool Usage (AI Integration)

Use `createRagTool()` to expose semantic search as an AI tool in your `createAiSlice()` configuration.

```typescript

import {createRagSlice, createRagTool} from '@sqlrooms/ai-rag';

import {createAiSlice, createDefaultAiTools} from '@sqlrooms/ai';

import {createOpenAIEmbeddingProvider} from './embeddings';

// Create RAG slice (same store)

...createRagSlice({

embeddingsDatabases: [

{

databaseFilePathOrUrl:

window.location.origin + '/rag/duckdb_docs_openai.duckdb',

databaseName: 'duckdb_docs',

embeddingProvider: createOpenAIEmbeddingProvider(

'text-embedding-3-small',

1536,

() => get().aiSettings.config.providers?.['openai']?.apiKey,

),

embeddingDimensions: 1536,

},

],

})(set, get, store),

// Register RAG tool in AI tools map

...createAiSlice({

tools: {

...createDefaultAiTools(store, {query: {}}),

search_documentation: createRagTool(),

},

})(set, get, store),

// Make store available globally for rag tool execution

(globalThis as any).__ROOM_STORE__ = roomStore;

```

This is the same pattern used in `examples/ai-rag/src/store.ts`.

## API Reference

### `createRagSlice(options)`

Creates a RAG slice for your store.

#### Options

* `embeddingsDatabases` - Array of embedding database configurations

#### Returns

A state creator function for Zustand.

### `EmbeddingDatabase`

Configuration for an embedding database:

```typescript

type EmbeddingDatabase = {

/** Path or URL to the DuckDB embedding database file */

databaseFilePathOrUrl: string;

/** Name to use when attaching the database */

databaseName: string;

/**

* Embedding provider for this database.

* MUST match the model used during database preparation.

*/

embeddingProvider: EmbeddingProvider;

/**

* Expected embedding dimensions (for validation).

* Optional but recommended.

*/

embeddingDimensions?: number;

};

```

### `EmbeddingProvider`

Function that converts text to embeddings:

```typescript

type EmbeddingProvider = (text: string) => Promise<number[]>;

```

**Important**: The embedding provider MUST match the model used when preparing the database. Check your database metadata to ensure compatibility.

### Store Methods

#### `rag.initialize()`

Initialize RAG by attaching all embedding databases and validating metadata.

```typescript

await store.getState().rag.initialize();

```

#### `rag.queryByText(text, options)`

Query embeddings using text. By default, performs **hybrid search** combining vector similarity with full-text search (BM25) using Reciprocal Rank Fusion (RRF).

```typescript

const results = await store.getState().rag.queryByText('search query', {

topK: 5, // Number of results to return (default: 5)

database: 'docs', // Database to search (default: first database)

hybrid: true, // Enable hybrid search (default: true)

// hybrid: false, // Disable hybrid search (vector-only)

// hybrid: 60, // Custom RRF k value (default: 60)

});

```

**Hybrid Search** combines:

* **Vector similarity**: Semantic understanding of the query

* **Full-text search (BM25)**: Keyword matching and ranking

* **Reciprocal Rank Fusion**: Smart combination of both result sets

This approach typically provides better results than vector-only search, especially for queries with specific keywords or technical terms.

Returns:

```typescript

type EmbeddingResult = {

score: number; // Cosine similarity (0-1, higher is better)

text: string; // The matched text chunk

nodeId: string; // Unique identifier for the chunk

metadata?: Record<string, unknown>; // Optional metadata (file path, etc.)

};

```

#### `rag.queryEmbeddings(embedding, options)`

Query embeddings using a pre-computed embedding vector.

```typescript

const embedding = await embeddingProvider('search query');

const results = await store.getState().rag.queryEmbeddings(embedding, {

topK: 5,

database: 'docs',

});

```

#### `rag.getMetadata(databaseName)`

Get metadata for a specific database:

```typescript

const metadata = await store.getState().rag.getMetadata('docs');

console.log(metadata);

// {

// provider: 'openai',

// model: 'text-embedding-3-small',

// dimensions: 1536,

// chunkingStrategy: 'markdown-aware'

// }

```

#### `rag.listDatabases()`

List all attached embedding databases:

```typescript

const databases = store.getState().rag.listDatabases();

console.log(databases); // ['docs', 'tutorials', 'api']

```

## Multiple Databases

You can attach multiple embedding databases, each with its own embedding model:

```typescript

import {openai} from '@ai-sdk/openai';

import {google} from '@ai-sdk/google';

import {createAiEmbeddingProvider} from '@sqlrooms/ai-rag';

const embeddingsDatabases = [

{

databaseFilePathOrUrl: '/data/duckdb_docs.duckdb',

databaseName: 'duckdb_docs',

// OpenAI text-embedding-3-small (1536d)

embeddingProvider: createAiEmbeddingProvider(

openai,

'text-embedding-3-small',

1536,

),

embeddingDimensions: 1536,

},

{

databaseFilePathOrUrl: '/data/react_docs.duckdb',

databaseName: 'react_docs',

// OpenAI text-embedding-3-small with reduced dimensions (512d)

embeddingProvider: createAiEmbeddingProvider(

openai,

'text-embedding-3-small',

512,

),

embeddingDimensions: 512,

},

{

databaseFilePathOrUrl: '/data/python_docs.duckdb',

databaseName: 'python_docs',

// Google text-embedding-004 (768d)

embeddingProvider: createAiEmbeddingProvider(

google,

'text-embedding-004',

768,

),

embeddingDimensions: 768,

},

];

```

Query a specific database:

```typescript

// Query DuckDB docs

const duckdbResults = await store

.getState()

.rag.queryByText('How to create a table?', {

database: 'duckdb_docs',

});

// Query React docs

const reactResults = await store

.getState()

.rag.queryByText('How to use hooks?', {

database: 'react_docs',

});

```

## Hybrid Search

Hybrid search combines vector similarity (semantic understanding) with full-text search (keyword matching) to provide more accurate and comprehensive results.

### How It Works

1. **Vector Search**: Uses embedding similarity to find semantically related content

2. **Full-Text Search (BM25)**: Uses DuckDB's FTS extension for keyword-based ranking

3. **Reciprocal Rank Fusion (RRF)**: Intelligently combines both result sets

### Benefits

* **Better Recall**: Finds results even when exact keywords aren't in the query

* **Improved Precision**: Keyword matching helps rank exact matches higher

* **Balanced Results**: RRF prevents either method from dominating unfairly

### Configuration

```typescript

// Default: Hybrid search enabled with k=60

const results = await store.getState().rag.queryByText('query', {

hybrid: true, // Enable hybrid search (default)

});

// Pure vector search only

const vectorOnly = await store.getState().rag.queryByText('query', {

hybrid: false, // Disable hybrid search

});

// Custom RRF k value (lower = more weight to top-ranked results)

const customRRF = await store.getState().rag.queryByText('query', {

hybrid: 60, // Custom k value for Reciprocal Rank Fusion

});

```

### When to Use What

* **Hybrid (default)**: Best for most use cases, especially technical documentation

* **Vector-only**: When you want pure semantic matching without keyword bias

* **Lower k value** (e.g., 30): Give more weight to top-ranked results

* **Higher k value** (e.g., 100): More balanced combination, less bias to top results

### Requirements

Hybrid search requires that the embedding database was prepared with FTS indexing enabled (which is the default in the Python `prepare-embeddings` command). If FTS is not available, the system automatically falls back to vector-only search.

## Embedding Providers

The `createAiEmbeddingProvider()` function works with any provider from the Vercel AI SDK.

### OpenAI

```typescript

import {openai} from '@ai-sdk/openai';

import {createAiEmbeddingProvider} from '@sqlrooms/ai-rag';

const embeddingProvider = createAiEmbeddingProvider(

openai,

'text-embedding-3-small',

1536,

);

```

### Google

```typescript

import {google} from '@ai-sdk/google';

import {createAiEmbeddingProvider} from '@sqlrooms/ai-rag';

const embeddingProvider = createAiEmbeddingProvider(

google,

'text-embedding-004',

768,

);

```

### Custom Provider

```typescript

import {createAiEmbeddingProvider} from '@sqlrooms/ai-rag';

// Any provider that implements the AiProvider interface

const embeddingProvider = createAiEmbeddingProvider(

myCustomProvider,

'my-model-id',

512,

);

```

### Multiple Providers Example

You can use different providers for different databases:

```typescript

import {openai} from '@ai-sdk/openai';

import {google} from '@ai-sdk/google';

import {createAiEmbeddingProvider} from '@sqlrooms/ai-rag';

const embeddingsDatabases = [

{

databaseName: 'docs_openai',

databaseFilePathOrUrl: './embeddings/docs_openai.duckdb',

embeddingProvider: createAiEmbeddingProvider(

openai,

'text-embedding-3-small',

1536,

),

embeddingDimensions: 1536,

},

{

databaseName: 'docs_google',

databaseFilePathOrUrl: './embeddings/docs_google.duckdb',

embeddingProvider: createAiEmbeddingProvider(

google,

'text-embedding-004',

768,

),

embeddingDimensions: 768,

},

];

```

## Preparing Databases

Use the Python `sqlrooms_rag` package to prepare embedding databases:

```bash

# Install the package

pip install sqlrooms-rag

# Prepare embeddings with OpenAI

python -m sqlrooms_rag.cli prepare-embeddings \

docs/ \

-o embeddings.duckdb \

--provider openai \

--model text-embedding-3-small \

--embed-dim 1536

# Prepare embeddings with HuggingFace (local, free)

python -m sqlrooms_rag.cli prepare-embeddings \

docs/ \

-o embeddings.duckdb \

--provider huggingface \

--model BAAI/bge-small-en-v1.5

```

See the [Python package documentation](../../python/rag/README.md) for more details.

## Database Schema

The embedding databases created by `sqlrooms_rag` have the following structure:

```sql

-- Main documents table with embeddings

CREATE TABLE documents (

node_id VARCHAR PRIMARY KEY,

text TEXT,

metadata_ JSON,

embedding FLOAT[], -- Vector embedding

doc_id VARCHAR -- Link to source document

);

-- Original source documents (full, unchunked)

CREATE TABLE source_documents (

doc_id VARCHAR PRIMARY KEY,

file_path VARCHAR,

file_name VARCHAR,

text TEXT,

metadata_ JSON,

created_at TIMESTAMP

);

-- Metadata about the embedding process

CREATE TABLE embedding_metadata (

key VARCHAR PRIMARY KEY,

value VARCHAR,

created_at TIMESTAMP

);

```

## Error Handling

```typescript

try {

const results = await store.getState().rag.queryByText('search query', {

database: 'nonexistent',

});

} catch (error) {

// Error: Database "nonexistent" not found. Available: docs, tutorials

}

try {

const wrongDimEmbedding = new Array(384).fill(0);

await store.getState().rag.queryEmbeddings(wrongDimEmbedding, {

database: 'docs', // Expects 1536 dimensions

});

} catch (error) {

// Error: Dimension mismatch: query has 384 dimensions,

// but database "docs" expects 1536 dimensions

}

```

## Best Practices

1. **Match Embedding Models**: Always use the same embedding model and dimensions when querying as when preparing the database.

2. **Check Metadata**: Use `getMetadata()` to verify the model and dimensions before querying.

3. **Dimension Validation**: Provide `embeddingDimensions` in your database configuration for automatic validation.

4. **Database Naming**: Use descriptive database names (e.g., `duckdb_docs`, `react_docs`) to easily identify them.

5. **Error Handling**: Always wrap queries in try-catch blocks to handle dimension mismatches and missing databases.

6. **Performance**: For large databases, consider using reduced dimensions (e.g., 512 instead of 1536) for faster queries and lower costs.

## Examples

See the [examples/ai](_media/ai) directory for complete examples:

* `src/embeddings.ts` - OpenAI embedding provider implementations

* `src/rag-example.ts` - Comprehensive usage examples

* `src/store.ts` - Store configuration with RAG

## License