Configuring EventAI¶

This guide explains how to configure EventAI, an AI-powered assistant that helps you generate EventQL queries from natural language prompts directly in the Management UI.

What is EventAI?¶

EventAI is an optional feature that integrates large language models into EventSourcingDB's Management UI. It allows you to generate EventQL queries by describing what you want in natural language, automatically fix invalid queries, and interactively refine queries through a conversational interface.

EventAI is particularly useful for exploring data, debugging, and prototyping queries without having to know the full EventQL syntax. It is disabled by default and becomes available only when explicitly configured.

Prerequisites¶

Before you can use EventAI, you need an OpenAI account with API access and an OpenAI API token. The OpenAI API is a paid service, and each query you generate will incur costs according to OpenAI's pricing model. Make sure to monitor your usage and set appropriate billing limits in your OpenAI account.

For current pricing information, visit OpenAI's pricing page.

Cost Awareness

EventAI uses the OpenAI API, which is billed based on the number of requests and tokens processed. Costs can accumulate quickly if used frequently. Review OpenAI's pricing before enabling this feature in production environments.

Currently, EventAI supports GPT-4o from OpenAI. The model identifier for configuration purposes is openai-gpt-4o. Additional models may be supported in future versions.

Obtaining an OpenAI API Token¶

To use EventAI, you need an API token from OpenAI. Visit platform.openai.com, sign in or create an account, and navigate to the API keys section. Create a new API key, copy it, and store it securely.

Keep Your Token Secret

The API token grants access to your OpenAI account and will be billed for usage. Never commit it to version control or share it publicly. Treat it like a password.

Configuration¶

EventAI requires two CLI flags to be configured when starting EventSourcingDB. Use --ai-model to specify which AI model to use, and --ai-option to provide model-specific configuration options in key=value format.

For OpenAI models, you must provide the token option with your OpenAI API token. Both flags are required – EventAI only becomes available if both are explicitly configured.

Example¶

Here's a complete example of how to start EventSourcingDB with EventAI enabled:

./eventsourcingdb run \
  --api-token <API_TOKEN> \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false \
  --with-ui \
  --ai-model openai-gpt-4o \
  --ai-option token=<OPENAI_API_TOKEN>

Replace <OPENAI_API_TOKEN> with your actual OpenAI API token.

Security Considerations¶

Instead of passing the token directly on the command line, consider using environment variables or a secrets management system. This prevents the token from appearing in shell history or process listings.

Storing Tokens Securely¶

You can reference environment variables directly in the command:

export OPENAI_API_TOKEN="your-token-here"

./eventsourcingdb run \
  --api-token <API_TOKEN> \
  --data-directory-temporary \
  --http-enabled \
  --https-enabled=false \
  --with-ui \
  --ai-model openai-gpt-4o \
  --ai-option token=$OPENAI_API_TOKEN

For production deployments, refer to Managing Configuration and Secrets for best practices on handling sensitive information securely across different deployment environments.

The Management UI, and therefore EventAI, is protected by the same API token used for the database. Anyone with access to the UI can use EventAI and generate queries.

Privacy and Data Protection¶

When using EventAI, it's important to understand what data is sent to external services. EventAI sends event schemas, your natural language prompts, and conversation history to OpenAI's API. Event schemas include event types and their structure, which are metadata about your events.

Actual event data – the contents of your events – is never transmitted to OpenAI. Only schema information is sent, not the data itself. However, if your event schemas contain sensitive information, such as field names that reveal business logic, you should consider whether this is compliant with your data protection requirements.

GDPR and Compliance

Event schemas and metadata are sent to OpenAI's servers, which are located outside the EU. Review OpenAI's data usage policies to understand how your data is handled and ensure this aligns with your compliance requirements.

Using EventAI in the Management UI¶

Once EventAI is configured, it appears as a panel in the EventQL Query Editor within the Management UI. Type a natural language description of what you want to query, and EventAI generates an EventQL query based on your prompt and the registered event schemas. The query is automatically inserted into the editor, where you can review and execute it.

