API reference

const context = new ExuluContext(options);

search(options: {
  query?: string;
  keywords?: string[];
  itemFilters: SearchFilters;
  chunkFilters: SearchFilters;
  user?: User;
  role?: string;
  method: VectorMethod;          // "cosineDistance" | "tsvector" | "hybridSearch"
  sort: any;
  trigger: STATISTICS_LABELS;    // "tool" | "agent" | "flow" | "api" | "claude-code" | "user" | "processor"
  limit: number;
  page: number;
  cutoffs?: { cosineDistance?: number; tsvector?: number; hybrid?: number };
  expand?: { before?: number; after?: number };
  entityFilter?: EntityFilter;
  queryEmbedding?: number[];
}): Promise<{
  itemFilters: SearchFilters;
  chunkFilters: SearchFilters;
  query?: string;
  keywords?: string[];
  method: VectorMethod;
  context: { name: string; id: string; embedder: string };
  chunks: VectorSearchChunkResult[];
  entityInsights?: EntityInsights;
}>

const results = await context.search({
  query: "How do I configure authentication?",
  keywords: ["auth", "configuration"],
  method: "hybridSearch",
  itemFilters: [{ category: { eq: "guide" } }],
  chunkFilters: [],
  user: currentUser,
  sort: undefined,
  trigger: "api",
  limit: 10,
  page: 1,
  expand: { before: 1, after: 2 },
});

for (const chunk of results.chunks) {
  console.log(chunk.item_name, chunk.chunk_hybrid_score, chunk.chunk_content);
}

createItem(
  item: Item,
  config: ExuluConfig,
  user?: number,
  role?: string,
  upsert?: boolean,
  generateEmbeddingsOverwrite?: boolean,
): Promise<{ item: Item; job?: string }>

const { item, job } = await context.createItem(
  {
    external_id: "doc-123",
    name: "Getting started",
    content: "Welcome to the platform…",
    category: "guide",
  },
  config,
  userId,
  undefined,
  true, // upsert on external_id
);

updateItem(
  item: Item,
  config: ExuluConfig,
  user?: number,
  role?: string,
  generateEmbeddingsOverwrite?: boolean,
  runProcessorOverwrite?: boolean,
): Promise<{ item: Item; job?: string }>

const { item, job } = await context.updateItem(
  { id: "123e4567-e89b-12d3-a456-426614174000", content: "Updated content…" },
  config,
  userId,
);

deleteItem(
  item: Item,
  user?: number,
  role?: string,
): Promise<{ id: string; job?: string }>

await context.deleteItem({ external_id: "doc-123" });

getItem({ item }: { item: Item }): Promise<Item>

const item = await context.getItem({ item: { external_id: "doc-123" } });
console.log(`${item.name} has ${item.chunksCount} chunks`);

getItems(options: {
  filters?: any[];
  fields?: string[];
  user?: User;
  role?: string;
}): Promise<Item[]>

const guides = await context.getItems({
  filters: [{ category: { eq: "guide" } }],
  fields: ["id", "name", "category"],
  user: currentUser,
});

deleteAll(): Promise<{ count: number; results: any; errors?: string[] }>

await context.deleteAll();

embeddings.generate.one(options: {
  item: Item;
  user?: number;
  role?: string;
  trigger: STATISTICS_LABELS;
  config: ExuluConfig;
}): Promise<{ id: string; job?: string; chunks?: number }>

const { job, chunks } = await context.embeddings.generate.one({
  item: { id: "123e4567-e89b-12d3-a456-426614174000" },
  user: userId,
  trigger: "api",
  config,
});

console.log(job ? `Queued as job ${job}` : `Wrote ${chunks} chunks`);

embeddings.generate.all(
  config: ExuluConfig,
  userId?: number,
  roleId?: string,
  limit?: number,
): Promise<{ jobs: string[]; items: number }>

const { jobs, items } = await context.embeddings.generate.all(config, userId, undefined, 1000);
console.log(`Processing ${items} items across ${jobs.length} jobs`);

createAndUpsertEmbeddings(
  item: Item,
  config: ExuluConfig,
  user?: number,
  statistics?: ExuluStatisticParams,
  role?: string,
  job?: string,
): Promise<{ id: string; chunks?: number; job?: string }>

processField(
  trigger: STATISTICS_LABELS,
  item: Item,
  exuluConfig: ExuluConfig,
  user?: number,
  role?: string,
): Promise<{ result: Item | undefined; job?: string }>

const { result, job } = await context.processField("api", item, config, userId);

executeSource(
  source: ExuluContextSource,
  inputs: any,
  exuluConfig: ExuluConfig,
): Promise<Item[]>

const source = context.sources[0];
const items = await context.executeSource(source, { since: "2026-01-01" }, config);
console.log(`Fetched ${items.length} items from ${source.name}`);

entityLayer.countStale(): Promise<number>

const stale = await context.entityLayer.countStale();

entityLayer.backfill(options?: {
  onlyStale?: boolean;   // default true
  limit?: number;        // safeguard cap, default 5000
}): Promise<{ processed: number; skipped: number }>

const { processed, skipped } = await context.entityLayer.backfill();

entityLayer.extractItem(itemId: string): Promise<{ extracted: number }>

entityLayer.detachItem(itemId: string): Promise<{ detached: number }>

entityLayer.purgeType(typeName: string): Promise<{ removed: number }>

await context.entityLayer.purgeType("Company");

createItemsTable(): Promise<void>

createChunksTable(): Promise<void>

tableExists(): Promise<boolean>

chunksTableExists(): Promise<boolean>

if (!(await context.tableExists())) {
  await context.createItemsTable();
}

console.log(context.id);                                  // "product_docs"
console.log(context.configuration.maxRetrievalResults);   // 10
console.log(context.fields.map((f) => `${f.name}: ${f.type}`));

// Create
const { item } = await context.createItem(
  { external_id: "doc-1", name: "Getting started", content: "This guide…", category: "guide" },
  config,
  userId,
);

// Read
const stored = await context.getItem({ item: { id: item.id } });

// Update (embeddings regenerate when calculateVectors is "onUpdate" or "always")
await context.updateItem({ id: item.id, content: "Updated content…" }, config, userId);

// Search
const results = await context.search({
  query: "getting started",
  method: "hybridSearch",
  itemFilters: [],
  chunkFilters: [],
  sort: undefined,
  trigger: "api",
  limit: 10,
  page: 1,
});

// Delete
await context.deleteItem({ id: item.id });