Functions and types

This page documents the top-level functions, enums, and types exported from @exulu/backend that are not part of a class. For class APIs see the Core classes and the other reference pages in this section.

Functions

defaultChunker

import { defaultChunker } from "@exulu/backend";

The built-in ChunkerOperation used when a context configures an embedding model but does not provide a custom chunker. It runs the SentenceChunker over the item’s primary text content — checking content, then description, prefixed by name — and respects maxChunkSize as the per-chunk token budget. Use defaultChunker directly when you want to invoke the standard chunking logic from a custom processor or in tests.

const result = await defaultChunker(item, 512, { storage });
// result.chunks: Array<{ content: string; index: number; metadata?: Record<string, unknown> }>

See ExuluChunkers for the full suite of built-in chunkers.

enableLiteLLMClientMode

import { enableLiteLLMClientMode } from "@exulu/backend";

Switches the current process into LiteLLM client mode: instead of spawning and supervising its own proxy, the process connects to a proxy managed by a separate process (typically the IMP HTTP server). Call this once at the very start of a worker or CLI process that shares a proxy with a running IMP server. Without it, the worker would attempt to spawn its own proxy on LITELLM_PORT — colliding with the server’s process — or fail with “package root not set”.

// worker-boot.ts — must be the first call
import { enableLiteLLMClientMode } from "@exulu/backend";
enableLiteLLMClientMode();

// Now safe to import anything that uses LiteLLM
import { ExuluQueues } from "@exulu/backend";

enableLiteLLMClientMode is a no-op when the current process has already started its own supervisor (e.g. a combined server + worker process). It is idempotent. See Self-hosting / LiteLLM for deployment context.

postgresClient

import { postgresClient } from "@exulu/backend";

const { db } = await postgresClient();

Returns a memoized Knex instance connected to the IMP Postgres database. On first call, creates the database if it does not exist (using POSTGRES_DB_NAME, defaulting to "exulu"). Subsequent calls return the cached connection. db is a Knex instance with pgvector registered, so vector operations (db.raw('... <=> ?', [vector])) work out of the box.

const { db } = await postgresClient();
const users = await db.from("users").select("id", "email").limit(10);

The connection pool defaults to min: 2, max: 4. Connection timeouts, SSL, and credentials are read from environment variables (POSTGRES_DB_HOST, POSTGRES_DB_PORT, POSTGRES_DB_USER, POSTGRES_DB_PASSWORD, POSTGRES_DB_SSL).

Enums

EXULU_STATISTICS_TYPE_ENUM

import { EXULU_STATISTICS_TYPE_ENUM } from "@exulu/backend";

String enum for the platform’s statistics event types, used as the type field in the statistics table.

Key	Value
`CONTEXT_RETRIEVE`	`"CONTEXT_RETRIEVE"`
`SOURCE_UPDATE`	`"SOURCE_UPDATE"`
`EMBEDDER_UPSERT`	`"EMBEDDER_UPSERT"`
`EMBEDDER_GENERATE`	`"EMBEDDER_GENERATE"`
`EMBEDDER_DELETE`	`"EMBEDDER_DELETE"`
`WORKFLOW_RUN`	`"WORKFLOW_RUN"`
`CONTEXT_UPSERT`	`"CONTEXT_UPSERT"`
`TOOL_CALL`	`"TOOL_CALL"`
`AGENT_RUN`	`"AGENT_RUN"`

The corresponding TypeScript union type is EXULU_STATISTICS_TYPE.

EXULU_JOB_STATUS_ENUM

import { EXULU_JOB_STATUS_ENUM } from "@exulu/backend";

String enum for BullMQ job statuses, used when querying the jobs table or filtering on queue inspector results.

Key	Value
`completed`	`"completed"`
`failed`	`"failed"`
`delayed`	`"delayed"`
`active`	`"active"`
`waiting`	`"waiting"`
`paused`	`"paused"`
`stuck`	`"stuck"`

The corresponding TypeScript union type is EXULU_JOB_STATUS.

Types

ChunkerOperation

type ChunkerOperation = (
  item: Item & { id: string },
  maxChunkSize: number,
  utils: { storage: ExuluStorage },
) => Promise<ChunkerResponse>;

