Bring your own prompts

Added in eventcatalog@2.35.7

info

Bring your own prompts is only available for OpenAI models.

EventCatalog allows you to bring your own prompts to EventCatalog Chat.

These are pre-defined prompts that you can use to customize the behavior of EventCatalog Chat for your organization and teams.

These can be great to give your model system prompts for each predefined example. In the example below we have examples prompts:

• "Generate a JSON schema Following FlowwMart Standards" (see example)
• "Create a Kafka producer code for event" (see example)
• "Create Kafka consumer code for event" (see example)
• "Create AWS Lambda function to Consume EventBridge Event" (see example)

Bringing your own prompts, let's you tailor your model to your organization and teams, you can include custom context, best practices and more.

Adding custom prompts

To add custom prompts you need to create a new directory called chat-prompts in your catalog directory.

Then you need to add your custom prompts to this folder. You can have as many nested folders as you want.

Here is an example of a nested folder structure:

EventCatalog Chat Prompts

chat-prompts/
  code/
    create-an-example-schema.mdx
    create-producer-code-for-event.mdx
    create-consumer-code-for-event.mdx
    create-consumer-code-for-eventbridge-event.mdx
  learning/
    best-practices-for-flowwmart.mdx
    how-to-use-event-driven-architecture.mdx
  security/
    how-to-secure-your-event-driven-architecture.mdx

Custom prompt example

Each prompt file should contain frontmatter and markdown:

• frontmatter:
  • title: The title of the prompt should on the UI
  • category: The category of the prompt, this will be used to group the prompt in the UI
  • icon: The icon of the prompt, this will be used to display the icon of the prompt in the UI
• markdown: The markdown content of the prompt, this will be given to the model to generate the response. Add your best practices, context, and more.

Here is an example of a prompt file 'understanding-best-practices-for-flowwmart.mdx', in this file we define best practices for our organization, and users can use this prompt to get more information about the best practices.

understanding-best-practices-for-flowwmart.mdx

---
# The title of the prompt should on the UI
title: Understanding best practices for FlowwMart
# The category of the prompt, this will be used to group the prompt in the UI
category:
  id: Learning
  label: Learning
  icon: GraduationCap
---

At FlowMart, we adhere to several best practices to ensure our Event-Driven Architecture (EDA) is robust, scalable, and maintainable. Here are the key guidelines:

### Event Naming and Structure

*   **Past Tense Naming:** All event names MUST be in the past tense (e.g., `OrderCreated`, `UserLoggedIn`, `PaymentProcessed`). This reflects that an event represents something that has already occurred.
*   **Correlation IDs:** Every event MUST include a `correlationId`. This allows us to track related events across different services and flows, which is crucial for debugging and observability.
*   **Clear Event Payloads:** Event payloads should be well-defined, documented, and contain only the necessary information relevant to the event itself. Avoid overly large or generic payloads.

### Contract Management and Ownership

*   **Producer Ownership:** The service that produces an event owns its contract (schema). Consumers should rely on this defined contract.
*   **Public vs. Private Events:** Events MUST be explicitly marked as either `public` or `private`.
    *   `Public` events have strong backward compatibility guarantees.
    *   `Private` events are typically for internal service use and may have less stringent compatibility requirements, but changes should still be coordinated.
*   **No Breaking Changes (Public Events):** We strive to avoid breaking changes in `public` event contracts. If a change is necessary, it must be additive or managed through versioning.
*   **Semantic Versioning (SemVer):** Event schemas SHOULD follow Semantic Versioning (e.g., `1.0.0`, `1.1.0`, `2.0.0`).
    *   MAJOR version bumps indicate breaking changes (avoided for public events).
    *   MINOR version bumps indicate backward-compatible additions.
    *   PATCH version bumps indicate backward-compatible fixes.

### Design Principles

*   **Idempotent Consumers:** Consumers should be designed to be idempotent, meaning they can safely process the same event multiple times without unintended side effects. This handles scenarios like message replays or network issues.
*   **Asynchronous Communication:** Favor asynchronous communication patterns. Events decouple services, allowing them to operate independently.
*   **Domain-Driven Design (DDD):** Align events with bounded contexts and domain concepts from DDD. This helps create meaningful, cohesive events.
*   **Schema Registry:** Utilize a schema registry (like the one provided by EventCatalog!) to manage, validate, and evolve event schemas centrally.

### Documentation and Discovery

*   **EventCatalog:** All events, schemas, producers, and consumers MUST be documented in our EventCatalog. This serves as the single source of truth for our EDA landscape.
*   **Clear Descriptions:** Provide clear, concise descriptions for each event, explaining its purpose and context.

By following these practices, we aim to build a resilient and understandable event-driven ecosystem at FlowMart.

Capturing input from the user

Some of your prompts might need to capture input from the user. You can do this by adding inputs to the frontmatter of the prompt.

