API reference - IMP Docs

All signatures on this page are verified against the current @exulu/backend source. For constructor-time options, see Configuration.

Constructor

const app = new ExuluApp();

Takes no parameters. The instance does nothing until you call create().

Lifecycle

create()

Initializes the app: merges built-in contexts, registers default providers, tools, and evals, validates IDs, checks the queue license, and probes system dependencies. See Introduction for the full behavior list.

create(options: {
  contexts?: Record<string, ExuluContext>;
  config: ExuluConfig;
  agents?: ExuluAgent[];
  providers?: ExuluProvider[];
  evals?: ExuluEval[];
  tools?: ExuluTool[];
}): Promise<ExuluApp>

options.config

ExuluConfig

required

Platform configuration. See Configuration.

options.contexts

Record<string, ExuluContext>

Contexts to register. Built-in contexts win on key collision.

options.agents

ExuluAgent[]

Code-defined agents, merged with database agents at read time.

options.providers

ExuluProvider[]

Custom providers, appended after the 19 defaults.

options.evals

ExuluEval[]

Custom evals. Only registered when Redis is configured.

options.tools

ExuluTool[]

Custom tools, registered ahead of the built-in tools.

return

Promise<ExuluApp>

The initialized instance (the same object you called create() on). It is also stored in an internal singleton.

const app = new ExuluApp();

await app.create({
  contexts: { product_docs: productDocsContext },
  config: {
    workers: { enabled: true },
    MCP: { enabled: false },
    telemetry: { enabled: false },
  },
  tools: [myCustomTool],
});

create() throws on invalid IDs, on registered queues without an Enterprise Edition license, and — unless requireSystemDependencies is false — on missing system dependencies.

express.init()

Builds and returns the Express application: registers the GraphQL and REST routes, sets up authentication middleware and logging, mounts the MCP endpoints when config.MCP.enabled is true, starts the LiteLLM proxy supervisor when EXULU_USE_LITELLM=true, and starts the transcription polling loop when TRANSCRIPTION_SERVER is set.

express.init(): Promise<Express>

return

Promise<Express>

The Express application, ready to listen() on a port. Calling express.init() again returns the same instance.

const server = await app.express.init();
server.listen(Number(process.env.PORT ?? 9001), () => {
  console.log("IMP backend listening on :9001");
});

If the LiteLLM supervisor fails to start, express.init() does not throw — the app keeps booting so the admin UI stays reachable, and agent requests fail with LITELLM_NOT_READY until the underlying issue is fixed and the process restarted.

expressApp

Getter for the initialized Express application.

get expressApp(): Express

return

Express

The Express application created by express.init().

const server = app.expressApp;

Throws if express.init() has not been called yet.

Component accessors

tool()

Returns a registered tool by ID.

tool(id: string): ExuluTool | undefined

string

required

The tool ID.

return

ExuluTool | undefined

The tool, or undefined if no tool with that ID is registered.

const todo = app.tool("todo_write");
if (todo) {
  console.log(todo.name);
}

tools()

Returns all registered tools: your custom tools plus the built-ins.

tools(): ExuluTool[]

return

ExuluTool[]

All registered tools.

console.log(`Registered ${app.tools().length} tools`);

context()

Returns a registered context by ID.

context(id: string): ExuluContext | undefined

string

required

The context ID.

return

ExuluContext | undefined

The context, or undefined if not registered.

const docs = app.context("product_docs");

contexts

Getter returning all registered contexts (yours plus built-ins) as an array.

get contexts(): ExuluContext[]

for (const context of app.contexts) {
  console.log(`${context.id}: ${context.name}`);
}

provider()

Returns a registered model provider by ID.

provider(id: string): ExuluProvider | undefined

string

required

The provider ID.

return

ExuluProvider | undefined

The provider, or undefined if not registered.

providers

Getter returning all registered providers — the 19 defaults plus any you passed to create().

get providers(): ExuluProvider[]

console.log(app.providers.map((p) => p.id));

agent()

Resolves an agent by ID. Unlike the other accessors, this is async: agents can be defined in code (passed to create()) or created in the database through the platform UI, and this method checks both.

agent(id: string, include?: {
  source: {
    code: boolean;
    database: boolean;
  };
}): Promise<ExuluAgent | undefined>

string

required

The agent ID.

include

object

default:"{ source: { code: true, database: true } }"

Which sources to check. Code-defined agents are checked first; database agents second.

return

Promise<ExuluAgent | undefined>

The agent with its RBAC block resolved. Code-defined agents without an explicit RBAC get a default public one and source: "code".

const agent = await app.agent("my_support_agent");

When the database source is included and no agent matches in either source, this method throws Agent instance not found. rather than returning undefined. It only returns undefined when the database lookup is excluded (include.source.database: false) and no code-defined agent matches.

