@exulu/backend

Exulu IMP (Intelligence Management Platform) is an open-source TypeScript framework for building production-ready AI agent applications. It provides the backend infrastructure for managing agents, semantic search contexts, background job processing, and tool integrations.

📚 Explore the Docs  ·  💬 Community Help  ·  🗺️ Roadmap

[!IMPORTANT] ⭐ Star this repo to follow development and updates

✨ Why Exulu IMP?

• 🤖 Multi-provider agents - Built-in support for OpenAI, Anthropic, Google, Cerebras and any AI SDK provider
• 🔍 Semantic search - Vector-powered RAG with pgvector and automatic embedding generation
• ⚙️ Background workers - BullMQ-based job queues for long-running tasks
• 🔐 Authentication - API keys, NextAuth integration, and role-based access control
• 🛠️ Tool system - Extend agent capabilities with custom functions and external APIs
• 📦 Self-hosted - Deploy anywhere you want, no vendor lock-in
• 🔌 Express API - GraphQL and REST endpoints out of the box
• 📊 OpenTelemetry - Built-in logging and tracing with SigNoz integration
• ⚡ TypeScript-first - Fully typed with automatic type inference

🚀 Quickstart

Installation

npm install @exulu/backend

Basic setup

import { ExuluApp, ExuluAgent, ExuluDefaultAgents } from "@exulu/backend";

const app = new ExuluApp();

await app.create({
  config: {
    express: { enabled: true, port: 3000 },
    workers: { enabled: true },
    telemetry: { enabled: false }
  },
  agents: [
    ExuluDefaultAgents.anthropic.sonnet45,
    ExuluDefaultAgents.openai.gpt5
  ],
  contexts: {},
  tools: []
});

const server = await app.express.init();
server.listen(3000, () => {
  console.log("🚀 Exulu IMP running on http://localhost:3000");
});

For a complete working example, check out the Exulu Example Repository which includes:

• Docker Compose setup for PostgreSQL, Redis, and MinIO
• Pre-configured agents and contexts
• Worker implementation
• Environment configuration templates
• Database initialization scripts

🎨 Admin Frontend

Exulu Frontend →

Modern React admin interface for managing your AI agents, contexts, and workflows

The Exulu Frontend provides a beautiful, production-ready admin interface built with Next.js 15, React 19, and Tailwind CSS.

# Using npx (recommended)
npx @exulu/frontend

# Or install globally
npm install -g @exulu/frontend
exulu-frontend

Agent Management

Session Monitoring

📖 Documentation

Visit docs.exulu.com for comprehensive documentation including:

• Quickstart Guide - Get up and running in minutes
• Core Classes - Learn about ExuluApp, ExuluAgent, ExuluContext, and more
• API Reference - Complete API documentation
• Configuration - Detailed configuration options

🏗️ Core concepts

ExuluApp

The main application class that orchestrates all components:

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

const agent = new ExuluAgent({
  id: "assistant",
  name: "Assistant",
  provider: "anthropic",
  type: "agent",
  maxContextLength: 200000,
  config: {
    model: {
      create: ({ apiKey }) => {
        const anthropic = createAnthropic({ apiKey });
        return anthropic.languageModel("claude-sonnet-4-5");
      }
    },
    instructions: "You are a helpful assistant."
  }
});

const app = new ExuluApp();
await app.create({
  config: {},
  agents: [agent],
  contexts: {...},
  tools: [...]
});

ExuluAgent

Create AI agents with different LLM providers:

import { ExuluAgent } from "@exulu/backend";
import { createAnthropic } from "@ai-sdk/anthropic";

const agent = new ExuluAgent({
  id: "assistant",
  name: "Assistant",
  provider: "anthropic",
  type: "agent",
  capabilities: {
    text: true,
    images: [".png", ".jpg"],
    files: [".pdf", ".docx"]
  },
  maxContextLength: 200000,
  config: {
    model: {
      create: ({ apiKey }) => {
        const anthropic = createAnthropic({ apiKey });
        return anthropic.languageModel("claude-sonnet-4-5");
      }
    },
    instructions: "You are a helpful assistant."
  }
});

Or use pre-configured agents:

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

// OpenAI
ExuluDefaultAgents.openai.gpt5;
ExuluDefaultAgents.openai.gpt4o;

// Anthropic
ExuluDefaultAgents.anthropic.opus4;
ExuluDefaultAgents.anthropic.sonnet45;

// Google
ExuluDefaultAgents.google.vertexGemini25Pro;

// Cerebras
ExuluDefaultAgents.cerebras.llama3370b;

ExuluContext

Semantic search with vector embeddings for RAG:

import { ExuluContext, ExuluEmbedder } from "@exulu/backend";

const embedder = new ExuluEmbedder({
  id: "embedder",
  name: "OpenAI Embedder",
  provider: "openai",
  model: "text-embedding-3-small",
  vectorDimensions: 1536,
  authenticationInformation: process.env.OPENAI_API_KEY
});

