> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erlc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Blocks: Ask AI and Handle Responses in erlc.dev Studio

> Use the Ask AI block to send prompts to an on-device language model and handle responses asynchronously in your erlc.dev Studio automations.

The AI blocks in erlc.dev Studio let you integrate a local language model directly into your automations. You can send a prompt in response to any event — a Discord message, a player joining, or a custom command — and then handle the generated response in a dedicated trigger block once the model finishes. This opens the door to dynamic, natural-language interactions without relying on external APIs or cloud services.

***

## Available Model

All AI blocks currently use the `qwen2.5:1.5b` model, a compact on-device language model optimised for fast inference. Set the `MODEL` field on each AI block to `qwen2.5:1.5b`.

***

## AI Action Blocks

Use these blocks as actions inside any automation stack to initiate an inference request. They send the prompt to the model and return immediately — they do **not** wait for the response inline.

<CardGroup cols={2}>
  <Card title="erlc_ask_ai" icon="robot">
    Sends the text provided in the `PROMPT` input to the model specified in the `MODEL` field. Use this for straightforward prompts where the model's default behaviour is acceptable.
  </Card>

  <Card title="erlc_ask_ai_with_system" icon="sliders">
    Sends a prompt alongside a system message. Connect a text value to `PROMPT` for the user message and a separate text value to `SYSTEM_PROMPT` to set the model's context and persona. Set `MODEL` in the field.
  </Card>
</CardGroup>

<Note>
  AI generation is **asynchronous**. When `erlc_ask_ai` (or `erlc_ask_ai_with_system`) runs, it dispatches the prompt to the model and execution of the current stack continues immediately with the next block. The model response does **not** arrive inline — it fires a separate `erlc_when_ai_responds` event when generation completes.
</Note>

<Tip>
  Use `erlc_ask_ai_with_system` to constrain and shape the model's behaviour for your specific server context. For example, set `SYSTEM_PROMPT` to `"You are a helpful ERLC server assistant. Keep responses under two sentences and stay on topic."` to prevent off-topic or excessively long replies before they reach your players.
</Tip>

***

## AI Response Trigger

<CardGroup cols={1}>
  <Card title="erlc_when_ai_responds" icon="bolt">
    Fires when the model identified by the `MODEL` field finishes generating a response. Place action blocks inside this trigger to handle the generated text — for example, sending the response as a Discord message. Read the generated text from the event context using the `erlc_event_value` block.
  </Card>
</CardGroup>

***

## Use Cases

<CardGroup cols={2}>
  <Card title="Auto-reply to Discord Messages" icon="comment-dots">
    Trigger on `discord_message_create`, pipe the message content into `erlc_ask_ai`, then send the AI response back to the channel with `erlc_bot_send_message`.
  </Card>

  <Card title="Summarise Emergency Calls" icon="phone-volume">
    When an in-game call is logged, send the description to the AI and post the summary to a staff Discord channel.
  </Card>

  <Card title="Dynamic Announcements" icon="bullhorn">
    Feed current server state (player count, active incidents) into a prompt and let the AI draft a contextual announcement.
  </Card>

  <Card title="Message Moderation" icon="shield-halved">
    Send flagged player messages to the AI with a moderation-focused system prompt and take action based on the classification in the response.
  </Card>
</CardGroup>

***

## JSON Example — Discord Message → Ask AI → Send Response

This example shows three connected pieces:

1. A `erlc_when_discord_event` trigger listening for `discord_message_create`.
2. An `erlc_ask_ai` block that forwards the message content as a prompt.
3. A separate `erlc_when_ai_responds` trigger that sends the response back to Discord.

**Stack 1 — Send the prompt when a message arrives:**

```json theme={null}
{
  "type": "erlc_when_discord_event",
  "id": "block_trigger_1",
  "fields": {
    "EVENT": "discord_message_create"
  },
  "next": {
    "block": {
      "type": "erlc_ask_ai",
      "id": "block_ask_1",
      "fields": {
        "MODEL": "qwen2.5:1.5b"
      },
      "inputs": {
        "PROMPT": {
          "block": {
            "type": "erlc_discord_event_value",
            "id": "block_msg_content_1",
            "fields": {
              "FIELD": "content"
            }
          }
        }
      }
    }
  }
}
```

**Stack 2 — Handle the AI response and reply to the channel:**

```json theme={null}
{
  "type": "erlc_when_ai_responds",
  "id": "block_ai_trigger_1",
  "fields": {
    "MODEL": "qwen2.5:1.5b"
  },
  "next": {
    "block": {
      "type": "erlc_bot_send_message",
      "id": "block_send_1",
      "inputs": {
        "MESSAGE": {
          "block": {
            "type": "erlc_event_value",
            "id": "block_ai_response_1",
            "fields": {
              "FIELD": "response"
            }
          }
        }
      }
    }
  }
}
```

<Note>
  The two stacks above are **separate trigger blocks** on the canvas, not connected by a `next` chain. Stack 1 runs when a Discord message arrives and dispatches the AI request. Stack 2 runs independently when the model responds. This is the correct pattern for all AI-driven automations in erlc.dev Studio.
</Note>

***

## Tips for Better AI Output

<Accordion title="Keep prompts specific">
  The `qwen2.5:1.5b` model performs best with short, specific prompts. Avoid open-ended instructions. Instead of `"Help this player"`, write `"In one sentence, tell this ERLC player how to contact staff: " + [player message]`.
</Accordion>

<Accordion title="Use the system prompt to set a persona">
  With `erlc_ask_ai_with_system`, set a system prompt like `"You are a strict ERLC moderator assistant. Reply only about in-game rules."` to prevent the model from straying into unrelated topics.
</Accordion>

<Accordion title="Rate-limit AI requests">
  Wrap your `erlc_ask_ai` block inside an `erlc_throttle` block to prevent a flood of Discord messages from triggering dozens of simultaneous AI requests. Set a reasonable `SECONDS` window (e.g. `5`) and a unique `KEY`.
</Accordion>

<Accordion title="Sanitise AI output before posting">
  Pass the AI response through `erlc_discord_escape` before sending it to Discord to prevent any model-generated Markdown syntax from rendering unintentionally.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.