agents()

Returns all agents. Also async — database agents are fetched and their RBAC resolved; code-defined agents are prepended with default public RBAC.

agents(include?: {
  source: {
    code: boolean;
    database: boolean;
  };
}): Promise<ExuluAgent[]>

include

object

default:"{ source: { code: true, database: true } }"

Which sources to include.

return

Promise<ExuluAgent[]>

Code-defined agents first, then database agents.

const agents = await app.agents();
console.log(agents.map((a) => `${a.name} (${a.id}, ${a.source ?? "database"})`));

Embeddings

App-level convenience wrappers around the per-context embedding methods. They resolve the context by ID and delegate to the context’s own embeddings methods.

embeddings.generate.one()

Loads one item from the context’s items table by ID and generates (or queues) its embeddings.

embeddings.generate.one(options: {
  context: string;
  item: string;
}): Promise<{ id: string; job?: string; chunks?: number }>

options.context

string

required

The context ID.

options.item

string

required

The item ID (UUID) within that context.

string

The item ID.

job

string

Job ID when the context’s embedder runs on a queue.

chunks

number

Number of chunks written when embeddings were generated inline.

const result = await app.embeddings.generate.one({
  context: "product_docs",
  item: "123e4567-e89b-12d3-a456-426614174000",
});

Throws if the context ID is not registered.

embeddings.generate.all()

Generates (or queues) embeddings for every item in a context.

embeddings.generate.all(options: {
  context: string;
}): Promise<{ jobs: string[]; items: number }>

options.context

string

required

The context ID.

jobs

string[]

Job IDs when the embedder runs on a queue.

items

number

Number of items processed.

await app.embeddings.generate.all({ context: "product_docs" });

Without a queue configured on the context’s embedder, this throws when the context holds more than 2,000 items. Configure embedder.queue for larger datasets.

Workers

bullmq.workers.create()

Starts BullMQ workers in the current process. Run this in a dedicated worker process, not inside the HTTP server.

bullmq.workers.create(queues?: string[]): Promise<Worker[]>

queues

string[]

Queue names this worker should listen to. When omitted, the worker listens to all registered queues.

return

Promise<Worker[]>

The BullMQ Worker instances, one per queue.

// Listen to all queues
await app.bullmq.workers.create();

// Or split workloads across processes
await app.bullmq.workers.create(["embeddings", "doc_processing"]);

What it does before starting the workers:

Checks the license — throws without a valid EXULU_ENTERPRISE_LICENSE covering queues.
Enables LiteLLM client mode — when EXULU_USE_LITELLM=true, the worker health-probes the server-managed proxy instead of spawning its own.
Configures worker logging — uses workers.logger.winston.transports, falling back to logger.winston.transports, then to the built-in console transport.
Creates context source schedulers — for every context source with a config.schedule cron expression and a queue, a BullMQ job scheduler is upserted with the source’s retries (default 3) and backoff (default exponential, 2000 ms).

Throws if create() has not resolved yet — always await the create() promise before starting workers.

Types

ExuluConfig

Documented in full in Configuration.

Create options

type CreateOptions = {
  contexts?: Record<string, ExuluContext>;
  config: ExuluConfig;
  agents?: ExuluAgent[];
  providers?: ExuluProvider[];
  evals?: ExuluEval[];
  tools?: ExuluTool[];
};

Putting it together

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

const app = new ExuluApp();
await app.create({
  contexts: { product_docs: productDocsContext },
  config: {
    workers: { enabled: true },
    MCP: { enabled: true },
    telemetry: { enabled: false },
  },
});

// Server process
const server = await app.express.init();
server.listen(9001);

// Inspect the registry
console.log("Contexts:", app.contexts.map((c) => c.id));
console.log("Providers:", app.providers.map((p) => p.id));
console.log("Tools:", app.tools().map((t) => t.id));
console.log("Agents:", (await app.agents()).map((a) => a.id));

// Kick off embeddings for a context
await app.embeddings.generate.all({ context: "product_docs" });

​Constructor

​Lifecycle

​create()

​express.init()

​expressApp

​Component accessors

​tool()

​tools()

​context()

​contexts

​provider()

​providers

​agent()

​agents()

​Embeddings

​embeddings.generate.one()

​embeddings.generate.all()

​Workers

​bullmq.workers.create()

​Types

​ExuluConfig

​Create options

​Putting it together

Constructor

Lifecycle

create()

express.init()

expressApp

Component accessors

tool()

tools()

context()

contexts

provider()

providers

agent()

agents()

Embeddings

embeddings.generate.one()

embeddings.generate.all()

Workers

bullmq.workers.create()

Types

ExuluConfig

Create options

Putting it together