const context = new ExuluContext({
  id: "docs",
  name: "Documentation",
  description: "Product documentation",
  embedder,
  tableName: "docs_items",
  fields: [
    { name: "title", type: "string" },
    { name: "url", type: "string" }
  ]
});

// Add documents
await context.addItem({
  content: "Product documentation content...",
  metadata: { title: "Getting Started", url: "https://docs.example.com/start" }
});

// Search (automatically available to agents)
const results = await context.search("How do I get started?", 5);

ExuluTool

Extend agent capabilities with custom functions:

import { ExuluTool } from "@exulu/backend";
import { z } from "zod";

const weatherTool = new ExuluTool({
  id: "get_weather",
  name: "Get Weather",
  description: "Get current weather for a location",
  parameters: z.object({
    location: z.string().describe("City name")
  }),
  execute: async ({ location }) => {
    const response = await fetch(`https://api.weather.com/${location}`);
    return await response.json();
  }
});

ExuluDatabase

Initialize database and generate API keys:

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

// Initialize database with contexts
await ExuluDatabase.init({ contexts: [documentationContext] });

// Generate API key
const { key } = await ExuluDatabase.api.key.generate(
  "Production API",
  "[email protected]"
);
console.log(`API Key: ${key}`);

Background workers

Process long-running tasks with BullMQ:

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

const app = new ExuluApp();
await app.create({
  config: {
    workers: { enabled: true }
  },
  // ... agents, contexts, tools
});

// Create worker to process jobs
const worker = await app.bullmq.workers.create();

// Worker automatically processes:
// - Embedding generation
// - Document chunking
// - Scheduled tasks
// - Custom queued jobs

⚙️ Requirements

• Node.js: 22.18.0 (enforced via engines in package.json)
• PostgreSQL: 13+ with pgvector extension
• Redis: Optional, only required if using background workers

🗂️ Exulu IMP ecosystem

The Exulu IMP platform consists of multiple repositories working together:

Backend structure

@exulu/backend/
├── src/
│   ├── exulu/
│   │   ├── app/           # ExuluApp implementation
│   │   ├── agent.ts       # ExuluAgent class
│   │   ├── context.ts     # ExuluContext class
│   │   ├── tool.ts        # ExuluTool class
│   │   ├── evals.ts       # ExuluEval class
│   │   └── otel.ts        # OpenTelemetry setup
│   ├── auth/              # Authentication utilities
│   ├── bullmq/            # Queue management
│   ├── chunking/          # Text chunking
│   ├── postgres/          # Database client
│   ├── redis/             # Redis client
│   └── templates/         # Default agents
├── types/                 # TypeScript type definitions
└── mintlify-docs/        # Documentation source

🔐 Authentication

Exulu IMP supports multiple authentication methods:

API Key authentication

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

const { db } = await postgresClient();
const result = await ExuluAuthentication.authenticate({
  apikey: "sk_abc123.../production-api-key",
  db
});

if (!result.error) {
  console.log(`Authenticated as: ${result.user?.email}`);
}

NextAuth session tokens

import { getToken } from "next-auth/jwt";

const token = await getToken({ req });
const result = await ExuluAuthentication.authenticate({
  authtoken: token,
  db
});

Internal service keys

const result = await ExuluAuthentication.authenticate({
  internalkey: process.env.INTERNAL_SECRET,
  db
});

📊 Evaluation framework

Test and measure agent performance:

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

const evaluation = new ExuluEval({
  id: "accuracy",
  name: "Response Accuracy",
  description: "Measures response accuracy",
  llm: false,
  execute: async ({ messages, testCase }) => {
    const response = messages[messages.length - 1]?.content || "";
    return response === testCase.expected_output ? 100 : 0;
  }
});

const score = await evaluation.run(agent, backend, testCase, messages);
console.log(`Score: ${score}/100`);

🔬 OpenTelemetry integration

Monitor your application with distributed tracing and logging:

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

const otel = ExuluOtel.create({
  SIGNOZ_TRACES_URL: process.env.SIGNOZ_TRACES_URL!,
  SIGNOZ_LOGS_URL: process.env.SIGNOZ_LOGS_URL!,
  SIGNOZ_ACCESS_TOKEN: process.env.SIGNOZ_ACCESS_TOKEN!
});

otel.start();

// Enable in ExuluApp
await app.create({
  config: {
    telemetry: { enabled: true },
    workers: {
      telemetry: { enabled: true },
      enabled: true
    }
  }
});

🌍 Environment variables

Create a .env file with:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/exulu

# NextAuth
NEXTAUTH_SECRET=your-secret-key

# Redis (optional, for workers)
REDIS_HOST=localhost
REDIS_PORT=6379