The function signature for a custom chunker. Implement this type and pass the result as the chunker option of an ExuluContext embedder config. utils.storage is available for chunkers that need to read files from object storage (e.g. to extract text from a PDF before chunking).

ChunkerResponse

type ChunkerResponse = {
  item: Item & { id: string };
  chunks: {
    content: string;
    index: number;
    metadata?: Record<string, unknown>;
  }[];
};

The return value of a ChunkerOperation. metadata is stored in a Postgres JSONB column — any JSON-serializable value is accepted (e.g. a page number from a PDF chunker).

ExuluContextEmbedder

type ExuluContextEmbedder = {
  model: string;
  queue?: Promise<ExuluQueueConfig>;
};

The embedder configuration on an ExuluContext. model is the LiteLLM model_name of the embedding model (declared in config.litellm.yaml). When queue is provided, embedding jobs run in the background via BullMQ.

ExuluAgent

interface ExuluAgent {
  id: string;
  name: string;
  type: "agent";
  source: "code" | "database";
  model?: string;
  instructions?: string;
  description?: string;
  memory?: string;
  welcomemessage?: string;
  defaultagent?: boolean;
  active?: boolean;
  feedback?: boolean;
  suggestions_enabled?: boolean;
  sandbox_enabled?: boolean;
  max_tool_steps?: number | null;
  slug?: string;
  tools?: { id: string; type: string; config: { name: string; variable: string; type: string }[]; name: string; description: string }[];
  skills?: { id: string; name: string; /* ... */ }[];
  workflows?: ExuluProviderWorkflowConfig;
  // ... additional fields
}

The database agent record, extended with hydrated relations. Named ExuluAgent at the package boundary (the internal type is agent.ts:ExuluAgent). Passed to tool execute functions, ExuluEval.run, ExuluReranker.rerank, and other contexts where the calling agent’s identity is needed.

VectorSearchChunkResult

type VectorSearchChunkResult = {
  chunk_content: string;
  chunk_index: number;
  chunk_id: string;
  chunk_source: string;
  chunk_metadata: Record<string, string>;
  chunk_created_at: string;
  chunk_updated_at: string;
  item_id: string;
  item_external_id: string;
  item_name: string;
  item_updated_at: string;
  item_created_at: string;
  chunk_cosine_distance?: number;
  chunk_fts_rank?: number;
  chunk_hybrid_score?: number;
  chunk_entities?: { id: string; name: string; type: string }[];
  context?: { name: string; id: string };
};

The shape returned by ExuluContext.search(), ExuluReadApi.authorizedRead(), and passed to ExuluReranker.rerank(). chunk_entities is present only when the entity layer is enabled for the context.

ExuluAuthConfig

type ExuluAuthConfig = ExuluOauthConfig | ExuluUserCredentialsConfig;

The discriminated union accepted by the authentication field of an ExuluTool. The active arm is selected by authType: "oauth" for the 3-legged OAuth 2.0 flow and "user_credentials" for the form-based credential prompt flow. See ExuluTool — configuration for the full authentication option guide.

ExuluOauthConfig

interface ExuluOauthConfig {
  authType: "oauth";
  provider: string;
  authorizationUrl: string;
  tokenUrl: string;
  clientId: string;
  clientSecret: string;
  scopes: readonly string[];
  pkce?: boolean;
  extraAuthParams?: Record<string, string>;
}

OAuth 2.0 configuration for an ExuluTool. When a tool is constructed with an authentication property set to this type, IMP wraps its execute to require a valid access token. provider lets multiple tools share the same token under one consent grant — tools with the same provider string share a single OAuth connection per user, rather than each requiring its own consent screen. All values are declared in code; none are exposed as admin-configurable tool config. pkce defaults to true (S256); set it to false for providers that reject PKCE. See ExuluTool — introduction for the full OAuth integration guide.

ExuluUserCredentialsConfig

interface ExuluUserCredentialsConfig {
  authType: "user_credentials";
  provider: string;
  fields: CredentialField[];
  validate?: (values: Record<string, string>) => Promise<void>;
}

User-credentials configuration for an ExuluTool. When a tool is constructed with an authentication property set to this type, IMP presents the user with a form before the first tool call, stores the submitted values encrypted, and injects them into execute as inputs.credentials. provider namespaces the stored credentials — tools sharing the same provider share a single stored credential set per user. validate is an optional async function called after the user submits; throw any Error to reject the submission with the error message.