EventAI maintains a conversation history during your session, allowing you to refine queries iteratively. For example, you can ask EventAI to limit results, add filters, or modify the sort order based on a previous query. EventAI also validates generated queries and attempts to fix errors automatically.

Example Prompts¶

EventAI works best with clear, specific prompts. The following examples are based on the library domain used throughout the documentation and demonstrate the kinds of queries you can generate.

For simple queries, you might ask EventAI to "Show me all events for book 42" or "List the 10 most recent book acquisitions". You can also filter events by type, such as "Find all events where books were borrowed".

When working with specific data, try prompts like "Show me all books borrowed by reader 23" or "Find all books by Arthur C. Clarke that were acquired". You can also search by specific fields, for example "Find all books with ISBN starting with 978-0756".

For aggregation queries, ask EventAI to "Count how many books were acquired in total" or "Count events by type and show me the distribution". You can also query for specific subjects, such as "List all readers who have been accepted".

Time-based queries work well with prompts like "List all events from the last 7 days" or "Show me books borrowed after November 1st, 2025".

For more complex scenarios, you might ask "Find all books that are currently borrowed (borrowed but not returned)" or "Show me events for all books, including their pages". These demonstrate how EventAI can handle more sophisticated query logic.

Best Practices¶

EventAI works best when your event schemas are registered in EventSourcingDB. This allows the AI to understand your domain model and generate more accurate queries. For details, see Registering Event Schemas.

The more specific your prompt, the better the result. Instead of asking for "some events", specify what you want, such as "Show me all book-acquired events from the last 30 days". Always review the generated EventQL query before executing it, especially if it involves large datasets, complex aggregations, or production data.

OpenAI enforces rate limits on API requests. If you encounter errors related to rate limiting, consider reducing the frequency of queries, upgrading your OpenAI plan, or implementing caching for common queries.

Troubleshooting¶

If the EventAI panel does not appear in the Management UI, ensure both --ai-model and --ai-option flags are set when starting the server. Also verify that --with-ui is specified to enable the Management UI. If the issue persists, clear your browser cache and reload the page.

If you see error messages like "unauthorized" or "invalid API key" when using EventAI, check that --ai-option token=<OPENAI_API_TOKEN> is correctly set. Verify the token is copied correctly from OpenAI and has not expired or been revoked. Ensure the token has access to the chat completions API.

EventAI calculates a confidence score for each prompt. If the score is below 0.5, it means your prompt likely cannot be answered with the available event schemas. This can happen if your prompt does not match your domain, no event schemas are registered, or the prompt is too ambiguous. For example, asking "Show me all orders" when your domain uses "books" will fail. Instead, ask "Show me all book acquisitions".

If EventAI returns an error saying it could not generate a valid query, try simplifying your request. Some SQL-like features may not be available in EventQL. Ensure your event schemas accurately reflect your events.

Network or API errors, such as "Connection failed" or "timeout" errors, can occur if OpenAI's service is unavailable. Check OpenAI's status page to see if there is an outage. Verify that EventSourcingDB can reach api.openai.com and that HTTPS connections to OpenAI are allowed by your firewall or proxy. You may also have exceeded OpenAI's rate limits – check the error message details for more information.

To diagnose EventAI issues, check the EventSourcingDB logs. The server logs all AI-related errors, including API communication failures, token validation errors, and query generation attempts. For general debugging guidance, see Diagnostics and Troubleshooting.

Cost Management¶

Since OpenAI API usage is billed per request and token, it's important to monitor usage regularly. Check your OpenAI account dashboard to track spending, and configure spending limits in your OpenAI account to avoid unexpected charges.

Use EventAI selectively – reserve it for exploration and debugging, not routine queries. If you do not need EventAI, simply omit the CLI flags to keep it disabled.

Summary¶

EventAI is a powerful tool for generating EventQL queries from natural language, but it requires external API access, proper token management, awareness of data privacy implications, and cost monitoring. For most development and debugging scenarios, EventAI can significantly speed up your workflow and reduce the learning curve for EventQL.