In the example below we capture the event name from the user and use this in the prompt (using {{event-name}}). We tell the model to use the users input to generate the JSON schema following FlowMart's payload standards.

When clicking on the prompt, the user will be asked to input the event name.

When the user clicks on the prompt, the prompt will be generated with the users input.

See the prompt file for single input

create-json-schema-for-event.mdx

   ---
title: Generate a JSON Schema Following FlowMart Standards
category:
id: Code
label: Code
icon: Code
inputs:
- id: event-name
  label: What is the name of the event?
  type: text
---

Generate a JSON schema for an event called `{{event-name}}`. This schema must follow FlowMart's payload standards.

**FlowMart Payload Standards:**

*   Every payload MUST include a top-level `metadata` field.
*   The `metadata` field MUST contain:
  *   `correlationId`: A string, preferably in UUID format.
  *   `createdDate`: A string in ISO 8601 format (e.g., "2023-11-02T14:29:55Z").
*   The main event details should be within a top-level `data` field.

**Example `UserSignedUp` Event Payload:**

```json
{
"metadata": {
   "correlationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
   "createdDate": "2023-11-02T14:29:55Z"
},
"data": {
  "userId": "user-789",
  "email": "test@example.com",
  "signUpMethod": "Google"
}
}
``

**Invalid Example (Missing `metadata`):**
```json
{
"data": {
  "userId": "user-123",
  "email": "invalid@example.com"
}
}
``

**Invalid Example (Missing `correlationId` in `metadata`):**
```json
{
"metadata": {
   "createdDate": "2023-11-01T10:00:00Z"
},
"data": {
   "userId": "user-456",
   "email": "incomplete@example.com"
}
}
``

**Task:**

Create the JSON schema definition for the `UserSignedUp` event described above, ensuring it enforces the FlowMart payload standards.

Capturing multiple inputs

You can capture multiple inputs from the user.

In this example we capture the event (from a list of events from EventCatalog) and the programming language (from a list of programming languages).

See the prompt file for multiple inputs

---
title: Create Kafka Producer Code for Event
category:
  id: Code
  label: Code
  icon: Code
inputs:
  - id: event-name
    label: Select the event you want to create a producer for
    type: resource-list-events
  - id: code-language
    label: What is the programming language of the code?
    type: select
    options:
      - Python
      - Java
      - TypeScript
      - Go
      - Ruby
---

Generate Kafka producer code in `{{code-language}}` that produces the event `{{event-name}}`.

**Kafka Cluster Details:**

*   **Bootstrap Servers:** `kafka-prod-1.flowmart.internal:9092,kafka-prod-2.flowmart.internal:9092,kafka-prod-3.flowmart.internal:9092`
*   **Topic Name:** The topic name follows the pattern `fm.events.<event-name>` (e.g., `fm.events.UserSignedUp` for the `UserSignedUp` event).
*   **Security Protocol:** SASL_SSL
*   **SASL Mechanism:** PLAIN
*   **Required Acknowledgements (acks):** `all` (Ensure highest durability).

**Best Practices to Follow:**

1.  **Serialization:** Assume the event payload needs to be serialized to JSON and follow FlowMart's payload standards (with `metadata` and `data` fields). The `metadata` should include a unique `eventId` (UUID) and `timestamp` (ISO 8601).
2.  **Error Handling:** Implement robust error handling for connection issues, serialization failures, and send failures. Consider retry mechanisms with backoff for transient errors.
3.  **Configuration:** Externalize Kafka connection details (don't hardcode them directly in the main logic).
4.  **Logging:** Add basic logging for successful message production and any errors encountered.
5.  **Asynchronous Sending:** Use asynchronous send calls for better performance, but ensure proper handling of send callbacks/futures for error checking and logging.
6.  **Partitioning:** Briefly mention how to set a message key (e.g., using `metadata.correlationId` or a relevant business ID) if specific partitioning is desired for ordering guarantees within a partition.

**Task:**

Provide the complete, runnable Kafka producer code snippet in `{{code-language}}` for the `{{event-name}}` event, incorporating the cluster details and best practices mentioned above. Include necessary imports, basic setup, and an example of how to construct and send an event message.

If you use any external libraries, please include the import statements and how to install them, step by step, make sure dependencies are listed first.

Types of inputs

• text
  • Renders a text input field.
• textarea
  • Renders a text area input field.
• code
  • Renders a code input field.
• select
  • Renders a select input field.
• resource-list-events
  • Renders a list of events users can choose from. These are events defined in the EventCatalog.
• resource-list-services
  • Renders a list of services users can choose from. These are services defined in the EventCatalog.
• resource-list-commands
  • Renders a list of commands users can choose from. These are commands defined in the EventCatalog.
• resource-list-queries
  • Renders a list of queries users can choose from. These are queries defined in the EventCatalog .

Examples

You can find an example of a prompt that captures multiple inputs on our Demo Catalog GitHub repository.