# S3 Storage (optional, for file uploads)
COMPANION_S3_REGION=us-east-1
COMPANION_S3_KEY=your-key
COMPANION_S3_SECRET=your-secret
COMPANION_S3_BUCKET=exulu-uploads
COMPANION_S3_ENDPOINT=https://s3.amazonaws.com

# OpenTelemetry (optional)
SIGNOZ_TRACES_URL=http://localhost:4318/v1/traces
SIGNOZ_LOGS_URL=http://localhost:4318/v1/logs
SIGNOZ_ACCESS_TOKEN=your-token

📦 Complete example

For a production-ready implementation, see the Exulu Example Repository:

git clone https://github.com/Qventu/exulu-example.git
cd exulu-example
npm install
docker compose up -d
npm run utils:initdb
npm run dev:server

The example includes:

• ✅ Docker Compose for all services
• ✅ Database initialization
• ✅ Pre-configured agents
• ✅ Context examples
• ✅ Custom tools
• ✅ Worker implementation
• ✅ Environment templates

Add the admin frontend:

# In a new terminal window
npx @exulu/frontend

Visit http://localhost:3001 to access the admin interface. See the Exulu Frontend repository for more details.

Audit logging

Enable an auditable, S3-backed trail of tool calls (which agent called which tool, on whose behalf, using which credential identity, with what payload). Off by default. Configure via ExuluApp.create({ config }):

await app.create({
  tools,
  config: {
    // ...existing config...
    audit: {
      enabled: true,
      retentionDays: 90,            // S3 lifecycle expiry
      // Optional: a dedicated, isolated bucket. Omit to reuse `fileUploads`.
      s3: {
        s3region: process.env.AUDIT_S3_REGION!,
        s3key: process.env.AUDIT_S3_KEY!,
        s3secret: process.env.AUDIT_S3_SECRET!,
        s3Bucket: process.env.AUDIT_S3_BUCKET!,
        s3prefix: "audit/",
      },
      // failureMode: "open" (default) | "closed"
      // sources: { toolCalls: { exclude: ["noisy_tool"] } },
    },
  },
});

Records are written as newline-delimited JSON under audit/dt=2026-07-28/14/1753970400000-3f8c2a1b.ndjson. Secret material is never logged — only credential identity (provider, account, authType, non-secret scopes/expiry). When reusing the shared fileUploads bucket, the S3 lifecycle rule is not applied automatically (to avoid touching a bucket that also holds user files); the exact rule to apply is logged at startup. Set manageLifecycle: true to apply it anyway.

🛠️ Development

# Install dependencies
npm install

# Build package
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run type-check

📚 Examples

RAG application

const context = new ExuluContext({
  id: "knowledge",
  name: "Knowledge Base",
  description: "Company knowledge base",
  embedder,
  tableName: "knowledge_items"
});

const agent = new ExuluAgent({
  id: "rag-agent",
  name: "RAG Assistant",
  provider: "anthropic",
  config: {
    instructions: "Answer questions using the knowledge base.",
    model: { create: ({ apiKey }) => anthropic("claude-sonnet-4-5", apiKey) }
  }
});

await app.create({
  agents: [agent],
  contexts: { knowledge: context }
});

// Agent automatically searches context when answering

Multi-agent workflow

const researchAgent = new ExuluAgent({
  id: "researcher",
  name: "Research Agent",
  provider: "openai",
  config: { /* ... */ }
});

const writerAgent = new ExuluAgent({
  id: "writer",
  name: "Writer Agent",
  provider: "anthropic",
  config: { /* ... */ }
});

await app.create({
  agents: [researchAgent, writerAgent],
  contexts: {},
  tools: [webSearchTool, documentTool]
});

Custom tool with API integration

const slackTool = new ExuluTool({
  id: "send_slack_message",
  name: "Send Slack Message",
  description: "Send a message to a Slack channel",
  parameters: z.object({
    channel: z.string(),
    message: z.string()
  }),
  execute: async ({ channel, message }) => {
    const response = await fetch("https://slack.com/api/chat.postMessage", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.SLACK_TOKEN}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ channel, text: message })
    });
    return await response.json();
  }
});

🚨 Need help?

• 📖 Documentation - Comprehensive guides and API reference
• 💬 Discord - Join our community
• 🐛 GitHub Issues - Report bugs
• 💡 GitHub Discussions - Ask questions

🗺️ Roadmap

Check out our Roadmap Discussion to see what we're working on and suggest features.

📄 License

This project is licensed under a commercial license. See exulu.com for licensing information.

The Exulu Example Project is open source under the MIT License.

🌟 Related projects

Exulu Frontend → Modern admin interface built with Next.js 15 Manage agents, contexts, and workflows visually

Exulu Example → Complete implementation example Docker setup with all services configured

⭐ Star us on GitHub

If you find Exulu IMP useful, give us a star! It helps others discover the project.

👏 Thanks to all our contributors