Skip to main content

Configuration

View as Markdown

EventCatalog Assistant is shown by default.

To use the assistant, you need to:

  1. Run EventCatalog with output: 'server' in your eventcatalog.config.js file
  2. Add an eventcatalog.chat.js file to your catalog
eventcatalog.config.js
module.exports = {
  // AI integrations require you to run EventCatalog as a server
  output: 'server'
};

You can hide the assistant by setting chat.enabled to false.

Disabling the feature​

EventCatalog Assistant is enabled by default. Set chat.enabled to false to hide the assistant UI and prevent chat requests:

eventcatalog.config.js
module.exports = {
  output: 'server',
  chat: {
    enabled: false,
  },
};

Installing your model and configuring eventcatalog.chat.js file​

First you have to install your model of choice (list of models) and configure the relevant secrets in your .env file.

Example of installing the OpenAI model:

<!-- in the root of your project -->
npm install @ai-sdk/openai
AI SDK version

From EventCatalog 4.12, the assistant uses AI SDK v7. Install a provider package that supports AI SDK v7, for example @ai-sdk/openai@^4. If you have custom tools that use AI SDK v6 APIs, update them to the v7 equivalents.

Configuring eventcatalog.chat.js​

This file will provide the model and any model configuration to EventCatalog.

In the example below we are using the OpenAI model gpt-4.1-nano and configuring the model with some additional parameters.

eventcatalog.chat.js
import { openai } from '@ai-sdk/openai';

// Export your model using the default export
export default async () => {
    return openai('gpt-4.1-nano');
}

// Export the configuration for the model (optional)
export const configuration = {
    topP: 0.9,
    topK: 40,
    frequencyPenalty: 0.0,
    presencePenalty: 0.0,
    temperature: 0.7,
    maxTokens: 10000,
}

Passing options to your provider​

Added in eventcatalog@5.7.1

Use configuration.providerOptions to pass settings that only your model provider understands. They're passed to the AI SDK's providerOptions, keyed by the provider's name.

For example, to set how much effort an Anthropic model puts into its answers:

eventcatalog.chat.js
import { anthropic } from '@ai-sdk/anthropic';

export default async () => {
    return anthropic('claude-haiku-5-5');
}

export const configuration = {
    providerOptions: {
        anthropic: { effort: 'medium' },
    },
}

Lower effort answers faster and costs less, which suits most drawing with Draw with AI. Raise it for harder questions. See your provider's page in the AI SDK docs for the options it accepts.

Once you have configured your model, restart EventCatalog and you can start asking questions about your architecture.

Troubleshooting​

eventcatalog.chat.js fails to load​

Added in eventcatalog@5.0.0

If your catalog has an eventcatalog.chat.js file but it fails to load (for example, a package it imports isn't installed), the assistant explains the problem instead of answering:

  • In eventcatalog dev, the assistant shows why the file didn't load and the steps to fix it: install the packages your eventcatalog.chat.js imports (for example npm install ai @ai-sdk/anthropic), add the provider's API key to your .env file, and restart EventCatalog.
  • Everywhere else, the reason is not shown to readers. The assistant tells them that the catalog owner can find the cause in the server logs, under Error loading chat configuration.