CredentialField

interface CredentialField {
  name: string;
  label: string;
  type: "text" | "password";
  placeholder?: string;
  help?: string;
}

One field in the credential-collection form rendered when ExuluUserCredentialsConfig is active. name is the key used in the credentials record injected into execute. type: "password" masks the input and is appropriate for API keys and secrets. placeholder and help are optional UI hints shown beneath the field.

ExuluOauthToolContext

type ExuluOauthToolContext = {
  accessToken: string;
  expiresAt: Date | null;
  scopes: string | null;
};

The OAuth context injected into an OAuth-enabled tool’s execute inputs as inputs.oauth. expiresAt is null when the provider did not report an expiry. scopes is the space-joined granted scope string when reported.

ExuluCredentialsToolContext

interface ExuluCredentialsToolContext {
  userId: string;
  provider: string;
  credentials: Record<string, string>;
}

Exported envelope type describing the shape of the user-credentials context. At runtime, only the plain credentials field is injected into a tool’s execute inputs as inputs.credentials — a Record<string, string> keyed by the name values declared in ExuluUserCredentialsConfig.fields. The userId and provider fields are part of the exported type definition and match what is documented on the configuration page and in the tutorial, but the injected runtime value is the plain record, not the full interface.

CredentialInvalidError

class CredentialInvalidError extends Error {
  readonly provider: string;
  readonly reason?: string;
  constructor(provider: string, reason?: string);
}

Thrown from a tool’s execute function to signal that a stored credential is no longer valid (e.g. a 401 from the upstream API). When IMP’s wrapExecuteWithAuth catches a CredentialInvalidError whose provider matches the tool’s configured provider, it deletes the stored credential and immediately re-prompts the user with a fresh form. Errors from a different provider are re-thrown unchanged. Construct with the tool’s authentication.provider and an optional human-readable reason string.

ExuluItem

type ExuluItem = {
  id?: string;
  name?: string;
  description?: string;
  createdAt?: string;
  updatedAt?: string;
  external_id?: string;
  source?: string;
  tags?: string[];
  textlength?: number;
  last_processed_at?: string;
  chunks?: { id: string; index: number; content: string; source: string; createdAt: string; updatedAt: string }[];
  [key: string]: any;
};

The base record shape for items stored in a knowledge context. Re-exported from @EXULU_TYPES/models/item as ExuluItem for package consumers. The index signature ([key: string]: any) accommodates context-specific custom fields defined in ExuluContext.fields.

Start

Tutorials

Recipes

Core classes

Reference

Functions and types

Functions

defaultChunker

enableLiteLLMClientMode

postgresClient

Enums

EXULU_STATISTICS_TYPE_ENUM

EXULU_JOB_STATUS_ENUM

Types

ChunkerOperation

ChunkerResponse

ExuluContextEmbedder

ExuluAgent

VectorSearchChunkResult

ExuluAuthConfig

ExuluOauthConfig

ExuluUserCredentialsConfig

CredentialField

ExuluOauthToolContext

ExuluCredentialsToolContext

CredentialInvalidError

ExuluItem

​Functions

​defaultChunker

​enableLiteLLMClientMode

​postgresClient

​Enums

​EXULU_STATISTICS_TYPE_ENUM

​EXULU_JOB_STATUS_ENUM

​Types

​ChunkerOperation

​ChunkerResponse

​ExuluContextEmbedder

​ExuluAgent

​VectorSearchChunkResult

​ExuluAuthConfig

​ExuluOauthConfig

​ExuluUserCredentialsConfig

​CredentialField

​ExuluOauthToolContext

​ExuluCredentialsToolContext

​CredentialInvalidError

​ExuluItem

Functions

defaultChunker

enableLiteLLMClientMode

postgresClient

Enums

EXULU_STATISTICS_TYPE_ENUM

EXULU_JOB_STATUS_ENUM

Types

ChunkerOperation

ChunkerResponse

ExuluContextEmbedder

ExuluAgent

VectorSearchChunkResult

ExuluAuthConfig

ExuluOauthConfig

ExuluUserCredentialsConfig

CredentialField

ExuluOauthToolContext

ExuluCredentialsToolContext

CredentialInvalidError

ExuluItem