> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exulu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API reference
> Complete method and property reference for ExuluContext
## Constructor
```typescript theme={null}
const context = new ExuluContext(options: ExuluContextOptions);
```
Creates a new ExuluContext instance. See the [configuration guide](/core/exulu-context/configuration) for all available options.
## Item management methods
### createItem()
Creates a new item in the context. Optionally triggers processor and embeddings generation.
```typescript theme={null}
async createItem(
item: Item,
config: ExuluConfig,
user?: number,
role?: string,
upsert?: boolean,
generateEmbeddingsOverwrite?: boolean
): Promise<{ item: Item; job?: string }>
```
Item data matching the context's field schema
ExuluApp configuration object
User ID for access control and tracking
Role ID for access control
If `true`, update existing item if `id` or `external_id` matches (default: `false`)
Override the `calculateVectors` configuration for this operation
The created item with generated `id`
Comma-separated job IDs if processor or embeddings were queued
```typescript theme={null}
const { item, job } = await context.createItem(
{
external_id: "doc-123",
name: "Getting Started",
content: "Welcome to our platform...",
category: "guide"
},
config,
userId
);
console.log(`Created item ${item.id}`);
if (job) {
console.log(`Queued jobs: ${job}`);
}
```
When `upsert: true`, the item is created if it doesn't exist, or updated if an item with the same `external_id` or `id` exists.
### updateItem()
Updates an existing item. Optionally triggers processor and embeddings generation.
```typescript theme={null}
async updateItem(
item: Item,
config: ExuluConfig,
user?: number,
role?: string,
generateEmbeddingsOverwrite?: boolean
): Promise<{ item: Item; job?: string }>
```
Item data with `id` field and fields to update
ExuluApp configuration object
User ID for access control and tracking
Role ID for access control
Override the `calculateVectors` configuration
The updated item
Comma-separated job IDs if processor or embeddings were queued
```typescript theme={null}
const { item } = await context.updateItem(
{
id: "123e4567-e89b-12d3-a456-426614174000",
content: "Updated content...",
category: "reference"
},
config,
userId
);
```
### deleteItem()
Deletes an item and its associated chunks.
```typescript theme={null}
async deleteItem(
item: Item,
user?: number,
role?: string
): Promise<{ id: string; job?: string }>
```
Item with `id` or `external_id` to delete
User ID for tracking
Role ID for access control
ID of the deleted item
```typescript theme={null}
await context.deleteItem({
id: "123e4567-e89b-12d3-a456-426614174000"
});
```
This permanently deletes the item and all its embedding chunks. This operation cannot be undone.
### getItem()
Retrieves a single item by ID or external ID.
```typescript theme={null}
async getItem({ item }: { item: Item }): Promise-
```
Object with `id` or `external_id` field
The item with all fields and `chunksCount` property
```typescript theme={null}
const item = await context.getItem({
item: { id: "123e4567-e89b-12d3-a456-426614174000" }
});
// Or by external_id
const item = await context.getItem({
item: { external_id: "doc-123" }
});
console.log(`Item has ${item.chunksCount} chunks`);
```
This method does not apply access control. You are responsible for implementing access control in your application.
### getItems()
Retrieves multiple items with optional filters.
```typescript theme={null}
async getItems({
filters,
fields
}: {
filters?: any[];
fields?: string[];
}): Promise
```
Array of filter conditions (field, operator, value)
Array of field names to return (default: all fields)
Array of items matching the filters
```typescript theme={null}
const items = await context.getItems({
filters: [
{ field: "category", operator: "=", value: "guide" },
{ field: "archived", operator: "=", value: false }
],
fields: ["id", "name", "category"]
});
```
### deleteAll()
Deletes all items and chunks from the context.
```typescript theme={null}
async deleteAll(): Promise<{
count: number;
results: any;
errors?: string[];
}>
```
Number of items deleted
Deletion results
```typescript theme={null}
await context.deleteAll();
```
This is a destructive operation that deletes all data in the context. Use with extreme caution.
## Search methods
### search()
Performs semantic, keyword, or hybrid search on the context.
```typescript theme={null}
async search(options: SearchOptions): Promise
```
Natural language search query
Specific keywords to search for
Search method: `"cosineDistance"`, `"tsvector"`, or `"hybridSearch"`
Filters to apply to items table
Filters to apply to chunks table
User object for access control
Role for access control
Maximum number of results to return
Page number for pagination (1-indexed)
Sort configuration
Trigger source for tracking: `"agent"`, `"api"`, `"processor"`, etc.
Override default cutoff scores
Override default chunk expansion
Array of matching chunks with metadata
Context metadata (name, id, embedder)
The search query used
The keywords used
The search method used
```typescript theme={null}
const results = await context.search({
query: "How do I configure authentication?",
keywords: ["auth", "config"],
method: "hybridSearch",
itemFilters: [
{ field: "category", operator: "=", value: "guide" }
],
chunkFilters: [],
user: currentUser,
limit: 10,
page: 1,
sort: undefined,
trigger: "api"
});
results.chunks.forEach(chunk => {
console.log(chunk.chunk_content);
console.log(chunk.item_name);
console.log(chunk.chunk_metadata);
});
```
```typescript theme={null}
method: "hybridSearch"
```
Combines semantic and keyword search. Best for most queries.
```typescript theme={null}
method: "cosineDistance"
```
Pure vector similarity search. Best for conceptual queries.
```typescript theme={null}
method: "tsvector"
```
Full-text keyword search. Best for exact terms and IDs.
## Embeddings methods
### embeddings.generate.one()
Generates embeddings for a single item.
```typescript theme={null}
async embeddings.generate.one({
item,
user,
role,
trigger,
config
}: EmbeddingsGenerateOneOptions): Promise<{
id: string;
job?: string;
chunks?: number;
}>
```
Item to generate embeddings for (must have `id`)
User ID for tracking
Role for tracking
Trigger source: `"agent"`, `"api"`, `"processor"`, etc.
ExuluApp configuration
Item ID
Job ID if queued for background processing
Number of chunks generated (if not queued)
```typescript theme={null}
const { id, job, chunks } = await context.embeddings.generate.one({
item: { id: "123e4567-e89b-12d3-a456-426614174000" },
user: userId,
trigger: "api",
config: config
});
if (job) {
console.log(`Embeddings queued as job ${job}`);
} else {
console.log(`Generated ${chunks} chunks`);
}
```
### embeddings.generate.all()
Generates embeddings for all items in the context.
```typescript theme={null}
async embeddings.generate.all(
config: ExuluConfig,
userId?: number,
roleId?: string,
limit?: number
): Promise<{
jobs: string[];
items: number;
}>
```
ExuluApp configuration
User ID for tracking
Role ID for tracking
Maximum number of items to process
Array of job IDs if queued
Number of items processed
```typescript theme={null}
const { jobs, items } = await context.embeddings.generate.all(
config,
userId,
undefined,
1000 // Process first 1000 items
);
console.log(`Processing ${items} items in ${jobs.length} jobs`);
```
Without a queue configured, this method can only process up to 2,000 items. For larger datasets, configure the embedder with a queue.
## Processor methods
### processField()
Processes an item using the configured processor.
```typescript theme={null}
async processField(
trigger: STATISTICS_LABELS,
item: Item,
exuluConfig: ExuluConfig,
user?: number,
role?: string
): Promise<{
result: Item | undefined;
job?: string;
}>
```
Trigger source for tracking
Item to process
ExuluApp configuration
User ID for tracking
Role for access control
Processed item (undefined if queued or filtered out)
Job ID if queued for background processing
```typescript theme={null}
const { result, job } = await context.processField(
"api",
item,
config,
userId
);
if (job) {
console.log(`Processing queued as job ${job}`);
} else {
console.log("Processed result:", result);
}
```
This method is typically called automatically by `createItem()` and `updateItem()` when a processor is configured.
## Source methods
### executeSource()
Executes a data source to fetch and return items.
```typescript theme={null}
async executeSource(
source: ExuluContextSource,
inputs: any,
exuluConfig: ExuluConfig
): Promise
```
Source configuration to execute
Input parameters for the source
ExuluApp configuration
Array of items fetched from the source
```typescript theme={null}
const source = context.sources[0];
const items = await context.executeSource(
source,
{ since: "2024-01-01" },
config
);
console.log(`Fetched ${items.length} items from ${source.name}`);
```
## Table management methods
### createItemsTable()
Creates the database table for storing items.
```typescript theme={null}
async createItemsTable(): Promise
```
```typescript theme={null}
await context.createItemsTable();
```
This is typically called automatically by `db.init()` when initializing the database. You rarely need to call it manually.
### createChunksTable()
Creates the database table for storing embedding chunks.
```typescript theme={null}
async createChunksTable(): Promise
```
```typescript theme={null}
await context.createChunksTable();
```
This method requires an embedder to be configured, as it uses the embedder's vector dimensions to create the table schema.
### tableExists()
Checks if the items table exists in the database.
```typescript theme={null}
async tableExists(): Promise
```
```typescript theme={null}
const exists = await context.tableExists();
if (!exists) {
await context.createItemsTable();
}
```
### chunksTableExists()
Checks if the chunks table exists in the database.
```typescript theme={null}
async chunksTableExists(): Promise
```
```typescript theme={null}
const exists = await context.chunksTableExists();
```
## Tool generation
### tool()
Exports the context as a tool that agents can use.
```typescript theme={null}
tool(): ExuluTool | null
```
Tool instance or `null` if `enableAsTool: false`
```typescript theme={null}
const tool = context.tool();
if (tool) {
console.log(tool.name); // "{context_name}_context_search"
console.log(tool.description);
}
```
This method is called automatically by ExuluApp when registering contexts. The generated tool is added to the tools registry.
## Internal methods
### createAndUpsertEmbeddings()
Internal method that generates embeddings and upserts chunks into the database.
```typescript theme={null}
async createAndUpsertEmbeddings(
item: Item,
config: ExuluConfig,
user?: number,
statistics?: ExuluStatisticParams,
role?: string,
job?: string
): Promise<{
id: string;
chunks?: number;
job?: string;
}>
```
This is an internal method. Use `embeddings.generate.one()` instead.
## Properties
### id
Unique context identifier
```typescript theme={null}
console.log(context.id); // "product_docs"
```
### name
Human-readable context name
```typescript theme={null}
console.log(context.name); // "Product Documentation"
```
### description
Context description
### active
Whether the context is active
### fields
Array of field definitions
```typescript theme={null}
context.fields.forEach(field => {
console.log(`${field.name}: ${field.type}`);
});
```
### embedder
Configured embedder instance
### processor
Configured processor
### sources
Array of data sources
### configuration
Context configuration object
```typescript theme={null}
console.log(context.configuration.maxRetrievalResults);
console.log(context.configuration.calculateVectors);
```
## Usage examples
### Complete CRUD workflow
```typescript theme={null}
// Create
const { item } = await context.createItem(
{
name: "Getting Started Guide",
content: "This guide helps you...",
category: "guide"
},
config,
userId
);
// Read
const retrieved = await context.getItem({ item: { id: item.id } });
// Update
await context.updateItem(
{
id: item.id,
content: "Updated content..."
},
config,
userId
);
// Search
const results = await context.search({
query: "getting started",
method: "hybridSearch",
itemFilters: [],
chunkFilters: [],
limit: 10,
page: 1,
sort: undefined,
trigger: "api"
});
// Delete
await context.deleteItem({ id: item.id });
```
### Bulk embeddings generation
```typescript theme={null}
// Generate embeddings for specific items
const items = await context.getItems({
filters: [
{ field: "embeddings_updated_at", operator: "IS", value: null }
]
});
for (const item of items) {
await context.embeddings.generate.one({
item,
trigger: "api",
config
});
}
// Or generate for all items
await context.embeddings.generate.all(config);
```
### Custom search with filters
```typescript theme={null}
const results = await context.search({
query: "authentication configuration",
keywords: ["oauth", "jwt"],
method: "hybridSearch",
itemFilters: [
{ field: "category", operator: "=", value: "guide" },
{ field: "archived", operator: "=", value: false }
],
chunkFilters: [],
user: currentUser,
role: currentUser.role.id,
limit: 20,
page: 1,
sort: undefined,
trigger: "api",
cutoffs: {
hybrid: 0.7 // Higher relevance threshold
},
expand: {
before: 2,
after: 2 // More context
}
});
```